turbine-orm 0.29.0 → 0.31.0

package/dist/powql.d.ts

@@ -156,6 +156,12 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * it and the trailing `returning` reads it back — as is any non-string PK.
      */
     private applyPkDefault;
+    /**
+     * The table name as a PowQL type reference — backtick-quoted when it is a
+     * reserved word (e.g. a table named `order`). Used in every emitted
+     * statement; plain `this.table` stays in error messages.
+     */
+    private get qt();
     create(args: CreateArgs<T>): Promise<T>;
     createMany(args: CreateManyArgs<T>): Promise<T[]>;
     update(args: UpdateArgs<T>): Promise<T>;

package/dist/powql.js

@@ -37,9 +37,9 @@
 import { randomUUID } from 'node:crypto';
 import { NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError } from './errors.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
-import { PowdbFloatParam, powqlColumnType, rowToEntity } from './powdb.js';
+import { PowdbFloatParam, powqlColumnType, quotePowqlIdent, rowToEntity } from './powdb.js';
 import { escapeLike } from './query/utils.js';
-import { normalizeKeyColumns, } from './schema.js';
+import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
 /**
  * Max parent keys per relation-loader `in (…)` query. A `with` over a large
  * parent set is split into batches of this size so a single query never exceeds
@@ -106,7 +106,14 @@ export class PowqlInterface {
         }
         this.meta = meta;
         this.defaultLimit = options.defaultLimit;
-        this.warnOnUnlimited = options.warnOnUnlimited !== false;
+        // Same per-table resolution as QueryInterface: an object map accepts BOTH
+        // the snake_case table name and the camelCase accessor as keys (snake_case
+        // wins on conflict); unlisted tables keep the default (warn on).
+        const warnOpt = options.warnOnUnlimited;
+        this.warnOnUnlimited =
+            typeof warnOpt === 'object' && warnOpt !== null
+                ? (warnOpt[table] ?? warnOpt[snakeToCamel(table)]) !== false
+                : warnOpt !== false;
         this.onQuery = options._onQuery;
     }
     // -------------------------------------------------------------------------
@@ -411,7 +418,7 @@ export class PowqlInterface {
                 const chunk = targetPks.slice(i, i + MAX_RELATION_KEYS);
                 const params = [];
                 const ph = chunk.map((v) => this.param(v, params)).join(', ');
-                const { rows } = await this.exec(`${through.table} filter .${targetJCol} in (${ph}) { .${sourceJCol} }`, params, timeout);
+                const { rows } = await this.exec(`${quotePowqlIdent(through.table)} filter .${targetJCol} in (${ph}) { .${sourceJCol} }`, params, timeout);
                 for (const r of rows) {
                     const v = r[sourceJCol];
                     if (v != null)
@@ -563,7 +570,7 @@ export class PowqlInterface {
         }
         const limitClause = limit !== undefined ? ` limit ${this.param(limit, params)}` : '';
         const offsetClause = args.offset ? ` offset ${this.param(args.offset, params)}` : '';
-        const powql = `${this.table}${distinct}${filter}${order}${limitClause}${offsetClause} ${this.projection(cols)}`;
+        const powql = `${this.qt}${distinct}${filter}${order}${limitClause}${offsetClause} ${this.projection(cols)}`;
         const { rows } = await this.exec(powql, params, args.timeout);
         return rows;
     }
@@ -712,7 +719,7 @@ export class PowqlInterface {
             const chunk = parentKeys.slice(i, i + MAX_RELATION_KEYS);
             const params = [];
             const placeholders = chunk.map((v) => this.param(v, params)).join(', ');
-            const powql = `${through.table} filter .${sourceJCol} in (${placeholders}) { .${sourceJCol}, .${targetJCol} }`;
+            const powql = `${quotePowqlIdent(through.table)} filter .${sourceJCol} in (${placeholders}) { .${sourceJCol}, .${targetJCol} }`;
             const { rows } = await this.exec(powql, params, timeout);
             for (const row of rows) {
                 const sv = String(row[sourceJCol]);
@@ -794,6 +801,14 @@ export class PowqlInterface {
         }
         return out;
     }
+    /**
+     * The table name as a PowQL type reference — backtick-quoted when it is a
+     * reserved word (e.g. a table named `order`). Used in every emitted
+     * statement; plain `this.table` stays in error messages.
+     */
+    get qt() {
+        return quotePowqlIdent(this.table);
+    }
     async create(args) {
         return this.withMiddleware('create', args, async () => {
             if (hasRelationFields(args.data, this.meta)) {
@@ -802,9 +817,11 @@ export class PowqlInterface {
             const data = this.applyPkDefault(args.data);
             const assigns = this.scalarData(data);
             const params = [];
-            const body = assigns.map((a) => `${a.col.name} := ${this.writeRef(a.value, a.col, params)}`).join(', ');
+            const body = assigns
+                .map((a) => `${quotePowqlIdent(a.col.name)} := ${this.writeRef(a.value, a.col, params)}`)
+                .join(', ');
             // `returning` surfaces the inserted row (all columns, schema order) in one round-trip.
-            const { rows } = await this.exec(`insert ${this.table} { ${body} } returning`, params, args.timeout);
+            const { rows } = await this.exec(`insert ${this.qt} { ${body} } returning`, params, args.timeout);
             const row = rows.length ? this.shape(rows)[0] : null;
             if (!row)
                 throw new NotFoundError({ table: this.table, where: data });
@@ -819,10 +836,10 @@ export class PowqlInterface {
             const params = [];
             const tuples = inputs.map((d) => {
                 const assigns = this.scalarData(d);
-                return `{ ${assigns.map((a) => `${a.col.name} := ${this.writeRef(a.value, a.col, params)}`).join(', ')} }`;
+                return `{ ${assigns.map((a) => `${quotePowqlIdent(a.col.name)} := ${this.writeRef(a.value, a.col, params)}`).join(', ')} }`;
             });
             // Multi-row insert with `returning` hands back every inserted row in one round-trip.
-            const { rows } = await this.exec(`insert ${this.table} ${tuples.join(', ')} returning`, params, args.timeout);
+            const { rows } = await this.exec(`insert ${this.qt} ${tuples.join(', ')} returning`, params, args.timeout);
             return this.shape(rows);
         });
     }
@@ -837,7 +854,7 @@ export class PowqlInterface {
             this.assertCompiledWhere(where, false, 'update');
             const setClause = this.buildUpdateAssignments(args.data, params);
             // `returning` hands back the post-update row(s); take the first (single-row contract).
-            const { rows } = await this.exec(`${this.table} filter ${where} update { ${setClause} } returning`, params, args.timeout);
+            const { rows } = await this.exec(`${this.qt} filter ${where} update { ${setClause} } returning`, params, args.timeout);
             const row = rows.length ? this.shape(rows)[0] : null;
             if (!row)
                 throw new NotFoundError({ table: this.table, where: args.where });
@@ -852,7 +869,7 @@ export class PowqlInterface {
             this.assertCompiledWhere(where, args.allowFullTableScan, 'updateMany');
             const setClause = this.buildUpdateAssignments(args.data, params);
             const filter = where ? ` filter ${where}` : '';
-            const { rowCount } = await this.exec(`${this.table}${filter} update { ${setClause} }`, params, args.timeout);
+            const { rowCount } = await this.exec(`${this.qt}${filter} update { ${setClause} }`, params, args.timeout);
             return { count: rowCount };
         });
     }
@@ -867,7 +884,7 @@ export class PowqlInterface {
             }
             const colMeta = this.column(field);
             const ref = this.ref(field);
-            const col = colMeta.name;
+            const col = quotePowqlIdent(colMeta.name);
             if (value !== null && typeof value === 'object' && !(value instanceof Date)) {
                 const opObj = value;
                 if ('set' in opObj)
@@ -925,21 +942,34 @@ export class PowqlInterface {
         // drifts from `powdbDialect`; falls back to the literal lowercase keywords.
         const d = this.options.dialect;
         const client = await this.pool.connect();
+        let began = false;
         try {
             await client.query(d?.beginStatement?.() ?? 'begin');
+            began = true;
             const { TransactionClient } = await import('./client.js');
             const tx = new TransactionClient(client, this.schema, this.middlewares, this.options);
             const ctx = { schema: this.schema, tx: tx };
-            const result = await fn(ctx);
+            // Plant the single-writer re-entrancy marker for the implicit tx's
+            // subtree (same seam TurbineClient.$transaction uses) — user code that
+            // fires db.$transaction from inside (e.g. $use middleware around a
+            // nested-write child op) must fast-fail E017, not queue into deadlock.
+            const wrap = client
+                .wrapTransactionCallback;
+            const result = await (wrap ? wrap(() => fn(ctx)) : fn(ctx));
             await client.query(d?.commitStatement?.() ?? 'commit');
             return result;
         }
         catch (err) {
-            try {
-                await client.query(d?.rollbackStatement?.() ?? 'rollback');
-            }
-            catch {
-                /* best-effort — the connection may be gone */
+            // Only roll back a transaction we actually opened — a failed BEGIN
+            // (queue timeout, re-entrancy E017) must not emit a stray ROLLBACK that
+            // could land inside another transaction on a shared engine handle.
+            if (began) {
+                try {
+                    await client.query(d?.rollbackStatement?.() ?? 'rollback');
+                }
+                catch {
+                    /* best-effort — the connection may be gone */
+                }
             }
             throw err;
         }
@@ -962,7 +992,7 @@ export class PowqlInterface {
             const where = this.buildWhere(resolvedWhere, params);
             this.assertCompiledWhere(where, false, 'delete');
             // `returning` hands back the deleted row(s) — no separate pre-image reselect needed.
-            const { rows } = await this.exec(`${this.table} filter ${where} delete returning`, params, args.timeout);
+            const { rows } = await this.exec(`${this.qt} filter ${where} delete returning`, params, args.timeout);
             const row = rows.length ? this.shape(rows)[0] : null;
             if (!row)
                 throw new NotFoundError({ table: this.table, where: args.where });
@@ -976,7 +1006,7 @@ export class PowqlInterface {
             const where = this.buildWhere(resolvedWhere, params);
             this.assertCompiledWhere(where, args.allowFullTableScan, 'deleteMany');
             const filter = where ? ` filter ${where}` : '';
-            const { rowCount } = await this.exec(`${this.table}${filter} delete`, params, args.timeout);
+            const { rowCount } = await this.exec(`${this.qt}${filter} delete`, params, args.timeout);
             return { count: rowCount };
         });
     }
@@ -991,14 +1021,14 @@ export class PowqlInterface {
             }
             const params = [];
             const createBody = this.scalarData(createData)
-                .map((a) => `${a.col.name} := ${this.writeRef(a.value, a.col, params)}`)
+                .map((a) => `${quotePowqlIdent(a.col.name)} := ${this.writeRef(a.value, a.col, params)}`)
                 .join(', ');
             const updateBody = this.buildUpdateAssignments(args.update, params);
             // PowDB 0.7.0's `upsert` statement does NOT accept a trailing `returning`
             // (verified: "unexpected trailing token … 'returning'"), because it is one
             // atomic insert-or-update, not two branches. So upsert alone keeps the
             // reselect-by-PK fetch; create/update/delete all use `returning`.
-            await this.exec(`upsert ${this.table} on .${pkCol} { ${createBody} } on conflict { ${updateBody} }`, params, args.timeout);
+            await this.exec(`upsert ${this.qt} on .${pkCol} { ${createBody} } on conflict { ${updateBody} }`, params, args.timeout);
             const pkField = this.meta.reverseColumnMap[pkCol] ?? pkCol;
             const row = await this.reselectByPk(createData[pkField], args.timeout);
             if (!row)
@@ -1043,7 +1073,7 @@ export class PowqlInterface {
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
             const where = this.buildWhere(resolvedWhere, params);
             const filter = where ? ` filter ${where}` : '';
-            const { rows } = await this.exec(`count(${this.table}${filter})`, params, args.timeout);
+            const { rows } = await this.exec(`count(${this.qt}${filter})`, params, args.timeout);
             return Number((rows[0]?.value ?? rows[0]?.count ?? 0));
         });
     }
@@ -1063,12 +1093,12 @@ export class PowqlInterface {
             };
             if (args._count) {
                 if (args._count === true) {
-                    result._count = (await scalar(`count(${this.table}${filter})`)) ?? 0;
+                    result._count = (await scalar(`count(${this.qt}${filter})`)) ?? 0;
                 }
                 else {
                     const counts = {};
                     for (const field of Object.keys(args._count).filter((f) => args._count[f])) {
-                        counts[field] = (await scalar(`count(${this.table}${filter} { ${this.ref(field)} })`)) ?? 0;
+                        counts[field] = (await scalar(`count(${this.qt}${filter} { ${this.ref(field)} })`)) ?? 0;
                     }
                     result._count = counts;
                 }
@@ -1080,7 +1110,7 @@ export class PowqlInterface {
                 const acc = {};
                 for (const field of Object.keys(spec).filter((f) => spec[f])) {
                     const powfn = fn.slice(1); // sum/avg/min/max
-                    acc[field] = await scalar(`${powfn}(${this.table}${filter} { ${this.ref(field)} })`);
+                    acc[field] = await scalar(`${powfn}(${this.qt}${filter} { ${this.ref(field)} })`);
                 }
                 result[fn] = acc;
             }
@@ -1114,7 +1144,7 @@ export class PowqlInterface {
             }
             const having = this.buildHaving(args.having, params);
             const order = this.buildOrder(args.orderBy);
-            const powql = `${this.table}${filter} group ${groupKeys.join(', ')}${having}${order} { ${proj.join(', ')} }`;
+            const powql = `${this.qt}${filter} group ${groupKeys.join(', ')}${having}${order} { ${proj.join(', ')} }`;
             const { rows } = await this.exec(powql, params, args.timeout);
             // Reshape: group keys → camel fields + coerced; aggregates → nested {_sum:{field}}.
             return rows.map((raw) => {

package/dist/query/builder.d.ts

@@ -55,6 +55,12 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     /** Pre-computed column type lookups (avoids linear scans per query) */
     private readonly columnPgTypeMap;
     private readonly 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).
+     */
+    private readonly crossSchemaTypeColumns;
     /** Tracks tables that have already triggered a deep-with warning (one-time) */
     private readonly deepWithWarned;
     /**
@@ -249,7 +255,10 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * 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).
      */
     private maybeWarnUnlimited;
     /**
@@ -427,17 +436,27 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      */
     private collectRelationFilterParams;
     private collectRelFilterParams;
-    /** Collect params from operator clauses. Mirrors buildOperatorClauses. */
+    /**
+     * Collect params from operator clauses. Mirrors buildOperatorClauses:
+     * {@link ColumnRef} values compile into the SQL text, so they push NOTHING -
+     * but they re-run the same validation (unknown ref / insensitive mode) so a
+     * warmed cache can never skip a check the build path enforces.
+     */
     private collectOperatorParams;
-    /** Collect params from JSON filter. Mirrors buildJsonFilterClauses. */
+    /**
+     * 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.
+     */
     private collectJsonFilterParams;
     /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
     private collectArrayFilterParams;
     /**
-     * Collect params for an orderBy clause. Only vector KNN ordering pushes a
-     * param (the `$n::vector` query vector); plain direction ordering is
-     * parameterless. Mirrors buildOrderBy's push order exactly so the cached-SQL
-     * param re-collection stays in lockstep.
+     * Collect params for an orderBy clause. Vector KNN ordering pushes the
+     * `$n::vector` query vector and JSON-path ordering pushes its text[] path;
+     * plain direction ordering is parameterless. Mirrors buildOrderBy's push
+     * order exactly so the cached-SQL param re-collection stays in lockstep.
      */
     private collectOrderByParams;
     /**
@@ -545,6 +564,28 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * (relation targets, not just `this.table`).
      */
     private pgTypeForColumn;
+    /**
+     * 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.
+     */
+    private enumTypeForColumn;
+    /**
+     * `::"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.
+     */
+    private enumCastSuffix;
     /**
      * Equality-fallthrough guard shared by every SQL-build path AND every
      * cache-hit param-collect path. A plain object literal that matched no known
@@ -575,9 +616,28 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * differently-shaped wheres would share one cached SQL string.
      */
     private fingerprintAliasWhere;
+    /**
+     * Validate a `{ col }` column reference against its table and return the
+     * resolved snake_case column name. Shared by the SQL-build path
+     * ({@link buildOperatorClauses}) and the cache-hit param-collect path
+     * (`collectOperatorParams`) so both always throw identically: a warmed
+     * cache can never skip the check.
+     */
+    private resolveColumnRef;
+    /**
+     * Compile a `{ col }` reference to its quoted, prefix-matched SQL identifier.
+     * NO param is bound: the referenced column is part of the SQL text (and of
+     * the where fingerprint, see {@link fingerprintOperatorShape}).
+     */
+    private columnRefSql;
     /**
      * Build SQL clauses for a single operator object on a column.
      * Each operator key becomes its own clause, all ANDed together.
+     *
+     * `equals`/`not`/`gt`/`gte`/`lt`/`lte` also accept a {@link ColumnRef}
+     * (`{ col: 'otherField' }`) which compiles to a column-to-column comparison
+     * against `refCtx`: no param bound, so `collectOperatorParams` mirrors by
+     * pushing nothing and the referenced name lives in the fingerprint.
      */
     private buildOperatorClauses;
     /**
@@ -611,6 +671,33 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * {@link UnsupportedFeatureError} (E017) instead of broken SQL.
      */
     private nullsSuffix;
+    /**
+     * Resolve an orderBy key to its snake_case column via the table's columnMap
+     * (camelToSnake fallback), throwing the SAME unknown-field E003 the top-level
+     * where path uses. Shared by top-level JSON-path ordering and every nested
+     * relation orderBy path so nested orderBy accepts exactly what top-level
+     * accepts (the 0.30.x bug: nested orderBy skipped the columnMap and rejected
+     * camelCase-named DB columns like "sortOrder").
+     */
+    private resolveOrderByColumn;
+    /**
+     * Validate a {@link JsonPathOrderBy} entry: column must exist AND be
+     * json/jsonb, path must be a non-empty array of keys/indexes: and return
+     * the resolved column. Shared by the SQL-build path
+     * ({@link buildJsonPathOrderEntry}) and the cache-hit param-collect mirrors
+     * so both always throw identically.
+     */
+    private validateJsonPathOrderBy;
+    /**
+     * Compile one {@link JsonPathOrderBy} entry:
+     * `("col" #>> $n::text[])::numeric ASC`: the numeric cast only with
+     * `type: 'numeric'` (default is text comparison), the extraction routed
+     * through the dialect's JSON hook exactly like the JSON where-filters, the
+     * path bound as ONE text[] param (mirrored by the order-param collectors).
+     * `prefix` scopes the column (`''` top-level, `t0.` inside a relation
+     * subquery).
+     */
+    private buildJsonPathOrderEntry;
     /**
      * Compile a relation ordering term. For a to-many relation the only allowed
      * key is `_count`, which becomes a correlated `COUNT(*)` subquery. For a
@@ -619,8 +706,37 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      *
      * Validation: relation must exist (E005); to-many only allows `_count`, and
      * to-one only allows real target columns (E003).
+     *
+     * `ctx` generalizes the term beyond the root table: inside a relation
+     * subquery's orderBy the relations live on the TARGET table's metadata and
+     * the correlation parent is the relation's alias, not `this.table`.
      */
     private buildRelationOrderBy;
+    /**
+     * Compile the ORDER BY terms of a relation `with` clause against the
+     * relation's table alias. One unified path for every relation shape
+     * (hasMany / manyToMany / belongsTo / hasOne) supporting exactly what the
+     * top-level orderBy accepts at this level:
+     *
+     *  - scalar columns via columnMap resolution (camelToSnake fallback) with
+     *    {@link OrderBySpec} nulls placement,
+     *  - {@link JsonPathOrderBy} entries (path bound as one text[] param),
+     *  - relation ordering on the TARGET's relations (`_count` for to-many, a
+     *    target column for to-one), correlated to the relation alias,
+     *  - vector KNN ordering stays top-level-only (E003, same as before).
+     *
+     * Param pushes (JSON paths, relation-order global filters) MUST be mirrored,
+     * in the same order, by {@link collectRelationOrderParams}.
+     */
+    private buildRelationOrderClause;
+    /**
+     * Param-collect mirror of {@link buildRelationOrderClause}: JSON-path
+     * entries push their path (one text[] param each); relation-order entries
+     * mirror {@link collectOrderByParams}' relation branch (count / to-one
+     * global-filter params); scalar entries push nothing but re-run the same
+     * column validation so a warmed cache can never skip it.
+     */
+    private collectRelationOrderParams;
     /**
      * Build a correlated `(SELECT COUNT(*) …)` scalar subquery for a to-many
      * relation, correlated to `parentRef`. hasMany counts child rows via the FK;
@@ -899,11 +1015,32 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * E.g. '_text' → 'text', '_int4' → 'integer'
      */
     private getArrayElementType;
+    /**
+     * 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.
+     */
+    private jsonRangeEntries;
     /**
      * 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}.
      */
     private buildJsonFilterClauses;
+    /**
+     * 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.
+     */
+    private castJsonNumeric;
     /**
      * Build SQL clauses for Array filter operators on a column.
      * Supports: has, hasEvery, hasSome, isEmpty.