turbine-orm 0.31.0 → 0.32.1

package/dist/errors.js

@@ -144,8 +144,16 @@ export class NotFoundError extends TurbineError {
 /** Thrown when a query or transaction exceeds the configured timeout */
 export class TimeoutError extends TurbineError {
     timeoutMs;
-    constructor(timeoutMs, context = 'Query') {
-        super(TurbineErrorCode.TIMEOUT, `[turbine] ${context} timed out after ${timeoutMs}ms`);
+    /**
+     * @param timeoutMs the client-side timeout budget in ms. Pass `0` when the
+     *   duration is unknown (e.g. a server-side `statement_timeout` cancellation
+     *   surfaced via `wrapPgError`, where Turbine did not set the deadline).
+     * @param context human label for the operation ("Query", "Transaction").
+     * @param options optional `message` override and pg `cause` to preserve, used
+     *   when wrapping a driver error rather than a client-side timer expiry.
+     */
+    constructor(timeoutMs, context = 'Query', options) {
+        super(TurbineErrorCode.TIMEOUT, options?.message ?? `[turbine] ${context} timed out after ${timeoutMs}ms`, options);
         this.name = 'TimeoutError';
         this.timeoutMs = timeoutMs;
     }
@@ -159,8 +167,13 @@ export class ValidationError extends TurbineError {
 }
 /** Thrown when a database connection fails */
 export class ConnectionError extends TurbineError {
-    constructor(message) {
-        super(TurbineErrorCode.CONNECTION, message);
+    /**
+     * @param message human-readable connection failure description.
+     * @param options optional pg/driver `cause` to preserve, used when wrapping a
+     *   connection-class driver error via `wrapPgError`.
+     */
+    constructor(message, options) {
+        super(TurbineErrorCode.CONNECTION, message, options);
         this.name = 'ConnectionError';
     }
 }
@@ -477,6 +490,35 @@ function parseColumnsFromDetail(detail) {
         return undefined;
     return m[1].split(',').map((s) => s.trim());
 }
+/**
+ * Connection-class error codes. Covers both pg SQLSTATEs (class 08
+ * connection_exception, plus a few class-53/57 admin/availability codes) and
+ * Node driver-level error codes that arrive on the same `.code` field when the
+ * socket never reaches Postgres. All map to {@link ConnectionError} (E004).
+ *
+ * `57014` (query_canceled, a server-side `statement_timeout` cancellation) is
+ * intentionally NOT here: it maps to {@link TimeoutError} (E002) instead.
+ */
+const CONNECTION_ERROR_CODES = new Set([
+    // pg SQLSTATE class 08: connection_exception
+    '08000', // connection_exception
+    '08001', // sqlclient_unable_to_establish_sqlconnection
+    '08003', // connection_does_not_exist
+    '08004', // sqlserver_rejected_establishment_of_sqlconnection
+    '08006', // connection_failure
+    '08P01', // protocol_violation
+    // pg SQLSTATE class 53/57 (server unavailable / shutting down)
+    '53300', // too_many_connections
+    '57P01', // admin_shutdown
+    '57P02', // crash_shutdown
+    '57P03', // cannot_connect_now
+    // Node driver-level socket errors (surface on err.code too)
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'ENOTFOUND',
+    'EPIPE',
+]);
 /**
  * Translate a pg driver error into a typed Turbine error.
  * If the error doesn't match a known constraint code, returns it unchanged.
@@ -489,6 +531,8 @@ function parseColumnsFromDetail(detail) {
  *   23P01 (exclusion_violation)   -> ExclusionConstraintError
  *   40P01 (deadlock_detected)     -> DeadlockError       (retryable)
  *   40001 (serialization_failure) -> SerializationFailureError (retryable)
+ *   57014 (query_canceled)        -> TimeoutError (server-side statement_timeout)
+ *   connection-class codes        -> ConnectionError (see CONNECTION_ERROR_CODES)
  *
  * The original pg error is preserved as `.cause` on the wrapped error.
  */
@@ -541,7 +585,21 @@ export function wrapPgError(err) {
             return new SerializationFailureError({
                 cause: err,
             });
+        case '57014':
+            // query_canceled: a server-side statement_timeout cancelled the query.
+            // Turbine did not set the deadline (that lives in Postgres config), so
+            // there is no client-side budget to report → timeoutMs = 0.
+            return new TimeoutError(0, 'Query', {
+                message: '[turbine] Query canceled by server-side statement_timeout',
+                cause: err,
+            });
         default:
+            if (CONNECTION_ERROR_CODES.has(e.code)) {
+                const pgMessage = typeof e.message === 'string' && e.message.length > 0 ? e.message : undefined;
+                return new ConnectionError(pgMessage
+                    ? `[turbine] Database connection error: ${pgMessage}`
+                    : `[turbine] Database connection error (${e.code})`, { cause: err });
+            }
             return err;
     }
 }

package/dist/generate.js

@@ -670,7 +670,8 @@ export function generateIndex(schema, options) {
     lines.push('/**');
     lines.push(' * Create a new Turbine client instance.');
     lines.push(' *');
-    lines.push(' * @param config - Connection configuration. Falls back to DATABASE_URL env var.');
+    lines.push(' * @param config - Connection configuration. Omit it (or pass no connection');
+    lines.push(' *   fields) to fall back to the `DATABASE_URL` environment variable.');
     lines.push(' * @returns A fully-typed TurbineClient with table accessors.');
     lines.push(' */');
     lines.push('export function turbine(config?: TurbineConfig): TurbineClient {');

package/dist/index.d.ts

@@ -43,7 +43,7 @@ export { type IntrospectOptions, introspect } from './introspect.js';
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
 export type { ObserveConfig, ObserveHandle } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByArgs, type HavingClause, type JsonFilter, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type HavingClause, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';

package/dist/powql.js

@@ -38,6 +38,7 @@ import { randomUUID } from 'node:crypto';
 import { NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError } from './errors.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
 import { PowdbFloatParam, powqlColumnType, quotePowqlIdent, rowToEntity } from './powdb.js';
+import { isRelationPickOrderBy } from './query/filters.js';
 import { escapeLike } from './query/utils.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
 /**
@@ -475,7 +476,22 @@ export class PowqlInterface {
             return '';
         const parts = keys.map(([field, dir]) => {
             if (dir && typeof dir === 'object') {
-                throw new UnsupportedFeatureError('vector / distance ordering', 'PowDB', `field "${field}"`);
+                // Name the actual feature in the refusal — a pick-row ordering
+                // reported as "vector / distance ordering" sends users hunting for
+                // pgvector docs. All object-valued orderings stay E017 on PowDB.
+                const o = dir;
+                const feature = isRelationPickOrderBy(dir)
+                    ? 'relation pick-row ordering'
+                    : 'distance' in o
+                        ? 'vector / distance ordering'
+                        : Array.isArray(o.path)
+                            ? 'JSON-path ordering'
+                            : '_count' in o
+                                ? 'relation _count ordering'
+                                : 'sort' in o || 'nulls' in o
+                                    ? 'NULLS placement / sort-spec ordering'
+                                    : 'object-valued ordering';
+                throw new UnsupportedFeatureError(feature, 'PowDB', `field "${field}"`);
             }
             return `${this.ref(field)} ${dir === 'desc' ? 'desc' : 'asc'}`;
         });
@@ -566,7 +582,7 @@ export class PowqlInterface {
         const limit = args.limit ?? args.take ?? this.defaultLimit;
         if (limit === undefined && this.warnOnUnlimited && !this.warnedUnlimited) {
             this.warnedUnlimited = true;
-            console.warn(`[turbine] findMany on "${this.table}" has no limit — this scans the whole table.`);
+            console.warn(`[turbine] findMany on "${this.table}" has no limit: this scans the whole table.`);
         }
         const limitClause = limit !== undefined ? ` limit ${this.param(limit, params)}` : '';
         const offsetClause = args.offset ? ` offset ${this.param(args.offset, params)}` : '';
@@ -1119,6 +1135,27 @@ export class PowqlInterface {
     }
     async groupBy(args) {
         return this.withMiddleware('groupBy', args, async () => {
+            // The SQL-only groupBy extensions (DISTINCT ON row source, JSON-path
+            // group keys / aggregate targets) have no PowQL equivalent: refuse
+            // clearly instead of emitting broken PowQL.
+            if (args.distinctOn) {
+                throw new UnsupportedFeatureError('groupBy distinctOn row source', 'PowDB');
+            }
+            for (const entry of args.by) {
+                if (typeof entry !== 'string') {
+                    throw new UnsupportedFeatureError('JSON-path groupBy keys', 'PowDB');
+                }
+            }
+            for (const fn of ['_sum', '_avg', '_min', '_max']) {
+                const spec = args[fn];
+                if (!spec)
+                    continue;
+                for (const value of Object.values(spec)) {
+                    if (value !== undefined && typeof value !== 'boolean') {
+                        throw new UnsupportedFeatureError(`JSON-path ${fn} aggregate targets`, 'PowDB');
+                    }
+                }
+            }
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
             const where = this.buildWhere(resolvedWhere, params);

package/dist/query/batched-loader.d.ts

@@ -138,6 +138,18 @@ export declare function neededParentKeyFields(parentMeta: TableMetadata, withCla
  * ({@link ValidationError}) when a named relation is to-one.
  */
 export declare function resolveCountRelations(parentMeta: TableMetadata, countSpec: WithCount): RelationDef[];
+/**
+ * Reject pick-row relation ordering anywhere inside a `with` tree's orderBy —
+ * strategy parity with the join path, which throws this exact E003 at SQL
+ * build time (`pickOrderNestedError` in builder.ts). Without this guard the
+ * loaders would forward `options.orderBy` as the child reader's TOP-LEVEL
+ * findMany orderBy, where the pick shape compiles fine — so the same query
+ * would execute on 'batched' but throw on 'join'. Walks the whole tree up
+ * front so acceptance never depends on which levels have rows — the batched
+ * runners in builder.ts call this BEFORE the base query (a zero-row base
+ * result must still reject, exactly like the join strategy's build-time throw).
+ */
+export declare function rejectNestedPickOrder(withClause: WithClause): void;
 /**
  * Load every relation in `withClause` for `parents` and attach it onto each row
  * in place. Mirrors the join strategy's output shape exactly. Recurses for nested

package/dist/query/batched-loader.js

@@ -48,6 +48,7 @@
  */
 import { CircularRelationError, RelationError, UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { normalizeKeyColumns } from '../schema.js';
+import { isRelationPickOrderBy } from './filters.js';
 /**
  * Max parent keys per follow-up query. On Postgres the whole key set travels as
  * ONE array parameter (`= ANY($1)`), so this is not a bind-parameter limit — it
@@ -177,6 +178,34 @@ export function resolveCountRelations(parentMeta, countSpec) {
 function keyOf(value) {
     return String(value);
 }
+/**
+ * Reject pick-row relation ordering anywhere inside a `with` tree's orderBy —
+ * strategy parity with the join path, which throws this exact E003 at SQL
+ * build time (`pickOrderNestedError` in builder.ts). Without this guard the
+ * loaders would forward `options.orderBy` as the child reader's TOP-LEVEL
+ * findMany orderBy, where the pick shape compiles fine — so the same query
+ * would execute on 'batched' but throw on 'join'. Walks the whole tree up
+ * front so acceptance never depends on which levels have rows — the batched
+ * runners in builder.ts call this BEFORE the base query (a zero-row base
+ * result must still reject, exactly like the join strategy's build-time throw).
+ */
+export function rejectNestedPickOrder(withClause) {
+    for (const spec of Object.values(withClause)) {
+        if (!spec || spec === true)
+            continue;
+        const options = spec;
+        if (options.orderBy) {
+            for (const [key, value] of Object.entries(options.orderBy)) {
+                if (isRelationPickOrderBy(value)) {
+                    throw new ValidationError(`[turbine] Pick-row ordering on relation "${key}" is only supported in a top-level ` +
+                        'findMany orderBy: nested `with` orderBy does not support it.');
+                }
+            }
+        }
+        if (options.with)
+            rejectNestedPickOrder(options.with);
+    }
+}
 /**
  * Load every relation in `withClause` for `parents` and attach it onto each row
  * in place. Mirrors the join strategy's output shape exactly. Recurses for nested
@@ -185,6 +214,10 @@ function keyOf(value) {
 export async function loadRelationsBatched(ctx, parents, withClause, timeout, depth = 0, path = [ctx.parentMeta.name]) {
     if (depth >= MAX_DEPTH)
         throw new CircularRelationError([...path, '…']);
+    // Scope-rule parity with the join strategy: validate the whole tree BEFORE
+    // the empty-parents early return, so accept/reject never depends on data.
+    if (depth === 0)
+        rejectNestedPickOrder(withClause);
     if (parents.length === 0)
         return;
     // Sibling relations are independent (each writes only its own parent[relName]

package/dist/query/builder.d.ts

@@ -22,6 +22,15 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly tableMeta;
     /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
     private readonly sqlTemplateCache;
+    /**
+     * Whether the most recent {@link acquireSql} call was a cache HIT. Read by
+     * {@link crossCheckCache} to decide whether to run the dev-mode lockstep
+     * cross-check. Safe as a single mutable flag: each `build*()` method calls
+     * `acquireSql` then `crossCheckCache` synchronously with no intervening
+     * `await` and no re-entrant `acquireSql` (relation subqueries are built
+     * inline, not through the top-level cache).
+     */
+    private lastCacheHit;
     private readonly middlewares;
     private readonly defaultLimit?;
     private readonly warnOnUnlimited;
@@ -183,8 +192,42 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * On hit, increments counters and returns the cached entry.
      *
      * When `sqlCache` is disabled, always calls `build()` without caching.
+     *
+     * `build` receives a fresh `$N` param scratch array. On a miss those params
+     * are discarded (the returned params come from each call site's dedicated
+     * collect path); the array exists so the build path can number placeholders
+     * via `params.length` exactly as it does today. On a HIT, `build` is skipped
+     * here but re-run by {@link crossCheckCache} (dev only) with a fresh array to
+     * verify the collect path stayed in lockstep with the build path.
+     *
+     * Sets {@link lastCacheHit} so the caller's `crossCheckCache` knows whether a
+     * cross-check is warranted.
      */
     private acquireSql;
+    /**
+     * Dev-mode SQL-cache lockstep cross-check (see {@link cacheCrossCheckEnabled}).
+     *
+     * Runs only when the most recent {@link acquireSql} was a cache HIT and the
+     * check is enabled. Rebuilds the SQL + `$N` params fresh via the same `build`
+     * closure the caller passed to `acquireSql`, then compares:
+     *   (a) the cached SQL string byte-for-byte against the fresh SQL, and
+     *   (b) the params the cache-hit collect path produced against the fresh
+     *       build-path params (length and element-wise strict deep-equal).
+     *
+     * A mismatch means the fingerprint / build / collect paths have drifted out
+     * of lockstep (the exact class of bug that has silently corrupted results
+     * before), so it throws a {@link ValidationError} (E003) naming the
+     * fingerprint, the operation, and both SQL strings (truncated). Failing loud
+     * in dev/test is the point. Production never reaches the comparison.
+     *
+     * @param op human label of the calling build method (for the error message).
+     * @param cacheKey the cache fingerprint that HIT.
+     * @param entry the cached SQL entry that will be executed.
+     * @param build the same closure passed to `acquireSql`; re-run here to
+     *   capture the fresh build-path SQL + params.
+     * @param collectedParams the params the caller's collect path produced.
+     */
+    private crossCheckCache;
     /**
      * Reset the per-instance unlimited-query warning dedupe set.
      * Exposed for tests so a single test process can verify the warning fires
@@ -339,6 +382,27 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     buildCount(args?: CountArgs<T>): DeferredQuery<number>;
     groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
     buildGroupBy(args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
+    /**
+     * Validate a JSON-path target (group key or aggregate target) in groupBy:
+     * the field must resolve to a real json/jsonb column and the path must be a
+     * non-empty array of keys/indexes. Returns the resolved snake_case column.
+     */
+    private resolveJsonPathTarget;
+    /**
+     * Build the `distinctOn` row source for groupBy (PostgreSQL only: other
+     * engines throw {@link UnsupportedFeatureError} E017):
+     *
+     * ```sql
+     * (SELECT DISTINCT ON ("c1") * FROM "table"<WHERE> ORDER BY "c1", <orderBy>) AS "table"
+     * ```
+     *
+     * The wrapper is aliased as the table name so every outer expression (group
+     * keys, aggregates, HAVING, ORDER BY) is byte-identical to the plain path.
+     * `distinctOn.orderBy` is required (it decides which row survives) and
+     * supports plain columns, {@link OrderBySpec} nulls, and JSON-path specs;
+     * JSON paths push their text[] param here, after the WHERE params.
+     */
+    private buildDistinctOnSource;
     /**
      * Build the SQL fragments for a {@link HavingClause}.
      *
@@ -349,6 +413,12 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * comparison value is pushed onto the shared `params` array and referenced by
      * a `$N` placeholder via {@link buildHavingNumericClauses} — there is no string
      * interpolation of user values.
+     *
+     * `jsonAggExprs` (from {@link buildGroupBy}) maps `alias:aggKey` to the
+     * exact aggregate expression a JSON-path aggregate emitted in SELECT
+     * (including its already-bound path placeholder), so HAVING on a JSON-path
+     * aggregate alias reuses the same expression instead of resolving the alias
+     * as a column.
      */
     private buildHavingClauses;
     /**
@@ -712,6 +782,46 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * the correlation parent is the relation's alias, not `this.table`.
      */
     private buildRelationOrderBy;
+    /**
+     * Validate a {@link RelationPickOrderBy} entry's scope and shape. Shared by
+     * the SQL-build path ({@link buildRelationPickOrderBy}) and the cache-hit
+     * param-collect mirror ({@link collectRelationPickOrderParams}) so both
+     * always throw identically:
+     *
+     *  - `nested` (inside a relation subquery's orderBy or a pick.orderBy):
+     *    top-level findMany only in this release (E003),
+     *  - manyToMany: not supported (E003 naming the limitation),
+     *  - to-one: order by the target column directly instead (E003),
+     *  - `pick.orderBy` is REQUIRED (deterministic row choice),
+     *  - `by` must be a target column name or a `{ field, path }` JSON-path spec.
+     */
+    private pickOrderNestedError;
+    private validatePickOrderBy;
+    /**
+     * Compile a {@link RelationPickOrderBy} term: a correlated scalar subquery
+     * that picks ONE related row (`ORDER BY <pick.orderBy> LIMIT 1`, optionally
+     * filtered by `pick.where` and the target's global filter) and surfaces one
+     * value from it (a plain target column or a JSON-path extraction) as the
+     * parent ORDER BY key:
+     *
+     * ```sql
+     * (SELECT ord0."data" #>> $1::text[] FROM "versions" ord0
+     *   WHERE ord0."instance_id" = "instances"."id" AND ord0."is_current" = $2
+     *   ORDER BY ord0."created_at" DESC LIMIT 1) ASC NULLS LAST
+     * ```
+     *
+     * Param-push order (mirrored EXACTLY by
+     * {@link collectRelationPickOrderParams}): `by` JSON path (if any) →
+     * target global filter → `pick.where` → `pick.orderBy` JSON paths.
+     */
+    private buildRelationPickOrderBy;
+    /**
+     * Param-collect mirror of {@link buildRelationPickOrderBy}: re-runs the same
+     * validation (a warmed cache can never skip it), then pushes in the same
+     * order: `by` JSON path → target global filter → `pick.where` →
+     * `pick.orderBy` JSON paths.
+     */
+    private collectRelationPickOrderParams;
     /**
      * Compile the ORDER BY terms of a relation `with` clause against the
      * relation's table alias. One unified path for every relation shape
@@ -1009,6 +1119,13 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Used to detect JSONB/array columns for specialized operators.
      * Uses pre-computed Map for O(1) lookup instead of linear scan.
      */
+    /**
+     * Case-insensitive json/jsonb column-type check. Postgres reports lowercase
+     * udt_names, but SQLite/MySQL introspection surfaces the DECLARED type
+     * (e.g. `JSON`), so every JSON-feature gate compares through this predicate
+     * — build and collect sides alike, keeping the SQL-cache lockstep.
+     */
+    private isJsonColumnType;
     private getColumnPgType;
     /**
      * Get the Postgres base element type for an array column.
@@ -1033,6 +1150,18 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * stays byte-identical to {@link collectJsonFilterParams}.
      */
     private buildJsonFilterClauses;
+    /**
+     * Bind value for a JSON path parameter, encoded per dialect. PostgreSQL's
+     * `#>>` takes a `text[]` (the segments as strings — or `nativeForm` when the
+     * caller has a specific native binding, e.g. JsonFilter's raw path array).
+     * Every other engine's JSON function (`json_extract` / `JSON_EXTRACT` /
+     * `JSON_VALUE`) takes a `'$'`-rooted JSONPath STRING: binding the raw array
+     * would arrive as `'["a"]'` (the driver shims JSON.stringify non-primitive
+     * params) and fail at runtime with the engine's bad-JSON-path error. The
+     * encoded path stays a bound parameter — never spliced into SQL text — so
+     * the build/collect param mirrors stay in lockstep and injection-safe.
+     */
+    private jsonPathParam;
     /**
      * Cast an extracted JSON path text value to a numeric type for range
      * comparison. PostgreSQL uses `(expr)::numeric` (exact — the right way to