turbine-orm 0.52.0 → 0.53.0

package/dist/query/aggregates.js

@@ -10,7 +10,7 @@
  */
 import { UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { snakeToCamel } from '../schema.js';
-import { isJsonPathOrderBy, isVectorOrderBy, normalizeOrderBy, orderByEntries } from './filters.js';
+import { isJsonPathOrderBy, isUnmatchedPlainObject, isVectorOrderBy, isWhereOperator, normalizeOrderBy, orderByEntries, } from './filters.js';
 import { ownLookup } from './utils.js';
 import * as whereMod from './where.js';
 /**
@@ -83,6 +83,12 @@ export function buildGroupBy(qi, args) {
     // expression (including any already-bound JSON-path placeholder, reused
     // exactly like HAVING since ORDER BY is appended after all other params).
     const byOrderExprs = new Map();
+    // The group-key set a `having` SCALAR filter may reference, keyed the same
+    // way (by-field name / JSON group-key alias). Separate from `byOrderExprs`
+    // because HAVING needs to know HOW the key is addressed: a plain by-field
+    // routes through the shared WHERE compiler by field name, a JSON group key
+    // re-emits its extract expression. See {@link buildHavingClauses}.
+    const havingGroupKeys = new Map();
     const usedResultKeys = new Set();
     const claimResultKey = (key, what) => {
         if (key === '_count' || usedResultKeys.has(key)) {
@@ -105,6 +111,7 @@ export function buildGroupBy(qi, args) {
             selectExprs.push(qi.q(col));
             byReaders.push({ resultKey: entry, rowKey: col, raw: false });
             byOrderExprs.set(entry, qi.q(col));
+            havingGroupKeys.set(entry, { kind: 'column', field: entry });
         }
         else {
             const col = resolveJsonPathTarget(qi, 'group key', entry.field, entry.path);
@@ -120,6 +127,9 @@ export function buildGroupBy(qi, args) {
             // ORDER BY by this JSON alias re-emits the extract expression (with its
             // already-bound $n): the same reuse HAVING does for JSON aggregates.
             byOrderExprs.set(alias, extract);
+            // Parenthesized: a scalar having predicate appends comparison / IS NULL
+            // operators to this expression, and the extract is emitted bare here.
+            havingGroupKeys.set(alias, { kind: 'expr', expr: `(${extract})`, label: `JSON group key "${alias}"` });
         }
     }
     // _count
@@ -215,7 +225,7 @@ export function buildGroupBy(qi, args) {
     // Appends to the same `params` array, so placeholders continue from the
     // WHERE clause's parameter positions (qi.p(params.length) below).
     if (args.having) {
-        const havingClauses = buildHavingClauses(qi, args.having, params, jsonAggExprs);
+        const havingClauses = buildHavingClauses(qi, args.having, params, jsonAggExprs, havingGroupKeys);
         if (havingClauses.length > 0) {
             sql += ` HAVING ${havingClauses.join(' AND ')}`;
         }
@@ -459,35 +469,46 @@ export function buildDistinctOnSource(qi, distinctOn, whereSql, params) {
     return (`(SELECT DISTINCT ON (${distinctCols.join(', ')}) * FROM ${qi.q(qi.table)}${whereSql} ` +
         `ORDER BY ${orderParts.join(', ')}) AS ${qi.q(qi.table)}`);
 }
+/**
+ * Maps a per-field aggregate key to its SQL function name. The set of allowed
+ * keys is fixed here: any OTHER underscore-prefixed key on a field's filter
+ * object is rejected by {@link ValidationError} (never interpolated), and every
+ * non-underscore key is a scalar operator on the grouped value itself.
+ */
+const HAVING_AGGREGATE_FNS = {
+    _sum: 'SUM',
+    _avg: 'AVG',
+    _min: 'MIN',
+    _max: 'MAX',
+    _count: 'COUNT',
+};
 /**
  * Build the SQL fragments for a {@link HavingClause}.
  *
+ * A field entry carries an AGGREGATE filter (`{ _sum: { gt: 100 } }`), a
+ * SCALAR filter on the grouped value itself (`{ not: null }`, `{ in: [...] }`,
+ * or a bare value as equality shorthand), or both in one object (ANDed,
+ * scalar first). `AND` / `OR` / `NOT` combine predicates at any depth.
+ *
  * Each aggregate expression (`COUNT(*)`, `SUM("col")`, etc.) is constructed
  * from a **schema-validated, quoted** column identifier: `qi.toColumn()`
  * throws {@link ValidationError} for unknown fields and `qi.q()` quotes via
  * the dialect, so no unvalidated identifier ever reaches the SQL string. Every
  * comparison value is pushed onto the shared `params` array and referenced by
- * a `$N` placeholder via {@link buildHavingNumericClauses}, there is no string
- * interpolation of user values.
+ * a `$N` placeholder via {@link buildHavingNumericClauses} (aggregates) or the
+ * shared WHERE compiler (scalars), there is no string interpolation of user
+ * values.
  *
  * `jsonAggExprs` (from {@link buildGroupBy}) maps `alias:aggKey` to the
  * exact aggregate expression a JSON-path aggregate emitted in SELECT
  * (including its already-bound path placeholder), so HAVING on a JSON-path
  * aggregate alias reuses the same expression instead of resolving the alias
- * as a column.
+ * as a column. `groupKeys` is the resolved `by` key set (see
+ * {@link HavingGroupKey}): a scalar filter is legal ONLY on a group key,
+ * because a non-grouped column cannot be referenced in HAVING at all.
  */
-export function buildHavingClauses(qi, having, params, jsonAggExprs) {
+export function buildHavingClauses(qi, having, params, jsonAggExprs, groupKeys) {
     const clauses = [];
-    // Maps the per-field aggregate key to its SQL function name. The set of
-    // allowed keys is fixed here, any other key on a field's filter object is
-    // rejected by ValidationError below (never interpolated).
-    const aggFnByKey = {
-        _sum: 'SUM',
-        _avg: 'AVG',
-        _min: 'MIN',
-        _max: 'MAX',
-        _count: 'COUNT',
-    };
     for (const [key, value] of Object.entries(having)) {
         if (value === undefined)
             continue;
@@ -496,11 +517,20 @@ export function buildHavingClauses(qi, having, params, jsonAggExprs) {
             clauses.push(...buildHavingNumericClauses(qi, 'COUNT(*)', value, params));
             continue;
         }
-        // Otherwise `key` is a field name mapping to a per-aggregate filter object.
-        if (typeof value !== 'object' || value === null) {
-            throw new ValidationError(`[turbine] Invalid having filter for field "${key}" on table "${qi.table}": ` +
-                `expected an aggregate object like { _sum: { gt: 100 } }.`);
+        // AND / OR / NOT, mixing scalar and aggregate predicates at any depth.
+        if (key === 'AND' || key === 'OR' || key === 'NOT') {
+            clauses.push(...buildHavingCombinator(qi, key, value, params, jsonAggExprs, groupKeys));
+            continue;
+        }
+        // Otherwise `key` is a field name. Split its aggregate keys from its
+        // scalar operator keys: everything the fixed aggregate map does not name
+        // filters the grouped value itself.
+        const { aggEntries, scalarFilter } = splitHavingField(qi, key, value);
+        if (scalarFilter !== undefined) {
+            clauses.push(...buildHavingScalarClauses(qi, key, scalarFilter, params, groupKeys));
         }
+        if (aggEntries.length === 0)
+            continue;
         // toColumn validates the field against schema metadata (throws
         // ValidationError on unknown columns) and q() quotes the identifier, no
         // unvalidated identifier ever reaches the SQL string. Resolution is lazy:
@@ -511,37 +541,147 @@ export function buildHavingClauses(qi, having, params, jsonAggExprs) {
             quotedCol ??= qi.q(qi.toColumn(key));
             return quotedCol;
         };
-        for (const [aggKey, filter] of Object.entries(value)) {
-            if (filter === undefined)
-                continue;
-            // ownLookup, not a bare index: an inherited Object.prototype member
-            // ("constructor", "toString", …) would otherwise resolve to a truthy
-            // builtin and be spliced into the HAVING clause as its source text.
-            const fn = ownLookup(aggFnByKey, aggKey);
-            if (!fn) {
-                throw new ValidationError(`[turbine] Unknown aggregate "${aggKey}" in having for field "${key}" on table "${qi.table}". ` +
-                    `Supported: ${Object.keys(aggFnByKey).join(', ')}.`);
-            }
-            const expr = jsonAggExprs?.get(`${key}:${aggKey}`) ?? `${fn}(${columnExpr()})`;
-            clauses.push(...buildHavingNumericClauses(qi, expr, filter, params));
+        for (const agg of aggEntries) {
+            const expr = jsonAggExprs?.get(`${key}:${agg.key}`) ?? `${agg.fn}(${columnExpr()})`;
+            clauses.push(...buildHavingNumericClauses(qi, expr, agg.filter, params));
+        }
+    }
+    return clauses;
+}
+/**
+ * Partition one `having` field entry into its aggregate filters and its scalar
+ * filter. A non-object value (or an object naming no aggregate key) is scalar
+ * in full, so the whole value keeps its original shape (operator object, JSON
+ * filter, bare value, `null`). An unknown UNDERSCORE-prefixed key is a
+ * misspelled aggregate, not a scalar operator, and throws E003 naming it.
+ */
+function splitHavingField(qi, field, value) {
+    if (!isUnmatchedPlainObject(value))
+        return { aggEntries: [], scalarFilter: value };
+    const aggEntries = [];
+    const scalarKeys = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (v === undefined)
+            continue;
+        // ownLookup, not a bare index: an inherited Object.prototype member
+        // ("constructor", "toString", …) would otherwise resolve to a truthy
+        // builtin and be spliced into the HAVING clause as its source text.
+        const fn = ownLookup(HAVING_AGGREGATE_FNS, k);
+        if (fn) {
+            aggEntries.push({ key: k, fn, filter: v });
+        }
+        else if (k.startsWith('_')) {
+            throw new ValidationError(`[turbine] Unknown aggregate "${k}" in having for field "${field}" on table "${qi.table}". ` +
+                `Supported: ${Object.keys(HAVING_AGGREGATE_FNS).join(', ')}.`);
+        }
+        else {
+            scalarKeys[k] = v;
+        }
+    }
+    if (aggEntries.length === 0)
+        return { aggEntries, scalarFilter: value };
+    return { aggEntries, scalarFilter: Object.keys(scalarKeys).length > 0 ? scalarKeys : undefined };
+}
+/**
+ * Compile a `having` AND / OR / NOT branch. Each condition is a nested
+ * {@link HavingClause}; its own clauses are ANDed (parenthesized when there is
+ * more than one) before being combined. `AND` contributes its parts directly
+ * (the caller ANDs them), mirroring {@link buildWhereClause}'s combinator
+ * shapes so HAVING and WHERE read the same way.
+ */
+function buildHavingCombinator(qi, key, value, params, jsonAggExprs, groupKeys) {
+    const conditions = Array.isArray(value) ? value : [value];
+    const parts = [];
+    for (const condition of conditions) {
+        if (!isUnmatchedPlainObject(condition)) {
+            throw new ValidationError(`[turbine] Invalid having "${key}" on table "${qi.table}": expected ` +
+                `${key === 'OR' ? 'an array of having objects' : 'a having object (or an array of them)'}.`);
         }
+        const sub = buildHavingClauses(qi, condition, params, jsonAggExprs, groupKeys);
+        if (sub.length === 0)
+            continue;
+        parts.push(sub.length === 1 ? sub[0] : `(${sub.join(' AND ')})`);
+    }
+    if (parts.length === 0)
+        return [];
+    if (key === 'AND')
+        return parts;
+    if (key === 'OR')
+        return [`(${parts.join(' OR ')})`];
+    return [`NOT (${parts.join(' AND ')})`];
+}
+/**
+ * Compile a SCALAR `having` filter: a predicate on the GROUPED value itself,
+ * as Prisma's groupBy allows (`having: { typeId: { not: null } }` →
+ * `HAVING "type_id" IS NOT NULL`).
+ *
+ * Placement is always HAVING, never WHERE. For a group key the two are
+ * result-equivalent (the value is constant within the group), but a scalar
+ * predicate ORed with an aggregate one is only expressible in HAVING, so one
+ * placement covers every shape and matches Prisma's emitted SQL.
+ *
+ * The field MUST be one of the `by` group keys: a predicate on any other
+ * column cannot appear in HAVING (Postgres answers "column must appear in the
+ * GROUP BY clause"), so it throws {@link ValidationError} E003 pointing at
+ * `where` / `by` / an aggregate filter instead of emitting invalid SQL.
+ *
+ * A plain by-column routes through the shared WHERE compiler
+ * ({@link whereMod.buildScalarClause}), so the operator set, enum casts, LIKE
+ * escaping, `mode: 'insensitive'`, and the dialect IN-clause form are
+ * inherited rather than reimplemented. A JSON-path group key compiles against
+ * its re-emitted extract expression.
+ */
+function buildHavingScalarClauses(qi, field, value, params, groupKeys) {
+    const ref = groupKeys?.get(field);
+    if (!ref) {
+        const known = groupKeys ? [...groupKeys.keys()] : [];
+        throw new ValidationError(`[turbine] having on "${field}" (table "${qi.table}") filters the grouped value itself, but ` +
+            `"${field}" is not one of the \`by\` group keys [${known.join(', ') || 'none'}]. A predicate on a ` +
+            'non-grouped column cannot go in HAVING: move it to `where` (it filters rows, not groups), add ' +
+            `"${field}" to \`by\`, or filter an aggregate of it instead (e.g. { ${field}: { _count: { gt: 0 } } }).`);
+    }
+    const clauses = [];
+    if (ref.kind === 'column') {
+        whereMod.buildScalarClause(qi, ref.field, value, params, clauses);
+        return clauses;
+    }
+    // JSON-path group key: the extract expression IS the group key, so it can
+    // carry a predicate in HAVING. It is not a column, so the column-typed
+    // surface (enum casts, temporal rewrites, column references) does not apply.
+    if (value === null) {
+        clauses.push(`${ref.expr} IS NULL`);
+    }
+    else if (isWhereOperator(value)) {
+        clauses.push(...whereMod.buildOperatorClauses(qi, ref.expr, value, params));
+    }
+    else if (isUnmatchedPlainObject(value)) {
+        throw new ValidationError(`[turbine] Unknown operator${Object.keys(value).length > 1 ? 's' : ''} ` +
+            `${Object.keys(value)
+                .map((k) => `"${k}"`)
+                .join(', ')} on ${ref.label} in having for table "${qi.table}".`);
+    }
+    else {
+        params.push(value);
+        clauses.push(`${ref.expr} = ${qi.p(params.length)}`);
     }
     return clauses;
 }
 /**
- * Convert a single having filter into one or more parameterized SQL
- * comparisons against the given aggregate expression. A bare number is
- * shorthand for equality. Unknown operator keys throw {@link ValidationError}.
+ * Convert a single having aggregate filter into one or more parameterized SQL
+ * comparisons against the given aggregate expression. A bare value is
+ * shorthand for equality. Operands are not numeric-only: `_min` / `_max`
+ * return a stored cell, so `MIN("title") > 'm'` is as valid as
+ * `SUM("views") > 10`. Unknown operator keys throw {@link ValidationError}.
  */
 export function buildHavingNumericClauses(qi, expr, filter, params) {
-    // Bare number → equality.
-    if (typeof filter === 'number') {
+    if (filter === null) {
+        throw new ValidationError(`[turbine] Invalid having filter on "${expr}" for table "${qi.table}": expected a value or operator object.`);
+    }
+    // Bare value (number, string, boolean, Date, …) → equality.
+    if (typeof filter !== 'object' || filter instanceof Date) {
         params.push(filter);
         return [`${expr} = ${qi.p(params.length)}`];
     }
-    if (typeof filter !== 'object' || filter === null) {
-        throw new ValidationError(`[turbine] Invalid having filter on "${expr}" for table "${qi.table}": expected a number or operator object.`);
-    }
     const op = filter;
     const allowedKeys = new Set(['equals', 'not', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn']);
     for (const k of Object.keys(op)) {

package/dist/query/builder.d.ts

@@ -605,7 +605,15 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * cache keys) when nothing qualifies.
      */
     private planAuto;
-    /** Dev-only once-per-relation note that `'auto'` engaged the batched fallback. */
+    /**
+     * Dev-only once-per-relation note that `'auto'` engaged the batched fallback.
+     *
+     * Both lines follow the same four parts: the CONDITION that tripped the rule,
+     * the MECHANISM (which plan shape was replaced by which, and what that costs),
+     * the fix, and the escape hatch. Naming only the condition is what lets a
+     * reader build a wrong model of the mechanism and read a correct optimization
+     * as a bug, so the mechanism sentence is not optional.
+     */
     private emitAutoNotes;
     /**
      * Execute a findMany/findUnique `'auto'` split: run the base query with the
@@ -942,7 +950,20 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private planFlatten;
     /** Dev-only once-only note that `'flatten'` was refused for the whole query. */
     private warnFlattenBlocked;
-    /** Convert camelCase field name to snake_case column name (unquoted, for non-SQL uses) */
+    /**
+     * Convert a field name to its snake_case column name (unquoted, for non-SQL
+     * uses), throwing E003 when the key names no column.
+     *
+     * The resolution rule itself lives in {@link resolveColumnName} (query/utils.ts)
+     * so the value-side passes that must NOT throw, write coercion above all, can
+     * share it instead of re-deriving it. Accepting `camelToSnake(field)` only
+     * when it is a real column preserves the convenience of writing `userId` when
+     * the schema exposes `user_id` under an unusual field name (and of writing the
+     * column name outright), while rejecting arbitrary strings, closing the
+     * defense-in-depth gap for SQL injection and catching typos like
+     * `where: { emial: 'x' }` with a clear error instead of a cryptic Postgres
+     * "column does not exist".
+     */
     private toColumn;
     /** Convert camelCase field name to a double-quoted SQL identifier */
     private toSqlColumn;

package/dist/query/builder.js

@@ -14,13 +14,13 @@ import { postgresDialect } from '../dialect.js';
 import { NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError } from '../errors.js';
 import { missingIndexForRelation, schemaHasIndexInfo } from '../index-advisor.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '../nested-write.js';
-import { camelToSnake, normalizeKeyColumns, snakeToCamel } from '../schema.js';
+import { normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import * as aggMod from './aggregates.js';
 import { defaultProjectionFields, includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, resolveCountRelations, stripFields, } from './batched-loader.js';
 import { expandCompoundUniqueWhere } from './compound-unique.js';
 import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
 import * as relationsMod from './relations.js';
-import { LRUCache, ownLookup, parseDbDate, sqlToPreparedName, unknownFieldMessage, } from './utils.js';
+import { LRUCache, ownLookup, parseDbDate, resolveColumnName, sqlToPreparedName, unknownFieldMessage, } from './utils.js';
 import { shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
@@ -672,12 +672,12 @@ export class QueryInterface {
         const rest = untyped.length > MAX_NAMED ? ` (+${untyped.length - MAX_NAMED} more)` : '';
         console.warn(`[turbine] table "${this.table}": no database type in metadata for column(s) ${named}${rest} (neither the ` +
             "column entry's `dialectType`/`pgType` nor the table-level `dialectTypes`/`pgTypes` map). Turbine cannot " +
-            'tell which of them are zone-less, so a `Date` written to one is bound by the driver as-is: right for ' +
-            "`timestamptz`, but a zone-less `date`/`timestamp` column then stores the PROCESS's local calendar fields " +
-            'rather than UTC (silently, since the read path shifts back by the same offset), and a `time`/`timetz` ' +
-            'column rejects the value outright (`22007 invalid input syntax for type time`). Columns whose type IS ' +
-            'resolved, every `timestamptz` among them, are unaffected. Regenerate the metadata with ' +
-            '`npx turbine generate`, or set the column types in your `defineSchema` definition.');
+            'tell which of them are zone-less, so it skips the UTC bind rewrite and a `Date` goes to the driver ' +
+            "as-is: right for `timestamptz`, but a zone-less `date`/`timestamp` then stores the PROCESS's local " +
+            'calendar fields rather than UTC (silently, since the read path shifts back by the same offset), and a ' +
+            '`time`/`timetz` column rejects the value outright (`22007 invalid input syntax for type time`). ' +
+            'Columns whose type IS resolved, every `timestamptz` among them, are unaffected. Fix: regenerate with ' +
+            '`npx turbine generate`, or set the column types in `defineSchema`.');
     }
     /** Quote an identifier through the active SQL dialect. */
     q(name) {
@@ -1252,7 +1252,15 @@ export class QueryInterface {
             return null;
         return split;
     }
-    /** Dev-only once-per-relation note that `'auto'` engaged the batched fallback. */
+    /**
+     * Dev-only once-per-relation note that `'auto'` engaged the batched fallback.
+     *
+     * Both lines follow the same four parts: the CONDITION that tripped the rule,
+     * the MECHANISM (which plan shape was replaced by which, and what that costs),
+     * the fix, and the escape hatch. Naming only the condition is what lets a
+     * reader build a wrong model of the mechanism and read a correct optimization
+     * as a bug, so the mechanism sentence is not optional.
+     */
     emitAutoNotes(engaged) {
         if (process.env.NODE_ENV === 'production')
             return;
@@ -1261,22 +1269,30 @@ export class QueryInterface {
                 continue;
             if (e.reason === 'to-one-cardinality') {
                 console.warn(`[turbine] auto strategy: to-one relation "${e.relation}" on "${this.table}" loads batched ` +
-                    `(the query is unbounded or its limit exceeds ${this.autoToOneThreshold()} rows, and a correlated ` +
-                    'to-one subquery is re-evaluated per parent row). Bound the query with a smaller `limit`, tune ' +
-                    "`autoToOneJoinMaxRows`, or set `relationLoadStrategy: 'join'` to force the single-statement plan.");
+                    `(the query is unbounded or its limit exceeds ${this.autoToOneThreshold()} rows). On the join plan ` +
+                    'a to-one relation is a correlated subquery the engine re-evaluates once per parent row, a per-row ' +
+                    'cost that stands even on a unique index; batched replaces it with ONE follow-up statement ' +
+                    '(`key = ANY(...)` for the whole page), so it trades that per-row cost for a single extra round ' +
+                    'trip. Bound the query with a smaller `limit`, tune `autoToOneJoinMaxRows` (the break-even is ' +
+                    "round-trip time / per-row cost), or set `relationLoadStrategy: 'join'` to force the " +
+                    'single-statement plan.');
                 continue;
             }
             const probe = e.miss
                 ? `probe "${e.miss.table}"(${e.miss.columns.join(', ')}) has no covering index`
                 : 'a probe in its subtree has no covering index';
-            // The `_count` case is the one people read as a needless demotion, because
-            // the follow-up statement is a grouped COUNT and the inline form looks
-            // like it would be one too. It is not: state the shape it replaced.
+            const child = e.miss?.table ?? 'the child table';
+            // Say which shape was replaced, not just the condition. The `_count` case
+            // is the one people read as a needless demotion, because the follow-up
+            // statement is a grouped COUNT and the inline form looks like it would be
+            // one too. It is not.
             const why = e.relation === '_count'
                 ? ' The inline form is one correlated COUNT(*) re-evaluated per parent row, so on an unindexed ' +
-                    `probe it is one full scan of "${e.miss?.table ?? 'the child table'}" per parent row; the ` +
-                    'follow-up is one grouped scan for the whole page.'
-                : '';
+                    `probe it is one full scan of "${child}" per parent row; the follow-up is one grouped scan for ` +
+                    'the whole page.'
+                : ' On the join plan that relation is a correlated subquery re-evaluated once per parent row, so an ' +
+                    `unindexed probe is one full scan of "${child}" per parent row; the batched follow-up scans it ` +
+                    'once for the whole page.';
             console.warn(`[turbine] auto strategy: relation "${e.relation}" on "${this.table}" loads batched (${probe}).${why} ` +
                 "Create the covering index (or set `relationLoadStrategy: 'join'` to force the single-statement " +
                 'plan); run `npx turbine doctor` for the exact CREATE INDEX SQL.');
@@ -1777,12 +1793,21 @@ export class QueryInterface {
                 const v = whereObj[k];
                 return v !== null && !isWhereOperator(v) && !ownLookup(this.tableMeta.relations, k);
             });
-        // Simple path: plain equality, no operators/null/OR
+        // Simple path: plain equality, no operators/null/OR.
+        //
+        // This path pushes its own params instead of going through
+        // `buildWhereClause`, so every VALUE transform the general walker applies
+        // has to be mirrored here or the two paths disagree on the same predicate.
+        // `coerceWhereOperand` is the one that matters: without it a `Date` keyed on
+        // a zone-less `date`/`timestamp`/`time` column binds raw, and a row that
+        // `findFirst` matches, `findUnique` silently misses. It is a value-only
+        // transform, so the emitted SQL and the cache key are untouched.
         if (!args.with && isSimpleWhere) {
+            const coerce = (k, v) => whereMod.coerceWhereOperand(this.ctx, this.tableMeta, this.toColumn(k), v);
             const buildSql = (freshParams) => {
                 const qt = this.q(this.table);
                 const whereClauses = whereKeys.map((k, i) => {
-                    freshParams.push(whereObj[k]);
+                    freshParams.push(coerce(k, whereObj[k]));
                     return `${this.toSqlColumn(k)} = ${this.p(i + 1)}`;
                 });
                 const whereSql = whereClauses.length > 0 ? ` WHERE ${whereClauses.join(' AND ')}` : '';
@@ -1790,9 +1815,9 @@ export class QueryInterface {
                 return `SELECT ${selectExpr} FROM ${qt}${whereSql}${this.limitOneClause()}`;
             };
             const entry = this.acquireSql(ck, buildSql);
-            // Collect params (same order as build)
+            // Collect params (same order and same coercion as build)
             for (const k of whereKeys) {
-                params.push(whereObj[k]);
+                params.push(coerce(k, whereObj[k]));
             }
             this.crossCheckCache('findUnique', ck, entry, buildSql, params);
             return {
@@ -1869,8 +1894,11 @@ export class QueryInterface {
             if (args?.with) {
                 const depth = this.measureWithDepth(args.with);
                 if (depth > 5 && shouldWarnOnce(WARN_NS.deepWith, this.table)) {
-                    console.warn(`[turbine] Deep with clause (depth ${depth}) on "${this.tableMeta.name}", ` +
-                        'consider splitting into separate queries for better performance.');
+                    console.warn(`[turbine] Deep with clause (depth ${depth}) on "${this.tableMeta.name}": every level is a ` +
+                        'correlated subquery the engine re-evaluates once per row of the level above, so the work ' +
+                        'multiplies down the tree and the whole subtree is built as JSON inside each parent row. Split ' +
+                        "into separate queries, or use `relationLoadStrategy: 'batched'` (one flat statement per " +
+                        'relation, no per-parent re-evaluation). Dev-only: silent under `NODE_ENV=production`.');
                 }
             }
         }
@@ -1974,8 +2002,11 @@ 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. ` +
-            'Pass `limit`, or silence with `warnOnUnlimited: false` (per call, per table, or in config).');
+        console.warn(`[turbine] warning: findMany on "${this.table}" has no limit: the statement is emitted with no row limit, ` +
+            'so the engine returns every matching row and the driver materializes all of them as objects before ' +
+            'this call resolves (the cost grows with the table, not with the rows you use). Pass `limit`/`take`, ' +
+            'or set `defaultLimit` in the client config; silence with `warnOnUnlimited: false` (per call, per ' +
+            'table, or in config).');
     }
     /**
      * Whether `where` can match at most one row, because it pins every column of
@@ -2819,28 +2850,24 @@ export class QueryInterface {
         console.warn(`[turbine] relationLoadStrategy: 'flatten' did not engage on "${this.table}": ${reason}. ` +
             'Every relation loads via the correlated subquery instead (same rows, same values, different plan).');
     }
-    /** Convert camelCase field name to snake_case column name (unquoted, for non-SQL uses) */
+    /**
+     * Convert a field name to its snake_case column name (unquoted, for non-SQL
+     * uses), throwing E003 when the key names no column.
+     *
+     * The resolution rule itself lives in {@link resolveColumnName} (query/utils.ts)
+     * so the value-side passes that must NOT throw, write coercion above all, can
+     * share it instead of re-deriving it. Accepting `camelToSnake(field)` only
+     * when it is a real column preserves the convenience of writing `userId` when
+     * the schema exposes `user_id` under an unusual field name (and of writing the
+     * column name outright), while rejecting arbitrary strings, closing the
+     * defense-in-depth gap for SQL injection and catching typos like
+     * `where: { emial: 'x' }` with a clear error instead of a cryptic Postgres
+     * "column does not exist".
+     */
     toColumn(field) {
-        // Prototype-safe lookup: a plain-object `columnMap` would otherwise return
-        // an inherited member (e.g. Object.prototype.constructor) for a field named
-        // "constructor" / "toString" / "__proto__", bypassing the unknown-field
-        // check below and returning a non-string as the column name.
-        const mapped = ownLookup(this.tableMeta.columnMap, field);
-        if (mapped)
-            return mapped;
-        // Fall back to camelToSnake ONLY if that snake_cased name also exists as a
-        // real column on the table. This preserves the convenience of writing
-        // `userId` when the schema exposes `user_id` under an unusual field name,
-        // but rejects arbitrary strings, closing the defense-in-depth gap for
-        // SQL injection and catching typos like `where: { emial: 'x' }` with a
-        // clear error instead of a cryptic Postgres "column does not exist".
-        const snake = camelToSnake(field);
-        if (this.tableMeta.reverseColumnMap && ownLookup(this.tableMeta.reverseColumnMap, snake)) {
-            return snake;
-        }
-        if (this.tableMeta.allColumns?.includes(snake)) {
-            return snake;
-        }
+        const column = resolveColumnName(this.tableMeta, field);
+        if (column)
+            return column;
         throw new ValidationError(unknownFieldMessage(this.table, field, this.tableMeta));
     }
     /** Convert camelCase field name to a double-quoted SQL identifier */