@vantreeseba/drizzle-graphql 13.1.1 → 15.0.0

package/README.md

@@ -2,17 +2,19 @@
 
 Automatically create GraphQL schema or customizable schema config fields from Drizzle ORM schema
 
+Site: [cubicecho.github.io/drizzle-graphql](https://cubicecho.github.io/drizzle-graphql/)
+
 ## Usage
 
 -   Pass your drizzle database instance and schema into builder to generate `{ schema, entities }` object
--   Use `schema` if pre-built schema already satisfies all your neeeds. It's compatible witn any server that consumes `GraphQLSchema` class instance
+-   Use `schema` if pre-built schema already satisfies all your needs. It's compatible with any server that consumes `GraphQLSchema` class instance
 
     Example: hosting schema using [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server)
 
     ```Typescript
     import { createServer } from 'node:http'
     import { createYoga } from 'graphql-yoga'
-    import { buildSchema } from 'drizzle-graphql'
+    import { buildSchema } from '@vantreeseba/drizzle-graphql'
 
     // db - your drizzle instance
     import { db } from './database'
@@ -20,6 +22,7 @@ Automatically create GraphQL schema or customizable schema config fields from Dr
     const { schema } = buildSchema(db)
 
     const yoga = createYoga({ schema })
+    const server = createServer(yoga)
 
     server.listen(4000, () => {
         console.info('Server is running on http://localhost:4000/graphql')
@@ -32,7 +35,7 @@ Automatically create GraphQL schema or customizable schema config fields from Dr
     import { createServer } from 'node:http'
     import { GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLSchema } from 'graphql'
     import { createYoga } from 'graphql-yoga'
-    import { buildSchema } from 'drizzle-graphql'
+    import { buildSchema } from '@vantreeseba/drizzle-graphql'
 
     // Schema contains 'Users' and 'Customers' tables
     import { db } from './database'
@@ -118,7 +121,7 @@ to leave that table with the default naming. The preset is exported as `singular
 so it can be wrapped:
 
 ```Typescript
-import { buildSchema, singularizeMapper } from 'drizzle-graphql'
+import { buildSchema, singularizeMapper } from '@vantreeseba/drizzle-graphql'
 
 const { schema } = buildSchema(db, {
     typeNameMapper: (table) => (table === 'auditLog' ? undefined : singularizeMapper(table)),
@@ -189,14 +192,16 @@ const { schema } = buildSchema(db, {
 -   The table is still fully readable — this decides which operations it offers, not whether
     it is in the schema at all. For that, use `exclude` below
 -   `nestedWrites` is the one flag that stays build-wide: its plans are computed once over
-    the whole relation graph, and a nested write reaches a second table by definition
+    the whole relation graph, and a nested write reaches a second table by definition. What
+    it offers on each relation still follows the *target* table's flags — see
+    [Nested writes](#nested-writes)
 -   `Mutation` is omitted when *no* table generates a mutation, and kept when one still does
 -   Some operations are built out of others, and the generator knows which. A table that
     asks for `upsert` while its `insert` or `update` is off — an upsert is a second write
     path past the operation you turned off — warns on the console at build time, naming the
     tables, rather than leaving that to be discovered later. So does asking for `updateMany`
-    without `update`, `groupBy` without `aggregates`, `countMutations` with neither plural
-    write, or `nestedWrites` alongside a table whose own writes are off
+    without `update`, `groupBy` without `aggregates`, or `countMutations` with neither plural
+    write. `nestedWrites` notes the nested inputs it left out because their table's write is off
 
 ## Excluding tables and columns
 
@@ -604,8 +609,9 @@ generated SDL says what a field actually holds instead of falling back to `Strin
 | `json` / `jsonb` (and `mode: 'json'`)       | `JSON`       | the parsed value                     |
 | `bigint` (and `mode: 'bigint'`)             | `BigInt`     | a decimal string                     |
 | `uuid`                                      | `UUID`       | a validated UUID string              |
-| `timestamp` / `datetime`                    | `DateTime`   | an ISO-8601 string                   |
-| `date`                                      | `Date`       | a `YYYY-MM-DD` string                |
+| `timestamp` / `datetime` (either `mode`)    | `DateTime`   | an ISO-8601 string                   |
+| SQLite `integer({ mode: 'timestamp' })` / `'timestamp_ms'` | `DateTime` | an ISO-8601 string       |
+| `date` (either `mode`)                      | `Date`       | a `YYYY-MM-DD` string                |
 
 ```graphql
 mutation {
@@ -623,15 +629,98 @@ mutation {
     `Number.MAX_SAFE_INTEGER` survive the round-trip. Integer literals are accepted on input;
     floats and non-numeric strings are rejected
 -   **`UUID`** validates the format on the way in, including inside `where` filters
+-   **`Date`** is a calendar day — no time, no offset — and is the same type in every position
+    a `date` column appears in: the object field, the create and update inputs, the
+    `DateFilter` operands, aggregate `min` / `max` and group keys. It takes and returns an
+    RFC 3339 `full-date` (`2026-09-15`) whichever `mode` the column is declared with; a
+    `mode: 'date'` column is read back from its JS `Date` as the UTC day, so no server timezone
+    shifts it. Input must name a real day: `2026-02-30`, `2026-13-45` and datetime strings like
+    `2026-09-15T10:00:00Z` are rejected. With `graphql-codegen`, map it as
+    `scalars: { Date: 'string' }`
+-   **`DateTime`** is an instant, and is likewise the same type in every position a Postgres
+    `timestamp`, MySQL `timestamp` / `datetime` or SQLite integer timestamp column appears in, with `DateTimeFilter` in
+    filters, whichever `mode` the column is declared with. It returns an ISO-8601 string in UTC.
+    MySQL stores these columns without an offset; the value is written and read as UTC
+    (`2026-09-15T10:00:00Z` is stored as `2026-09-15 10:00:00`) whatever the Node process's
+    timezone, the way drizzle itself treats them. Postgres `timestamp` without time zone is
+    treated the same way, in both modes; `timestamptz` stores the instant, and its text in
+    `mode: 'string'` (`2026-09-15 04:00:00-06`) is returned as the same instant in UTC. The
+    scalar carries milliseconds, so a `timestamp(6)` value's microseconds are truncated on read
+    and on write. A SQLite `integer({ mode: 'timestamp' })` or `integer({ mode: 'timestamp_ms' })`
+    column is `DateTime` too; it stores the instant as epoch seconds or milliseconds. Seconds
+    mode cannot hold a fraction, so it is floored (never rounded) on write —
+    `2026-09-15T10:00:00.999Z` is stored as `1789466400` and reads back as
+    `2026-09-15T10:00:00.000Z` — and filter operands on such a column are floored the same way,
+    so `eq` with the value you wrote finds the row you wrote it to
 
 The scalars are exported if you need them in a hand-written schema:
 
 ```Typescript
-import { GraphQLBigIntString, GraphQLDate, GraphQLDateTime, GraphQLJSON, GraphQLUUID } from 'drizzle-graphql'
+import { GraphQLBigIntString, GraphQLDate, GraphQLDateTime, GraphQLJSON, GraphQLUUID } from '@vantreeseba/drizzle-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`.
+called in SDL, to avoid clashing with the language's own `BigInt`. `GraphQLDate` is this
+library's own `Date` scalar, not `graphql-scalars`' (whose `parseValue` returns a JS `Date`).
+
+> **Upgrading — `date` columns.** A `date` column used to be typed differently depending on
+> where it appeared and which `mode` it was declared with. Both modes are now `Date` everywhere:
+>
+> | Drizzle column | position | before | now |
+> | --- | --- | --- | --- |
+> | `date(…, { mode: 'string' })` | output | `Date` | `Date` |
+> | | create / update input | `String` | `Date` |
+> | | filter | `StringFilter` | `DateFilter` |
+> | `date(…)` / `{ mode: 'date' }` (Postgres) | output, input, min/max, group keys | `DateTime` | `Date` |
+> | | filter | `DateTimeFilter` | `DateFilter` |
+> | `date(…, { mode: 'date' })` (MySQL) | output, input, min/max, group keys | `JSON` | `Date` |
+> | | filter | `JSONFilter` | `DateFilter` |
+> | `date(…, { mode: 'string' })` (MySQL) | output, input, min/max, group keys | `String` | `Date` |
+> | | filter | `StringFilter` | `DateFilter` |
+>
+> What to change:
+>
+> -   Variables typed `String` or `DateTime` for a date field become `Date`; filters on it are
+>     `DateFilter`, which has the `DateTimeFilter` operators (`eq` / `ne` / `lt` / `lte` / `gt` /
+>     `gte` / `inArray` / `notInArray` / `isNull` / `isNotNull`) and none of the string ones
+> -   Send `YYYY-MM-DD`. A datetime string such as `2026-09-15T00:00:00.000Z` used to be
+>     truncated to its date and is now rejected
+> -   A `mode: 'date'` column read `2026-09-15T00:00:00.000Z` and now reads `2026-09-15`
+> -   In `graphql-codegen`, map `scalars: { Date: 'string' }` — the value is a string in both
+>     directions
+> -   If you passed `graphql-scalars`' `GraphQLDate` as a column override, pass this library's
+>     exported `GraphQLDate` instead. They share the name `Date`, so a schema holding both
+>     fails to build with graphql's "multiple types named Date" error
+
+> **Upgrading — MySQL `timestamp` / `datetime` columns.** These used to fall through to
+> `JSON` in `mode: 'date'` and to `String` in `mode: 'string'`. All four are now `DateTime`, as
+> Postgres `timestamp` already was:
+>
+> | Drizzle column (MySQL) | position | before | now |
+> | --- | --- | --- | --- |
+> | `timestamp(…)` / `datetime(…)` (`mode: 'date'`) | output, input, min/max, group keys | `JSON` | `DateTime` |
+> | | filter | `JSONFilter` | `DateTimeFilter` |
+> | `timestamp(…)` / `datetime(…)` with `{ mode: 'string' }` | output, input, min/max, group keys | `String` | `DateTime` |
+> | | filter | `StringFilter` | `DateTimeFilter` |
+>
+> Variables for these fields become `DateTime` and their filters `DateTimeFilter`, which has no
+> `JSONFilter` / `StringFilter` operators such as `contains` or `like`. Input must be an ISO-8601
+> date-time (`2026-09-15T10:00:00Z`, or with an offset). A `mode: 'string'` column used to read
+> MySQL's own `2026-09-15 10:00:00` and now reads `2026-09-15T10:00:00.000Z`. In
+> `graphql-codegen`, map `DateTime` the way you already do for Postgres timestamps.
+
+> **Upgrading — SQLite integer timestamps.** `integer({ mode: 'timestamp' })` and
+> `integer({ mode: 'timestamp_ms' })` used to fall through to `JSON`. Both are now `DateTime`:
+>
+> | Drizzle column (SQLite) | position | before | now |
+> | --- | --- | --- | --- |
+> | `integer(…, { mode: 'timestamp' })` / `{ mode: 'timestamp_ms' }` | output, input, min/max, group keys | `JSON` | `DateTime` |
+> | | filter | `JSONFilter` | `DateTimeFilter` |
+>
+> Variables for these fields become `DateTime`, and their filters `DateTimeFilter`, which swaps
+> the JSON `path` operator for `lt` / `lte` / `gt` / `gte` / `inArray` / `notInArray`. Input must
+> be an ISO-8601 date-time; a JSON value such as a bare number is rejected. Reads are unchanged:
+> they were already ISO-8601 strings in UTC. The stored integers are unchanged too.
 
 ### Overriding a column's scalar
 
@@ -909,7 +998,7 @@ no others. The set follows the column's data type, never its name:
 | column type | `eq` `ne` `inArray` `notInArray` `isNull` `isNotNull` | `lt` `lte` `gt` `gte` | pattern operators + `insensitive` |
 | --- | --- | --- | --- |
 | text / varchar | yes | yes | yes |
-| timestamp, date | yes | yes | — |
+| timestamp (`DateTimeFilter`), date (`DateFilter`) | yes | yes | — |
 | int, float, bigint, decimal | yes | yes | — |
 | uuid | yes | yes | — |
 | boolean | yes | — | — |
@@ -1531,6 +1620,32 @@ mutation {
 -   A `set` that carries only relation fields is a valid update: it changes what the row is
     attached to without rewriting the row
 
+### The target table's own rules
+
+A nested write is a write to another table, so it follows that table's rules, not just the
+root field's:
+
+-   **`scope`** narrows the rows `connect` / `disconnect` / `set` can reach, and
+    **`contextValues`** stamp the rows a nested `create` inserts
+-   **`features`**: each nested input is generated only when the table it writes has that
+    write turned on. Whatever is left out is noted on the console at build time, and a
+    relation with nothing left loses its field altogether
+
+    | Input | Needs, on the table it writes |
+    | --- | --- |
+    | `create` | the target's `insert` (and its `update` too on a to-one whose nullable key lives on the target, since attaching detaches the previous row) |
+    | `connect` / `disconnect` / `set`, key on the target | the target's `update` |
+    | `connect` / `disconnect`, key on the parent | nothing — only the parent's own row changes |
+    | many-to-many `connect` | the junction's `insert` |
+    | many-to-many `disconnect` | the junction's `delete` |
+    | many-to-many `set` | the junction's `insert` and `delete` |
+
+    An excluded junction table takes its relation's inputs with it. A table whose writes are
+    reserved for a hand-written mutation (`insert: false`) can therefore no longer be written
+    by another table's nested `create` either
+-   **`onWrite`**: the hooks of the table a nested statement writes run too — see
+    [Nested writes and hooks](#nested-writes-and-hooks)
+
 ### Many-to-many relations
 
 A relation declared with `.through()` is written by inserting and deleting rows of its
@@ -2034,7 +2149,7 @@ To control the boundary yourself, open a transaction and put it on the GraphQL c
 the exported `drizzleExecutorKey`:
 
 ```Typescript
-import { buildSchema, drizzleExecutorKey } from 'drizzle-graphql'
+import { buildSchema, drizzleExecutorKey } from '@vantreeseba/drizzle-graphql'
 
 const { schema } = buildSchema(db)
 
@@ -2161,6 +2276,7 @@ The payload:
 | `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 |
+| `nested` | `{ parentTable, relation, op }` when a [nested write](#nested-writes-and-hooks) wrote the rows; `undefined` at the mutation field's own table |
 
 -   **`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
@@ -2170,11 +2286,58 @@ The payload:
     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.
+-   With `nestedWrites`, the hooks of **every table a nested write reaches** fire too —
+    below.
 
 A build with no `onWrite` opens exactly the transactions it did before.
 
+### Nested writes and hooks
+
+A nested `create` / `connect` / `disconnect` / `set` runs the `before` and `after` hooks of the
+table its statement writes, on the same `tx`, with `payload.nested` saying where it came from:
+
+```Typescript
+onWrite: {
+    todos: {
+        before: async ({ nested, args, tx }) => { /* runs ahead of the nested statement too */ },
+        after: async ({ operation, rows, nested, tx }) => {
+            // createProjectsSingle(values: { …, todos: { create: [ … ] } }) arrives here as
+            // operation: 'insert', nested: { parentTable: 'projects', relation: 'todos', op: 'create' }
+            for (const row of rows) await assertOwnsProject(tx, row.projectId)
+        },
+        columns: ['projectId'],
+    },
+}
+```
+
+| Nested input | `table` | `operation` |
+| --- | --- | --- |
+| `create` | the target | `insert` |
+| `connect` / `disconnect` / `set`, key on the target | the target | `update` (the foreign key moved; nothing is deleted) |
+| `connect` / `disconnect`, key on the parent | — | no target hook: only the parent's row changes, and its own hook sees that |
+| many-to-many `connect` | the junction | `insert` |
+| many-to-many `disconnect` | the junction | `delete` |
+| many-to-many `set` | the junction | `delete` (the old links), then `insert` (the new ones) |
+
+-   **`nested`** is `{ parentTable, relation, op }` — the Drizzle schema key of the table whose
+    input carried the relation field, the relation's name, and which of its inputs this is.
+    It is `undefined` at the mutation field's own table, so a hook that only cares about root
+    writes starts with `if (payload.nested) return`
+-   **One call per input and operation**, not per row: a nested `create` of three rows is one
+    `insert` call with three rows, and an update whose `where` matched several parents hands
+    the hook every child it wrote across all of them. A to-one `connect` that also detaches
+    the row attached before is one `update` call holding both rows; a detached row's key is
+    `null`
+-   **`rows`** hold the table's primary key and the join column(s) the statement changed — a
+    nested write has no client selection of its own — plus whatever the hook names in
+    `columns`
+-   **`args`, `context` and `info`** are the root mutation field's; **`single`** says whether the
+    relation is a to-one
+-   **`before`** runs ahead of that input's first statement, **`after`** once its last has
+    returned, and both inside the transaction every nested write opens — so a hook on a child
+    table can roll the whole tree back, the parent row included, even when the root field has
+    no hook of its own
+
 
 ## Relations & N+1 handling