@nxgt/graphql-codegen-zod 0.1.0 → 0.2.0

package/README.md

@@ -3,7 +3,8 @@
 A [graphql-codegen](https://the-guild.dev/graphql/codegen) plugin that writes
 Zod 4 schemas, and their TypeScript types, from your SDL: one per enum and per
 input type, one per field that takes arguments, one per named operation's
-variables. It carries every `@constraint` of
+variables, one per object type, interface and union, and one per named
+operation's result and per fragment. It carries every `@constraint` of
 [`@nxgt/graphql-validation`](https://www.npmjs.com/package/@nxgt/graphql-validation),
 through that package's own rules, so the server (`withValidation`) and the
 generated code accept and refuse the same values. For graphql-codegen 5 to 7
@@ -29,18 +30,37 @@ run `withValidation` on a server.
 
 ## Setup
 
-Declare `@constraint` in the schema codegen reads, with `constraintTypeDefs`
-or the `.graphqls` file that package ships. Without the directive nothing is
-constrained; plain types are still generated.
+Write the SDL files codegen reads: `@constraint` from
+`@nxgt/graphql-validation` and the custom scalars from `@nxgt/graphql-scalars`.
+Install both, so their bins are yours, whatever the package manager links:
+`bun add @nxgt/graphql-validation @nxgt/graphql-scalars` (the generated file
+imports `@nxgt/graphql-scalars` at run time anyway). Without the directive
+nothing is constrained; plain types are still generated.
 
-Then add the plugin, writing to **its own file**:
+```sh
+bunx nxgt-graphql-validation typedefs --out   # generated/graphql/constraint.graphqls
+bunx nxgt-graphql-scalars typedefs --out      # generated/graphql/scalars.graphqls
+```
+
+Both bins are described in the
+[validation](https://www.npmjs.com/package/@nxgt/graphql-validation#ide-support)
+and [scalars](https://www.npmjs.com/package/@nxgt/graphql-scalars#the-sdl-as-a-file)
+READMEs. `typedefs DateTime Long --out` keeps only the scalars you use. Or skip the CLI and list
+`node_modules/@nxgt/graphql-validation/graphql/constraint.graphqls` and
+`node_modules/@nxgt/graphql-scalars/graphql/scalars.graphqls` in `schema`.
+
+Then add the plugin, writing to **its own file**, with those files in `schema`:
 
 ```ts
 // codegen.ts
 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
-	schema: 'src/schema/**/*.graphql',
+	schema: [
+		'generated/graphql/constraint.graphqls',
+		'generated/graphql/scalars.graphqls',
+		'src/schema/**/*.graphql',
+	],
 	documents: 'src/operations/**/*.graphql',
 	generates: {
 		'src/generated/zod.ts': {
@@ -55,11 +75,24 @@ export default config;
 The plugin writes types named as `@graphql-codegen/typescript` names them
 (`SignUpInput`, `MutationSignUpArgs`), which would collide with that plugin's
 in one file. Its `*Args` and `*Variables` types can replace the typescript
-plugin's.
+plugin's; so can its object types, interfaces and unions (`User`), or
+`objects: false` leaves them to that plugin. Its `*Query`, `*Mutation` and
+`*Fragment` types can replace typescript-operations' (`SearchQuery`,
+`UserFieldsFragment`), or `operations: false` leaves them to it.
 
 `scalarSchemas` supplies a Zod schema for each custom scalar of the schema;
 see [Scalars](docs/guide/output.md#scalars).
 
+Run codegen, once or on every change:
+
+```sh
+bunx graphql-codegen --config codegen.ts
+bunx graphql-codegen --config codegen.ts --watch
+```
+
+or add `"codegen": "graphql-codegen"` to the `scripts` of `package.json` and
+run `bun run codegen`.
+
 ## Usage
 
 ### On the server: type the resolvers
@@ -76,6 +109,24 @@ export const signUp = (_: unknown, { input }: MutationSignUpArgs) => {
 };
 ```
 
+### On the server: type what a resolver returns
+
+Object types, interfaces and unions are typed
+`z.output`: custom scalars decoded, `__typename` optional, nullable fields
+optional.
+
+```ts
+import type { User } from './generated/zod';
+
+export const me = (): User => ({ id: 'u_1', name: 'Al', joined: new Date() });
+```
+
+`zUser.parse(value)` reads a wire value: a `DateTime` string becomes a
+`Date`, and a field the schema does not declare is dropped. To check what a
+resolver returns, which holds a `Date`, encode it back to the wire form:
+`z.encode(zUser, value)`, or `z.safeEncode(zUser, value)` for a result. A
+resolver's string for a `DateTime` is refused.
+
 ### On the client: check before sending
 
 Variables are typed `z.input`: what a client sends. A schema per named
@@ -92,6 +143,32 @@ if (!result.success) {
 }
 ```
 
+### On the client: parse the response
+
+An operation's result is typed `z.output`: what the response holds, custom
+scalars decoded. An abstract type's selection is a union on `__typename` when
+its members select different fields, so checking it narrows.
+
+```graphql
+query Search($text: String!) {
+  search(text: $text) {
+    __typename
+    ... on User { id joined }
+    ... on Post { id title }
+  }
+}
+```
+
+```ts
+import { zSearchQuery } from './generated/zod';
+
+const search = zSearchQuery.parse(response.data).search;
+for (const hit of search) {
+	if (hit.__typename === 'User') hit.joined.getFullYear(); // a Date
+	else hit.title; // Post
+}
+```
+
 What is generated, how it is named, defaults, recursion, `@oneOf` and scalars
 are in [Output](docs/guide/output.md).
 
@@ -106,6 +183,8 @@ are in [Output](docs/guide/output.md).
 | `typesPrefix`, `typesSuffix` | `string` | none | around each type's name |
 | `addUnderscoreToArgsType` | `boolean` | `false` | `Query_FindUserArgs` |
 | `dedupeOperationSuffix`, `omitOperationSuffix` | `boolean` | `false` | as in `typescript-operations` |
+| `objects` | `boolean` | `true` | write the object types, interfaces and unions; `false` writes no object types, interfaces or unions; results are still written unless `operations: false` |
+| `operations` | `boolean` | `true` | write each named operation's result and each fragment; `false` writes none, the variables stay |
 
 Each is detailed in [Output](docs/guide/output.md).
 
@@ -128,10 +207,19 @@ Each is detailed in [Output](docs/guide/output.md).
   [validation troubleshooting](https://github.com/softistx/nxgt-graphql/blob/develop/packages/graphql-validation/docs/troubleshooting.md).
 - A custom scalar mapped nowhere fails generation, naming it, rather than
   becoming an unchecked `z.unknown()`.
+- An abstract type whose possible types select different fields is a union on
+  `__typename`: select it, under one key for every member, or generation
+  fails. When they all select the same fields, no `__typename` is needed.
+- A field under `@skip`, `@include` or `@defer` may be absent: it is
+  `.optional()`.
 - Generate into a file of its own: the type names collide with the typescript
-  plugins'.
-- An input type in a cycle also declares `<Type>Input`: a GraphQL type of
-  that name fails generation. Rename it, or set `typesSuffix`.
+  plugins', `*Query` and `*Fragment` with typescript-operations'. Take them from
+  this plugin, or set `objects: false` and `operations: false`.
+- An input type in a cycle also declares `<Type>Input`, and an object type in a
+  cycle `<Type>Wire`: a GraphQL type of that name fails generation. Rename it,
+  or set `typesSuffix`.
+- 0.1.0's output needs both `objects: false` and `operations: false`: a custom
+  scalar an operation selects needs a schema, whichever option is set alone.
 
 Every error and its fix is in [Troubleshooting](docs/troubleshooting.md).
 

package/dist/collect-fields.d.ts

@@ -0,0 +1,24 @@
+import { type FieldNode, type FragmentDefinitionNode, type GraphQLObjectType, type GraphQLSchema, type SelectionSetNode } from 'graphql';
+/** A selection set, and whether the response may leave it out. */
+export interface Selected {
+    readonly set: SelectionSetNode;
+    readonly conditional: boolean;
+}
+/** A response key: its field, every node selecting it, if it may be absent. */
+export interface Collected {
+    readonly name: string;
+    readonly nodes: {
+        readonly node: FieldNode;
+        readonly conditional: boolean;
+    }[];
+    optional: boolean;
+}
+/**
+ * The fields `sets` select on `type`, by response key, as graphql's
+ * CollectFields gathers them for every value of the variables: inline
+ * fragments and spreads whose type condition `type` satisfies, the same
+ * key's nodes merged, each node keeping whether it may be left out, so a
+ * sub-field only a conditional node selects stays optional.
+ */
+export declare function collectFields(schema: GraphQLSchema, fragments: ReadonlyMap<string, FragmentDefinitionNode>, type: GraphQLObjectType, sets: readonly Selected[]): Map<string, Collected>;
+//# sourceMappingURL=collect-fields.d.ts.map

package/dist/collect-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-fields.d.ts","sourceRoot":"","sources":["../src/collect-fields.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,SAAS,EACd,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAIlB,KAAK,gBAAgB,EACrB,MAAM,SAAS,CAAC;AAEjB,kEAAkE;AAClE,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC9B;AAED,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IAC9E,QAAQ,EAAE,OAAO,CAAC;CAClB;AAKD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC5B,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,EACtD,IAAI,EAAE,iBAAiB,EACvB,IAAI,EAAE,SAAS,QAAQ,EAAE,GACvB,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CA8CxB"}

package/dist/config.d.ts

@@ -34,6 +34,16 @@ export interface CodegenZodConfig {
     readonly addUnderscoreToArgsType?: boolean;
     readonly dedupeOperationSuffix?: boolean;
     readonly omitOperationSuffix?: boolean;
+    /**
+     * The SDL's object types, interfaces and unions, as what a resolver
+     * returns: `zUser`, `User`. Default `true`.
+     */
+    readonly objects?: boolean;
+    /**
+     * Each named operation's result and each fragment, as the response
+     * holds them: `zUserQuery`, `UserFieldsFragment`. Default `true`.
+     */
+    readonly operations?: boolean;
 }
 /** A file of `documents`, as graphql-codegen hands it to a plugin. */
 export interface DocumentFile {

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,gEAAgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EACvB,MAAM,GACN,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,GAC1B;QACA,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;QACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAC9B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;KACtC,CAAC;IACL,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,gEAAgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EACvB,MAAM,GACN,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,GAC1B;QACA,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;QACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAC9B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;KACtC,CAAC;IACL,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC"}

package/dist/cycles.d.ts

@@ -6,4 +6,11 @@ import { type GraphQLSchema } from 'graphql';
  * types out.
  */
 export declare function inputCycles(schema: GraphQLSchema): ReadonlySet<string>;
+/**
+ * The object types that reach themselves through their fields, an
+ * interface's or a union's members included: TypeScript infers such a
+ * schema only so deep (TS2589 past a loop of ten), so the plugin writes
+ * their types out.
+ */
+export declare function outputCycles(schema: GraphQLSchema): ReadonlySet<string>;
 //# sourceMappingURL=cycles.d.ts.map

package/dist/cycles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cycles.d.ts","sourceRoot":"","sources":["../src/cycles.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,aAAa,EAGlB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,WAAW,CAAC,MAAM,CAAC,CAOtE"}
+{"version":3,"file":"cycles.d.ts","sourceRoot":"","sources":["../src/cycles.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,aAAa,EAMlB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,WAAW,CAAC,MAAM,CAAC,CAUtE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,WAAW,CAAC,MAAM,CAAC,CAavE"}

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import type { CodegenZodConfig, DocumentFile } from './config';
 export type { CodegenZodConfig, DocumentFile } from './config';
 /**
  * The graphql-codegen plugin: Zod schemas, and their types, for the
- * schema's enums, input types and field arguments, and for the variables of
- * each operation in `documents`, with every `@constraint` of
+ * schema's enums, input types, field arguments, object types, interfaces and
+ * unions, and for the variables of each operation in `documents`, with every `@constraint` of
  * `@nxgt/graphql-validation`. It refuses a schema `withValidation` would
  * refuse, with the same message.
  */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,KAAK,aAAa,EAIlB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAQ/D,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE/D;;;;;;GAMG;AACH,wBAAsB,MAAM,CAC3B,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,YAAY,EAAE,EAClC,MAAM,GAAE,gBAAqB,EAC7B,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACjD,OAAO,CAAC,MAAM,CAAC,CAiCjB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,KAAK,aAAa,EAIlB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAU/D,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE/D;;;;;;GAMG;AACH,wBAAsB,MAAM,CAC3B,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,YAAY,EAAE,EAClC,MAAM,GAAE,gBAAqB,EAC7B,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACjD,OAAO,CAAC,MAAM,CAAC,CAqCjB"}