turbine-orm 0.91.0 → 0.92.0

package/dist/cjs/query/relations.js

@@ -83,9 +83,11 @@ exports.buildJsonRow = buildJsonRow;
 exports.buildRelationShapes = buildRelationShapes;
 exports.buildRelationShape = buildRelationShape;
 exports.makeNestedParser = makeNestedParser;
+exports.makeReferencePositionalParser = makeReferencePositionalParser;
 exports.decodePositionalRelations = decodePositionalRelations;
 exports.decodePositionalValue = decodePositionalValue;
 exports.decodePositionalObject = decodePositionalObject;
+exports.makePositionalRowParser = makePositionalRowParser;
 exports.provableUniqueTargetKey = provableUniqueTargetKey;
 exports.planFlattenWith = planFlattenWith;
 exports.emitFlattenNode = emitFlattenNode;
@@ -1488,6 +1490,22 @@ 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.
@@ -1514,75 +1532,66 @@ 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 && (0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.WARN_NS.relationParseFailure, `${qi.table}.${relName}`)) {
-                    (0, logger_js_1.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 errors_js_1.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 && (0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.WARN_NS.relationParseFailure, `${qi.table}.${relName}`)) {
+                (0, logger_js_1.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 errors_js_1.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`.
@@ -1768,9 +1777,12 @@ 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.
  */
 function makeNestedParser(qi, withClause, includePii, flattenPlan) {
     // A flatten plan and the positional encoding are mutually exclusive (the
@@ -1782,6 +1794,16 @@ 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.
+ */
+function makeReferencePositionalParser(qi, shapes) {
     return (row) => parseNestedRow(qi, decodePositionalRelations(qi, row, shapes), qi.table);
 }
 /**
@@ -1836,6 +1858,247 @@ 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 = (0, utils_js_1.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 !== utils_js_1.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 !== utils_js_1.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.
+ */
+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 === utils_js_1.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/cjs/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

package/dist/cjs/query/utils.js

@@ -8,7 +8,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.JSON_WIRE_COERCION_OIDS = exports.OPERATOR_KEYS = exports.PREPARED_STATEMENT_BUDGET = exports.LRUCache = exports.INTERNAL_COMBINATOR = void 0;
+exports.JSON_WIRE_COERCION_OIDS = exports.CELL_DIALECT = exports.CELL_TEXT_ARRAY = exports.CELL_FLOAT_ARRAY = exports.CELL_FLOAT = exports.CELL_TEMPORAL = exports.CELL_PLAIN = exports.OPERATOR_KEYS = exports.PREPARED_STATEMENT_BUDGET = exports.LRUCache = exports.INTERNAL_COMBINATOR = void 0;
 exports.quoteIdent = quoteIdent;
 exports.ownLookup = ownLookup;
 exports.resolveColumnName = resolveColumnName;
@@ -884,6 +884,13 @@ function renderTemporal(value, kind) {
  * or a `±HH`, `±HHMM`, `±HH:MM` offset.
  */
 const TZ_SUFFIX_RE = /(?:Z|[+-]\d{2}(?::?\d{2})?)$/;
+const COLON_CHAR = 58;
+const PLUS_CHAR = 43;
+const MINUS_CHAR = 45;
+/** `0`-`9` as a char code. */
+function isDigitCode(code) {
+    return code >= 48 && code <= 57;
+}
 /**
  * Parse a database date-time string deterministically.
  *
@@ -906,6 +913,29 @@ function parseDbDate(value) {
     return Number.isNaN(date.getTime()) ? (parseDbDateGeneral(value) ?? date) : date;
 }
 function parseDbDateCommon(value) {
+    // Fast path for the shape `timestamptz` arrives in, a trailing `±HH:MM`
+    // offset (`2026-07-07T17:15:41.896+00:00`). It is exactly the general path's
+    // answer for that shape, not an approximation of it: the string contains a
+    // ':' (at length-3), TZ_SUFFIX_RE matches, and neither normalizing replace
+    // below can fire (the first needs four digits after the sign, the second two
+    // digits at the very end after it), so that path also ends in
+    // `new Date(value)`. All six offset characters are checked, so a near miss
+    // (`+0a:00`, `05:30` without a sign) still takes the general path. It skips
+    // one regex test and two regex replaces per value, which on a nested read is
+    // the single largest cost in the decode. The invalid-date fallback in
+    // parseDbDate still runs on the result, so a BC or five-digit year is
+    // unchanged.
+    const n = value.length;
+    if (n >= 6 && value.charCodeAt(n - 3) === COLON_CHAR) {
+        const sign = value.charCodeAt(n - 6);
+        if ((sign === PLUS_CHAR || sign === MINUS_CHAR) &&
+            isDigitCode(value.charCodeAt(n - 5)) &&
+            isDigitCode(value.charCodeAt(n - 4)) &&
+            isDigitCode(value.charCodeAt(n - 2)) &&
+            isDigitCode(value.charCodeAt(n - 1))) {
+            return new Date(value);
+        }
+    }
     // Date-only values (`2026-07-07`, from `date` columns in json_agg output)
     // have no time to zone-pin, and their `-07` tail must not be read as an
     // offset. JS parses bare ISO dates as UTC midnight already.
@@ -945,6 +975,19 @@ function parseDbDateGeneral(value) {
     }
     return 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.
+ */
+exports.CELL_PLAIN = 0;
+exports.CELL_TEMPORAL = 1;
+exports.CELL_FLOAT = 2;
+exports.CELL_FLOAT_ARRAY = 3;
+exports.CELL_TEXT_ARRAY = 4;
+/** The dialect's own decode for a type whose storage differs (see `Dialect.decodeColumnValue`). */
+exports.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

package/dist/cjs/query/where.d.ts

@@ -133,6 +133,21 @@ export interface BuilderCtx {
     toColumn(field: string): string;
     castAgg(expr: string, target: 'int' | 'float'): string;
     parseRow(row: Record<string, unknown>, table: string): Record<string, unknown>;
+    /**
+     * The field name and cell kind {@link parseRow} applies to each key of a row
+     * whose keys are exactly `keys`, in order (`undefined` for a table with no
+     * metadata). Read once per relation shape by the positional nested-row plan
+     * in relations.ts, so a nested row decodes by the same answers `parseRow`
+     * would give. Optional, like the members above, so a hand-built ctx keeps
+     * compiling; without it (or {@link decodeCell}) the nested parser takes the
+     * general path.
+     */
+    rowDecodePlan?(table: string, keys: readonly string[]): {
+        readonly fields: readonly string[];
+        readonly kinds: readonly number[];
+    } | undefined;
+    /** {@link parseRow}'s decode of one cell whose kind is not `CELL_PLAIN` (see utils.ts). */
+    decodeCell?(kind: number, value: unknown, table: string, field: string): unknown;
     nullsSuffix(nulls: 'first' | 'last' | undefined): string;
     isRelationOrderByValue(value: unknown): boolean;
     resolveOrderByColumn(table: string, meta: TableMetadata, key: string): string;

package/dist/cjs/schema-builder.d.ts

@@ -73,8 +73,10 @@ export interface ColumnDef {
      * code-first declaration: it carries onto {@link ColumnConfig.pii} and, via
      * `schemaDefToMetadata` / codegen, onto
      * {@link import('./schema.js').ColumnMetadata.pii}. A PII column is excluded
-     * from default projections (read back only via an explicit `select` or
-     * `includePii: UNSAFE`, the imported sentinel symbol) and redacted by Studio.
+     * from default projections and comes back only from a read that passes
+     * `includePii: UNSAFE` (the imported sentinel symbol). Naming it in `select`
+     * without that flag throws (E003), a write never returns it, and Studio
+     * redacts it.
      * Introspection never auto-tags PII.
      */
     pii?: boolean;
@@ -248,9 +250,10 @@ export interface TableDef {
     checks?: readonly CheckDef[];
     /**
      * Index declarations for this table (plain column indexes and/or PowDB
-     * doc-field expression indexes). Consumed by the PowDB DDL generator
-     * (`powqlSchemaDDL`) and carried onto `IndexMetadata` by
-     * `schemaDefToMetadata`; the SQL DDL generators do not consume them yet.
+     * doc-field expression indexes). Plain column indexes are emitted as `CREATE [UNIQUE] INDEX` by
+     * `schemaToSQL` and added by `schemaDiff`; doc-field indexes are PowDB-only
+     * (`powqlSchemaDDL`). Both are carried onto `IndexMetadata` by
+     * `schemaDefToMetadata`.
      */
     indexes?: readonly SchemaIndexDef[];
 }

package/dist/cli/config.d.ts

@@ -189,6 +189,11 @@ export interface ResolvedConfig {
     relationNames?: Record<string, Record<string, string>>;
     /** Column type overrides for the generator, or undefined when none is declared. */
     columnTypes?: Record<string, string>;
+    /**
+     * The config file's `adapter`, passed to `migrate up` / `deploy` / `down` so a
+     * CockroachDB or YugabyteDB project takes the migration lock its engine supports.
+     */
+    adapter?: import('../adapters/index.js').DatabaseAdapter;
 }
 export interface CliOverrides {
     url?: string;

package/dist/cli/config.js

@@ -184,6 +184,7 @@ export function resolveConfig(fileConfig, overrides) {
         importExtension: overrides.importExtension ?? fileConfig.importExtension ?? 'auto',
         keepColumnNames: overrides.keepColumnNames ?? fileConfig.keepColumnNames ?? false,
         legacyToManyUniques: overrides.legacyToManyUniques ?? fileConfig.legacyToManyUniques ?? false,
+        adapter: fileConfig.adapter,
     };
 }
 /**

package/dist/cli/index.d.ts

@@ -2,23 +2,23 @@
 /**
  * turbine-orm CLI
  *
- * Commands:
- *   turbine init                 , Initialize a Turbine project
- *   turbine generate | pull      , Introspect database and generate TypeScript types
- *   turbine migrate-from-prisma   - Parse a schema.prisma and emit a Prisma->Turbine name map + report
- *   turbine push                  - Apply schema-builder definitions to database (--schema-file, destructive ops gated)
- *   turbine migrate create <name> - Create a new SQL migration file (--auto | --from-diff | --recipe <name>)
- *   turbine migrate up           , Apply pending migrations
- *   turbine migrate deploy       , Apply pending migrations without prompts
- *   turbine migrate down         , Rollback last migration
- *   turbine migrate status       , Show migration status
- *   turbine seed                 , Run seed file
- *   turbine status               , Show schema summary
- *   turbine doctor                - Index + cached-plan triage (--fix, --json, --no-concurrently, --unused, --audit, --no-plan-divergence, --allow-pooler)
- *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
- *   turbine mcp                  , Start read-only MCP server over JSON-RPC stdio
- *   turbine observe              , Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
- *   turbine skill                 - Install the agent query skill (--print, --agents, --dir <path>)
+ * Commands (each has its own `--help`, which is the full flag list):
+ *   turbine init                   Initialize a Turbine project
+ *   turbine generate | pull        Introspect the database and generate TypeScript types
+ *   turbine migrate-from-prisma    Parse a schema.prisma and emit a Prisma->Turbine name map + report
+ *   turbine push                   Apply defineSchema() definitions to the database (destructive ops gated)
+ *   turbine migrate create <name>  Create a SQL migration file (--auto | --from-diff | --recipe <name>)
+ *   turbine migrate up             Apply pending migrations
+ *   turbine migrate deploy         Apply pending migrations without prompts
+ *   turbine migrate down           Roll back the last migration
+ *   turbine migrate status         Show migration status
+ *   turbine seed                   Run the seed file
+ *   turbine status                 Show a schema summary
+ *   turbine doctor                 Index + cached-plan triage
+ *   turbine studio                 Launch the local read-only web UI (--demo for a seeded sample DB)
+ *   turbine mcp                    Start the read-only MCP server over JSON-RPC stdio
+ *   turbine observe                Launch the metrics dashboard (--metrics-url or TURBINE_OBSERVE_URL)
+ *   turbine skill                  Install the agent query skill
  *
  * Usage:
  *   DATABASE_URL=postgres://... npx turbine generate