turbine-orm 0.19.1 → 0.19.2

package/dist/cli/studio.d.ts

@@ -79,14 +79,4 @@ export declare function apiBuilder(req: IncomingMessage, res: ServerResponse, ct
 export declare function apiListSavedQueries(res: ServerResponse, ctx: StudioContext, params: URLSearchParams): void;
 export declare function apiCreateSavedQuery(req: IncomingMessage, res: ServerResponse, ctx: StudioContext): Promise<void>;
 export declare function apiDeleteSavedQuery(res: ServerResponse, ctx: StudioContext, id: string): void;
-/**
- * Accept only SELECT or WITH (CTE) statements. Reject any statement that
- * contains a semicolon followed by non-whitespace (prevents statement
- * stacking), and require the first non-comment keyword to be SELECT or WITH.
- *
- * This is a first-line filter — the transaction's READ ONLY mode is the
- * second line of defense. Both must fail before a destructive statement
- * could run.
- */
-export declare function isReadOnlyStatement(sql: string): boolean;
 //# sourceMappingURL=studio.d.ts.map

package/dist/cli/studio.js

@@ -535,35 +535,6 @@ function clampInt(value, fallback, min, max) {
         return fallback;
     return Math.min(Math.max(n, min), max);
 }
-/**
- * Accept only SELECT or WITH (CTE) statements. Reject any statement that
- * contains a semicolon followed by non-whitespace (prevents statement
- * stacking), and require the first non-comment keyword to be SELECT or WITH.
- *
- * This is a first-line filter — the transaction's READ ONLY mode is the
- * second line of defense. Both must fail before a destructive statement
- * could run.
- */
-export function isReadOnlyStatement(sql) {
-    const stripped = stripSqlComments(sql).trim();
-    if (!stripped)
-        return false;
-    // Disallow statement stacking. A single trailing `;` is fine.
-    const withoutTrailingSemi = stripped.replace(/;+\s*$/, '');
-    if (withoutTrailingSemi.includes(';'))
-        return false;
-    const firstWord = withoutTrailingSemi.slice(0, 6).toUpperCase();
-    if (firstWord.startsWith('SELECT'))
-        return true;
-    if (firstWord.startsWith('WITH'))
-        return true;
-    return false;
-}
-function stripSqlComments(sql) {
-    // Strip -- line comments and /* block comments */. Not a full SQL parser,
-    // but sufficient to catch the common bypass attempts.
-    return sql.replace(/--[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
-}
 function serializeRow(row) {
     const out = {};
     for (const [k, v] of Object.entries(row)) {

package/dist/client.d.ts

@@ -255,12 +255,14 @@ export declare class TurbineClient {
     private readonly activeSubscriptions;
     constructor(config: TurbineConfig | undefined, schema: SchemaMetadata);
     /**
-     * Register a middleware function that runs before/after every query.
+     * Register a middleware function that runs around every query.
      *
-     * 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.
      *
      * @example
      * ```ts
@@ -272,16 +274,13 @@ export declare class TurbineClient {
      *   return result;
      * });
      *
-     * // Soft-delete middleware
+     * // Result transformation middleware — redact a field on the way out
      * db.$use(async (params, next) => {
-     *   if (params.action === 'findMany' || params.action === 'findUnique') {
-     *     params.args.where = { ...params.args.where, deletedAt: null };
-     *   }
-     *   if (params.action === 'delete') {
-     *     params.action = 'update';
-     *     params.args = { where: params.args.where, data: { deletedAt: new Date() } };
+     *   const result = await next(params);
+     *   if (params.model === 'users' && Array.isArray(result)) {
+     *     for (const row of result as { email?: string }[]) row.email = '[redacted]';
      *   }
-     *   return next(params);
+     *   return result;
      * });
      * ```
      */

package/dist/client.js

@@ -323,12 +323,14 @@ export class TurbineClient {
     // Middleware — intercept all queries
     // -------------------------------------------------------------------------
     /**
-     * Register a middleware function that runs before/after every query.
+     * Register a middleware function that runs around every query.
      *
-     * 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.
      *
      * @example
      * ```ts
@@ -340,16 +342,13 @@ export class TurbineClient {
      *   return result;
      * });
      *
-     * // Soft-delete middleware
+     * // Result transformation middleware — redact a field on the way out
      * db.$use(async (params, next) => {
-     *   if (params.action === 'findMany' || params.action === 'findUnique') {
-     *     params.args.where = { ...params.args.where, deletedAt: null };
-     *   }
-     *   if (params.action === 'delete') {
-     *     params.action = 'update';
-     *     params.args = { where: params.args.where, data: { deletedAt: new Date() } };
+     *   const result = await next(params);
+     *   if (params.model === 'users' && Array.isArray(result)) {
+     *     for (const row of result as { email?: string }[]) row.email = '[redacted]';
      *   }
-     *   return next(params);
+     *   return result;
      * });
      * ```
      */

package/dist/index.d.ts

@@ -43,7 +43,7 @@ export { type IntrospectOptions, introspect } from './introspect.js';
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
 export type { ObserveConfig, ObserveHandle } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type HavingClause, type JsonFilter, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type HavingClause, type JsonFilter, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { ColumnMetadata, IndexMetadata, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';

package/dist/query/builder.d.ts

@@ -168,10 +168,12 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * 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.
      */
     private executeWithMiddleware;
     findUnique<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O> | null>;
@@ -228,11 +230,11 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     buildFindFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T>;
     findUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>>;
     buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T>;
-    create(args: CreateArgs<T>): Promise<T>;
+    create(args: CreateArgs<T, R>): Promise<T>;
     buildCreate(args: CreateArgs<T>): DeferredQuery<T>;
     createMany(args: CreateManyArgs<T>): Promise<T[]>;
     buildCreateMany(args: CreateManyArgs<T>): DeferredQuery<T[]>;
-    update(args: UpdateArgs<T>): Promise<T>;
+    update(args: UpdateArgs<T, R>): Promise<T>;
     buildUpdate(args: UpdateArgs<T>): DeferredQuery<T>;
     private nestedCreate;
     private nestedUpdate;

package/dist/query/builder.js

@@ -44,6 +44,53 @@ function isUnmatchedPlainObject(value) {
     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 */
@@ -53,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 ||
@@ -356,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;
@@ -398,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 &&
@@ -603,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);
@@ -644,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);
             }
@@ -1886,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
@@ -1964,12 +2015,7 @@ 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)
@@ -1990,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)
@@ -2075,7 +2122,7 @@ export class QueryInterface {
             }
             // Operator objects
             if (isWhereOperator(value)) {
-                this.collectOperatorParams(value, params);
+                this.collectOperatorParams(rawColumn, value, params);
                 continue;
             }
             // Plain equality — same strict validation as the build path, so a
@@ -2089,22 +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;
             }
-            const col = meta.columnMap[field] ?? camelToSnake(field);
             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)
@@ -2260,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;
@@ -2287,7 +2340,7 @@ export class QueryInterface {
                 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;
@@ -2301,7 +2354,7 @@ export class QueryInterface {
         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;
@@ -2321,7 +2374,7 @@ export class QueryInterface {
         }
         // 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;
@@ -2403,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 = [];
@@ -2610,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);
@@ -2675,7 +2731,9 @@ export class QueryInterface {
      */
     buildAliasWhere(targetTable, targetMeta, alias, where, params) {
         const clauses = [];
-        for (const [key, value] of Object.entries(where)) {
+        // 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') {
@@ -2717,7 +2775,9 @@ export class QueryInterface {
     }
     /** Mirrors {@link buildAliasWhere} param-push order for the cache-hit collect path. */
     collectAliasWhereParams(targetTable, targetMeta, where, params) {
-        for (const [key, value] of Object.entries(where)) {
+        // 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') {
@@ -2735,11 +2795,11 @@ export class QueryInterface {
             }
             if (value === null)
                 continue;
+            const col = targetMeta.columnMap[key] ?? camelToSnake(key);
             if (isWhereOperator(value)) {
-                this.collectOperatorParams(value, params);
+                this.collectOperatorParams(col, value, params);
                 continue;
             }
-            const col = targetMeta.columnMap[key] ?? camelToSnake(key);
             this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(targetMeta, col), targetTable);
             params.push(value);
         }
@@ -2773,11 +2833,7 @@ export class QueryInterface {
                 continue;
             }
             if (isWhereOperator(value)) {
-                const opKeys = Object.keys(value)
-                    .filter((k) => k !== 'mode')
-                    .sort();
-                const mode = value.mode;
-                parts.push(`${key}:op(${opKeys.join(',')}${mode === 'insensitive' ? ':i' : ''})`);
+                parts.push(`${key}:${fingerprintOperatorShape(value)}`);
                 continue;
             }
             if (isUnmatchedPlainObject(value)) {
@@ -2796,6 +2852,16 @@ export class QueryInterface {
      */
     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)}`);
@@ -3094,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}". ` +
@@ -3249,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}". ` +
@@ -3325,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}". ` +
@@ -3443,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}". ` +
@@ -3466,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}". ` +

package/dist/query/index.d.ts

@@ -5,7 +5,7 @@
  * `import { … } from './query/index.js'` is a drop-in replacement for the
  * former monolithic `import { … } from './query.js'`.
  */
-export type { AggregateArgs, AggregateResult, ArrayFilter, ConnectOrCreateOp, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, HavingClause, JsonFilter, NestedCreateOp, NestedUpdateOp, OmitResult, OrderByClause, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, SelectResult, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
+export type { AggregateArgs, AggregateResult, ArrayFilter, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, HavingClause, JsonFilter, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, SelectResult, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, InsertStatementInput, UpsertStatementInput, } from '../dialect.js';
 export { postgresDialect } from '../dialect.js';
 export type { SqlCacheEntry } from './utils.js';