turbine-orm 0.81.0 → 0.90.0

package/dist/nested-write.d.ts

@@ -77,6 +77,9 @@ export interface NestedWriteContext {
                 where: Record<string, unknown>;
                 with?: Record<string, unknown>;
             }): Promise<T | null>;
+            findFirst(args: {
+                where: Record<string, unknown>;
+            }): Promise<T | null>;
         };
     };
 }

package/dist/nested-write.js

@@ -13,6 +13,8 @@
  */
 import { CircularRelationError, describeTargetForMessage, NotFoundError, RelationError, UnsupportedFeatureError, ValidationError, } from './errors.js';
 import { markInternalRowSelector } from './query/compound-unique.js';
+import { resolveExcludedFromCreate } from './query/expr.js';
+import { isPlainRecord, setOwn } from './query/filters.js';
 import { markInternalCombinator, resolveColumnName } from './query/utils.js';
 import { normalizeKeyColumns } from './schema.js';
 const MAX_DEPTH = 10;
@@ -42,7 +44,7 @@ export function extractRelationFields(data, tableMeta) {
             relations[key] = value;
         }
         else {
-            scalars[key] = value;
+            setOwn(scalars, key, value);
         }
     }
     return { scalars, relations };
@@ -208,32 +210,73 @@ function toArray(value) {
 function keyOf(value) {
     return String(value);
 }
+/** The operations that point a to-one relation's foreign key at a row: at most one per write. */
+const BELONGS_TO_POINTER_OPS = ['create', 'connect', 'connectOrCreate', 'disconnect', 'delete'];
 /**
  * Validate that all operation keys in a nested write are recognized and
- * allowed for the current context (create vs update).
+ * allowed for the current context (create vs update) and relation.
+ *
+ * A belongsTo relation is one row the parent points at, so it takes Prisma's
+ * to-one operations: no `set` (a to-many operation), and at most one of the
+ * operations that decide what the parent points at, since one write cannot
+ * honor two. An operation whose value is `undefined` is absent, as everywhere
+ * else in a query; only its name is still checked, so a misspelled operation
+ * is reported whatever it holds.
  */
-function validateOps(relationName, ops, isUpdate) {
+function validateOps(relationName, ops, isUpdate, rel) {
+    const belongsTo = rel?.type === 'belongsTo';
     for (const opName of Object.keys(ops)) {
+        const absent = ops[opName] === undefined;
         if (!CREATE_ONLY_OPS.has(opName) && !UPDATE_ONLY_OPS.has(opName)) {
+            const updateOps = belongsTo
+                ? ', disconnect, delete, update, upsert'
+                : ', disconnect, set, delete, update, upsert';
             throw new ValidationError(`Unknown nested write operation "${opName}" on relation "${relationName}". ` +
-                `Valid operations: create, connect, connectOrCreate${isUpdate ? ', disconnect, set, delete, update, upsert' : ''}.`);
+                `Valid operations: create, connect, connectOrCreate${isUpdate ? updateOps : ''}.`);
         }
+        if (absent)
+            continue;
         if (!isUpdate && UPDATE_ONLY_OPS.has(opName)) {
             throw new ValidationError(`Operation "${opName}" on relation "${relationName}" is only valid inside update(), not create().`);
         }
+        if (belongsTo && opName === 'set') {
+            throw new ValidationError(`Nested set on "${relationName}" is not supported: "${relationName}" is a single "${rel.to}" row this ` +
+                `record points at, and set replaces a to-many list. Use connect to point at a different "${rel.to}", ` +
+                'or disconnect to clear it.');
+        }
+    }
+    if (belongsTo) {
+        const given = BELONGS_TO_POINTER_OPS.filter((op) => ops[op] !== undefined && ops[op] !== false);
+        if (given.length > 1) {
+            throw new ValidationError(`Nested write on "${relationName}" combines ${given.join(' and ')}. "${relationName}" is a single ` +
+                `"${rel.to}" row, so one write can create, connect, connectOrCreate, disconnect or delete it, not ` +
+                'several. Split the write in two if both are intended.');
+        }
     }
 }
+/**
+ * The single item a to-one operation names. A one-element array is accepted
+ * for compatibility; an empty or longer one is refused, since only one row can
+ * be pointed at and keeping one of several would drop the rest silently.
+ */
+function singleToOneItem(value, op, relName, rel) {
+    if (!Array.isArray(value))
+        return value;
+    if (value.length === 1)
+        return value[0];
+    throw new ValidationError(`Nested ${op} on "${relName}" received ${value.length} items, but "${relName}" is a single "${rel.to}" ` +
+        `row. Pass one object, for example \`${op}: { ... }\`.`);
+}
 /**
  * The `with` clause that reads back the tree a nested write just wrote.
  *
  * Built from the DATA, recursively: a relation whose payload itself contains
  * relation writes is requested as `{ rel: { with: { ... } } }` rather than
- * `{ rel: true }`. It used to be the top-level keys alone, so a depth-3 create
- * wrote all three levels and returned an object whose grandchildren were
- * missing entirely, which a caller reads as "there are none".
+ * `{ rel: true }`. Requesting the top-level keys alone would return a depth-3
+ * create without its grandchildren, which a caller reads as "there are none".
  *
  * Only relations that were actually WRITTEN are requested, so a create with no
- * nested data still reads back exactly what it did before. The walk is capped
+ * nested data reads back just the row. The walk is capped
  * at {@link MAX_DEPTH}, the cap the write walk itself uses, and the builder's
  * own relation-depth guard is the backstop below that.
  */
@@ -278,10 +321,6 @@ function readBackWith(schema, tableName, relations, depth = 0) {
     }
     return Object.keys(clause).length > 0 ? clause : undefined;
 }
-/** A plain object (not an array, Date or null), the shape nested payloads take. */
-function isPlainRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date);
-}
 /**
  * Build a PK-based where clause from a parent row and its table metadata.
  */
@@ -813,6 +852,17 @@ function notRelatedToParent(op, relName, rel, target) {
             `or it belongs to a different parent (a nested ${op} can only touch this parent's rows).`,
     });
 }
+/** A belongsTo `delete` (or a `disconnect` naming fields) on a parent whose foreign key is NULL. */
+function nothingConnected(op, relName, rel, target) {
+    return new NotFoundError({
+        table: rel.to,
+        where: target,
+        operation: `nested ${op}`,
+        message: `Nested ${op} on relation "${relName}": nothing is connected (this record's foreign key to "${rel.to}" ` +
+            `is NULL), so there is no "${rel.to}" row to ${op}.` +
+            (op === 'disconnect' ? ' Use `disconnect: true` to clear the relation whatever it points at.' : ''),
+    });
+}
 /** Re-tag a NotFoundError from a scoped child write as a relation-scoped miss. */
 function rethrowAsNotRelated(err, op, relName, rel, target) {
     if (err instanceof NotFoundError) {
@@ -844,7 +894,7 @@ export async function executeNestedCreate(ctx, tableName, data, depth = 0, path
             throw new RelationError(`Unknown relation "${relName}" on table "${tableName}". ` +
                 `Available relations: ${Object.keys(tableMeta.relations).join(', ') || '(none)'}.`);
         }
-        validateOps(relName, ops, false);
+        validateOps(relName, ops, false, rel);
     }
     // belongsTo relations put the foreign key on the PARENT row, so they must be
     // resolved BEFORE the parent is inserted, otherwise a NOT NULL FK column
@@ -922,7 +972,7 @@ export async function executeNestedUpdate(ctx, tableName, where, data, depth = 0
             throw new RelationError(`Unknown relation "${relName}" on table "${tableName}". ` +
                 `Available relations: ${Object.keys(tableMeta.relations).join(', ') || '(none)'}.`);
         }
-        validateOps(relName, ops, true);
+        validateOps(relName, ops, true, rel);
     }
     // Update parent row with scalar data (may be empty if only relation ops)
     let parentRow;
@@ -972,25 +1022,11 @@ export async function executeNestedUpdate(ctx, tableName, where, data, depth = 0
             if (ops.upsert !== undefined) {
                 await processBelongsToUpsert(ctx, rel, ops.upsert, parentRow, tableName);
             }
-            if (ops.disconnect !== undefined) {
-                // For belongsTo disconnect, null out the FK on the parent
-                const fks = normalizeKeyColumns(rel.foreignKey);
-                const nullable = fks.every((fk) => {
-                    const col = tableMeta.columns.find((c) => c.name === fk);
-                    return col?.nullable ?? false;
-                });
-                if (!nullable) {
-                    throw new ValidationError(`Cannot disconnect "${relName}": foreign key column(s) ${fks.join(', ')} are NOT NULL. Use delete instead.`);
-                }
-                const updateData = {};
-                for (const fk of fks) {
-                    const field = tableMeta.reverseColumnMap[fk] ?? fk;
-                    updateData[field] = null;
-                }
-                await ctx.tx.table(tableName).update({
-                    where: pkWhere(tableMeta, parentRow),
-                    data: updateData,
-                });
+            if (ops.disconnect !== undefined && ops.disconnect !== false) {
+                await processBelongsToDisconnect(ctx, rel, ops.disconnect, relName, parentRow, tableName, 'disconnect');
+            }
+            if (ops.delete !== undefined && ops.delete !== false) {
+                await processBelongsToDisconnect(ctx, rel, ops.delete, relName, parentRow, tableName, 'delete');
             }
         }
         else {
@@ -1069,93 +1105,107 @@ async function processHasManyCreate(ctx, rel, ops, parentRow, depth, path, relNa
  * which UPDATEs the FK after the parent already exists.)
  */
 async function resolveBelongsToForCreate(ctx, rel, ops, parentTable, depth, path, relName) {
-    const fks = normalizeKeyColumns(rel.foreignKey);
-    const refs = normalizeKeyColumns(rel.referenceKey);
-    const parentMeta = ctx.schema.tables[parentTable];
-    const relatedTable = ctx.schema.tables[rel.to];
-    let relatedRow = null;
+    const relatedRow = await resolveBelongsToTarget(ctx, rel, ops, depth, path, relName);
+    return relatedRow ? belongsToKeyData(ctx, rel, parentTable, relatedRow) : {};
+}
+/**
+ * The row a belongsTo create / connect / connectOrCreate points the parent at,
+ * or null when the write names none of the three. Shared by the create path
+ * (which folds the key into the parent INSERT) and the update path (which
+ * UPDATEs the parent's key), so the two cannot disagree about any of them.
+ */
+async function resolveBelongsToTarget(ctx, rel, ops, depth, path, relName) {
     if (ops.create !== undefined) {
-        const items = toArray(ops.create);
-        if (items.length > 0) {
-            relatedRow = (await executeNestedCreate(ctx, rel.to, items[0], depth + 1, [...path, relName]));
-        }
+        const item = singleToOneItem(ops.create, 'create', relName, rel);
+        return (await executeNestedCreate(ctx, rel.to, item, depth + 1, [...path, relName]));
     }
-    else if (ops.connect !== undefined) {
-        const items = toArray(ops.connect);
-        if (items.length > 0) {
-            const target = items[0];
-            relatedRow = (await ctx.tx.table(rel.to).findUnique({ where: target }));
-            if (!relatedRow) {
-                throw new ValidationError(`connect on "${relName}": no ${rel.to} row found matching ${describeTargetForMessage(target)}.`);
-            }
-        }
-    }
-    else if (ops.connectOrCreate !== undefined) {
-        const items = toArray(ops.connectOrCreate);
-        if (items.length > 0) {
-            const op = items[0];
-            relatedRow = (await ctx.tx.table(rel.to).findUnique({ where: op.where }));
-            if (!relatedRow) {
-                // For belongsTo the FK lives on the parent, so the related row is
-                // created plainly (no FK injection) and we read its reference key.
-                relatedRow = (await ctx.tx.table(rel.to).create({ data: op.create }));
-            }
+    if (ops.connect !== undefined) {
+        const target = singleToOneItem(ops.connect, 'connect', relName, rel);
+        const found = (await ctx.tx.table(rel.to).findUnique({ where: target }));
+        if (!found) {
+            throw new ValidationError(`connect on "${relName}": no ${rel.to} row found matching ${describeTargetForMessage(target)}.`);
         }
+        return found;
     }
-    const fkScalars = {};
-    if (relatedRow) {
-        for (let i = 0; i < fks.length; i++) {
-            const fkField = parentMeta.reverseColumnMap[fks[i]] ?? fks[i];
-            const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
-            fkScalars[fkField] = relatedRow[refField];
+    if (ops.connectOrCreate !== undefined) {
+        const op = singleToOneItem(ops.connectOrCreate, 'connectOrCreate', relName, rel);
+        if (!isPlainRecord(op?.where) || !isPlainRecord(op?.create)) {
+            throw new ValidationError(`Nested connectOrCreate on "${relName}" requires "where" and "create" fields.`);
         }
+        const found = (await ctx.tx.table(rel.to).findUnique({ where: op.where }));
+        // For belongsTo the FK lives on the parent, so the related row is created
+        // plainly (no FK injection) and its reference key is read back.
+        return found ?? (await ctx.tx.table(rel.to).create({ data: op.create }));
     }
-    return fkScalars;
+    return null;
 }
-async function processBelongsToCreate(ctx, rel, ops, parentRow, parentTable, depth, path, relName) {
+/** The parent's own field values that point it at `relatedRow`. */
+function belongsToKeyData(ctx, rel, parentTable, relatedRow) {
     const fks = normalizeKeyColumns(rel.foreignKey);
     const refs = normalizeKeyColumns(rel.referenceKey);
-    // create, insert the related row, then update parent's FK
-    if (ops.create !== undefined) {
-        const items = toArray(ops.create);
-        if (items.length > 0) {
-            const relatedRow = (await executeNestedCreate(ctx, rel.to, items[0], depth + 1, [...path, relName]));
-            const updateData = {};
-            const relatedTable = ctx.schema.tables[rel.to];
-            for (let i = 0; i < fks.length; i++) {
-                const fkField = ctx.schema.tables[parentTable]?.reverseColumnMap[fks[i]] ?? fks[i];
-                const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
-                updateData[fkField] = relatedRow[refField];
-            }
-            const parentMeta = ctx.schema.tables[parentTable];
-            await ctx.tx.table(parentTable).update({
-                where: pkWhere(parentMeta, parentRow),
-                data: updateData,
-            });
-        }
+    const parentMeta = ctx.schema.tables[parentTable];
+    const relatedTable = ctx.schema.tables[rel.to];
+    const data = {};
+    for (let i = 0; i < fks.length; i++) {
+        const fkField = parentMeta?.reverseColumnMap[fks[i]] ?? fks[i];
+        const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
+        data[fkField] = relatedRow === null ? null : relatedRow[refField];
     }
-    // connect, validate existence, update parent's FK
-    if (ops.connect !== undefined) {
-        const items = toArray(ops.connect);
-        if (items.length > 0) {
-            const target = items[0];
-            const existing = await ctx.tx.table(rel.to).findUnique({ where: target });
-            if (!existing) {
-                throw new ValidationError(`connect on "${relName}": no ${rel.to} row found matching ${describeTargetForMessage(target)}.`);
-            }
-            const updateData = {};
-            const relatedTable = ctx.schema.tables[rel.to];
-            for (let i = 0; i < fks.length; i++) {
-                const fkField = ctx.schema.tables[parentTable]?.reverseColumnMap[fks[i]] ?? fks[i];
-                const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
-                updateData[fkField] = existing[refField];
-            }
-            const parentMeta = ctx.schema.tables[parentTable];
-            await ctx.tx.table(parentTable).update({
-                where: pkWhere(parentMeta, parentRow),
-                data: updateData,
-            });
-        }
+    return data;
+}
+/** Update path: create / connect / connectOrCreate the related row, then point the parent at it. */
+async function processBelongsToCreate(ctx, rel, ops, parentRow, parentTable, depth, path, relName) {
+    const relatedRow = await resolveBelongsToTarget(ctx, rel, ops, depth, path, relName);
+    if (!relatedRow)
+        return;
+    await ctx.tx.table(parentTable).update({
+        where: pkWhere(ctx.schema.tables[parentTable], parentRow),
+        data: belongsToKeyData(ctx, rel, parentTable, relatedRow),
+    });
+}
+/**
+ * `disconnect` / `delete` on a belongsTo relation, with Prisma's semantics:
+ * both clear the parent's foreign key, and `delete` then deletes the row it
+ * pointed at. `true` (or `{}`) means the connected row; an object with fields
+ * additionally requires the connected row to match it. Both need a nullable
+ * foreign key: with a NOT NULL one the parent cannot exist pointing at nothing.
+ *
+ * `disconnect: true` when nothing is connected is a no-op: the parent already
+ * points at nothing, which is what was asked. A `delete`, or a `disconnect`
+ * that names fields, asks about a row that is not there, so it is E001.
+ */
+async function processBelongsToDisconnect(ctx, rel, arg, relName, parentRow, parentTable, op) {
+    const parentMeta = ctx.schema.tables[parentTable];
+    const fks = normalizeKeyColumns(rel.foreignKey);
+    const nullable = fks.every((fk) => parentMeta.columns.find((c) => c.name === fk)?.nullable ?? false);
+    if (!nullable) {
+        throw new ValidationError(`Cannot ${op} "${relName}": foreign key column(s) ${fks.join(', ')} on "${parentTable}" are NOT NULL, so ` +
+            `every "${parentTable}" row must point at a "${rel.to}". Connect it to a different "${rel.to}" instead` +
+            `${op === 'delete' ? `, or delete the "${rel.to}" row directly once nothing points at it` : ''}.`);
+    }
+    const item = singleToOneItem(arg, op, relName, rel);
+    // `{}` is the documented to-one spelling of `true` (the connected row). An
+    // object whose keys are all undefined is still refused below: that is the
+    // shape of a missing request field, not a choice.
+    const target = isPlainRecord(item) && Object.keys(item).length === 0 ? true : item;
+    assertTargetSelectsSomething(target, op, relName, rel);
+    const correlation = belongsToCorrelationWhere(ctx, rel, parentRow, parentTable);
+    if (!correlation) {
+        if (op === 'disconnect' && target === true)
+            return;
+        throw nothingConnected(op, relName, rel, target);
+    }
+    const related = (await ctx.tx.table(rel.to).findFirst({ where: scopeWhereToParent(target, correlation) }));
+    if (!related)
+        throw notRelatedToParent(op, relName, rel, target);
+    await ctx.tx.table(parentTable).update({
+        where: pkWhere(parentMeta, parentRow),
+        data: belongsToKeyData(ctx, rel, parentTable, null),
+    });
+    if (op === 'delete') {
+        // Any other row still pointing at it makes this a foreign-key violation
+        // (E009), which rolls the whole write back.
+        await ctx.tx.table(rel.to).delete({ where: pkWhere(ctx.schema.tables[rel.to], related) });
     }
 }
 // ---------------------------------------------------------------------------
@@ -1366,11 +1416,12 @@ async function processNestedUpsert(ctx, rel, upsertArg, parentRow, relName) {
             throw new ValidationError(`Nested upsert on "${rel.name}" requires "where", "create", and "update" fields.`);
         }
         assertTargetSelectsSomething(item.where, 'upsert', relName, rel);
+        const update = upsertUpdateData(ctx, rel, item);
         const scoped = correlation ? scopeWhereToParent(item.where, correlation) : null;
         const existing = scoped ? await ctx.tx.table(rel.to).findUnique({ where: scoped }) : null;
         if (existing && scoped) {
             try {
-                await ctx.tx.table(rel.to).update({ where: scoped, data: item.update });
+                await ctx.tx.table(rel.to).update({ where: scoped, data: update });
             }
             catch (err) {
                 rethrowAsNotRelated(err, 'upsert', relName, rel, item.where);
@@ -1382,6 +1433,19 @@ async function processNestedUpsert(ctx, rel, upsertArg, parentRow, relName) {
         }
     }
 }
+/**
+ * A nested upsert's `update`, with each `expr.excluded(f)` resolved to the
+ * value its `create` supplies: the incoming row of a one-row upsert is
+ * `create`, as it is for a top-level `upsert()`. Resolved before the lookup,
+ * so a reference `create` cannot satisfy is refused whether or not the row
+ * exists.
+ */
+function upsertUpdateData(ctx, rel, item) {
+    const tableMeta = ctx.schema.tables[rel.to];
+    if (!tableMeta)
+        return item.update;
+    return resolveExcludedFromCreate({ table: rel.to, tableMeta }, item.update, item.create) ?? item.update;
+}
 async function processBelongsToUpdate(ctx, rel, updateArg, parentRow, parentTable) {
     const item = updateArg;
     if (!item.data) {
@@ -1420,6 +1484,7 @@ async function processBelongsToUpsert(ctx, rel, upsertArg, parentRow, parentTabl
     // hasMany/hasOne nested upsert makes: an upsert whose target is out of the
     // relation creates a row owned by this parent rather than rewriting a
     // stranger's.
+    const update = upsertUpdateData(ctx, rel, item);
     const correlation = belongsToCorrelationWhere(ctx, rel, parentRow, parentTable);
     // findMany, not findUnique: the scoped where ANDs a non-unique-looking
     // correlation onto the caller's selector. The correlation targets the
@@ -1434,7 +1499,7 @@ async function processBelongsToUpsert(ctx, rel, upsertArg, parentRow, parentTabl
         : null;
     if (existing) {
         const relatedMeta = ctx.schema.tables[rel.to];
-        await ctx.tx.table(rel.to).update({ where: pkWhere(relatedMeta, existing), data: item.update });
+        await ctx.tx.table(rel.to).update({ where: pkWhere(relatedMeta, existing), data: update });
     }
     else {
         // Create the related row, then update parent's FK to point at it

package/dist/pipeline-submittable.d.ts

@@ -65,11 +65,23 @@ export interface PipelineRunOptions {
      * Whether to wrap the pipeline in BEGIN/COMMIT (default: true).
      * When true, all queries execute atomically. On error, ROLLBACK is sent.
      * When false, each query gets its own Sync message for error isolation.
+     *
+     * A transactional batch that may write holds its COMMIT until every
+     * query's transform has run, so a transform that throws (a `...OrThrow`
+     * miss, an optimistic-lock conflict) rolls the writes back instead of
+     * rejecting after they committed. That costs a second round trip; a batch
+     * of plain SELECTs has nothing to undo and keeps the single one.
      */
     transactional?: boolean;
     /** Timeout in milliseconds. If exceeded, the connection is destroyed. */
     timeout?: number;
 }
+/**
+ * Whether a transactional batch must hold its COMMIT until the transforms have
+ * run. Anything that is not a plain SELECT counts as a write, so a statement
+ * this cannot classify costs a round trip rather than correctness.
+ */
+export declare function batchMayWrite(queries: readonly DeferredQuery<unknown>[]): boolean;
 /**
  * Execute multiple queries using the Postgres extended-query pipeline protocol.
  *