feat(sql-orm-client): nested updateAll, deleteAll and array returns in relation callbacks

docs/reference/error-reference.md

@@ -1014,17 +1014,13 @@ A mutation that expected the database to return a row got none: `create()`/`upse
 
 A valid ORM method was called in a configuration that does not support it: mutating an MTI variant collection with a method that requires `createAll()`, passing `onConflict: 'skip'` to `createAll()` on an MTI variant collection, Mongo `upsert()` with dot-path field operations, a Mongo `upsert()` whose `create` sets a field that has an update default and whose update pulls by a match document (that upsert runs as one update pipeline, which can pull only a single value), a Mongo mutation carrying windowing (`orderBy`/`offset`/`limit`) or includes, or `variant()` called on a collection that already has a variant selected (SQL and Mongo ORMs; call it on the base collection instead; `reason: 'variant-already-selected'`, with `variant` and `selectedValue` naming the selected variant model and its discriminator value). Payload: `method`, `model`, `reason`, `field`.
 
-### ORM.RELATION_LINK_DUPLICATE
-
-A `connect()` nested mutation violated a unique constraint on the junction table: the junction link is likely already present. The original driver error is preserved as `cause`. Payload: `relation`, `junction`.
-
 ### ORM.RELATION_MUTATION_INVALID
 
-A nested relation mutation's input is malformed: a relation field without a mutator callback or returning an invalid descriptor, `create` without data, `connect`/`disconnect` with a missing or empty criterion, duplicate connect criteria resolving to the same junction link, or conflicting values for a junction column. Payload: `kind`, `relation`, `model`, `problem`, `junction`, `column`.
+A nested relation mutation's input is malformed: a relation field without a mutator callback or returning an invalid descriptor, `create` without data or with a row that is not an object, `connect`/`disconnect` with a missing or empty criterion, conflicting values for a junction column, an array of operations that contains a nested array or a value that is not an operation, or `updateAll` data that sets the field linking the related row to its parent. Payload: `kind`, `relation`, `model`, `problem`, `junction`, `column`, `index`, `fields`.
 
 ### ORM.RELATION_MUTATION_UNSUPPORTED
 
-A nested relation mutation kind is not supported in this position: `disconnect()` outside `update()` nested mutations, or `create()`/`connect()` through a junction table with required columns the relation API cannot populate (`disconnect()` stays available). Payload: `kind`, `relation`.
+A nested relation mutation kind is not supported in this position: `disconnect()`, `updateAll()` or `deleteAll()` outside `update()` nested mutations, `updateAll()` or `deleteAll()` on a to-one relation, or `create()`/`connect()` through a junction table with required columns the relation API cannot populate (`disconnect()` stays available). Payload: `kind`, `relation`, `reason`.
 
 ### ORM.RELATION_ROW_MISSING
 

packages/3-extensions/sql-orm-client/README.md

@@ -164,6 +164,77 @@ The option needs the contract capability `insertOnConflictSkip`, and `insertOnCo
 
 The optional `configure` callback may still be passed in second position when there are no options.
 
+## Nested writes
+
+A relation field in `create()` or `update()` data takes a callback. The callback receives a mutator for that relation and returns the operation to apply to it.
+
+```ts
+await db.User.where({ id: 1 }).update({
+  name: 'Alice',
+  posts: (posts) => posts.create({ title: 'Hello' }),
+});
+```
+
+| Operation | Available in | Relations |
+| --- | --- | --- |
+| `r.create(data)` | `create()`, `update()` | all |
+| `r.connect(criteria)` | `create()`, `update()` | all |
+| `r.disconnect(criteria?)` | `update()` | all |
+| `r.where(w).updateAll(data)`, `r.updateAll(data)` | `update()` | to-many |
+| `r.where(w).deleteAll()`, `r.deleteAll()` | `update()` | to-many |
+
+Two restrictions apply on a many-to-many relation:
+
+- `r.disconnect()` without criteria is refused with `ORM.RELATION_MUTATION_INVALID`, and is a type error. Pass the criteria of the rows to disconnect.
+- `r.connect` does nothing for a row that is already linked when the junction table has a primary key or unique constraint over its link columns; without such a key it inserts another junction row.
+- `r.create` and `r.connect` are refused with `ORM.RELATION_MUTATION_UNSUPPORTED`, and are type errors, when the junction table has a column other than its link columns that is not nullable and has no default. `r.disconnect(criteria)` stays available.
+
+On a runtime that provides transactions, the parent write and its nested operations run in one transaction, so either all of them are applied or none is.
+
+### Updating and deleting related rows
+
+`updateAll` and `deleteAll` change or delete only rows related to the record being updated. On a one-to-many relation, a row is related when its foreign key equals that record's key. On a many-to-many relation, a row is related when the junction table has a row holding both that record's key and the row's key. A row that matches the filter but is related only to another record is not changed. A row related to this record and also to other records is changed.
+
+```ts
+await db.User.where({ id: 1 }).update({
+  posts: (posts) => posts.where({ published: false }).updateAll({ published: true }),
+});
+
+await db.User.where({ id: 1 }).update({
+  posts: (posts) => posts.where((post) => post.title.like('Draft%')).deleteAll(),
+});
+```
+
+`where` takes the same inputs as a collection's `where`: a callback over the related model, a field/value object, or an expression. Chained `where` calls combine with AND.
+
+Unlike a collection's `updateAll` and `deleteAll`, the nested forms do not require `where`. Without it they apply to every related row:
+
+```ts
+await db.User.where({ id: 1 }).update({
+  posts: (posts) => posts.deleteAll(),
+});
+```
+
+`updateAll` data is the related model's own fields. It cannot set the foreign-key field that refers to the parent; that is refused with `ORM.RELATION_MUTATION_INVALID`. `updateAll` with no fields to set changes no rows. It is not an error when no row matches.
+
+Both operations are refused with `ORM.RELATION_MUTATION_UNSUPPORTED` inside `create()` and on a to-one relation. With an emitted `contract.d.ts` these are also type errors.
+
+On a many-to-many relation, `deleteAll` deletes the related rows and does not delete or change junction rows itself. What happens to their junction rows is decided by the foreign-key action in your schema: with a cascading foreign key they are removed, and with a restricting one the database refuses the delete and the whole `update()` is rolled back. When the junction table has no foreign key to the related table, `deleteAll` deletes the related rows and their junction rows remain, holding keys of rows that no longer exist. Declare a foreign key with a cascading delete on the junction table so that the junction rows are removed with the rows they refer to.
+
+### Several operations on one relation
+
+A callback may return an array of operations. They are applied in array order, each after the previous one has been written. An empty array applies no operation.
+
+```ts
+await db.User.where({ id: 1 }).update({
+  posts: (posts) => [
+    posts.where({ published: false }).deleteAll(),
+    posts.create({ title: 'Fresh start' }),
+    posts.updateAll({ featured: false }),
+  ],
+});
+```
+
 ## Prepared row descriptions
 
 Built-in collection chains expose terminal-only `.prepared.all(configure?)`, `.prepared.first(filter?, configure?)` and `.prepared.firstOrThrow(filter?, configure?)` views. They synchronously return a `Preparable<DbRow, Result>` without executing it: a description containing a SQL `plan` and a required `consume` function. The description is not itself a `SqlQueryPlan`. Filters, projection, includes, variants, first-row limit replacement and read annotations use the ordinary row pipeline.

packages/3-extensions/sql-orm-client/package.json

@@ -22,7 +22,6 @@
     "@internal/framework-components": "workspace:8.0.0-rc.17",
     "@internal/operations": "workspace:8.0.0-rc.17",
     "@internal/sql-contract": "workspace:8.0.0-rc.17",
-    "@internal/sql-errors": "workspace:8.0.0-rc.17",
     "@internal/sql-operations": "workspace:8.0.0-rc.17",
     "@internal/sql-relational-core": "workspace:8.0.0-rc.17",
     "@internal/sql-runtime": "workspace:8.0.0-rc.17",
@@ -35,6 +34,7 @@
     "@internal/family-sql": "workspace:8.0.0-rc.17",
     "@internal/ids": "workspace:8.0.0-rc.17",
     "@internal/sql-contract-ts": "workspace:8.0.0-rc.17",
+    "@internal/sql-errors": "workspace:8.0.0-rc.17",
     "@internal/target-postgres": "workspace:8.0.0-rc.17",
     "@repo/test-utils": "workspace:8.0.0-rc.17",
     "@repo/tsconfig": "workspace:8.0.0-rc.17",

packages/3-extensions/sql-orm-client/src/collection-contract.ts

@@ -250,6 +250,16 @@ export function getColumnToFieldMap(
   return cached;
 }
 
+export function resolveColumnToField(
+  contract: Contract<SqlStorage>,
+  namespaceId: string,
+  modelName: string,
+  columnName: string,
+): string {
+  const columnToField = getColumnToFieldMap(contract, namespaceId, modelName);
+  return columnToField[columnName] ?? columnName;
+}
+
 const completeColumnToFieldCache = new WeakMap<object, Map<string, Record<string, string>>>();
 
 /**
@@ -278,11 +288,11 @@ export function getCompleteColumnToFieldMap(
   return cached;
 }
 
-interface ResolvedThrough extends ContractRelationThrough {
+export interface ResolvedThrough extends ContractRelationThrough {
   readonly requiredPayloadColumns: readonly string[];
 }
 
-interface ResolvedRelation {
+export interface ResolvedRelation {
   readonly to: string;
   readonly toNamespace: string;
   readonly cardinality: RelationCardinalityTag | undefined;
@@ -580,6 +590,25 @@ export function resolveRowIdentityColumns(
   return [];
 }
 
+export function hasUniqueKeyOverColumns(
+  contract: Contract<SqlStorage>,
+  namespaceId: string,
+  tableName: string,
+  columns: readonly string[],
+): boolean {
+  const table = resolveTableForContract(contract, namespaceId, tableName)?.table;
+  if (table === undefined) {
+    return false;
+  }
+  const wanted = new Set(columns);
+  return [table.primaryKey, ...table.uniques].some(
+    (key) =>
+      key !== undefined &&
+      key.columns.length === wanted.size &&
+      key.columns.every((column) => wanted.has(column)),
+  );
+}
+
 export function assertReturningCapability(contract: Contract<SqlStorage>, action: string): void {
   if (hasContractCapability(contract, 'returning')) {
     return;