turbine-orm 0.32.2 → 0.33.0

package/dist/cjs/dialect.js

@@ -58,6 +58,7 @@ exports.postgresDialect = {
     supportsListenNotify: true,
     supportsRLS: true,
     supportsAdvisoryLock: true,
+    supportsLateralJoin: true,
     paramPlaceholder(index) {
         return `$${index}`;
     },

package/dist/cjs/mssql.js

@@ -478,6 +478,9 @@ exports.mssqlDialect = {
     supportsVector: false,
     supportsListenNotify: false,
     supportsRLS: false,
+    // SQL Server has OUTER APPLY, not FROM-clause LATERAL: the lateral pick plan
+    // is Postgres-only (out of scope here).
+    supportsLateralJoin: false,
     // sp_getapplock / sp_releaseapplock exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
     // FOR JSON over zero rows is NULL → coalesced in the relation override.

package/dist/cjs/mysql.js

@@ -379,6 +379,9 @@ exports.mysqlDialect = {
     supportsVector: false,
     supportsListenNotify: false,
     supportsRLS: false,
+    // MySQL 8.0.14+ supports LATERAL, but the opt-in lateral pick plan stays
+    // Postgres-only in this release (flipping it on is a one-line change + tests).
+    supportsLateralJoin: false,
     // GET_LOCK / RELEASE_LOCK exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
     // JSON_ARRAYAGG has no inline ORDER BY argument → force the inner-subquery

package/dist/cjs/powdb.js

@@ -142,6 +142,9 @@ exports.powdbDialect = {
     supportsRLS: false,
     supportsAdvisoryLock: false,
     supportsILike: false,
+    // PowQL has no LATERAL construct; PowqlInterface refuses pick ordering
+    // earlier, this override keeps the flag truthful if a future path consults it.
+    supportsLateralJoin: false,
     beginStatement: () => 'begin',
     commitStatement: () => 'commit',
     rollbackStatement: () => 'rollback',

package/dist/cjs/query/builder.js

@@ -995,14 +995,22 @@ class QueryInterface {
             else {
                 selectClause = `${qt}.*`;
             }
-            let sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${freshWhereSql}`;
+            // Piece-then-assemble. The join-sink between FROM and WHERE carries any
+            // `plan: 'lateral'` pick joins; it is populated during the ORDER BY build
+            // below and spliced in at final assembly. Empty for every other query
+            // shape → the assembled SQL is byte-identical to the incremental-append
+            // form for the default plan (asserted by the byte-equality snapshot test).
+            const lateralJoins = [];
+            // WHERE + cursor conditions accumulate into `tail`, pushing params in
+            // where → cursor order (the collect path mirrors this exactly).
+            let tail = freshWhereSql;
             if (args?.cursor) {
                 // Sorted (canonical) order — MUST match cursorFp and the cache-hit collect below.
                 const cursorEntries = (0, filters_js_1.sortedEntries)(args.cursor).filter(([, v]) => v !== undefined);
                 if (cursorEntries.length > 0) {
                     const cursorConditions = cursorEntries.map(([k, v]) => {
                         const col = this.toSqlColumn(k);
-                        // orderBy values can be the { sort, nulls } spec form — normalize
+                        // orderBy values can be the { sort, nulls } spec form: normalize
                         // before comparing, or a desc spec would seek the ascending side.
                         const dir = args.orderBy?.[k];
                         const desc = (0, filters_js_1.isOrderBySpec)(dir) ? dir.sort === 'desc' : dir === 'desc';
@@ -1010,33 +1018,38 @@ class QueryInterface {
                         freshParams.push(v);
                         return `${qt}.${col} ${op} ${this.p(freshParams.length)}`;
                     });
-                    if (freshWhereSql) {
-                        sql += ` AND ${cursorConditions.join(' AND ')}`;
-                    }
-                    else {
-                        sql += ` WHERE ${cursorConditions.join(' AND ')}`;
-                    }
+                    tail += freshWhereSql ? ` AND ${cursorConditions.join(' AND ')}` : ` WHERE ${cursorConditions.join(' AND ')}`;
                 }
             }
-            if (args?.orderBy) {
-                if (distinctPrefix) {
-                    // Postgres requires DISTINCT ON expressions to lead the ORDER BY.
-                    // Prisma semantics ("first row per combination, result in the user's
-                    // order") need two levels: inner DISTINCT ON ordered by the distinct
-                    // columns then the user's order (picks the right representative row),
-                    // outer re-ordered by the user's order alone.
-                    if (Object.values(args.orderBy).some((d) => (0, filters_js_1.isVectorOrderBy)(d))) {
-                        throw new errors_js_1.ValidationError('[turbine] `distinct` cannot be combined with vector distance ordering.');
-                    }
-                    const userOrder = this.buildOrderBy(args.orderBy, freshParams);
-                    sql += ` ORDER BY ${distinctCols.map((c) => `${c} ASC`).join(', ')}, ${userOrder}`;
-                    sql = `SELECT * FROM (${sql}) AS ${this.q(`${this.table}_distinct`)} ORDER BY ${userOrder}`;
-                }
-                else {
-                    // Pass freshParams so vector KNN ordering binds its `$n::vector` query
-                    // vector at the correct position (after cursor params, before LIMIT).
-                    sql += ` ORDER BY ${this.buildOrderBy(args.orderBy, freshParams)}`;
+            // ORDER BY is built AFTER the cursor pushes (param order
+            // where → with → cursor → orderBy → limit → offset) and BEFORE final
+            // assembly (so the lateral sink is filled before the FROM clause is
+            // written). distinct + relation orderBy is refused up front, so a lateral
+            // pick can never reach the distinct branch (lateralJoins stays empty).
+            let sql;
+            if (args?.orderBy && distinctPrefix) {
+                // Postgres requires DISTINCT ON expressions to lead the ORDER BY. Prisma
+                // semantics ("first row per combination, result in the user's order")
+                // need two levels: inner DISTINCT ON ordered by the distinct columns then
+                // the user's order (picks the right representative row), outer re-ordered
+                // by the user's order alone.
+                if (Object.values(args.orderBy).some((d) => (0, filters_js_1.isVectorOrderBy)(d))) {
+                    throw new errors_js_1.ValidationError('[turbine] `distinct` cannot be combined with vector distance ordering.');
                 }
+                const userOrder = this.buildOrderBy(args.orderBy, freshParams);
+                const inner = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${tail} ORDER BY ${distinctCols
+                    .map((c) => `${c} ASC`)
+                    .join(', ')}, ${userOrder}`;
+                sql = `SELECT * FROM (${inner}) AS ${this.q(`${this.table}_distinct`)} ORDER BY ${userOrder}`;
+            }
+            else {
+                // Pass freshParams so vector KNN ordering binds its `$n::vector` query
+                // vector at the correct position (after cursor params, before LIMIT), and
+                // lateralJoins so a lateral pick splices its join into the FROM clause.
+                const orderBySql = args?.orderBy
+                    ? ` ORDER BY ${this.buildOrderBy(args.orderBy, freshParams, lateralJoins)}`
+                    : '';
+                sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${lateralJoins.join('')}${tail}${orderBySql}`;
             }
             // Pagination — push params in the same order the collect path mirrors
             // (limit before offset); the SQL TEXT shape is dialect-owned via
@@ -4354,7 +4367,13 @@ class QueryInterface {
             const pickWhere = d.pick?.where
                 ? `;pw=${this.fingerprintAliasWhere(d.pick.where, targetTable)}`
                 : '';
-            return `pick(${by},${d.direction ?? 'asc'},${d.nulls ?? ''};po=${pickOrder}${pickWhere})`;
+            // Plan discriminator: the lateral plan emits DIFFERENT SQL (a FROM-clause
+            // join + a qualified order term) so a warm cache must never serve one
+            // plan's SQL for the other. Emitted ONLY for `'lateral'`: absent means
+            // the default subquery plan, keeping every pre-existing cache key
+            // byte-identical (no cold-cache churn on upgrade).
+            const planTag = d.plan === 'lateral' ? ';plan=lat' : '';
+            return `pick(${by},${d.direction ?? 'asc'},${d.nulls ?? ''};po=${pickOrder}${pickWhere}${planTag})`;
         }
         if ((0, filters_js_1.isOrderBySpec)(d))
             return `spec(${d.sort},${d.nulls ?? ''})`;
@@ -4371,7 +4390,7 @@ class QueryInterface {
         }
         return String(d);
     }
-    buildOrderBy(orderBy, params) {
+    buildOrderBy(orderBy, params, lateralSink) {
         // Dev-only: validate that orderBy fields exist in the table schema. Relation
         // orderBy keys (object values that are neither a vector nor an OrderBySpec)
         // are validated in the relation branch below, so skip them here.
@@ -4414,7 +4433,7 @@ class QueryInterface {
             // keyed by a relation name (`{ posts: { _count: 'desc' } }` / `{ author:
             // { name: 'asc' } }`).
             if (this.isRelationOrderByValue(value)) {
-                return this.buildRelationOrderBy(key, value, `ord${relOrdCounter++}`, params);
+                return this.buildRelationOrderBy(key, value, `ord${relOrdCounter++}`, params, undefined, lateralSink);
             }
             // Scalar column ordering — a plain direction or an OrderBySpec (nulls).
             if (meta && !(key in meta.columnMap)) {
@@ -4523,7 +4542,7 @@ class QueryInterface {
      * 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, ctx) {
+    buildRelationOrderBy(relName, value, alias, params, ctx, lateralSink) {
         const ownerMeta = ctx?.meta ?? this.tableMeta;
         const ownerTable = ctx?.table ?? this.table;
         const parentRef = ctx?.parentRef ?? this.table;
@@ -4539,7 +4558,7 @@ class QueryInterface {
         // scope errors, shared with the cache-hit collect mirror.
         if ((0, filters_js_1.isRelationPickOrderBy)(value)) {
             this.validatePickOrderBy(relName, relDef, value, ctx !== undefined);
-            return this.buildRelationPickOrderBy(relName, relDef, value, alias, parentRef, params);
+            return this.buildRelationPickOrderBy(relName, relDef, value, alias, parentRef, params, lateralSink);
         }
         // To-many: only `_count` is meaningful → correlated COUNT(*) subquery.
         if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
@@ -4631,6 +4650,25 @@ class QueryInterface {
             throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering on relation "${relName}" requires \`by\`: a target column name ` +
                 "or a JSON-path spec ({ field: 'data', path: ['title'] }).");
         }
+        // Physical plan gate. A typo like `plan: 'latreal'` must never silently run
+        // the subquery plan (a silent plan change wearing a validation gap). Shared
+        // by build and cache-hit collect so a warmed cache throws identically.
+        if (spec.plan !== undefined && spec.plan !== 'subquery' && spec.plan !== 'lateral') {
+            throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering on relation "${relName}" has an invalid \`plan\`: ` +
+                `${JSON.stringify(spec.plan)}. Use 'subquery' (default) or 'lateral'.`);
+        }
+        if (spec.plan === 'lateral') {
+            if (!this.dialect.supportsLateralJoin) {
+                throw new errors_js_1.UnsupportedFeatureError("pick-row ordering with plan: 'lateral'", this.dialect.name, "LATERAL joins are only available on PostgreSQL. Omit `plan` (or use 'subquery').");
+            }
+            // The lateral exposes one reserved output column, `__turbine_pick`. A
+            // parent column with that exact name would make the unqualified WHERE
+            // reference ambiguous once the join is in scope; refuse it explicitly.
+            if (this.tableMeta.allColumns.includes('__turbine_pick')) {
+                throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering with plan: 'lateral' cannot be used: table "${this.tableMeta.name}" ` +
+                    'has a column named "__turbine_pick", which the lateral join output reserves.');
+            }
+        }
     }
     /**
      * Compile a {@link RelationPickOrderBy} term: a correlated scalar subquery
@@ -4649,36 +4687,83 @@ class QueryInterface {
      * {@link collectRelationPickOrderParams}): `by` JSON path (if any) →
      * target global filter → `pick.where` → `pick.orderBy` JSON paths.
      */
-    buildRelationPickOrderBy(relName, relDef, spec, alias, parentRef, params) {
+    buildRelationPickOrderBy(relName, relDef, spec, alias, parentRef, params, lateralSink) {
         if (!params) {
             throw new errors_js_1.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 errors_js_1.RelationError(`[turbine] Unknown relation target "${relDef.to}"`);
+        const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+        const limitOne = this.buildPagination('1', undefined, true);
+        // Parents with ZERO surviving related rows have no row to pick: the
+        // correlated subquery yields NULL, and the LEFT JOIN LATERAL null-extends
+        // its single row identically. Without a nulls clause, Postgres DESC
+        // defaults to NULLS FIRST (every childless parent tops 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.
+        const nullsSql = spec.nulls
+            ? this.nullsSuffix(spec.nulls)
+            : this.dialect.name === 'postgresql' || this.dialect.name === 'sqlite'
+                ? ' NULLS LAST'
+                : '';
+        // Lateral plan: splice a `LEFT JOIN LATERAL (... LIMIT 1) ON true` into the
+        // FROM clause (via the sink) and order by its single reserved output column.
+        // Param push order is IDENTICAL to the subquery plan (compilePickPieces is
+        // shared), so the cache-hit collect mirror needs no changes. Scope +
+        // capability were already enforced by validatePickOrderBy (shared with the
+        // collect path); the missing-sink guard catches a non-findMany build
+        // context and hard-fails rather than silently emitting a subquery.
+        if (spec.plan === 'lateral') {
+            if (!lateralSink) {
+                throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering with plan: 'lateral' on relation "${relName}" is only supported ` +
+                    'in a top-level findMany orderBy.');
+            }
+            const childAlias = `${alias}i`;
+            const { byExpr, where, orderClause } = this.compilePickPieces(relDef, targetMeta, spec, childAlias, parentRef, params);
+            lateralSink.push(` LEFT JOIN LATERAL (SELECT ${byExpr} AS ${this.q('__turbine_pick')} FROM ${this.q(relDef.to)} ${childAlias}` +
+                ` WHERE ${where}${orderClause}${limitOne}) ${alias} ON true`);
+            return `${alias}.${this.q('__turbine_pick')} ${dir}${nullsSql}`;
+        }
+        // Subquery plan (default): a correlated scalar subquery in ORDER BY.
+        const { byExpr, where, orderClause } = this.compilePickPieces(relDef, targetMeta, spec, alias, parentRef, params);
+        return `(SELECT ${byExpr} FROM ${this.q(relDef.to)} ${alias} WHERE ${where}${orderClause}${limitOne}) ${dir}${nullsSql}`;
+    }
+    /**
+     * Compile the shared inner pieces of a pick-row ordering against `childAlias`
+     * (the table alias the related row is read from): the `by` value expression,
+     * the correlation + target global filter + `pick.where` predicate, and the
+     * `pick.orderBy` clause. Factored out of {@link buildRelationPickOrderBy} so
+     * the subquery and lateral plans build IDENTICAL pieces in the SAME param
+     * push order (`by` JSON path → target global filter → `pick.where` →
+     * `pick.orderBy` JSON paths), which is why the collect mirror
+     * ({@link collectRelationPickOrderParams}) is plan-agnostic.
+     */
+    compilePickPieces(relDef, targetMeta, spec, childAlias, parentRef, params) {
         // 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)}`;
+            byExpr = `${childAlias}.${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));
+            const extract = this.dialect.buildJsonPathExtract(`${childAlias}.${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);
+        let where = this.dialect.buildCorrelation(childAlias, relDef.foreignKey, this.q(parentRef), relDef.referenceKey);
+        const gf = this.targetGlobalFilterAlias(relDef.to, childAlias, params);
         if (gf)
             where += ` AND ${gf}`;
         if (spec.pick.where) {
-            const pickWhere = this.buildAliasWhere(relDef.to, targetMeta, alias, spec.pick.where, params);
+            const pickWhere = this.buildAliasWhere(relDef.to, targetMeta, childAlias, spec.pick.where, params);
             if (pickWhere)
                 where += ` AND ${pickWhere}`;
         }
@@ -4686,21 +4771,8 @@ class QueryInterface {
         // (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}`;
+        const orderClause = this.buildRelationOrderClause(relDef.to, targetMeta, childAlias, Object.entries(spec.pick.orderBy), params);
+        return { byExpr, where, orderClause };
     }
     /**
      * Param-collect mirror of {@link buildRelationPickOrderBy}: re-runs the same

package/dist/cjs/query/filters.js

@@ -319,9 +319,9 @@ function isJsonPathOrderBy(value) {
 }
 /**
  * Check if an orderBy value is a pick-row relation ordering:
- * `{ pick: { orderBy, ... }, by, direction?, nulls? }`. The full shape is
- * required — `pick` must be an object carrying `orderBy`, `by` must be
- * present, and no keys outside `{ pick, by, direction, nulls }` — so a to-one
+ * `{ pick: { orderBy, ... }, by, direction?, nulls?, plan? }`. The full shape
+ * is required (`pick` must be an object carrying `orderBy`, `by` must be
+ * present, and no keys outside `{ pick, by, direction, nulls, plan }`), so a to-one
  * relation whose target has real columns literally named `pick` and `by`
  * (whose values are direction strings or `{ sort, nulls }` specs, never an
  * object with `orderBy`) still falls through to column ordering. `distance`
@@ -339,7 +339,7 @@ function isRelationPickOrderBy(value) {
     if (typeof v.pick !== 'object' || v.pick === null || Array.isArray(v.pick) || !('orderBy' in v.pick))
         return false;
     for (const key of Object.keys(v)) {
-        if (key !== 'pick' && key !== 'by' && key !== 'direction' && key !== 'nulls')
+        if (key !== 'pick' && key !== 'by' && key !== 'direction' && key !== 'nulls' && key !== 'plan')
             return false;
     }
     return true;

package/dist/cjs/sqlite.js

@@ -378,6 +378,8 @@ exports.sqliteDialect = {
     supportsListenNotify: false,
     supportsRLS: false,
     supportsAdvisoryLock: false,
+    // No FROM-clause LATERAL: the opt-in lateral pick plan is Postgres-only.
+    supportsLateralJoin: false,
     // json_group_array / json_object have no inline ORDER BY argument, so every
     // ordered to-many relation is forced through the inner-subquery rewrite.
     aggSupportsInlineOrderBy: false,

package/dist/dialect.d.ts

@@ -295,6 +295,13 @@ export interface Dialect {
     readonly supportsRLS: boolean;
     /** Whether this dialect/engine supports advisory-lock-style migration locking. */
     readonly supportsAdvisoryLock: boolean;
+    /**
+     * Whether this dialect supports `LEFT JOIN LATERAL (...) ON true` in the FROM
+     * clause. Gates the opt-in `plan: 'lateral'` pick-row ordering. Optional:
+     * absent is treated as `false`, so only dialects that set it true admit the
+     * lateral plan (else E017). PostgreSQL only in this release.
+     */
+    readonly supportsLateralJoin?: boolean;
     /** Build a dialect-specific RETURNING clause. Return an empty string when unsupported. */
     buildReturningClause(selection?: string): string;
     /** Build a single-row INSERT statement. Inputs are SQL-ready quoted fragments. */

package/dist/dialect.js

@@ -22,6 +22,7 @@ export const postgresDialect = {
     supportsListenNotify: true,
     supportsRLS: true,
     supportsAdvisoryLock: true,
+    supportsLateralJoin: true,
     paramPlaceholder(index) {
         return `$${index}`;
     },

package/dist/mssql.js

@@ -467,6 +467,9 @@ export const mssqlDialect = {
     supportsVector: false,
     supportsListenNotify: false,
     supportsRLS: false,
+    // SQL Server has OUTER APPLY, not FROM-clause LATERAL: the lateral pick plan
+    // is Postgres-only (out of scope here).
+    supportsLateralJoin: false,
     // sp_getapplock / sp_releaseapplock exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
     // FOR JSON over zero rows is NULL → coalesced in the relation override.

package/dist/mysql.js

@@ -368,6 +368,9 @@ export const mysqlDialect = {
     supportsVector: false,
     supportsListenNotify: false,
     supportsRLS: false,
+    // MySQL 8.0.14+ supports LATERAL, but the opt-in lateral pick plan stays
+    // Postgres-only in this release (flipping it on is a one-line change + tests).
+    supportsLateralJoin: false,
     // GET_LOCK / RELEASE_LOCK exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
     // JSON_ARRAYAGG has no inline ORDER BY argument → force the inner-subquery

package/dist/powdb.js

@@ -92,6 +92,9 @@ export const powdbDialect = {
     supportsRLS: false,
     supportsAdvisoryLock: false,
     supportsILike: false,
+    // PowQL has no LATERAL construct; PowqlInterface refuses pick ordering
+    // earlier, this override keeps the flag truthful if a future path consults it.
+    supportsLateralJoin: false,
     beginStatement: () => 'begin',
     commitStatement: () => 'commit',
     rollbackStatement: () => 'rollback',

package/dist/query/builder.d.ts

@@ -829,6 +829,17 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * target global filter → `pick.where` → `pick.orderBy` JSON paths.
      */
     private buildRelationPickOrderBy;
+    /**
+     * Compile the shared inner pieces of a pick-row ordering against `childAlias`
+     * (the table alias the related row is read from): the `by` value expression,
+     * the correlation + target global filter + `pick.where` predicate, and the
+     * `pick.orderBy` clause. Factored out of {@link buildRelationPickOrderBy} so
+     * the subquery and lateral plans build IDENTICAL pieces in the SAME param
+     * push order (`by` JSON path → target global filter → `pick.where` →
+     * `pick.orderBy` JSON paths), which is why the collect mirror
+     * ({@link collectRelationPickOrderParams}) is plan-agnostic.
+     */
+    private compilePickPieces;
     /**
      * Param-collect mirror of {@link buildRelationPickOrderBy}: re-runs the same
      * validation (a warmed cache can never skip it), then pushes in the same

package/dist/query/builder.js

@@ -959,14 +959,22 @@ export class QueryInterface {
             else {
                 selectClause = `${qt}.*`;
             }
-            let sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${freshWhereSql}`;
+            // Piece-then-assemble. The join-sink between FROM and WHERE carries any
+            // `plan: 'lateral'` pick joins; it is populated during the ORDER BY build
+            // below and spliced in at final assembly. Empty for every other query
+            // shape → the assembled SQL is byte-identical to the incremental-append
+            // form for the default plan (asserted by the byte-equality snapshot test).
+            const lateralJoins = [];
+            // WHERE + cursor conditions accumulate into `tail`, pushing params in
+            // where → cursor order (the collect path mirrors this exactly).
+            let tail = freshWhereSql;
             if (args?.cursor) {
                 // Sorted (canonical) order — MUST match cursorFp and the cache-hit collect below.
                 const cursorEntries = sortedEntries(args.cursor).filter(([, v]) => v !== undefined);
                 if (cursorEntries.length > 0) {
                     const cursorConditions = cursorEntries.map(([k, v]) => {
                         const col = this.toSqlColumn(k);
-                        // orderBy values can be the { sort, nulls } spec form — normalize
+                        // orderBy values can be the { sort, nulls } spec form: normalize
                         // before comparing, or a desc spec would seek the ascending side.
                         const dir = args.orderBy?.[k];
                         const desc = isOrderBySpec(dir) ? dir.sort === 'desc' : dir === 'desc';
@@ -974,33 +982,38 @@ export class QueryInterface {
                         freshParams.push(v);
                         return `${qt}.${col} ${op} ${this.p(freshParams.length)}`;
                     });
-                    if (freshWhereSql) {
-                        sql += ` AND ${cursorConditions.join(' AND ')}`;
-                    }
-                    else {
-                        sql += ` WHERE ${cursorConditions.join(' AND ')}`;
-                    }
+                    tail += freshWhereSql ? ` AND ${cursorConditions.join(' AND ')}` : ` WHERE ${cursorConditions.join(' AND ')}`;
                 }
             }
-            if (args?.orderBy) {
-                if (distinctPrefix) {
-                    // Postgres requires DISTINCT ON expressions to lead the ORDER BY.
-                    // Prisma semantics ("first row per combination, result in the user's
-                    // order") need two levels: inner DISTINCT ON ordered by the distinct
-                    // columns then the user's order (picks the right representative row),
-                    // outer re-ordered by the user's order alone.
-                    if (Object.values(args.orderBy).some((d) => isVectorOrderBy(d))) {
-                        throw new ValidationError('[turbine] `distinct` cannot be combined with vector distance ordering.');
-                    }
-                    const userOrder = this.buildOrderBy(args.orderBy, freshParams);
-                    sql += ` ORDER BY ${distinctCols.map((c) => `${c} ASC`).join(', ')}, ${userOrder}`;
-                    sql = `SELECT * FROM (${sql}) AS ${this.q(`${this.table}_distinct`)} ORDER BY ${userOrder}`;
-                }
-                else {
-                    // Pass freshParams so vector KNN ordering binds its `$n::vector` query
-                    // vector at the correct position (after cursor params, before LIMIT).
-                    sql += ` ORDER BY ${this.buildOrderBy(args.orderBy, freshParams)}`;
+            // ORDER BY is built AFTER the cursor pushes (param order
+            // where → with → cursor → orderBy → limit → offset) and BEFORE final
+            // assembly (so the lateral sink is filled before the FROM clause is
+            // written). distinct + relation orderBy is refused up front, so a lateral
+            // pick can never reach the distinct branch (lateralJoins stays empty).
+            let sql;
+            if (args?.orderBy && distinctPrefix) {
+                // Postgres requires DISTINCT ON expressions to lead the ORDER BY. Prisma
+                // semantics ("first row per combination, result in the user's order")
+                // need two levels: inner DISTINCT ON ordered by the distinct columns then
+                // the user's order (picks the right representative row), outer re-ordered
+                // by the user's order alone.
+                if (Object.values(args.orderBy).some((d) => isVectorOrderBy(d))) {
+                    throw new ValidationError('[turbine] `distinct` cannot be combined with vector distance ordering.');
                 }
+                const userOrder = this.buildOrderBy(args.orderBy, freshParams);
+                const inner = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${tail} ORDER BY ${distinctCols
+                    .map((c) => `${c} ASC`)
+                    .join(', ')}, ${userOrder}`;
+                sql = `SELECT * FROM (${inner}) AS ${this.q(`${this.table}_distinct`)} ORDER BY ${userOrder}`;
+            }
+            else {
+                // Pass freshParams so vector KNN ordering binds its `$n::vector` query
+                // vector at the correct position (after cursor params, before LIMIT), and
+                // lateralJoins so a lateral pick splices its join into the FROM clause.
+                const orderBySql = args?.orderBy
+                    ? ` ORDER BY ${this.buildOrderBy(args.orderBy, freshParams, lateralJoins)}`
+                    : '';
+                sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${lateralJoins.join('')}${tail}${orderBySql}`;
             }
             // Pagination — push params in the same order the collect path mirrors
             // (limit before offset); the SQL TEXT shape is dialect-owned via
@@ -4318,7 +4331,13 @@ export class QueryInterface {
             const pickWhere = d.pick?.where
                 ? `;pw=${this.fingerprintAliasWhere(d.pick.where, targetTable)}`
                 : '';
-            return `pick(${by},${d.direction ?? 'asc'},${d.nulls ?? ''};po=${pickOrder}${pickWhere})`;
+            // Plan discriminator: the lateral plan emits DIFFERENT SQL (a FROM-clause
+            // join + a qualified order term) so a warm cache must never serve one
+            // plan's SQL for the other. Emitted ONLY for `'lateral'`: absent means
+            // the default subquery plan, keeping every pre-existing cache key
+            // byte-identical (no cold-cache churn on upgrade).
+            const planTag = d.plan === 'lateral' ? ';plan=lat' : '';
+            return `pick(${by},${d.direction ?? 'asc'},${d.nulls ?? ''};po=${pickOrder}${pickWhere}${planTag})`;
         }
         if (isOrderBySpec(d))
             return `spec(${d.sort},${d.nulls ?? ''})`;
@@ -4335,7 +4354,7 @@ export class QueryInterface {
         }
         return String(d);
     }
-    buildOrderBy(orderBy, params) {
+    buildOrderBy(orderBy, params, lateralSink) {
         // Dev-only: validate that orderBy fields exist in the table schema. Relation
         // orderBy keys (object values that are neither a vector nor an OrderBySpec)
         // are validated in the relation branch below, so skip them here.
@@ -4378,7 +4397,7 @@ export class QueryInterface {
             // keyed by a relation name (`{ posts: { _count: 'desc' } }` / `{ author:
             // { name: 'asc' } }`).
             if (this.isRelationOrderByValue(value)) {
-                return this.buildRelationOrderBy(key, value, `ord${relOrdCounter++}`, params);
+                return this.buildRelationOrderBy(key, value, `ord${relOrdCounter++}`, params, undefined, lateralSink);
             }
             // Scalar column ordering — a plain direction or an OrderBySpec (nulls).
             if (meta && !(key in meta.columnMap)) {
@@ -4487,7 +4506,7 @@ export class QueryInterface {
      * 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, ctx) {
+    buildRelationOrderBy(relName, value, alias, params, ctx, lateralSink) {
         const ownerMeta = ctx?.meta ?? this.tableMeta;
         const ownerTable = ctx?.table ?? this.table;
         const parentRef = ctx?.parentRef ?? this.table;
@@ -4503,7 +4522,7 @@ export class QueryInterface {
         // 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);
+            return this.buildRelationPickOrderBy(relName, relDef, value, alias, parentRef, params, lateralSink);
         }
         // To-many: only `_count` is meaningful → correlated COUNT(*) subquery.
         if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
@@ -4595,6 +4614,25 @@ export class QueryInterface {
             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'] }).");
         }
+        // Physical plan gate. A typo like `plan: 'latreal'` must never silently run
+        // the subquery plan (a silent plan change wearing a validation gap). Shared
+        // by build and cache-hit collect so a warmed cache throws identically.
+        if (spec.plan !== undefined && spec.plan !== 'subquery' && spec.plan !== 'lateral') {
+            throw new ValidationError(`[turbine] Pick-row ordering on relation "${relName}" has an invalid \`plan\`: ` +
+                `${JSON.stringify(spec.plan)}. Use 'subquery' (default) or 'lateral'.`);
+        }
+        if (spec.plan === 'lateral') {
+            if (!this.dialect.supportsLateralJoin) {
+                throw new UnsupportedFeatureError("pick-row ordering with plan: 'lateral'", this.dialect.name, "LATERAL joins are only available on PostgreSQL. Omit `plan` (or use 'subquery').");
+            }
+            // The lateral exposes one reserved output column, `__turbine_pick`. A
+            // parent column with that exact name would make the unqualified WHERE
+            // reference ambiguous once the join is in scope; refuse it explicitly.
+            if (this.tableMeta.allColumns.includes('__turbine_pick')) {
+                throw new ValidationError(`[turbine] Pick-row ordering with plan: 'lateral' cannot be used: table "${this.tableMeta.name}" ` +
+                    'has a column named "__turbine_pick", which the lateral join output reserves.');
+            }
+        }
     }
     /**
      * Compile a {@link RelationPickOrderBy} term: a correlated scalar subquery
@@ -4613,36 +4651,83 @@ export class QueryInterface {
      * {@link collectRelationPickOrderParams}): `by` JSON path (if any) →
      * target global filter → `pick.where` → `pick.orderBy` JSON paths.
      */
-    buildRelationPickOrderBy(relName, relDef, spec, alias, parentRef, params) {
+    buildRelationPickOrderBy(relName, relDef, spec, alias, parentRef, params, lateralSink) {
         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}"`);
+        const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+        const limitOne = this.buildPagination('1', undefined, true);
+        // Parents with ZERO surviving related rows have no row to pick: the
+        // correlated subquery yields NULL, and the LEFT JOIN LATERAL null-extends
+        // its single row identically. Without a nulls clause, Postgres DESC
+        // defaults to NULLS FIRST (every childless parent tops 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.
+        const nullsSql = spec.nulls
+            ? this.nullsSuffix(spec.nulls)
+            : this.dialect.name === 'postgresql' || this.dialect.name === 'sqlite'
+                ? ' NULLS LAST'
+                : '';
+        // Lateral plan: splice a `LEFT JOIN LATERAL (... LIMIT 1) ON true` into the
+        // FROM clause (via the sink) and order by its single reserved output column.
+        // Param push order is IDENTICAL to the subquery plan (compilePickPieces is
+        // shared), so the cache-hit collect mirror needs no changes. Scope +
+        // capability were already enforced by validatePickOrderBy (shared with the
+        // collect path); the missing-sink guard catches a non-findMany build
+        // context and hard-fails rather than silently emitting a subquery.
+        if (spec.plan === 'lateral') {
+            if (!lateralSink) {
+                throw new ValidationError(`[turbine] Pick-row ordering with plan: 'lateral' on relation "${relName}" is only supported ` +
+                    'in a top-level findMany orderBy.');
+            }
+            const childAlias = `${alias}i`;
+            const { byExpr, where, orderClause } = this.compilePickPieces(relDef, targetMeta, spec, childAlias, parentRef, params);
+            lateralSink.push(` LEFT JOIN LATERAL (SELECT ${byExpr} AS ${this.q('__turbine_pick')} FROM ${this.q(relDef.to)} ${childAlias}` +
+                ` WHERE ${where}${orderClause}${limitOne}) ${alias} ON true`);
+            return `${alias}.${this.q('__turbine_pick')} ${dir}${nullsSql}`;
+        }
+        // Subquery plan (default): a correlated scalar subquery in ORDER BY.
+        const { byExpr, where, orderClause } = this.compilePickPieces(relDef, targetMeta, spec, alias, parentRef, params);
+        return `(SELECT ${byExpr} FROM ${this.q(relDef.to)} ${alias} WHERE ${where}${orderClause}${limitOne}) ${dir}${nullsSql}`;
+    }
+    /**
+     * Compile the shared inner pieces of a pick-row ordering against `childAlias`
+     * (the table alias the related row is read from): the `by` value expression,
+     * the correlation + target global filter + `pick.where` predicate, and the
+     * `pick.orderBy` clause. Factored out of {@link buildRelationPickOrderBy} so
+     * the subquery and lateral plans build IDENTICAL pieces in the SAME param
+     * push order (`by` JSON path → target global filter → `pick.where` →
+     * `pick.orderBy` JSON paths), which is why the collect mirror
+     * ({@link collectRelationPickOrderParams}) is plan-agnostic.
+     */
+    compilePickPieces(relDef, targetMeta, spec, childAlias, parentRef, params) {
         // 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)}`;
+            byExpr = `${childAlias}.${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));
+            const extract = this.dialect.buildJsonPathExtract(`${childAlias}.${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);
+        let where = this.dialect.buildCorrelation(childAlias, relDef.foreignKey, this.q(parentRef), relDef.referenceKey);
+        const gf = this.targetGlobalFilterAlias(relDef.to, childAlias, params);
         if (gf)
             where += ` AND ${gf}`;
         if (spec.pick.where) {
-            const pickWhere = this.buildAliasWhere(relDef.to, targetMeta, alias, spec.pick.where, params);
+            const pickWhere = this.buildAliasWhere(relDef.to, targetMeta, childAlias, spec.pick.where, params);
             if (pickWhere)
                 where += ` AND ${pickWhere}`;
         }
@@ -4650,21 +4735,8 @@ export class QueryInterface {
         // (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}`;
+        const orderClause = this.buildRelationOrderClause(relDef.to, targetMeta, childAlias, Object.entries(spec.pick.orderBy), params);
+        return { byExpr, where, orderClause };
     }
     /**
      * Param-collect mirror of {@link buildRelationPickOrderBy}: re-runs the same

package/dist/query/filters.d.ts

@@ -156,9 +156,9 @@ export declare function isOrderBySpec(value: unknown): value is OrderBySpec;
 export declare function isJsonPathOrderBy(value: unknown): value is JsonPathOrderBy;
 /**
  * Check if an orderBy value is a pick-row relation ordering:
- * `{ pick: { orderBy, ... }, by, direction?, nulls? }`. The full shape is
- * required — `pick` must be an object carrying `orderBy`, `by` must be
- * present, and no keys outside `{ pick, by, direction, nulls }` — so a to-one
+ * `{ pick: { orderBy, ... }, by, direction?, nulls?, plan? }`. The full shape
+ * is required (`pick` must be an object carrying `orderBy`, `by` must be
+ * present, and no keys outside `{ pick, by, direction, nulls, plan }`), so a to-one
  * relation whose target has real columns literally named `pick` and `by`
  * (whose values are direction strings or `{ sort, nulls }` specs, never an
  * object with `orderBy`) still falls through to column ordering. `distance`

package/dist/query/filters.js

@@ -296,9 +296,9 @@ export function isJsonPathOrderBy(value) {
 }
 /**
  * Check if an orderBy value is a pick-row relation ordering:
- * `{ pick: { orderBy, ... }, by, direction?, nulls? }`. The full shape is
- * required — `pick` must be an object carrying `orderBy`, `by` must be
- * present, and no keys outside `{ pick, by, direction, nulls }` — so a to-one
+ * `{ pick: { orderBy, ... }, by, direction?, nulls?, plan? }`. The full shape
+ * is required (`pick` must be an object carrying `orderBy`, `by` must be
+ * present, and no keys outside `{ pick, by, direction, nulls, plan }`), so a to-one
  * relation whose target has real columns literally named `pick` and `by`
  * (whose values are direction strings or `{ sort, nulls }` specs, never an
  * object with `orderBy`) still falls through to column ordering. `distance`
@@ -316,7 +316,7 @@ export function isRelationPickOrderBy(value) {
     if (typeof v.pick !== 'object' || v.pick === null || Array.isArray(v.pick) || !('orderBy' in v.pick))
         return false;
     for (const key of Object.keys(v)) {
-        if (key !== 'pick' && key !== 'by' && key !== 'direction' && key !== 'nulls')
+        if (key !== 'pick' && key !== 'by' && key !== 'direction' && key !== 'nulls' && key !== 'plan')
             return false;
     }
     return true;

package/dist/query/types.d.ts

@@ -979,6 +979,17 @@ export interface RelationPickOrderBy {
      * "highest first" sort). Set `nulls` explicitly to override.
      */
     nulls?: 'first' | 'last';
+    /**
+     * Physical plan for the pick. `'subquery'` (default) compiles a correlated
+     * scalar subquery in ORDER BY. `'lateral'` (PostgreSQL only, E017 elsewhere)
+     * compiles a `LEFT JOIN LATERAL (... LIMIT 1) ON true` and orders by the
+     * joined value. Identical results; the lateral form can be significantly
+     * faster on large parent sets where the ordering subquery dominates the plan.
+     * Never falls back silently: contexts that cannot take a lateral (non-Postgres
+     * engines, `distinct`, nested `with` orderBy, a parent column literally named
+     * `__turbine_pick`) throw.
+     */
+    plan?: 'subquery' | 'lateral';
 }
 /**
  * An orderBy clause maps each key to one of:

package/dist/sqlite.js

@@ -370,6 +370,8 @@ export const sqliteDialect = {
     supportsListenNotify: false,
     supportsRLS: false,
     supportsAdvisoryLock: false,
+    // No FROM-clause LATERAL: the opt-in lateral pick plan is Postgres-only.
+    supportsLateralJoin: false,
     // json_group_array / json_object have no inline ORDER BY argument, so every
     // ordered to-many relation is forced through the inner-subquery rewrite.
     aggSupportsInlineOrderBy: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.32.2",
+  "version": "0.33.0",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "exports": {