litedbmodel 2.1.0 → 2.2.1

package/dist/DBModel.js

@@ -21,6 +21,15 @@ const drivers_2 = require("./drivers");
 const connection_errors_1 = require("./connection-errors");
 // Import LazyRelation module (static import for Vitest compatibility)
 const LazyRelation_1 = require("./LazyRelation");
+// Phase F-2 (#105): the SCP runtime bridge — puts DBModel's pooled execution on the Phase A-E runtime
+// (real tx / reader-writer routing / multi-DB / middleware). Wired for the live pg/mysql dialects;
+// sqlite + an uninitialized handler keep the v1 in-proc path. Every statement — a v1-built SELECT as
+// much as a compiled write bundle — reaches the DB through this ONE ctx seam.
+const dbmodel_runtime_1 = require("./scp/dbmodel-runtime");
+const exec_context_1 = require("./scp/exec-context");
+// The row-lock tail SSoT (` FOR UPDATE` / ` FOR SHARE`) — shared with the SCP `compileSelect`, so the
+// imperative builder and the compiled statement render byte-identical locking clauses.
+const compile_select_1 = require("./scp/makesql/compile-select");
 // AsyncLocalStorage for transaction context
 const transactionContext = new async_hooks_1.AsyncLocalStorage();
 // AsyncLocalStorage for writer context (for withWriter())
@@ -173,6 +182,132 @@ class DBModel {
     };
     /** Last transaction completion time (for writer sticky) */
     static _lastTransactionTime = 0;
+    /**
+     * The Phase A-E SCP runtime context (built lazily from `_dbConfig` for the live pg/mysql dialects).
+     * `null` when not yet built; `false` when the config is sqlite / uninitialized (⇒ v1 in-proc path,
+     * the backward-compat fallback). Rebuilt on `setConfig`. Phase F-2 (#105). @internal
+     */
+    static _scpRuntime = null;
+    /**
+     * The `scpRuntimeGeneration()` a cached `_scpRuntime` was built at. `closeAllPools()` bumps that
+     * generation and closes the pools; a cache from an older generation therefore points at a CLOSED pool
+     * and must be rebuilt on next use (#182). `-1` = never built. @internal
+     */
+    static _scpRuntimeGen = -1;
+    /**
+     * Get the SCP runtime context for this model's config (Phase F-2 / #105), lazily built from
+     * `_dbConfig`. Returns `null` when the model should use the v1 in-proc path (sqlite, or no live
+     * config, or the pg/mysql peer dep is unavailable) — the backward-compat fallback (empty middleware
+     * / single-DB / sqlite behavior unchanged). The routed reader/writer pools, writer-sticky, and the
+     * ctx seam (middleware + tx-pinning) all come from here. @internal
+     */
+    static _getScpRuntime() {
+        if (this._scpRuntime === false)
+            return null;
+        // A cached runtime is reusable only while its pools are still open — i.e. its generation still matches.
+        // After a `closeAllPools()` bumped the generation, the cache points at a closed pool; fall through to
+        // rebuild rather than hand back a runtime whose `acquire()` throws "pool after end" (#182).
+        if (this._scpRuntime !== null && this._scpRuntimeGen === (0, dbmodel_runtime_1.scpRuntimeGeneration)())
+            return this._scpRuntime;
+        const config = this._dbConfig;
+        const driver = config?.driver ?? (config ? 'postgres' : undefined);
+        if (config === null || driver === 'sqlite' || driver === undefined) {
+            this._scpRuntime = false;
+            return null;
+        }
+        try {
+            const rt = (0, dbmodel_runtime_1.buildContextFromConfig)({
+                ...(config.host !== undefined ? { host: config.host } : {}),
+                ...(config.port !== undefined ? { port: config.port } : {}),
+                ...(config.database !== undefined ? { database: config.database } : {}),
+                ...(config.user !== undefined ? { user: config.user } : {}),
+                ...(config.password !== undefined ? { password: config.password } : {}),
+                ...(config.max !== undefined ? { max: config.max } : {}),
+                ...(config.keepAlive !== undefined ? { keepAlive: config.keepAlive } : {}),
+                ...(config.keepAliveInitialDelayMillis !== undefined ? { keepAliveInitialDelayMillis: config.keepAliveInitialDelayMillis } : {}),
+                driver: driver,
+            }, {
+                ...(this._configOptions.writerConfig !== undefined ? { writerConfig: this._configOptions.writerConfig } : {}),
+                ...(this._configOptions.useWriterAfterTransaction !== undefined ? { useWriterAfterTransaction: this._configOptions.useWriterAfterTransaction } : {}),
+                ...(this._configOptions.writerStickyDuration !== undefined ? { writerStickyDuration: this._configOptions.writerStickyDuration } : {}),
+            });
+            this._scpRuntime = rt;
+            this._scpRuntimeGen = (0, dbmodel_runtime_1.scpRuntimeGeneration)();
+            return rt;
+        }
+        catch {
+            // The pg/mysql peer dep is unavailable (or pool construction failed) — fall back to the v1 path.
+            this._scpRuntime = false;
+            return null;
+        }
+    }
+    /**
+     * Reset the cached SCP runtime (called on `setConfig`). This clears the CACHE only; it does not close
+     * the displaced runtime's pools, because `setConfig` is synchronous and closing is not.
+     *
+     * It used to say the caller closed them. It did not — `setConfig` only called this — so every
+     * reconfigure leaked a routed pool set with no handle left to reach it. The displaced runtime stays in
+     * `dbmodel-runtime`'s own registry and is closed by `closeAllPools()`. @internal
+     */
+    static _resetScpRuntime() {
+        this._scpRuntime = null;
+    }
+    /** Cached §4.1 column-type overrides for the SCP read/write bundle (per class). @internal */
+    static _scpColumnTypesCache = new WeakMap();
+    /**
+     * The §4.1 column-type OVERRIDES for the SCP read/write bundle (the F1 `columnTypes` escape hatch).
+     * Phase F-2 (#105): a column whose SQL type cannot be derived from the decorator — no explicit
+     * `sqlCast` family AND no `baseSqlType` (its TS `design:type` is `Object`, e.g. a NULLABLE
+     * `string | null` / `number | null` field: TS emits `design:type = Object` for a union) — would
+     * otherwise take the blanket-INTEGER default and THROW `materialize int32` on a live string. Because
+     * the DBModel read path does its OWN v1 de-box (`_createInstance` → `typeCastFromDB`), the SCP typed
+     * read only needs a NON-THROWING, passthrough-safe SQL type for such columns: we pin them to `TEXT`
+     * (passthrough — the driver value flows through unchanged, then v1 casts it). Columns WITH a derivable
+     * type (explicit family / a non-union `design:type`) keep it. This preserves the v1 read contract
+     * exactly (int→number, string→string) while never throwing on an undeterminable nullable column.
+     * @internal
+     */
+    static _scpColumnTypes() {
+        const cached = DBModel._scpColumnTypesCache.get(this);
+        if (cached !== undefined)
+            return cached;
+        const meta = (0, decorators_1.getColumnMeta)(this);
+        const columnTypes = {};
+        if (meta !== undefined) {
+            for (const [propKey, m] of meta) {
+                const baseSqlType = m.baseSqlType;
+                // A column with an EXPLICIT `@column.*` family (`sqlCast`: boolean / bigint / uuid / jsonb /
+                // date / timestamp / *Array) keeps its derived SQL type — that family de-box matches v1's.
+                if (m.sqlCast !== undefined)
+                    continue;
+                // A bare `@column()` whose TS `design:type` is String / Boolean / Date / BigInt has an
+                // UNAMBIGUOUS SQL type (option B: TEXT / BOOLEAN / TIMESTAMP / BIGINT) — keep it, so the SCP
+                // typed de-box fires exactly as the v1 contract (string→string, bool→boolean, …).
+                if (baseSqlType !== undefined && baseSqlType !== 'INTEGER')
+                    continue;
+                // What remains is a bare `Number` (baseSqlType INTEGER) — AMBIGUOUS: it may back an INTEGER or a
+                // DECIMAL/NUMERIC column (pg returns DECIMAL as a string that `int32` materialize would REJECT)
+                // — OR a union field with NO `design:type` (string|null). Pin these to `TEXT` = passthrough:
+                // the DBModel path does its OWN v1 de-box (`_createInstance` → `typeCastFromDB`), so the SCP
+                // read only needs a NON-THROWING passthrough (int→number, decimal→number, string→string — the
+                // exact v1 read contract). This is F1's `columnTypes` escape hatch for the un-derivable number.
+                columnTypes[propKey] = 'TEXT';
+            }
+        }
+        const result = { columnTypes };
+        DBModel._scpColumnTypesCache.set(this, result);
+        return result;
+    }
+    /**
+     * Is the SCP execution path usable RIGHT NOW? The v1 method/SQL middleware system
+     * (`src/Middleware.ts` + `DBModel.use`) is a SEPARATE registry from the SCP middleware chain, so a
+     * registered v1 middleware must keep the v1 execute path (its `execute`/method hooks fire exactly as
+     * before — backward-compat). With NO v1 middleware, the SCP path (routing/tx via the ctx seam, plus
+     * the SCP middleware chain for `src/scp` `use()`) drives execution. Phase F-2 (#105). @internal
+     */
+    static _scpUsable() {
+        return DBModel._middlewares.length === 0;
+    }
     /**
      * Initialize DBModel with database config.
      * Call this once at application startup.
@@ -217,6 +352,11 @@ class DBModel {
             ...this._configOptions,
             ...options,
         };
+        // Phase F-2 (#105): drop the cached SCP runtime so the next op rebuilds it from the new config
+        // (new reader/writer pools + routing). The v1 DBHandler above still owns its own pools (used by
+        // the v1 fallback path + tx-context bridging); the SCP runtime owns the routed pools for the
+        // SCP execution path. Rebuilt lazily on first use.
+        this._resetScpRuntime();
     }
     /**
      * Get current limit configuration.
@@ -557,9 +697,9 @@ class DBModel {
         if (options.offset !== undefined) {
             sql += ` OFFSET ${options.offset}`;
         }
-        if (options.forUpdate) {
-            sql += ' FOR UPDATE';
-        }
+        // Row lock (` FOR UPDATE` / ` FOR SHARE`) — rendered by the ONE `lockTail` aggregation point the
+        // SCP `compileSelect` also consumes, so the imperative and the compiled text cannot drift.
+        sql += (0, compile_select_1.lockTail)(options);
         if (options.append) {
             sql += ` ${options.append}`;
         }
@@ -640,10 +780,30 @@ class DBModel {
      * Build SELECT SQL and execute via query()
      * @internal
      */
-    static _select(conditions, options = {}) {
+    static async _select(conditions, options = {}) {
+        // A `find` shape is only known PER REQUEST (`{where:{age:{gt:x}}}`), so it is built imperatively —
+        // compile-free — by the v1 builder. It still reaches the DB through the SCP ctx seam: `query` →
+        // `execute` → `_scpRawExecute`, so routing, middleware and an ambient transaction pin all apply.
         const { sql, params } = this._buildSelectSQL(conditions, options);
         return this.query(sql, params);
     }
+    /** Merge FIND_FILTER (the model's default filter) into a condition object (v1 `_buildSelectSQL` parity). */
+    static _mergeFindFilter(conditions) {
+        if (!this.FIND_FILTER)
+            return conditions;
+        const filter = (0, Column_1.condsToRecord)(this.FIND_FILTER);
+        return { ...conditions, ...filter };
+    }
+    /** Build model instances from raw rows, wiring the deferred relation context (v1 `query` parity). @internal */
+    static _instancesFromRows(rows) {
+        const instances = rows.map((row) => this._createInstance(row));
+        if (instances.length > 1) {
+            const deferredRef = [this, instances];
+            for (const inst of instances)
+                inst._deferredContext = deferredRef;
+        }
+        return instances;
+    }
     /**
      * Select for lazy relation loading.
      * Applies hasManyHardLimit check and supports CTE/raw conditions.
@@ -812,7 +972,48 @@ class DBModel {
         const onConflictUpdateCols = options.onConflictUpdate === 'all'
             ? 'all'
             : options.onConflictUpdate?.map(toColName);
-        // Execute INSERT for each group
+        // Phase F-2 (#105): route the INSERT through the SCP batch-write bundle (compileCreateBundle →
+        // executeTransactionAsync on the writer, write=tx guard). `compileInsertMany` reproduces the v1
+        // `buildInsert` byte-for-byte (per the parity rule), so the executed SQL is identical; onConflict*
+        // ride the build options unchanged. The legacy raw `conflict` string (no structured onConflict) is
+        // NOT modeled in the SCP builder — that rare path keeps the v1 execute loop below. Requires the
+        // rows to be a SINGLE column-pattern group (the common case); a heterogeneous multi-pattern insert
+        // and the legacy conflict path fall through to the v1 loop.
+        const rt = this._getScpRuntime();
+        const singleGroup = groupedByPattern.size === 1 ? [...groupedByPattern.values()][0] : undefined;
+        if (rt !== null &&
+            this._scpUsable() &&
+            singleGroup !== undefined &&
+            !(options.conflict && !options.onConflict)) {
+            // The SCP MySQL batch INSERT wraps values in a JSON array (`json_each`), so a Date value would
+            // be JSON-serialized to an ISO string (`…T…Z`) that MySQL's `CAST(… AS DATETIME)` rejects. The v1
+            // direct-param path passes a Date object (mysql2 formats it). For the batch/JSON path, pre-format
+            // any Date to the MySQL `YYYY-MM-DD HH:MM:SS.mmm` string the CAST accepts (PG/SQLite pass Date
+            // straight through their own binding, so this is mysql-only). Phase F-2 (#105).
+            const scpRecords = rt.dialect === 'mysql' ? singleGroup.records.map((r) => this._mysqlDateStrings(r)) : singleGroup.records;
+            const bundle = (0, dbmodel_runtime_1.compileCreateBundle)(this, 'create', {
+                tableName,
+                records: scpRecords,
+                rawRecords: singleGroup.rawRecords,
+                sqlCastMap,
+                ...(onConflictCols !== undefined ? { onConflict: onConflictCols } : {}),
+                ...(options.onConflictIgnore !== undefined ? { onConflictIgnore: options.onConflictIgnore } : {}),
+                ...(onConflictUpdateCols !== undefined ? { onConflictUpdate: onConflictUpdateCols } : {}),
+                ...(options.returning !== undefined ? { returning: options.returning } : {}),
+                // The model's PK travels with the write so a dialect without native RETURNING can recover
+                // the rows it wrote by the REAL key — the auto-increment range, or the values the write
+                // itself bound (UUID / client-supplied / composite). Omitting it is what made those
+                // models silently return no rows.
+                pk: (() => {
+                    const k = (0, decorators_1.getPrimaryKey)(this);
+                    return { columns: k.columns, autoInc: k.autoInc };
+                })(),
+            }, rt.dialect, this._scpColumnTypes());
+            const result = await (0, dbmodel_runtime_1.executeWriteAsync)(bundle, {}, rt);
+            const rows = this._writeResultRows(result);
+            return rows.map((row) => this._createInstance(row));
+        }
+        // Execute INSERT for each group (v1 path — heterogeneous patterns / legacy conflict / v1 fallback).
         const allResults = [];
         for (const { columns, records: groupRecords, rawRecords: groupRawRecords } of groupedByPattern.values()) {
             // Use SqlBuilder to build the INSERT SQL
@@ -925,6 +1126,56 @@ class DBModel {
         instance.typeCastFromDB();
         return instance;
     }
+    /**
+     * Route a raw `(sql, params)` through the SCP ctx seam (the escape-hatch / Fragment path). A
+     * SELECT / …RETURNING / WITH / VALUES / SHOW / PRAGMA runs the READ seam (reader routing / an
+     * ambient tx pin); any other statement the WRITE seam (writer routing / the tx pin). The seam
+     * applies the SCP middleware chain + connection routing; inside a SCP `transaction(fn)` the ALS pin
+     * resolves the tx connection so the statement joins the transaction. Phase F-2 (#105). @internal
+     */
+    static async _scpRawExecute(sql, params, rt) {
+        const ctx = rt.ctx;
+        // v1-built SQL uses `?` placeholders; the SCP seam passes SQL verbatim, so renumber `?`→`$N` for
+        // postgres (mysql keeps `?`) — the conversion v1's DBHandler did on the imperative path.
+        const rendered = (0, dbmodel_runtime_1.renderRawSql)(sql, rt.dialect);
+        const returnsRows = /^\s*(select|with|show|pragma|values|explain|table)\b/i.test(rendered) || /\breturning\b/i.test(rendered);
+        if (returnsRows) {
+            return (0, exec_context_1.executeAsync)(ctx, rendered, params, { write: false });
+        }
+        await (0, exec_context_1.runAsync)(ctx, rendered, params, { write: true });
+        return [];
+    }
+    /**
+     * Convert any `Date` value in a record to the MySQL `YYYY-MM-DD HH:MM:SS.mmm` string (server-local
+     * wall-clock, matching mysql2's own Date→DATETIME formatting) so it survives the SCP MySQL batch
+     * INSERT's JSON-array round-trip + `CAST(… AS DATETIME)`. Non-Date values pass through. @internal
+     */
+    static _mysqlDateStrings(record) {
+        let out;
+        for (const [k, v] of Object.entries(record)) {
+            if (v instanceof Date) {
+                if (out === undefined)
+                    out = { ...record };
+                const p = (n, w = 2) => String(n).padStart(w, '0');
+                out[k] = `${v.getFullYear()}-${p(v.getMonth() + 1)}-${p(v.getDate())} ${p(v.getHours())}:${p(v.getMinutes())}:${p(v.getSeconds())}.${p(v.getMilliseconds(), 3)}`;
+            }
+        }
+        return out ?? record;
+    }
+    /**
+     * Flatten a SCP {@link executeWriteAsync} result (a `TransactionResult`) into the RETURNING rows the
+     * v1 write path returns: a batch write exposes every group's rows via `returnedRows`; a single-write
+     * Command exposes its one row via `entity`. A non-returning write yields `[]`. Phase F-2 (#105). @internal
+     */
+    static _writeResultRows(result) {
+        if (result.returnedRows !== undefined) {
+            const out = [];
+            for (const group of result.returnedRows)
+                out.push(...group);
+            return out;
+        }
+        return result.entity !== null ? [result.entity] : [];
+    }
     /**
      * Build PkeyResult from rows containing primary key values
      * @internal
@@ -1118,44 +1369,38 @@ class DBModel {
     /** Cache for primary key columns detected from @column({ primaryKey: true }) */
     static _pkeyColumnsCache = new WeakMap();
     /**
-     * Get primary key columns with fallback to ['id']
-     * Priority: 1. PKEY_COLUMNS getter  2. @column({ primaryKey: true })  3. 'id' default
+     * The primary key as v1 `Column` objects. WHICH columns those are is resolved by the ONE
+     * derivation ({@link getPrimaryKey}, in the layer that owns column metadata); this method only
+     * maps that answer onto the `Column` statics the imperative builders bind against.
      * @internal
      */
     static _getPkeyColumnsWithDefault() {
-        // 1. Explicit PKEY_COLUMNS takes precedence
+        // 1. Explicit PKEY_COLUMNS takes precedence — already Column objects.
         if (this.PKEY_COLUMNS) {
             return this.PKEY_COLUMNS;
         }
-        // 2. Check cache for decorator-detected primary keys
         const cached = DBModel._pkeyColumnsCache.get(this);
         if (cached) {
             return cached;
         }
-        // 3. Detect from @column({ primaryKey: true }) decorator
-        const meta = (0, decorators_1.getColumnMeta)(this);
-        if (meta) {
-            const pkeyColumns = [];
+        const pkey = (0, decorators_1.getPrimaryKey)(this);
+        let pkeyColumns = [];
+        if (pkey.declared) {
+            // The declared PK: take each property's static Column (a callable carrying `columnName`).
             const thisClass = this;
-            for (const [propKey, colMeta] of meta) {
-                if (colMeta.primaryKey) {
-                    // Get the static Column property from the class
-                    // Note: Column is a callable function, so typeof is 'function', not 'object'
-                    const col = thisClass[propKey];
-                    if (col && typeof col === 'function' && 'columnName' in col) {
-                        pkeyColumns.push(col);
-                    }
+            for (const propKey of pkey.propKeys) {
+                const col = thisClass[propKey];
+                if (col && typeof col === 'function' && 'columnName' in col) {
+                    pkeyColumns.push(col);
                 }
             }
-            if (pkeyColumns.length > 0) {
-                DBModel._pkeyColumnsCache.set(this, pkeyColumns);
-                return pkeyColumns;
-            }
         }
-        // 4. Default: create a Column for 'id'
-        const defaultPkey = [(0, Column_1.createColumn)('id', this.TABLE_NAME, this.name)];
-        DBModel._pkeyColumnsCache.set(this, defaultPkey);
-        return defaultPkey;
+        if (pkeyColumns.length === 0) {
+            // The legacy default (or a declared PK with no matching Column static): synthesize it.
+            pkeyColumns = pkey.columns.map((c) => (0, Column_1.createColumn)(c, this.TABLE_NAME, this.name));
+        }
+        DBModel._pkeyColumnsCache.set(this, pkeyColumns);
+        return pkeyColumns;
     }
     /**
      * Get GROUP BY clause as string
@@ -2168,6 +2413,17 @@ class DBModel {
             sql = sqlOrFragment;
         }
         const core = async (s, p) => {
+            // Phase F-2 (#105): the ESCAPE-HATCH / Fragment path through the SCP ctx seam. When the SCP
+            // runtime is active (and no v1 middleware), route raw execute/query THROUGH the seam so an
+            // ambient SCP transaction pin (the tx connection), reader/writer routing, and the SCP middleware
+            // chain all apply — the SAME central point every SCP-generated statement uses. A SELECT/RETURNING
+            // runs the read seam; any other statement the write seam (writer routing). This is what lets a v1
+            // -fallback op (CTE / QUERY view / updateMany / findById) join a `transaction(fn)` correctly.
+            const rt = this._getScpRuntime();
+            if (rt !== null && this._scpUsable()) {
+                const rows = await this._scpRawExecute(s, p || [], rt);
+                return { rows, rowCount: rows.length };
+            }
             const handler = this.getHandler();
             // Use writer pool if in withWriter context or writer sticky period
             const useWriter = this._getWriterContext().getStore() !== undefined || this._shouldUseWriterSticky();
@@ -2271,6 +2527,29 @@ class DBModel {
             // Already in a transaction, just execute the function
             return func();
         }
+        // Phase F-2 (#105): when the SCP runtime is active (and no v1 middleware), open the transaction on
+        // the SCP tx runtime (`scpTransaction` — one owned pooled connection pinned in the SCP ALS, the
+        // isolation-aware BEGIN/COMMIT + #81 retry). Every op inside `func` joins it: an SCP write via
+        // `executeWriteAsync` (its `executeTransactionAsync` sees the ambient pin → no new BEGIN), an SCP
+        // read / a v1-fallback `execute()` via the SCP seam (the ALS pin resolves the tx connection). We
+        // ALSO set the v1 `transactionContext` marker (a sentinel connection) so v1 code that checks
+        // `inTransaction()` / `_checkWriteAllowed` / `getCurrentConnection()` still sees an active tx.
+        const rt = this._getScpRuntime();
+        if (rt !== null && this._scpUsable()) {
+            const useWriterAfterTx = options.useWriterAfterTransaction ?? this._configOptions.useWriterAfterTransaction ?? true;
+            const result = await (0, exec_context_1.transaction)(rt.ctx, () => {
+                // Set the v1 tx marker for the duration of the body (same async scope as the SCP pin). The
+                // sentinel connection is never used for I/O — v1-fallback ops route through the SCP seam.
+                const sentinel = {
+                    query: async () => ({ rows: [], rowCount: 0 }),
+                    release: () => undefined,
+                };
+                return txContext.run({ connection: sentinel }, func);
+            }, options, rt.dialect);
+            if (useWriterAfterTx && !(options.rollbackOnly ?? false))
+                this._lastTransactionTime = Date.now();
+            return result;
+        }
         // Get handler
         const handler = this.getHandler();
         const retryOnError = options.retryOnError ?? true;
@@ -2477,6 +2756,10 @@ class DBModel {
                 ...options,
             };
             static _lastTransactionTime = 0;
+            // Phase F-2 (#105): this base class gets its OWN SCP runtime slot (built lazily from ITS config),
+            // isolated from DBModel's default-config runtime and from other base classes — otherwise a
+            // sqlite/mysql base would inherit DBModel's shared pg runtime and route its SQL to the wrong DB.
+            static _scpRuntime = null;
             // Override to use this base class's transaction context
             static _getTransactionContext() {
                 return baseTransactionContext;