@nxgt/graphql-codegen-zod 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# @nxgt/graphql-codegen-zod
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+[`@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
+(ESM) and `graphql` 16 and 17.
+
+## Install
+
+```sh
+bun add -d @nxgt/graphql-codegen-zod @graphql-codegen/cli
+bun add graphql zod typescript
+```
+
+Peers, all **required**:
+
+| Peer | Range |
+| --- | --- |
+| `graphql` | `^16.11.0 \|\| ^17.0.0` |
+| `zod` | `>=4.6.5 <5` |
+| `typescript` | `^6.0.3` |
+
+`@nxgt/graphql-validation` is a dependency; you install it yourself only to
+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.
+
+Then add the plugin, writing to **its own file**:
+
+```ts
+// codegen.ts
+import type { CodegenConfig } from '@graphql-codegen/cli';
+
+const config: CodegenConfig = {
+	schema: 'src/schema/**/*.graphql',
+	documents: 'src/operations/**/*.graphql',
+	generates: {
+		'src/generated/zod.ts': {
+			plugins: ['@nxgt/graphql-codegen-zod'],
+			config: { scalarSchemas: '@nxgt/graphql-scalars' },
+		},
+	},
+};
+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.
+
+`scalarSchemas` supplies a Zod schema for each custom scalar of the schema;
+see [Scalars](docs/guide/output.md#scalars).
+
+## Usage
+
+### On the server: type the resolvers
+
+Arguments are typed `z.output`: what a resolver receives once
+`withValidation` has parsed them.
+
+```ts
+import type { MutationSignUpArgs } from './generated/zod';
+
+export const signUp = (_: unknown, { input }: MutationSignUpArgs) => {
+	// input.role is always set: its default was filled in
+	return { id: 'u_1', email: input.email };
+};
+```
+
+### On the client: check before sending
+
+Variables are typed `z.input`: what a client sends. A schema per named
+operation accepts and refuses what the server would.
+
+```ts
+import { zSignUpMutationVariables } from './generated/zod';
+
+const result = zSignUpMutationVariables.safeParse({
+	input: { email: form.email, name: form.name },
+});
+if (!result.success) {
+	for (const issue of result.error.issues) showError(issue.path, issue.message);
+}
+```
+
+What is generated, how it is named, defaults, recursion, `@oneOf` and scalars
+are in [Output](docs/guide/output.md).
+
+## Options
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `scalarSchemas` | `string` | none | module exporting a `scalarSchemas` record keyed by scalar name |
+| `zodScalars` | `Record<string, string>` | none | `'<module>#<export>'` per scalar; wins over `scalarSchemas` |
+| `schemaPrefix` | `string` | `'z'` | before each schema's name |
+| `namingConvention` | `'keep' \| 'change-case-all#<case>' \| (name) => string \| { typeNames, transformUnderscore, enumValues }` | PascalCase per underscore part | how type names are cased, as the typescript plugins read it |
+| `typesPrefix`, `typesSuffix` | `string` | none | around each type's name |
+| `addUnderscoreToArgsType` | `boolean` | `false` | `Query_FindUserArgs` |
+| `dedupeOperationSuffix`, `omitOperationSuffix` | `boolean` | `false` | as in `typescript-operations` |
+
+Each is detailed in [Output](docs/guide/output.md).
+
+## Traps
+
+- An `ID` is a string on the client: `graphql` also takes an `Int` for an
+  `ID`, the generated schema does not. Send `{ id: "5" }`.
+- A single value for a list is taken, as `graphql` takes it, for every item
+  type and at any depth: `tags: "a"` parses to `["a"]`, `contacts: { phone }`
+  to `[{ phone }]`.
+- An input type in a cycle (`Filter.and: [Filter]`) has its types written
+  out, `Filter` and `FilterInput`, and its schema is typed
+  `z.ZodType<Filter, FilterInput>`: it has no `.shape` or `.extend`.
+- Input types are `z.strictObject`: a field the schema does not declare is
+  refused.
+- A schema that declares `@constraint` must come from SDL files; an
+  introspected one fails generation.
+- The plugin refuses a schema `withValidation` would refuse, with the same
+  message; those are in the
+  [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()`.
+- 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`.
+
+Every error and its fix is in [Troubleshooting](docs/troubleshooting.md).
+
+## Documentation
+
+The package exports `plugin` and the `CodegenZodConfig` and `DocumentFile` types from `.`; graphql-codegen finds `plugin` by the package name. See [Output](docs/guide/output.md#the-plugin-function).
+
+- [Documentation index](docs/README.md)
+- Guides: [Output](docs/guide/output.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Roadmap](docs/roadmap.md)

package/dist/config.d.ts

@@ -0,0 +1,43 @@
+import type { DocumentNode } from 'graphql';
+/**
+ * The plugin's options, under `config` in `codegen.ts`. The naming options
+ * mean what they mean to `@graphql-codegen/typescript`, so the types this
+ * plugin writes carry the names the typescript plugins give them.
+ */
+export interface CodegenZodConfig {
+    /**
+     * A module exporting `scalarSchemas`, a record of Zod schemas keyed by
+     * GraphQL scalar name: `'@nxgt/graphql-scalars'`, or a path relative to
+     * the generated file.
+     */
+    readonly scalarSchemas?: string;
+    /**
+     * One scalar's schema, `'<module>#<export>'`, winning over
+     * `scalarSchemas`: `{ Money: './money#moneySchema' }`.
+     */
+    readonly zodScalars?: Readonly<Record<string, string>>;
+    /** Before each schema's name: `zSignUpInput`. Default `'z'`. */
+    readonly schemaPrefix?: string;
+    /**
+     * As the typescript plugins read it, for type names: `'keep'`,
+     * `'change-case-all#<case>'`, a function, or `{ typeNames,
+     * transformUnderscore }`. Default: PascalCase each part between
+     * underscores.
+     */
+    readonly namingConvention?: string | ((name: string) => string) | {
+        readonly typeNames?: string | ((name: string) => string);
+        readonly enumValues?: unknown;
+        readonly transformUnderscore?: boolean;
+    };
+    readonly typesPrefix?: string;
+    readonly typesSuffix?: string;
+    readonly addUnderscoreToArgsType?: boolean;
+    readonly dedupeOperationSuffix?: boolean;
+    readonly omitOperationSuffix?: boolean;
+}
+/** A file of `documents`, as graphql-codegen hands it to a plugin. */
+export interface DocumentFile {
+    readonly document?: DocumentNode | undefined;
+    readonly location?: string | undefined;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +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"}

package/dist/cycles.d.ts

@@ -0,0 +1,9 @@
+import { type GraphQLSchema } from 'graphql';
+/**
+ * The input types that reach themselves through their fields, directly
+ * (`Filter.and: [Filter]`) or through others: TypeScript cannot infer the
+ * schema of such a type once a field wraps it, so the plugin writes their
+ * types out.
+ */
+export declare function inputCycles(schema: GraphQLSchema): ReadonlySet<string>;
+//# sourceMappingURL=cycles.d.ts.map

package/dist/cycles.d.ts.map

@@ -0,0 +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"}

package/dist/defaults.d.ts

@@ -0,0 +1,21 @@
+import { type ConstValueNode, type GraphQLArgument, type GraphQLInputField, type GraphQLInputType } from 'graphql';
+/**
+ * A default's value as the client parses it: its literal coerced as
+ * graphql coerces it. An integer a JavaScript number cannot keep exact,
+ * given to an ID or a custom scalar, fails, naming `where`: the server
+ * would hand the scalar every digit. An Int or a Float rounds on both sides.
+ */
+export declare function parsedDefault(literal: ConstValueNode, type: GraphQLInputType, where: string): unknown;
+/**
+ * The default of an argument or input field as a literal: its SDL's, or,
+ * for a schema built without SDL (introspected), its value written back.
+ * graphql 16 holds that value in `defaultValue`, graphql 17 in `default`.
+ */
+export declare function defaultLiteral(input: GraphQLArgument | GraphQLInputField): ConstValueNode | undefined;
+/**
+ * A default as graphql coerces it, through lists and input objects: a
+ * single value given for a list is a list of it (`[String!] = "a"` is
+ * `["a"]`, `[[Int]] = 1` is `[[1]]`), at any depth.
+ */
+export declare function coerced(value: unknown, type: GraphQLInputType): unknown;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AACA,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,eAAe,EAEpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EAUrB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,wBAAgB,aAAa,CAC5B,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,MAAM,GACX,OAAO,CAGT;AAmCD;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,eAAe,GAAG,iBAAiB,GACxC,cAAc,GAAG,SAAS,CAyB5B;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAoBvE"}

package/dist/imports.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The named imports of the generated file, one line per module, an alias
+ * when two modules export the same name.
+ */
+export declare class Imports {
+    #private;
+    /** `reserved`: the names the file declares, which no import may take. */
+    constructor(reserved?: Iterable<string>);
+    /** The local name `exported` from `module` is reached by. */
+    add(module: string, exported: string): string;
+    /** The import lines, `zod` first, double-quoted as every string the file holds. */
+    lines(): string[];
+}
+//# sourceMappingURL=imports.d.ts.map

package/dist/imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imports.d.ts","sourceRoot":"","sources":["../src/imports.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,OAAO;;IAMnB,yEAAyE;gBAC7D,QAAQ,GAAE,QAAQ,CAAC,MAAM,CAAM;IAI3C,6DAA6D;IAC7D,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAY7C,mFAAmF;IACnF,KAAK,IAAI,MAAM,EAAE;CAUjB"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { type GraphQLSchema } from 'graphql';
+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
+ * `@nxgt/graphql-validation`. It refuses a schema `withValidation` would
+ * refuse, with the same message.
+ */
+export declare function plugin(schema: GraphQLSchema, documents: readonly DocumentFile[], config?: CodegenZodConfig, info?: {
+    readonly outputFile?: string | undefined;
+}): Promise<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}