@joktec/mysql 0.2.13 → 0.2.14

package/README.md

@@ -1,118 +1,248 @@
-<div align="center">
-  <h1>@joktec/mysql</h1>
-  <p>A NestJS library that provides a wrapper around the `sequelize` and `sequelize-typescript` libraries for MySQL databases.</p>
-</div>
+# @joktec/mysql
 
-## Table of Contents
-1. [Introduction](#introduction)
-2. [Installation](#installation)
-3. [Getting Started](#getting-started)
-4. [Reference](#reference)
-5. [Contributing](#contributing)
+Relational TypeORM database package for JokTec applications.
 
-## Introduction
-This library provides an easy-to-use interface for working with MySQL databases in NestJS applications. It is built on top of the popular `sequelize` and `sequelize-typescript` libraries, and provides a set of convenient abstractions for working with these libraries.
+`@joktec/mysql` wraps TypeORM with JokTec config, lifecycle, entity registration, base repositories, naming strategy support, and shared CRUD pagination contracts from `@joktec/core`. The package name remains `mysql`, but the first-class relational targets are MySQL, MariaDB, and Postgres.
 
-## Installation
-To install this library, use either `npm` or `yarn`:
+## Install
 
 ```bash
-npm install @joktec/mysql
-# or
 yarn add @joktec/mysql
 ```
 
-## Getting Started
-### Configuration
-To use this library, you must first provide the necessary configuration. This can be done by creating a config.yml file in your application's root directory, with the following content:
-```yaml
-mysql:
-  host: localhost
-  port: 3306
-  user: my_user
-  password: my_pass
-  database: my_database
-```
-Replace the values with your actual database connection information.
-
-### Module
-Once you have provided the configuration, you can create a MysqlModule in your NestJS application:
-```typescript
-import { CoreModule, Module } from '@joktec/core';
+## Public Surface
+
+- module and service:
+  - `MysqlModule`
+  - `MysqlService`
+  - `MysqlRepo`
+- config and client:
+  - `MysqlConfig`
+  - `MysqlClient`
+  - `Dialect`
+  - `MysqlLogLevel`
+  - relational dialect capabilities
+- model contracts:
+  - `MysqlModel`
+  - `IMysqlRequest`
+  - `IMysqlResponse`
+- decorators and helpers:
+  - `@Tables`
+  - `@Column`
+  - `@PrimaryColumn`
+  - `MysqlHelper`
+  - `MysqlFinder`
+  - `MysqlNamingStrategy`
+- selected TypeORM exports.
+
+## Module Registration
+
+Register application entities through `MysqlModule.forRoot(...)`:
+
+```ts
+import { Module } from '@joktec/core';
 import { MysqlModule } from '@joktec/mysql';
+import { ProfileBadge } from './entities/profile-badge.entity';
 
 @Module({
-  imports: [CoreModule, MysqlModule],
+  imports: [
+    MysqlModule.forRoot({
+      conId: 'default',
+      models: [ProfileBadge],
+    }),
+  ],
 })
-export class AppModule {}
+export class RepositoryModule {}
 ```
 
-### Service
-You can then use the MysqlService to interact with the database:
-```typescript
+Use `conId` when the application config contains multiple SQL connections. Repositories resolve the TypeORM repository through the same `conId`, including transaction-scoped managers when passed through repository options.
+
+## Repository Usage
+
+Extend `MysqlRepo` for each application entity:
+
+```ts
 import { Injectable } from '@joktec/core';
-import { MysqlService } from '@joktec/mysql';
+import { MysqlRepo, MysqlService } from '@joktec/mysql';
+import { ProfileBadge } from '../entities/profile-badge.entity';
 
 @Injectable()
-export class UserService {
-  constructor(private readonly mysqlService: MysqlService) {}
+export class ProfileBadgeRepo extends MysqlRepo<ProfileBadge, string> {
+  constructor(mysqlService: MysqlService) {
+    super(mysqlService, ProfileBadge);
+  }
+}
+```
+
+Services can then use the shared `BaseService` contract:
+
+```ts
+import { BaseService, Injectable } from '@joktec/core';
+import { IMysqlRequest } from '@joktec/mysql';
+import { ProfileBadge } from '../entities/profile-badge.entity';
+import { ProfileBadgeRepo } from '../repositories/profile-badge.repo';
 
-  async getUsers() {
-    const users = await this.mysqlService.getModel(User).findAll();
-    return users;
+@Injectable()
+export class ProfileBadgeService extends BaseService<ProfileBadge, string, IMysqlRequest<ProfileBadge>> {
+  constructor(protected profileBadgeRepo: ProfileBadgeRepo) {
+    super(profileBadgeRepo);
   }
 }
 ```
 
-### Repository
-#### Define a Model
-You can define a model using `@joktec/mysql` (based on interface of `sequelize-typescript`):
-```typescript
-import { Table, Column, Model } from '@joktec/mysql';
+## Config Shape
+
+The application config reads the `mysql` section and maps it to `MysqlConfig`.
+
+Common fields:
+
+```yaml
+mysql:
+  conId: default
+  dialect: mysql
+  host: localhost
+  port: 3306
+  username: example_user
+  password: example_password
+  database: example_db
+  charset: utf8mb4
+  timezone: Z
+  connectTimeout: 20000
+  sync: false
+  benchmark:
+    enable: false
+    all: false
+    level: [error, warn]
+```
+
+Supported `dialect` values are `mysql`, `mariadb`, and `postgres`. Other TypeORM drivers are not treated as stable package targets until they have package-level contract tests.
+
+`slaves` can be configured for TypeORM replication. Slave entries inherit missing host, port, username, password, and database values from the master config.
 
-@Table
-export class User extends Model<User> {
-  @Column
-  name: string;
+`sync` is disabled by default. For multi-process deployments, enable `sync` only in one controlled owner process, such as a local example app, migration owner, or development-only bootstrap.
 
-  @Column
-  email: string;
+## Query Contract
+
+`IMysqlRequest<T>` extends `IBaseRequest<T>` and adds SQL-specific flags:
+
+```ts
+{
+  select?: string | Array<keyof T>;
+  keyword?: string;
+  condition?: ICondition<T>;
+  page?: number;
+  offset?: number;
+  cursor?: string;
+  cursorKey?: keyof T | Array<keyof T> | string;
+  limit?: number;
+  sort?: ISort<T>;
+  populate?: IPopulate<T>;
+  withDeleted?: boolean;
 }
 ```
 
-#### Define a Repository
-You can create a repository for your model by extending the MysqlRepository class and providing the model type as a generic argument:
-```typescript
-import { Injectable } from '@nestjs/common';
-import { MysqlRepository } from '@joktec/mysql';
-import { User } from './user.model';
+Supported repository operations include `paginate`, `find`, `count`, `findOne`, `create`, `update`, `delete`, `restore`, `upsert`, and `bulkUpsert`.
 
-@Injectable()
-export class UserRepository extends MysqlRepository<User> {}
+Repository reads use QueryBuilder so condition, projection, sorting, relation population, and cursor pagination share the same field validation path. Request field names are validated against TypeORM metadata before they are interpolated into SQL identifiers.
+
+## Pagination
+
+`MysqlRepo.paginate` supports page, offset, and cursor pagination through the shared `@joktec/core` response contracts.
+
+Runtime priority:
+
+1. cursor when `cursor` or `cursorKey` exists
+2. offset when `offset` exists
+3. page as the default fallback
+
+Cursor pagination behavior:
+
+- default cursor keys: `createdAt` plus entity primary key columns
+- custom `cursorKey`: supported
+- primary keys are appended as tie-breakers
+- cursor keys are validated against TypeORM column metadata
+- cursor conditions are built as lexicographic SQL `OR` clauses
+- fetches `limit + 1` rows to compute `hasNextPage`
+- returns `nextCursor` as an opaque token
+
+Example first cursor request:
+
+```ts
+const firstPage = await profileBadgeRepo.paginate({
+  cursorKey: 'createdAt',
+  limit: 20,
+  sort: { createdAt: 'desc' },
+});
 ```
-#### Using Repository in Service
-You can then use the repository in your service:
-```typescript
-import { Injectable } from '@nestjs/common';
-import { UserRepository } from './user.repository';
 
-@Injectable()
-export class UserService {
-  constructor(private readonly userRepository: UserRepository) {}
+Example next cursor request:
 
-  async getUsers() {
-    const users = await this.userRepository.findAll();
-    return users;
-  }
+```ts
+const nextPage = await profileBadgeRepo.paginate({
+  cursor: firstPage.nextCursor,
+  limit: 20,
+});
+```
+
+For stable cursor pagination, prefer cursor keys backed by indexed columns. The default assumes entities have `createdAt` and primary key columns available through the shared model pattern.
+
+## Entity Notes
+
+Keep entity definitions in the consuming app or package. Keep app-specific query behavior inside app repositories or services, not inside `@joktec/mysql`.
+
+`@joktec/mysql` exposes schema-first decorators that wrap TypeORM metadata together with Swagger, `class-validator`, and `class-transformer` metadata. Use them when an entity should be reused as the source class for mapped DTOs.
+
+```ts
+import { Column, MysqlModel, PrimaryColumn, Tables } from '@joktec/mysql';
+
+@Tables<ProfileBadge>({ name: 'profile_badges', index: ['code', 'active'] })
+export class ProfileBadge extends MysqlModel {
+  @PrimaryColumn('uuidv7')
+  id?: string;
+
+  @Column({ length: 64, nullable: false, unique: true })
+  code!: string;
+
+  @Column({ length: 128, nullable: false })
+  title!: string;
+
+  @Column({ nullable: false, default: true })
+  active!: boolean;
 }
 ```
 
-## Reference
-[sequelize](https://www.npmjs.com/package/sequelize)
+`@Column` accepts normal TypeORM column options and adds optional schema metadata such as `hidden`, `groups`, `example`, `deprecated`, `swagger`, `decorators`, `required`, `isEmail`, `isPhone`, `isHexColor`, `isUrl`, `minlength`, `maxlength`, `min`, and `max`.
+
+`@PrimaryColumn` supports TypeORM generated strategies (`increment`, `uuid`, `rowid`, `identity`) and JokTec-managed `uuidv7`. `uuidv7` is stored as a 36-character varchar and generated before insert when the entity does not already have an id.
 
-[sequelize-typescript](https://www.npmjs.com/package/sequelize-typescript)
+Guidelines:
 
-## Contributing
-Contributions to `@joktec/mysql` are welcome. If you would like to contribute, please fork the repository, make your changes, and submit a pull request.
+- Prefer numeric auto-increment primary keys for write-heavy MySQL tables.
+- Use UUID primary keys only when the application needs globally unique/public identifiers.
+- Prefer `uuidv7` over random UUIDs when the id is also used as a cursor or clustered/indexed ordering signal.
+- For UUID-heavy cursor pagination, prefer a composite cursor such as `createdAt + id`, or a monotonic indexed cursor column.
+- Add indexes that match common filters and cursor sort order. A cursor using `createdAt + id` should have a matching composite index where possible.
+- `@Tables` provides common TypeORM entity/index wiring, but database-specific search/index behavior should still be verified per dialect.
 
-Please make sure to update tests as appropriate.
+## Error Contract
+
+`MysqlCatch` normalizes common TypeORM driver errors into stable framework codes, including duplicate key, foreign key violation, not-null violation, unknown column, deadlock, lock timeout, connection failure, and transaction conflict. Raw driver details remain attached for logging/debugging, but application code should branch on the stable framework message.
+
+## Repository Layout
+
+- `src/mysql.module.ts`: Nest module and entity registration.
+- `src/mysql.service.ts`: connection lifecycle service.
+- `src/mysql.repo.ts`: base repository and pagination implementation.
+- `src/mysql.config.ts`: config validation and defaults.
+- `src/helpers`: query parsing and TypeORM option helpers.
+- `src/services`: naming strategy and benchmark helpers.
+- `src/models`: model, request, response, and options contracts.
+- `src/index.ts`: public package export boundary.
+
+## Development
+
+```bash
+yarn lint --scope @joktec/mysql
+yarn build --scope @joktec/mysql
+yarn test --scope @joktec/mysql
+```

package/dist/__tests__/mysql.column.decorator.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mysql.column.decorator.spec.d.ts.map

package/dist/__tests__/mysql.column.decorator.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.column.decorator.spec.d.ts","sourceRoot":"","sources":["../../src/__tests__/mysql.column.decorator.spec.ts"],"names":[],"mappings":""}

package/dist/__tests__/mysql.column.decorator.spec.js

@@ -0,0 +1,60 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const utils_1 = require("@joktec/utils");
+const typeorm_1 = require("typeorm");
+const decorators_1 = require("../decorators");
+const UUID_V7_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+(0, globals_1.describe)('MySQL column decorators', () => {
+    (0, globals_1.it)('applies TypeORM column metadata and validation decorators', () => {
+        class ProductColumnFixture {
+        }
+        __decorate([
+            (0, decorators_1.Column)({ length: 10, nullable: false }),
+            __metadata("design:type", String)
+        ], ProductColumnFixture.prototype, "name", void 0);
+        const metadata = (0, typeorm_1.getMetadataArgsStorage)().columns.find(item => item.target === ProductColumnFixture && item.propertyName === 'name');
+        (0, globals_1.expect)(metadata).toBeDefined();
+        (0, globals_1.expect)(metadata.options.length).toEqual(10);
+        const invalid = new ProductColumnFixture();
+        (0, globals_1.expect)((0, utils_1.validateSync)(invalid).map(error => error.property)).toContain('name');
+        const valid = new ProductColumnFixture();
+        valid.name = 'product';
+        (0, globals_1.expect)((0, utils_1.validateSync)(valid)).toHaveLength(0);
+    });
+    (0, globals_1.it)('treats nullable columns as optional validation fields', () => {
+        class OptionalColumnFixture {
+        }
+        __decorate([
+            (0, decorators_1.Column)({ length: 10, nullable: true }),
+            __metadata("design:type", String)
+        ], OptionalColumnFixture.prototype, "code", void 0);
+        (0, globals_1.expect)((0, utils_1.validateSync)(new OptionalColumnFixture())).toHaveLength(0);
+    });
+    (0, globals_1.it)('generates uuidv7 values before insert for primary columns', () => {
+        class UuidPrimaryFixture {
+        }
+        __decorate([
+            (0, decorators_1.PrimaryColumn)('uuidv7'),
+            __metadata("design:type", String)
+        ], UuidPrimaryFixture.prototype, "id", void 0);
+        const fixture = new UuidPrimaryFixture();
+        const hookName = Object.getOwnPropertyNames(UuidPrimaryFixture.prototype).find(name => name.includes('__joktecBeforeInsertUuidV7_id'));
+        (0, globals_1.expect)(hookName).toBeDefined();
+        fixture[hookName]();
+        (0, globals_1.expect)(fixture.id).toMatch(UUID_V7_REGEX);
+        const metadata = (0, typeorm_1.getMetadataArgsStorage)().columns.find(item => item.target === UuidPrimaryFixture && item.propertyName === 'id');
+        (0, globals_1.expect)(metadata).toBeDefined();
+        (0, globals_1.expect)(metadata.options.primary).toEqual(true);
+    });
+});
+//# sourceMappingURL=mysql.column.decorator.spec.js.map

package/dist/__tests__/mysql.column.decorator.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.column.decorator.spec.js","sourceRoot":"","sources":["../../src/__tests__/mysql.column.decorator.spec.ts"],"names":[],"mappings":";;;;;;;;;;;AAAA,2CAAqD;AACrD,yCAA6C;AAC7C,qCAAiD;AACjD,8CAAsD;AAEtD,MAAM,aAAa,GAAG,uEAAuE,CAAC;AAE9F,IAAA,kBAAQ,EAAC,yBAAyB,EAAE,GAAG,EAAE;IACvC,IAAA,YAAE,EAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,oBAAoB;SAGzB;QADC;YADC,IAAA,mBAAM,EAAC,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;;0DAC1B;QAGhB,MAAM,QAAQ,GAAG,IAAA,gCAAsB,GAAE,CAAC,OAAO,CAAC,IAAI,CACpD,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,oBAAoB,IAAI,IAAI,CAAC,YAAY,KAAK,MAAM,CAC7E,CAAC;QAEF,IAAA,gBAAM,EAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;QAC/B,IAAA,gBAAM,EAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAE5C,MAAM,OAAO,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAC3C,IAAA,gBAAM,EAAC,IAAA,oBAAY,EAAC,OAAO,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAE7E,MAAM,KAAK,GAAG,IAAI,oBAAoB,EAAE,CAAC;QACzC,KAAK,CAAC,IAAI,GAAG,SAAS,CAAC;QACvB,IAAA,gBAAM,EAAC,IAAA,oBAAY,EAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,IAAA,YAAE,EAAC,uDAAuD,EAAE,GAAG,EAAE;QAC/D,MAAM,qBAAqB;SAG1B;QADC;YADC,IAAA,mBAAM,EAAC,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;2DACzB;QAGhB,IAAA,gBAAM,EAAC,IAAA,oBAAY,EAAC,IAAI,qBAAqB,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACpE,CAAC,CAAC,CAAC;IAEH,IAAA,YAAE,EAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,kBAAkB;SAGvB;QADC;YADC,IAAA,0BAAa,EAAC,QAAQ,CAAC;;sDACZ;QAGd,MAAM,OAAO,GAAG,IAAI,kBAAkB,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,MAAM,CAAC,mBAAmB,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACpF,IAAI,CAAC,QAAQ,CAAC,+BAA+B,CAAC,CAC/C,CAAC;QAEF,IAAA,gBAAM,EAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;QAC/B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAEpB,IAAA,gBAAM,EAAC,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAE1C,MAAM,QAAQ,GAAG,IAAA,gCAAsB,GAAE,CAAC,OAAO,CAAC,IAAI,CACpD,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,kBAAkB,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI,CACzE,CAAC;QACF,IAAA,gBAAM,EAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;QAC/B,IAAA,gBAAM,EAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/mysql.dialect.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mysql.dialect.spec.d.ts.map

package/dist/__tests__/mysql.dialect.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.dialect.spec.d.ts","sourceRoot":"","sources":["../../src/__tests__/mysql.dialect.spec.ts"],"names":[],"mappings":""}

package/dist/__tests__/mysql.dialect.spec.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mysql_config_1 = require("../mysql.config");
+const services_1 = require("../services");
+describe('Mysql dialect support', () => {
+    it('should default schema sync to explicit opt-in', () => {
+        const config = new mysql_config_1.MysqlConfig({ username: 'root', password: 'root', database: 'joktec' });
+        expect(config.sync).toBe(false);
+    });
+    it('should expose first-class capabilities for mysql and postgres', () => {
+        expect((0, services_1.getMysqlDialectCapabilities)(mysql_config_1.Dialect.MYSQL)).toMatchObject({
+            firstClass: true,
+            caseInsensitiveLike: 'LIKE',
+            fullTextIndex: true,
+        });
+        expect((0, services_1.getMysqlDialectCapabilities)(mysql_config_1.Dialect.POSTGRES)).toMatchObject({
+            firstClass: true,
+            caseInsensitiveLike: 'ILIKE',
+            arrayOperators: true,
+        });
+    });
+    it('should accept only first-class relational dialects', () => {
+        expect(() => (0, services_1.assertFirstClassDialect)(mysql_config_1.Dialect.MYSQL)).not.toThrow();
+        expect(() => (0, services_1.assertFirstClassDialect)(mysql_config_1.Dialect.MARIADB)).not.toThrow();
+        expect(() => (0, services_1.assertFirstClassDialect)(mysql_config_1.Dialect.POSTGRES)).not.toThrow();
+    });
+});
+//# sourceMappingURL=mysql.dialect.spec.js.map

package/dist/__tests__/mysql.dialect.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.dialect.spec.js","sourceRoot":"","sources":["../../src/__tests__/mysql.dialect.spec.ts"],"names":[],"mappings":";;AAAA,kDAAuD;AACvD,0CAAmF;AAEnF,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,MAAM,GAAG,IAAI,0BAAW,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAiB,CAAC,CAAC;QAE1G,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+DAA+D,EAAE,GAAG,EAAE;QACvE,MAAM,CAAC,IAAA,sCAA2B,EAAC,sBAAO,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC;YAC/D,UAAU,EAAE,IAAI;YAChB,mBAAmB,EAAE,MAAM;YAC3B,aAAa,EAAE,IAAI;SACpB,CAAC,CAAC;QACH,MAAM,CAAC,IAAA,sCAA2B,EAAC,sBAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC;YAClE,UAAU,EAAE,IAAI;YAChB,mBAAmB,EAAE,OAAO;YAC5B,cAAc,EAAE,IAAI;SACrB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,CAAC,GAAG,EAAE,CAAC,IAAA,kCAAuB,EAAC,sBAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACnE,MAAM,CAAC,GAAG,EAAE,CAAC,IAAA,kCAAuB,EAAC,sBAAO,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACrE,MAAM,CAAC,GAAG,EAAE,CAAC,IAAA,kCAAuB,EAAC,sBAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/mysql.exception.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mysql.exception.spec.d.ts.map

package/dist/__tests__/mysql.exception.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.exception.spec.d.ts","sourceRoot":"","sources":["../../src/__tests__/mysql.exception.spec.ts"],"names":[],"mappings":""}

package/dist/__tests__/mysql.exception.spec.js

@@ -0,0 +1,42 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const typeorm_1 = require("typeorm");
+const mysql_exception_1 = require("../mysql.exception");
+class QueryFailureHarness {
+    constructor() {
+        this.PinoLogger = {
+            setContext: jest.fn(),
+        };
+    }
+    async run(error) {
+        throw error;
+    }
+}
+__decorate([
+    mysql_exception_1.MysqlCatch,
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Error]),
+    __metadata("design:returntype", Promise)
+], QueryFailureHarness.prototype, "run", null);
+describe('Mysql exception mapping', () => {
+    it('should normalize duplicate key driver errors', async () => {
+        const harness = new QueryFailureHarness();
+        const error = new typeorm_1.QueryFailedError('insert', [], { code: 'ER_DUP_ENTRY' });
+        await expect(harness.run(error)).rejects.toThrow('MYSQL_DUPLICATE_KEY');
+    });
+    it('should normalize postgres deadlock driver errors', async () => {
+        const harness = new QueryFailureHarness();
+        const error = new typeorm_1.QueryFailedError('update', [], { code: '40P01' });
+        await expect(harness.run(error)).rejects.toThrow('MYSQL_DEADLOCK');
+    });
+});
+//# sourceMappingURL=mysql.exception.spec.js.map

package/dist/__tests__/mysql.exception.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.exception.spec.js","sourceRoot":"","sources":["../../src/__tests__/mysql.exception.spec.ts"],"names":[],"mappings":";;;;;;;;;;;AAAA,qCAA2C;AAC3C,wDAAgD;AAEhD,MAAM,mBAAmB;IAAzB;QACE,eAAU,GAAG;YACX,UAAU,EAAE,IAAI,CAAC,EAAE,EAAE;SACtB,CAAC;IAMJ,CAAC;IAHO,AAAN,KAAK,CAAC,GAAG,CAAC,KAAY;QACpB,MAAM,KAAK,CAAC;IACd,CAAC;CACF;AAHO;IADL,4BAAU;;qCACM,KAAK;;8CAErB;AAGH,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;IACvC,EAAE,CAAC,8CAA8C,EAAE,KAAK,IAAI,EAAE;QAC5D,MAAM,OAAO,GAAG,IAAI,mBAAmB,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,IAAI,0BAAgB,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,cAAc,EAA8B,CAAC,CAAC;QAEvG,MAAM,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC1E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,KAAK,IAAI,EAAE;QAChE,MAAM,OAAO,GAAG,IAAI,mBAAmB,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,IAAI,0BAAgB,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAA8B,CAAC,CAAC;QAEhG,MAAM,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/mysql.helper.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mysql.helper.spec.d.ts.map

package/dist/__tests__/mysql.helper.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.helper.spec.d.ts","sourceRoot":"","sources":["../../src/__tests__/mysql.helper.spec.ts"],"names":[],"mappings":""}

package/dist/__tests__/mysql.helper.spec.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const helpers_1 = require("../helpers");
+const mysql_config_1 = require("../mysql.config");
+const metadata = {
+    name: 'TestMysqlEntity',
+    columns: [
+        { propertyName: 'id', propertyPath: 'id' },
+        { propertyName: 'title', propertyPath: 'title' },
+        { propertyName: 'createdAt', propertyPath: 'createdAt' },
+    ],
+    relations: [{ propertyName: 'author', propertyPath: 'author' }],
+};
+const createQueryBuilder = () => ({
+    alias: 'TestMysqlEntity',
+    andWhere: jest.fn().mockReturnThis(),
+    addOrderBy: jest.fn().mockReturnThis(),
+    select: jest.fn().mockReturnThis(),
+    leftJoinAndSelect: jest.fn().mockReturnThis(),
+});
+describe('MysqlHelper query safety', () => {
+    it('should reject unsafe field paths before interpolating identifiers', () => {
+        const qb = createQueryBuilder();
+        expect(() => helpers_1.MysqlHelper.applyOrder(qb, { 'title;drop': 'asc' }, { metadata, dialect: mysql_config_1.Dialect.MYSQL })).toThrow('MYSQL_UNSAFE_FIELD_PATH');
+    });
+    it('should reject unknown columns from request query', () => {
+        const qb = createQueryBuilder();
+        expect(() => helpers_1.MysqlHelper.applyProjection(qb, ['missingColumn'], { metadata, dialect: mysql_config_1.Dialect.MYSQL })).toThrow('MYSQL_UNKNOWN_COLUMN');
+    });
+    it('should reject unsupported array operators for mysql dialect', () => {
+        const qb = createQueryBuilder();
+        expect(() => helpers_1.MysqlHelper.applyCondition(qb, { title: { $size: 2 } }, { metadata, dialect: mysql_config_1.Dialect.MYSQL })).toThrow('MYSQL_OPERATOR_UNSUPPORTED_BY_DIALECT');
+    });
+    it('should choose postgres case-insensitive like operator and escape wildcard input', () => {
+        const qb = createQueryBuilder();
+        helpers_1.MysqlHelper.applyCondition(qb, { title: { $like: 'hello_%\\' } }, {
+            metadata,
+            dialect: mysql_config_1.Dialect.POSTGRES,
+        });
+        expect(qb.andWhere).toHaveBeenCalledWith("TestMysqlEntity.title ILIKE :title_0 ESCAPE '\\\\'", {
+            title_0: '%hello\\_\\%\\\\%',
+        });
+    });
+    it('should reject empty or non-array values for list operators', () => {
+        const qb = createQueryBuilder();
+        expect(() => helpers_1.MysqlHelper.applyCondition(qb, { title: { $in: [] } }, { metadata, dialect: mysql_config_1.Dialect.MYSQL })).toThrow('MYSQL_INVALID_OPERATOR_VALUE');
+        expect(() => helpers_1.MysqlHelper.applyCondition(qb, { title: { $nin: 'draft' } }, { metadata, dialect: mysql_config_1.Dialect.MYSQL })).toThrow('MYSQL_INVALID_OPERATOR_VALUE');
+    });
+    it('should respect boolean semantics for nil and exists operators', () => {
+        const qb = createQueryBuilder();
+        helpers_1.MysqlHelper.applyCondition(qb, {
+            title: { $nil: false },
+            createdAt: { $exists: false },
+        }, { metadata, dialect: mysql_config_1.Dialect.MYSQL });
+        expect(qb.andWhere).toHaveBeenCalledWith('TestMysqlEntity.title IS NOT NULL');
+        expect(qb.andWhere).toHaveBeenCalledWith('TestMysqlEntity.createdAt IS NULL');
+    });
+    it('should keep the root alias when building nested logical clauses', () => {
+        const qb = createQueryBuilder();
+        helpers_1.MysqlHelper.applyCondition(qb, { $or: [{ title: 'first' }, { title: 'second' }] }, {
+            metadata,
+            dialect: mysql_config_1.Dialect.MYSQL,
+        });
+        const rootBracket = qb.andWhere.mock.calls[0][0];
+        const childBuilder = {
+            andWhere: jest.fn().mockReturnThis(),
+            orWhere: jest.fn().mockReturnThis(),
+        };
+        rootBracket.whereFactory(childBuilder);
+        const firstNestedBracket = childBuilder.andWhere.mock.calls[0][0];
+        const grandChildBuilder = {
+            andWhere: jest.fn().mockReturnThis(),
+        };
+        firstNestedBracket.whereFactory(grandChildBuilder);
+        expect(grandChildBuilder.andWhere).toHaveBeenCalledWith('TestMysqlEntity.title = :title_0', {
+            title_0: 'first',
+        });
+    });
+});
+//# sourceMappingURL=mysql.helper.spec.js.map

package/dist/__tests__/mysql.helper.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.helper.spec.js","sourceRoot":"","sources":["../../src/__tests__/mysql.helper.spec.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/mysql.module.integration.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mysql.module.integration.spec.d.ts.map

package/dist/__tests__/mysql.module.integration.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.module.integration.spec.d.ts","sourceRoot":"","sources":["../../src/__tests__/mysql.module.integration.spec.ts"],"names":[],"mappings":""}