turbine-orm 0.31.0 → 0.32.0

package/dist/query/builder.js

@@ -15,8 +15,8 @@ import { CircularRelationError, NotFoundError, OptimisticLockError, RelationErro
 import { missingIndexForRelation } from '../index-advisor.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '../nested-write.js';
 import { camelToSnake, normalizeKeyColumns, snakeToCamel } from '../schema.js';
-import { includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, resolveCountRelations, stripFields, } from './batched-loader.js';
-import { assertBindableEqualsOperand, findArrayUniqueKey, findJsonUniqueKey, fingerprintJsonFilterShape, fingerprintOperatorShape, isArrayFilter, isColumnRef, isJsonFilter, isJsonPathOrderBy, isOrderBySpec, isTextSearchFilter, isUnmatchedPlainObject, isVectorFilter, isVectorOrderBy, isWhereOperator, JSON_RANGE_OPERATORS, normalizeOrderBy, sortedEntries, sortedKeys, UPDATE_OPERATOR_KEYS, VECTOR_DISTANCE_COMPARATORS, VECTOR_METRIC_OPERATORS, validateTextSearchConfig, } from './filters.js';
+import { includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, resolveCountRelations, stripFields, } from './batched-loader.js';
+import { assertBindableEqualsOperand, findArrayUniqueKey, findJsonUniqueKey, fingerprintJsonFilterShape, fingerprintOperatorShape, isArrayFilter, isColumnRef, isJsonFilter, isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isTextSearchFilter, isUnmatchedPlainObject, isVectorFilter, isVectorOrderBy, isWhereOperator, JSON_RANGE_OPERATORS, normalizeOrderBy, sortedEntries, sortedKeys, UPDATE_OPERATOR_KEYS, VECTOR_DISTANCE_COMPARATORS, VECTOR_METRIC_OPERATORS, validateTextSearchConfig, } from './filters.js';
 import { escapeLike, LRUCache, OPERATOR_KEYS, parseDbDate, sqlToPreparedName } from './utils.js';
 /** Relations already warned about missing FK indexes (once per process, dev only). */
 const unindexedRelationWarned = new Set();
@@ -291,6 +291,10 @@ export class QueryInterface {
      */
     async runFindManyBatched(args) {
         const withClause = args.with;
+        // Scope-rule parity with the join strategy (which throws at SQL build):
+        // reject nested pick-row ordering BEFORE the base query so acceptance
+        // never depends on how many rows come back.
+        rejectNestedPickOrder(withClause);
         // Capture the opt-out from the ARGS before any await: this.currentSkip is
         // instance state on a cached accessor, so a concurrent build during the
         // base-query await would overwrite it (tenant query loading relations with
@@ -516,6 +520,8 @@ export class QueryInterface {
      */
     async runFindUniqueBatched(args) {
         const withClause = args.with;
+        // Same scope-rule parity as runFindManyBatched: reject before querying.
+        rejectNestedPickOrder(withClause);
         const needed = neededParentKeyFields(this.tableMeta, withClause);
         const proj = includeKeysForBatching(args.select, args.omit, needed);
         const baseArgs = { ...args, with: undefined, select: proj.select, omit: proj.omit };
@@ -702,6 +708,21 @@ export class QueryInterface {
     // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindMany(args) {
         this.currentSkip = args?.skipGlobalFilters;
+        // `distinct` + relation orderBy is refused up front (E003): the distinct
+        // path re-orders in an outer wrapper (`... AS "<table>_distinct" ORDER BY
+        // <userOrder>`) where a correlated relation subquery (pick-row, `_count`,
+        // to-one relation ordering) would reference the parent table name out of
+        // scope — a guaranteed "missing FROM-clause entry" crash on Postgres.
+        // Checked BEFORE the SQL cache so build and warm-cache paths throw
+        // identically (same rule as the vector guard inside the distinct branch).
+        if (args?.distinct && args.distinct.length > 0 && args.orderBy) {
+            for (const d of Object.values(args.orderBy)) {
+                if (this.isRelationOrderByValue(d)) {
+                    throw new ValidationError('[turbine] `distinct` cannot be combined with relation orderBy (pick-row, `_count`, or ' +
+                        'to-one relation ordering): the outer re-order cannot reference the parent table.');
+                }
+            }
+        }
         const columnsList = this.resolveColumns(args?.select, args?.omit);
         const colKey = columnsList ? columnsList.join(',') : '*';
         // AND-merge this table's global filter into the user where; `hasWhere` gates
@@ -715,7 +736,7 @@ export class QueryInterface {
         const withFp = args?.with ? this.withFingerprint(args.with) : '';
         const orderFp = args?.orderBy
             ? Object.entries(args.orderBy)
-                .map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d)}`)
+                .map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d, this.tableMeta.relations[k]?.to)}`)
                 .join(',')
             : '';
         const cursorFp = args?.cursor
@@ -1576,67 +1597,124 @@ export class QueryInterface {
         const meta = this.schema.tables[this.table];
         if (meta) {
             for (const key of args.by) {
-                if (!(key in meta.columnMap)) {
+                if (typeof key === 'string' && !(key in meta.columnMap)) {
                     throw new ValidationError(`Unknown column "${key}" in groupBy for table "${this.table}"`);
                 }
             }
         }
         this.currentSkip = args.skipGlobalFilters;
-        const groupColsRaw = args.by.map((k) => this.toColumn(k));
-        const groupCols = groupColsRaw.map((c) => this.q(c));
         const gbWhere = this.mergeGlobalFilter(args.where);
         const { sql: whereSql, params } = gbWhere
             ? this.buildWhere(gbWhere)
             : { sql: '', params: [] };
-        // Build SELECT expressions: group-by columns + aggregate functions
-        const selectExprs = [...groupCols];
+        // Row source. Plain: `"table"<WHERE>`. With `distinctOn` (PostgreSQL
+        // only), the groupBy runs over one representative row per column
+        // combination: the wrapper carries args.where INSIDE it (filter before
+        // picking) and is aliased as the table name so every outer expression is
+        // byte-identical either way.
+        const fromSql = args.distinctOn
+            ? this.buildDistinctOnSource(args.distinctOn, whereSql, params)
+            : `${this.q(this.table)}${whereSql}`;
+        // Group keys: plain columns and/or JSON-path keys. Output-name collisions
+        // are rejected up front — and the check runs over the EMITTED SQL output
+        // column names (snake_case column / JSON alias / `_agg_key` aggregate
+        // alias), not just the given arg keys: the driver keeps only the LAST
+        // duplicate field per row object, so a JSON alias equal to another key's
+        // snake_case column (or an aggregate output alias) would silently clobber
+        // that value in the results.
+        const groupExprs = [];
+        const selectExprs = [];
+        /** by entries in order: how to read each group key off the result row. */
+        const byReaders = [];
+        const usedResultKeys = new Set();
+        const claimResultKey = (key, what) => {
+            if (key === '_count' || usedResultKeys.has(key)) {
+                throw new ValidationError(`[turbine] groupBy output name "${key}" (${what}) collides with another output column on table ` +
+                    `"${this.table}": set an explicit \`alias\` (or rename the aggregate key) to disambiguate.`);
+            }
+            usedResultKeys.add(key);
+        };
+        for (const entry of args.by) {
+            if (typeof entry === 'string') {
+                const col = this.toColumn(entry);
+                claimResultKey(entry, `column "${col}"`);
+                // The emitted output column is the snake_case name; claim it too (when
+                // it differs from the result key) so a JSON alias like 'created_at'
+                // cannot silently shadow the 'createdAt' group key on the wire.
+                if (col !== entry)
+                    claimResultKey(col, `column "${col}"`);
+                groupExprs.push(this.q(col));
+                selectExprs.push(this.q(col));
+                byReaders.push({ resultKey: entry, rowKey: col, raw: false });
+            }
+            else {
+                const col = this.resolveJsonPathTarget('group key', entry.field, entry.path);
+                params.push(this.jsonPathParam(entry.path));
+                const extract = this.dialect.buildJsonPathExtract(this.q(col), this.p(params.length));
+                const alias = entry.alias ?? String(entry.path[entry.path.length - 1]);
+                claimResultKey(alias, `JSON path on "${entry.field}"`);
+                // Same expression (and the same $n placeholder) in SELECT and GROUP BY.
+                selectExprs.push(`(${extract}) AS ${this.q(alias)}`);
+                groupExprs.push(extract);
+                byReaders.push({ resultKey: alias, rowKey: alias, raw: true });
+            }
+        }
         // _count
         if (args._count === true || args._count === undefined) {
             // default: always include count
             selectExprs.push(`${this.castAgg('COUNT(*)', 'int')} AS _count`);
         }
-        // _sum
-        if (args._sum) {
-            for (const [field, enabled] of Object.entries(args._sum)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`SUM(${this.q(col)}) AS ${this.q(`_sum_${col}`)}`);
-                }
-            }
-        }
-        // _avg
-        if (args._avg) {
-            for (const [field, enabled] of Object.entries(args._avg)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`${this.castAgg(`AVG(${this.q(col)})`, 'float')} AS ${this.q(`_avg_${col}`)}`);
-                }
-            }
-        }
-        // _min
-        if (args._min) {
-            for (const [field, enabled] of Object.entries(args._min)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`MIN(${this.q(col)}) AS ${this.q(`_min_${col}`)}`);
+        // _sum / _avg / _min / _max: `true` keeps the plain-column behavior; a
+        // {@link JsonPathAggregateTarget} aggregates a JSON path under the arg key
+        // as alias. `jsonAggFields` routes each JSON-aggregate row key back to its
+        // alias (and coercion kind) in the transform; `jsonAggExprs` lets HAVING
+        // reuse the exact aggregate expression (same placeholders) by alias.
+        const jsonAggFields = new Map();
+        const jsonAggExprs = new Map();
+        const buildAggregates = (aggKey, sqlFn, spec) => {
+            if (!spec)
+                return;
+            for (const [key, target] of Object.entries(spec)) {
+                if (!target)
+                    continue;
+                if (target === true) {
+                    const col = this.toColumn(key);
+                    // Aggregate output aliases share the same output-name namespace as
+                    // the group keys: `_sum: { totalPrice: true, total_price: {json} }`
+                    // would emit two "_sum_total_price" columns and silently drop one.
+                    claimResultKey(`${aggKey}_${col}`, `${aggKey} of column "${col}"`);
+                    const inner = `${sqlFn}(${this.q(col)})`;
+                    const expr = aggKey === '_avg' ? this.castAgg(inner, 'float') : inner;
+                    selectExprs.push(`${expr} AS ${this.q(`${aggKey}_${col}`)}`);
+                    continue;
                 }
-            }
-        }
-        // _max
-        if (args._max) {
-            for (const [field, enabled] of Object.entries(args._max)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`MAX(${this.q(col)}) AS ${this.q(`_max_${col}`)}`);
+                const col = this.resolveJsonPathTarget(`${aggKey} target "${key}"`, target.field, target.path);
+                const alwaysNumeric = aggKey === '_sum' || aggKey === '_avg';
+                if (alwaysNumeric && target.type === 'text') {
+                    throw new ValidationError(`[turbine] groupBy ${aggKey} target "${key}" on table "${this.table}": ` +
+                        `${aggKey} over a JSON path is always numeric: remove \`type: 'text'\`.`);
                 }
+                const numeric = alwaysNumeric || target.type === 'numeric';
+                claimResultKey(`${aggKey}_${key}`, `${aggKey} JSON target "${key}"`);
+                params.push(this.jsonPathParam(target.path));
+                const extract = this.dialect.buildJsonPathExtract(this.q(col), this.p(params.length));
+                const inner = `${sqlFn}(${numeric ? this.castJsonNumeric(extract) : extract})`;
+                const expr = aggKey === '_avg' ? this.castAgg(inner, 'float') : inner;
+                selectExprs.push(`${expr} AS ${this.q(`${aggKey}_${key}`)}`);
+                jsonAggFields.set(`${aggKey}_${key}`, { field: key, numeric });
+                jsonAggExprs.set(`${key}:${aggKey}`, expr);
             }
-        }
-        let sql = `SELECT ${selectExprs.join(', ')} FROM ${this.q(this.table)}${whereSql} GROUP BY ${groupCols.join(', ')}`;
+        };
+        buildAggregates('_sum', 'SUM', args._sum);
+        buildAggregates('_avg', 'AVG', args._avg);
+        buildAggregates('_min', 'MIN', args._min);
+        buildAggregates('_max', 'MAX', args._max);
+        let sql = `SELECT ${selectExprs.join(', ')} FROM ${fromSql} GROUP BY ${groupExprs.join(', ')}`;
         // HAVING — filter whole groups by their aggregate values.
         // Appends to the same `params` array, so placeholders continue from the
         // WHERE clause's parameter positions (this.p(params.length) below).
         if (args.having) {
-            const havingClauses = this.buildHavingClauses(args.having, params);
+            const havingClauses = this.buildHavingClauses(args.having, params, jsonAggExprs);
             if (havingClauses.length > 0) {
                 sql += ` HAVING ${havingClauses.join(' AND ')}`;
             }
@@ -1652,9 +1730,11 @@ export class QueryInterface {
                 const parsed = this.parseRow(row, this.table);
                 // Restructure aggregate results into nested objects (Prisma-style)
                 const restructured = {};
-                // Copy group-by fields
-                for (const field of args.by) {
-                    restructured[field] = parsed[field];
+                // Copy group-by fields. JSON-path keys read their alias off the raw
+                // row (the alias is not a table column, so parseRow's snake→camel
+                // mapping must not touch it).
+                for (const reader of byReaders) {
+                    restructured[reader.resultKey] = reader.raw ? row[reader.rowKey] : parsed[reader.resultKey];
                 }
                 // _count
                 if ('_count' in row) {
@@ -1669,29 +1749,27 @@ export class QueryInterface {
                 const minObj = {};
                 const maxObj = {};
                 let hasSums = false, hasAvgs = false, hasMins = false, hasMaxs = false;
+                // JSON-path aggregates keep their arg key verbatim; plain-column
+                // aggregates keep the snake→camel field mapping.
+                const jsonAgg = (rawKey) => jsonAggFields.get(rawKey);
+                const fieldFor = (rawKey, col) => jsonAgg(rawKey)?.field ?? this.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
                 for (const [rawKey, rawValue] of Object.entries(row)) {
                     if (rawKey.startsWith('_sum_')) {
-                        const col = rawKey.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                        sumObj[field] = rawValue !== null ? Number(rawValue) : null;
+                        sumObj[fieldFor(rawKey, rawKey.slice(5))] = rawValue !== null ? Number(rawValue) : null;
                         hasSums = true;
                     }
                     else if (rawKey.startsWith('_avg_')) {
-                        const col = rawKey.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                        avgObj[field] = rawValue !== null ? Number(rawValue) : null;
+                        avgObj[fieldFor(rawKey, rawKey.slice(5))] = rawValue !== null ? Number(rawValue) : null;
                         hasAvgs = true;
                     }
                     else if (rawKey.startsWith('_min_')) {
-                        const col = rawKey.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                        minObj[field] = rawValue;
+                        const j = jsonAgg(rawKey);
+                        minObj[fieldFor(rawKey, rawKey.slice(5))] = j?.numeric && rawValue !== null ? Number(rawValue) : rawValue;
                         hasMins = true;
                     }
                     else if (rawKey.startsWith('_max_')) {
-                        const col = rawKey.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                        maxObj[field] = rawValue;
+                        const j = jsonAgg(rawKey);
+                        maxObj[fieldFor(rawKey, rawKey.slice(5))] = j?.numeric && rawValue !== null ? Number(rawValue) : rawValue;
                         hasMaxs = true;
                     }
                 }
@@ -1708,6 +1786,75 @@ export class QueryInterface {
             tag: `${this.table}.groupBy`,
         };
     }
+    /**
+     * 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.
+     */
+    resolveJsonPathTarget(context, field, path) {
+        if (typeof field !== 'string') {
+            throw new ValidationError(`[turbine] groupBy ${context} on table "${this.table}" requires a string \`field\`.`);
+        }
+        const col = this.toColumn(field);
+        if (!Array.isArray(path) ||
+            path.length === 0 ||
+            path.some((el) => typeof el !== 'string' && !(typeof el === 'number' && Number.isFinite(el)))) {
+            throw new ValidationError(`[turbine] groupBy ${context} on "${field}" (table "${this.table}") requires a non-empty \`path\` ` +
+                `array of keys/indexes (e.g. { field: '${field}', path: ['category'] }).`);
+        }
+        const colType = this.pgTypeForColumn(this.tableMeta, col);
+        if (!this.isJsonColumnType(colType)) {
+            throw new ValidationError(`[turbine] groupBy ${context} on "${field}": column "${col}" on table "${this.table}" is not a JSON ` +
+                `column (actual type: ${colType}).`);
+        }
+        return col;
+    }
+    /**
+     * 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.
+     */
+    buildDistinctOnSource(distinctOn, whereSql, params) {
+        if (this.dialect.name !== 'postgresql') {
+            throw new UnsupportedFeatureError('DISTINCT ON row source (groupBy distinctOn)', this.dialect.name, 'groupBy({ distinctOn }) requires PostgreSQL: SELECT DISTINCT ON is not portable.');
+        }
+        if (!Array.isArray(distinctOn.columns) || distinctOn.columns.length === 0) {
+            throw new ValidationError(`[turbine] groupBy distinctOn on table "${this.table}" requires a non-empty \`columns\` array.`);
+        }
+        const orderEntries = Object.entries(distinctOn.orderBy ?? {});
+        if (orderEntries.length === 0) {
+            throw new ValidationError(`[turbine] groupBy distinctOn on table "${this.table}" requires \`orderBy\` to pick ONE row per ` +
+                "column combination deterministically (e.g. orderBy: { createdAt: 'desc' }).");
+        }
+        const distinctCols = distinctOn.columns.map((c) => this.q(this.toColumn(c)));
+        // DISTINCT ON expressions must lead the ORDER BY; the user's orderBy then
+        // decides which row survives per combination.
+        const orderParts = [...distinctCols];
+        for (const [key, value] of orderEntries) {
+            if (isJsonPathOrderBy(value)) {
+                orderParts.push(this.buildJsonPathOrderEntry(this.table, this.tableMeta, key, value, '', params));
+                continue;
+            }
+            if (isVectorOrderBy(value) || this.isRelationOrderByValue(value)) {
+                throw new ValidationError(`[turbine] groupBy distinctOn.orderBy on "${key}" (table "${this.table}") supports plain columns, ` +
+                    'sort specs, and JSON-path orderings only.');
+            }
+            const col = this.resolveOrderByColumn(this.table, this.tableMeta, key);
+            const { dir, nulls } = normalizeOrderBy(value);
+            orderParts.push(`${this.q(col)} ${dir}${this.nullsSuffix(nulls)}`);
+        }
+        return (`(SELECT DISTINCT ON (${distinctCols.join(', ')}) * FROM ${this.q(this.table)}${whereSql} ` +
+            `ORDER BY ${orderParts.join(', ')}) AS ${this.q(this.table)}`);
+    }
     /**
      * Build the SQL fragments for a {@link HavingClause}.
      *
@@ -1718,8 +1865,14 @@ export class QueryInterface {
      * 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.
      */
-    buildHavingClauses(having, params) {
+    buildHavingClauses(having, params, jsonAggExprs) {
         const clauses = [];
         // Maps the per-field aggregate key to its SQL function name. The set of
         // allowed keys is fixed here — any other key on a field's filter object is
@@ -1746,8 +1899,14 @@ export class QueryInterface {
             }
             // toColumn validates the field against schema metadata (throws
             // ValidationError on unknown columns) and q() quotes the identifier — no
-            // unvalidated identifier ever reaches the SQL string.
-            const quotedCol = this.q(this.toColumn(key));
+            // unvalidated identifier ever reaches the SQL string. Resolution is lazy:
+            // a JSON-path aggregate alias is not a column, so it must not hit
+            // toColumn when every aggregate under it resolves via `jsonAggExprs`.
+            let quotedCol = null;
+            const columnExpr = () => {
+                quotedCol ??= this.q(this.toColumn(key));
+                return quotedCol;
+            };
             for (const [aggKey, filter] of Object.entries(value)) {
                 if (filter === undefined)
                     continue;
@@ -1756,7 +1915,7 @@ export class QueryInterface {
                     throw new ValidationError(`[turbine] Unknown aggregate "${aggKey}" in having for field "${key}" on table "${this.table}". ` +
                         `Supported: ${Object.keys(aggFnByKey).join(', ')}.`);
                 }
-                const expr = `${fn}(${quotedCol})`;
+                const expr = jsonAggExprs?.get(`${key}:${aggKey}`) ?? `${fn}(${columnExpr()})`;
                 clauses.push(...this.buildHavingNumericClauses(expr, filter, params));
             }
         }
@@ -2403,7 +2562,7 @@ export class QueryInterface {
             // JSONB filter
             if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
                 const colType = this.getColumnPgType(rawColumn);
-                if (colType === 'json' || colType === 'jsonb') {
+                if (this.isJsonColumnType(colType)) {
                     this.collectJsonFilterParams(value, params, this.q(rawColumn));
                     continue;
                 }
@@ -2514,7 +2673,7 @@ export class QueryInterface {
             // the target column is json/jsonb.
             if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
                 const colType = this.pgTypeForColumn(meta, col);
-                if (colType === 'json' || colType === 'jsonb') {
+                if (this.isJsonColumnType(colType)) {
                     this.collectJsonFilterParams(value, params, `${this.q(targetTable)}.${this.q(col)}`);
                     continue;
                 }
@@ -2584,7 +2743,8 @@ export class QueryInterface {
         let pathPushed = false;
         const pushPathOnce = () => {
             if (!pathPushed) {
-                params.push(filter.path);
+                // Only reached when a path-requiring clause validated filter.path.
+                params.push(this.jsonPathParam(filter.path, filter.path));
                 pathPushed = true;
             }
         };
@@ -2636,15 +2796,20 @@ export class QueryInterface {
             // then the path bound as one text[] param.
             if (isJsonPathOrderBy(dir)) {
                 this.validateJsonPathOrderBy(this.table, this.tableMeta, key, dir);
-                params.push(dir.path.map(String));
+                params.push(this.jsonPathParam(dir.path));
                 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.
+            // subquery as `_count`: mirror its global-filter params. Pick-row
+            // ordering mirrors its full param chain (by-path / global filter /
+            // pick.where / pick.orderBy paths). To-one relation orderBy carries the
+            // target's global filter once per ordered column.
             if (this.isRelationOrderByValue(dir)) {
                 const relDef = this.tableMeta.relations[key];
-                if (relDef && (relDef.type === 'hasMany' || relDef.type === 'manyToMany')) {
+                if (relDef && isRelationPickOrderBy(dir)) {
+                    this.collectRelationPickOrderParams(key, relDef, dir, params);
+                }
+                else if (relDef && (relDef.type === 'hasMany' || relDef.type === 'manyToMany')) {
                     this.collectRelationCountParams(relDef, params);
                 }
                 else if (relDef) {
@@ -2734,7 +2899,8 @@ export class QueryInterface {
             }
             // orderBy shape (OrderBySpec nulls placement changes the SQL, so fingerprint it)
             if (opts.orderBy) {
-                const oEntries = Object.entries(opts.orderBy).map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d)}`);
+                const targetRels = this.schema.tables[relDef.to]?.relations;
+                const oEntries = Object.entries(opts.orderBy).map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d, targetRels?.[k]?.to)}`);
                 subParts.push(`o=${oEntries.join(',')}`);
             }
             // limit presence
@@ -3144,7 +3310,7 @@ export class QueryInterface {
             // Handle JSONB filter operators (for json/jsonb columns)
             if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
                 const colType = this.getColumnPgType(rawColumn);
-                if (colType === 'json' || colType === 'jsonb') {
+                if (this.isJsonColumnType(colType)) {
                     const jsonClauses = this.buildJsonFilterClauses(column, value, params);
                     andClauses.push(...jsonClauses);
                     continue;
@@ -3359,7 +3525,7 @@ export class QueryInterface {
             // jsonb value, silently matching nothing.
             if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
                 const colType = this.pgTypeForColumn(meta, col);
-                if (colType === 'json' || colType === 'jsonb') {
+                if (this.isJsonColumnType(colType)) {
                     conditions.push(...this.buildJsonFilterClauses(qCol, value, params));
                     continue;
                 }
@@ -3459,7 +3625,7 @@ export class QueryInterface {
     assertBindableEqualityValue(rawColumn, value, columnPgType, table) {
         if (!isUnmatchedPlainObject(value))
             return;
-        if (columnPgType === 'json' || columnPgType === 'jsonb')
+        if (this.isJsonColumnType(columnPgType))
             return;
         const badKeys = Object.keys(value);
         throw new ValidationError(badKeys.length === 0
@@ -3530,7 +3696,7 @@ export class QueryInterface {
             // bound as a plain equality value.
             if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
                 const colType = this.pgTypeForColumn(targetMeta, col);
-                if (colType === 'json' || colType === 'jsonb') {
+                if (this.isJsonColumnType(colType)) {
                     clauses.push(...this.buildJsonFilterClauses(qCol, value, params));
                     continue;
                 }
@@ -3603,7 +3769,7 @@ export class QueryInterface {
             // JSONB filter — mirrors buildAliasWhere.
             if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
                 const colType = this.pgTypeForColumn(targetMeta, col);
-                if (colType === 'json' || colType === 'jsonb') {
+                if (this.isJsonColumnType(colType)) {
                     this.collectJsonFilterParams(value, params, this.q(col));
                     continue;
                 }
@@ -3836,7 +4002,7 @@ export class QueryInterface {
      * vs relation-column never collide on one cached SQL string. Captures the
      * SQL-shaping bits (direction, nulls, metric, relation keys) — never values.
      */
-    orderByEntryFingerprint(d) {
+    orderByEntryFingerprint(d, targetTable) {
         // Vector KNN ordering changes the emitted operator by metric and adds a
         // `::vector` param, so metric + direction must be part of the cache key.
         if (isVectorOrderBy(d)) {
@@ -3847,13 +4013,36 @@ export class QueryInterface {
         if (isJsonPathOrderBy(d)) {
             return `jp(${d.direction ?? 'asc'},${d.type === 'numeric' ? 'num' : 'text'},${d.nulls ?? ''})`;
         }
+        // Pick-row relation ordering: the by-shape (column vs JSON path vs cast),
+        // direction, nulls, pick.orderBy shape, and pick.where SHAPE are all SQL
+        // text; the JSON paths and pick.where values are bound params and stay OUT
+        // of the key. `targetTable` (the relation's target, resolved by the
+        // caller) lets the pick.where fingerprint distinguish relation-filter
+        // shapes inside it: two pick.wheres that differ only in shape must never
+        // share one cached SQL string.
+        if (isRelationPickOrderBy(d)) {
+            const by = typeof d.by === 'string'
+                ? `col=${JSON.stringify(d.by)}`
+                : `jp(${JSON.stringify(d.by?.field)},${d.by?.type === 'numeric' ? 'num' : 'text'})`;
+            const pickOrder = Object.entries(d.pick?.orderBy ?? {})
+                .map(([k, v]) => `${k}:${this.orderByEntryFingerprint(v)}`)
+                .join(',');
+            const pickWhere = d.pick?.where
+                ? `;pw=${this.fingerprintAliasWhere(d.pick.where, targetTable)}`
+                : '';
+            return `pick(${by},${d.direction ?? 'asc'},${d.nulls ?? ''};po=${pickOrder}${pickWhere})`;
+        }
         if (isOrderBySpec(d))
             return `spec(${d.sort},${d.nulls ?? ''})`;
         if (d && typeof d === 'object') {
             // Relation ordering (`{ _count: 'desc' }` or `{ name: 'asc' }`).
+            // INSERTION order, never sorted: the compile side (buildRelationOrderBy)
+            // emits one ORDER BY term per entry in Object.entries order, so entry
+            // order is SQL-shaping precedence. A sorted fingerprint made
+            // `{ name: 'asc', email: 'desc' }` and the swapped literal share one
+            // cached SQL string — silently mis-ordered results on a warm cache.
             return `rel(${Object.entries(d)
                 .map(([k, v]) => `${k}=${this.orderByEntryFingerprint(v)}`)
-                .sort()
                 .join(',')})`;
         }
         return String(d);
@@ -3971,7 +4160,7 @@ export class QueryInterface {
                 `of keys/indexes (e.g. { path: ['weight'], direction: 'asc' }).`);
         }
         const colType = this.pgTypeForColumn(meta, col);
-        if (colType !== 'json' && colType !== 'jsonb') {
+        if (!this.isJsonColumnType(colType)) {
             throw new ValidationError(`[turbine] JSON-path orderBy on "${field}": column "${col}" on table "${table}" is not a JSON column ` +
                 `(actual type: ${colType}).`);
         }
@@ -3991,7 +4180,7 @@ export class QueryInterface {
         if (!params) {
             throw new ValidationError(`[turbine] JSON-path ordering on "${field}" is not supported in this orderBy context.`);
         }
-        params.push(spec.path.map(String));
+        params.push(this.jsonPathParam(spec.path));
         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';
@@ -4019,12 +4208,21 @@ export class QueryInterface {
             throw new RelationError(`[turbine] Unknown relation "${relName}" in orderBy on table "${ownerTable}". ` +
                 `Available: ${Object.keys(ownerMeta.relations).join(', ')}`);
         }
+        // Pick-row ordering (`{ pick, by }`): order by a value from ONE related
+        // row: a correlated scalar subquery with its own ORDER BY … LIMIT 1.
+        // Top-level findMany only (`ctx` present means we are inside a relation
+        // subquery's orderBy) and hasMany only: validatePickOrderBy throws the
+        // scope errors, shared with the cache-hit collect mirror.
+        if (isRelationPickOrderBy(value)) {
+            this.validatePickOrderBy(relName, relDef, value, ctx !== undefined);
+            return this.buildRelationPickOrderBy(relName, relDef, value, alias, parentRef, params);
+        }
         // To-many: only `_count` is meaningful → correlated COUNT(*) subquery.
         if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
             const keys = Object.keys(value);
             if (keys.length !== 1 || keys[0] !== '_count') {
                 throw new ValidationError(`[turbine] orderBy on to-many relation "${relName}" only supports "_count" ` +
-                    `(got: ${keys.join(', ') || '(empty)'}).`);
+                    `or a pick-row ordering ({ pick, by }) (got: ${keys.join(', ') || '(empty)'}).`);
             }
             const { dir } = normalizeOrderBy(value._count);
             return `${this.buildRelationCountExpr(relDef, parentRef, alias, params)} ${dir}`;
@@ -4065,6 +4263,145 @@ export class QueryInterface {
         })
             .join(', ');
     }
+    /**
+     * 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.
+     */
+    pickOrderNestedError(relName) {
+        return new ValidationError(`[turbine] Pick-row ordering on relation "${relName}" is only supported in a top-level ` +
+            'findMany orderBy: nested `with` orderBy does not support it.');
+    }
+    validatePickOrderBy(relName, relDef, spec, nested) {
+        if (nested) {
+            throw this.pickOrderNestedError(relName);
+        }
+        if (relDef.type === 'manyToMany') {
+            throw new ValidationError(`[turbine] Pick-row ordering is not supported on manyToMany relation "${relName}": ` +
+                'hasMany relations only.');
+        }
+        if (relDef.type !== 'hasMany') {
+            throw new ValidationError(`[turbine] Pick-row ordering is only for to-many (hasMany) relations; "${relName}" is ${relDef.type}. ` +
+                `Order by the target column directly instead ({ ${relName}: { <column>: 'asc' } }).`);
+        }
+        const pickOrder = spec.pick?.orderBy;
+        if (typeof spec.pick !== 'object' ||
+            spec.pick === null ||
+            typeof pickOrder !== 'object' ||
+            pickOrder === null ||
+            Object.keys(pickOrder).length === 0) {
+            throw new ValidationError(`[turbine] Pick-row ordering on relation "${relName}" requires \`pick.orderBy\` to choose ONE ` +
+                "related row deterministically (e.g. pick: { orderBy: { createdAt: 'desc' } }).");
+        }
+        const by = spec.by;
+        const validJsonBy = typeof by === 'object' && by !== null && typeof by.field === 'string' && Array.isArray(by.path);
+        if (typeof by !== 'string' && !validJsonBy) {
+            throw new ValidationError(`[turbine] Pick-row ordering on relation "${relName}" requires \`by\`: a target column name ` +
+                "or a JSON-path spec ({ field: 'data', path: ['title'] }).");
+        }
+    }
+    /**
+     * 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.
+     */
+    buildRelationPickOrderBy(relName, relDef, spec, alias, parentRef, params) {
+        if (!params) {
+            throw new ValidationError(`[turbine] Pick-row ordering on relation "${relName}" is only supported in a top-level findMany orderBy.`);
+        }
+        const targetMeta = this.schema.tables[relDef.to];
+        if (!targetMeta)
+            throw new RelationError(`[turbine] Unknown relation target "${relDef.to}"`);
+        // The value surfaced from the picked row (SELECT list: its param binds first).
+        let byExpr;
+        if (typeof spec.by === 'string') {
+            const col = this.resolveOrderByColumn(relDef.to, targetMeta, spec.by);
+            byExpr = `${alias}.${this.q(col)}`;
+        }
+        else {
+            const col = this.validateJsonPathOrderBy(relDef.to, targetMeta, spec.by.field, {
+                path: spec.by.path,
+            });
+            params.push(this.jsonPathParam(spec.by.path));
+            const extract = this.dialect.buildJsonPathExtract(`${alias}.${this.q(col)}`, this.p(params.length));
+            byExpr = spec.by.type === 'numeric' ? this.castJsonNumeric(extract) : extract;
+        }
+        // Correlation to the parent row, then the target's global filter (a
+        // soft-deleted / other-tenant row must never be picked: matches the
+        // `with` subquery and to-one relation-orderBy semantics), then pick.where.
+        let where = this.dialect.buildCorrelation(alias, relDef.foreignKey, this.q(parentRef), relDef.referenceKey);
+        const gf = this.targetGlobalFilterAlias(relDef.to, alias, params);
+        if (gf)
+            where += ` AND ${gf}`;
+        if (spec.pick.where) {
+            const pickWhere = this.buildAliasWhere(relDef.to, targetMeta, alias, spec.pick.where, params);
+            if (pickWhere)
+                where += ` AND ${pickWhere}`;
+        }
+        // pick.orderBy: same surface as a relation `with` orderBy on the target
+        // (plain columns, OrderBySpec nulls, JSON-path specs); a nested pick in
+        // here routes back through buildRelationOrderBy with ctx set and throws
+        // the top-level-only E003.
+        const orderClause = this.buildRelationOrderClause(relDef.to, targetMeta, alias, Object.entries(spec.pick.orderBy), params);
+        const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+        const limitOne = this.buildPagination('1', undefined, true);
+        // Parents with ZERO surviving related rows make the correlated subquery
+        // yield NULL. Without a nulls clause, Postgres DESC defaults to NULLS
+        // FIRST — every childless parent would top a "highest first" sort. Default
+        // to NULLS LAST in BOTH directions (deterministic across engines: SQLite's
+        // NULL-is-smallest default diverges from Postgres) unless the caller set
+        // `nulls` explicitly; the grammar gate matches nullsSuffix (PG + SQLite).
+        const nullsSql = spec.nulls
+            ? this.nullsSuffix(spec.nulls)
+            : this.dialect.name === 'postgresql' || this.dialect.name === 'sqlite'
+                ? ' NULLS LAST'
+                : '';
+        return `(SELECT ${byExpr} FROM ${this.q(relDef.to)} ${alias} WHERE ${where}${orderClause}${limitOne}) ${dir}${nullsSql}`;
+    }
+    /**
+     * 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.
+     */
+    collectRelationPickOrderParams(relName, relDef, spec, params) {
+        this.validatePickOrderBy(relName, relDef, spec, false);
+        const targetMeta = this.schema.tables[relDef.to];
+        if (!targetMeta)
+            throw new RelationError(`[turbine] Unknown relation target "${relDef.to}"`);
+        if (typeof spec.by === 'string') {
+            this.resolveOrderByColumn(relDef.to, targetMeta, spec.by);
+        }
+        else {
+            this.validateJsonPathOrderBy(relDef.to, targetMeta, spec.by.field, { path: spec.by.path });
+            params.push(this.jsonPathParam(spec.by.path));
+        }
+        this.collectTargetGlobalFilterAlias(relDef.to, params);
+        if (spec.pick.where) {
+            this.collectAliasWhereParams(relDef.to, targetMeta, spec.pick.where, params);
+        }
+        this.collectRelationOrderParams(relDef.to, targetMeta, Object.entries(spec.pick.orderBy), params);
+    }
     /**
      * Compile the ORDER BY terms of a relation `with` clause against the
      * relation's table alias. One unified path for every relation shape
@@ -4115,10 +4452,15 @@ export class QueryInterface {
             }
             if (isJsonPathOrderBy(dirValue)) {
                 this.validateJsonPathOrderBy(targetTable, targetMeta, key, dirValue);
-                params.push(dirValue.path.map(String));
+                params.push(this.jsonPathParam(dirValue.path));
                 continue;
             }
             if (this.isRelationOrderByValue(dirValue)) {
+                // Pick-row ordering is top-level-only: the build path throws the same
+                // E003 (buildRelationOrderBy with ctx set), so the mirror must too.
+                if (isRelationPickOrderBy(dirValue)) {
+                    throw this.pickOrderNestedError(key);
+                }
                 const relDef = targetMeta.relations[key];
                 if (relDef && (relDef.type === 'hasMany' || relDef.type === 'manyToMany')) {
                     this.collectRelationCountParams(relDef, params);
@@ -5077,6 +5419,16 @@ export class QueryInterface {
      * 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.
+     */
+    isJsonColumnType(colType) {
+        const t = colType.toLowerCase();
+        return t === 'json' || t === 'jsonb';
+    }
     getColumnPgType(column) {
         return this.columnPgTypeMap.get(column) ?? 'text';
     }
@@ -5146,7 +5498,8 @@ export class QueryInterface {
         let pathParamIdx = null;
         const pathExtract = () => {
             if (pathParamIdx === null) {
-                params.push(filter.path);
+                // Only reached when a path-requiring clause validated filter.path.
+                params.push(this.jsonPathParam(filter.path, filter.path));
                 pathParamIdx = params.length;
             }
             return this.dialect.buildJsonPathExtract(column, this.p(pathParamIdx));
@@ -5182,6 +5535,24 @@ export class QueryInterface {
         }
         return clauses;
     }
+    /**
+     * 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.
+     */
+    jsonPathParam(path, nativeForm) {
+        if (this.dialect.jsonPathSupport === 'native')
+            return nativeForm ?? path.map(String);
+        return `$${path
+            .map((seg) => typeof seg === 'number' || /^\d+$/.test(String(seg)) ? `[${seg}]` : `."${String(seg).replace(/"/g, '\\"')}"`)
+            .join('')}`;
+    }
     /**
      * Cast an extracted JSON path text value to a numeric type for range
      * comparison. PostgreSQL uses `(expr)::numeric` (exact — the right way to