turbine-orm 0.22.0 → 0.23.0

package/dist/cjs/powql.js

@@ -16,19 +16,63 @@
  *   - `create`/`createMany`/`update`/`delete` use PowDB 0.7.0's trailing
  *     `returning` keyword (`RETURNING *`, all columns) to surface affected rows
  *     in one round-trip. `upsert` is the lone exception — its statement does not
- *     accept `returning`, so it reselects the row by PK.
- *   - The PK is generated client-side (UUID) when the column has a default.
- *   - `with` (nested relations) degrades to **batched N+1 loaders** — D
- *     round-trips for depth D, not one query. manyToMany is Phase B.
+ *     accept `returning`, so it reselects the row by PK (a composite-PK upsert
+ *     reselects-or-writes inside one flat transaction).
+ *   - The PK is server-assigned when the column is `isGenerated` (PowDB's `auto`
+ *     int — read back via `returning`); otherwise a defaulted **string** PK is
+ *     generated client-side (UUID).
+ *   - `with` (nested relations) uses **batched N+1 loaders** — D round-trips for
+ *     depth D, not one query — including manyToMany (junction → targets).
+ *   - **Relation filters** (`some`/`none`/`every`, all cardinalities incl. m2m)
+ *     are resolved client-side to a literal `in (…)` list, never an IN-subquery:
+ *     PowDB's executor caches a subquery's result by plan shape and would return
+ *     a stale prior result for a later subquery of the same shape.
+ *   - **Nested writes** (relation ops in `create`/`update` data) run through the
+ *     shared nested-write engine as one flat top-level transaction (PowDB is
+ *     single-writer, no savepoints).
  *   - pgvector / JSON / array filters and cursor streaming throw
  *     {@link UnsupportedFeatureError} (E017) — they have no PowDB equivalent.
  *
  * @module
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PowqlInterface = void 0;
 const node_crypto_1 = require("node:crypto");
 const errors_js_1 = require("./errors.js");
+const nested_write_js_1 = require("./nested-write.js");
 const powdb_js_1 = require("./powdb.js");
 const utils_js_1 = require("./query/utils.js");
 const schema_js_1 = require("./schema.js");
@@ -191,7 +235,10 @@ class PowqlInterface {
                     parts.push(`not (${sub})`);
             }
             else if (this.meta.relations[key]) {
-                parts.push(this.buildRelationFilter(this.meta.relations[key], value, params));
+                // Relation filters are pre-resolved to scalar in/notIn by
+                // resolveRelationFilters() before buildWhere runs — reaching here means
+                // a caller skipped that step (an internal bug, not user error).
+                throw new errors_js_1.ValidationError(`[turbine] internal: relation filter "${key}" reached buildWhere unresolved (missing resolveRelationFilters()).`);
             }
             else {
                 parts.push(this.buildFieldCondition(key, value, params));
@@ -279,41 +326,147 @@ class PowqlInterface {
         return `${lhs} ${negate ? 'not in' : 'in'} (${items})`;
     }
     /**
-     * Relation filter (`some`/`none`/`every`) via the verified IN-subquery form
-     * `Outer filter .localKey in (Target filter <e> { .targetKey })`. `exists`
-     * correlation is unreliable on PowDB, so it is never used.
+     * Pre-resolve every relation filter (`some`/`none`/`every`) in a where clause
+     * into a plain scalar `in`/`notIn` condition on the **local key**, by running
+     * the inner predicate as its own query and materializing the matching keys as
+     * a literal list. The compiled where is then relation-free and `buildWhere`
+     * emits only `in (<literal list>)`.
+     *
+     * Why not an IN-subquery (`.k in (Target filter <e> { .fk })`)? PowDB's
+     * executor caches a subquery's result by **plan shape, ignoring the literal**,
+     * so a second subquery of the same shape with a different value returns the
+     * first one's stale rows (reproduced live on the embedded engine; the
+     * single-statement literal `in (list)` form is always correct). Resolving
+     * client-side trades extra round-trips for correctness, and recurses — nested
+     * relation filters in the inner predicate resolve when the target query runs.
      */
-    buildRelationFilter(rel, filter, params) {
+    async resolveRelationFilters(where, timeout) {
+        if (!where)
+            return where;
+        const scalar = {};
+        const relConds = [];
+        for (const [key, value] of Object.entries(where)) {
+            if (value === undefined)
+                continue;
+            if (key === 'AND' || key === 'OR') {
+                scalar[key] = await Promise.all(value.map((w) => this.resolveRelationFilters(w, timeout)));
+            }
+            else if (key === 'NOT') {
+                scalar[key] = await this.resolveRelationFilters(value, timeout);
+            }
+            else if (this.meta.relations[key]) {
+                relConds.push(await this.resolveRelationCondition(this.meta.relations[key], value, timeout));
+            }
+            else {
+                scalar[key] = value;
+            }
+        }
+        if (!relConds.length)
+            return scalar;
+        const hasScalar = Object.keys(scalar).length > 0;
+        return { AND: [...(hasScalar ? [scalar] : []), ...relConds] };
+    }
+    /** Resolve one hasMany/hasOne/belongsTo filter to `{ localField: { in|notIn: [...] } }`. */
+    async resolveRelationCondition(rel, filter, timeout) {
+        const mode = filter.some ? 'some' : filter.none ? 'none' : filter.every ? 'every' : null;
+        if (!mode)
+            return {};
+        const innerWhere = filter[mode];
+        const innerEmpty = !innerWhere || Object.keys(innerWhere).length === 0;
         if (rel.type === 'manyToMany') {
-            throw new errors_js_1.UnsupportedFeatureError('manyToMany relation filters', 'PowDB', `relation "${rel.name}" — junction-table relation filters are Phase B`);
+            return this.resolveManyToManyCondition(rel, mode, innerWhere, innerEmpty, timeout);
         }
         const fk = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
         const rk = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
         if (fk.length > 1 || rk.length > 1) {
-            throw new errors_js_1.UnsupportedFeatureError('composite-key relation filters', 'PowDB', `relation "${rel.name}" uses a composite key`);
+            throw new errors_js_1.UnsupportedFeatureError('composite-key relation filters', 'PowDB', `relation "${rel.name}" uses a composite key — PowQL has no tuple-\`in\` to express it`);
         }
-        // hasMany/hasOne: outer.referenceKey ∈ target.foreignKey.
-        // belongsTo:      outer.foreignKey  ∈ target.referenceKey.
-        const localKey = rel.type === 'belongsTo' ? fk[0] : rk[0];
-        const targetKey = rel.type === 'belongsTo' ? rk[0] : fk[0];
         const targetMeta = this.schema.tables[rel.to];
         if (!targetMeta)
             throw new errors_js_1.ValidationError(`[turbine] Relation "${rel.name}" targets unknown table "${rel.to}".`);
-        const sub = (whereObj, negateInner) => {
-            const innerQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
-            const inner = innerQi.buildWhere(whereObj, params);
-            const filterClause = inner ? ` filter ${negateInner ? `not (${inner})` : inner}` : '';
-            return `${rel.to}${filterClause} { .${targetKey} }`;
+        // hasMany/hasOne: localKey = our referenceKey, collect the child's foreignKey.
+        // belongsTo:      localKey = our foreignKey,   collect the target's referenceKey.
+        const localCol = rel.type === 'belongsTo' ? fk[0] : rk[0];
+        const childCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
+        const localField = this.meta.reverseColumnMap[localCol] ?? localCol;
+        const childField = targetMeta.reverseColumnMap[childCol] ?? childCol;
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const collect = async (w) => {
+            const rows = await targetQi.findMany({
+                where: w,
+                select: { [childField]: true },
+                timeout,
+            });
+            return [...new Set(rows.map((r) => r[childField]).filter((v) => v != null))];
+        };
+        if (mode === 'some')
+            return { [localField]: { in: await collect(innerWhere) } };
+        if (mode === 'none')
+            return { [localField]: { notIn: await collect(innerWhere) } };
+        // every: a parent qualifies unless it has a child FAILING the predicate.
+        if (innerEmpty)
+            return {}; // every:{} ⇒ trivially true for all parents
+        return { [localField]: { notIn: await collect({ NOT: innerWhere }) } };
+    }
+    /** Resolve a manyToMany filter through the junction to `{ sourceRefField: { in|notIn: [...] } }`. */
+    async resolveManyToManyCondition(rel, mode, innerWhere, innerEmpty, timeout) {
+        const through = rel.through;
+        if (!through)
+            throw new errors_js_1.ValidationError(`[turbine] manyToMany relation "${rel.name}" is missing its junction (\`through\`).`);
+        const sourceJ = (0, schema_js_1.normalizeKeyColumns)(through.sourceKey);
+        const targetJ = (0, schema_js_1.normalizeKeyColumns)(through.targetKey);
+        const sourceRef = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
+        const targetMeta = this.schema.tables[rel.to];
+        if (!targetMeta)
+            throw new errors_js_1.ValidationError(`[turbine] Relation "${rel.name}" targets unknown table "${rel.to}".`);
+        if (sourceJ.length > 1 || targetJ.length > 1 || sourceRef.length > 1 || targetMeta.primaryKey.length > 1) {
+            throw new errors_js_1.UnsupportedFeatureError('composite-key manyToMany filters', 'PowDB', `relation "${rel.name}" — PowQL has no tuple-\`in\` for composite junction/target keys`);
+        }
+        const sourceJCol = sourceJ[0];
+        const targetJCol = targetJ[0];
+        const sourceRefCol = sourceRef[0];
+        const targetPkCol = targetMeta.primaryKey[0];
+        const sourceRefField = this.meta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
+        const sourceRefColMeta = this.meta.columns.find((c) => c.name === sourceRefCol);
+        const targetPkField = targetMeta.reverseColumnMap[targetPkCol] ?? targetPkCol;
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const collectTargetPks = async (w) => {
+            const rows = await targetQi.findMany({
+                where: w,
+                select: { [targetPkField]: true },
+                timeout,
+            });
+            return [...new Set(rows.map((r) => r[targetPkField]).filter((v) => v != null))];
+        };
+        // Junction source keys linking any of `targetPks` (literal IN-list — never a subquery).
+        const sourcesForTargets = async (targetPks) => {
+            if (!targetPks.length)
+                return [];
+            const out = new Set();
+            for (let i = 0; i < targetPks.length; i += MAX_RELATION_KEYS) {
+                const chunk = targetPks.slice(i, i + MAX_RELATION_KEYS);
+                const params = [];
+                const ph = chunk.map((v) => this.param(v, params)).join(', ');
+                const { rows } = await this.exec(`${through.table} filter .${targetJCol} in (${ph}) { .${sourceJCol} }`, params, timeout);
+                for (const r of rows) {
+                    const v = r[sourceJCol];
+                    if (v != null)
+                        out.add(sourceRefColMeta ? coerceScalar(String(v), sourceRefColMeta.tsType) : v);
+                }
+            }
+            return [...out];
         };
-        if (filter.some)
-            return `.${localKey} in (${sub(filter.some, false)})`;
-        if (filter.none)
-            return `.${localKey} not in (${sub(filter.none, false)})`;
-        if (filter.every) {
-            // Parents with no child failing the predicate.
-            return `.${localKey} not in (${sub(filter.every, true)})`;
+        if (mode === 'some') {
+            return { [sourceRefField]: { in: await sourcesForTargets(await collectTargetPks(innerWhere)) } };
         }
-        return this.alwaysFalse();
+        if (mode === 'none') {
+            return { [sourceRefField]: { notIn: await sourcesForTargets(await collectTargetPks(innerWhere)) } };
+        }
+        // every: exclude parents that link a target FAILING the predicate.
+        if (innerEmpty)
+            return {}; // every:{} ⇒ trivially true
+        const failing = await sourcesForTargets(await collectTargetPks({ NOT: innerWhere }));
+        return { [sourceRefField]: { notIn: failing } };
     }
     // -------------------------------------------------------------------------
     // Projection / order
@@ -433,7 +586,8 @@ class PowqlInterface {
             throw new errors_js_1.UnsupportedFeatureError('cursor pagination', 'PowDB', 'use limit/offset instead');
         }
         const params = [];
-        const where = this.buildWhere(args.where, params);
+        const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+        const where = this.buildWhere(resolvedWhere, params);
         const cols = this.projectedColumns(args.select, args.omit);
         const distinct = args.distinct?.length ? ' distinct' : '';
         const filter = where ? ` filter ${where}` : '';
@@ -500,7 +654,8 @@ class PowqlInterface {
             if (!rel)
                 throw new errors_js_1.ValidationError(`[turbine] Unknown relation "${relName}" on "${this.table}".`);
             if (rel.type === 'manyToMany') {
-                throw new errors_js_1.UnsupportedFeatureError('manyToMany nested reads', 'PowDB', `relation "${relName}" — junction loading is Phase B`);
+                await this.loadManyToMany(parents, rel, relName, opt, timeout);
+                continue;
             }
             const fk = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
             const rk = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
@@ -550,6 +705,95 @@ class PowqlInterface {
             }
         }
     }
+    /**
+     * manyToMany nested read — a three-hop batched loader (no `json_agg`/join
+     * pushdown): (1) read the junction rows for all parents in `sourceKey in (…)`
+     * chunks, (2) read the target rows for the collected `targetKey`s, (3) stitch
+     * each parent → its junction rows → its targets in memory. Mirrors the
+     * single-key N+1 loaders; the junction's source/target columns must be single
+     * (composite junction keys would need PowQL tuple-`in`, which it lacks).
+     */
+    async loadManyToMany(parents, rel, relName, opt, timeout) {
+        const through = rel.through;
+        if (!through)
+            throw new errors_js_1.ValidationError(`[turbine] manyToMany relation "${relName}" is missing its junction (\`through\`).`);
+        const sourceJ = (0, schema_js_1.normalizeKeyColumns)(through.sourceKey);
+        const targetJ = (0, schema_js_1.normalizeKeyColumns)(through.targetKey);
+        const sourceRef = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
+        const targetMeta = this.schema.tables[rel.to];
+        if (!targetMeta)
+            throw new errors_js_1.ValidationError(`[turbine] Relation "${relName}" targets unknown table "${rel.to}".`);
+        if (sourceJ.length > 1 || targetJ.length > 1 || sourceRef.length > 1 || targetMeta.primaryKey.length > 1) {
+            throw new errors_js_1.UnsupportedFeatureError('composite-key manyToMany', 'PowDB', `relation "${relName}" — PowQL has no tuple-\`in\`, so composite junction/target keys can't be loaded`);
+        }
+        const sourceJCol = sourceJ[0];
+        const targetJCol = targetJ[0];
+        const sourceRefCol = sourceRef[0];
+        const targetPkCol = targetMeta.primaryKey[0];
+        const parentRefField = this.meta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
+        const targetPkField = targetMeta.reverseColumnMap[targetPkCol] ?? targetPkCol;
+        const targetPkColMeta = targetMeta.columns.find((c) => c.name === targetPkCol);
+        const parentKeys = [
+            ...new Set(parents.map((p) => p[parentRefField]).filter((k) => k != null)),
+        ];
+        if (!parentKeys.length) {
+            for (const parent of parents)
+                parent[relName] = [];
+            return;
+        }
+        // (1) Junction rows: sourceKeyVal(String) → [targetKeyVal(String)].
+        const targetsBySource = new Map();
+        const allTargetVals = new Set();
+        for (let i = 0; i < parentKeys.length; i += MAX_RELATION_KEYS) {
+            const chunk = parentKeys.slice(i, i + MAX_RELATION_KEYS);
+            const params = [];
+            const placeholders = chunk.map((v) => this.param(v, params)).join(', ');
+            const powql = `${through.table} filter .${sourceJCol} in (${placeholders}) { .${sourceJCol}, .${targetJCol} }`;
+            const { rows } = await this.exec(powql, params, timeout);
+            for (const row of rows) {
+                const sv = String(row[sourceJCol]);
+                const tv = String(row[targetJCol]);
+                const bucket = targetsBySource.get(sv);
+                if (bucket)
+                    bucket.push(tv);
+                else
+                    targetsBySource.set(sv, [tv]);
+                allTargetVals.add(tv);
+            }
+        }
+        // (2) Target rows by PK, honouring the relation's own where/with/select/…
+        const options = (opt === true ? {} : opt);
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const targetByPk = new Map();
+        const targetValList = [...allTargetVals].map((v) => targetPkColMeta ? coerceScalar(v, targetPkColMeta.tsType) : v);
+        for (let i = 0; i < targetValList.length; i += MAX_RELATION_KEYS) {
+            const chunk = targetValList.slice(i, i + MAX_RELATION_KEYS);
+            const where = {
+                ...options.where,
+                [targetPkField]: { in: chunk },
+            };
+            const targets = (await targetQi.findMany({
+                ...options,
+                where,
+                with: options.with,
+                timeout: options.timeout ?? timeout,
+            }));
+            for (const t of targets)
+                targetByPk.set(String(t[targetPkField]), t);
+        }
+        // (3) Stitch: each parent → its junction targets (m2m is always a list).
+        for (const parent of parents) {
+            const sv = String(parent[parentRefField]);
+            const tvs = targetsBySource.get(sv) ?? [];
+            const children = [];
+            for (const tv of tvs) {
+                const child = targetByPk.get(tv);
+                if (child)
+                    children.push(child);
+            }
+            parent[relName] = children;
+        }
+    }
     // -------------------------------------------------------------------------
     // Writes (reselect — PowDB has no RETURNING)
     // -------------------------------------------------------------------------
@@ -560,19 +804,27 @@ class PowqlInterface {
             if (value === undefined)
                 continue;
             if (this.meta.relations[field]) {
-                throw new errors_js_1.UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}" in write data — Phase B`);
+                throw new errors_js_1.UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}" — nested writes need create()/update(), not createMany()/upsert()`);
             }
             out.push({ col: this.column(field), value });
         }
         return out;
     }
-    /** Fill in a client-generated UUID for a defaulted PK that wasn't supplied. */
+    /**
+     * Fill in a client-generated UUID for a defaulted **string** PK that wasn't
+     * supplied. A server-generated PK ({@link ColumnMetadata.isGenerated}, e.g. an
+     * `int` column with PowDB's `auto` modifier) is left untouched — PowDB assigns
+     * it and the trailing `returning` reads it back — as is any non-string PK.
+     */
     applyPkDefault(data) {
         const out = { ...data };
         for (const pk of this.meta.primaryKey) {
             const field = this.meta.reverseColumnMap[pk] ?? pk;
             const col = this.meta.columns.find((c) => c.name === pk);
-            if (out[field] == null && col?.hasDefault && col.tsType.replace(/\s*\|\s*null$/, '').trim() === 'string') {
+            if (out[field] == null &&
+                col?.hasDefault &&
+                !col.isGenerated &&
+                col.tsType.replace(/\s*\|\s*null$/, '').trim() === 'string') {
                 out[field] = (0, node_crypto_1.randomUUID)();
             }
         }
@@ -580,6 +832,9 @@ class PowqlInterface {
     }
     async create(args) {
         return this.withMiddleware('create', args, async () => {
+            if ((0, nested_write_js_1.hasRelationFields)(args.data, this.meta)) {
+                return this.nestedCreate(args);
+            }
             const data = this.applyPkDefault(args.data);
             const assigns = this.scalarData(data);
             const params = [];
@@ -609,8 +864,12 @@ class PowqlInterface {
     }
     async update(args) {
         return this.withMiddleware('update', args, async () => {
+            if ((0, nested_write_js_1.hasRelationFields)(args.data, this.meta)) {
+                return this.nestedUpdate(args);
+            }
             const params = [];
-            const where = this.buildWhere(args.where, params);
+            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const where = this.buildWhere(resolvedWhere, params);
             this.assertCompiledWhere(where, false, 'update');
             const setClause = this.buildUpdateAssignments(args.data, params);
             // `returning` hands back the post-update row(s); take the first (single-row contract).
@@ -624,7 +883,8 @@ class PowqlInterface {
     async updateMany(args) {
         return this.withMiddleware('updateMany', args, async () => {
             const params = [];
-            const where = this.buildWhere(args.where, params);
+            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const where = this.buildWhere(resolvedWhere, params);
             this.assertCompiledWhere(where, args.allowFullTableScan, 'updateMany');
             const setClause = this.buildUpdateAssignments(args.data, params);
             const filter = where ? ` filter ${where}` : '';
@@ -639,7 +899,7 @@ class PowqlInterface {
             if (value === undefined)
                 continue;
             if (this.meta.relations[field]) {
-                throw new errors_js_1.UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}" — Phase B`);
+                throw new errors_js_1.UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}" — nested writes need create()/update(), not updateMany()/upsert()`);
             }
             const colMeta = this.column(field);
             const ref = this.ref(field);
@@ -667,10 +927,75 @@ class PowqlInterface {
             throw new errors_js_1.ValidationError(`[turbine] update on "${this.table}" has no fields to set.`);
         return parts.join(', ');
     }
+    // -------------------------------------------------------------------------
+    // Nested writes — create/update whose `data` carries relation ops (create,
+    // connect, connectOrCreate, disconnect, set, delete, update, upsert). Reuses
+    // the engine-agnostic nested-write engine (it only needs ctx.schema + the
+    // table accessors PowqlInterface already provides). Runs as ONE flat top-level
+    // PowDB transaction — single global write lock, no savepoints, so the whole
+    // tree commits or rolls back together (mirrors the SQL path's coverage:
+    // hasMany / hasOne / belongsTo; manyToMany nested writes are not handled by
+    // the shared engine on any backend).
+    // -------------------------------------------------------------------------
+    isTxScoped() {
+        return this.options._txScoped === true;
+    }
+    async nestedCreate(args) {
+        const data = args.data;
+        if (this.isTxScoped()) {
+            return (0, nested_write_js_1.executeNestedCreate)(this.buildNestedCtx(), this.table, data);
+        }
+        return this.runInImplicitTx((ctx) => (0, nested_write_js_1.executeNestedCreate)(ctx, this.table, data));
+    }
+    async nestedUpdate(args) {
+        const data = args.data;
+        const where = args.where;
+        if (this.isTxScoped()) {
+            return (0, nested_write_js_1.executeNestedUpdate)(this.buildNestedCtx(), this.table, where, data);
+        }
+        return this.runInImplicitTx((ctx) => (0, nested_write_js_1.executeNestedUpdate)(ctx, this.table, where, data));
+    }
+    /** Open a flat PowDB transaction on a pinned connection and run `fn` inside it. */
+    async runInImplicitTx(fn) {
+        // Route tx keywords through the dialect (like the SQL path) so this never
+        // drifts from `powdbDialect`; falls back to the literal lowercase keywords.
+        const d = this.options.dialect;
+        const client = await this.pool.connect();
+        try {
+            await client.query(d?.beginStatement?.() ?? 'begin');
+            const { TransactionClient } = await Promise.resolve().then(() => __importStar(require('./client.js')));
+            const tx = new TransactionClient(client, this.schema, this.middlewares, this.options);
+            const ctx = { schema: this.schema, tx: tx };
+            const result = await fn(ctx);
+            await client.query(d?.commitStatement?.() ?? 'commit');
+            return result;
+        }
+        catch (err) {
+            try {
+                await client.query(d?.rollbackStatement?.() ?? 'rollback');
+            }
+            catch {
+                /* best-effort — the connection may be gone */
+            }
+            throw err;
+        }
+        finally {
+            client.release();
+        }
+    }
+    /** Already inside a transaction: build a context whose table accessors reuse the pinned pool. */
+    buildNestedCtx() {
+        const opts = { ...this.options, _txScoped: true };
+        const tx = {
+            table: (name) => new PowqlInterface(this.pool, name, this.schema, this.middlewares, opts),
+        };
+        return { schema: this.schema, tx: tx };
+    }
     async delete(args) {
         return this.withMiddleware('delete', args, async () => {
             const params = [];
-            const where = this.buildWhere(args.where, params);
+            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const where = this.buildWhere(resolvedWhere, params);
             this.assertCompiledWhere(where, false, 'delete');
             // `returning` hands back the deleted row(s) — no separate pre-image reselect needed.
             const { rows } = await this.exec(`${this.table} filter ${where} delete returning`, params, args.timeout);
@@ -683,7 +1008,8 @@ class PowqlInterface {
     async deleteMany(args) {
         return this.withMiddleware('deleteMany', args, async () => {
             const params = [];
-            const where = this.buildWhere(args.where, params);
+            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const where = this.buildWhere(resolvedWhere, params);
             this.assertCompiledWhere(where, args.allowFullTableScan, 'deleteMany');
             const filter = where ? ` filter ${where}` : '';
             const { rowCount } = await this.exec(`${this.table}${filter} delete`, params, args.timeout);
@@ -694,8 +1020,10 @@ class PowqlInterface {
         return this.withMiddleware('upsert', args, async () => {
             const createData = this.applyPkDefault(args.create);
             const pkCol = this.meta.primaryKey[0];
-            if (!pkCol || this.meta.primaryKey.length !== 1) {
-                throw new errors_js_1.UnsupportedFeatureError('composite-key upsert', 'PowDB', `table "${this.table}"`);
+            if (this.meta.primaryKey.length !== 1 || !pkCol) {
+                // PowQL's native `upsert … on .col` takes a single conflict column, so a
+                // composite PK falls back to an atomic reselect-or-write transaction.
+                return this.upsertComposite(createData, args.update);
             }
             const params = [];
             const createBody = this.scalarData(createData)
@@ -714,13 +1042,42 @@ class PowqlInterface {
             return row;
         });
     }
+    /**
+     * Composite-key upsert: PowQL's `upsert … on .col` only takes one conflict
+     * column, so reselect by the full composite PK and update-or-create inside one
+     * flat transaction (PowDB single-writer makes the read-then-write safe from
+     * concurrent writers; the transaction makes it atomic with the write).
+     */
+    async upsertComposite(createData, updateData) {
+        // Accept either the camelCase field or the snake_case column in `create`
+        // (create() resolves both), and key the where by field name.
+        const pkPairs = this.meta.primaryKey.map((pk) => {
+            const field = this.meta.reverseColumnMap[pk] ?? pk;
+            return { field, value: createData[field] ?? createData[pk] };
+        });
+        if (pkPairs.some((p) => p.value == null)) {
+            throw new errors_js_1.ValidationError(`[turbine] upsert on "${this.table}" needs every composite-PK field in \`create\` (${pkPairs
+                .map((p) => p.field)
+                .join(', ')}).`);
+        }
+        const pkWhere = Object.fromEntries(pkPairs.map((p) => [p.field, p.value]));
+        const run = async (ctx) => {
+            const tbl = ctx.tx.table(this.table);
+            const existing = await tbl.findUnique({ where: pkWhere });
+            return existing
+                ? (await tbl.update({ where: pkWhere, data: updateData }))
+                : (await tbl.create({ data: createData }));
+        };
+        return this.isTxScoped() ? run(this.buildNestedCtx()) : this.runInImplicitTx(run);
+    }
     // -------------------------------------------------------------------------
     // Aggregates
     // -------------------------------------------------------------------------
     async count(args = {}) {
         return this.withMiddleware('count', (args ?? {}), async () => {
             const params = [];
-            const where = this.buildWhere(args.where, params);
+            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const where = this.buildWhere(resolvedWhere, params);
             const filter = where ? ` filter ${where}` : '';
             const { rows } = await this.exec(`count(${this.table}${filter})`, params, args.timeout);
             return Number((rows[0]?.value ?? rows[0]?.count ?? 0));
@@ -731,7 +1088,8 @@ class PowqlInterface {
             // One scalar query per aggregate — PowDB's bare-projection aggregate is broken.
             const result = {};
             const filterParams = [];
-            const where = this.buildWhere(args.where, filterParams);
+            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const where = this.buildWhere(resolvedWhere, filterParams);
             const filter = where ? ` filter ${where}` : '';
             const scalar = async (expr) => {
                 const params = [...filterParams];
@@ -768,7 +1126,8 @@ class PowqlInterface {
     async groupBy(args) {
         return this.withMiddleware('groupBy', args, async () => {
             const params = [];
-            const where = this.buildWhere(args.where, params);
+            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const where = this.buildWhere(resolvedWhere, params);
             const filter = where ? ` filter ${where}` : '';
             const groupKeys = args.by.map((f) => this.ref(f));
             // Safe aliases — PowQL rejects reserved-word aliases (e.g. `count:`).

package/dist/generate.js

@@ -504,6 +504,10 @@ function serializeColumn(col) {
         `arrayType: '${escSQ(col.arrayType ?? col.pgArrayType)}'`,
         `pgArrayType: '${escSQ(col.pgArrayType)}'`,
     ];
+    // Emit isGenerated only when set (server-generated serial/identity), so the
+    // output stays byte-identical for the common client-default columns.
+    if (col.isGenerated)
+        parts.push(`isGenerated: true`);
     if (col.maxLength !== undefined)
         parts.push(`maxLength: ${col.maxLength}`);
     return `{ ${parts.join(', ')} }`;

package/dist/introspect.js

@@ -28,6 +28,7 @@ const SQL_COLUMNS = `
     data_type,
     is_nullable,
     column_default,
+    is_identity,
     ordinal_position,
     character_maximum_length
   FROM information_schema.columns
@@ -163,6 +164,11 @@ export async function introspectPostgresCatalog(options) {
                     pgTypeToTs(isArray ? dialectType : baseType, isNullable),
                 nullable: isNullable,
                 hasDefault: row.column_default !== null,
+                // Server-generated = a sequence default (serial/BIGSERIAL → nextval(…))
+                // or an IDENTITY column. Distinct from a client-side default expression
+                // (gen_random_uuid(), now()), which Turbine must still synthesize.
+                isGenerated: (typeof row.column_default === 'string' && row.column_default.includes('nextval(')) ||
+                    row.is_identity === 'YES',
                 isArray,
                 arrayType,
                 pgArrayType: arrayType,

package/dist/powdb.d.ts

@@ -150,7 +150,10 @@ export declare function powqlColumnType(col: ColumnMetadata): PowqlType;
  * Generate PowQL DDL (`type T { … }`) for every table in a schema. Used to
  * provision a PowDB database from a code-first `defineSchema`/`SchemaMetadata`
  * (PowDB has no migration runner yet). The primary key column is declared
- * `required unique`; non-nullable columns are `required`.
+ * `required unique`; non-nullable columns are `required`. A server-generated
+ * column ({@link ColumnMetadata.isGenerated}) that maps to PowQL `int` gets the
+ * `auto` modifier, so PowDB assigns a monotonic id on insert and Turbine stops
+ * synthesizing a client-side value for it.
  */
 export declare function powqlSchemaDDL(schema: SchemaMetadata): string[];
 /**