@vantreeseba/drizzle-graphql 7.0.0 → 7.2.0

package/README.md

@@ -101,6 +101,7 @@ const { schema } = buildSchema(db, {
         distinct: false,          // the `distinct` argument on list queries
         insert: false,            // create<Table> / create<Table>Single mutations
         update: false,            // update<Table> / update<Table>Single mutations
+        updateMany: false,        // update<Table>Many batch mutation (needs `update`)
         delete: false,            // delete<Table> / delete<Table>Single mutations
         upsert: true,             // upsert<Table> / upsert<Table>Single mutations (off by default)
         nestedWrites: true,       // relation fields on the create/update inputs (off by default)
@@ -123,6 +124,92 @@ const { schema } = buildSchema(db, {
     `mutations: false`
 -   List and single queries are always generated, so `Query` is never empty
 
+## Excluding tables and columns
+
+`features` decides which *kinds* of operation exist. `exclude` decides which tables and
+columns exist at all — for the table holding session tokens, or the column holding a
+password hash:
+
+```Typescript
+const { schema } = buildSchema(db, {
+    exclude: {
+        tables: ['magicLinks', 'sessions'],
+        columns: { apiKeys: ['keyHash'] },
+    },
+})
+```
+
+Both lists are keyed by the **Drizzle schema key**, not the database name and not the
+generated GraphQL name.
+
+An excluded **table** generates nothing: no object type, no queries, no mutations, no
+aggregates, and no relation field on any other table that points at it. `Users.sessions`
+is gone, and so is `users(where: { sessions: { … } })` — the table is unreachable, not
+merely unnamed.
+
+An excluded **column** disappears from every surface at once:
+
+| Surface | Effect |
+| --- | --- |
+| `<Type>` object type | field removed |
+| `Create<Type>Input` / `Update<Type>Input` | field removed (nested-write payloads too) |
+| `<Type>Filters` | field removed |
+| `<Type>OrderBy` | field removed |
+| `<Type>MinAggregate` / `<Type>MaxAggregate` / … | field removed |
+| `<Type>DistinctColumn` / `<Type>GroupByColumn` | value removed |
+| `<Type>ConflictColumn` (upsert targets) | value removed |
+
+Two details worth stating plainly:
+
+-   **The exclusion is all-or-nothing on purpose.** A column you can filter on but not
+    select is an oracle: `where: { keyHash: { eq: '…' } }` confirms a value without ever
+    returning it. Ordering and grouping leak the same way, more slowly. There is no
+    read-only or write-only variant of `exclude` for this reason.
+-   **Nothing changes below the schema.** An excluded column is still written by its
+    default, still read by the primary-key and cursor machinery, and still usable by your
+    own resolvers. Only the generated schema stops mentioning it.
+
+Names that match nothing throw at build time, so renaming a column fails the build instead
+of quietly un-hiding it. Excluding a `NOT NULL` column with no default is allowed — the
+table becomes readable but not insertable — and warns on the console, since that is more
+often a mistake than a plan.
+
+> `exclude` is a static decision: the column is absent for every caller. Deciding per
+> 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.
+## Naming
+
+Type and field names are derived from the Drizzle schema keys. Three options change them.
+
+`prefixes` and `suffixes` rename operations without touching type names:
+
+```Typescript
+const { schema } = buildSchema(db, {
+    prefixes: { insert: 'add', update: 'edit', delete: 'remove' }, // default: create / update / delete
+    suffixes: { list: 'All', single: '' },                         // default: '' / 'Single'
+})
+```
+
+The list and single suffixes cannot be identical unless a `typeNameMapper` is also given —
+`users` and `usersSingle` would otherwise collapse onto one field name, and `buildSchema`
+throws rather than generating a schema that silently drops one of them.
+
+`typeNameMapper` renames the table itself, which is what a plural-keyed schema usually wants:
+`export const users = pgTable('users', …)` otherwise produces `type Users` and a
+`usersSingle` query.
+
+```Typescript
+import pluralize from 'pluralize'
+
+const { schema } = buildSchema(db, {
+    typeNameMapper: (table) => ({ singular: pluralize.singular(table), plural: table }),
+})
+// type User; queries `users` / `user`; mutations `createUsers` / `createUser`
+```
+
+Return `undefined` for any table that should keep its default naming.
+
 ## Scalars
 
 Columns whose values don't fit a built-in GraphQL scalar get a named custom scalar, so the
@@ -162,6 +249,25 @@ import { GraphQLBigIntString, GraphQLDate, GraphQLDateTime, GraphQLJSON, GraphQL
 `GraphQLBigIntString` is the `BigInt` scalar — named for what it does rather than what it is
 called in SDL, to avoid clashing with the language's own `BigInt`.
 
+### Overriding a column's scalar
+
+Built-in detection is a default, not a ceiling. `scalars` overrides named columns, and
+`mapColumnType` applies a rule across every column at build time — the tool for a convention
+("every `numeric` column is `Money`") or for a custom column type detection does not know:
+
+```Typescript
+const { schema } = buildSchema(db, {
+    scalars: {
+        users: { email: EmailAddressScalar },              // by table key, then column key
+    },
+    mapColumnType: (column) => (column.columnType === 'PgNumeric' ? MoneyScalar : undefined),
+})
+```
+
+Either may return a single scalar, or an `{ output, input }` pair when the read and write
+types differ. `mapColumnType` returning `undefined` keeps the default, and a column matched
+by both is decided by `scalars` alone.
+
 ## Enum types
 
 A column declared with a database enum becomes a GraphQL enum named after **the enum**, not
@@ -798,6 +904,51 @@ that out at the type level, `features: { requireWhere: true }` makes `where` non
 `update<Table>` / `delete<Table>` and rejects a `where` with no filters, exactly like the
 Single variants. It defaults to `false` for backwards compatibility.
 
+## Bounding page size
+
+Nothing stops a client asking a list query for every row it has. `limits` sets a page size for
+a request that names none, a ceiling for one that does, or both:
+
+```ts
+buildSchema(db, {
+  limits: {
+    defaultLimit: 25,
+    maxLimit: 100,
+    tables: {
+      Posts: { defaultLimit: 50 },
+      AuditLog: { maxLimit: 10, clampToMax: true },
+    },
+  },
+});
+```
+
+| Key | Effect |
+| --- | --- |
+| `defaultLimit` | The `limit` applied when the request passes none |
+| `maxLimit` | The largest `limit` a request may ask for |
+| `clampToMax` | `false` (default) rejects a `limit` above `maxLimit`; `true` reduces it |
+| `tables` | Per-table overrides, keyed by the table's key in your Drizzle schema |
+
+A per-table policy overrides the global one key by key, so `AuditLog` above still inherits
+`defaultLimit: 25`. Everything is optional; a build with no `limits` behaves exactly as before.
+
+Two details worth stating plainly:
+
+-   **`maxLimit` alone also bounds a request that passes no `limit`.** No limit means every
+    row, which is above any maximum, so such a request runs at `maxLimit`.
+-   **A rejection is the default because truncation lies.** Silently cutting a page down to
+    `maxLimit` tells a paginating client it has reached the end when it has not. `clampToMax:
+    true` opts into that when you would rather never fail a query.
+
+The policy applies to root list queries and to to-many relation fields, on both the eager and
+the lazy relation paths. A relation takes the policy of the table it *reads*, not its parent's:
+with `tables: { Posts: { maxLimit: 10 } }`, `users { posts(limit: 50) }` is rejected. Cursor
+pagination inherits it — a page defaults to `defaultLimit` and the `cursor` values stay usable.
+
+What it does not touch: `<tableName>Single` queries, which are already one row; aggregate,
+group-by and `<relation>Aggregate` fields, which count over the whole table rather than
+returning rows; and to-one relation fields, which take no `limit` at all.
+
 ## Query cost
 
 Generated fields carry a `complexity` hint in their GraphQL extensions, ready for
@@ -815,6 +966,10 @@ fields it mentions:
 So `users(limit: 20) { id posts(limit: 5) { id } }` costs `20 * (1 + 5 * 1)` = 120, while the
 same query without limits costs `10 * (1 + 10 * 1)` = 110.
 
+A [limit policy](#bounding-page-size) feeds into the hint: a field with no `limit` is priced at
+its `defaultLimit` rather than `defaultListSize`, and nothing is priced above `maxLimit`, so the
+cost matches the rows the query can actually pull.
+
 The hints do nothing until you install a complexity rule, so they are generated by default:
 
 ```ts
@@ -840,9 +995,108 @@ buildSchema(db, { complexity: false });
 
 Cost is not a depth bound. A cyclic relation graph (`user -> posts -> author -> posts -> …`)
 lets a client nest as deep as it likes, and a deep query over cheap fields can stay under any
-complexity ceiling. Put a depth limit in front of a publicly exposed schema as well — e.g.
-[`graphql-depth-limit`](https://github.com/stems/graphql-depth-limit) — or set
-`relationsDepthLimit: 0` to generate no relation fields at all.
+complexity ceiling. Set `relationsDepthLimit: 0` to generate no relation fields at all, or —
+more usefully — bound depth at the edge, along with the rest of the document-shape defences
+below.
+
+### Hardening a public endpoint
+
+A generated schema is wide by construction: every table is reachable, every relation is
+traversable, and the relation graph is usually cyclic. The `complexity` hints price that
+surface, but only for the shapes the generator knows about, and nothing in this library
+inspects the incoming document. For a schema exposed to untrusted clients, put
+[GraphQL Armor](https://github.com/Escape-Technologies/graphql-armor) in front of it — it
+bundles the document-level defences this library deliberately does not generate:
+
+| Protection | What it bounds |
+| --- | --- |
+| `maxDepth` | nesting through a cyclic relation graph |
+| `maxAliases` | the same expensive list requested many times under many aliases |
+| `maxDirectives` | directive-count amplification |
+| `maxTokens` | parser blow-up, rejected before validation runs |
+| `costLimit` | a static per-document cost ceiling |
+| `blockFieldSuggestion` | `Did you mean "keyHash"?` leaking field names on a typo |
+
+```ts
+import { EnvelopArmor } from '@escape.tech/graphql-armor';
+import { createYoga } from 'graphql-yoga';
+
+const { schema } = buildSchema(db);
+const armor = new EnvelopArmor({
+  maxDepth: { n: 8 }, // roughly three relation hops into the generated graph
+  maxAliases: { n: 15 },
+  costLimit: { maxCost: 5000 },
+});
+
+const yoga = createYoga({ schema, plugins: armor.protect().plugins });
+```
+
+`ApolloArmor` is the Apollo Server equivalent — its `protect()` returns `plugins` plus
+`validationRules`.
+
+Armor's `costLimit` is its own document-shape estimate and does not read the `complexity`
+extensions above; the two compose, if you want a cheap static ceiling alongside row-count
+aware pricing. Neither one bounds an individual `limit` argument, so a single unbounded list
+query is still a full table scan — cap `limit` yourself if that matters.
+
+## Authorization
+
+`buildSchema` is handed a Drizzle instance, not a request. It has no notion of who is asking,
+so it generates no authorization: every table it knows about is queryable and writable by
+anyone who can reach the endpoint. Auth belongs to a layer above the schema, where the
+request context actually lives.
+
+-   **[graphql-shield](https://github.com/maticzav/graphql-shield)** — permission rules
+    mapped onto fields and applied with
+    [`graphql-middleware`](https://github.com/maticzav/graphql-middleware). Rules attach to
+    root fields *and* to fields of a generated object type, which is what makes it an answer
+    to "this column must never leave the server" and not just "this query is blocked":
+
+    ```ts
+    import { applyMiddleware } from 'graphql-middleware';
+    import { allow, deny, rule, shield } from 'graphql-shield';
+
+    const isAuthenticated = rule()((parent, args, ctx) => Boolean(ctx.userId));
+
+    const { schema } = buildSchema(db);
+    const guarded = applyMiddleware(
+      schema,
+      shield(
+        {
+          Query: { users: isAuthenticated, usersSingle: isAuthenticated },
+          Mutation: { '*': isAuthenticated },
+          ApiKeys: { keyHash: deny }, // field stays in the schema, never resolves
+        },
+        { fallbackRule: allow },
+      ),
+    );
+    ```
+
+-   **[CASL](https://casl.js.org)** (`@casl/ability`) — one ability definition, conditions and
+    field lists included (`can('read', 'Posts', ['title', 'body'])`), shared between the
+    GraphQL layer and the rest of the app instead of a permission model that exists only in
+    the API. CASL is not GraphQL middleware itself: wire it in through the shield rules above
+    or through your own resolver wrapper, and let the ability answer the questions.
+
+What neither can do is **narrow** a query. They permit or deny a field; they do not append
+`WHERE user_id = …` to the SQL a generated resolver runs, and a permitted `users` query still
+returns every tenant's rows. Until row scoping is a first-class option here, the ways to get
+it are, in increasing order of effort:
+
+-   supply the tenant predicate as an ordinary `where` argument from a trusted gateway, and
+    deny the raw generated fields to everyone else;
+-   build the schema by hand from `entities`, exposing only the generated resolvers you have
+    wrapped;
+-   put the scoped tables behind database row-level security and give the driver the
+    request's identity, so the narrowing happens below Drizzle entirely.
+
+None of this removes anything from introspection either — `deny` hides the data, not the
+shape. If the schema must not so much as mention a table, keep that table out of the Drizzle
+instance you pass to `buildSchema` (a second instance over a narrowed schema object is
+cheap).
+
+Nor is it a row bound: a complexity ceiling prices the `limit` a client asks for, it does not
+cap it. Use [`limits`](#bounding-page-size) for that.
 
 ## Error handling
 
@@ -889,10 +1143,44 @@ want to fall back to it explicitly.
 
 ## Transactions
 
-Each resolver runs its statements on the database the schema was built from. A request that
-fires several mutations therefore commits each one separately, and a failure halfway leaves
-the earlier ones in place. To run a whole request as one unit, open a transaction yourself
-and put it on the GraphQL context under the exported `drizzleExecutorKey`:
+Each resolver runs its statements on the database the schema was built from, so by default a
+request that fires several mutations commits each one separately and a failure halfway leaves
+the earlier ones in place. There are two ways to make a request atomic.
+
+### Letting the library open one
+
+`transactions: 'auto'` opens `db.transaction()` once per request whose document selects more
+than one root mutation field, and runs every mutation field — plus the reads nested under
+them — inside it:
+
+```Typescript
+const { schema } = buildSchema(db, { transactions: 'auto' })
+
+// or, to change the safety timeout:
+const { schema } = buildSchema(db, { transactions: { mode: 'auto', timeoutMs: 10_000 } })
+```
+
+The transaction commits when the last mutation field completes and rolls back if any of them
+fails; mutation fields after a failure fail fast instead of running against a rolled-back
+transaction. A document with one mutation field or none opens nothing, so ordinary requests
+are untouched.
+
+-   The driver must support `db.transaction()` — `neon-http` does not. For SQLite only an
+    asynchronous driver can hold a transaction open across resolvers, and `buildSchema`
+    throws for a synchronous one rather than failing at request time
+-   The GraphQL context value must be a fresh object per request (every mainstream server
+    does this) — it keys the per-request transaction state
+-   `timeoutMs` (default `30000`) rolls back an abandoned transaction, e.g. when the host
+    server stopped calling resolvers because of a non-null completion error, instead of
+    leaking the connection
+-   A document that mixes in mutation fields this build did not generate is left alone: their
+    completion cannot be tracked, so no transaction is opened
+-   It never nests — an executor supplied on the context wins, as below
+
+### Supplying your own executor
+
+To control the boundary yourself, open a transaction and put it on the GraphQL context under
+the exported `drizzleExecutorKey`:
 
 ```Typescript
 import { buildSchema, drizzleExecutorKey } from 'drizzle-graphql'
@@ -1018,3 +1306,24 @@ Opting a relation out does **not** remove its field — it keeps resolving lazil
 request-scoped batch loader, so the field still works even before you override it. Table
 and relation names are the Drizzle schema keys (e.g. `Users`, `posts`), matching the keys
 of `entities.fieldResolvers`.
+
+## Configuration reference
+
+Every key of the second argument to `buildSchema(db, config?)`. Each links to the section
+that explains it, where there is one.
+
+| Key | Default | What it does |
+| --- | --- | --- |
+| `mutations` | `true` | `false` omits the `Mutation` type entirely |
+| `features` | see [Choosing what gets generated](#choosing-what-gets-generated) | which operations are generated, per operation |
+| `relationsDepthLimit` | unlimited | how deep relation fields are generated; `0` gives a flat, columns-only schema |
+| `prefixes` / `suffixes` / `typeNameMapper` | see [Naming](#naming) | operation and type names |
+| `scalars` / `mapColumnType` | built-in detection | [override a column's GraphQL type](#overriding-a-columns-scalar), by name or by rule |
+| `enumNameMapper` | shared `<EnumName>Enum` per database enum | [names the enum a column maps to](#enum-types) |
+| `describeColumn` / `describeTable` / `describeRelation` | none | [GraphQL descriptions](#documenting-the-schema) |
+| `deprecateColumn` | none | `@deprecated` on a column's output and optional input fields |
+| `conflictDoNothing` | `false` | PostgreSQL only — `ON CONFLICT DO NOTHING` on inserts, which makes `create<Table>Single` nullable |
+| `complexity` | on | [cost hints](#query-cost) in field extensions; `false` turns them off |
+| `transactions` | `'none'` | `'auto'` wraps a multi-mutation request in one [transaction](#transactions) |
+| `onError` | replaces driver errors | [error handling](#error-handling) hook — log, or surface a different error |
+| `eagerLoadRelations` | `true` | [which relations are pre-fetched](#overriding-a-relations-resolver-without-overfetching) with the parent query |