turbine-orm 0.52.0 → 0.53.0

package/dist/cjs/query/aggregates.js

@@ -126,6 +126,12 @@ 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)) {
@@ -148,6 +154,7 @@ 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);
@@ -163,6 +170,9 @@ 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
@@ -258,7 +268,7 @@ 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 ')}`;
         }
@@ -502,35 +512,46 @@ 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.
  */
-function buildHavingClauses(qi, having, params, jsonAggExprs) {
+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;
@@ -539,11 +560,20 @@ 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 errors_js_1.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:
@@ -554,37 +584,147 @@ 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 = (0, utils_js_1.ownLookup)(aggFnByKey, aggKey);
-            if (!fn) {
-                throw new errors_js_1.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 (!(0, filters_js_1.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 = (0, utils_js_1.ownLookup)(HAVING_AGGREGATE_FNS, k);
+        if (fn) {
+            aggEntries.push({ key: k, fn, filter: v });
+        }
+        else if (k.startsWith('_')) {
+            throw new errors_js_1.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 (!(0, filters_js_1.isUnmatchedPlainObject)(condition)) {
+            throw new errors_js_1.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 errors_js_1.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 ((0, filters_js_1.isWhereOperator)(value)) {
+        clauses.push(...whereMod.buildOperatorClauses(qi, ref.expr, value, params));
+    }
+    else if ((0, filters_js_1.isUnmatchedPlainObject)(value)) {
+        throw new errors_js_1.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}.
  */
 function buildHavingNumericClauses(qi, expr, filter, params) {
-    // Bare number → equality.
-    if (typeof filter === 'number') {
+    if (filter === null) {
+        throw new errors_js_1.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 errors_js_1.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/cjs/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/cjs/query/builder.js

@@ -708,12 +708,12 @@ 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) {
@@ -1288,7 +1288,15 @@ 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;
@@ -1297,22 +1305,30 @@ 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.');
@@ -1813,12 +1829,21 @@ class QueryInterface {
                 const v = whereObj[k];
                 return v !== null && !(0, filters_js_1.isWhereOperator)(v) && !(0, utils_js_1.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 ')}` : '';
@@ -1826,9 +1851,9 @@ 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 {
@@ -1905,8 +1930,11 @@ class QueryInterface {
             if (args?.with) {
                 const depth = this.measureWithDepth(args.with);
                 if (depth > 5 && (0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.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`.');
                 }
             }
         }
@@ -2010,8 +2038,11 @@ 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
@@ -2855,28 +2886,24 @@ 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 = (0, utils_js_1.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 = (0, schema_js_1.camelToSnake)(field);
-        if (this.tableMeta.reverseColumnMap && (0, utils_js_1.ownLookup)(this.tableMeta.reverseColumnMap, snake)) {
-            return snake;
-        }
-        if (this.tableMeta.allColumns?.includes(snake)) {
-            return snake;
-        }
+        const column = (0, utils_js_1.resolveColumnName)(this.tableMeta, field);
+        if (column)
+            return column;
         throw new errors_js_1.ValidationError((0, utils_js_1.unknownFieldMessage)(this.table, field, this.tableMeta));
     }
     /** Convert camelCase field name to a double-quoted SQL identifier */

package/dist/cjs/query/types.d.ts

@@ -718,23 +718,29 @@ export interface CountArgs<T, R extends object = {}> {
     skipGlobalFilters?: SkipGlobalFilters;
 }
 /**
- * Numeric comparison operators usable inside a `having` filter. A bare number
+ * Comparison operators usable inside a `having` aggregate filter. A bare value
  * is shorthand for equality (`COUNT(*) = $n`); the operator object supports
- * range and inequality comparisons. Mirrors the numeric subset of
+ * range and inequality comparisons. Mirrors the comparison subset of
  * {@link WhereOperator} so the same SQL machinery can be reused.
+ *
+ * `V` is the operand type: `number` for `_sum` / `_avg` / `_count`, the
+ * column's own type for `_min` / `_max` (those return a stored cell, so
+ * `MIN("title") > 'm'` is as valid as `MIN("views") > 10`).
  */
-export interface HavingNumericOperator {
-    equals?: number;
-    not?: number;
-    gt?: number;
-    gte?: number;
-    lt?: number;
-    lte?: number;
-    in?: number[];
-    notIn?: number[];
+export interface HavingComparisonOperator<V = number> {
+    equals?: V;
+    not?: V;
+    gt?: V;
+    gte?: V;
+    lt?: V;
+    lte?: V;
+    in?: V[];
+    notIn?: V[];
 }
-/** A single having predicate value: a bare number (equality) or an operator object. */
-export type HavingFilter = number | HavingNumericOperator;
+/** The number-operand spelling, kept as the historical public name. */
+export type HavingNumericOperator = HavingComparisonOperator<number>;
+/** A single having predicate value: a bare value (equality) or an operator object. */
+export type HavingFilter<V = number> = V | HavingComparisonOperator<V>;
 /**
  * Per-field aggregate filters inside a {@link HavingClause}. Each aggregate
  * function maps to a {@link HavingFilter} comparison on that field.
@@ -742,33 +748,52 @@ export type HavingFilter = number | HavingNumericOperator;
  * @example
  *   viewCount: { _sum: { gt: 100 }, _avg: { lte: 50 } }
  */
-export interface HavingAggregateFilter {
+export interface HavingAggregateFilter<V = unknown> {
     _sum?: HavingFilter;
     _avg?: HavingFilter;
-    _min?: HavingFilter;
-    _max?: HavingFilter;
+    _min?: HavingFilter<V>;
+    _max?: HavingFilter<V>;
     _count?: HavingFilter;
 }
+/**
+ * One field entry of a {@link HavingClause}. Following Prisma, a field accepts
+ * BOTH an aggregate filter (`{ _sum: { gt: 100 } }`) and a scalar filter on the
+ * grouped value itself (`{ not: null }`, `{ in: ['a', 'b'] }`, or a bare value
+ * as equality shorthand), including both in the same object, which are ANDed.
+ *
+ * A scalar filter is only legal on a column listed in `by`: the group's value
+ * is constant within the group, so it compiles into HAVING against the bare
+ * group key. On any other column it throws {@link ValidationError} E003, since
+ * a non-grouped column cannot be referenced in HAVING at all.
+ */
+export type HavingFieldFilter<V = unknown> = (HavingAggregateFilter<V> & WhereOperator<V>) | WhereValue<V>;
 /**
  * HAVING clause for `groupBy`, filters whole groups by their aggregate values
- * (the SQL `HAVING` clause). Follows Prisma's shape: each aggregable field maps
- * to a {@link HavingAggregateFilter} (`field → aggregate → operator → value`),
- * and the special top-level `_count` key (no field) filters on `COUNT(*)`.
+ * and by the grouped values themselves (the SQL `HAVING` clause). Follows
+ * Prisma's shape: each field maps to a {@link HavingFieldFilter}, the special
+ * top-level `_count` key (no field) filters on `COUNT(*)`, and `AND` / `OR` /
+ * `NOT` combine predicates at any depth.
  *
- * Implemented as a mapped type so the special `_count` key can carry a
- * {@link HavingFilter} while every entity field carries a
- * {@link HavingAggregateFilter}, without the index-signature conflict an
- * intersection type would produce when `T` is a broad `Record<string, unknown>`.
+ * Implemented as a mapped type so the special keys can carry their own value
+ * types while every entity field carries a {@link HavingFieldFilter}, without
+ * the index-signature conflict an intersection type would produce when `T` is
+ * a broad `Record<string, unknown>`.
  *
  * @example
  *   // groups with more than 5 rows whose summed viewCount is at least 100
  *   having: { _count: { gt: 5 }, viewCount: { _sum: { gte: 100 } } }
+ * @example
+ *   // by: ['typeId'] , drop the NULL group, keep busy groups
+ *   having: { typeId: { not: null }, _count: { gt: 1 } }
  */
 export type HavingClause<T> = {
     /** Filter on `COUNT(*)` for the whole group. */
     _count?: HavingFilter;
+    AND?: HavingClause<T> | HavingClause<T>[];
+    OR?: HavingClause<T>[];
+    NOT?: HavingClause<T> | HavingClause<T>[];
 } & {
-    [K in keyof T & string]?: HavingAggregateFilter;
+    [K in keyof T & string]?: HavingFieldFilter<T[K]>;
 };
 /**
  * A JSON-path group key in {@link GroupByArgs.by}: groups by the value