@vantreeseba/drizzle-graphql 7.5.0 → 7.7.0

package/README.md

@@ -237,6 +237,96 @@ table becomes readable but not insertable — and warns on the console, since th
 often a mistake than a plan.
 
 > `exclude` is a static decision: the column is absent for every caller. Deciding per
+> request *which fields* a caller may reach is a job for
+> [`graphql-shield`](https://the-guild.dev/graphql/shield) or an equivalent layer above the
+> schema. Deciding per request *which rows* a caller may reach is `scope`, below — that one a
+> layer above cannot do, because a nested relation field never passes through a root resolver.
+
+## Row scoping and multi-tenancy
+
+`scope` attaches a predicate, derived from the request context, to every read and write of a
+table:
+
+```Typescript
+import { and, eq } from 'drizzle-orm'
+
+const { schema } = buildSchema(db, {
+    scope: {
+        posts: (ctx, table) => eq(table.orgId, ctx.orgId),
+        // A filter object works too — same shape as the generated `where` argument:
+        comments: (ctx) => ({ post: { orgId: { eq: ctx.orgId } } }),
+    },
+})
+```
+
+Keyed by the **Drizzle schema key**. `ctx` is your GraphQL context value; `table` is the table
+the current statement runs against — for a relational read that is Drizzle's *aliased* copy, so
+always build the predicate from that argument rather than from the imported table object.
+
+The predicate is ANDed on **last**, after whatever the client sent, so a client filter can only
+narrow the scope, never widen it. It reaches every path that touches the table:
+
+| Path | Effect |
+| --- | --- |
+| `posts`, `postsSingle` | out-of-scope rows are not returned |
+| `postsAggregate`, `postsGroupBy` | counted over in-scope rows only |
+| `user.posts`, `user.postsAggregate` | scoped on both the batched and the eager (`with:`) path |
+| cursor pages | the keyset page is taken within the scope |
+| `updatePosts`, `updatePostsMany`, `deletePosts` | an out-of-scope row is simply not matched |
+| `upsertPosts` (conflict branch) | a conflicting row outside the scope is left alone, not taken over |
+| nested `connect` / `disconnect` / `set` | only in-scope rows can be attached or detached |
+
+Two things it deliberately does not do:
+
+-   **It does not refuse.** A scoped `deletePosts(where: { id: { eq: 4 } })` on another
+    tenant's row returns `[]`, the same answer as a row that does not exist. Telling the caller
+    "that row exists but is not yours" is the leak the scope is there to close.
+-   **It does not apply to a plain insert.** There is no existing row to filter. `contextValues`
+    is the write-side half.
+
+Returning `undefined` means *no restriction for this context*, so one hook can let an
+administrator through:
+
+```Typescript
+scope: {
+    posts: (ctx, table) => (ctx.isAdmin ? undefined : eq(table.orgId, ctx.orgId)),
+}
+```
+
+A table with no entry is unscoped, and a build with no `scope` at all emits exactly the SQL it
+did before.
+
+### Columns the server owns
+
+`contextValues` supplies a column's value from the request context instead of accepting it from
+the client:
+
+```Typescript
+const { schema } = buildSchema(db, {
+    contextValues: {
+        posts: {
+            orgId: (ctx) => ctx.orgId,
+            authorId: (ctx) => ctx.userId,
+        },
+    },
+})
+```
+
+-   The column is **removed from `CreatePostsInput` and `UpdatePostsInput`**, so a client cannot
+    send it at all — the SDL itself says the column is server-owned. It stays readable on the
+    object type.
+-   Every insert stamps it, including rows created by a nested `create`.
+-   Updates never write it, so an update cannot hand a row to another owner.
+
+Together the two close the loop: `contextValues` decides which tenant a new row belongs to, and
+`scope` decides which rows a request can see and change afterwards.
+
+> **MySQL caveat.** `ON DUPLICATE KEY UPDATE` takes no predicate, so a MySQL upsert's conflict
+> branch cannot be scoped. Scope the table's `update` and rely on `contextValues` for the insert
+> half.
+
+Names that match nothing throw at build time, the same as `exclude` — a renamed column fails the
+build instead of quietly ceasing to be scoped.
 > request who may see what is a job for [`graphql-shield`](https://the-guild.dev/graphql/shield)
 > or an equivalent layer above the schema, which has the request context this library
 > does not.
@@ -272,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
@@ -1547,7 +1712,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

@@ -237,6 +237,96 @@ table becomes readable but not insertable — and warns on the console, since th
 often a mistake than a plan.
 
 > `exclude` is a static decision: the column is absent for every caller. Deciding per
+> request *which fields* a caller may reach is a job for
+> [`graphql-shield`](https://the-guild.dev/graphql/shield) or an equivalent layer above the
+> schema. Deciding per request *which rows* a caller may reach is `scope`, below — that one a
+> layer above cannot do, because a nested relation field never passes through a root resolver.
+
+## Row scoping and multi-tenancy
+
+`scope` attaches a predicate, derived from the request context, to every read and write of a
+table:
+
+```Typescript
+import { and, eq } from 'drizzle-orm'
+
+const { schema } = buildSchema(db, {
+    scope: {
+        posts: (ctx, table) => eq(table.orgId, ctx.orgId),
+        // A filter object works too — same shape as the generated `where` argument:
+        comments: (ctx) => ({ post: { orgId: { eq: ctx.orgId } } }),
+    },
+})
+```
+
+Keyed by the **Drizzle schema key**. `ctx` is your GraphQL context value; `table` is the table
+the current statement runs against — for a relational read that is Drizzle's *aliased* copy, so
+always build the predicate from that argument rather than from the imported table object.
+
+The predicate is ANDed on **last**, after whatever the client sent, so a client filter can only
+narrow the scope, never widen it. It reaches every path that touches the table:
+
+| Path | Effect |
+| --- | --- |
+| `posts`, `postsSingle` | out-of-scope rows are not returned |
+| `postsAggregate`, `postsGroupBy` | counted over in-scope rows only |
+| `user.posts`, `user.postsAggregate` | scoped on both the batched and the eager (`with:`) path |
+| cursor pages | the keyset page is taken within the scope |
+| `updatePosts`, `updatePostsMany`, `deletePosts` | an out-of-scope row is simply not matched |
+| `upsertPosts` (conflict branch) | a conflicting row outside the scope is left alone, not taken over |
+| nested `connect` / `disconnect` / `set` | only in-scope rows can be attached or detached |
+
+Two things it deliberately does not do:
+
+-   **It does not refuse.** A scoped `deletePosts(where: { id: { eq: 4 } })` on another
+    tenant's row returns `[]`, the same answer as a row that does not exist. Telling the caller
+    "that row exists but is not yours" is the leak the scope is there to close.
+-   **It does not apply to a plain insert.** There is no existing row to filter. `contextValues`
+    is the write-side half.
+
+Returning `undefined` means *no restriction for this context*, so one hook can let an
+administrator through:
+
+```Typescript
+scope: {
+    posts: (ctx, table) => (ctx.isAdmin ? undefined : eq(table.orgId, ctx.orgId)),
+}
+```
+
+A table with no entry is unscoped, and a build with no `scope` at all emits exactly the SQL it
+did before.
+
+### Columns the server owns
+
+`contextValues` supplies a column's value from the request context instead of accepting it from
+the client:
+
+```Typescript
+const { schema } = buildSchema(db, {
+    contextValues: {
+        posts: {
+            orgId: (ctx) => ctx.orgId,
+            authorId: (ctx) => ctx.userId,
+        },
+    },
+})
+```
+
+-   The column is **removed from `CreatePostsInput` and `UpdatePostsInput`**, so a client cannot
+    send it at all — the SDL itself says the column is server-owned. It stays readable on the
+    object type.
+-   Every insert stamps it, including rows created by a nested `create`.
+-   Updates never write it, so an update cannot hand a row to another owner.
+
+Together the two close the loop: `contextValues` decides which tenant a new row belongs to, and
+`scope` decides which rows a request can see and change afterwards.
+
+> **MySQL caveat.** `ON DUPLICATE KEY UPDATE` takes no predicate, so a MySQL upsert's conflict
+> branch cannot be scoped. Scope the table's `update` and rely on `contextValues` for the insert
+> half.
+
+Names that match nothing throw at build time, the same as `exclude` — a renamed column fails the
+build instead of quietly ceasing to be scoped.
 > request who may see what is a job for [`graphql-shield`](https://the-guild.dev/graphql/shield)
 > or an equivalent layer above the schema, which has the request context this library
 > does not.
@@ -272,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
@@ -1547,7 +1712,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