@vantreeseba/drizzle-graphql 7.2.0 → 7.4.0

package/README.md

@@ -85,6 +85,39 @@ Automatically create GraphQL schema or customizable schema config fields from Dr
     })
     ```
 
+## Naming the generated types and fields
+
+By default every name comes from the table's key in the Drizzle schema: `tasks` gives type
+`Tasks`, queries `tasks` / `tasksSingle`, mutations `createTasks` / `createTasksSingle`.
+Most schemas use plural table keys and want singular type names, so that pairing is shipped
+as a preset:
+
+```Typescript
+const { schema } = buildSchema(db, { typeNameMapper: 'singularize' })
+```
+
+`tasks` then gives type `Task`, queries `tasks` (list) and `task` (single), mutations
+`createTasks` (array) and `createTask` (single), `updateTask`, `deleteTask`. Irregular
+plurals go through `pluralize`, so `people` gives `Person` / `people` / `person` and
+`addresses` gives `Address` rather than the `addresss` a naive suffix would produce. A table
+key that is already singular is pluralized for the list side, and a capitalized key is
+uncapitalized for the field side, so `tasks`, `task` and `Tasks` all land on the same names.
+
+For anything else, pass your own function — it is asked per table and may return `undefined`
+to leave that table with the default naming. The preset is exported as `singularizeMapper`
+so it can be wrapped:
+
+```Typescript
+import { buildSchema, singularizeMapper } from 'drizzle-graphql'
+
+const { schema } = buildSchema(db, {
+    typeNameMapper: (table) => (table === 'auditLog' ? undefined : singularizeMapper(table)),
+})
+```
+
+With a mapper in play the singular/plural forms are what keep the list and single fields
+apart, so `suffixes` may be empty on both sides. Without one, they must still differ.
+
 ## Choosing what gets generated
 
 Every generated operation is on by default. `features` turns individual ones off, which
@@ -124,6 +157,35 @@ const { schema } = buildSchema(db, {
     `mutations: false`
 -   List and single queries are always generated, so `Query` is never empty
 
+### Per-table operations
+
+The choice is rarely build-wide: a schema usually has a handful of tables that must not be
+deleted through the API, a handful whose writes belong to a hand-written resolver that
+enforces something, and a majority that want everything. Any flag can be a predicate
+instead of a boolean, asked once per table with the table's key in the Drizzle schema:
+
+```Typescript
+const { schema } = buildSchema(db, {
+    features: {
+        delete: (table) => table !== 'auditLog',
+        update: (table) => !ownedByCustomResolver.has(table),
+        upsert: (table) => table === 'settings',
+    },
+})
+```
+
+-   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
+-   `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
+
 ## Excluding tables and columns
 
 `features` decides which *kinds* of operation exist. `exclude` decides which tables and
@@ -402,6 +464,124 @@ A **to-many** relation takes a `some` / `none` / `every` wrapper
     `users(where: { roles: { some: { name: { eq: "admin" } } } })` works the same as a direct
     to-many relation
 
+## Matching lists of values
+
+`inArray` / `notInArray` take a list of candidate values and compile to SQL `IN` / `NOT IN`.
+Two things about them are worth stating explicitly.
+
+**An empty list is answered, not rejected.** A caller building a filter from a variable often
+ends up with an empty list, and that list has a well-defined meaning: nothing is `IN ()` and
+everything is `NOT IN ()`.
+
+```graphql
+{
+    # no rows
+    posts(where: { id: { inArray: [] } }) {
+        id
+    }
+
+    # every row
+    posts(where: { id: { notInArray: [] } }) {
+        id
+    }
+}
+```
+
+The same rule applies to the Postgres array-column operators: `hasSome: []` matches nothing
+(overlapping with no elements is never true) and `hasEvery: []` matches everything (every
+array contains all zero of them).
+
+**The list's own order can be the sort order.** SQL returns `IN` matches in whatever order it
+likes, so a caller that fetches rows by a ranked list of ids normally has to re-sort them
+client-side. Setting `matchFilterOrder` on an `orderBy` entry sorts by the row's position in
+that column's `inArray` list instead of by the column's value:
+
+```graphql
+{
+    posts(
+        where: { id: { inArray: [7, 3, 12] } }
+        orderBy: { id: { direction: asc, priority: 1, matchFilterOrder: true } }
+    ) {
+        id # → 7, 3, 12
+    }
+}
+```
+
+-   `direction: asc` keeps the list's order; `desc` reverses it
+-   It needs an `inArray` filter on the same column, at the top level of `where` — an
+        `inArray` buried inside an `OR` branch raises an error rather than being guessed at
+-   It interleaves with the other `orderBy` entries by `priority` like any ordering key, and
+        works on relation fields as well as root lists
+-   It compiles to a `CASE` ladder over the list values, so it behaves identically on all
+        three dialects and every value stays a bound parameter
+-   It cannot be combined with `after` or `distinct`: a row's position in the request's own
+        filter list is not a value of the row, so it cannot be encoded into a cursor or rebuilt
+        against a subquery. Selecting `cursor` under it yields `null` rather than an error
+
+## Filtering inside JSON documents
+
+`json` / `jsonb` columns get a `path` filter that compares the value at one path inside the
+document, alongside the whole-document `eq` / `ne` / `contains` operators:
+
+```graphql
+{
+    users(where: { meta: { path: { path: ["profile", "level"], gt: 2 } } }) {
+        id
+    }
+}
+```
+
+`path` walks the document key by key from the root; an all-digits key indexes an array
+(`["tags", "0"]`). Several predicates may be given at once and are `AND`ed:
+
+```graphql
+{
+    users(
+        where: {
+            meta: {
+                path: [
+                    { path: ["profile", "role"], eq: "admin" }
+                    { path: ["profile", "level"], gte: 3 }
+                ]
+            }
+        }
+    ) {
+        id
+    }
+}
+```
+
+Available operators are `eq` / `ne` / `lt` / `lte` / `gt` / `gte`, the safe string matchers
+`startsWith` / `endsWith` / `contains` (plus their case-insensitive `i`-prefixed forms), and
+`isNull` / `isNotNull`. A missing key and a JSON `null` both read as null.
+
+**How the value is compared** is decided by the operand: a GraphQL number compares
+numerically, a boolean as a boolean, and anything else as text. Pass `as: TEXT | NUMBER |
+BOOLEAN` when the operand's type doesn't match the document's — comparing a numeric field
+against a `String` variable, say:
+
+```graphql
+{
+    users(where: { meta: { path: { path: ["profile", "level"], as: NUMBER, eq: "3" } } }) {
+        id
+    }
+}
+```
+
+A value of the wrong shape never matches rather than failing the query: `gt: 0` against a
+document whose path holds `"admin"` returns no rows on every dialect. That takes a guard on
+each one — Postgres errors outright on a bad `::numeric`, MySQL quietly casts a non-numeric
+string to `0`, and SQLite's cross-type ordering would otherwise sort every string above every
+number.
+
+Note that `contains` means different things at the two levels, because a path names a scalar:
+on the column it is structural JSON containment (Postgres `@>` / MySQL `JSON_CONTAINS`),
+inside a `path` filter it is substring matching on the extracted value.
+
+Path filters combine with `AND` / `OR` / `NOT` like any other operator, and are accepted
+everywhere a filter is — list, single and aggregate queries, `update` / `delete`, and the
+`where` argument on a relation field.
+
 ## Aggregate queries
 
 Every table also gets an aggregate query field — `<tableName>Aggregate` (e.g. `usersAggregate`),
@@ -642,8 +822,8 @@ field, and passing it back as `after` resumes strictly after that row.
 -   Dates and bigints round-trip losslessly through the cursor
 -   A cursor is only valid under the ordering it was issued for — reusing it with a
     different `orderBy` (or a malformed/corrupted cursor) returns a `GraphQLError`
--   `after` cannot be combined with `distinct`, and a table with no primary key cannot use
-    cursor pagination (its `cursor` field resolves to `null`)
+-   `after` cannot be combined with `distinct` or with `matchFilterOrder`, and a table with
+    no primary key cannot use cursor pagination (its `cursor` field resolves to `null`)
 -   If a table has a real column named `cursor`, the column wins and the meta field is
     skipped
 

package/dist/README.md

@@ -85,6 +85,39 @@ Automatically create GraphQL schema or customizable schema config fields from Dr
     })
     ```
 
+## Naming the generated types and fields
+
+By default every name comes from the table's key in the Drizzle schema: `tasks` gives type
+`Tasks`, queries `tasks` / `tasksSingle`, mutations `createTasks` / `createTasksSingle`.
+Most schemas use plural table keys and want singular type names, so that pairing is shipped
+as a preset:
+
+```Typescript
+const { schema } = buildSchema(db, { typeNameMapper: 'singularize' })
+```
+
+`tasks` then gives type `Task`, queries `tasks` (list) and `task` (single), mutations
+`createTasks` (array) and `createTask` (single), `updateTask`, `deleteTask`. Irregular
+plurals go through `pluralize`, so `people` gives `Person` / `people` / `person` and
+`addresses` gives `Address` rather than the `addresss` a naive suffix would produce. A table
+key that is already singular is pluralized for the list side, and a capitalized key is
+uncapitalized for the field side, so `tasks`, `task` and `Tasks` all land on the same names.
+
+For anything else, pass your own function — it is asked per table and may return `undefined`
+to leave that table with the default naming. The preset is exported as `singularizeMapper`
+so it can be wrapped:
+
+```Typescript
+import { buildSchema, singularizeMapper } from 'drizzle-graphql'
+
+const { schema } = buildSchema(db, {
+    typeNameMapper: (table) => (table === 'auditLog' ? undefined : singularizeMapper(table)),
+})
+```
+
+With a mapper in play the singular/plural forms are what keep the list and single fields
+apart, so `suffixes` may be empty on both sides. Without one, they must still differ.
+
 ## Choosing what gets generated
 
 Every generated operation is on by default. `features` turns individual ones off, which
@@ -124,6 +157,35 @@ const { schema } = buildSchema(db, {
     `mutations: false`
 -   List and single queries are always generated, so `Query` is never empty
 
+### Per-table operations
+
+The choice is rarely build-wide: a schema usually has a handful of tables that must not be
+deleted through the API, a handful whose writes belong to a hand-written resolver that
+enforces something, and a majority that want everything. Any flag can be a predicate
+instead of a boolean, asked once per table with the table's key in the Drizzle schema:
+
+```Typescript
+const { schema } = buildSchema(db, {
+    features: {
+        delete: (table) => table !== 'auditLog',
+        update: (table) => !ownedByCustomResolver.has(table),
+        upsert: (table) => table === 'settings',
+    },
+})
+```
+
+-   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
+-   `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
+
 ## Excluding tables and columns
 
 `features` decides which *kinds* of operation exist. `exclude` decides which tables and
@@ -402,6 +464,124 @@ A **to-many** relation takes a `some` / `none` / `every` wrapper
     `users(where: { roles: { some: { name: { eq: "admin" } } } })` works the same as a direct
     to-many relation
 
+## Matching lists of values
+
+`inArray` / `notInArray` take a list of candidate values and compile to SQL `IN` / `NOT IN`.
+Two things about them are worth stating explicitly.
+
+**An empty list is answered, not rejected.** A caller building a filter from a variable often
+ends up with an empty list, and that list has a well-defined meaning: nothing is `IN ()` and
+everything is `NOT IN ()`.
+
+```graphql
+{
+    # no rows
+    posts(where: { id: { inArray: [] } }) {
+        id
+    }
+
+    # every row
+    posts(where: { id: { notInArray: [] } }) {
+        id
+    }
+}
+```
+
+The same rule applies to the Postgres array-column operators: `hasSome: []` matches nothing
+(overlapping with no elements is never true) and `hasEvery: []` matches everything (every
+array contains all zero of them).
+
+**The list's own order can be the sort order.** SQL returns `IN` matches in whatever order it
+likes, so a caller that fetches rows by a ranked list of ids normally has to re-sort them
+client-side. Setting `matchFilterOrder` on an `orderBy` entry sorts by the row's position in
+that column's `inArray` list instead of by the column's value:
+
+```graphql
+{
+    posts(
+        where: { id: { inArray: [7, 3, 12] } }
+        orderBy: { id: { direction: asc, priority: 1, matchFilterOrder: true } }
+    ) {
+        id # → 7, 3, 12
+    }
+}
+```
+
+-   `direction: asc` keeps the list's order; `desc` reverses it
+-   It needs an `inArray` filter on the same column, at the top level of `where` — an
+        `inArray` buried inside an `OR` branch raises an error rather than being guessed at
+-   It interleaves with the other `orderBy` entries by `priority` like any ordering key, and
+        works on relation fields as well as root lists
+-   It compiles to a `CASE` ladder over the list values, so it behaves identically on all
+        three dialects and every value stays a bound parameter
+-   It cannot be combined with `after` or `distinct`: a row's position in the request's own
+        filter list is not a value of the row, so it cannot be encoded into a cursor or rebuilt
+        against a subquery. Selecting `cursor` under it yields `null` rather than an error
+
+## Filtering inside JSON documents
+
+`json` / `jsonb` columns get a `path` filter that compares the value at one path inside the
+document, alongside the whole-document `eq` / `ne` / `contains` operators:
+
+```graphql
+{
+    users(where: { meta: { path: { path: ["profile", "level"], gt: 2 } } }) {
+        id
+    }
+}
+```
+
+`path` walks the document key by key from the root; an all-digits key indexes an array
+(`["tags", "0"]`). Several predicates may be given at once and are `AND`ed:
+
+```graphql
+{
+    users(
+        where: {
+            meta: {
+                path: [
+                    { path: ["profile", "role"], eq: "admin" }
+                    { path: ["profile", "level"], gte: 3 }
+                ]
+            }
+        }
+    ) {
+        id
+    }
+}
+```
+
+Available operators are `eq` / `ne` / `lt` / `lte` / `gt` / `gte`, the safe string matchers
+`startsWith` / `endsWith` / `contains` (plus their case-insensitive `i`-prefixed forms), and
+`isNull` / `isNotNull`. A missing key and a JSON `null` both read as null.
+
+**How the value is compared** is decided by the operand: a GraphQL number compares
+numerically, a boolean as a boolean, and anything else as text. Pass `as: TEXT | NUMBER |
+BOOLEAN` when the operand's type doesn't match the document's — comparing a numeric field
+against a `String` variable, say:
+
+```graphql
+{
+    users(where: { meta: { path: { path: ["profile", "level"], as: NUMBER, eq: "3" } } }) {
+        id
+    }
+}
+```
+
+A value of the wrong shape never matches rather than failing the query: `gt: 0` against a
+document whose path holds `"admin"` returns no rows on every dialect. That takes a guard on
+each one — Postgres errors outright on a bad `::numeric`, MySQL quietly casts a non-numeric
+string to `0`, and SQLite's cross-type ordering would otherwise sort every string above every
+number.
+
+Note that `contains` means different things at the two levels, because a path names a scalar:
+on the column it is structural JSON containment (Postgres `@>` / MySQL `JSON_CONTAINS`),
+inside a `path` filter it is substring matching on the extracted value.
+
+Path filters combine with `AND` / `OR` / `NOT` like any other operator, and are accepted
+everywhere a filter is — list, single and aggregate queries, `update` / `delete`, and the
+`where` argument on a relation field.
+
 ## Aggregate queries
 
 Every table also gets an aggregate query field — `<tableName>Aggregate` (e.g. `usersAggregate`),
@@ -642,8 +822,8 @@ field, and passing it back as `after` resumes strictly after that row.
 -   Dates and bigints round-trip losslessly through the cursor
 -   A cursor is only valid under the ordering it was issued for — reusing it with a
     different `orderBy` (or a malformed/corrupted cursor) returns a `GraphQLError`
--   `after` cannot be combined with `distinct`, and a table with no primary key cannot use
-    cursor pagination (its `cursor` field resolves to `null`)
+-   `after` cannot be combined with `distinct` or with `matchFilterOrder`, and a table with
+    no primary key cannot use cursor pagination (its `cursor` field resolves to `null`)
 -   If a table has a real column named `cursor`, the column wins and the meta field is
     skipped