@vantreeseba/drizzle-graphql 7.7.0 → 7.9.0

package/README.md

@@ -945,6 +945,56 @@ supplies no `orderBy`:
 An explicit `orderBy` always takes precedence, composite primary keys are ordered by every
 key column, and an unpaginated list query is left unordered so no sort is paid for.
 
+## Default ordering
+
+A table usually has one ordering that is right nearly every time it is read — newest first,
+priority first, name alphabetical. `defaults` names that ordering once, and every query that
+does not ask for its own gets it:
+
+```ts
+buildSchema(db, {
+  defaults: {
+    Todos: { orderBy: { priority: 'desc', createdAt: 'desc' } },
+    Users: { orderBy: { name: 'asc' } },
+  },
+});
+```
+
+```graphql
+# ordered by priority desc, then createdAt desc — nothing in the query says so
+{ todos { id title } }
+```
+
+Keys are the table's key in your Drizzle schema and the column's property name, so a typo in
+either fails at `buildSchema` time rather than silently doing nothing. Each column takes
+`'asc'`, `'desc'`, or a `{ direction, priority? }` object mirroring the `orderBy` argument.
+Columns sort highest `priority` first, and the shorthand leaves it unset, so the shorthand
+falls back to the order the keys are written in — the object form is there for when you would
+rather state the precedence than depend on that:
+
+```ts
+defaults: {
+  Todos: { orderBy: { createdAt: { direction: 'desc', priority: 1 }, priority: { direction: 'desc', priority: 2 } } },
+}
+```
+
+It applies to list queries, `<tableName>Single` queries, and to-many relation fields on both
+the eager and the lazy relation paths — a relation takes the default of the table it *reads*,
+not its parent's. To-one relation fields are a single row and take no ordering.
+
+Two details worth stating plainly:
+
+-   **Any `orderBy` in the request wins outright.** The default is a fallback for a missing
+    argument, not a base that client ordering is appended to. To ask for *no* ordering, pass
+    `orderBy: {}` — an empty object is still an argument, so it suppresses the default.
+-   **A default ordering makes an unpaginated list query pay for a sort.** That is the point,
+    but it is a cost a table with no `defaults` entry does not pay; a build with no `defaults`
+    behaves exactly as before.
+
+Cursor pagination composes with it: a default-ordered page is ordered by those columns plus
+the primary key tiebreak, and its `cursor` values encode that same total order, so paging works
+without the client restating the ordering.
+
 ## Cursor pagination
 
 `OFFSET` pagination degrades linearly and shifts under concurrent writes. List queries also
@@ -1130,12 +1180,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
@@ -1555,6 +1639,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:

package/dist/README.md

@@ -945,6 +945,56 @@ supplies no `orderBy`:
 An explicit `orderBy` always takes precedence, composite primary keys are ordered by every
 key column, and an unpaginated list query is left unordered so no sort is paid for.
 
+## Default ordering
+
+A table usually has one ordering that is right nearly every time it is read — newest first,
+priority first, name alphabetical. `defaults` names that ordering once, and every query that
+does not ask for its own gets it:
+
+```ts
+buildSchema(db, {
+  defaults: {
+    Todos: { orderBy: { priority: 'desc', createdAt: 'desc' } },
+    Users: { orderBy: { name: 'asc' } },
+  },
+});
+```
+
+```graphql
+# ordered by priority desc, then createdAt desc — nothing in the query says so
+{ todos { id title } }
+```
+
+Keys are the table's key in your Drizzle schema and the column's property name, so a typo in
+either fails at `buildSchema` time rather than silently doing nothing. Each column takes
+`'asc'`, `'desc'`, or a `{ direction, priority? }` object mirroring the `orderBy` argument.
+Columns sort highest `priority` first, and the shorthand leaves it unset, so the shorthand
+falls back to the order the keys are written in — the object form is there for when you would
+rather state the precedence than depend on that:
+
+```ts
+defaults: {
+  Todos: { orderBy: { createdAt: { direction: 'desc', priority: 1 }, priority: { direction: 'desc', priority: 2 } } },
+}
+```
+
+It applies to list queries, `<tableName>Single` queries, and to-many relation fields on both
+the eager and the lazy relation paths — a relation takes the default of the table it *reads*,
+not its parent's. To-one relation fields are a single row and take no ordering.
+
+Two details worth stating plainly:
+
+-   **Any `orderBy` in the request wins outright.** The default is a fallback for a missing
+    argument, not a base that client ordering is appended to. To ask for *no* ordering, pass
+    `orderBy: {}` — an empty object is still an argument, so it suppresses the default.
+-   **A default ordering makes an unpaginated list query pay for a sort.** That is the point,
+    but it is a cost a table with no `defaults` entry does not pay; a build with no `defaults`
+    behaves exactly as before.
+
+Cursor pagination composes with it: a default-ordered page is ordered by those columns plus
+the primary key tiebreak, and its `cursor` values encode that same total order, so paging works
+without the client restating the ordering.
+
 ## Cursor pagination
 
 `OFFSET` pagination degrades linearly and shifts under concurrent writes. List queries also
@@ -1130,12 +1180,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
@@ -1555,6 +1639,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: