@nage-api/data-sql 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,150 @@
+# @nage-api/data-sql
+
+The SQL driver for `@nage-api/data` (PLAN.md §14.1), built on Sequelize.
+
+Install one driver, never two: the engine is chosen when the workspace is
+scaffolded, so no dead branch of the other stack is compiled in. Today this is
+the only driver there is — `@nage-api/data-mongo` (§8) has not been written.
+
+`sequelize` is a **peer** dependency, so the dialect package is yours to choose:
+`pg`, `mysql2`, `mariadb` or `sqlite3` alongside it.
+
+```ts
+import { Module } from '@nestjs/common';
+import { resolveTlsOptions } from '@nage-api/core';
+import { NageSqlModule } from '@nage-api/data-sql';
+import type { NageConfig } from '@nage-api/contracts';
+import { Sequelize } from 'sequelize';
+
+import type { Env } from './config/env.schema.js';
+
+/** Both come from the application: validated env, and the config it built. */
+declare const env: Env;
+declare const config: NageConfig;
+
+const sequelize = new Sequelize(env.DATABASE_URL, {
+  // `verify-full` unless the config says otherwise; the legacy pair of
+  // `rejectUnauthorized: false` literals is what this replaces (§12).
+  dialectOptions: { ssl: resolveTlsOptions(config.database?.ssl) },
+  logging: false,
+});
+
+@Module({ imports: [NageSqlModule.forRoot({ sequelize })] })
+export class AppModule {}
+```
+
+A model declares the framework's audit columns and leaves Sequelize's own
+bookkeeping off, because the driver stamps those columns itself:
+
+```ts
+import { defineQueryPolicy } from '@nage-api/data';
+import { SqlRepository } from '@nage-api/data-sql';
+import { DataTypes, type Model, type ModelStatic, type Sequelize } from 'sequelize';
+
+interface Product {
+  readonly id: number;
+  name: string;
+  price: number;
+}
+
+/** The row type the driver expects: attributes stay opaque to it. */
+type Row = Model<Record<string, unknown>, Record<string, unknown>>;
+
+declare const sequelize: Sequelize;
+
+const ProductModel: ModelStatic<Row> = sequelize.define<Row>(
+  'Product',
+  {
+    id: { type: DataTypes.INTEGER, primaryKey: true, autoIncrement: true },
+    name: { type: DataTypes.STRING, allowNull: false },
+    price: { type: DataTypes.INTEGER, allowNull: false },
+    // Stamped by `@nage-api/data`, so they are ordinary columns here.
+    created_at: DataTypes.STRING,
+    updated_at: DataTypes.STRING,
+    created_by: DataTypes.INTEGER,
+    updated_by: DataTypes.INTEGER,
+    deleted_at: DataTypes.STRING,
+    deleted_by: DataTypes.INTEGER,
+  },
+  // `timestamps: false` and no `paranoid`: two mechanisms writing the same
+  // columns disagree about their format and their meaning.
+  { tableName: 'products', timestamps: false, freezeTableName: true },
+);
+
+const productPolicy = defineQueryPolicy<Product>({
+  filterable: ['name', 'price'],
+  sortable: ['name', 'price'],
+  selectable: ['id', 'name', 'price'],
+  searchable: ['name'],
+});
+
+const products = new SqlRepository<Product>(ProductModel, { policy: productPolicy });
+```
+
+## What it provides
+
+| Export                | Purpose                                                           |
+| --------------------- | ----------------------------------------------------------------- |
+| `SqlRepository`       | `RepositoryPort` over a Sequelize model                           |
+| `SqlUnitOfWork`       | `UnitOfWork` over a managed Sequelize transaction                 |
+| `SqlMigrationStore`   | The migrations ledger, plus a best-effort lock                    |
+| `SqlDataSourceHealth` | `authenticate()` probe for `/health/ready`                        |
+| `translateWhere`      | The DSL → `Op.*` translation                                      |
+| `NageSqlModule`       | Publishes the unit of work and health probe against core's tokens |
+
+## Behaviour worth knowing
+
+**A client-supplied key never reaches Sequelize.** `translateWhere` maps each
+DSL operator to an `Op.*` symbol and throws on anything else, so the emitted
+clause contains only symbols this package owns. That is the second line of
+defence; `parseQuery` in `@nage-api/data` is the first.
+
+**Audit and soft delete are the framework's, not Sequelize's.** The driver uses
+the shared `stamp*` helpers rather than Sequelize's `timestamps`/`paranoid`, so
+the columns and semantics are identical across drivers — which is what lets one
+conformance suite cover both.
+
+**Transactions are the database's.** `SqlUnitOfWork.run` uses a managed
+transaction: it commits on success, rolls back on failure, and re-raises the
+original error — the same observable contract the in-memory driver gives.
+
+**Migrations replace auto-sync.** `SqlMigrationStore` records each applied
+migration in `nage_migrations`. Its lock is a row in that same table rather than
+an advisory lock — SQLite has none — so it is best effort: it stops a second
+process starting, and a process that dies mid-migration leaves the row behind
+for an operator to delete. Migrating as one deploy step, not on every instance
+boot, is what the design assumes. `nage db migrate` is the intended entry point
+and is **not implemented yet** (see `@nage-api/cli`'s "Not yet implemented"), so
+today the runner is called from a script of your own.
+
+## Testing
+
+The driver runs the shared conformance suite from `@nage-api/data` against SQLite
+in-process — real SQL generation, real transactions, no container required, and
+the same suite the in-memory driver runs, which is what makes parity checkable.
+
+Against Postgres and MySQL it is untested. `@nage-api/testing` ships the
+`ContainerHarness` the matrix needs and pins the images, but no suite here uses
+it and the adapter has never run against Docker, so dialect-specific behaviour —
+`ILIKE`, the `LIKE` escape character, `findAndCountAll` with a join — rests on
+Sequelize rather than on a test in this repository.
+
+## Not yet implemented
+
+- **The module does not open the connection.** `forRoot` takes an already-built
+  `Sequelize`; there is no `forRootAsync` and nothing reads `database.pool`, so
+  pool sizing, `acquireTimeoutMs` and connect-retry backoff are the application's
+  to arrange (§14.2). It does close the pool: `onApplicationShutdown` calls
+  `sequelize.close()`, and `installShutdown` runs that **after** the HTTP drain,
+  so nothing is still querying when it happens.
+- **Named scopes.** `Query.scope` reaches the driver and is ignored.
+- **Optimistic locking.** `descriptor.versioned` is accepted and unused.
+- **`bulkUpdate` and `bulkDelete` are row-by-row.** Each matching row is fetched
+  and written individually so that the audit stamps and soft-delete semantics
+  match the other driver exactly; a wide bulk write is N statements, not one.
+- **`populate` is thin.** It becomes a Sequelize `include` by association name.
+  Only a `belongsTo` case is tested, and the driver does not set `distinct`, so
+  eager-loading a to-many association can inflate `pagination.count`.
+
+`docs/packages/data-sql.md` is the longer guide: every option and its default, the
+model definition this driver expects, and the mistakes worth knowing about.

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@nage-api/data-sql` — the SQL driver (PLAN.md §14.1).
+ *
+ * Implements the ports declared by `@nage-api/data` on top of Sequelize. A project
+ * installs this **or** `@nage-api/data-mongo`, never both: the engine is chosen at
+ * scaffold time, so no dead branch of the other stack is compiled in — the
+ * problem that made every legacy deployment boot a Mongo connection it did not
+ * use.
+ */
+export { SqlRepository, type SqlRepositoryOptions } from './sql.repository.js';
+export { SqlUnitOfWork, transactionOf, type SqlTxContext } from './sql.unit-of-work.js';
+export { SqlMigrationStore, type SqlMigrationStoreOptions } from './sql.migration-store.js';
+export { SqlDataSourceHealth } from './sql.health.js';
+export { translateWhere } from './where-translator.js';
+export { NageSqlModule, type SqlModuleOptions } from './sql.module.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * `@nage-api/data-sql` — the SQL driver (PLAN.md §14.1).
+ *
+ * Implements the ports declared by `@nage-api/data` on top of Sequelize. A project
+ * installs this **or** `@nage-api/data-mongo`, never both: the engine is chosen at
+ * scaffold time, so no dead branch of the other stack is compiled in — the
+ * problem that made every legacy deployment boot a Mongo connection it did not
+ * use.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NageSqlModule = exports.translateWhere = exports.SqlDataSourceHealth = exports.SqlMigrationStore = exports.transactionOf = exports.SqlUnitOfWork = exports.SqlRepository = void 0;
+var sql_repository_js_1 = require("./sql.repository.js");
+Object.defineProperty(exports, "SqlRepository", { enumerable: true, get: function () { return sql_repository_js_1.SqlRepository; } });
+var sql_unit_of_work_js_1 = require("./sql.unit-of-work.js");
+Object.defineProperty(exports, "SqlUnitOfWork", { enumerable: true, get: function () { return sql_unit_of_work_js_1.SqlUnitOfWork; } });
+Object.defineProperty(exports, "transactionOf", { enumerable: true, get: function () { return sql_unit_of_work_js_1.transactionOf; } });
+var sql_migration_store_js_1 = require("./sql.migration-store.js");
+Object.defineProperty(exports, "SqlMigrationStore", { enumerable: true, get: function () { return sql_migration_store_js_1.SqlMigrationStore; } });
+var sql_health_js_1 = require("./sql.health.js");
+Object.defineProperty(exports, "SqlDataSourceHealth", { enumerable: true, get: function () { return sql_health_js_1.SqlDataSourceHealth; } });
+var where_translator_js_1 = require("./where-translator.js");
+Object.defineProperty(exports, "translateWhere", { enumerable: true, get: function () { return where_translator_js_1.translateWhere; } });
+var sql_module_js_1 = require("./sql.module.js");
+Object.defineProperty(exports, "NageSqlModule", { enumerable: true, get: function () { return sql_module_js_1.NageSqlModule; } });
+//# sourceMappingURL=index.js.map

package/dist/sql.health.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Connection probe for `/health/ready` (PLAN.md §21).
+ *
+ * `authenticate()` issues a trivial query, so a pool that has lost its
+ * connection reports down instead of the instance discovering it on the next
+ * request.
+ */
+import type { DataSourceHealth } from '@nage-api/contracts';
+import type { Sequelize } from 'sequelize';
+export declare class SqlDataSourceHealth implements DataSourceHealth {
+    private readonly sequelize;
+    readonly driver: string;
+    constructor(sequelize: Sequelize);
+    ping(): Promise<boolean>;
+}
+//# sourceMappingURL=sql.health.d.ts.map

package/dist/sql.health.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Connection probe for `/health/ready` (PLAN.md §21).
+ *
+ * `authenticate()` issues a trivial query, so a pool that has lost its
+ * connection reports down instead of the instance discovering it on the next
+ * request.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlDataSourceHealth = void 0;
+class SqlDataSourceHealth {
+    sequelize;
+    driver;
+    constructor(sequelize) {
+        this.sequelize = sequelize;
+        this.driver = `sql:${sequelize.getDialect()}`;
+    }
+    async ping() {
+        try {
+            await this.sequelize.authenticate();
+            return true;
+        }
+        catch {
+            // The reason is the caller's to log; readiness only needs the verdict.
+            return false;
+        }
+    }
+}
+exports.SqlDataSourceHealth = SqlDataSourceHealth;
+//# sourceMappingURL=sql.health.js.map

package/dist/sql.migration-store.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The migrations ledger, in SQL (PLAN.md §14.2).
+ *
+ * One row per applied migration, plus an advisory lock so that four instances
+ * booting together do not all try to migrate — the failure mode `synchronize`
+ * had, at a worse moment.
+ */
+import type { AppliedMigration, MigrationStore } from '@nage-api/data';
+import { type Sequelize } from 'sequelize';
+export interface SqlMigrationStoreOptions {
+    /** Ledger table name; `nage_migrations` by default. */
+    readonly tableName?: string;
+}
+export declare class SqlMigrationStore implements MigrationStore {
+    #private;
+    constructor(sequelize: Sequelize, options?: SqlMigrationStoreOptions);
+    initialize(): Promise<void>;
+    applied(): Promise<readonly AppliedMigration[]>;
+    record(migration: AppliedMigration): Promise<void>;
+    remove(id: string): Promise<void>;
+    /**
+     * Best-effort lock.
+     *
+     * A row in the ledger stands in for a lock the dialect may not have; SQLite in
+     * particular has no advisory locks. It is honest about being best effort:
+     * `nage db migrate` as a deploy step remains the supported path.
+     */
+    lock(): Promise<boolean>;
+    unlock(): Promise<void>;
+}
+//# sourceMappingURL=sql.migration-store.d.ts.map

package/dist/sql.migration-store.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * The migrations ledger, in SQL (PLAN.md §14.2).
+ *
+ * One row per applied migration, plus an advisory lock so that four instances
+ * booting together do not all try to migrate — the failure mode `synchronize`
+ * had, at a worse moment.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlMigrationStore = void 0;
+const core_1 = require("@nage-api/core");
+const sequelize_1 = require("sequelize");
+class SqlMigrationStore {
+    #sequelize;
+    #tableName;
+    #model;
+    #locked = false;
+    constructor(sequelize, options = {}) {
+        this.#sequelize = sequelize;
+        this.#tableName = options.tableName ?? 'nage_migrations';
+    }
+    async initialize() {
+        if (this.#model !== undefined)
+            return;
+        this.#model = this.#sequelize.define(this.#tableName, {
+            id: { type: sequelize_1.DataTypes.STRING(255), primaryKey: true },
+            name: { type: sequelize_1.DataTypes.STRING(255), allowNull: false },
+            applied_at: { type: sequelize_1.DataTypes.STRING(64), allowNull: false },
+            checksum: { type: sequelize_1.DataTypes.STRING(128), allowNull: true },
+        }, { tableName: this.#tableName, timestamps: false, freezeTableName: true });
+        await this.#model.sync();
+    }
+    async applied() {
+        const rows = await this.#require().findAll({ order: [['id', 'ASC']] });
+        return (rows
+            // The lock lives in the same table; it is not a migration.
+            .filter((row) => String(row.get({ plain: true })['id']) !== LOCK_ID)
+            .map((row) => {
+            const plain = row.get({ plain: true });
+            const checksum = plain['checksum'];
+            return {
+                id: String(plain['id']),
+                name: String(plain['name']),
+                appliedAt: String(plain['applied_at']),
+                ...(typeof checksum === 'string' ? { checksum } : {}),
+            };
+        }));
+    }
+    async record(migration) {
+        await this.#require().create({
+            id: migration.id,
+            name: migration.name,
+            applied_at: migration.appliedAt,
+            checksum: migration.checksum ?? null,
+        });
+    }
+    async remove(id) {
+        await this.#require().destroy({ where: { id } });
+    }
+    /**
+     * Best-effort lock.
+     *
+     * A row in the ledger stands in for a lock the dialect may not have; SQLite in
+     * particular has no advisory locks. It is honest about being best effort:
+     * `nage db migrate` as a deploy step remains the supported path.
+     */
+    async lock() {
+        const model = this.#require();
+        const existing = await model.findByPk(LOCK_ID);
+        if (existing !== null)
+            return false;
+        await model.create({
+            id: LOCK_ID,
+            name: 'lock',
+            applied_at: new Date().toISOString(),
+            checksum: null,
+        });
+        this.#locked = true;
+        return true;
+    }
+    async unlock() {
+        if (!this.#locked)
+            return;
+        await this.#require().destroy({ where: { id: LOCK_ID } });
+        this.#locked = false;
+    }
+    #require() {
+        if (this.#model === undefined) {
+            throw new core_1.DatabaseError({ detail: 'The migration store has not been initialised' });
+        }
+        return this.#model;
+    }
+}
+exports.SqlMigrationStore = SqlMigrationStore;
+/** Sorts before any timestamp id, and is filtered out of `applied()` by name. */
+const LOCK_ID = '__lock__';
+//# sourceMappingURL=sql.migration-store.js.map

package/dist/sql.module.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `NageSqlModule.forRoot()` — wires the SQL driver into an application
+ * (PLAN.md §7.3).
+ *
+ * Publishes the unit of work and the health probe against the tokens declared
+ * by `@nage-api/core`, so application code and feature packages inject ports and
+ * never this module.
+ *
+ * It also closes the pool on shutdown (§21, "DB lifecycle … close on
+ * shutdown"), which nothing did before: the connections were left to the process
+ * exit. On a rolling deploy that leaves the server holding sessions for an
+ * instance that has gone, and any statement still open is torn down rather than
+ * ended. The hook runs after the HTTP drain — see `installShutdown` in
+ * `@nage-api/core`, which is what puts the two in that order.
+ */
+import { type DynamicModule } from '@nestjs/common';
+import type { LoggerPort } from '@nage-api/contracts';
+import type { Sequelize } from 'sequelize';
+/** Token for the connection itself, for code that needs raw SQL. */
+export declare const NAGE_SEQUELIZE: unique symbol;
+export interface SqlModuleOptions {
+    /** An already-configured connection. TLS comes from `resolveTlsOptions` (§12). */
+    readonly sequelize: Sequelize;
+}
+export declare class NageSqlModule {
+    private readonly sequelize;
+    private readonly logger?;
+    constructor(sequelize: Sequelize, logger?: LoggerPort | undefined);
+    static forRoot(options: SqlModuleOptions): DynamicModule;
+    onApplicationShutdown(): Promise<void>;
+}
+//# sourceMappingURL=sql.module.d.ts.map

package/dist/sql.module.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * `NageSqlModule.forRoot()` — wires the SQL driver into an application
+ * (PLAN.md §7.3).
+ *
+ * Publishes the unit of work and the health probe against the tokens declared
+ * by `@nage-api/core`, so application code and feature packages inject ports and
+ * never this module.
+ *
+ * It also closes the pool on shutdown (§21, "DB lifecycle … close on
+ * shutdown"), which nothing did before: the connections were left to the process
+ * exit. On a rolling deploy that leaves the server holding sessions for an
+ * instance that has gone, and any statement still open is torn down rather than
+ * ended. The hook runs after the HTTP drain — see `installShutdown` in
+ * `@nage-api/core`, which is what puts the two in that order.
+ */
+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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var NageSqlModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NageSqlModule = exports.NAGE_SEQUELIZE = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nage-api/core");
+const data_1 = require("@nage-api/data");
+const sql_health_js_1 = require("./sql.health.js");
+const sql_unit_of_work_js_1 = require("./sql.unit-of-work.js");
+/** Token for the connection itself, for code that needs raw SQL. */
+exports.NAGE_SEQUELIZE = Symbol('NAGE_SEQUELIZE');
+let NageSqlModule = NageSqlModule_1 = class NageSqlModule {
+    sequelize;
+    logger;
+    constructor(sequelize, logger) {
+        this.sequelize = sequelize;
+        this.logger = logger;
+    }
+    static forRoot(options) {
+        return {
+            module: NageSqlModule_1,
+            providers: [
+                { provide: exports.NAGE_SEQUELIZE, useValue: options.sequelize },
+                { provide: core_1.NAGE_UNIT_OF_WORK, useValue: new sql_unit_of_work_js_1.SqlUnitOfWork(options.sequelize) },
+                { provide: data_1.NAGE_DATA_HEALTH, useValue: new sql_health_js_1.SqlDataSourceHealth(options.sequelize) },
+            ],
+            exports: [exports.NAGE_SEQUELIZE, core_1.NAGE_UNIT_OF_WORK, data_1.NAGE_DATA_HEALTH],
+        };
+    }
+    async onApplicationShutdown() {
+        try {
+            await this.sequelize.close();
+        }
+        catch (error) {
+            // Reported, not rethrown: a driver that cannot close is not a reason to
+            // fail the shutdown that is already under way, and the shutdown sequence
+            // would otherwise turn this into a non-zero exit on every deploy.
+            this.logger?.warn('Closing the database connection failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+};
+exports.NageSqlModule = NageSqlModule;
+exports.NageSqlModule = NageSqlModule = NageSqlModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({}),
+    __param(0, (0, common_1.Inject)(exports.NAGE_SEQUELIZE)),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(core_1.NAGE_LOGGER)),
+    __metadata("design:paramtypes", [Function, Object])
+], NageSqlModule);
+//# sourceMappingURL=sql.module.js.map

package/dist/sql.repository.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Sequelize-backed `RepositoryPort` (PLAN.md §14.1).
+ *
+ * The same contract the in-memory driver implements, over a real database. It
+ * shares the DSL, the audit stamping and the soft-delete semantics with
+ * `@nage-api/data` rather than reimplementing them, so behaviour that the
+ * conformance suite pins down cannot drift between drivers.
+ */
+import type { BulkResult, ByIdQuery, CursorPaginated, DeepPartial, DeleteOptions, Id, ModelDescriptor, Paginated, Query, QueryPolicy, RepositoryPort, UnknownRecord, WriteOptions } from '@nage-api/contracts';
+import type { Model, ModelStatic } from 'sequelize';
+/** A Sequelize model instance carrying arbitrary attributes. */
+type AnyModel = Model<UnknownRecord, UnknownRecord>;
+export interface SqlRepositoryOptions<TEntity> {
+    readonly descriptor?: Partial<ModelDescriptor<TEntity>>;
+    readonly policy?: QueryPolicy<TEntity>;
+    readonly now?: () => Date;
+}
+export declare class SqlRepository<TEntity extends {
+    id: Id;
+}> implements RepositoryPort<TEntity> {
+    #private;
+    readonly descriptor: ModelDescriptor<TEntity>;
+    constructor(model: ModelStatic<AnyModel>, options?: SqlRepositoryOptions<TEntity>);
+    findAll(query?: Query<TEntity>): Promise<Paginated<TEntity>>;
+    findByCursor(query?: Query<TEntity>): Promise<CursorPaginated<TEntity>>;
+    findOne(query?: Query<TEntity>): Promise<TEntity | null>;
+    findById(id: Id, query?: Omit<ByIdQuery<TEntity>, 'id'>): Promise<TEntity | null>;
+    exists(query?: Query<TEntity>): Promise<boolean>;
+    count(query?: Query<TEntity>): Promise<number>;
+    create(data: DeepPartial<TEntity>, options?: WriteOptions): Promise<TEntity>;
+    update(id: Id, data: DeepPartial<TEntity>, options?: WriteOptions): Promise<TEntity>;
+    delete(id: Id, options?: DeleteOptions): Promise<void>;
+    restore(id: Id, options?: WriteOptions): Promise<TEntity>;
+    bulkCreate(data: readonly DeepPartial<TEntity>[], options?: WriteOptions): Promise<BulkResult<TEntity>>;
+    bulkUpdate(query: Query<TEntity>, data: DeepPartial<TEntity>, options?: WriteOptions): Promise<BulkResult<TEntity>>;
+    bulkDelete(query: Query<TEntity>, options?: DeleteOptions): Promise<number>;
+}
+export {};
+//# sourceMappingURL=sql.repository.d.ts.map

package/dist/sql.repository.js

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * Sequelize-backed `RepositoryPort` (PLAN.md §14.1).
+ *
+ * The same contract the in-memory driver implements, over a real database. It
+ * shares the DSL, the audit stamping and the soft-delete semantics with
+ * `@nage-api/data` rather than reimplementing them, so behaviour that the
+ * conformance suite pins down cannot drift between drivers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlRepository = void 0;
+const core_1 = require("@nage-api/core");
+const data_1 = require("@nage-api/data");
+const where_translator_js_1 = require("./where-translator.js");
+const sql_unit_of_work_js_1 = require("./sql.unit-of-work.js");
+class SqlRepository {
+    descriptor;
+    #model;
+    #policy;
+    #now;
+    constructor(model, options = {}) {
+        this.#model = model;
+        this.descriptor = {
+            name: model.name,
+            primaryKey: 'id',
+            softDelete: true,
+            timestamps: true,
+            versioned: false,
+            ...options.descriptor,
+        };
+        this.#policy = options.policy ?? (0, data_1.defineQueryPolicy)();
+        this.#now = options.now ?? (() => new Date());
+    }
+    // ── Reads ─────────────────────────────────────────────────────────────────
+    async findAll(query = {}) {
+        const { offset, limit } = (0, data_1.resolvePagination)(query, this.#policy);
+        const { rows, count } = await this.#model.findAndCountAll({
+            ...this.#findOptions(query),
+            offset,
+            limit,
+        });
+        return {
+            records: rows.map((row) => this.#toEntity(row, query)),
+            pagination: { offset, limit, count },
+        };
+    }
+    async findByCursor(query = {}) {
+        const { limit } = (0, data_1.resolvePagination)(query, this.#policy);
+        const offset = query.cursor === undefined ? 0 : Number(decodeCursor(query.cursor));
+        // One extra row answers "is there more?" without a second count query.
+        const rows = await this.#model.findAll({
+            ...this.#findOptions(query),
+            offset,
+            limit: limit + 1,
+        });
+        const hasMore = rows.length > limit;
+        const page = hasMore ? rows.slice(0, limit) : rows;
+        return {
+            records: page.map((row) => this.#toEntity(row, query)),
+            pagination: {
+                nextCursor: hasMore ? encodeCursor(String(offset + limit)) : null,
+                limit,
+                hasMore,
+            },
+        };
+    }
+    async findOne(query = {}) {
+        const row = await this.#model.findOne(this.#findOptions(query));
+        return row === null ? null : this.#toEntity(row, query);
+    }
+    async findById(id, query = {}) {
+        const row = await this.#findRow(id, query.withDeleted === true);
+        return row === null ? null : this.#toEntity(row, query);
+    }
+    async exists(query = {}) {
+        return (await this.count(query)) > 0;
+    }
+    count(query = {}) {
+        return this.#model.count({ where: this.#whereFor(query) });
+    }
+    // ── Writes ────────────────────────────────────────────────────────────────
+    async create(data, options = {}) {
+        const row = await this.#model.create((0, data_1.stampCreate)(data, { now: this.#now }), {
+            ...this.#transaction(options),
+        });
+        return this.#toEntity(row);
+    }
+    async update(id, data, options = {}) {
+        const row = await this.#findRow(id, false);
+        if (row === null)
+            throw this.#notFound(id);
+        await row.update((0, data_1.stampUpdate)(data, { now: this.#now }), {
+            ...this.#transaction(options),
+        });
+        return this.#toEntity(row);
+    }
+    async delete(id, options = {}) {
+        const row = await this.#findRow(id, false);
+        if (row === null)
+            throw this.#notFound(id);
+        const mode = options.mode ?? (this.descriptor.softDelete ? 'soft' : 'hard');
+        if (mode === 'hard' || !this.descriptor.softDelete) {
+            await row.destroy({ ...this.#transaction(options) });
+            return;
+        }
+        await row.update((0, data_1.stampSoftDelete)({ now: this.#now }), { ...this.#transaction(options) });
+    }
+    async restore(id, options = {}) {
+        const row = await this.#findRow(id, true);
+        if (row === null)
+            throw this.#notFound(id);
+        await row.update((0, data_1.stampRestore)({ now: this.#now }), { ...this.#transaction(options) });
+        return this.#toEntity(row);
+    }
+    async bulkCreate(data, options = {}) {
+        const rows = await this.#model.bulkCreate(data.map((entry) => (0, data_1.stampCreate)(entry, { now: this.#now })), { ...this.#transaction(options) });
+        return { affected: rows.length, records: rows.map((row) => this.#toEntity(row)) };
+    }
+    async bulkUpdate(query, data, options = {}) {
+        const rows = await this.#model.findAll({ where: this.#whereFor(query) });
+        const patch = (0, data_1.stampUpdate)(data, { now: this.#now });
+        for (const row of rows)
+            await row.update(patch, { ...this.#transaction(options) });
+        return { affected: rows.length, records: rows.map((row) => this.#toEntity(row)) };
+    }
+    async bulkDelete(query, options = {}) {
+        const rows = await this.#model.findAll({ where: this.#whereFor(query) });
+        const mode = options.mode ?? (this.descriptor.softDelete ? 'soft' : 'hard');
+        for (const row of rows) {
+            if (mode === 'hard' || !this.descriptor.softDelete) {
+                await row.destroy({ ...this.#transaction(options) });
+            }
+            else {
+                await row.update((0, data_1.stampSoftDelete)({ now: this.#now }), { ...this.#transaction(options) });
+            }
+        }
+        return rows.length;
+    }
+    // ── Internals ─────────────────────────────────────────────────────────────
+    #findOptions(query) {
+        const options = { where: this.#whereFor(query) };
+        if (query.sort !== undefined && query.sort.length > 0) {
+            options.order = query.sort.map(([field, direction]) => [
+                field,
+                direction.toUpperCase(),
+            ]);
+        }
+        if (query.select !== undefined && query.select.length > 0) {
+            // The primary key is always fetched: a record the caller cannot identify
+            // is of little use, and soft-delete checks need it.
+            options.attributes = [...new Set([this.descriptor.primaryKey, ...query.select])];
+        }
+        if (query.populate !== undefined && query.populate.length > 0) {
+            options.include = query.populate.map((relation) => ({ association: relation }));
+        }
+        return options;
+    }
+    /**
+     * Build the `where` clause, layering soft delete and search on top of the
+     * translated DSL.
+     */
+    #whereFor(query) {
+        const clauses = [
+            (0, where_translator_js_1.translateWhere)(query.where, this.#dialect()),
+        ];
+        if (this.descriptor.softDelete && query.withDeleted !== true) {
+            clauses.push({ deleted_at: null });
+        }
+        if (query.search !== undefined) {
+            const fields = query.search.fields ?? this.#policy.searchable;
+            const term = `%${escapeLike(query.search.term)}%`;
+            const searchClause = (0, where_translator_js_1.translateWhere)({ or: fields.map((field) => ({ [field]: { ilike: term } })) }, this.#dialect());
+            clauses.push(searchClause);
+        }
+        return Object.assign({}, ...clauses);
+    }
+    async #findRow(id, withDeleted) {
+        const row = await this.#model.findByPk(id);
+        if (row === null)
+            return null;
+        if (!withDeleted && this.descriptor.softDelete && (0, data_1.isSoftDeleted)(row.get())) {
+            return null;
+        }
+        return row;
+    }
+    /**
+     * Narrow a row back to the fields the caller selected.
+     *
+     * `#findOptions` widens the SQL attribute list with the primary key, so the
+     * row carries a column the caller did not ask for; every read has to project
+     * it away. Skipping this on the list reads is what let the SQL driver return
+     * `id` while the in-memory driver did not, and a projection that differs by
+     * driver is a response shape that changes with the engine.
+     */
+    #toEntity(row, query = {}) {
+        const plain = row.get({ plain: true });
+        if (query.select === undefined || query.select.length === 0)
+            return plain;
+        const projected = {};
+        for (const field of query.select)
+            projected[field] = plain[field];
+        return projected;
+    }
+    #transaction(options) {
+        const transaction = (0, sql_unit_of_work_js_1.transactionOf)(options.tx);
+        return transaction === undefined ? {} : { transaction };
+    }
+    #dialect() {
+        return this.#model.sequelize?.getDialect() ?? 'postgres';
+    }
+    #notFound(id) {
+        return new core_1.NotFoundError({
+            detail: `${this.descriptor.name} ${String(id)} was not found`,
+            meta: { model: this.descriptor.name, id },
+        });
+    }
+}
+exports.SqlRepository = SqlRepository;
+/**
+ * `%` and `_` are wildcards in LIKE; a searched term must not carry them.
+ *
+ * The backslash is the default LIKE escape character on Postgres and MySQL, so
+ * no `ESCAPE` clause is emitted. SQLite has no default escape character, so
+ * there a term containing `%`, `_` or `\` matches nothing instead of matching
+ * the literal — a false negative, and the safe direction to be wrong in: the
+ * alternative, leaving the term unescaped, turns one keystroke into a
+ * full-table read.
+ */
+function escapeLike(term) {
+    return term.replace(/[%_\\]/g, '\\$&');
+}
+function encodeCursor(value) {
+    return Buffer.from(value, 'utf8').toString('base64url');
+}
+function decodeCursor(cursor) {
+    return Buffer.from(cursor, 'base64url').toString('utf8');
+}
+//# sourceMappingURL=sql.repository.js.map

package/dist/sql.unit-of-work.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Sequelize transactions behind the `UnitOfWork` port (PLAN.md §14.2).
+ *
+ * The legacy framework had no transaction abstraction at all: a bulk operation
+ * that failed halfway left the rows it had already written. Here a unit commits
+ * or rolls back as a whole, and the lifecycle hooks of `ModelService` run inside
+ * it, so a failing `doAfterCreate` undoes the create.
+ */
+import type { TxContext, UnitOfWork } from '@nage-api/contracts';
+import type { Sequelize, Transaction } from 'sequelize';
+/**
+ * The driver's transaction handle.
+ *
+ * `TxContext` is deliberately opaque in the contract — its shape is the driver's
+ * business — so the Sequelize transaction rides along here and repositories
+ * read it back out.
+ */
+export interface SqlTxContext extends TxContext {
+    readonly transaction: Transaction;
+}
+export declare class SqlUnitOfWork implements UnitOfWork {
+    private readonly sequelize;
+    constructor(sequelize: Sequelize);
+    /**
+     * Run `fn` inside a managed transaction.
+     *
+     * Sequelize commits when the callback resolves and rolls back when it throws,
+     * re-raising the original error — the same observable behaviour the in-memory
+     * driver gives, which is what lets one conformance suite cover both.
+     */
+    run<TResult>(fn: (tx: TxContext) => Promise<TResult>): Promise<TResult>;
+}
+/** Read the Sequelize transaction out of an opaque context, if there is one. */
+export declare function transactionOf(tx: TxContext | undefined): Transaction | undefined;
+//# sourceMappingURL=sql.unit-of-work.d.ts.map

package/dist/sql.unit-of-work.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Sequelize transactions behind the `UnitOfWork` port (PLAN.md §14.2).
+ *
+ * The legacy framework had no transaction abstraction at all: a bulk operation
+ * that failed halfway left the rows it had already written. Here a unit commits
+ * or rolls back as a whole, and the lifecycle hooks of `ModelService` run inside
+ * it, so a failing `doAfterCreate` undoes the create.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlUnitOfWork = void 0;
+exports.transactionOf = transactionOf;
+const core_1 = require("@nage-api/core");
+class SqlUnitOfWork {
+    sequelize;
+    constructor(sequelize) {
+        this.sequelize = sequelize;
+    }
+    /**
+     * Run `fn` inside a managed transaction.
+     *
+     * Sequelize commits when the callback resolves and rolls back when it throws,
+     * re-raising the original error — the same observable behaviour the in-memory
+     * driver gives, which is what lets one conformance suite cover both.
+     */
+    run(fn) {
+        return this.sequelize.transaction(async (transaction) => {
+            const context = { id: (0, core_1.randomId)(), driver: 'sql', transaction };
+            return fn(context);
+        });
+    }
+}
+exports.SqlUnitOfWork = SqlUnitOfWork;
+/** Read the Sequelize transaction out of an opaque context, if there is one. */
+function transactionOf(tx) {
+    return tx?.transaction;
+}
+//# sourceMappingURL=sql.unit-of-work.js.map

package/dist/where-translator.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Translate the typed `Where` DSL into Sequelize's operator symbols
+ * (PLAN.md §12, §14.1).
+ *
+ * The translation is total and closed: every operator the DSL defines maps to a
+ * `Op.*` symbol, and anything else throws. The legacy driver passed
+ * client-supplied `$`-keys through to the ORM, which is how a query language
+ * became an injection surface — here a client-supplied key never reaches
+ * Sequelize, because only names this function knows are emitted.
+ */
+import type { Where } from '@nage-api/contracts';
+type SequelizeWhere = Record<string | symbol, unknown>;
+/** Convert a validated `Where` clause into a Sequelize `where` object. */
+export declare function translateWhere<TEntity>(where: Where<TEntity> | undefined, dialect?: string): SequelizeWhere;
+export {};
+//# sourceMappingURL=where-translator.d.ts.map

package/dist/where-translator.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Translate the typed `Where` DSL into Sequelize's operator symbols
+ * (PLAN.md §12, §14.1).
+ *
+ * The translation is total and closed: every operator the DSL defines maps to a
+ * `Op.*` symbol, and anything else throws. The legacy driver passed
+ * client-supplied `$`-keys through to the ORM, which is how a query language
+ * became an injection surface — here a client-supplied key never reaches
+ * Sequelize, because only names this function knows are emitted.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.translateWhere = translateWhere;
+const sequelize_1 = require("sequelize");
+const core_1 = require("@nage-api/core");
+/**
+ * A `Map` rather than an object: a lookup miss is `undefined`, which is the
+ * case that matters here — an unknown key must fall through to the rejection
+ * below rather than quietly producing `undefined` as an operator.
+ */
+const OPERATOR_MAP = new Map([
+    ['eq', sequelize_1.Op.eq],
+    ['ne', sequelize_1.Op.ne],
+    ['gt', sequelize_1.Op.gt],
+    ['gte', sequelize_1.Op.gte],
+    ['lt', sequelize_1.Op.lt],
+    ['lte', sequelize_1.Op.lte],
+    ['in', sequelize_1.Op.in],
+    ['nin', sequelize_1.Op.notIn],
+    ['like', sequelize_1.Op.like],
+    // Only Postgres implements ILIKE; elsewhere it is folded to LIKE below.
+    ['ilike', sequelize_1.Op.iLike],
+    ['between', sequelize_1.Op.between],
+]);
+const LOGICAL_MAP = new Map([
+    ['and', sequelize_1.Op.and],
+    ['or', sequelize_1.Op.or],
+    ['not', sequelize_1.Op.not],
+]);
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Convert a validated `Where` clause into a Sequelize `where` object. */
+function translateWhere(where, dialect = 'postgres') {
+    if (where === undefined)
+        return {};
+    const result = {};
+    // Entries are typed `unknown` deliberately: the clause is validated data from
+    // `parseQuery`, but at runtime it is still a plain object a caller built.
+    for (const [key, value] of Object.entries(where)) {
+        if (value === undefined)
+            continue;
+        const logical = LOGICAL_MAP.get(key);
+        if (logical !== undefined) {
+            result[logical] = Array.isArray(value)
+                ? value.map((clause) => translateWhere(clause, dialect))
+                : translateWhere(value, dialect);
+            continue;
+        }
+        if (!isPlainObject(value)) {
+            // A bare value is equality.
+            result[key] = value;
+            continue;
+        }
+        result[key] = translateCondition(key, value, dialect);
+    }
+    return result;
+}
+function translateCondition(field, condition, dialect) {
+    const translated = {};
+    for (const [operator, operand] of Object.entries(condition)) {
+        if (operator === 'isNull') {
+            translated[operand === true ? sequelize_1.Op.is : sequelize_1.Op.not] = null;
+            continue;
+        }
+        const symbol = OPERATOR_MAP.get(operator);
+        if (symbol === undefined) {
+            // Unreachable through `parseQuery`, which allow-lists operators; this is
+            // the second line of defence for code that builds a clause by hand.
+            throw new core_1.InvalidQueryError({
+                message: `Operator "${operator}" is not supported by the SQL driver`,
+                meta: { field, operator },
+            });
+        }
+        // Only Postgres implements ILIKE; elsewhere the comparison is folded to
+        // LIKE, which most other dialects treat case-insensitively by collation.
+        if (operator === 'ilike' && dialect !== 'postgres') {
+            translated[sequelize_1.Op.like] = operand;
+            continue;
+        }
+        translated[symbol] = operand;
+    }
+    return translated;
+}
+//# sourceMappingURL=where-translator.js.map

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@nage-api/data-sql",
+  "version": "1.0.0-beta.2",
+  "description": "SQL driver for @nage-api/data — Sequelize-backed repository, unit of work and migration store",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nage-api/contracts": "1.0.0-beta.2",
+    "@nage-api/core": "1.0.0-beta.2",
+    "@nage-api/data": "1.0.0-beta.2"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "reflect-metadata": "^0.2.0",
+    "sequelize": "^6.37.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "11.1.29",
+    "@swc/core": "1.15.47",
+    "@types/node": "22.20.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "reflect-metadata": "0.2.2",
+    "rimraf": "6.1.3",
+    "sequelize": "6.37.8",
+    "sqlite3": "6.0.1",
+    "typescript": "5.9.3",
+    "unplugin-swc": "1.5.11",
+    "vitest": "4.1.10",
+    "@nage-api/testing": "1.0.0-beta.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}