turbine-orm 0.91.0 → 0.92.0

package/dist/powdb.d.ts

@@ -21,7 +21,9 @@
  *     writable types (`str`/`int`/`float`/`bool`); `Date` → `int` epoch micros;
  *     `string` PKs hold UUID strings.
  *   - **No JSON aggregation / link navigation**, single-query nested `with` is
- *     impossible → it degrades to batched N+1 loaders (Phase B).
+ *     not available → on PowDB 0.18+ an eligible `with` compiles to nested
+ *     projections inside the parent statement; older engines and ineligible
+ *     relations use batched loaders.
  *   - **Single global write lock; no savepoints/isolation**, nested
  *     transactions / isolation / vector / LISTEN-NOTIFY / RLS throw.
  *     Independent concurrent `db.$transaction` calls do NOT throw: they queue
@@ -667,8 +669,10 @@ export { PowqlInterface } from './powql.js';
  */
 export interface TurbinePowdbOptions extends EngineClientConfig {
     /**
-     * Client-level default `with`-relation load strategy. On PowDB the default is
-     * the batched N+1 loaders; setting `'join'` opts INTO native PowQL server-side
+     * Client-level default `with`-relation load strategy. On PowDB 0.18+ the default
+     * compiles eligible relations to nested projections in one statement (older
+     * engines and ineligible relations use the batched loaders); `'batched'` forces
+     * the loaders, and setting `'join'` opts INTO native PowQL server-side
      * joins for eligible top-level relations (ineligible ones, e.g. a paged parent
      * or a nested `with`, fall back to the loaders per-relation and silently). A
      * per-query `relationLoadStrategy` arg still overrides this. Requires an engine
@@ -743,9 +747,9 @@ export interface TurbinePowdbOptions extends EngineClientConfig {
 /**
  * Selects the **embedded** transport, an in-process `@zvndev/powdb-embedded`
  * database at the given data directory (no server, no socket). The value is the
- * data dir path. Preview: Full-durability checkpoint-bound; built binaries ship
- * for macOS (arm64/x64) and Unix-glibc only (Intel-mac/musl/Windows fall back to
- * a from-source `npm run build`).
+ * data dir path. Preview: Full-durability checkpoint-bound; prebuilt binaries ship
+ * for macOS arm64 and Linux glibc x64/arm64 only (Intel macOS, musl and Windows
+ * fall back to a from-source `npm run build`).
  *
  * @example
  * ```ts

package/dist/powdb.js

@@ -21,7 +21,9 @@
  *     writable types (`str`/`int`/`float`/`bool`); `Date` → `int` epoch micros;
  *     `string` PKs hold UUID strings.
  *   - **No JSON aggregation / link navigation**, single-query nested `with` is
- *     impossible → it degrades to batched N+1 loaders (Phase B).
+ *     not available → on PowDB 0.18+ an eligible `with` compiles to nested
+ *     projections inside the parent statement; older engines and ineligible
+ *     relations use batched loaders.
  *   - **Single global write lock; no savepoints/isolation**, nested
  *     transactions / isolation / vector / LISTEN-NOTIFY / RLS throw.
  *     Independent concurrent `db.$transaction` calls do NOT throw: they queue
@@ -1832,7 +1834,7 @@ async function loadPowdbEmbedded() {
     catch (err) {
         throw new ConnectionError("turbine-orm/powdb embedded mode requires the optional peer '@zvndev/powdb-embedded'. " +
             'Install it: npm i @zvndev/powdb-embedded. If install succeeded but loading failed, your platform has no ' +
-            'prebuilt binary (prebuilts ship for macOS arm64/x64 and Linux glibc x64/arm64; Intel-mac/musl/Windows ' +
+            'prebuilt binary (prebuilts ship for macOS arm64 and Linux glibc x64/arm64; Intel macOS, musl and Windows ' +
             'build from source), build it with `npm run build` in the addon, then retry. You can also construct the ' +
             'pool yourself and inject it: turbinePowDB(pool, schema). ' +
             `(${err.message})`);

package/dist/query/builder.d.ts

@@ -1702,6 +1702,14 @@ export declare class QueryInterface<T extends object, R extends object = {}, M e
      * search down the wrong path.
      */
     private buildRowDecodePlan;
+    /**
+     * The cached decode plan for one exact column list, without touching the
+     * per-table most-recent slot. {@link buildRowDecodePlan} is the per-row entry;
+     * this is also what the positional nested-row plan in relations.ts reads
+     * (through the ctx) when it is built, so a nested row decodes by exactly the
+     * field names and cell kinds {@link parseRow} would give the same keys.
+     */
+    private rowDecodePlanFor;
     /**
      * Whether a cached plan describes exactly this row's column list, in order.
      * A pointer compare per column: both sides are the driver's own interned

package/dist/query/builder.js

@@ -34,7 +34,7 @@ import { lockOnStreamMessage, lockOutsideTransactionMessage, lockWithDistinctMes
 import { resolveSqlComment } from './sql-comment.js';
 import { DEFAULT_STREAM_IDLE_TIMEOUT_MS, newStreamIdleState, resolveStreamIdleTimeout, StreamIdleGuard, streamBackstopStatement, streamIdleExpiredError, watchStreamConnection, } from './stream-idle.js';
 import { resolveSkipGlobalFilters, resolveUnsafeFlag, UNSAFE } from './types.js';
-import { assertMiddlewareArgsKept, availableClause, boundedPreparedName, canCancelBackend, isNodePostgresPool, isTemporalInfinity, LRUCache, normalizePagination, ownLookup, parseDbDate, readJsonFloat, readJsonFloatArray, readOnlyMiddlewareParams, readTextArray, resolveColumnName, resolveRelation, resolveRelationDef, sendCancelRequest, sqlToPreparedName, unknownFieldMessage, warnRedundantSortTerm, } from './utils.js';
+import { assertMiddlewareArgsKept, availableClause, boundedPreparedName, CELL_DIALECT, CELL_FLOAT, CELL_FLOAT_ARRAY, CELL_PLAIN, CELL_TEMPORAL, CELL_TEXT_ARRAY, canCancelBackend, isNodePostgresPool, isTemporalInfinity, LRUCache, normalizePagination, ownLookup, parseDbDate, readJsonFloat, readJsonFloatArray, readOnlyMiddlewareParams, readTextArray, resolveColumnName, resolveRelation, resolveRelationDef, sendCancelRequest, sqlToPreparedName, unknownFieldMessage, warnRedundantSortTerm, } from './utils.js';
 import { resetWarnOnce, shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
@@ -239,14 +239,6 @@ const ROW_PLAN_CACHE_SIZE = 128;
  * probe's own limit.
  */
 const STREAM_SPECULATION_MAX_BATCH = 1000;
-/** Per-cell decode work in a {@link RowDecodePlan}. */
-const CELL_PLAIN = 0;
-const CELL_TEMPORAL = 1;
-const CELL_FLOAT = 2;
-const CELL_FLOAT_ARRAY = 3;
-const CELL_TEXT_ARRAY = 4;
-/** The dialect's own decode for a type whose storage differs (see `Dialect.decodeColumnValue`). */
-const CELL_DIALECT = 5;
 const FLOAT_TYPES = new Set(['float4', 'float8', 'real', 'double precision']);
 const FLOAT_ARRAY_TYPES = new Set(['_float4', '_float8', 'float4[]', 'float8[]', 'real[]', 'double precision[]']);
 /**
@@ -982,6 +974,11 @@ export class QueryInterface {
             toColumn: (field) => this.toColumn(field),
             castAgg: (expr, target) => this.castAgg(expr, target),
             parseRow: (row, table) => this.parseRow(row, table),
+            rowDecodePlan: (table, keys) => {
+                const meta = this.schema.tables[table];
+                return meta ? this.rowDecodePlanFor(table, meta, keys) : undefined;
+            },
+            decodeCell: (kind, value, table, field) => this.decodeCell(kind, value, table, field),
             nullsSuffix: (nulls) => this.nullsSuffix(nulls),
             isRelationOrderByValue: (value) => this.isRelationOrderByValue(value),
             resolveOrderByColumn: (table, meta, key) => this.resolveOrderByColumn(table, meta, key),
@@ -5290,6 +5287,18 @@ export class QueryInterface {
      * search down the wrong path.
      */
     buildRowDecodePlan(table, meta, keys) {
+        const plan = this.rowDecodePlanFor(table, meta, keys);
+        this.rowPlanLast.set(table, plan);
+        return plan;
+    }
+    /**
+     * The cached decode plan for one exact column list, without touching the
+     * per-table most-recent slot. {@link buildRowDecodePlan} is the per-row entry;
+     * this is also what the positional nested-row plan in relations.ts reads
+     * (through the ctx) when it is built, so a nested row decodes by exactly the
+     * field names and cell kinds {@link parseRow} would give the same keys.
+     */
+    rowDecodePlanFor(table, meta, keys) {
         const shapeKey = `${table}\u0000${keys.join('\u0000')}`;
         let plan = this.rowPlanCache.get(shapeKey);
         if (plan === undefined) {
@@ -5313,7 +5322,6 @@ export class QueryInterface {
             plan = { cols, fields, kinds };
             this.rowPlanCache.set(shapeKey, plan);
         }
-        this.rowPlanLast.set(table, plan);
         return plan;
     }
     /**

package/dist/query/relations.d.ts

@@ -353,11 +353,22 @@ export declare function buildRelationShapes(qi: BuilderCtx, table: string, withC
 export declare function buildRelationShape(qi: BuilderCtx, relDef: RelationDef, spec: true | WithOptions, parentMeta: TableMetadata, includePii?: boolean): RelationShape;
 /**
  * Build the row parser for a `with` clause. In object mode this is just
- * {@link parseNestedRow}. In positional mode it decodes each relation's
- * positional arrays into the object form first (shapes built once, not per
- * row), then delegates to parseNestedRow for date/snake-camel coercion.
+ * {@link parseNestedRow}. In positional mode the relation shapes are built
+ * once (not per row) and compiled into a decode plan
+ * ({@link makePositionalRowParser}) that turns each positional array straight
+ * into its parsed row. A query whose shapes the plan declines takes the
+ * reference path instead, which decodes each positional array into the object
+ * form and hands it to parseNestedRow.
  */
 export declare function makeNestedParser(qi: BuilderCtx, withClause: WithClause, includePii?: boolean, flattenPlan?: FlattenPlan | null): (row: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * The positional parser the plan in {@link makePositionalRowParser} is held to:
+ * decode each relation's arrays into the object representation, then parse
+ * that exactly as an object-encoded row is parsed. It is the path for every
+ * query the plan declines, and is exported so the differential tests can
+ * compare the two.
+ */
+export declare function makeReferencePositionalParser(qi: BuilderCtx, shapes: Record<string, RelationShape>): (row: Record<string, unknown>) => Record<string, unknown>;
 /**
  * Return a shallow copy of a top-level row with each relation column decoded
  * from its positional array(s) into the object representation. Only relation
@@ -374,6 +385,13 @@ export declare function decodePositionalRelations(qi: BuilderCtx, row: Record<st
 export declare function decodePositionalValue(qi: BuilderCtx, raw: unknown, shape: RelationShape): unknown;
 /** Map one positional array back to a keyed object using the shape's key order. */
 export declare function decodePositionalObject(qi: BuilderCtx, arr: unknown, shape: RelationShape): unknown;
+/**
+ * Compile a top-level positional parser for `shapes`, or `undefined` when any
+ * part of it is a shape the plan does not take (the caller then uses
+ * {@link makeReferencePositionalParser}). Rows are identical to the
+ * reference's on every shape it does take.
+ */
+export declare function makePositionalRowParser(qi: BuilderCtx, table: string, shapes: Record<string, RelationShape>): ((row: Record<string, unknown>) => Record<string, unknown>) | undefined;
 /** One relation `'flatten'` declined, with the reason, for the dev warning. */
 export interface FlattenReject {
     /** Dotted path from the root table's `with`, e.g. `order.customer`. */

package/dist/query/relations.js

@@ -19,7 +19,7 @@ import { normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import { resolveCountRelations, stitchOnlyFields } from './batched-loader.js';
 import { describeOperand, isJsonPathOrderBy, isOrderBySpec, isPlainRecord, isRelationPickOrderBy, isVectorOrderBy, MAX_NAMED_ORDER_KEYS, normalizeOrderBy, orderByEntries, sortedEntries, } from './filters.js';
 import { assertDirectionToken, assertOrderDirection } from './types.js';
-import { availableClause, canonicalColumnOrder, ownLookup, relationInProjectionMessage, resolveColumnName, resolveRelation, resolveRelationDef, selectNamesNothingMessage, selectOmitExclusiveMessage, suggestKey, unknownFieldMessage, } from './utils.js';
+import { availableClause, CELL_FLOAT, CELL_PLAIN, canonicalColumnOrder, ownLookup, relationInProjectionMessage, resolveColumnName, resolveRelation, resolveRelationDef, selectNamesNothingMessage, selectOmitExclusiveMessage, suggestKey, unknownFieldMessage, } from './utils.js';
 import { hasWarnedOnce, shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
@@ -1405,6 +1405,22 @@ export function parseNestedRow(qi, row, table, fromJson = false) {
     const meta = qi.schema.tables[table];
     if (!meta)
         return qi.parseRow(row, table);
+    const parsed = parseScalarColumns(qi, row, table, meta, fromJson);
+    for (const [relName, relDef] of getRelationEntries(qi, table, meta)) {
+        const rawValue = row[relName];
+        if (rawValue === undefined)
+            continue;
+        parsed[relName] = parseRelationValue(qi, relName, relDef, rawValue);
+    }
+    return parsed;
+}
+/**
+ * The scalar half of {@link parseNestedRow}: the row through `parseRow` (after
+ * the JSON-wire decode when `fromJson`), with any `_count__<rel>` columns
+ * folded into a `_count` object. Relation columns are copied through as they
+ * are; the caller replaces each one it parses.
+ */
+function parseScalarColumns(qi, row, table, meta, fromJson) {
     const parsed = qi.parseRow(fromJson ? decodeJsonWireRow(qi, row, table, meta) : row, table);
     // Assemble reserved `_count__<rel>` scalar columns into a `_count` object.
     // parseRow copies these unknown columns through under their raw key.
@@ -1431,75 +1447,66 @@ export function parseNestedRow(qi, row, table, fromJson = false) {
             delete parsed[`${COUNT_PREFIX}${rel}`];
         parsed._count = countObj;
     }
-    for (const [relName, relDef] of getRelationEntries(qi, table, meta)) {
-        const rawValue = row[relName];
-        if (rawValue === undefined)
-            continue;
-        // --- Short-circuit: skip JSON.parse for common empty/null cases ---
-        // hasMany returns '[]' (from COALESCE(..., '[]'::json)); belongsTo/hasOne returns null
-        if (rawValue === null || rawValue === 'null') {
-            parsed[relName] = null;
-            continue;
-        }
-        if (rawValue === '[]') {
-            parsed[relName] = [];
-            continue;
-        }
-        if (Array.isArray(rawValue) && rawValue.length === 0) {
-            parsed[relName] = [];
-            continue;
-        }
-        // --- Non-empty values: full parse path ---
-        if (typeof rawValue === 'string') {
-            try {
-                const jsonVal = JSON.parse(rawValue);
-                // After parsing, recurse via parseNestedRow so each item gets date
-                // coercion AND its own sub-relations parsed at arbitrary depth.
-                if (Array.isArray(jsonVal)) {
-                    parsed[relName] = jsonVal.map((item) => typeof item === 'object' && item !== null
-                        ? parseNestedRow(qi, item, relDef.to, true)
-                        : item);
-                }
-                else if (typeof jsonVal === 'object' && jsonVal !== null) {
-                    parsed[relName] = parseNestedRow(qi, jsonVal, relDef.to, true);
-                }
-                else {
-                    parsed[relName] = jsonVal;
-                }
+    return parsed;
+}
+/**
+ * The relation half of {@link parseNestedRow}: one relation column's value
+ * (never `undefined`, which the caller skips) as the parsed relation.
+ */
+function parseRelationValue(qi, relName, relDef, rawValue) {
+    // --- Short-circuit: skip JSON.parse for common empty/null cases ---
+    // hasMany returns '[]' (from COALESCE(..., '[]'::json)); belongsTo/hasOne returns null
+    if (rawValue === null || rawValue === 'null')
+        return null;
+    if (rawValue === '[]')
+        return [];
+    if (Array.isArray(rawValue) && rawValue.length === 0)
+        return [];
+    // --- Non-empty values: full parse path ---
+    if (typeof rawValue === 'string') {
+        try {
+            const jsonVal = JSON.parse(rawValue);
+            // After parsing, recurse via parseNestedRow so each item gets date
+            // coercion AND its own sub-relations parsed at arbitrary depth.
+            if (Array.isArray(jsonVal)) {
+                return jsonVal.map((item) => typeof item === 'object' && item !== null
+                    ? parseNestedRow(qi, item, relDef.to, true)
+                    : item);
             }
-            catch (err) {
-                // A relation column that does not parse is a bug in the emitted SQL or
-                // a driver-level corruption, not a recoverable condition. Handing back
-                // the raw string satisfied the assignment and violated the generated
-                // type: callers got a `string` where `Post[]` was promised, and found
-                // out at the first `.map`. Throw instead, with the context needed to
-                // find it.
-                //
-                // The warn is gated and deduped because this sits in parseNestedRow's
-                // per-relation loop: one 10,000-row page was 10,000 warnings. The
-                // parse error stays out of the entry: its message quotes the payload,
-                // which is row data.
-                const log = whereMod.adviceLogger(qi);
-                if (log && shouldWarnOnce(WARN_NS.relationParseFailure, `${qi.table}.${relName}`)) {
-                    logTo(log, 'warn', `Relation "${relName}" on "${qi.table}" returned a payload that is not valid JSON. ` +
-                        `This is a bug; please report it with the emitted SQL.`, { code: 'relation-payload-json', table: qi.table, relation: relName });
-                }
-                throw new InvariantError('relation-payload-json', `Relation "${relName}" on table "${qi.table}" returned a payload that could not be parsed as JSON.`, { cause: err });
+            if (typeof jsonVal === 'object' && jsonVal !== null) {
+                return parseNestedRow(qi, jsonVal, relDef.to, true);
             }
-        }
-        else if (Array.isArray(rawValue)) {
-            parsed[relName] = rawValue.map((item) => typeof item === 'object' && item !== null
-                ? parseNestedRow(qi, item, relDef.to, true)
-                : item);
-        }
-        else if (typeof rawValue === 'object' && rawValue !== null) {
-            parsed[relName] = parseNestedRow(qi, rawValue, relDef.to, true);
-        }
-        else {
-            parsed[relName] = rawValue;
+            return jsonVal;
+        }
+        catch (err) {
+            // A relation column that does not parse is a bug in the emitted SQL or
+            // a driver-level corruption, not a recoverable condition. Handing back
+            // the raw string satisfied the assignment and violated the generated
+            // type: callers got a `string` where `Post[]` was promised, and found
+            // out at the first `.map`. Throw instead, with the context needed to
+            // find it.
+            //
+            // The warn is gated and deduped because this sits in parseNestedRow's
+            // per-relation loop: one 10,000-row page was 10,000 warnings. The
+            // parse error stays out of the entry: its message quotes the payload,
+            // which is row data.
+            const log = whereMod.adviceLogger(qi);
+            if (log && shouldWarnOnce(WARN_NS.relationParseFailure, `${qi.table}.${relName}`)) {
+                logTo(log, 'warn', `Relation "${relName}" on "${qi.table}" returned a payload that is not valid JSON. ` +
+                    `This is a bug; please report it with the emitted SQL.`, { code: 'relation-payload-json', table: qi.table, relation: relName });
+            }
+            throw new InvariantError('relation-payload-json', `Relation "${relName}" on table "${qi.table}" returned a payload that could not be parsed as JSON.`, { cause: err });
         }
     }
-    return parsed;
+    if (Array.isArray(rawValue)) {
+        return rawValue.map((item) => typeof item === 'object' && item !== null
+            ? parseNestedRow(qi, item, relDef.to, true)
+            : item);
+    }
+    if (typeof rawValue === 'object' && rawValue !== null) {
+        return parseNestedRow(qi, rawValue, relDef.to, true);
+    }
+    return rawValue;
 }
 /**
  * Resolve the emitted column list for a relation, honoring `select` / `omit`.
@@ -1685,9 +1692,12 @@ export function buildRelationShape(qi, relDef, spec, parentMeta, includePii) {
 }
 /**
  * Build the row parser for a `with` clause. In object mode this is just
- * {@link parseNestedRow}. In positional mode it decodes each relation's
- * positional arrays into the object form first (shapes built once, not per
- * row), then delegates to parseNestedRow for date/snake-camel coercion.
+ * {@link parseNestedRow}. In positional mode the relation shapes are built
+ * once (not per row) and compiled into a decode plan
+ * ({@link makePositionalRowParser}) that turns each positional array straight
+ * into its parsed row. A query whose shapes the plan declines takes the
+ * reference path instead, which decodes each positional array into the object
+ * form and hands it to parseNestedRow.
  */
 export function makeNestedParser(qi, withClause, includePii, flattenPlan) {
     // A flatten plan and the positional encoding are mutually exclusive (the
@@ -1699,6 +1709,16 @@ export function makeNestedParser(qi, withClause, includePii, flattenPlan) {
         return (row) => parseNestedRow(qi, row, qi.table);
     }
     const shapes = buildRelationShapes(qi, qi.table, withClause, includePii);
+    return makePositionalRowParser(qi, qi.table, shapes) ?? makeReferencePositionalParser(qi, shapes);
+}
+/**
+ * The positional parser the plan in {@link makePositionalRowParser} is held to:
+ * decode each relation's arrays into the object representation, then parse
+ * that exactly as an object-encoded row is parsed. It is the path for every
+ * query the plan declines, and is exported so the differential tests can
+ * compare the two.
+ */
+export function makeReferencePositionalParser(qi, shapes) {
     return (row) => parseNestedRow(qi, decodePositionalRelations(qi, row, shapes), qi.table);
 }
 /**
@@ -1753,6 +1773,247 @@ export function decodePositionalObject(qi, arr, shape) {
     }
     return obj;
 }
+/**
+ * A key the reference path treats as an ordinary own property: not one that
+ * resolves through `Object.prototype` when read off a plain object (`__proto__`
+ * included), and not an integer-like key, which `Object.keys` lists ahead of
+ * every other key whatever order it was written in.
+ */
+function isPlainKey(key) {
+    return typeof key === 'string' && !(key in Object.prototype) && !/^\d+$/.test(key);
+}
+/**
+ * Does `name` reach `parseRow`'s answer for a top-level column? Any overlap
+ * with a column name, field name, reverse-map key or date column means the
+ * reference would give the relation column a field or cell kind of its own.
+ */
+function nameTouchesColumns(qi, table, meta, name) {
+    if (Object.hasOwn(meta.reverseColumnMap, name) || meta.dateColumns.has(name))
+        return true;
+    if (getCamelDateFields(qi, table, meta).has(name))
+        return true;
+    return meta.columns.some((column) => column.name === name || column.field === name);
+}
+/** The indexes of `relations` in `entries` order, or `null` when that is their own order. */
+function relationDecodeOrder(relations, entries) {
+    const order = [];
+    for (const [name] of entries) {
+        const index = relations.findIndex((rel) => rel.name === name);
+        if (index !== -1)
+            order.push(index);
+    }
+    return order.every((index, i) => index === i) ? null : order;
+}
+/** The plan for one relation shape, or `undefined` when the plan cannot take it. */
+function planPositionalRow(qi, table, shape) {
+    const meta = qi.schema.tables[table];
+    if (!meta || !qi.rowDecodePlan)
+        return undefined;
+    const keys = shape.keys;
+    if (new Set(keys).size !== keys.length || !keys.every(isPlainKey))
+        return undefined;
+    const rowPlan = qi.rowDecodePlan(table, keys);
+    if (!rowPlan)
+        return undefined;
+    const entries = getRelationEntries(qi, table, meta);
+    if (!entries.every(([name]) => isPlainKey(name)))
+        return undefined;
+    const relationNames = new Set(entries.map(([name]) => name));
+    const wireFields = jsonWireFields(qi, table, meta);
+    const wireOrder = wireFields ? [...wireFields.keys()] : [];
+    const fields = [];
+    const wire = [];
+    const cellPositions = [];
+    const cellKinds = [];
+    const relations = [];
+    let lastWireRank = -1;
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        const field = rowPlan.fields[i];
+        const kind = rowPlan.kinds[i];
+        // parseNestedRow folds a `_count__` field into `_count`; the plan does not.
+        if (!isPlainKey(field) || field.startsWith(COUNT_PREFIX))
+            return undefined;
+        const nested = shape.nested[key];
+        if (nested) {
+            const def = ownLookup(meta.relations, key);
+            // The reference copies the slot through parseRow before replacing it, so
+            // the slot must be a plain cell under its own name, and no wire field.
+            if (!def || field !== key || kind !== CELL_PLAIN || wireFields?.has(key))
+                return undefined;
+            const row = planPositionalRow(qi, def.to, nested);
+            if (!row)
+                return undefined;
+            relations.push({ name: key, def, many: nested.cardinality === 'many', position: i, row });
+            continue;
+        }
+        // buildRelationShape puts every scalar ahead of every relation slot, and a
+        // scalar named like one of the table's relations would be re-read as it.
+        if (relations.length > 0 || relationNames.has(key))
+            return undefined;
+        const rule = wireFields?.get(key);
+        if (rule !== undefined) {
+            // The reference decodes wire columns in table-column order before any
+            // cell decode; the plan does them in key order, so the two must agree.
+            const rank = wireOrder.indexOf(key);
+            if (rank < lastWireRank)
+                return undefined;
+            lastWireRank = rank;
+        }
+        fields.push(field);
+        wire.push(rule);
+        if (kind !== CELL_PLAIN) {
+            cellPositions.push(i);
+            cellKinds.push(kind);
+        }
+    }
+    // Two keys landing on one field, or a scalar field named like a relation
+    // slot, would collapse into one property in a different order.
+    const written = new Set(fields);
+    if (written.size !== fields.length || relations.some((rel) => written.has(rel.name)))
+        return undefined;
+    return {
+        table,
+        fields,
+        wire,
+        cellPositions,
+        cellKinds,
+        relations,
+        relationOrder: relationDecodeOrder(relations, entries),
+    };
+}
+/**
+ * Compile a top-level positional parser for `shapes`, or `undefined` when any
+ * part of it is a shape the plan does not take (the caller then uses
+ * {@link makeReferencePositionalParser}). Rows are identical to the
+ * reference's on every shape it does take.
+ */
+export function makePositionalRowParser(qi, table, shapes) {
+    const meta = qi.schema.tables[table];
+    if (!meta || !qi.rowDecodePlan || !qi.decodeCell)
+        return undefined;
+    const entries = getRelationEntries(qi, table, meta);
+    if (!entries.every(([name]) => isPlainKey(name)))
+        return undefined;
+    const plans = [];
+    for (const [name, def] of entries) {
+        const shape = Object.hasOwn(shapes, name) ? shapes[name] : undefined;
+        if (!shape) {
+            plans.push(null);
+            continue;
+        }
+        // The reference runs the top-level row through parseRow with the relation
+        // columns already decoded; the plan runs it with them raw and replaces them
+        // after. Those agree only while parseRow copies a relation column through
+        // untouched, under its own name, and the `_count` fold never reads it.
+        if (name.startsWith(COUNT_PREFIX) || nameTouchesColumns(qi, table, meta, name))
+            return undefined;
+        const row = planPositionalRow(qi, def.to, shape);
+        if (!row)
+            return undefined;
+        plans.push({ name, def, many: shape.cardinality === 'many', position: -1, row });
+    }
+    const isOwnEnumerable = Object.prototype.propertyIsEnumerable;
+    return (row) => {
+        const parsed = parseScalarColumns(qi, row, table, meta, false);
+        for (let i = 0; i < entries.length; i++) {
+            const [name, def] = entries[i];
+            // The reference reads relation columns off a `{ ...row }` copy, which
+            // holds exactly the row's own enumerable properties.
+            if (!isOwnEnumerable.call(row, name))
+                continue;
+            const plan = plans[i];
+            if (plan !== null) {
+                parsed[name] = decodePlannedRelation(qi, row[name], plan);
+                continue;
+            }
+            const raw = row[name];
+            if (raw !== undefined)
+                parsed[name] = parseRelationValue(qi, name, def, raw);
+        }
+        return parsed;
+    };
+}
+/**
+ * One relation value through the plan: exactly what the reference produces by
+ * {@link decodePositionalValue} followed by {@link parseRelationValue}. Every
+ * value that is not the well-formed positional shape (a payload that is not
+ * JSON, a to-many that is not an array, a to-one that is not an array) is
+ * handed to `parseRelationValue` as the reference would hand it, so it
+ * decodes, or throws, identically.
+ */
+function decodePlannedRelation(qi, raw, rel) {
+    let value = raw;
+    if (typeof value === 'string') {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            return parseRelationValue(qi, rel.name, rel.def, raw);
+        }
+    }
+    if (value === null || value === undefined)
+        return rel.many ? [] : null;
+    if (!rel.many) {
+        return Array.isArray(value)
+            ? decodePlannedRow(qi, value, rel.row)
+            : parseRelationValue(qi, rel.name, rel.def, value);
+    }
+    if (!Array.isArray(value))
+        return parseRelationValue(qi, rel.name, rel.def, value);
+    const out = [];
+    for (let i = 0; i < value.length; i++) {
+        const item = value[i];
+        out.push(Array.isArray(item)
+            ? decodePlannedRow(qi, item, rel.row)
+            : typeof item === 'object' && item !== null
+                ? parseNestedRow(qi, item, rel.def.to, true)
+                : item);
+    }
+    return out;
+}
+/** One positional array through its row plan, into the parsed row. */
+function decodePlannedRow(qi, arr, plan) {
+    const out = {};
+    const { fields, wire, cellPositions, cellKinds, relations, table } = plan;
+    for (let i = 0; i < fields.length; i++) {
+        let value = arr[i];
+        const rule = wire[i];
+        if (rule !== undefined && typeof value === 'string')
+            value = rule.decode(value);
+        out[fields[i]] = value;
+    }
+    if (cellPositions.length > 0) {
+        // `decodeCell` is present: the plan is only built when it is.
+        const decodeCell = qi.decodeCell;
+        for (let c = 0; c < cellPositions.length; c++) {
+            const field = fields[cellPositions[c]];
+            const kind = cellKinds[c];
+            const value = out[field];
+            // parseRow's own skip: a float the driver already made a number.
+            if (kind === CELL_FLOAT && typeof value !== 'string')
+                continue;
+            out[field] = decodeCell(kind, value, table, field);
+        }
+    }
+    if (relations.length > 0) {
+        const order = plan.relationOrder;
+        if (order === null) {
+            for (const rel of relations)
+                out[rel.name] = decodePlannedRelation(qi, arr[rel.position], rel);
+        }
+        else {
+            // Claim the keys in key order first, then decode in the reference's order.
+            for (const rel of relations)
+                out[rel.name] = undefined;
+            for (const index of order) {
+                const rel = relations[index];
+                out[rel.name] = decodePlannedRelation(qi, arr[rel.position], rel);
+            }
+        }
+    }
+    return out;
+}
 // ---------------------------------------------------------------------------
 // relationLoadStrategy: 'flatten', to-one relations compiled as LEFT JOINs
 // ---------------------------------------------------------------------------

package/dist/query/utils.d.ts

@@ -423,6 +423,19 @@ export declare function coerceTemporalValue(dbType: string | undefined, value: u
  * as-is.
  */
 export declare function parseDbDate(value: string): Date;
+/**
+ * Per-cell decode work in a row decode plan (`RowDecodePlan` in builder.ts).
+ * Defined here rather than in builder.ts because the positional nested-row
+ * plan in relations.ts reads the same codes, and relations.ts cannot import
+ * builder.ts.
+ */
+export declare const CELL_PLAIN = 0;
+export declare const CELL_TEMPORAL = 1;
+export declare const CELL_FLOAT = 2;
+export declare const CELL_FLOAT_ARRAY = 3;
+export declare const CELL_TEXT_ARRAY = 4;
+/** The dialect's own decode for a type whose storage differs (see `Dialect.decodeColumnValue`). */
+export declare const CELL_DIALECT = 5;
 /**
  * A float column's value as the driver reads it. JSON has no NaN or infinity,
  * so `json_build_object` renders them as the strings "NaN", "Infinity" and