turbine-orm 0.32.0 → 0.32.1

package/dist/query/builder.js

@@ -20,6 +20,105 @@ import { assertBindableEqualsOperand, findArrayUniqueKey, findJsonUniqueKey, fin
 import { escapeLike, LRUCache, OPERATOR_KEYS, parseDbDate, sqlToPreparedName } from './utils.js';
 /** Relations already warned about missing FK indexes (once per process, dev only). */
 const unindexedRelationWarned = new Set();
+/**
+ * Dev-mode SQL-cache lockstep cross-check gate.
+ *
+ * The SQL template cache requires three code paths to enumerate where-clause
+ * keys identically: `fingerprintWhere` (builds the cache key),
+ * `buildWhereClause` (builds SQL + `$N` params on a MISS), and
+ * `collectWhereParams` (re-collects params on a HIT without rebuilding). They
+ * are synchronized only by convention, and drift has shipped silent
+ * wrong-results bugs before (permuted where-key order; an orderBy fingerprint
+ * collision). This check catches such drift loudly the moment a cache HIT
+ * happens by rebuilding the SQL + params fresh and comparing them against what
+ * the cache-hit path produced.
+ *
+ * Enabled only when `NODE_ENV !== 'production'` (same convention as the other
+ * dev-only guards in this file) AND `TURBINE_DISABLE_CACHE_CHECK !== '1'`. The
+ * env vars are read inline (not captured once) so tests and perf-sensitive dev
+ * traffic can toggle them per process. In production the check never runs, so
+ * the hot path is unchanged.
+ */
+function cacheCrossCheckEnabled() {
+    return process.env.NODE_ENV !== 'production' && process.env.TURBINE_DISABLE_CACHE_CHECK !== '1';
+}
+/**
+ * Strict structural equality for a single SQL parameter value. Handles the
+ * value shapes Turbine binds: primitives (incl. `NaN` and `bigint`), `null`/
+ * `undefined`, `Date` (by time), `Buffer`/typed arrays (by bytes), arrays
+ * (`in` lists, pgvector arrays), and plain objects (JSON filter payloads).
+ */
+function cacheParamValueEqual(a, b) {
+    if (a === b)
+        return true; // identical ref or equal primitive (covers matching null/undefined)
+    if (a === null || b === null || a === undefined || b === undefined)
+        return false;
+    const ta = typeof a;
+    if (ta !== typeof b)
+        return false;
+    if (ta !== 'object') {
+        // Primitives that failed `===`: only NaN is legitimately "equal" to itself.
+        return typeof a === 'number' && Number.isNaN(a) && Number.isNaN(b);
+    }
+    if (a instanceof Date || b instanceof Date) {
+        return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+    }
+    const aView = ArrayBuffer.isView(a);
+    const bView = ArrayBuffer.isView(b);
+    if (aView || bView) {
+        if (!aView || !bView)
+            return false;
+        const ua = a;
+        const ub = b;
+        if (ua.byteLength !== ub.byteLength)
+            return false;
+        const va = new Uint8Array(ua.buffer, ua.byteOffset, ua.byteLength);
+        const vb = new Uint8Array(ub.buffer, ub.byteOffset, ub.byteLength);
+        for (let i = 0; i < va.length; i++) {
+            if (va[i] !== vb[i])
+                return false;
+        }
+        return true;
+    }
+    const aArr = Array.isArray(a);
+    const bArr = Array.isArray(b);
+    if (aArr || bArr) {
+        if (!aArr || !bArr)
+            return false;
+        const arrA = a;
+        const arrB = b;
+        if (arrA.length !== arrB.length)
+            return false;
+        for (let i = 0; i < arrA.length; i++) {
+            if (!cacheParamValueEqual(arrA[i], arrB[i]))
+                return false;
+        }
+        return true;
+    }
+    const objA = a;
+    const objB = b;
+    const keysA = Object.keys(objA);
+    const keysB = Object.keys(objB);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const k of keysA) {
+        if (!Object.hasOwn(objB, k))
+            return false;
+        if (!cacheParamValueEqual(objA[k], objB[k]))
+            return false;
+    }
+    return true;
+}
+/** Element-wise strict equality of two SQL parameter arrays. */
+function cacheParamsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (!cacheParamValueEqual(a[i], b[i]))
+            return false;
+    }
+    return true;
+}
 // biome-ignore lint/complexity/noBannedTypes: {} means "no relations known" — intentional for untyped table access
 export class QueryInterface {
     pool;
@@ -28,6 +127,15 @@ export class QueryInterface {
     tableMeta;
     /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
     sqlTemplateCache = new LRUCache(1000);
+    /**
+     * Whether the most recent {@link acquireSql} call was a cache HIT. Read by
+     * {@link crossCheckCache} to decide whether to run the dev-mode lockstep
+     * cross-check. Safe as a single mutable flag: each `build*()` method calls
+     * `acquireSql` then `crossCheckCache` synchronously with no intervening
+     * `await` and no re-entrant `acquireSql` (relation subqueries are built
+     * inline, not through the top-level cache).
+     */
+    lastCacheHit = false;
     middlewares;
     defaultLimit;
     warnOnUnlimited;
@@ -346,24 +454,84 @@ export class QueryInterface {
      * On hit, increments counters and returns the cached entry.
      *
      * When `sqlCache` is disabled, always calls `build()` without caching.
+     *
+     * `build` receives a fresh `$N` param scratch array. On a miss those params
+     * are discarded (the returned params come from each call site's dedicated
+     * collect path); the array exists so the build path can number placeholders
+     * via `params.length` exactly as it does today. On a HIT, `build` is skipped
+     * here but re-run by {@link crossCheckCache} (dev only) with a fresh array to
+     * verify the collect path stayed in lockstep with the build path.
+     *
+     * Sets {@link lastCacheHit} so the caller's `crossCheckCache` knows whether a
+     * cross-check is warranted.
      */
     acquireSql(cacheKey, build) {
         if (!this.sqlCacheEnabled) {
-            const sql = build();
+            this.lastCacheHit = false;
+            const sql = build([]);
             this.cacheMisses++;
             return { sql, name: sqlToPreparedName(sql) };
         }
         const cached = this.sqlTemplateCache.get(cacheKey);
         if (cached) {
             this.cacheHits++;
+            this.lastCacheHit = true;
             return cached;
         }
-        const sql = build();
+        this.lastCacheHit = false;
+        const sql = build([]);
         const entry = { sql, name: sqlToPreparedName(sql) };
         this.sqlTemplateCache.set(cacheKey, entry);
         this.cacheMisses++;
         return entry;
     }
+    /**
+     * Dev-mode SQL-cache lockstep cross-check (see {@link cacheCrossCheckEnabled}).
+     *
+     * Runs only when the most recent {@link acquireSql} was a cache HIT and the
+     * check is enabled. Rebuilds the SQL + `$N` params fresh via the same `build`
+     * closure the caller passed to `acquireSql`, then compares:
+     *   (a) the cached SQL string byte-for-byte against the fresh SQL, and
+     *   (b) the params the cache-hit collect path produced against the fresh
+     *       build-path params (length and element-wise strict deep-equal).
+     *
+     * A mismatch means the fingerprint / build / collect paths have drifted out
+     * of lockstep (the exact class of bug that has silently corrupted results
+     * before), so it throws a {@link ValidationError} (E003) naming the
+     * fingerprint, the operation, and both SQL strings (truncated). Failing loud
+     * in dev/test is the point. Production never reaches the comparison.
+     *
+     * @param op human label of the calling build method (for the error message).
+     * @param cacheKey the cache fingerprint that HIT.
+     * @param entry the cached SQL entry that will be executed.
+     * @param build the same closure passed to `acquireSql`; re-run here to
+     *   capture the fresh build-path SQL + params.
+     * @param collectedParams the params the caller's collect path produced.
+     */
+    crossCheckCache(op, cacheKey, entry, build, collectedParams) {
+        if (!this.lastCacheHit)
+            return;
+        if (!cacheCrossCheckEnabled())
+            return;
+        const freshParams = [];
+        const freshSql = build(freshParams);
+        const sqlOk = freshSql === entry.sql;
+        const paramsOk = cacheParamsEqual(collectedParams, freshParams);
+        if (sqlOk && paramsOk)
+            return;
+        const truncate = (s) => (s.length > 300 ? `${s.slice(0, 300)}… (${s.length} chars total)` : s);
+        const details = [];
+        if (!sqlOk) {
+            details.push(`cached SQL and freshly-built SQL diverge:\n  cached = <${truncate(entry.sql)}>\n  fresh  = <${truncate(freshSql)}>`);
+        }
+        if (!paramsOk) {
+            details.push(`cache-hit params and freshly-built params diverge (collected ${collectedParams.length}, built ${freshParams.length})`);
+        }
+        throw new ValidationError(`[turbine] SQL cache lockstep violation on ${op} (fingerprint "${cacheKey}"). ` +
+            `This is a Turbine internal invariant violation, please report it at ` +
+            `https://github.com/zvndev/turbine-orm/issues. The fingerprint, SQL-build, and ` +
+            `param-collect paths must enumerate where-clause keys identically.\n${details.join('\n')}`);
+    }
     /**
      * Reset the per-instance unlimited-query warning dedupe set.
      * Exposed for tests so a single test process can verify the warning fires
@@ -562,19 +730,22 @@ export class QueryInterface {
             });
         // Simple path: plain equality, no operators/null/OR
         if (!args.with && isSimpleWhere) {
-            const entry = this.acquireSql(ck, () => {
+            const buildSql = (freshParams) => {
                 const qt = this.q(this.table);
-                const tempParams = whereKeys.map((k) => whereObj[k]);
-                const whereClauses = whereKeys.map((k, i) => `${this.toSqlColumn(k)} = ${this.p(i + 1)}`);
+                const whereClauses = whereKeys.map((k, i) => {
+                    freshParams.push(whereObj[k]);
+                    return `${this.toSqlColumn(k)} = ${this.p(i + 1)}`;
+                });
                 const whereSql = whereClauses.length > 0 ? ` WHERE ${whereClauses.join(' AND ')}` : '';
                 const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${this.q(c)}`).join(', ') : `${qt}.*`;
-                void tempParams; // params are positional, SQL is value-invariant
                 return `SELECT ${selectExpr} FROM ${qt}${whereSql}${this.limitOneClause()}`;
-            });
+            };
+            const entry = this.acquireSql(ck, buildSql);
             // Collect params (same order as build)
             for (const k of whereKeys) {
                 params.push(whereObj[k]);
             }
+            this.crossCheckCache('findUnique', ck, entry, buildSql, params);
             return {
                 sql: entry.sql,
                 params,
@@ -588,16 +759,17 @@ export class QueryInterface {
         }
         // General path (with operators, null, OR, with clause)
         if (!args.with) {
-            const entry = this.acquireSql(ck, () => {
-                const freshParams = [];
+            const buildSql = (freshParams) => {
                 const clause = this.buildWhereClause(whereObj, freshParams);
                 const whereSql = clause ? ` WHERE ${clause}` : '';
                 const qt = this.q(this.table);
                 const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${this.q(c)}`).join(', ') : `${qt}.*`;
                 return `SELECT ${selectExpr} FROM ${qt}${whereSql}${this.limitOneClause()}`;
-            });
+            };
+            const entry = this.acquireSql(ck, buildSql);
             // Collect params
             this.collectWhereParams(whereObj, params);
+            this.crossCheckCache('findUnique', ck, entry, buildSql, params);
             return {
                 sql: entry.sql,
                 params,
@@ -614,16 +786,17 @@ export class QueryInterface {
         //   1. buildWhere pushes where params
         //   2. buildSelectWithRelations pushes relation params to same array
         // We must preserve this exact order.
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             const selectClause = this.buildSelectWithRelations(this.table, args.with, freshParams, columnsList);
             return `SELECT ${selectClause} FROM ${this.q(this.table)}${whereSql}${this.limitOneClause()}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         // Collect params in exact build order: where first, then with-clause relations
         this.collectWhereParams(whereObj, params);
         this.collectWithParams(args.with, params);
+        this.crossCheckCache('findUnique', ck, entry, buildSql, params);
         const parseWith = this.makeNestedParser(args.with);
         return {
             sql: entry.sql,
@@ -688,7 +861,7 @@ export class QueryInterface {
         if (this.warnedTables.has(this.table))
             return;
         this.warnedTables.add(this.table);
-        console.warn(`[turbine] warning: findMany on "${this.table}" has no limit — this will fetch every row. ` +
+        console.warn(`[turbine] warning: findMany on "${this.table}" has no limit: this will fetch every row. ` +
             'Pass `limit`, or silence with `warnOnUnlimited: false` (per call, per table, or in config).');
     }
     /**
@@ -745,15 +918,24 @@ export class QueryInterface {
                 .sort()
                 .join(',')
             : '';
-        const distinctFp = args?.distinct ? args.distinct.slice().sort().join(',') : '';
+        // distinct must fingerprint in USER order: the SQL emits `DISTINCT ON` in
+        // the caller's column order, so a permuted array rebuilds different SQL and
+        // must not collapse onto the same cache entry (would trip the cross-check).
+        const distinctFp = args?.distinct ? args.distinct.join(',') : '';
         const effectiveLimit = args?.take ?? args?.limit ?? this.defaultLimit;
-        const limitFp = effectiveLimit !== undefined ? '1' : '0';
-        const offsetFp = args?.offset !== undefined ? '1' : '0';
+        // On engines that inline the literal LIMIT/OFFSET into the SQL text
+        // (dialect.inlineLimitOffset, MySQL), the value is part of the SQL, not the
+        // params, so it MUST be part of the fingerprint or two different limits share
+        // one cached statement (silent wrong row counts). Parameterized engines
+        // (PG/SQLite/SQL Server, whose buildLimitOffset uses placeholders) keep the
+        // presence-only fingerprint so the cache is not needlessly fragmented.
+        const inlinePagination = this.dialect.inlineLimitOffset === true;
+        const limitFp = effectiveLimit !== undefined ? (inlinePagination ? `v${effectiveLimit}` : '1') : '0';
+        const offsetFp = args?.offset !== undefined ? (inlinePagination ? `v${args.offset}` : '1') : '0';
         const ck = `fm:${whereFp}|c=${colKey}|o=${orderFp}|l=${limitFp}|off=${offsetFp}|cur=${cursorFp}|d=${distinctFp}|w=${withFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            // Fresh build — generates SQL and populates freshParams
-            const freshParams = [];
+        const buildSql = (freshParams) => {
+            // Fresh build: generates SQL and populates freshParams
             const { sql: freshWhereSql } = hasWhere
                 ? (() => {
                     const clause = this.buildWhereClause(whereObj, freshParams);
@@ -833,7 +1015,8 @@ export class QueryInterface {
             }
             sql += this.buildPagination(limitPh, offsetPh, !!args?.orderBy);
             return sql;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         // Collect params in exact build order:
         // 1. WHERE params (includes the AND-merged global filter, if any)
         if (hasWhere) {
@@ -864,6 +1047,7 @@ export class QueryInterface {
         if (args?.offset !== undefined && !this.dialect.inlineLimitOffset) {
             params.push(Number(args.offset));
         }
+        this.crossCheckCache('findMany', ck, entry, buildSql, params);
         // Build the row parser once (positional shapes are computed here, not per row).
         const parseWith = args?.with ? this.makeNestedParser(args.with) : null;
         return {
@@ -1189,8 +1373,7 @@ export class QueryInterface {
         const whereFp = this.fingerprintWhere(whereObj);
         const ck = lock ? null : `u:${setFp}|${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const buildSql = () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const setEntries = Object.entries(dataObj).filter(([, v]) => v !== undefined);
             const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, freshParams));
             if (lock) {
@@ -1214,13 +1397,15 @@ export class QueryInterface {
         };
         let sql;
         let preparedName;
+        let cacheEntry;
         if (ck) {
-            const entry = this.acquireSql(ck, buildSql);
-            sql = entry.sql;
-            preparedName = entry.name;
+            cacheEntry = this.acquireSql(ck, buildSql);
+            sql = cacheEntry.sql;
+            preparedName = cacheEntry.name;
         }
         else {
-            sql = buildSql();
+            // optimisticLock path: value-variant version check → uncacheable, no cross-check.
+            sql = buildSql([]);
         }
         // Collect params: SET first, then WHERE, then version check (same order as fresh build)
         this.collectSetParams(dataObj, params);
@@ -1228,6 +1413,9 @@ export class QueryInterface {
         if (lock) {
             params.push(lock.expected);
         }
+        if (ck && cacheEntry) {
+            this.crossCheckCache('update', ck, cacheEntry, buildSql, params);
+        }
         return {
             sql,
             params,
@@ -1359,8 +1547,7 @@ export class QueryInterface {
         const whereFp = this.fingerprintWhere(whereObj);
         const ck = `d:${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             // SQL Server injects `OUTPUT DELETED.*` between `DELETE FROM <t>` and WHERE;
@@ -1368,8 +1555,10 @@ export class QueryInterface {
             return this.dialect.buildDeleteStatement
                 ? this.dialect.buildDeleteStatement({ table: this.q(this.table), whereSql, returning: '*' })
                 : `DELETE FROM ${this.q(this.table)}${whereSql}${this.dialect.buildReturningClause('*')}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         this.collectWhereParams(whereObj, params);
+        this.crossCheckCache('delete', ck, entry, buildSql, params);
         return {
             sql: entry.sql,
             params,
@@ -1497,16 +1686,17 @@ export class QueryInterface {
         const whereFp = this.fingerprintWhere(whereObj);
         const ck = `um:${setFp}|${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const setEntries = Object.entries(dataObj).filter(([, v]) => v !== undefined);
             const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, freshParams));
             const whereClause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
             return `UPDATE ${this.q(this.table)} SET ${setClauses.join(', ')}${whereSql}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         this.collectSetParams(dataObj, params);
         this.collectWhereParams(whereObj, params);
+        this.crossCheckCache('updateMany', ck, entry, buildSql, params);
         return {
             sql: entry.sql,
             params,
@@ -1533,13 +1723,14 @@ export class QueryInterface {
         const whereFp = this.fingerprintWhere(whereObj);
         const ck = `dm:${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             return `DELETE FROM ${this.q(this.table)}${whereSql}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         this.collectWhereParams(whereObj, params);
+        this.crossCheckCache('deleteMany', ck, entry, buildSql, params);
         return {
             sql: entry.sql,
             params,
@@ -1566,15 +1757,16 @@ export class QueryInterface {
         const whereFp = hasWhere ? this.fingerprintWhere(whereObj) : '';
         const ck = `cnt:${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const clause = hasWhere ? this.buildWhereClause(whereObj, freshParams) : null;
             const whereSql = clause ? ` WHERE ${clause}` : '';
             return `SELECT ${this.castAgg('COUNT(*)', 'int')} AS count FROM ${this.q(this.table)}${whereSql}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         if (hasWhere) {
             this.collectWhereParams(whereObj, params);
         }
+        this.crossCheckCache('count', ck, entry, buildSql, params);
         return {
             sql: entry.sql,
             params,
@@ -2903,9 +3095,11 @@ export class QueryInterface {
                 const oEntries = Object.entries(opts.orderBy).map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d, targetRels?.[k]?.to)}`);
                 subParts.push(`o=${oEntries.join(',')}`);
             }
-            // limit presence
+            // limit presence, but on inline-pagination engines (MySQL) the literal
+            // value is baked into the subquery SQL, so fingerprint the value there or
+            // `{limit:3}` and `{limit:5}` would share one cached statement.
             if (opts.limit !== undefined) {
-                subParts.push('l=1');
+                subParts.push(this.dialect.inlineLimitOffset ? `l=${opts.limit}` : 'l=1');
             }
             // nested with (recurse)
             if (opts.with) {

package/dist/query/deferred.d.ts

@@ -85,10 +85,19 @@ export interface QueryInterfaceOptions {
     preparedStatements?: boolean;
     /**
      * Enable the SQL template cache. When true, repeated queries with the
-     * same shape (same keys, operators, relations — different values) reuse
+     * same shape (same keys, operators, relations, different values) reuse
      * cached SQL text instead of rebuilding from scratch.
      *
      * Default: `true`. Set to `false` as a nuclear kill switch.
+     *
+     * Dev-mode safety net: when `NODE_ENV !== 'production'`, every cache HIT is
+     * cross-checked by rebuilding the SQL + params fresh and comparing them
+     * against the cache-hit result, catching any drift between the fingerprint,
+     * SQL-build, and param-collect paths (which has silently corrupted results
+     * before). A mismatch throws a `ValidationError` (E003). This runs only
+     * outside production, so it never touches the production hot path. Set the
+     * env var `TURBINE_DISABLE_CACHE_CHECK=1` to opt out when dev traffic is
+     * perf-sensitive.
      */
     sqlCache?: boolean;
     /** SQL dialect implementation. Defaults to PostgreSQL. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.32.0",
+  "version": "0.32.1",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "exports": {
@@ -75,7 +75,8 @@
     "lint:fix": "biome check --write src/",
     "format": "biome format --write src/",
     "prepublishOnly": "npm run build && npm run typecheck && npm run lint && npm run test:unit",
-    "prepare": "husky",
+    "prepack": "node scripts/strip-prepare.mjs",
+    "postpack": "node scripts/restore-prepare.mjs",
     "size": "size-limit",
     "size:check": "size-limit",
     "test:watch": "tsx --watch --test src/test/*.test.ts",