@vantreeseba/drizzle-graphql 14.0.0 → 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)),
@@ -606,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 {
@@ -625,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
 
@@ -911,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 | — | — |
@@ -2062,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)