turbine-orm 0.28.3 → 0.30.0

package/dist/cjs/query/builder.js

@@ -97,6 +97,12 @@ 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();
     /**
@@ -134,9 +140,19 @@ 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[(0, schema_js_1.snakeToCamel)(table)]) !== false
+                : warnOpt !== false;
         this.utcTimestamps = options?.utcTimestamps !== false;
         this.preparedStatementsEnabled = options?.preparedStatements ?? true;
         this.sqlCacheEnabled = options?.sqlCache !== false;
@@ -152,9 +168,12 @@ 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. */
@@ -680,10 +699,16 @@ 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;
@@ -694,7 +719,7 @@ 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.
@@ -1043,7 +1068,8 @@ 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,
@@ -1125,7 +1151,13 @@ 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,
@@ -1399,7 +1431,8 @@ 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));
@@ -1407,7 +1440,7 @@ 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;
         });
@@ -2087,6 +2120,10 @@ 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 &&
@@ -2101,7 +2138,7 @@ 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)) {
@@ -2129,7 +2166,7 @@ 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
@@ -2228,10 +2265,10 @@ 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) && (0, filters_js_1.isJsonFilter)(value)) {
-                const jKeys = Object.keys(value).sort();
-                parts.push(`${key}:json(${jKeys.join(',')})`);
+                parts.push(`${key}:${(0, filters_js_1.fingerprintJsonFilterShape)(value)}`);
                 continue;
             }
             // Array filter
@@ -2317,6 +2354,15 @@ class QueryInterface {
             else if ((0, filters_js_1.isWhereOperator)(value)) {
                 parts.push(`${key}:${(0, filters_js_1.fingerprintOperatorShape)(value)}`);
             }
+            else if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.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}:${(0, filters_js_1.fingerprintJsonFilterShape)(value)}`);
+            }
+            else if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isArrayFilter)(value)) {
+                parts.push(`${key}:arr(${this.fingerprintArrayFilter(value)})`);
+            }
             else if ((0, filters_js_1.isUnmatchedPlainObject)(value)) {
                 parts.push(`${key}:obj(${Object.keys(value)
                     .sort()
@@ -2394,7 +2440,7 @@ class QueryInterface {
             if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isJsonFilter)(value)) {
                 const colType = this.getColumnPgType(rawColumn);
                 if (colType === 'json' || colType === 'jsonb') {
-                    this.collectJsonFilterParams(value, params);
+                    this.collectJsonFilterParams(value, params, this.q(rawColumn));
                     continue;
                 }
             }
@@ -2495,6 +2541,24 @@ class QueryInterface {
                 }
             }
             const col = meta.columnMap[field] ?? (0, schema_js_1.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) && (0, filters_js_1.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) && (0, filters_js_1.isArrayFilter)(value)) {
+                const colType = this.pgTypeForColumn(meta, col);
+                if (colType.startsWith('_')) {
+                    this.collectArrayFilterParams(value, params);
+                    continue;
+                }
+            }
             if ((0, filters_js_1.isWhereOperator)(value)) {
                 this.collectOperatorParams(col, value, params);
                 continue;
@@ -2530,10 +2594,22 @@ class QueryInterface {
         if (op.endsWith !== undefined)
             params.push(`%${(0, utils_js_1.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) {
@@ -2545,6 +2621,10 @@ 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) {
@@ -3264,6 +3344,35 @@ 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) && (0, filters_js_1.isJsonFilter)(value)) {
+                const colType = this.pgTypeForColumn(meta, col);
+                if (colType === 'json' || colType === 'jsonb') {
+                    conditions.push(...this.buildJsonFilterClauses(qCol, value, params));
+                    continue;
+                }
+                const jsonKey = (0, filters_js_1.findJsonUniqueKey)(value);
+                if (jsonKey) {
+                    throw new errors_js_1.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) && (0, filters_js_1.isArrayFilter)(value)) {
+                const colType = this.pgTypeForColumn(meta, col);
+                if (colType.startsWith('_')) {
+                    conditions.push(...this.buildArrayFilterClauses(qCol, value, params, colType));
+                    continue;
+                }
+                const arrayKey = (0, filters_js_1.findArrayUniqueKey)(value);
+                if (arrayKey) {
+                    throw new errors_js_1.ValidationError(`[turbine] Column "${col}" on table "${targetTable}" is not an array column ` +
+                        `(actual type: ${colType}); cannot apply array operator '${arrayKey}'.`);
+                }
+            }
             if ((0, filters_js_1.isWhereOperator)(value)) {
                 const opClauses = this.buildOperatorClauses(qCol, value, params);
                 conditions.push(...opClauses);
@@ -3282,6 +3391,49 @@ 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
@@ -3360,6 +3512,34 @@ 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) && (0, filters_js_1.isJsonFilter)(value)) {
+                const colType = this.pgTypeForColumn(targetMeta, col);
+                if (colType === 'json' || colType === 'jsonb') {
+                    clauses.push(...this.buildJsonFilterClauses(qCol, value, params));
+                    continue;
+                }
+                const jsonKey = (0, filters_js_1.findJsonUniqueKey)(value);
+                if (jsonKey) {
+                    throw new errors_js_1.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) && (0, filters_js_1.isArrayFilter)(value)) {
+                const colType = this.pgTypeForColumn(targetMeta, col);
+                if (colType.startsWith('_')) {
+                    clauses.push(...this.buildArrayFilterClauses(qCol, value, params, colType));
+                    continue;
+                }
+                const arrayKey = (0, filters_js_1.findArrayUniqueKey)(value);
+                if (arrayKey) {
+                    throw new errors_js_1.ValidationError(`[turbine] Column "${col}" on table "${targetTable}" is not an array column ` +
+                        `(actual type: ${colType}); cannot apply array operator '${arrayKey}'.`);
+                }
+            }
             if ((0, filters_js_1.isWhereOperator)(value)) {
                 clauses.push(...this.buildOperatorClauses(qCol, value, params));
                 continue;
@@ -3403,6 +3583,22 @@ class QueryInterface {
                 }
             }
             const col = targetMeta.columnMap[key] ?? (0, schema_js_1.camelToSnake)(key);
+            // JSONB filter — mirrors buildAliasWhere.
+            if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.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) && (0, filters_js_1.isArrayFilter)(value)) {
+                const colType = this.pgTypeForColumn(targetMeta, col);
+                if (colType.startsWith('_')) {
+                    this.collectArrayFilterParams(value, params);
+                    continue;
+                }
+            }
             if ((0, filters_js_1.isWhereOperator)(value)) {
                 this.collectOperatorParams(col, value, params);
                 continue;
@@ -3461,6 +3657,16 @@ class QueryInterface {
                 parts.push(`${key}:${(0, filters_js_1.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) && (0, filters_js_1.isJsonFilter)(value)) {
+                parts.push(`${key}:${(0, filters_js_1.fingerprintJsonFilterShape)(value)}`);
+                continue;
+            }
+            if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isArrayFilter)(value)) {
+                parts.push(`${key}:arr(${this.fingerprintArrayFilter(value)})`);
+                continue;
+            }
             if ((0, filters_js_1.isUnmatchedPlainObject)(value)) {
                 parts.push(`${key}:obj(${Object.keys(value)
                     .sort()
@@ -4685,18 +4891,59 @@ 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(filters_js_1.JSON_RANGE_OPERATORS)) {
+            const value = filter[op];
+            if (value === undefined)
+                continue;
+            if (filter.path === undefined) {
+                throw new errors_js_1.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 errors_js_1.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 errors_js_1.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
@@ -4713,8 +4960,28 @@ 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/cjs/query/filters.js

@@ -7,13 +7,14 @@
  * and execution rather than filter-shape bookkeeping.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VECTOR_DISTANCE_COMPARATORS = exports.VECTOR_METRIC_OPERATORS = exports.TEXT_SEARCH_KEYS = exports.ARRAY_UNIQUE_KEYS = exports.ARRAY_OPERATOR_KEYS = exports.JSONB_UNIQUE_KEYS = exports.JSONB_OPERATOR_KEYS = exports.UPDATE_OPERATOR_KEYS = void 0;
+exports.VECTOR_DISTANCE_COMPARATORS = exports.VECTOR_METRIC_OPERATORS = exports.TEXT_SEARCH_KEYS = exports.ARRAY_UNIQUE_KEYS = exports.ARRAY_OPERATOR_KEYS = exports.JSONB_UNIQUE_KEYS = exports.JSON_RANGE_OPERATORS = exports.JSONB_OPERATOR_KEYS = exports.UPDATE_OPERATOR_KEYS = void 0;
 exports.isWhereOperator = isWhereOperator;
 exports.isUnmatchedPlainObject = isUnmatchedPlainObject;
 exports.fingerprintOperatorShape = fingerprintOperatorShape;
 exports.assertBindableEqualsOperand = assertBindableEqualsOperand;
 exports.sortedKeys = sortedKeys;
 exports.sortedEntries = sortedEntries;
+exports.fingerprintJsonFilterShape = fingerprintJsonFilterShape;
 exports.isJsonFilter = isJsonFilter;
 exports.findJsonUniqueKey = findJsonUniqueKey;
 exports.isArrayFilter = isArrayFilter;
@@ -109,6 +110,36 @@ function sortedEntries(obj) {
 exports.UPDATE_OPERATOR_KEYS = new Set(['set', 'increment', 'decrement', 'multiply', 'divide']);
 /** Known JSONB operator keys */
 exports.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`.
+ */
+exports.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.
+ */
+function fingerprintJsonFilterShape(filter) {
+    const obj = filter;
+    const parts = Object.keys(obj)
+        .filter((k) => obj[k] !== undefined)
+        .sort()
+        .map((k) => (k in exports.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