turbine-orm 0.28.3 → 0.30.0

package/dist/query/builder.js

@@ -16,7 +16,7 @@ import { missingIndexForRelation } from '../index-advisor.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '../nested-write.js';
 import { camelToSnake, normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import { includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, resolveCountRelations, stripFields, } from './batched-loader.js';
-import { assertBindableEqualsOperand, findArrayUniqueKey, findJsonUniqueKey, fingerprintOperatorShape, isArrayFilter, isJsonFilter, isOrderBySpec, isTextSearchFilter, isUnmatchedPlainObject, isVectorFilter, isVectorOrderBy, isWhereOperator, normalizeOrderBy, sortedEntries, sortedKeys, UPDATE_OPERATOR_KEYS, VECTOR_DISTANCE_COMPARATORS, VECTOR_METRIC_OPERATORS, validateTextSearchConfig, } from './filters.js';
+import { assertBindableEqualsOperand, findArrayUniqueKey, findJsonUniqueKey, fingerprintJsonFilterShape, fingerprintOperatorShape, isArrayFilter, isJsonFilter, isOrderBySpec, isTextSearchFilter, isUnmatchedPlainObject, isVectorFilter, isVectorOrderBy, isWhereOperator, JSON_RANGE_OPERATORS, normalizeOrderBy, sortedEntries, sortedKeys, UPDATE_OPERATOR_KEYS, VECTOR_DISTANCE_COMPARATORS, VECTOR_METRIC_OPERATORS, validateTextSearchConfig, } from './filters.js';
 import { escapeLike, LRUCache, OPERATOR_KEYS, parseDbDate, sqlToPreparedName } from './utils.js';
 /** Relations already warned about missing FK indexes (once per process, dev only). */
 const unindexedRelationWarned = new Set();
@@ -61,6 +61,12 @@ export class QueryInterface {
     /** Pre-computed column type lookups (avoids linear scans per query) */
     columnPgTypeMap;
     columnArrayTypeMap;
+    /**
+     * Columns whose type lives in a DIFFERENT schema than the introspected one
+     * (ColumnMetadata.pgTypeSchema is recorded only in that case) — such columns
+     * must never receive this schema's `::"enum"` cast (see enumTypeForColumn).
+     */
+    crossSchemaTypeColumns;
     /** Tracks tables that have already triggered a deep-with warning (one-time) */
     deepWithWarned = new Set();
     /**
@@ -98,9 +104,19 @@ export class QueryInterface {
         this.middlewares = middlewares ?? [];
         this.defaultLimit = options?.defaultLimit;
         // Default to ON: surfacing accidental full-table scans is more valuable
-        // than the (small) risk of noisy logs. Callers explicitly opt out with
-        // `warnOnUnlimited: false`.
-        this.warnOnUnlimited = options?.warnOnUnlimited !== false;
+        // than the (small) risk of noisy logs. Callers opt out globally with
+        // `warnOnUnlimited: false`, per table with `warnOnUnlimited: { users:
+        // false }` (unlisted tables keep the default), or per call via
+        // `findMany({ warnOnUnlimited: false })`.
+        // Per-table maps accept BOTH key forms — the snake_case table name
+        // (`user_profiles`) and the camelCase accessor (`userProfiles`) — since
+        // users naturally key by the accessor they type everywhere else. The
+        // snake_case entry wins when both are present.
+        const warnOpt = options?.warnOnUnlimited;
+        this.warnOnUnlimited =
+            typeof warnOpt === 'object' && warnOpt !== null
+                ? (warnOpt[table] ?? warnOpt[snakeToCamel(table)]) !== false
+                : warnOpt !== false;
         this.utcTimestamps = options?.utcTimestamps !== false;
         this.preparedStatementsEnabled = options?.preparedStatements ?? true;
         this.sqlCacheEnabled = options?.sqlCache !== false;
@@ -116,9 +132,12 @@ export class QueryInterface {
         // Pre-compute column type lookup maps (TASK-26)
         this.columnPgTypeMap = new Map();
         this.columnArrayTypeMap = new Map();
+        this.crossSchemaTypeColumns = new Set();
         for (const col of this.tableMeta.columns) {
             this.columnPgTypeMap.set(col.name, col.dialectType ?? col.pgType);
             this.columnArrayTypeMap.set(col.name, col.arrayType ?? col.pgArrayType);
+            if (col.pgTypeSchema !== undefined)
+                this.crossSchemaTypeColumns.add(col.name);
         }
     }
     /** Quote an identifier through the active SQL dialect. */
@@ -644,10 +663,16 @@ export class QueryInterface {
      * loop calling `db.users.findMany()` thousands of times only logs once.
      * Suppressed when `defaultLimit` is configured (the caller has already
      * opted in to a bounded query) and when the user passed an explicit
-     * `limit`, `take`, or `cursor`.
+     * `limit`, `take`, or `cursor`. A per-call `warnOnUnlimited` overrides the
+     * config-level setting in either direction (`false` silences a call that
+     * intentionally reads the full set; `true` forces the warning even when
+     * disabled in config).
      */
     maybeWarnUnlimited(args) {
-        if (!this.warnOnUnlimited)
+        const perCall = args?.warnOnUnlimited;
+        if (perCall === false)
+            return;
+        if (perCall === undefined && !this.warnOnUnlimited)
             return;
         if (this.defaultLimit !== undefined)
             return;
@@ -658,7 +683,7 @@ export class QueryInterface {
             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 set `warnOnUnlimited: false` in config to silence.');
+            'Pass `limit`, or silence with `warnOnUnlimited: false` (per call, per table, or in config).');
     }
     /**
      * Recursively measure the maximum depth of a `with` clause tree.
@@ -1007,7 +1032,8 @@ export class QueryInterface {
         const entries = Object.entries(args.data).filter(([, v]) => v !== undefined);
         const columns = entries.map(([k]) => this.toSqlColumn(k));
         const params = entries.map(([, v]) => v);
-        const placeholders = entries.map((_, i) => `${this.p(i + 1)}`);
+        // Enum columns get an explicit `::"EnumName"` cast (see enumTypeForColumn).
+        const placeholders = entries.map(([k], i) => `${this.p(i + 1)}${this.enumCastSuffix(this.toColumn(k))}`);
         const sql = this.dialect.buildInsertStatement({
             table: this.q(this.table),
             columns,
@@ -1089,7 +1115,13 @@ export class QueryInterface {
             return keys.map((key) => record[key]);
         });
         // Use actual Postgres types for array casts in the default PostgreSQL dialect.
-        const typeCasts = columns.map((col) => this.getColumnArrayType(col));
+        // Enum columns cast to `"EnumName"[]` — the generic text[] fallback would
+        // type the UNNEST output as text, which Postgres refuses to coerce to the
+        // enum ("column X is of type Y but expression is of type text").
+        const typeCasts = columns.map((col) => {
+            const enumType = this.enumTypeForColumn(col);
+            return enumType ? `${this.q(enumType)}[]` : this.getColumnArrayType(col);
+        });
         const quotedColumns = columns.map((c) => this.q(c));
         const built = this.dialect.buildBulkInsertStatement({
             table: qt,
@@ -1363,7 +1395,8 @@ export class QueryInterface {
         const createEntries = Object.entries(args.create).filter(([, v]) => v !== undefined);
         const columns = createEntries.map(([k]) => this.toSqlColumn(k));
         const createParams = createEntries.map(([, v]) => v);
-        const placeholders = createEntries.map((_, i) => `${this.p(i + 1)}`);
+        // Enum columns get an explicit `::"EnumName"` cast (see enumTypeForColumn).
+        const placeholders = createEntries.map(([k], i) => `${this.p(i + 1)}${this.enumCastSuffix(this.toColumn(k))}`);
         // The conflict target comes from `where` keys — must be unique/PK columns
         const conflictKeys = Object.keys(args.where).filter((k) => args.where[k] !== undefined);
         const conflictColumns = conflictKeys.map((k) => this.toSqlColumn(k));
@@ -1371,7 +1404,7 @@ export class QueryInterface {
         const updateEntries = Object.entries(args.update).filter(([, v]) => v !== undefined);
         let paramIdx = createParams.length + 1;
         const setClauses = updateEntries.map(([k]) => {
-            const clause = `${this.toSqlColumn(k)} = ${this.p(paramIdx)}`;
+            const clause = `${this.toSqlColumn(k)} = ${this.p(paramIdx)}${this.enumCastSuffix(this.toColumn(k))}`;
             paramIdx++;
             return clause;
         });
@@ -2051,6 +2084,10 @@ export class QueryInterface {
      */
     buildSetClause(key, value, params) {
         const col = this.toSqlColumn(key);
+        // Enum columns get an explicit `::"EnumName"` cast on their value bind
+        // (see enumTypeForColumn); `''` everywhere else. Value-invariant, so the
+        // SQL cache and collectSetParams are unaffected.
+        const cast = this.enumCastSuffix(this.toColumn(key));
         // Detect atomic-operator object: plain object (not null, not array, not
         // Date, not Buffer) with EXACTLY one key matching an operator name.
         if (value !== null &&
@@ -2065,7 +2102,7 @@ export class QueryInterface {
                 const opValue = v[op];
                 if (op === 'set') {
                     params.push(opValue);
-                    return `${col} = ${this.p(params.length)}`;
+                    return `${col} = ${this.p(params.length)}${cast}`;
                 }
                 // Arithmetic operators: must be finite numbers
                 if (typeof opValue !== 'number' || !Number.isFinite(opValue)) {
@@ -2093,7 +2130,7 @@ export class QueryInterface {
         }
         // Plain value (including null, Date, Buffer, arrays, JSON objects)
         params.push(value);
-        return `${col} = ${this.p(params.length)}`;
+        return `${col} = ${this.p(params.length)}${cast}`;
     }
     // =========================================================================
     // Fingerprinting — value-invariant shape keys for SQL cache lookup
@@ -2192,10 +2229,10 @@ export class QueryInterface {
                 parts.push(`${key}:vec(${dist.metric},${cmps})`);
                 continue;
             }
-            // JSON filter
+            // JSON filter — range ops carry a numeric/string annotation because the
+            // numeric compile emits a cast (different SQL shape).
             if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
-                const jKeys = Object.keys(value).sort();
-                parts.push(`${key}:json(${jKeys.join(',')})`);
+                parts.push(`${key}:${fingerprintJsonFilterShape(value)}`);
                 continue;
             }
             // Array filter
@@ -2281,6 +2318,15 @@ export class QueryInterface {
             else if (isWhereOperator(value)) {
                 parts.push(`${key}:${fingerprintOperatorShape(value)}`);
             }
+            else if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
+                // Mirrors fingerprintWhere: JSON filters inside relation sub-wheres
+                // build real JSON clauses (buildSubWhereForRelation), so their shape
+                // must be cache-distinct from plain equality.
+                parts.push(`${key}:${fingerprintJsonFilterShape(value)}`);
+            }
+            else if (typeof value === 'object' && !Array.isArray(value) && isArrayFilter(value)) {
+                parts.push(`${key}:arr(${this.fingerprintArrayFilter(value)})`);
+            }
             else if (isUnmatchedPlainObject(value)) {
                 parts.push(`${key}:obj(${Object.keys(value)
                     .sort()
@@ -2358,7 +2404,7 @@ export class QueryInterface {
             if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
                 const colType = this.getColumnPgType(rawColumn);
                 if (colType === 'json' || colType === 'jsonb') {
-                    this.collectJsonFilterParams(value, params);
+                    this.collectJsonFilterParams(value, params, this.q(rawColumn));
                     continue;
                 }
             }
@@ -2459,6 +2505,24 @@ export class QueryInterface {
                 }
             }
             const col = meta.columnMap[field] ?? camelToSnake(field);
+            // JSONB filter — mirrors buildSubWhereForRelation (which mirrors the
+            // top-level buildWhereClause): route to the JSON param collector when
+            // the target column is json/jsonb.
+            if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
+                const colType = this.pgTypeForColumn(meta, col);
+                if (colType === 'json' || colType === 'jsonb') {
+                    this.collectJsonFilterParams(value, params, `${this.q(targetTable)}.${this.q(col)}`);
+                    continue;
+                }
+            }
+            // Array filter — mirrors buildSubWhereForRelation.
+            if (typeof value === 'object' && !Array.isArray(value) && isArrayFilter(value)) {
+                const colType = this.pgTypeForColumn(meta, col);
+                if (colType.startsWith('_')) {
+                    this.collectArrayFilterParams(value, params);
+                    continue;
+                }
+            }
             if (isWhereOperator(value)) {
                 this.collectOperatorParams(col, value, params);
                 continue;
@@ -2494,10 +2558,22 @@ export class QueryInterface {
         if (op.endsWith !== undefined)
             params.push(`%${escapeLike(op.endsWith)}`);
     }
-    /** Collect params from JSON filter. Mirrors buildJsonFilterClauses. */
-    collectJsonFilterParams(filter, params) {
+    /**
+     * Collect params from JSON filter. Mirrors buildJsonFilterClauses exactly:
+     * the `path` is bound at most once (its placeholder is shared by every
+     * extraction clause), then equals/contains/hasKey values, then the range
+     * comparison values in {@link JSON_RANGE_OPERATORS} order.
+     */
+    collectJsonFilterParams(filter, params, column) {
+        let pathPushed = false;
+        const pushPathOnce = () => {
+            if (!pathPushed) {
+                params.push(filter.path);
+                pathPushed = true;
+            }
+        };
         if (filter.path !== undefined && filter.equals !== undefined) {
-            params.push(filter.path);
+            pushPathOnce();
             params.push(String(filter.equals));
         }
         else if (filter.equals !== undefined) {
@@ -2509,6 +2585,10 @@ export class QueryInterface {
         if (filter.hasKey !== undefined) {
             params.push(filter.hasKey);
         }
+        for (const { value } of this.jsonRangeEntries(filter, column)) {
+            pushPathOnce();
+            params.push(value);
+        }
     }
     /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
     collectArrayFilterParams(filter, params) {
@@ -3228,6 +3308,35 @@ export class QueryInterface {
                 conditions.push(`${qCol} IS NULL`);
                 continue;
             }
+            // JSONB filter on a json/jsonb column of the relation target — mirrors
+            // the top-level WHERE path (buildWhereClause). Without this branch the
+            // filter object used to fall through to plain equality and bind as a
+            // jsonb value, silently matching nothing.
+            if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
+                const colType = this.pgTypeForColumn(meta, col);
+                if (colType === 'json' || colType === 'jsonb') {
+                    conditions.push(...this.buildJsonFilterClauses(qCol, value, params));
+                    continue;
+                }
+                const jsonKey = findJsonUniqueKey(value);
+                if (jsonKey) {
+                    throw new ValidationError(`[turbine] Column "${col}" on table "${targetTable}" is not a JSON column ` +
+                        `(actual type: ${colType}); cannot apply JSON operator '${jsonKey}'.`);
+                }
+            }
+            // Array filter on an array column of the relation target — same mirror.
+            if (typeof value === 'object' && !Array.isArray(value) && isArrayFilter(value)) {
+                const colType = this.pgTypeForColumn(meta, col);
+                if (colType.startsWith('_')) {
+                    conditions.push(...this.buildArrayFilterClauses(qCol, value, params, colType));
+                    continue;
+                }
+                const arrayKey = findArrayUniqueKey(value);
+                if (arrayKey) {
+                    throw new ValidationError(`[turbine] Column "${col}" on table "${targetTable}" is not an array column ` +
+                        `(actual type: ${colType}); cannot apply array operator '${arrayKey}'.`);
+                }
+            }
             if (isWhereOperator(value)) {
                 const opClauses = this.buildOperatorClauses(qCol, value, params);
                 conditions.push(...opClauses);
@@ -3246,6 +3355,49 @@ export class QueryInterface {
     pgTypeForColumn(meta, column) {
         return meta.dialectTypes?.[column] ?? meta.pgTypes?.[column] ?? 'text';
     }
+    /**
+     * The Postgres enum type name for a column, when the schema knows one.
+     *
+     * Introspection stores each column's `udt_name` in `pgTypes` and every
+     * database enum in `schema.enums` (typname → labels); a column whose type
+     * matches an enum key needs an explicit `::"EnumName"` cast on its write
+     * binds — bulk-insert forms like `UNNEST($1::text[])` otherwise type the
+     * value as text and Postgres refuses the implicit text→enum coercion
+     * ("column X is of type Y but expression is of type text").
+     *
+     * Postgres-only by construction: gated on the active dialect being
+     * `postgresql` AND on `schema.enums` having entries (only PG introspection
+     * produces them — `defineSchema` and the other engines leave it empty), so
+     * SQLite/MySQL/MSSQL/PowDB output is byte-identical.
+     */
+    enumTypeForColumn(column) {
+        if (this.dialect.name !== 'postgresql')
+            return null;
+        const enums = this.schema.enums;
+        if (!enums)
+            return null;
+        // Cross-schema guard (N-5): introspection records pgTypeSchema ONLY when
+        // the column's type lives OUTSIDE the introspected schema. A same-named
+        // enum in another schema must not get this schema's cast — search_path
+        // would resolve `::"status"` to the wrong type. Skipping the cast restores
+        // the pre-cast behavior for such columns. Columns without pgTypeSchema
+        // (same-schema types, defineSchema/legacy metadata) keep the cast.
+        if (this.crossSchemaTypeColumns.has(column))
+            return null;
+        const pgType = this.columnPgTypeMap.get(column) ?? this.tableMeta.pgTypes?.[column];
+        if (!pgType || pgType.startsWith('_'))
+            return null;
+        return Object.hasOwn(enums, pgType) ? pgType : null;
+    }
+    /**
+     * `::"EnumName"` cast suffix for a write-bind placeholder on an enum
+     * column; `''` for every other column, so non-enum SQL stays byte-identical.
+     * The type name is an introspected identifier and is quoted via the dialect.
+     */
+    enumCastSuffix(column) {
+        const enumType = this.enumTypeForColumn(column);
+        return enumType ? `::${this.q(enumType)}` : '';
+    }
     /**
      * Equality-fallthrough guard shared by every SQL-build path AND every
      * cache-hit param-collect path. A plain object literal that matched no known
@@ -3324,6 +3476,34 @@ export class QueryInterface {
                 clauses.push(`${qCol} IS NULL`);
                 continue;
             }
+            // JSONB filter on a json/jsonb column — mirrors the top-level WHERE path
+            // (buildWhereClause) so a `with.where` JSON filter is never silently
+            // bound as a plain equality value.
+            if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
+                const colType = this.pgTypeForColumn(targetMeta, col);
+                if (colType === 'json' || colType === 'jsonb') {
+                    clauses.push(...this.buildJsonFilterClauses(qCol, value, params));
+                    continue;
+                }
+                const jsonKey = findJsonUniqueKey(value);
+                if (jsonKey) {
+                    throw new ValidationError(`[turbine] Column "${col}" on table "${targetTable}" is not a JSON column ` +
+                        `(actual type: ${colType}); cannot apply JSON operator '${jsonKey}'.`);
+                }
+            }
+            // Array filter on an array column — same mirror.
+            if (typeof value === 'object' && !Array.isArray(value) && isArrayFilter(value)) {
+                const colType = this.pgTypeForColumn(targetMeta, col);
+                if (colType.startsWith('_')) {
+                    clauses.push(...this.buildArrayFilterClauses(qCol, value, params, colType));
+                    continue;
+                }
+                const arrayKey = findArrayUniqueKey(value);
+                if (arrayKey) {
+                    throw new ValidationError(`[turbine] Column "${col}" on table "${targetTable}" is not an array column ` +
+                        `(actual type: ${colType}); cannot apply array operator '${arrayKey}'.`);
+                }
+            }
             if (isWhereOperator(value)) {
                 clauses.push(...this.buildOperatorClauses(qCol, value, params));
                 continue;
@@ -3367,6 +3547,22 @@ export class QueryInterface {
                 }
             }
             const col = targetMeta.columnMap[key] ?? camelToSnake(key);
+            // JSONB filter — mirrors buildAliasWhere.
+            if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
+                const colType = this.pgTypeForColumn(targetMeta, col);
+                if (colType === 'json' || colType === 'jsonb') {
+                    this.collectJsonFilterParams(value, params, this.q(col));
+                    continue;
+                }
+            }
+            // Array filter — mirrors buildAliasWhere.
+            if (typeof value === 'object' && !Array.isArray(value) && isArrayFilter(value)) {
+                const colType = this.pgTypeForColumn(targetMeta, col);
+                if (colType.startsWith('_')) {
+                    this.collectArrayFilterParams(value, params);
+                    continue;
+                }
+            }
             if (isWhereOperator(value)) {
                 this.collectOperatorParams(col, value, params);
                 continue;
@@ -3425,6 +3621,16 @@ export class QueryInterface {
                 parts.push(`${key}:${fingerprintOperatorShape(value)}`);
                 continue;
             }
+            // JSON / array filters build real clauses in buildAliasWhere, so their
+            // shape must be cache-distinct from plain equality (mirrors fingerprintWhere).
+            if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
+                parts.push(`${key}:${fingerprintJsonFilterShape(value)}`);
+                continue;
+            }
+            if (typeof value === 'object' && !Array.isArray(value) && isArrayFilter(value)) {
+                parts.push(`${key}:arr(${this.fingerprintArrayFilter(value)})`);
+                continue;
+            }
             if (isUnmatchedPlainObject(value)) {
                 parts.push(`${key}:obj(${Object.keys(value)
                     .sort()
@@ -4649,18 +4855,59 @@ export class QueryInterface {
         };
         return typeMap[baseType] ?? 'text';
     }
+    /**
+     * Validate and enumerate the range comparisons (`gt`/`gte`/`lt`/`lte`) on a
+     * JSON filter, in the fixed {@link JSON_RANGE_OPERATORS} order. Shared by
+     * the SQL-build path ({@link buildJsonFilterClauses}) and the cache-hit
+     * param-collect path ({@link collectJsonFilterParams}) so both always agree
+     * on which params are pushed — and both throw identically for invalid
+     * shapes, so a warmed cache can never skip validation.
+     */
+    jsonRangeEntries(filter, column) {
+        const entries = [];
+        for (const [op, sqlOp] of Object.entries(JSON_RANGE_OPERATORS)) {
+            const value = filter[op];
+            if (value === undefined)
+                continue;
+            if (filter.path === undefined) {
+                throw new ValidationError(`[turbine] JSON range operator '${op}' on ${column} requires a \`path\` ` +
+                    `(e.g. { path: ['meta', 'score'], ${op}: ${JSON.stringify(value)} }).`);
+            }
+            if (typeof value !== 'number' && typeof value !== 'string') {
+                throw new ValidationError(`[turbine] JSON range operator '${op}' on ${column} requires a number or string, ` +
+                    `got ${JSON.stringify(value)}.`);
+            }
+            if (typeof value === 'number' && !Number.isFinite(value)) {
+                throw new ValidationError(`[turbine] JSON range operator '${op}' on ${column} requires a finite number.`);
+            }
+            entries.push({ sqlOp, value });
+        }
+        return entries;
+    }
     /**
      * Build SQL clauses for JSONB filter operators on a column.
-     * Supports: path, equals, contains, hasKey.
+     * Supports: path, equals, contains, hasKey, gt, gte, lt, lte.
+     *
+     * The `path` param is bound at most once and its placeholder is shared by
+     * every clause that extracts it (equals + range ops), so the param list
+     * stays byte-identical to {@link collectJsonFilterParams}.
      */
     buildJsonFilterClauses(column, filter, params) {
         const clauses = [];
+        // Lazily bind the path once; reuse the same $N in every extraction clause.
+        let pathParamIdx = null;
+        const pathExtract = () => {
+            if (pathParamIdx === null) {
+                params.push(filter.path);
+                pathParamIdx = params.length;
+            }
+            return this.dialect.buildJsonPathExtract(column, this.p(pathParamIdx));
+        };
         if (filter.path !== undefined && filter.equals !== undefined) {
             // Path access + equals: column #>> $N::text[] = $M
-            params.push(filter.path);
-            const pathParam = params.length;
+            const extract = pathExtract();
             params.push(String(filter.equals));
-            clauses.push(`${this.dialect.buildJsonPathExtract(column, this.p(pathParam))} = ${this.p(params.length)}`);
+            clauses.push(`${extract} = ${this.p(params.length)}`);
         }
         else if (filter.equals !== undefined) {
             // Containment equality: column @> $N::jsonb
@@ -4677,8 +4924,28 @@ export class QueryInterface {
             params.push(filter.hasKey);
             clauses.push(`${column} ? ${this.p(params.length)}`);
         }
+        // Range comparisons on the extracted path: numbers compare numerically
+        // (cast through the dialect), strings compare as text.
+        for (const { sqlOp, value } of this.jsonRangeEntries(filter, column)) {
+            const extract = pathExtract();
+            params.push(value);
+            const lhs = typeof value === 'number' ? this.castJsonNumeric(extract) : extract;
+            clauses.push(`${lhs} ${sqlOp} ${this.p(params.length)}`);
+        }
         return clauses;
     }
+    /**
+     * Cast an extracted JSON path text value to a numeric type for range
+     * comparison. PostgreSQL uses `(expr)::numeric` (exact — the right way to
+     * compare JSON numbers, and `::float` would lose precision on big ints);
+     * other dialects route through {@link Dialect.castAggregate} (SQLite/MySQL/
+     * SQL Server have no `::` operator) as a float cast.
+     */
+    castJsonNumeric(extract) {
+        if (this.dialect.name === 'postgresql')
+            return `(${extract})::numeric`;
+        return this.dialect.castAggregate ? this.dialect.castAggregate(`(${extract})`, 'float') : `(${extract})::numeric`;
+    }
     /**
      * Build SQL clauses for Array filter operators on a column.
      * Supports: has, hasEvery, hasSome, isEmpty.

package/dist/query/deferred.d.ts

@@ -66,9 +66,14 @@ export interface QueryInterfaceOptions {
      * without a `limit`. Defaults to `true` so that accidental unbounded
      * queries are surfaced loudly during development. Pass `false` to silence
      * the warning entirely (e.g. for CLI tooling that intentionally streams
-     * full tables).
+     * full tables), or a per-table map (`{ userProfiles: false }`) to silence
+     * only the tables that intentionally read full sets — unlisted tables keep
+     * the default. Map keys accept BOTH the camelCase accessor name
+     * (`userProfiles`) and the snake_case table name (`user_profiles`); the
+     * snake_case entry wins if both are present. Individual calls can also
+     * override via `findMany({ warnOnUnlimited: false })`.
      */
-    warnOnUnlimited?: boolean;
+    warnOnUnlimited?: boolean | Record<string, boolean>;
     /**
      * Enable prepared statements. When true, queries are submitted with a
      * `{ name, text, values }` object to the pg driver, which caches the

package/dist/query/filters.d.ts

@@ -48,6 +48,24 @@ export declare function sortedEntries<V>(obj: Record<string, V>): [string, V][];
 export declare const UPDATE_OPERATOR_KEYS: Set<string>;
 /** Known JSONB operator keys */
 export declare const JSONB_OPERATOR_KEYS: Set<string>;
+/**
+ * JSON range comparison operators → SQL comparison tokens, in the FIXED order
+ * the build and collect paths iterate them. These keys are deliberately NOT in
+ * {@link JSONB_OPERATOR_KEYS}: `gt`/`gte`/`lt`/`lte` overlap with
+ * `WhereOperator`, so a bare `{ gt: 5 }` must keep its column-comparison
+ * meaning. They only compile as JSON range ops when the object is already a
+ * {@link JsonFilter} (detected via `path` / `equals` / `contains` / `hasKey`),
+ * and they always require `path`.
+ */
+export declare const JSON_RANGE_OPERATORS: Record<'gt' | 'gte' | 'lt' | 'lte', string>;
+/**
+ * Value-invariant shape fingerprint for a {@link JsonFilter}. Range operators
+ * are annotated with the comparison value's kind (`#n` numeric / `#s` string)
+ * because a numeric comparison compiles to a `::numeric` cast — a different
+ * SQL text than the text comparison — so the two must never share a cached
+ * SQL entry.
+ */
+export declare function fingerprintJsonFilterShape(filter: JsonFilter): string;
 /**
  * JSONB operator keys that are *unique* to {@link JsonFilter} — they cannot
  * appear in any other where-filter shape, so the presence of one of these is

package/dist/query/filters.js

@@ -90,6 +90,36 @@ export function sortedEntries(obj) {
 export const UPDATE_OPERATOR_KEYS = new Set(['set', 'increment', 'decrement', 'multiply', 'divide']);
 /** Known JSONB operator keys */
 export const JSONB_OPERATOR_KEYS = new Set(['path', 'equals', 'contains', 'hasKey']);
+/**
+ * JSON range comparison operators → SQL comparison tokens, in the FIXED order
+ * the build and collect paths iterate them. These keys are deliberately NOT in
+ * {@link JSONB_OPERATOR_KEYS}: `gt`/`gte`/`lt`/`lte` overlap with
+ * `WhereOperator`, so a bare `{ gt: 5 }` must keep its column-comparison
+ * meaning. They only compile as JSON range ops when the object is already a
+ * {@link JsonFilter} (detected via `path` / `equals` / `contains` / `hasKey`),
+ * and they always require `path`.
+ */
+export const JSON_RANGE_OPERATORS = {
+    gt: '>',
+    gte: '>=',
+    lt: '<',
+    lte: '<=',
+};
+/**
+ * Value-invariant shape fingerprint for a {@link JsonFilter}. Range operators
+ * are annotated with the comparison value's kind (`#n` numeric / `#s` string)
+ * because a numeric comparison compiles to a `::numeric` cast — a different
+ * SQL text than the text comparison — so the two must never share a cached
+ * SQL entry.
+ */
+export function fingerprintJsonFilterShape(filter) {
+    const obj = filter;
+    const parts = Object.keys(obj)
+        .filter((k) => obj[k] !== undefined)
+        .sort()
+        .map((k) => (k in JSON_RANGE_OPERATORS ? `${k}#${typeof obj[k] === 'number' ? 'n' : 's'}` : k));
+    return `json(${parts.join(',')})`;
+}
 /**
  * JSONB operator keys that are *unique* to {@link JsonFilter} — they cannot
  * appear in any other where-filter shape, so the presence of one of these is

package/dist/query/types.d.ts

@@ -310,6 +310,13 @@ export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClaus
     relationLoadStrategy?: RelationLoadStrategy;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
+    /**
+     * Per-call override of the unbounded-findMany warning. Pass `false` when
+     * this call intentionally reads the full table (the config-level
+     * `warnOnUnlimited` stays in effect for every other call); pass `true` to
+     * force the warning even when it is disabled in config.
+     */
+    warnOnUnlimited?: boolean;
 }
 export interface FindManyStreamArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> extends FindManyArgs<T, R, W, S, O> {
     /**
@@ -628,6 +635,18 @@ export interface JsonFilter {
     contains?: unknown;
     /** Key existence check: column ? key */
     hasKey?: string;
+    /**
+     * Greater-than comparison of the value at `path` (required). Numbers cast
+     * the extracted text to numeric — `(col #>> path)::numeric > $n` — while
+     * strings compare as text.
+     */
+    gt?: number | string;
+    /** Greater-than-or-equal comparison of the value at `path` (required). See {@link JsonFilter.gt}. */
+    gte?: number | string;
+    /** Less-than comparison of the value at `path` (required). See {@link JsonFilter.gt}. */
+    lt?: number | string;
+    /** Less-than-or-equal comparison of the value at `path` (required). See {@link JsonFilter.gt}. */
+    lte?: number | string;
 }
 /** Array query operators for where clauses */
 export interface ArrayFilter {