turbine-orm 0.30.0 → 0.31.0

package/dist/cjs/query/builder.js

@@ -2459,7 +2459,11 @@ class QueryInterface {
             }
             // Operator objects
             if ((0, filters_js_1.isWhereOperator)(value)) {
-                this.collectOperatorParams(rawColumn, value, params);
+                this.collectOperatorParams(rawColumn, value, params, {
+                    meta: this.tableMeta,
+                    table: this.table,
+                    prefix: '',
+                });
                 continue;
             }
             // Plain equality — same strict validation as the build path, so a
@@ -2560,28 +2564,40 @@ class QueryInterface {
                 }
             }
             if ((0, filters_js_1.isWhereOperator)(value)) {
-                this.collectOperatorParams(col, value, params);
+                this.collectOperatorParams(col, value, params, { meta, table: targetTable, prefix: '' });
                 continue;
             }
             this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(meta, col), targetTable);
             params.push(value);
         }
     }
-    /** Collect params from operator clauses. Mirrors buildOperatorClauses. */
-    collectOperatorParams(column, op, params) {
-        if (op.equals !== undefined && op.equals !== null) {
+    /**
+     * 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.
+     */
+    collectOperatorParams(column, op, params, refCtx) {
+        const skipRef = (v) => {
+            if (!(0, filters_js_1.isColumnRef)(v))
+                return false;
+            if (refCtx)
+                this.resolveColumnRef(v, refCtx, op.mode);
+            return true;
+        };
+        if (op.equals !== undefined && op.equals !== null && !skipRef(op.equals)) {
             (0, filters_js_1.assertBindableEqualsOperand)(op.equals, `"${column}"`);
             params.push(op.equals);
         }
-        if (op.gt !== undefined)
+        if (op.gt !== undefined && !skipRef(op.gt))
             params.push(op.gt);
-        if (op.gte !== undefined)
+        if (op.gte !== undefined && !skipRef(op.gte))
             params.push(op.gte);
-        if (op.lt !== undefined)
+        if (op.lt !== undefined && !skipRef(op.lt))
             params.push(op.lt);
-        if (op.lte !== undefined)
+        if (op.lte !== undefined && !skipRef(op.lte))
             params.push(op.lte);
-        if (op.not !== undefined && op.not !== null)
+        if (op.not !== undefined && op.not !== null && !skipRef(op.not))
             params.push(op.not);
         if (op.in !== undefined)
             params.push(this.inParam(op.in));
@@ -2637,10 +2653,10 @@ class QueryInterface {
         // isEmpty has no params (IS NULL / IS NOT NULL)
     }
     /**
-     * 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.
      */
     collectOrderByParams(orderBy, params) {
         for (const [key, dir] of Object.entries(orderBy)) {
@@ -2652,6 +2668,13 @@ class QueryInterface {
                 this.pushVectorParam(key, rawColumn, dir.distance.to, params);
                 continue;
             }
+            // JSON-path ordering: mirrors buildJsonPathOrderEntry: same validation,
+            // then the path bound as one text[] param.
+            if ((0, filters_js_1.isJsonPathOrderBy)(dir)) {
+                this.validateJsonPathOrderBy(this.table, this.tableMeta, key, dir);
+                params.push(dir.path.map(String));
+                continue;
+            }
             // To-many relation orderBy (`{ posts: { _count } }`) uses the same count
             // subquery as `_count` — mirror its global-filter params. To-one relation
             // orderBy carries the target's global filter once per ordered column.
@@ -2798,9 +2821,20 @@ class QueryInterface {
         const targetMeta = this.schema.tables[targetTable];
         if (!targetMeta)
             return;
+        // A dialect that owns the whole subquery (buildRelationSubquery override,
+        // SQL Server FOR JSON) compiles orderBy through its OWN paging clause -
+        // plain directions only, no order params: so the native order-param
+        // mirrors below must stay off for it (its documented contract remains
+        // where → limit → nested).
+        const nativeOrderPath = !this.dialect.buildRelationSubquery;
         // manyToMany param order mirrors buildManyToManySubquery:
-        //   where params → limit param → nested-with params (always, both paths).
+        //   orderBy params → where params → limit param → nested-with params
+        //   (always, both paths).
         if (relDef.type === 'manyToMany') {
+            const m2mOrderEntries = spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+            if (nativeOrderPath && m2mOrderEntries.length > 0) {
+                this.collectRelationOrderParams(targetTable, targetMeta, m2mOrderEntries, params);
+            }
             if (spec.where) {
                 this.collectAliasWhereParams(targetTable, targetMeta, spec.where, params);
             }
@@ -2819,7 +2853,8 @@ class QueryInterface {
             return;
         }
         // Mirrors buildRelationSubquery's willWrap: `orderBy: {}` is treated as absent.
-        const hasOrder = spec.orderBy ? Object.values(spec.orderBy).some((dir) => dir !== undefined) : false;
+        const relOrderEntries = spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+        const hasOrder = relOrderEntries.length > 0;
         const willWrap = relDef.type === 'hasMany' && (spec.limit !== undefined || hasOrder);
         // Non-wrapped path: nested relations BEFORE where/limit
         if (!willWrap && spec.with) {
@@ -2830,6 +2865,12 @@ class QueryInterface {
                 this.collectRelationSubqueryParams(nestedRelDef, nestedSpec, params, 'alias', depth + 1);
             }
         }
+        // orderBy params (JSON paths / relation-order global filters): mirrors
+        // buildRelationSubquery, which builds its ORDER BY terms BEFORE compiling
+        // spec.where (both wrapped and non-wrapped paths).
+        if (nativeOrderPath && hasOrder) {
+            this.collectRelationOrderParams(targetTable, targetMeta, relOrderEntries, params);
+        }
         // where params — mirrors buildAliasWhere push order
         if (spec.where) {
             this.collectAliasWhereParams(targetTable, targetMeta, spec.where, params);
@@ -3180,7 +3221,11 @@ class QueryInterface {
             }
             // Handle operator objects
             if ((0, filters_js_1.isWhereOperator)(value)) {
-                const opClauses = this.buildOperatorClauses(column, value, params);
+                const opClauses = this.buildOperatorClauses(column, value, params, {
+                    meta: this.tableMeta,
+                    table: this.table,
+                    prefix: '',
+                });
                 andClauses.push(...opClauses);
                 continue;
             }
@@ -3374,7 +3419,11 @@ class QueryInterface {
                 }
             }
             if ((0, filters_js_1.isWhereOperator)(value)) {
-                const opClauses = this.buildOperatorClauses(qCol, value, params);
+                const opClauses = this.buildOperatorClauses(qCol, value, params, {
+                    meta,
+                    table: targetTable,
+                    prefix: `${qt}.`,
+                });
                 conditions.push(...opClauses);
                 continue;
             }
@@ -3541,7 +3590,11 @@ class QueryInterface {
                 }
             }
             if ((0, filters_js_1.isWhereOperator)(value)) {
-                clauses.push(...this.buildOperatorClauses(qCol, value, params));
+                clauses.push(...this.buildOperatorClauses(qCol, value, params, {
+                    meta: targetMeta,
+                    table: targetTable,
+                    prefix: `${alias}.`,
+                }));
                 continue;
             }
             this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(targetMeta, col), targetTable);
@@ -3600,7 +3653,7 @@ class QueryInterface {
                 }
             }
             if ((0, filters_js_1.isWhereOperator)(value)) {
-                this.collectOperatorParams(col, value, params);
+                this.collectOperatorParams(col, value, params, { meta: targetMeta, table: targetTable, prefix: '' });
                 continue;
             }
             this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(targetMeta, col), targetTable);
@@ -3677,16 +3730,55 @@ class QueryInterface {
         }
         return parts.join('&');
     }
+    /**
+     * 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.
+     */
+    resolveColumnRef(ref, ctx, mode) {
+        if (mode === 'insensitive') {
+            throw new errors_js_1.ValidationError(`[turbine] mode: 'insensitive' cannot be combined with a column reference ({ col: "${ref.col}" }). ` +
+                `Case-insensitive column-to-column comparison is not supported: use client.sql\`...\` ` +
+                `for lower(a) = lower(b).`);
+        }
+        const col = ctx.meta.columnMap[ref.col] ?? (0, schema_js_1.camelToSnake)(ref.col);
+        if (!ctx.meta.allColumns.includes(col)) {
+            throw new errors_js_1.ValidationError(`[turbine] Unknown field "${ref.col}" referenced by { col } in where on table "${ctx.table}". ` +
+                `Known fields: ${Object.keys(ctx.meta.columnMap).join(', ') || '(none)'}.`);
+        }
+        return col;
+    }
+    /**
+     * 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}).
+     */
+    columnRefSql(ref, ctx, mode) {
+        if (!ctx) {
+            throw new errors_js_1.ValidationError(`[turbine] Column reference { col: "${ref.col}" } is not supported in this filter context.`);
+        }
+        return `${ctx.prefix}${this.q(this.resolveColumnRef(ref, ctx, mode))}`;
+    }
     /**
      * 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.
      */
-    buildOperatorClauses(column, op, params) {
+    buildOperatorClauses(column, op, params, refCtx) {
         const clauses = [];
         if (op.equals !== undefined) {
             if (op.equals === null) {
                 clauses.push(`${column} IS NULL`);
             }
+            else if ((0, filters_js_1.isColumnRef)(op.equals)) {
+                clauses.push(`${column} = ${this.columnRefSql(op.equals, refCtx, op.mode)}`);
+            }
             else {
                 (0, filters_js_1.assertBindableEqualsOperand)(op.equals, column);
                 params.push(op.equals);
@@ -3694,25 +3786,48 @@ class QueryInterface {
             }
         }
         if (op.gt !== undefined) {
-            params.push(op.gt);
-            clauses.push(`${column} > ${this.p(params.length)}`);
+            if ((0, filters_js_1.isColumnRef)(op.gt)) {
+                clauses.push(`${column} > ${this.columnRefSql(op.gt, refCtx, op.mode)}`);
+            }
+            else {
+                params.push(op.gt);
+                clauses.push(`${column} > ${this.p(params.length)}`);
+            }
         }
         if (op.gte !== undefined) {
-            params.push(op.gte);
-            clauses.push(`${column} >= ${this.p(params.length)}`);
+            if ((0, filters_js_1.isColumnRef)(op.gte)) {
+                clauses.push(`${column} >= ${this.columnRefSql(op.gte, refCtx, op.mode)}`);
+            }
+            else {
+                params.push(op.gte);
+                clauses.push(`${column} >= ${this.p(params.length)}`);
+            }
         }
         if (op.lt !== undefined) {
-            params.push(op.lt);
-            clauses.push(`${column} < ${this.p(params.length)}`);
+            if ((0, filters_js_1.isColumnRef)(op.lt)) {
+                clauses.push(`${column} < ${this.columnRefSql(op.lt, refCtx, op.mode)}`);
+            }
+            else {
+                params.push(op.lt);
+                clauses.push(`${column} < ${this.p(params.length)}`);
+            }
         }
         if (op.lte !== undefined) {
-            params.push(op.lte);
-            clauses.push(`${column} <= ${this.p(params.length)}`);
+            if ((0, filters_js_1.isColumnRef)(op.lte)) {
+                clauses.push(`${column} <= ${this.columnRefSql(op.lte, refCtx, op.mode)}`);
+            }
+            else {
+                params.push(op.lte);
+                clauses.push(`${column} <= ${this.p(params.length)}`);
+            }
         }
         if (op.not !== undefined) {
             if (op.not === null) {
                 clauses.push(`${column} IS NOT NULL`);
             }
+            else if ((0, filters_js_1.isColumnRef)(op.not)) {
+                clauses.push(`${column} != ${this.columnRefSql(op.not, refCtx, op.mode)}`);
+            }
             else {
                 params.push(op.not);
                 clauses.push(`${column} != ${this.p(params.length)}`);
@@ -3763,6 +3878,11 @@ class QueryInterface {
         if ((0, filters_js_1.isVectorOrderBy)(d)) {
             return `vec(${d.distance.metric},${d.distance.direction ?? 'asc'})`;
         }
+        // JSON-path ordering: direction, cast kind, and nulls placement change the
+        // SQL text; the path itself is a bound param and stays OUT of the key.
+        if ((0, filters_js_1.isJsonPathOrderBy)(d)) {
+            return `jp(${d.direction ?? 'asc'},${d.type === 'numeric' ? 'num' : 'text'},${d.nulls ?? ''})`;
+        }
         if ((0, filters_js_1.isOrderBySpec)(d))
             return `spec(${d.sort},${d.nulls ?? ''})`;
         if (d && typeof d === 'object') {
@@ -3808,6 +3928,11 @@ class QueryInterface {
                 const safeDir = value.distance.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
                 return `${this.q(rawColumn)} ${operator} ${placeholder} ${safeDir}`;
             }
+            // JSON-path ordering: { path: [...], direction?, type?, nulls? } on a
+            // json/jsonb column of THIS table. Path is bound as one text[] param.
+            if ((0, filters_js_1.isJsonPathOrderBy)(value)) {
+                return this.buildJsonPathOrderEntry(this.table, this.tableMeta, key, value, '', params);
+            }
             // Relation ordering: an object value that is not a vector or OrderBySpec,
             // keyed by a relation name (`{ posts: { _count: 'desc' } }` / `{ author:
             // { name: 'asc' } }`).
@@ -3834,6 +3959,7 @@ class QueryInterface {
             value !== null &&
             !Array.isArray(value) &&
             !(0, filters_js_1.isVectorOrderBy)(value) &&
+            !(0, filters_js_1.isJsonPathOrderBy)(value) &&
             !(0, filters_js_1.isOrderBySpec)(value));
     }
     /**
@@ -3850,6 +3976,63 @@ class QueryInterface {
         }
         return nulls === 'first' ? ' NULLS FIRST' : ' NULLS LAST';
     }
+    /**
+     * 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").
+     */
+    resolveOrderByColumn(table, meta, key) {
+        const col = meta.columnMap[key] ?? (0, schema_js_1.camelToSnake)(key);
+        if (!meta.allColumns.includes(col)) {
+            throw new errors_js_1.ValidationError(`[turbine] Unknown field "${key}" in orderBy on table "${table}". ` +
+                `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
+        }
+        return col;
+    }
+    /**
+     * 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.
+     */
+    validateJsonPathOrderBy(table, meta, field, spec) {
+        const col = this.resolveOrderByColumn(table, meta, field);
+        if (spec.path.length === 0 ||
+            spec.path.some((el) => typeof el !== 'string' && !(typeof el === 'number' && Number.isFinite(el)))) {
+            throw new errors_js_1.ValidationError(`[turbine] JSON-path orderBy on "${field}" (table "${table}") requires a non-empty \`path\` array ` +
+                `of keys/indexes (e.g. { path: ['weight'], direction: 'asc' }).`);
+        }
+        const colType = this.pgTypeForColumn(meta, col);
+        if (colType !== 'json' && colType !== 'jsonb') {
+            throw new errors_js_1.ValidationError(`[turbine] JSON-path orderBy on "${field}": column "${col}" on table "${table}" is not a JSON column ` +
+                `(actual type: ${colType}).`);
+        }
+        return col;
+    }
+    /**
+     * 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).
+     */
+    buildJsonPathOrderEntry(table, meta, field, spec, prefix, params) {
+        const col = this.validateJsonPathOrderBy(table, meta, field, spec);
+        if (!params) {
+            throw new errors_js_1.ValidationError(`[turbine] JSON-path ordering on "${field}" is not supported in this orderBy context.`);
+        }
+        params.push(spec.path.map(String));
+        const extract = this.dialect.buildJsonPathExtract(`${prefix}${this.q(col)}`, this.p(params.length));
+        const lhs = spec.type === 'numeric' ? this.castJsonNumeric(extract) : extract;
+        const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+        return `${lhs} ${dir}${this.nullsSuffix(spec.nulls)}`;
+    }
     /**
      * Compile a relation ordering term. For a to-many relation the only allowed
      * key is `_count`, which becomes a correlated `COUNT(*)` subquery. For a
@@ -3858,12 +4041,19 @@ class QueryInterface {
      *
      * 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`.
      */
-    buildRelationOrderBy(relName, value, alias, params) {
-        const relDef = this.tableMeta.relations[relName];
+    buildRelationOrderBy(relName, value, alias, params, ctx) {
+        const ownerMeta = ctx?.meta ?? this.tableMeta;
+        const ownerTable = ctx?.table ?? this.table;
+        const parentRef = ctx?.parentRef ?? this.table;
+        const relDef = ownerMeta.relations[relName];
         if (!relDef) {
-            throw new errors_js_1.RelationError(`[turbine] Unknown relation "${relName}" in orderBy on table "${this.table}". ` +
-                `Available: ${Object.keys(this.tableMeta.relations).join(', ')}`);
+            throw new errors_js_1.RelationError(`[turbine] Unknown relation "${relName}" in orderBy on table "${ownerTable}". ` +
+                `Available: ${Object.keys(ownerMeta.relations).join(', ')}`);
         }
         // To-many: only `_count` is meaningful → correlated COUNT(*) subquery.
         if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
@@ -3873,14 +4063,14 @@ class QueryInterface {
                     `(got: ${keys.join(', ') || '(empty)'}).`);
             }
             const { dir } = (0, filters_js_1.normalizeOrderBy)(value._count);
-            return `${this.buildRelationCountExpr(relDef, this.table, alias, params)} ${dir}`;
+            return `${this.buildRelationCountExpr(relDef, parentRef, alias, params)} ${dir}`;
         }
         // To-one: each entry orders by a correlated scalar subquery on a target column.
         const targetMeta = this.schema.tables[relDef.to];
         if (!targetMeta)
             throw new errors_js_1.RelationError(`[turbine] Unknown relation target "${relDef.to}"`);
         const qTarget = this.q(relDef.to);
-        const qParent = this.q(this.table);
+        const qParent = this.q(parentRef);
         // belongsTo: alias.referenceKey = parent.foreignKey; hasOne: reversed.
         const correlation = relDef.type === 'belongsTo'
             ? this.dialect.buildCorrelation(alias, relDef.referenceKey, qParent, relDef.foreignKey)
@@ -3891,7 +4081,9 @@ class QueryInterface {
         }
         return entries
             .map(([col, dirValue]) => {
-            const snakeCol = (0, schema_js_1.camelToSnake)(col);
+            // columnMap-first resolution (camelToSnake fallback): mirrors the
+            // scalar orderBy path so camelCase-named DB columns resolve here too.
+            const snakeCol = targetMeta.columnMap[col] ?? (0, schema_js_1.camelToSnake)(col);
             if (!targetMeta.allColumns.includes(snakeCol)) {
                 throw new errors_js_1.ValidationError(`[turbine] Unknown column "${col}" in orderBy on relation "${relName}" (table "${relDef.to}").`);
             }
@@ -3909,6 +4101,74 @@ class QueryInterface {
         })
             .join(', ');
     }
+    /**
+     * 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}.
+     */
+    buildRelationOrderClause(targetTable, targetMeta, alias, orderEntries, params) {
+        let relOrdCounter = 0;
+        const orders = orderEntries
+            .map(([key, dirValue]) => {
+            if ((0, filters_js_1.isVectorOrderBy)(dirValue)) {
+                throw new errors_js_1.ValidationError(`[turbine] Vector distance ordering on "${key}" is only supported in a top-level findMany orderBy.`);
+            }
+            if ((0, filters_js_1.isJsonPathOrderBy)(dirValue)) {
+                return this.buildJsonPathOrderEntry(targetTable, targetMeta, key, dirValue, `${alias}.`, params);
+            }
+            if (this.isRelationOrderByValue(dirValue)) {
+                return this.buildRelationOrderBy(key, dirValue, `${alias}ord${relOrdCounter++}`, params, { meta: targetMeta, table: targetTable, parentRef: alias });
+            }
+            const col = this.resolveOrderByColumn(targetTable, targetMeta, key);
+            const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(dirValue);
+            return `${alias}.${this.q(col)} ${dir}${this.nullsSuffix(nulls)}`;
+        })
+            .join(', ');
+        return ` ORDER BY ${orders}`;
+    }
+    /**
+     * 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.
+     */
+    collectRelationOrderParams(targetTable, targetMeta, orderEntries, params) {
+        for (const [key, dirValue] of orderEntries) {
+            if ((0, filters_js_1.isVectorOrderBy)(dirValue)) {
+                throw new errors_js_1.ValidationError(`[turbine] Vector distance ordering on "${key}" is only supported in a top-level findMany orderBy.`);
+            }
+            if ((0, filters_js_1.isJsonPathOrderBy)(dirValue)) {
+                this.validateJsonPathOrderBy(targetTable, targetMeta, key, dirValue);
+                params.push(dirValue.path.map(String));
+                continue;
+            }
+            if (this.isRelationOrderByValue(dirValue)) {
+                const relDef = targetMeta.relations[key];
+                if (relDef && (relDef.type === 'hasMany' || relDef.type === 'manyToMany')) {
+                    this.collectRelationCountParams(relDef, params);
+                }
+                else if (relDef) {
+                    for (const _col of Object.keys(dirValue)) {
+                        this.collectTargetGlobalFilterAlias(relDef.to, params);
+                    }
+                }
+                continue;
+            }
+            this.resolveOrderByColumn(targetTable, targetMeta, key);
+        }
+    }
     /**
      * Build a correlated `(SELECT COUNT(*) …)` scalar subquery for a to-many
      * relation, correlated to `parentRef`. hasMany counts child rows via the FK;
@@ -4628,20 +4888,13 @@ class QueryInterface {
         // Quote parent ref — can be a table name or auto-generated alias
         const qParent = this.q(parentRef);
         const qTarget = this.q(targetTable);
-        // Build ORDER BY for json_agg
+        // Build ORDER BY for json_agg: unified with the top-level orderBy surface
+        // (columnMap resolution, OrderBySpec nulls, JSON-path, relation ordering).
+        // Param pushes here land BEFORE the spec.where params, mirrored by
+        // collectRelationSubqueryParams.
         let orderClause = '';
         if (relOrderEntries.length > 0) {
-            const orders = relOrderEntries
-                .map(([k, dirValue]) => {
-                const col = (0, schema_js_1.camelToSnake)(k);
-                if (!targetMeta.allColumns.includes(col)) {
-                    throw new errors_js_1.ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
-                }
-                const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(dirValue);
-                return `${alias}.${this.q(col)} ${dir}${this.nullsSuffix(nulls)}`;
-            })
-                .join(', ');
-            orderClause = ` ORDER BY ${orders}`;
+            orderClause = this.buildRelationOrderClause(targetTable, targetMeta, alias, relOrderEntries, params);
         }
         // Build WHERE — correlate to parent via parentRef (alias or table name).
         // For hasMany/hasOne: TARGET has the FK (RelationDef.foreignKey is always
@@ -4715,8 +4968,10 @@ class QueryInterface {
             const inlineOrder = this.dialect.aggSupportsInlineOrderBy ? orderClause.trim() || undefined : undefined;
             return `SELECT ${this.dialect.buildJsonArrayAgg(jsonObj, inlineOrder)} FROM ${qTarget} ${alias} WHERE ${whereClause}`;
         }
-        // belongsTo / hasOne — return single object
-        return `SELECT ${jsonObj} FROM ${qTarget} ${alias} WHERE ${whereClause} LIMIT 1`;
+        // belongsTo / hasOne: return single object. An orderBy picks WHICH row
+        // the LIMIT 1 keeps (deterministic hasOne over a non-unique FK): matching
+        // the batched strategy, which orders its flat follow-up and takes bucket[0].
+        return `SELECT ${jsonObj} FROM ${qTarget} ${alias} WHERE ${whereClause}${orderClause} LIMIT 1`;
     }
     /**
      * Build the json_agg subquery for a `manyToMany` relation, JOINing the target
@@ -4774,22 +5029,15 @@ class QueryInterface {
         let whereClause = sourceKeys
             .map((jcol, i) => `${jalias}.${this.q(jcol)} = ${qParent}.${this.q(refKeys[i])}`)
             .join(' AND ');
-        // ORDER BY on the target rows. `orderBy: {}` (no defined entries) is
-        // treated as absent — it must not render a dangling `ORDER BY `.
+        // ORDER BY on the target rows: unified with the top-level orderBy surface
+        // (columnMap resolution, OrderBySpec nulls, JSON-path, relation ordering).
+        // `orderBy: {}` (no defined entries) is treated as absent: it must not
+        // render a dangling `ORDER BY `. Param pushes here land BEFORE the
+        // spec.where params, mirrored by collectRelationSubqueryParams' m2m branch.
         const relOrderEntries = spec !== true && spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
         let orderClause = '';
         if (relOrderEntries.length > 0) {
-            const orders = relOrderEntries
-                .map(([k, dirValue]) => {
-                const col = (0, schema_js_1.camelToSnake)(k);
-                if (!targetMeta.allColumns.includes(col)) {
-                    throw new errors_js_1.ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
-                }
-                const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(dirValue);
-                return `${talias}.${this.q(col)} ${dir}${this.nullsSuffix(nulls)}`;
-            })
-                .join(', ');
-            orderClause = ` ORDER BY ${orders}`;
+            orderClause = this.buildRelationOrderClause(targetTable, targetMeta, talias, relOrderEntries, params);
         }
         // Additional WHERE filters on the target — full scalar where surface,
         // properly parameterized against the target alias.