@vantreeseba/drizzle-graphql 7.6.0 → 7.8.0

package/README.md

@@ -362,6 +362,81 @@ const { schema } = buildSchema(db, {
 
 Return `undefined` for any table that should keep its default naming.
 
+## Soft delete
+
+`softDelete` turns a table's `delete` mutation into an UPDATE that marks the row, and hides
+marked rows from every read:
+
+```Typescript
+const { schema } = buildSchema(db, {
+    softDelete: {
+        posts: 'deletedAt',
+        // The NOT NULL form has to spell out both values:
+        flags: { column: 'isArchived', deletedValue: true, restoredValue: false },
+    },
+})
+```
+
+Keyed by the **Drizzle schema key**, like `scope` and `exclude`. A function form is also
+accepted, for a convention applied across the schema:
+
+```Typescript
+softDelete: (table, tableName) => ('deletedAt' in getTableColumns(table) ? 'deletedAt' : undefined)
+```
+
+What a declared table gets:
+
+| Path | Effect |
+| --- | --- |
+| `deletePosts`, `deletePostsSingle` | UPDATE that writes the marker; returns the rows as they now stand |
+| `restorePosts`, `restorePostsSingle` | the inverse — matches **only** marked rows and clears the marker |
+| `posts`, `postsSingle`, cursor pages | marked rows are not returned |
+| `postsAggregate`, `postsGroupBy` | counted over unmarked rows only |
+| `user.posts`, `user.postsAggregate` | hidden on both the batched and the eager (`with:`) path |
+| `updatePosts`, `updatePostsMany`, a second `deletePosts` | a marked row is simply not matched |
+| nested `connect` / `disconnect` / `set` | a marked row cannot be attached or detached |
+| `CreatePostsInput`, `UpdatePostsInput` | the marker column is **removed** — only the mutations write it |
+
+Every read path also gains a `deleted` argument for the cases the default hides:
+
+```graphql
+{
+    live: posts { id }                      # the default — EXCLUDE
+    trash: posts(deleted: ONLY) { id }      # the trash view, no second field needed
+    all: posts(deleted: INCLUDE) { id }
+}
+```
+
+The marker column stays **readable and filterable** — it is only the write inputs that lose it,
+the same trade `contextValues` makes.
+
+Defaults come from the column's type: `new Date()` for a timestamp, an ISO string for text,
+`Date.now()` for a number, `true` for a boolean. A NOT NULL column has no "absent" state, so
+the predicate has to compare against a constant: any NOT NULL column other than a boolean must
+give `deletedValue` (a constant, not a function) and `restoredValue`, or the build throws.
+
+Three things it deliberately does not do:
+
+-   **It does not cascade.** Marking a post does not mark its comments. A comment whose post is
+    marked is still returned by `comments`; its `post` field resolves to `null`. Declare the
+    child table too if that is not what you want.
+-   **It does not free the row's unique keys.** A marked row still occupies its primary key and
+    every unique index, so inserting a new row with the same natural key fails the constraint.
+    A partial unique index (`WHERE deleted_at IS NULL`) is the usual answer.
+-   **It does not refuse.** Like `scope`, an unreachable row answers the same as a row that does
+    not exist.
+
+The soft-delete predicate is ANDed **before** a `scope` predicate, both after the client's
+`where` — so a scope still confines what `deleted: INCLUDE` can reach.
+
+> **MySQL caveat.** `ON DUPLICATE KEY UPDATE` takes no predicate, so an upsert whose conflict
+> target hits a marked row updates it — reviving it — rather than leaving it alone. On
+> PostgreSQL and SQLite the conflict branch carries the predicate and updates nothing.
+
+A table with no declaration keeps a real `DELETE`, gets no `restore` mutation and no `deleted`
+argument, and a build with no `softDelete` at all emits exactly the SQL it did before.
+
+
 ## Scalars
 
 Columns whose values don't fit a built-in GraphQL scalar get a named custom scalar, so the
@@ -1055,12 +1130,46 @@ mutation {
     `author: { create: … }` available, `authorId` is one of two ways to supply it
 -   Nesting is one level deep: the row a nested `create` inserts takes columns only, and the
     join column is left off, since the write it is part of sets it
--   Many-to-many (`.through()`) relations are not written through
+-   Many-to-many (`.through()`) relations are written through their junction table — see
+    below
 -   The whole tree runs in one transaction — a savepoint when the request already carries one
     — so a failure anywhere leaves nothing behind
 -   A `set` that carries only relation fields is a valid update: it changes what the row is
     attached to without rewriting the row
 
+### Many-to-many relations
+
+A relation declared with `.through()` is written by inserting and deleting rows of its
+junction table, so nothing about the two rows being linked changes:
+
+```graphql
+mutation {
+    updatePostsSingle(
+        where: { id: { eq: 1 } }
+        set: { tags: { set: [{ name: { inArray: ["news", "release"] } }] } }
+    ) {
+        id
+    }
+}
+```
+
+-   It offers `connect` on the create input, and `connect`, `disconnect` and `set` on the
+    update input. All three take the target's `Filters`, exactly as on a foreign-key relation
+-   `disconnect` and `set` are offered unconditionally here: unlinking deletes a junction row
+    rather than writing `NULL` into a column that might be `NOT NULL`
+-   `connect` links every row its filters match and leaves already-linked rows alone, so
+    re-connecting is a no-op rather than a unique-constraint error
+-   `disconnect` deletes only the links, never the rows they pointed at
+-   `set: []` unlinks everything and links nothing back, which is how a many-to-many relation
+    is cleared
+-   There is no `create`: inserting a row *and* linking it is a write to two tables, and the
+    link is what the relation field is for. Create the row with its own mutation, then
+    `connect` it
+-   A relation is left out when its junction carries a further `NOT NULL` column with no
+    default — a filter alone could not supply a value for it — and when it is declared as a
+    to-one, whose "exactly one" guarantee lives in the junction's constraints rather than in
+    the relation
+
 Dialect support: **PostgreSQL**, and **SQLite** on an asynchronous driver (libsql, D1). A
 nested write reads back the key of the row it just wrote, which MySQL has no `RETURNING` for,
 and interleaves awaited statements inside a transaction, which a synchronous SQLite driver
@@ -1480,6 +1589,81 @@ example a pooled connection bound to a tenant, or a logging proxy around `db`. B
 key is created with `Symbol.for`, the ESM and CJS builds of this package agree on it when
 both end up loaded in one process.
 
+Or let the library open one per request: `transactions: 'auto'` wraps a document that fires
+more than one generated mutation in a single transaction, committed when the last one
+completes and rolled back if any of them fails.
+
+```Typescript
+buildSchema(db, { transactions: 'auto' })
+```
+
+A document with one mutation, or one that selects a mutation field this build did not
+generate, still runs unwrapped — there is nothing to keep atomic.
+
+## Write hooks
+
+`onWrite` runs a hook **inside the mutation's transaction**, so its writes commit or roll back
+with the mutation itself. That is the position an audit row, an outbox row or a denormalized
+counter needs, and the one a `graphql-middleware` wrapper cannot occupy — a wrapper sits
+outside the resolver, so its after-position is after the commit.
+
+```Typescript
+const { schema } = buildSchema(db, {
+    onWrite: {
+        posts: async ({ table, operation, rows, tx }) => {
+            await tx.insert(auditLog).values(rows.map((row) => ({ table, operation, rowId: row.id })))
+        },
+    },
+})
+```
+
+A bare function is the **`after`** hook — the position that has rows. `{ before, after }` names
+them explicitly:
+
+```Typescript
+onWrite: {
+    posts: {
+        // Reads inside the same snapshot the write will use.
+        before: async ({ args, tx }) => {
+            const [parent] = await tx.select().from(orgs).where(eq(orgs.id, args.values[0].orgId))
+            if (!parent) throw new Error('org went away')
+        },
+        after: async ({ rows, tx }) => { /* … */ },
+    },
+}
+```
+
+Registering a bare function (or a positions object) at the top level applies it to every table;
+anything else is read as a table map keyed by the **Drizzle schema key**, and a name that
+matches nothing throws at build time.
+
+The payload:
+
+| Field | |
+| --- | --- |
+| `table` | Drizzle schema key of the table being written |
+| `operation` | `'insert' \| 'update' \| 'updateMany' \| 'upsert' \| 'delete' \| 'restore'` |
+| `position` | `'before'` or `'after'` |
+| `single` | whether the field writes one row or a list |
+| `args` | the field's GraphQL arguments, as the resolver received them |
+| `rows` | the post-write rows **as the database returned them**, before the output mapper |
+| `context`, `info` | the GraphQL context value and resolve info |
+| `tx` | the executor the mutation ran on |
+
+-   **`tx` is the executor the mutation itself used** — one you supplied under
+    `drizzleExecutorKey`, the request's auto-transaction, or, for a field that would otherwise
+    have run unwrapped, a transaction opened for it *because* the hook is there. The hook does
+    not have to know which.
+-   **Throwing rolls the mutation back.** A hook that can only log is what a logging plugin
+    already does.
+-   **`rows` is empty** at the `before` position, and on MySQL, whose mutations return no rows.
+    The `before` position and `args` still work there.
+-   The hook fires for the **mutation field's own table**. Rows a nested `create` writes into
+    another table do not fire that table's hook.
+
+A build with no `onWrite` opens exactly the transactions it did before.
+
+
 ## Relations & N+1 handling
 
 Generated schemas resolve nested relations without N+1 query explosions:
@@ -1637,7 +1821,8 @@ const meta = drizzleExtension(field)
 //   table: 'Users',        // the Drizzle schema key
 //   kind: 'mutation',      // 'query' | 'mutation' | 'relation' | 'aggregate' | 'type'
 //   operation: 'update',   // 'select' | 'insert' | 'update' | 'updateMany' | 'upsert'
-//                          // | 'delete' | 'aggregate' | 'groupBy' | 'relation'
+//                          // | 'delete' | 'restore' | 'aggregate' | 'groupBy'
+//                          // | 'relation'
 //                          // | 'relationAggregate'
 //   single: true,          // one row, or a list
 //   targetArg: 'where',    // 'where' | 'values' | 'updates' — where the rows live

package/dist/README.md

@@ -362,6 +362,81 @@ const { schema } = buildSchema(db, {
 
 Return `undefined` for any table that should keep its default naming.
 
+## Soft delete
+
+`softDelete` turns a table's `delete` mutation into an UPDATE that marks the row, and hides
+marked rows from every read:
+
+```Typescript
+const { schema } = buildSchema(db, {
+    softDelete: {
+        posts: 'deletedAt',
+        // The NOT NULL form has to spell out both values:
+        flags: { column: 'isArchived', deletedValue: true, restoredValue: false },
+    },
+})
+```
+
+Keyed by the **Drizzle schema key**, like `scope` and `exclude`. A function form is also
+accepted, for a convention applied across the schema:
+
+```Typescript
+softDelete: (table, tableName) => ('deletedAt' in getTableColumns(table) ? 'deletedAt' : undefined)
+```
+
+What a declared table gets:
+
+| Path | Effect |
+| --- | --- |
+| `deletePosts`, `deletePostsSingle` | UPDATE that writes the marker; returns the rows as they now stand |
+| `restorePosts`, `restorePostsSingle` | the inverse — matches **only** marked rows and clears the marker |
+| `posts`, `postsSingle`, cursor pages | marked rows are not returned |
+| `postsAggregate`, `postsGroupBy` | counted over unmarked rows only |
+| `user.posts`, `user.postsAggregate` | hidden on both the batched and the eager (`with:`) path |
+| `updatePosts`, `updatePostsMany`, a second `deletePosts` | a marked row is simply not matched |
+| nested `connect` / `disconnect` / `set` | a marked row cannot be attached or detached |
+| `CreatePostsInput`, `UpdatePostsInput` | the marker column is **removed** — only the mutations write it |
+
+Every read path also gains a `deleted` argument for the cases the default hides:
+
+```graphql
+{
+    live: posts { id }                      # the default — EXCLUDE
+    trash: posts(deleted: ONLY) { id }      # the trash view, no second field needed
+    all: posts(deleted: INCLUDE) { id }
+}
+```
+
+The marker column stays **readable and filterable** — it is only the write inputs that lose it,
+the same trade `contextValues` makes.
+
+Defaults come from the column's type: `new Date()` for a timestamp, an ISO string for text,
+`Date.now()` for a number, `true` for a boolean. A NOT NULL column has no "absent" state, so
+the predicate has to compare against a constant: any NOT NULL column other than a boolean must
+give `deletedValue` (a constant, not a function) and `restoredValue`, or the build throws.
+
+Three things it deliberately does not do:
+
+-   **It does not cascade.** Marking a post does not mark its comments. A comment whose post is
+    marked is still returned by `comments`; its `post` field resolves to `null`. Declare the
+    child table too if that is not what you want.
+-   **It does not free the row's unique keys.** A marked row still occupies its primary key and
+    every unique index, so inserting a new row with the same natural key fails the constraint.
+    A partial unique index (`WHERE deleted_at IS NULL`) is the usual answer.
+-   **It does not refuse.** Like `scope`, an unreachable row answers the same as a row that does
+    not exist.
+
+The soft-delete predicate is ANDed **before** a `scope` predicate, both after the client's
+`where` — so a scope still confines what `deleted: INCLUDE` can reach.
+
+> **MySQL caveat.** `ON DUPLICATE KEY UPDATE` takes no predicate, so an upsert whose conflict
+> target hits a marked row updates it — reviving it — rather than leaving it alone. On
+> PostgreSQL and SQLite the conflict branch carries the predicate and updates nothing.
+
+A table with no declaration keeps a real `DELETE`, gets no `restore` mutation and no `deleted`
+argument, and a build with no `softDelete` at all emits exactly the SQL it did before.
+
+
 ## Scalars
 
 Columns whose values don't fit a built-in GraphQL scalar get a named custom scalar, so the
@@ -1055,12 +1130,46 @@ mutation {
     `author: { create: … }` available, `authorId` is one of two ways to supply it
 -   Nesting is one level deep: the row a nested `create` inserts takes columns only, and the
     join column is left off, since the write it is part of sets it
--   Many-to-many (`.through()`) relations are not written through
+-   Many-to-many (`.through()`) relations are written through their junction table — see
+    below
 -   The whole tree runs in one transaction — a savepoint when the request already carries one
     — so a failure anywhere leaves nothing behind
 -   A `set` that carries only relation fields is a valid update: it changes what the row is
     attached to without rewriting the row
 
+### Many-to-many relations
+
+A relation declared with `.through()` is written by inserting and deleting rows of its
+junction table, so nothing about the two rows being linked changes:
+
+```graphql
+mutation {
+    updatePostsSingle(
+        where: { id: { eq: 1 } }
+        set: { tags: { set: [{ name: { inArray: ["news", "release"] } }] } }
+    ) {
+        id
+    }
+}
+```
+
+-   It offers `connect` on the create input, and `connect`, `disconnect` and `set` on the
+    update input. All three take the target's `Filters`, exactly as on a foreign-key relation
+-   `disconnect` and `set` are offered unconditionally here: unlinking deletes a junction row
+    rather than writing `NULL` into a column that might be `NOT NULL`
+-   `connect` links every row its filters match and leaves already-linked rows alone, so
+    re-connecting is a no-op rather than a unique-constraint error
+-   `disconnect` deletes only the links, never the rows they pointed at
+-   `set: []` unlinks everything and links nothing back, which is how a many-to-many relation
+    is cleared
+-   There is no `create`: inserting a row *and* linking it is a write to two tables, and the
+    link is what the relation field is for. Create the row with its own mutation, then
+    `connect` it
+-   A relation is left out when its junction carries a further `NOT NULL` column with no
+    default — a filter alone could not supply a value for it — and when it is declared as a
+    to-one, whose "exactly one" guarantee lives in the junction's constraints rather than in
+    the relation
+
 Dialect support: **PostgreSQL**, and **SQLite** on an asynchronous driver (libsql, D1). A
 nested write reads back the key of the row it just wrote, which MySQL has no `RETURNING` for,
 and interleaves awaited statements inside a transaction, which a synchronous SQLite driver
@@ -1480,6 +1589,81 @@ example a pooled connection bound to a tenant, or a logging proxy around `db`. B
 key is created with `Symbol.for`, the ESM and CJS builds of this package agree on it when
 both end up loaded in one process.
 
+Or let the library open one per request: `transactions: 'auto'` wraps a document that fires
+more than one generated mutation in a single transaction, committed when the last one
+completes and rolled back if any of them fails.
+
+```Typescript
+buildSchema(db, { transactions: 'auto' })
+```
+
+A document with one mutation, or one that selects a mutation field this build did not
+generate, still runs unwrapped — there is nothing to keep atomic.
+
+## Write hooks
+
+`onWrite` runs a hook **inside the mutation's transaction**, so its writes commit or roll back
+with the mutation itself. That is the position an audit row, an outbox row or a denormalized
+counter needs, and the one a `graphql-middleware` wrapper cannot occupy — a wrapper sits
+outside the resolver, so its after-position is after the commit.
+
+```Typescript
+const { schema } = buildSchema(db, {
+    onWrite: {
+        posts: async ({ table, operation, rows, tx }) => {
+            await tx.insert(auditLog).values(rows.map((row) => ({ table, operation, rowId: row.id })))
+        },
+    },
+})
+```
+
+A bare function is the **`after`** hook — the position that has rows. `{ before, after }` names
+them explicitly:
+
+```Typescript
+onWrite: {
+    posts: {
+        // Reads inside the same snapshot the write will use.
+        before: async ({ args, tx }) => {
+            const [parent] = await tx.select().from(orgs).where(eq(orgs.id, args.values[0].orgId))
+            if (!parent) throw new Error('org went away')
+        },
+        after: async ({ rows, tx }) => { /* … */ },
+    },
+}
+```
+
+Registering a bare function (or a positions object) at the top level applies it to every table;
+anything else is read as a table map keyed by the **Drizzle schema key**, and a name that
+matches nothing throws at build time.
+
+The payload:
+
+| Field | |
+| --- | --- |
+| `table` | Drizzle schema key of the table being written |
+| `operation` | `'insert' \| 'update' \| 'updateMany' \| 'upsert' \| 'delete' \| 'restore'` |
+| `position` | `'before'` or `'after'` |
+| `single` | whether the field writes one row or a list |
+| `args` | the field's GraphQL arguments, as the resolver received them |
+| `rows` | the post-write rows **as the database returned them**, before the output mapper |
+| `context`, `info` | the GraphQL context value and resolve info |
+| `tx` | the executor the mutation ran on |
+
+-   **`tx` is the executor the mutation itself used** — one you supplied under
+    `drizzleExecutorKey`, the request's auto-transaction, or, for a field that would otherwise
+    have run unwrapped, a transaction opened for it *because* the hook is there. The hook does
+    not have to know which.
+-   **Throwing rolls the mutation back.** A hook that can only log is what a logging plugin
+    already does.
+-   **`rows` is empty** at the `before` position, and on MySQL, whose mutations return no rows.
+    The `before` position and `args` still work there.
+-   The hook fires for the **mutation field's own table**. Rows a nested `create` writes into
+    another table do not fire that table's hook.
+
+A build with no `onWrite` opens exactly the transactions it did before.
+
+
 ## Relations & N+1 handling
 
 Generated schemas resolve nested relations without N+1 query explosions:
@@ -1637,7 +1821,8 @@ const meta = drizzleExtension(field)
 //   table: 'Users',        // the Drizzle schema key
 //   kind: 'mutation',      // 'query' | 'mutation' | 'relation' | 'aggregate' | 'type'
 //   operation: 'update',   // 'select' | 'insert' | 'update' | 'updateMany' | 'upsert'
-//                          // | 'delete' | 'aggregate' | 'groupBy' | 'relation'
+//                          // | 'delete' | 'restore' | 'aggregate' | 'groupBy'
+//                          // | 'relation'
 //                          // | 'relationAggregate'
 //   single: true,          // one row, or a list
 //   targetArg: 'where',    // 'where' | 'values' | 'updates' — where the rows live