turbine-orm 0.19.0 → 0.19.2

package/dist/query/builder.js

@@ -30,6 +30,67 @@ function isWhereOperator(value) {
     const keys = Object.keys(value);
     return keys.length > 0 && keys.every((k) => OPERATOR_KEYS.has(k));
 }
+/**
+ * True for a *plain object literal* that reached an equality fallthrough
+ * without matching any known filter shape — the misspelled-operator case.
+ * Class instances (Buffer for bytea, Decimal wrappers, ...) are legitimate
+ * bind values and return false, as do arrays and Dates.
+ */
+function isUnmatchedPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value) || value instanceof Date)
+        return false;
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
+ * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
+ * param pushed), so null-ness is part of the shape — without it a cache entry
+ * warmed by `{ not: 5 }` would serve `{ not: null }` with a desynced param list.
+ */
+function fingerprintOperatorShape(value) {
+    const obj = value;
+    const opKeys = Object.keys(obj)
+        .filter((k) => k !== 'mode')
+        .map((k) => ((k === 'equals' || k === 'not') && obj[k] === null ? `${k}:null` : k))
+        .sort();
+    const modeStr = value.mode === 'insensitive' ? ':i' : '';
+    return `op(${opKeys.join(',')}${modeStr})`;
+}
+/**
+ * Guard for the value of an `equals` operator reaching the plain-equality
+ * operator path. A plain object literal can only legitimately be an equality
+ * value on a json/jsonb column — and those route to the JSONB filter branch
+ * BEFORE the operator branch, so any plain object that reaches here is a
+ * mistake (e.g. `{ equals: { foo: 1 } }` on a text column). Shared by the
+ * SQL-build path and the cache-hit param-collect path so a warmed cache can
+ * never skip the check.
+ */
+function assertBindableEqualsOperand(value, column) {
+    if (!isUnmatchedPlainObject(value))
+        return;
+    throw new ValidationError(`[turbine] Plain-object value for operator 'equals' on ${column}: ` +
+        `objects are only valid 'equals' values on JSON (json/jsonb) columns, ` +
+        `where 'equals' is the JSONB containment filter.`);
+}
+/**
+ * Object keys in sorted order, mirroring the canonical order used by every
+ * cache fingerprint. The SQL-build and cache-hit param-collect paths MUST
+ * enumerate object keys in this exact order: fingerprints sort keys, so two
+ * where clauses with the same fields in different insertion order share one
+ * cache entry — if build/collect iterated insertion order, the cached SQL's
+ * `$N` placeholders would bind the wrong values (cross-tenant-leak class).
+ * Array order (OR/AND members) is positional and is never sorted.
+ */
+function sortedKeys(obj) {
+    return Object.keys(obj).sort();
+}
+/** {@link sortedKeys}, but yielding `[key, value]` pairs. */
+function sortedEntries(obj) {
+    return Object.entries(obj).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
 /** Known atomic-update operator keys — used to detect operator objects vs plain JSON values */
 const UPDATE_OPERATOR_KEYS = new Set(['set', 'increment', 'decrement', 'multiply', 'divide']);
 /** Known JSONB operator keys */
@@ -39,9 +100,11 @@ const JSONB_OPERATOR_KEYS = new Set(['path', 'equals', 'contains', 'hasKey']);
  * appear in any other where-filter shape, so the presence of one of these is
  * an unambiguous signal that the user meant a JSON filter. Used by the
  * strict-validation path so that `{ contains: 'foo' }` (which is also a valid
- * `WhereOperator` for LIKE) is not misclassified.
+ * `WhereOperator` for LIKE) is not misclassified. Note `equals` is NOT in this
+ * set: on non-JSON columns it is a plain equality operator (`WhereOperator`),
+ * so it must fall through instead of throwing.
  */
-const JSONB_UNIQUE_KEYS = new Set(['path', 'equals', 'hasKey']);
+const JSONB_UNIQUE_KEYS = new Set(['path', 'hasKey']);
 /** Check if a value is a JSONB filter object */
 function isJsonFilter(value) {
     if (value === null ||
@@ -342,10 +405,12 @@ export class QueryInterface {
      * Execute a query through the middleware chain.
      * If no middlewares are registered, executes directly.
      *
-     * Middleware can inspect and log query parameters, modify results after execution,
-     * and measure timing. Note: query SQL is generated before middleware runs, so
-     * modifying params.args in middleware will NOT affect the executed SQL.
-     * To intercept queries before SQL generation, use the raw() method instead.
+     * Middleware can inspect and log query parameters, measure timing, and
+     * transform the result returned by `next()`. Note: query SQL is generated
+     * BEFORE middleware runs — `params.args` is a read-only snapshot, and
+     * mutating it does NOT change the executed SQL. Cross-cutting filters
+     * (e.g. soft deletes) belong in the query itself: pass an explicit
+     * `where: { deletedAt: null }` or wrap the table accessor in a small helper.
      */
     async executeWithMiddleware(action, args, executor) {
         this.currentAction = action;
@@ -384,8 +449,12 @@ export class QueryInterface {
         const withFp = args.with ? this.withFingerprint(args.with) : '';
         const ck = `fu:${whereFingerprint}|c=${colKey}|w=${withFp}`;
         const params = [];
-        // Check if all where values are simple (plain equality, no operators/null/OR)
-        const whereKeys = Object.keys(whereObj).filter((k) => whereObj[k] !== undefined);
+        // Check if all where values are simple (plain equality, no operators/null/OR).
+        // Keys are sorted to match fingerprintWhere — insertion order here would let
+        // permuted where literals share a cache entry with misaligned params.
+        const whereKeys = Object.keys(whereObj)
+            .filter((k) => whereObj[k] !== undefined)
+            .sort();
         const isSimpleWhere = !whereObj.OR &&
             !whereObj.AND &&
             !whereObj.NOT &&
@@ -589,7 +658,8 @@ export class QueryInterface {
             }
             let sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${freshWhereSql}`;
             if (args?.cursor) {
-                const cursorEntries = Object.entries(args.cursor).filter(([, v]) => v !== undefined);
+                // Sorted (canonical) order — MUST match cursorFp and the cache-hit collect below.
+                const cursorEntries = sortedEntries(args.cursor).filter(([, v]) => v !== undefined);
                 if (cursorEntries.length > 0) {
                     const cursorConditions = cursorEntries.map(([k, v]) => {
                         const col = this.toSqlColumn(k);
@@ -630,9 +700,9 @@ export class QueryInterface {
         if (args?.with) {
             this.collectWithParams(args.with, params);
         }
-        // 3. Cursor params
+        // 3. Cursor params — sorted (canonical) order, matching cursorFp and the build path.
         if (args?.cursor) {
-            const cursorEntries = Object.entries(args.cursor).filter(([, v]) => v !== undefined);
+            const cursorEntries = sortedEntries(args.cursor).filter(([, v]) => v !== undefined);
             for (const [, v] of cursorEntries) {
                 params.push(v);
             }
@@ -1872,12 +1942,7 @@ export class QueryInterface {
             }
             // Operator objects
             if (isWhereOperator(value)) {
-                const opKeys = Object.keys(value)
-                    .filter((k) => k !== 'mode')
-                    .sort();
-                const mode = value.mode;
-                const modeStr = mode === 'insensitive' ? ':i' : '';
-                parts.push(`${key}:op(${opKeys.join(',')}${modeStr})`);
+                parts.push(`${key}:${fingerprintOperatorShape(value)}`);
                 continue;
             }
             // Vector distance filter — metric (operator) and present comparators
@@ -1908,6 +1973,16 @@ export class QueryInterface {
                 parts.push(`${key}:fts(${cfg})`);
                 continue;
             }
+            // Plain object literal that matched no filter shape — give it a
+            // fingerprint distinct from real equality. The build path throws for
+            // these on non-JSON columns; sharing `key:eq` would let a cache entry
+            // warmed by genuine equality serve the bad filter silently.
+            if (isUnmatchedPlainObject(value)) {
+                parts.push(`${key}:obj(${Object.keys(value)
+                    .sort()
+                    .join(',')})`);
+                continue;
+            }
             // Plain equality
             parts.push(`${key}:eq`);
         }
@@ -1940,12 +2015,12 @@ export class QueryInterface {
                 parts.push(`${key}:null`);
             }
             else if (isWhereOperator(value)) {
-                const opKeys = Object.keys(value)
-                    .filter((k) => k !== 'mode')
-                    .sort();
-                const mode = value.mode;
-                const modeStr = mode === 'insensitive' ? ':i' : '';
-                parts.push(`${key}:op(${opKeys.join(',')}${modeStr})`);
+                parts.push(`${key}:${fingerprintOperatorShape(value)}`);
+            }
+            else if (isUnmatchedPlainObject(value)) {
+                parts.push(`${key}:obj(${Object.keys(value)
+                    .sort()
+                    .join(',')})`);
             }
             else {
                 parts.push(`${key}:eq`);
@@ -1961,7 +2036,8 @@ export class QueryInterface {
      * @internal Exposed as package-private for testing.
      */
     collectWhereParams(where, params) {
-        const keys = Object.keys(where);
+        // Sorted (canonical) order — MUST match fingerprintWhere and buildWhereClause.
+        const keys = sortedKeys(where);
         for (const key of keys) {
             const value = where[key];
             if (value === undefined)
@@ -2046,10 +2122,12 @@ export class QueryInterface {
             }
             // Operator objects
             if (isWhereOperator(value)) {
-                this.collectOperatorParams(value, params);
+                this.collectOperatorParams(rawColumn, value, params);
                 continue;
             }
-            // Plain equality
+            // Plain equality — same strict validation as the build path, so a
+            // cache hit can never silently bind a misspelled-operator object.
+            this.assertBindableEqualityValue(rawColumn, value, this.getColumnPgType(rawColumn), this.table);
             params.push(value);
         }
     }
@@ -2058,20 +2136,28 @@ export class QueryInterface {
         const meta = this.schema.tables[targetTable];
         if (!meta)
             return;
-        for (const [_field, value] of Object.entries(subWhere)) {
+        // Sorted (canonical) order — MUST match fingerprintRelFilter and buildSubWhereForRelation.
+        for (const field of sortedKeys(subWhere)) {
+            const value = subWhere[field];
             if (value === undefined)
                 continue;
             if (value === null)
                 continue;
+            const col = meta.columnMap[field] ?? camelToSnake(field);
             if (isWhereOperator(value)) {
-                this.collectOperatorParams(value, params);
+                this.collectOperatorParams(col, value, params);
                 continue;
             }
+            this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(meta, col), targetTable);
             params.push(value);
         }
     }
     /** Collect params from operator clauses. Mirrors buildOperatorClauses. */
-    collectOperatorParams(op, params) {
+    collectOperatorParams(column, op, params) {
+        if (op.equals !== undefined && op.equals !== null) {
+            assertBindableEqualsOperand(op.equals, `"${column}"`);
+            params.push(op.equals);
+        }
         if (op.gt !== undefined)
             params.push(op.gt);
         if (op.gte !== undefined)
@@ -2194,13 +2280,11 @@ export class QueryInterface {
                     .sort();
                 subParts.push(`om=${omKeys.join(',')}`);
             }
-            // where shape (value-invariant)
+            // where shape (value-invariant, operator-shape-aware: `{title: 'x'}` and
+            // `{title: {contains: 'x'}}` emit different SQL so they must not share
+            // a fingerprint)
             if (opts.where) {
-                // Use a target-table QI if possible, or a simplified fingerprint
-                const wKeys = Object.keys(opts.where)
-                    .filter((k) => opts.where[k] !== undefined)
-                    .sort();
-                subParts.push(`w=${wKeys.join(',')}`);
+                subParts.push(`w=${this.fingerprintAliasWhere(opts.where)}`);
             }
             // orderBy shape
             if (opts.orderBy) {
@@ -2229,7 +2313,7 @@ export class QueryInterface {
         const meta = this.schema.tables[table ?? this.table];
         if (!meta)
             return;
-        for (const [relName, relSpec] of Object.entries(withClause)) {
+        for (const [relName, relSpec] of sortedEntries(withClause)) {
             const relDef = meta.relations[relName];
             if (!relDef)
                 continue;
@@ -2250,15 +2334,13 @@ export class QueryInterface {
         //   where params → limit param → nested-with params (always, both paths).
         if (relDef.type === 'manyToMany') {
             if (spec.where) {
-                for (const [, v] of Object.entries(spec.where)) {
-                    params.push(v);
-                }
+                this.collectAliasWhereParams(targetTable, targetMeta, spec.where, params);
             }
-            if (spec.limit) {
+            if (spec.limit !== undefined) {
                 params.push(Number(spec.limit));
             }
             if (spec.with) {
-                for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+                for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                     const nestedRelDef = targetMeta.relations[nestedRelName];
                     if (!nestedRelDef)
                         continue;
@@ -2267,31 +2349,32 @@ export class QueryInterface {
             }
             return;
         }
-        const willWrap = relDef.type === 'hasMany' && (spec.limit !== undefined || spec.orderBy !== undefined);
+        // Mirrors buildRelationSubquery's willWrap: `orderBy: {}` is treated as absent.
+        const hasOrder = spec.orderBy ? Object.values(spec.orderBy).some((dir) => dir !== undefined) : false;
+        const willWrap = relDef.type === 'hasMany' && (spec.limit !== undefined || hasOrder);
         // Non-wrapped path: nested relations BEFORE where/limit
         if (!willWrap && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+            for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                 const nestedRelDef = targetMeta.relations[nestedRelName];
                 if (!nestedRelDef)
                     continue;
                 this.collectRelationSubqueryParams(nestedRelDef, nestedSpec, params, 'alias', depth + 1);
             }
         }
-        // where params
+        // where params — mirrors buildAliasWhere push order
         if (spec.where) {
-            for (const [, v] of Object.entries(spec.where)) {
-                params.push(v);
-            }
+            this.collectAliasWhereParams(targetTable, targetMeta, spec.where, params);
         }
         // limit param — only hasMany parameterizes its limit (mirrors
         // buildRelationSubquery). belongsTo/hasOne ignore limit (always LIMIT 1), so
         // pushing one here would orphan a param and desync the collect path.
-        if (relDef.type === 'hasMany' && spec.limit) {
+        // `limit: 0` pushes (LIMIT 0 is honored), so check !== undefined.
+        if (relDef.type === 'hasMany' && spec.limit !== undefined) {
             params.push(Number(spec.limit));
         }
         // Wrapped path: nested relations AFTER where/limit (inside inner subquery)
         if (willWrap && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+            for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                 const nestedRelDef = targetMeta.relations[nestedRelName];
                 if (!nestedRelDef)
                     continue;
@@ -2373,7 +2456,8 @@ export class QueryInterface {
      * Supports: equality, operators, NULL, OR, AND, NOT, relation filters (some/every/none).
      */
     buildWhereClause(where, params) {
-        const keys = Object.keys(where);
+        // Sorted (canonical) order — MUST match fingerprintWhere and collectWhereParams.
+        const keys = sortedKeys(where);
         if (keys.length === 0)
             return null;
         const andClauses = [];
@@ -2494,25 +2578,11 @@ export class QueryInterface {
                 andClauses.push(...opClauses);
                 continue;
             }
-            // Strict validation: a plain (non-array, non-Date) object on a non-JSON
-            // column matched no known filter shape — almost always a misspelled
-            // operator (`startWith` for `startsWith`) or a stray nested object.
-            // Silently treating it as `col = $1` returns wrong rows with no error, so
-            // throw with the offending keys and the supported operator list. JSON/JSONB
-            // columns legitimately accept object values for equality, so they fall
-            // through unchanged.
-            if (typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
-                const colType = this.getColumnPgType(rawColumn);
-                if (colType !== 'json' && colType !== 'jsonb') {
-                    const badKeys = Object.keys(value);
-                    throw new ValidationError(badKeys.length === 0
-                        ? `[turbine] Empty filter object on "${rawColumn}" for table "${this.table}". ` +
-                            `Provide a value or an operator like { gt: 1 }.`
-                        : `[turbine] Unknown operator${badKeys.length > 1 ? 's' : ''} ` +
-                            `${badKeys.map((k) => `"${k}"`).join(', ')} on "${rawColumn}" for table "${this.table}". ` +
-                            `Supported operators: ${[...OPERATOR_KEYS].join(', ')}.`);
-                }
-            }
+            // Strict validation: a plain object literal that matched no known filter
+            // shape is almost always a misspelled operator (`startWith` for
+            // `startsWith`). The guard also runs on the cache-hit param-collect path
+            // (collectWhereParams) so a warmed SQL cache can never skip it.
+            this.assertBindableEqualityValue(rawColumn, value, this.getColumnPgType(rawColumn), this.table);
             // Plain equality
             params.push(value);
             andClauses.push(`${column} = ${this.p(params.length)}`);
@@ -2594,7 +2664,9 @@ export class QueryInterface {
             return null;
         const qt = this.q(targetTable);
         const conditions = [];
-        for (const [field, value] of Object.entries(subWhere)) {
+        // Sorted (canonical) order — MUST match fingerprintRelFilter and collectRelFilterParams.
+        for (const field of sortedKeys(subWhere)) {
+            const value = subWhere[field];
             if (value === undefined)
                 continue;
             const col = meta.columnMap[field] ?? camelToSnake(field);
@@ -2612,17 +2684,184 @@ export class QueryInterface {
                 conditions.push(...opClauses);
                 continue;
             }
+            this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(meta, col), targetTable);
             params.push(value);
             conditions.push(`${qCol} = ${this.p(params.length)}`);
         }
         return conditions.length > 0 ? conditions.join(' AND ') : null;
     }
+    /**
+     * Resolve a column's Postgres type from an arbitrary table's metadata
+     * (relation targets, not just `this.table`).
+     */
+    pgTypeForColumn(meta, column) {
+        return meta.dialectTypes?.[column] ?? meta.pgTypes?.[column] ?? 'text';
+    }
+    /**
+     * Equality-fallthrough guard shared by every SQL-build path AND every
+     * cache-hit param-collect path. A plain object literal that matched no known
+     * filter shape on a non-JSON column is almost always a misspelled operator
+     * (`startWith` for `startsWith`); binding it as `col = $1` silently returns
+     * wrong rows. Class instances (Buffer for bytea, Decimal wrappers, ...) are
+     * legitimate bind values and pass through, as do objects on json/jsonb
+     * columns (object equality).
+     */
+    assertBindableEqualityValue(rawColumn, value, columnPgType, table) {
+        if (!isUnmatchedPlainObject(value))
+            return;
+        if (columnPgType === 'json' || columnPgType === 'jsonb')
+            return;
+        const badKeys = Object.keys(value);
+        throw new ValidationError(badKeys.length === 0
+            ? `[turbine] Empty filter object on "${rawColumn}" for table "${table}". ` +
+                `Provide a value or an operator like { gt: 1 }.`
+            : `[turbine] Unknown operator${badKeys.length > 1 ? 's' : ''} ` +
+                `${badKeys.map((k) => `"${k}"`).join(', ')} on "${rawColumn}" for table "${table}". ` +
+                `Supported operators: ${[...OPERATOR_KEYS].join(', ')}.`);
+    }
+    /**
+     * Build the user-supplied `where` filter of a relation `with` clause against
+     * the relation's table alias. Supports the same scalar surface as the
+     * top-level WHERE builder — equality, IS NULL, operator objects (incl.
+     * `mode: 'insensitive'`), and OR/AND/NOT combinators. Unknown operator
+     * objects throw via {@link assertBindableEqualityValue}.
+     *
+     * Param push order MUST mirror {@link collectAliasWhereParams} exactly, or
+     * cache hits and pipeline batching will desync.
+     */
+    buildAliasWhere(targetTable, targetMeta, alias, where, params) {
+        const clauses = [];
+        // Sorted (canonical) order — MUST match fingerprintAliasWhere and collectAliasWhereParams.
+        for (const key of sortedKeys(where)) {
+            const value = where[key];
+            if (value === undefined)
+                continue;
+            if (key === 'OR' || key === 'AND') {
+                const arr = value;
+                if (!Array.isArray(arr) || arr.length === 0)
+                    continue;
+                const subs = arr
+                    .map((cond) => this.buildAliasWhere(targetTable, targetMeta, alias, cond, params))
+                    .filter((s) => s !== null)
+                    .map((s) => `(${s})`);
+                if (subs.length > 0)
+                    clauses.push(`(${subs.join(key === 'OR' ? ' OR ' : ' AND ')})`);
+                continue;
+            }
+            if (key === 'NOT') {
+                const sub = this.buildAliasWhere(targetTable, targetMeta, alias, value, params);
+                if (sub)
+                    clauses.push(`NOT (${sub})`);
+                continue;
+            }
+            const col = targetMeta.columnMap[key] ?? camelToSnake(key);
+            if (!targetMeta.allColumns.includes(col)) {
+                throw new ValidationError(`[turbine] Unknown column "${key}" in where for table "${targetTable}"`);
+            }
+            const qCol = `${alias}.${this.q(col)}`;
+            if (value === null) {
+                clauses.push(`${qCol} IS NULL`);
+                continue;
+            }
+            if (isWhereOperator(value)) {
+                clauses.push(...this.buildOperatorClauses(qCol, value, params));
+                continue;
+            }
+            this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(targetMeta, col), targetTable);
+            params.push(value);
+            clauses.push(`${qCol} = ${this.p(params.length)}`);
+        }
+        return clauses.length > 0 ? clauses.join(' AND ') : null;
+    }
+    /** Mirrors {@link buildAliasWhere} param-push order for the cache-hit collect path. */
+    collectAliasWhereParams(targetTable, targetMeta, where, params) {
+        // Sorted (canonical) order — MUST match fingerprintAliasWhere and buildAliasWhere.
+        for (const key of sortedKeys(where)) {
+            const value = where[key];
+            if (value === undefined)
+                continue;
+            if (key === 'OR' || key === 'AND') {
+                const arr = value;
+                if (!Array.isArray(arr) || arr.length === 0)
+                    continue;
+                for (const cond of arr) {
+                    this.collectAliasWhereParams(targetTable, targetMeta, cond, params);
+                }
+                continue;
+            }
+            if (key === 'NOT') {
+                this.collectAliasWhereParams(targetTable, targetMeta, value, params);
+                continue;
+            }
+            if (value === null)
+                continue;
+            const col = targetMeta.columnMap[key] ?? camelToSnake(key);
+            if (isWhereOperator(value)) {
+                this.collectOperatorParams(col, value, params);
+                continue;
+            }
+            this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(targetMeta, col), targetTable);
+            params.push(value);
+        }
+    }
+    /**
+     * Value-invariant, shape-aware fingerprint for a relation `with` clause's
+     * `where` filter. Must distinguish every SQL shape {@link buildAliasWhere}
+     * can emit — equality vs null vs operator sets vs combinators — or two
+     * differently-shaped wheres would share one cached SQL string.
+     */
+    fingerprintAliasWhere(where) {
+        const keys = Object.keys(where)
+            .filter((k) => where[k] !== undefined)
+            .sort();
+        const parts = [];
+        for (const key of keys) {
+            const value = where[key];
+            if (key === 'OR' || key === 'AND') {
+                const arr = value;
+                if (!Array.isArray(arr) || arr.length === 0)
+                    continue;
+                parts.push(`${key}[${arr.map((c) => this.fingerprintAliasWhere(c)).join(',')}]`);
+                continue;
+            }
+            if (key === 'NOT') {
+                parts.push(`NOT(${this.fingerprintAliasWhere(value)})`);
+                continue;
+            }
+            if (value === null) {
+                parts.push(`${key}:null`);
+                continue;
+            }
+            if (isWhereOperator(value)) {
+                parts.push(`${key}:${fingerprintOperatorShape(value)}`);
+                continue;
+            }
+            if (isUnmatchedPlainObject(value)) {
+                parts.push(`${key}:obj(${Object.keys(value)
+                    .sort()
+                    .join(',')})`);
+                continue;
+            }
+            parts.push(`${key}:eq`);
+        }
+        return parts.join('&');
+    }
     /**
      * Build SQL clauses for a single operator object on a column.
      * Each operator key becomes its own clause, all ANDed together.
      */
     buildOperatorClauses(column, op, params) {
         const clauses = [];
+        if (op.equals !== undefined) {
+            if (op.equals === null) {
+                clauses.push(`${column} IS NULL`);
+            }
+            else {
+                assertBindableEqualsOperand(op.equals, column);
+                params.push(op.equals);
+                clauses.push(`${column} = ${this.p(params.length)}`);
+            }
+        }
         if (op.gt !== undefined) {
             params.push(op.gt);
             clauses.push(`${column} > ${this.p(params.length)}`);
@@ -2921,7 +3160,7 @@ export class QueryInterface {
         const baseCols = cols.map((col) => `${qtbl}.${this.q(col)}`).join(', ');
         const relationSelects = [];
         const aliasCounter = { n: 0 };
-        for (const [relName, relSpec] of Object.entries(withClause)) {
+        for (const [relName, relSpec] of sortedEntries(withClause)) {
             const relDef = meta.relations[relName];
             if (!relDef) {
                 throw new RelationError(`[turbine] Unknown relation "${relName}" on table "${table}". ` +
@@ -3063,7 +3302,11 @@ export class QueryInterface {
         // Determine if this hasMany will take the wrapped subquery path (LIMIT or ORDER BY).
         // When wrapping, nested relations are built in the wrapped path referencing innerAlias,
         // so we must NOT build them here (they would push orphaned params).
-        const willWrap = relDef.type === 'hasMany' && spec !== true && (spec.limit !== undefined || spec.orderBy !== undefined);
+        // An orderBy with no defined entries (`orderBy: {}`) is treated as absent —
+        // it must neither trigger the wrap (dropping nested relations) nor render a
+        // dangling `ORDER BY `. `limit: 0` is meaningful (LIMIT 0) and DOES wrap.
+        const relOrderEntries = spec !== true && spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+        const willWrap = relDef.type === 'hasMany' && spec !== true && (spec.limit !== undefined || relOrderEntries.length > 0);
         // manyToMany takes a dedicated JOIN-through-junction path. Nested relations,
         // where, orderBy, and select/omit are handled there (the target alias is the
         // row source, exactly like hasMany), so short-circuit before the hasMany logic.
@@ -3072,7 +3315,7 @@ export class QueryInterface {
         }
         // Nested relations — only in the non-wrapped path (wrapped path builds them separately)
         if (!willWrap && spec !== true && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+            for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                 const nestedRelDef = targetMeta.relations[nestedRelName];
                 if (!nestedRelDef) {
                     throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
@@ -3091,14 +3334,14 @@ export class QueryInterface {
         const qTarget = this.q(targetTable);
         // Build ORDER BY for json_agg
         let orderClause = '';
-        if (spec !== true && spec.orderBy) {
-            const orders = Object.entries(spec.orderBy)
+        if (relOrderEntries.length > 0) {
+            const orders = relOrderEntries
                 .map(([k, dir]) => {
                 const col = camelToSnake(k);
                 if (!targetMeta.allColumns.includes(col)) {
                     throw new ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
                 }
-                const safeDir = dir.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+                const safeDir = String(dir).toLowerCase() === 'desc' ? 'DESC' : 'ASC';
                 return `${alias}.${this.q(col)} ${safeDir}`;
             })
                 .join(', ');
@@ -3115,24 +3358,21 @@ export class QueryInterface {
         else {
             whereClause = this.dialect.buildCorrelation(alias, relDef.foreignKey, qParent, relDef.referenceKey);
         }
-        // Additional filters — properly parameterized
+        // Additional filters — full scalar where surface (equality, null, operator
+        // objects, OR/AND/NOT), properly parameterized against this alias.
         if (spec !== true && spec.where) {
-            for (const [k, v] of Object.entries(spec.where)) {
-                const col = camelToSnake(k);
-                if (!targetMeta.allColumns.includes(col)) {
-                    throw new ValidationError(`[turbine] Unknown column "${k}" in where for table "${targetTable}"`);
-                }
-                params.push(v);
-                whereClause += ` AND ${alias}.${this.q(col)} = ${this.p(params.length)}`;
-            }
+            const extra = this.buildAliasWhere(targetTable, targetMeta, alias, spec.where, params);
+            if (extra)
+                whereClause += ` AND ${extra}`;
         }
         // LIMIT — only meaningful for hasMany. A belongsTo / hasOne subquery returns
         // a single row (literal `LIMIT 1` below), so a `spec.limit` here must NOT push
         // a parameter: doing so orphans an untyped `$N` that the SQL never references,
         // which Postgres rejects with "could not determine data type of parameter $N"
         // (and shifts every later placeholder by one). To-one relations ignore limit.
+        // `limit: 0` is honored (LIMIT 0 → empty array), so check !== undefined.
         let limitClause = '';
-        if (relDef.type === 'hasMany' && spec !== true && spec.limit) {
+        if (relDef.type === 'hasMany' && spec !== true && spec.limit !== undefined) {
             params.push(Number(spec.limit));
             limitClause = ` LIMIT ${this.p(params.length)}`;
         }
@@ -3151,7 +3391,7 @@ export class QueryInterface {
                 ]);
                 // Build nested relation subqueries referencing innerAlias
                 if (spec !== true && spec.with) {
-                    for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+                    for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                         const nestedRelDef = targetMeta.relations[nestedRelName];
                         if (!nestedRelDef) {
                             throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
@@ -3226,35 +3466,33 @@ export class QueryInterface {
         let whereClause = sourceKeys
             .map((jcol, i) => `${jalias}.${this.q(jcol)} = ${qParent}.${this.q(refKeys[i])}`)
             .join(' AND ');
-        // ORDER BY on the target rows
+        // ORDER BY on the target rows. `orderBy: {}` (no defined entries) is
+        // treated as absent — it must not render a dangling `ORDER BY `.
+        const relOrderEntries = spec !== true && spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
         let orderClause = '';
-        if (spec !== true && spec.orderBy) {
-            const orders = Object.entries(spec.orderBy)
+        if (relOrderEntries.length > 0) {
+            const orders = relOrderEntries
                 .map(([k, dir]) => {
                 const col = camelToSnake(k);
                 if (!targetMeta.allColumns.includes(col)) {
                     throw new ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
                 }
-                const safeDir = dir.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+                const safeDir = String(dir).toLowerCase() === 'desc' ? 'DESC' : 'ASC';
                 return `${talias}.${this.q(col)} ${safeDir}`;
             })
                 .join(', ');
             orderClause = ` ORDER BY ${orders}`;
         }
-        // Additional WHERE filters on the target — properly parameterized.
+        // Additional WHERE filters on the target — full scalar where surface,
+        // properly parameterized against the target alias.
         if (spec !== true && spec.where) {
-            for (const [k, v] of Object.entries(spec.where)) {
-                const col = camelToSnake(k);
-                if (!targetMeta.allColumns.includes(col)) {
-                    throw new ValidationError(`[turbine] Unknown column "${k}" in where for table "${targetTable}"`);
-                }
-                params.push(v);
-                whereClause += ` AND ${talias}.${this.q(col)} = ${this.p(params.length)}`;
-            }
+            const extra = this.buildAliasWhere(targetTable, targetMeta, talias, spec.where, params);
+            if (extra)
+                whereClause += ` AND ${extra}`;
         }
-        // LIMIT
+        // LIMIT — `limit: 0` is honored (LIMIT 0 → empty array)
         let limitClause = '';
-        if (spec !== true && spec.limit) {
+        if (spec !== true && spec.limit !== undefined) {
             params.push(Number(spec.limit));
             limitClause = ` LIMIT ${this.p(params.length)}`;
         }
@@ -3271,7 +3509,7 @@ export class QueryInterface {
             ]);
             // Nested relations reference the inner alias.
             if (spec !== true && spec.with) {
-                for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+                for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                     const nestedRelDef = targetMeta.relations[nestedRelName];
                     if (!nestedRelDef) {
                         throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
@@ -3294,7 +3532,7 @@ export class QueryInterface {
             `${talias}.${this.q(col)}`,
         ]);
         if (spec !== true && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+            for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                 const nestedRelDef = targetMeta.relations[nestedRelName];
                 if (!nestedRelDef) {
                     throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +