@vantreeseba/drizzle-graphql 13.0.0 → 13.1.1

package/README.md

@@ -711,6 +711,51 @@ lists is the build-time error above.
 >     `${tableName}${columnName[0]!.toUpperCase()}${columnName.slice(1)}Enum`
 > ```
 
+### Enum value names
+
+A value's GraphQL name is the stored value itself, or `Option<index>` when the stored value
+is not a usable GraphQL name. `enumValueNameMapper` renames the values — most often to follow
+GraphQL's SCREAMING_CASE convention while the database keeps its lowercase values:
+
+```Typescript
+export const Runs = pgTable('runs', {
+    status: text('status', { enum: ['running', 'ok', 'error', 'stopped'] }),
+})
+
+const { schema } = buildSchema(db, {
+    // The built-in preset: `inProgress` / `in-progress` → `IN_PROGRESS`
+    enumValueNameMapper: 'constant',
+})
+```
+
+```graphql
+enum RunsStatusEnum {
+    RUNNING   # stored as 'running'
+    OK
+    ERROR
+    STOPPED
+}
+```
+
+-   Only the GraphQL name changes. Each value's internal `value` is still the stored string,
+    so filters (`eq`, `inArray`, …), create/update inputs, outputs and your own resolvers keep
+    sending and receiving exactly what the database stores. The generated TypeScript types
+    keep the stored values too
+-   The function form receives the stored `value`, its `index`, the enum's GraphQL `typeName`
+    (after `enumNameMapper`) and everything `enumNameMapper` receives. Returning `undefined`
+    keeps the default name for that value:
+
+    ```Typescript
+    enumValueNameMapper: ({ value, typeName }) =>
+        typeName === 'RunsStatusEnum' ? value.toUpperCase() : undefined,
+    ```
+
+-   The build fails, rather than producing an invalid or lossy schema, when a returned name is
+    not a valid GraphQL enum value name, when two values of one enum map to the same name, or
+    when columns that share one enum type (the columns of one `pgEnum`) would name its values
+    differently — give those columns separate types with `enumNameMapper` if they really
+    should differ
+
 ## Documenting the schema
 
 Four hooks put descriptions and deprecations on the generated types. Each is called per
@@ -1578,9 +1623,27 @@ mutation {
 -   Both return `Int!` — the number of rows the write affected — and add no new output type
     to the schema
 -   Arguments are exactly the plural mutation's, so a client swaps one field name for the
-    other; `features.requireWhere` applies to them the same way
+    other; `features.requireWhere` applies to them the same way, and on a soft-deleting
+    table that opted into `hardDelete` the delete takes `hard` too
 -   They follow the feature switch of the write they mirror: `updateCount` needs
     `features.update`, `deleteCount` needs `features.delete`
+-   They obey the same row policies as the plural write — only the answer differs:
+    -   [`scope`](#row-scoping-and-multi-tenancy) is ANDed into the `where`, so they reach,
+        and count, only in-scope rows
+    -   on a [soft-deleting](#soft-delete) table `delete<Table>Count` marks the rows rather
+        than removing them, and neither mutation reaches a row that is already marked
+    -   a [`contextValues`](#row-scoping-and-multi-tenancy) column is never reassigned by the
+        update
+    -   [`onWrite`](#write-hooks) hooks run `before` and `after`, in a transaction, with the
+        plural write's payload (`operation: 'update'` / `'delete'`, `single: false`). An
+        `after` hook is handed rows, so a table with one gives up the returnless write: the
+        statement `RETURNING`s the hook's `columns`, or just the primary key when it names
+        none (every column, on a table without a key), and the count is the number of rows
+        returned. Without an `after` hook there is no `RETURNING` at all. On MySQL the hook
+        gets `rows: []`, as it does on every MySQL mutation
+-   Their [`extensions.drizzle`](#identifying-generated-fields) is the plural write's
+    (`operation: 'update'` / `'delete'`, `targetArg: 'where'`) plus `count: true`, so a
+    wrapper that gates writes on `operation` covers them too
 -   **MySQL** gets them too, and they are arguably most useful there: MySQL's other mutations
     return only `MutationReturn { isSuccess }`, so a row count is strictly more information
 -   `update<Table>Count` **rejects** nested writes with a `GraphQLError` — a nested write
@@ -2019,8 +2082,12 @@ 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 })))
+        posts: {
+            after: async ({ table, operation, rows, tx }) => {
+                await tx.insert(auditLog).values(rows.map((row) => ({ table, operation, rowId: row.id })))
+            },
+            // Every row carries `id`, even when the client's mutation did not select it.
+            columns: ['id'],
         },
     },
 })
@@ -2046,6 +2113,42 @@ Registering a bare function (or a positions object) at the top level applies it
 anything else is read as a table map keyed by the **Drizzle schema key**, and a name that
 matches nothing throws at build time.
 
+### Which columns `rows` holds
+
+The statement's `RETURNING` list is built from the client's selection, so by default a row
+holds only the columns the mutation's document asked for (plus any key a selected relation or a
+nested write needed). A hook that reads a column the client may not select — `row.id` above, or
+the `personId` an `addresses` hook needs to bump its person's revision — names it in `columns`:
+
+```Typescript
+onWrite: {
+    addresses: {
+        after: async ({ rows, tx }) => { /* every row has `id` and `personId` */ },
+        columns: ['id', 'personId'],
+    },
+    contactInfos: {
+        after: async ({ rows, tx }) => { /* every row has every column */ },
+        columns: 'all',
+    },
+}
+```
+
+-   The names are **column keys** — the property names on the Drizzle table object, which is
+    what `rows` is keyed by. An unknown name throws at build time, and so does `columns` on a
+    registration with no `after` hook (only `after` is handed rows).
+-   On a top-level registration, a named column must exist on **every** table; `'all'` always
+    works.
+-   The columns are added to `RETURNING` for every write the hook is attached to: insert, upsert,
+    update, `updateMany`, delete and restore. A delete's rows are the rows it removed.
+-   The [count mutations](#row-counts-instead-of-rows) fire the hooks as `update` / `delete`.
+    The client selects nothing there, so an `after` hook's rows hold exactly its `columns`, or
+    just the primary key when it names none — the one `RETURNING` those mutations pay for.
+-   **The client's response is unchanged.** Columns the hook asked for but the client did not
+    select are taken back off before the rows are mapped, so they reach neither the response nor
+    a custom resolver calling the generated one. The hook gets its own copy of the rows.
+-   **MySQL** has no `RETURNING`, so its mutations return no rows and `columns` has nothing to
+    add to: `rows` stays empty there. The names are still checked at build time.
+
 The payload:
 
 | Field | |
@@ -2055,7 +2158,7 @@ The payload:
 | `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 |
+| `rows` | the post-write rows **as the database returned them**, before the output mapper — the selected columns plus the hook's [`columns`](#which-columns-rows-holds) |
 | `context`, `info` | the GraphQL context value and resolve info |
 | `tx` | the executor the mutation ran on |
 
@@ -2247,7 +2350,9 @@ the check to make before treating a field as one of ours. Relation fields (and
 naming the relation's **target** — so `Users.posts` reads as
 `{ table: 'Posts', parentTable: 'Users', relation: 'posts' }`. Object types carry
 `{ table, kind: 'type', primaryKey }`, which is what a stitching layer needs to map a type
-back to its source.
+back to its source. The [count mutations](#row-counts-instead-of-rows) carry their plural
+write's `operation` plus `count: true` — they write the same rows but resolve to an `Int!`, so
+a wrapper that reads the result as rows should check `count` first.
 
 Because the row identity of a mutation lives in a different argument for every operation,
 `identifyRows` reads whichever one applies and hands back primary-key values:
@@ -2285,6 +2390,7 @@ that explains it, where there is one.
 | `typeNamePrefix` / `typeNameSuffix` / `derivedTypeNameMapper` | none | [names of the derived types](#renaming-the-derived-types) — filters, inputs, aggregates, shared inputs |
 | `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) |
+| `enumValueNameMapper` | the stored value | [names the enum's values](#enum-value-names); `'constant'` for CONSTANT_CASE |
 | `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 |