@vantreeseba/drizzle-graphql 4.1.0 → 5.0.0

package/README.md

@@ -96,12 +96,14 @@ reach:
 const { schema } = buildSchema(db, {
     features: {
         aggregates: false,        // <plural>Aggregate root queries
+        groupBy: false,           // <plural>GroupBy root queries
         relationAggregates: false, // <relation>Aggregate fields on object types
         distinct: false,          // the `distinct` argument on list queries
         insert: false,            // create<Table> / create<Table>Single mutations
-        update: false,            // update<Table> mutations
-        delete: false,            // delete<Table> mutations
+        update: false,            // update<Table> / update<Table>Single mutations
+        delete: false,            // delete<Table> / delete<Table>Single mutations
         upsert: true,             // upsert<Table> / upsert<Table>Single mutations (off by default)
+        requireWhere: true,       // make `where` non-null on plural update/delete (off by default)
     },
 })
 ```
@@ -110,6 +112,8 @@ const { schema } = buildSchema(db, {
     changes nothing else
 -   `upsert` is the exception: it defaults to `false`, so the upsert mutations and their
     conflict input only exist if you ask for them
+-   `groupBy` needs `aggregates`: it reuses those output types, so turning `aggregates` off
+    turns the group-by queries off with it
 -   Turning off `insert` or `update` also drops the input type that only that mutation
     used (`Create<Type>Input` / `Update<Type>Input`)
 -   Turning off all three mutation features omits the `Mutation` type entirely, the same as
@@ -201,8 +205,10 @@ A **to-many** relation takes a `some` / `none` / `every` wrapper
 -   `some: {}` means "at least one related row exists"; `none: {}` means "none exist"
 -   Several modes may be given at once and are `AND`ed together
 -   A relation whose name collides with a column name is skipped — the column keeps the field
--   Many-to-many relations declared with `.through()` are not filterable yet and are left out
-    of the filter input
+-   Many-to-many relations declared with `.through()` are filterable too: the `EXISTS`
+    subquery joins the junction table to the target, so
+    `users(where: { roles: { some: { name: { eq: "admin" } } } })` works the same as a direct
+    to-many relation
 
 ## Aggregate queries
 
@@ -253,7 +259,72 @@ The optional `where` argument takes the same filter input as the table's list qu
 applied to every aggregate in the selection. All requested aggregates are computed in a
 single `SELECT`, and on an empty result set `count` is `0` while the other values are `null`.
 
-Grouping (`groupBy`) is not supported yet.
+Add `groupBy` to get the same numbers one row per group — see [Group by](#group-by).
+
+## Group by
+
+Every table with aggregates also gets a `<tableName>GroupBy` query (e.g. `postsGroupBy`): the
+same aggregates as `<tableName>Aggregate`, computed once per distinct combination of the
+columns you group by.
+
+```graphql
+{
+    postsGroupBy(
+        groupBy: [authorId, published]
+        where: { createdAt: { gte: "2024-01-01T00:00:00Z" } }
+        having: { count: { gte: 5 } }
+    ) {
+        group {
+            authorId
+            published
+        }
+        count
+        avg {
+            views
+        }
+        max {
+            createdAt
+        }
+    }
+}
+```
+
+-   `groupBy` is required and takes one or more values of the table's `<Type>GroupByColumn`
+    enum. It holds the orderable columns plus booleans — anything the database can group on.
+    An empty list is an error, and repeated columns are ignored
+-   `group` is a `<Type>GroupKeys!` object with one nullable field per groupable column, typed
+    like the table's own column. Columns the query did not group by come back as `null`, which
+    a column whose grouped value really is `NULL` is indistinguishable from
+-   Every other field is the same one `<tableName>Aggregate` returns — `count`, `avg`, `sum`,
+    `min`, `max`, `countNonNull`, `countDistinct` — with the identical types and rules
+-   `where` filters rows before grouping; `having` filters groups after aggregating
+-   The result is `[<Type>GroupBy!]!`, one row per group, in whatever order the database
+    returns them. Add your own ordering client-side if you need it
+
+`having` mirrors the aggregate selection, with an `AggregateNumberFilter` (`eq`, `ne`, `gt`,
+`gte`, `lt`, `lte`, all `Float`) in place of each value:
+
+```graphql
+{
+    postsGroupBy(groupBy: [authorId], having: { count: { gt: 3 }, avg: { views: { gte: 100 } } }) {
+        group {
+            authorId
+        }
+        count
+    }
+}
+```
+
+-   `having: { count: … }` filters on the row count; `avg` / `sum` / `min` / `max` /
+    `countNonNull` / `countDistinct` take one filter per column, over the same columns the
+    matching aggregate type exposes
+-   Every entry in a `having` is ANDed together
+-   A group filter does not need to be in the selection — `having: { count: { gt: 3 } }` works
+    whether or not you asked for `count`
+
+The whole thing is one `SELECT … GROUP BY … HAVING …`. Set `features: { groupBy: false }` to
+leave these queries (and their `<Type>GroupBy`, `<Type>GroupKeys`, `<Type>GroupByColumn` and
+`<Type>Having` types) out of the schema; turning off `aggregates` removes them too.
 
 ## Relation aggregates
 
@@ -397,6 +468,37 @@ The build-wide `conflictDoNothing` option is deprecated in favour of this: it ap
 `create*` mutation with no way for a request to opt out. `onConflict: { action: NOTHING }` is
 the per-request replacement.
 
+## Single-row update & delete
+
+Alongside the plural `update<Table>` / `delete<Table>` mutations, every table gets an
+`update<Table>Single` / `delete<Table>Single` variant that targets exactly one row:
+
+```graphql
+mutation {
+    updateUsersSingle(where: { id: { eq: 1 } }, set: { name: "Dan" }) {
+        id
+        name
+    }
+}
+```
+
+-   `where` is **non-null** and must contain at least one filter — `where: {}` is rejected at
+    resolve time, so a Single write can never become an unbounded one
+-   The return type is the single (nullable) row type, not a list: the affected row comes back
+    directly, and **no match returns `null`** instead of an empty list
+-   If `where` matches **more than one row**, the mutation throws a `GraphQLError` and writes
+    nothing — the match is checked (`LIMIT 2`) before the write runs
+-   **MySQL** cannot return the affected row (no `RETURNING`), so its Single variants keep the
+    single-match and non-empty-`where` guarantees but return `MutationReturn` like every other
+    MySQL mutation
+-   The variants are generated under `features.update` / `features.delete`, share the plural
+    mutations' input types, and appear in `entities.mutations` for custom schemas
+
+The plural mutations still accept a missing `where` (a full-table write) by default. To rule
+that out at the type level, `features: { requireWhere: true }` makes `where` non-null on
+`update<Table>` / `delete<Table>` and rejects a `where` with no filters, exactly like the
+Single variants. It defaults to `false` for backwards compatibility.
+
 ## Query cost
 
 Generated fields carry a `complexity` hint in their GraphQL extensions, ready for
@@ -408,7 +510,7 @@ fields it mentions:
 | Field | Cost |
 | --- | --- |
 | List query, to-many relation | `(limit ?? defaultListSize) * childComplexity` |
-| Aggregate query, `<relation>Aggregate` | `aggregateCost + childComplexity` |
+| Aggregate query, group-by query, `<relation>Aggregate` | `aggregateCost + childComplexity` |
 | Everything else | no hint — your estimator's default applies |
 
 So `users(limit: 20) { id posts(limit: 5) { id } }` costs `20 * (1 + 5 * 1)` = 120, while the
@@ -555,6 +657,28 @@ Generated schemas resolve nested relations without N+1 query explosions:
 > **SQLite 3.25+**. Relations without pagination, and all other query/mutation paths,
 > have no such requirement.
 
+### Relation nullability
+
+A **to-many** relation field is always `[Target!]!`. A **to-one** relation field is
+nullable by default, but honors the relation's declared optionality: declaring
+`optional: false` on a Drizzle `one` relation — the assertion that the related row always
+exists, i.e. a `NOT NULL` foreign key — emits the field as `Target!`:
+
+```Typescript
+const relations = buildRelations({ Users, Posts }, {
+    Posts: {
+        // posts.author_id is NOT NULL → author: Users!
+        author: r.one.Users({ from: r.Posts.authorId, to: r.Users.id, optional: false }),
+    },
+})
+```
+
+Only the explicit `optional: false` declaration is honored — required-ness is never
+inferred from column nullability, since a `NOT NULL` `from` column does not guarantee a
+related row exists when the constraint lives on the other side of the join. Note that on a
+required relation, a `where` argument that filters out the related row (or a dangling
+foreign key) resolves to `null` and therefore surfaces as a GraphQL non-null error.
+
 ### Overriding a relation's resolver without overfetching
 
 By default the eager `with:` pre-fetch is driven purely by the GraphQL selection set:

package/dist/README.md

@@ -96,12 +96,14 @@ reach:
 const { schema } = buildSchema(db, {
     features: {
         aggregates: false,        // <plural>Aggregate root queries
+        groupBy: false,           // <plural>GroupBy root queries
         relationAggregates: false, // <relation>Aggregate fields on object types
         distinct: false,          // the `distinct` argument on list queries
         insert: false,            // create<Table> / create<Table>Single mutations
-        update: false,            // update<Table> mutations
-        delete: false,            // delete<Table> mutations
+        update: false,            // update<Table> / update<Table>Single mutations
+        delete: false,            // delete<Table> / delete<Table>Single mutations
         upsert: true,             // upsert<Table> / upsert<Table>Single mutations (off by default)
+        requireWhere: true,       // make `where` non-null on plural update/delete (off by default)
     },
 })
 ```
@@ -110,6 +112,8 @@ const { schema } = buildSchema(db, {
     changes nothing else
 -   `upsert` is the exception: it defaults to `false`, so the upsert mutations and their
     conflict input only exist if you ask for them
+-   `groupBy` needs `aggregates`: it reuses those output types, so turning `aggregates` off
+    turns the group-by queries off with it
 -   Turning off `insert` or `update` also drops the input type that only that mutation
     used (`Create<Type>Input` / `Update<Type>Input`)
 -   Turning off all three mutation features omits the `Mutation` type entirely, the same as
@@ -201,8 +205,10 @@ A **to-many** relation takes a `some` / `none` / `every` wrapper
 -   `some: {}` means "at least one related row exists"; `none: {}` means "none exist"
 -   Several modes may be given at once and are `AND`ed together
 -   A relation whose name collides with a column name is skipped — the column keeps the field
--   Many-to-many relations declared with `.through()` are not filterable yet and are left out
-    of the filter input
+-   Many-to-many relations declared with `.through()` are filterable too: the `EXISTS`
+    subquery joins the junction table to the target, so
+    `users(where: { roles: { some: { name: { eq: "admin" } } } })` works the same as a direct
+    to-many relation
 
 ## Aggregate queries
 
@@ -253,7 +259,72 @@ The optional `where` argument takes the same filter input as the table's list qu
 applied to every aggregate in the selection. All requested aggregates are computed in a
 single `SELECT`, and on an empty result set `count` is `0` while the other values are `null`.
 
-Grouping (`groupBy`) is not supported yet.
+Add `groupBy` to get the same numbers one row per group — see [Group by](#group-by).
+
+## Group by
+
+Every table with aggregates also gets a `<tableName>GroupBy` query (e.g. `postsGroupBy`): the
+same aggregates as `<tableName>Aggregate`, computed once per distinct combination of the
+columns you group by.
+
+```graphql
+{
+    postsGroupBy(
+        groupBy: [authorId, published]
+        where: { createdAt: { gte: "2024-01-01T00:00:00Z" } }
+        having: { count: { gte: 5 } }
+    ) {
+        group {
+            authorId
+            published
+        }
+        count
+        avg {
+            views
+        }
+        max {
+            createdAt
+        }
+    }
+}
+```
+
+-   `groupBy` is required and takes one or more values of the table's `<Type>GroupByColumn`
+    enum. It holds the orderable columns plus booleans — anything the database can group on.
+    An empty list is an error, and repeated columns are ignored
+-   `group` is a `<Type>GroupKeys!` object with one nullable field per groupable column, typed
+    like the table's own column. Columns the query did not group by come back as `null`, which
+    a column whose grouped value really is `NULL` is indistinguishable from
+-   Every other field is the same one `<tableName>Aggregate` returns — `count`, `avg`, `sum`,
+    `min`, `max`, `countNonNull`, `countDistinct` — with the identical types and rules
+-   `where` filters rows before grouping; `having` filters groups after aggregating
+-   The result is `[<Type>GroupBy!]!`, one row per group, in whatever order the database
+    returns them. Add your own ordering client-side if you need it
+
+`having` mirrors the aggregate selection, with an `AggregateNumberFilter` (`eq`, `ne`, `gt`,
+`gte`, `lt`, `lte`, all `Float`) in place of each value:
+
+```graphql
+{
+    postsGroupBy(groupBy: [authorId], having: { count: { gt: 3 }, avg: { views: { gte: 100 } } }) {
+        group {
+            authorId
+        }
+        count
+    }
+}
+```
+
+-   `having: { count: … }` filters on the row count; `avg` / `sum` / `min` / `max` /
+    `countNonNull` / `countDistinct` take one filter per column, over the same columns the
+    matching aggregate type exposes
+-   Every entry in a `having` is ANDed together
+-   A group filter does not need to be in the selection — `having: { count: { gt: 3 } }` works
+    whether or not you asked for `count`
+
+The whole thing is one `SELECT … GROUP BY … HAVING …`. Set `features: { groupBy: false }` to
+leave these queries (and their `<Type>GroupBy`, `<Type>GroupKeys`, `<Type>GroupByColumn` and
+`<Type>Having` types) out of the schema; turning off `aggregates` removes them too.
 
 ## Relation aggregates
 
@@ -397,6 +468,37 @@ The build-wide `conflictDoNothing` option is deprecated in favour of this: it ap
 `create*` mutation with no way for a request to opt out. `onConflict: { action: NOTHING }` is
 the per-request replacement.
 
+## Single-row update & delete
+
+Alongside the plural `update<Table>` / `delete<Table>` mutations, every table gets an
+`update<Table>Single` / `delete<Table>Single` variant that targets exactly one row:
+
+```graphql
+mutation {
+    updateUsersSingle(where: { id: { eq: 1 } }, set: { name: "Dan" }) {
+        id
+        name
+    }
+}
+```
+
+-   `where` is **non-null** and must contain at least one filter — `where: {}` is rejected at
+    resolve time, so a Single write can never become an unbounded one
+-   The return type is the single (nullable) row type, not a list: the affected row comes back
+    directly, and **no match returns `null`** instead of an empty list
+-   If `where` matches **more than one row**, the mutation throws a `GraphQLError` and writes
+    nothing — the match is checked (`LIMIT 2`) before the write runs
+-   **MySQL** cannot return the affected row (no `RETURNING`), so its Single variants keep the
+    single-match and non-empty-`where` guarantees but return `MutationReturn` like every other
+    MySQL mutation
+-   The variants are generated under `features.update` / `features.delete`, share the plural
+    mutations' input types, and appear in `entities.mutations` for custom schemas
+
+The plural mutations still accept a missing `where` (a full-table write) by default. To rule
+that out at the type level, `features: { requireWhere: true }` makes `where` non-null on
+`update<Table>` / `delete<Table>` and rejects a `where` with no filters, exactly like the
+Single variants. It defaults to `false` for backwards compatibility.
+
 ## Query cost
 
 Generated fields carry a `complexity` hint in their GraphQL extensions, ready for
@@ -408,7 +510,7 @@ fields it mentions:
 | Field | Cost |
 | --- | --- |
 | List query, to-many relation | `(limit ?? defaultListSize) * childComplexity` |
-| Aggregate query, `<relation>Aggregate` | `aggregateCost + childComplexity` |
+| Aggregate query, group-by query, `<relation>Aggregate` | `aggregateCost + childComplexity` |
 | Everything else | no hint — your estimator's default applies |
 
 So `users(limit: 20) { id posts(limit: 5) { id } }` costs `20 * (1 + 5 * 1)` = 120, while the
@@ -555,6 +657,28 @@ Generated schemas resolve nested relations without N+1 query explosions:
 > **SQLite 3.25+**. Relations without pagination, and all other query/mutation paths,
 > have no such requirement.
 
+### Relation nullability
+
+A **to-many** relation field is always `[Target!]!`. A **to-one** relation field is
+nullable by default, but honors the relation's declared optionality: declaring
+`optional: false` on a Drizzle `one` relation — the assertion that the related row always
+exists, i.e. a `NOT NULL` foreign key — emits the field as `Target!`:
+
+```Typescript
+const relations = buildRelations({ Users, Posts }, {
+    Posts: {
+        // posts.author_id is NOT NULL → author: Users!
+        author: r.one.Users({ from: r.Posts.authorId, to: r.Users.id, optional: false }),
+    },
+})
+```
+
+Only the explicit `optional: false` declaration is honored — required-ness is never
+inferred from column nullability, since a `NOT NULL` `from` column does not guarantee a
+related row exists when the constraint lives on the other side of the join. Note that on a
+required relation, a `where` argument that filters out the related row (or a dangling
+foreign key) resolves to `null` and therefore surfaces as a GraphQL non-null error.
+
 ### Overriding a relation's resolver without overfetching
 
 By default the eager `with:` pre-fetch is driven purely by the GraphQL selection set: