turbine-orm 0.91.0 → 0.92.0

package/dist/cjs/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/cjs/powdb.js

@@ -22,7 +22,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
@@ -1867,7 +1869,7 @@ async function loadPowdbEmbedded() {
     catch (err) {
         throw new errors_js_1.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/cjs/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/cjs/query/builder.js

@@ -277,14 +277,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[]']);
 /**
@@ -294,11 +286,11 @@ const FLOAT_ARRAY_TYPES = new Set(['_float4', '_float8', 'float4[]', 'float8[]',
  */
 function cellKindOf(pgType, enums) {
     if (FLOAT_TYPES.has(pgType))
-        return CELL_FLOAT;
+        return utils_js_1.CELL_FLOAT;
     if (FLOAT_ARRAY_TYPES.has(pgType))
-        return CELL_FLOAT_ARRAY;
+        return utils_js_1.CELL_FLOAT_ARRAY;
     const element = pgType.startsWith('_') ? pgType.slice(1) : pgType.endsWith('[]') ? pgType.slice(0, -2) : undefined;
-    return element !== undefined && enums !== undefined && Object.hasOwn(enums, element) ? CELL_TEXT_ARRAY : CELL_PLAIN;
+    return element !== undefined && enums !== undefined && Object.hasOwn(enums, element) ? utils_js_1.CELL_TEXT_ARRAY : utils_js_1.CELL_PLAIN;
 }
 /**
  * Strict structural equality for a single SQL parameter value. Handles the
@@ -1020,6 +1012,11 @@ 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),
@@ -5266,9 +5263,9 @@ class QueryInterface {
                 if (typeof pgType !== 'string')
                     continue;
                 let kind = cellKindOf(pgType, this.schema.enums);
-                const decode = kind === CELL_PLAIN ? this.dialect.decodeColumnValue?.(pgType) : undefined;
+                const decode = kind === utils_js_1.CELL_PLAIN ? this.dialect.decodeColumnValue?.(pgType) : undefined;
                 if (decode !== undefined) {
-                    kind = CELL_DIALECT;
+                    kind = utils_js_1.CELL_DIALECT;
                     let decoders = this.dialectDecodeCache.get(table);
                     if (!decoders) {
                         decoders = new Map();
@@ -5277,7 +5274,7 @@ class QueryInterface {
                     decoders.set(column.name, decode);
                     decoders.set(column.field, decode);
                 }
-                if (kind === CELL_PLAIN)
+                if (kind === utils_js_1.CELL_PLAIN)
                     continue;
                 kinds.set(column.name, kind);
                 kinds.set(column.field, kind);
@@ -5289,15 +5286,15 @@ class QueryInterface {
     /** One cell's decode, for every kind but {@link CELL_PLAIN}. */
     decodeCell(kind, value, table, field) {
         switch (kind) {
-            case CELL_TEMPORAL:
+            case utils_js_1.CELL_TEMPORAL:
                 return this.decodeTemporalCell(value, table, field);
-            case CELL_FLOAT:
+            case utils_js_1.CELL_FLOAT:
                 return (0, utils_js_1.readJsonFloat)(value);
-            case CELL_FLOAT_ARRAY:
+            case utils_js_1.CELL_FLOAT_ARRAY:
                 return (0, utils_js_1.readJsonFloatArray)(value);
-            case CELL_TEXT_ARRAY:
+            case utils_js_1.CELL_TEXT_ARRAY:
                 return (0, utils_js_1.readTextArray)(value);
-            case CELL_DIALECT:
+            case utils_js_1.CELL_DIALECT:
                 return this.decodeDialectCell(value, table, field);
             default:
                 return value;
@@ -5328,6 +5325,18 @@ 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) {
@@ -5345,13 +5354,12 @@ class QueryInterface {
                 fields.push(field);
                 // Top-level rows are snake_case (dateCols); nested rows are camelCase.
                 kinds.push(dateCols.has(col) || camelDateFields.has(field)
-                    ? CELL_TEMPORAL
-                    : (cellKinds.get(col) ?? cellKinds.get(field) ?? CELL_PLAIN));
+                    ? utils_js_1.CELL_TEMPORAL
+                    : (cellKinds.get(col) ?? cellKinds.get(field) ?? utils_js_1.CELL_PLAIN));
             }
             plan = { cols, fields, kinds };
             this.rowPlanCache.set(shapeKey, plan);
         }
-        this.rowPlanLast.set(table, plan);
         return plan;
     }
     /**
@@ -5399,7 +5407,7 @@ class QueryInterface {
                 const kind = kinds[i];
                 // A float from the driver is already a number; only JSON's strings need reading.
                 parsed[field] =
-                    kind === CELL_PLAIN || (kind === CELL_FLOAT && typeof value !== 'string')
+                    kind === utils_js_1.CELL_PLAIN || (kind === utils_js_1.CELL_FLOAT && typeof value !== 'string')
                         ? value
                         : this.decodeCell(kind, value, table, field);
             }

package/dist/cjs/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`. */