@nxgt/graphql-validation 0.0.0-stage → 0.2.0

package/docs/guide/errors.md

@@ -0,0 +1,194 @@
+# Errors
+
+The error an invalid input becomes, how a client reads it, and `validated` for
+rules a `@constraint` cannot say. For declaring constraints, see
+[Constraints](constraints.md).
+
+## The error
+
+An invalid input is **one** `GraphQLError`, thrown before your resolver runs:
+
+- `message`: `Invalid arguments for <Type>.<field>. <path>: <first issue message>`,
+  for a log line. The path is dotted; `arguments` stands for an empty path.
+- `extensions.code`: `BAD_USER_INPUT`, the code Apollo and most clients read.
+- `extensions.issues`: every reason, not only the first.
+
+```json
+{
+  "errors": [
+    {
+      "message": "Invalid arguments for Mutation.signUp. input.email: Invalid email address",
+      "path": ["signUp"],
+      "extensions": {
+        "code": "BAD_USER_INPUT",
+        "issues": [
+          { "path": ["input", "email"], "message": "Invalid email address", "code": "invalid_format", "constraint": "format" },
+          { "path": ["input", "name"], "message": "Too small: expected string to have >=2 characters", "code": "too_small", "constraint": "minLength" },
+          { "path": ["input", "tags"], "message": "Too big: expected array to have <=2 items", "code": "too_big", "constraint": "maxItems" }
+        ]
+      }
+    }
+  ],
+  "data": { "signUp": null }
+}
+```
+
+The error's own `path` is the field; each issue's `path` is **relative to the
+arguments**: the argument name, then input fields, with a number for a list
+index. `code` is Zod's issue code (`too_small`, `too_big`, `invalid_format`,
+`custom`, ...). `constraint` is the `@constraint` argument that refused
+(`minLength`, `format`, `maxItems`, ...); it is absent for a refusal of a
+[`validated`](#validated) schema. `message` is Zod's, in English, and is not
+meant for display in every language: map on `constraint` and `path` if you
+translate. Prefer `constraint` to `code`: it is the name in your schema, while
+`code` is Zod's and can change when Zod does across a major version.
+
+### Types
+
+```ts
+interface ValidationIssue {
+  readonly path: readonly (string | number)[];
+  readonly message: string;
+  readonly code: string;
+  /** The `@constraint` argument that refused; absent for `validated`'s own schema. */
+  readonly constraint?: ConstraintArgument;
+}
+
+type ConstraintArgument =
+  | 'format' | 'minLength' | 'maxLength' | 'startsWith' | 'endsWith'
+  | 'contains' | 'notContains' | 'pattern' | 'min' | 'max'
+  | 'exclusiveMin' | 'exclusiveMax' | 'multipleOf' | 'minItems' | 'maxItems';
+
+type BadUserInputExtensions = {
+  readonly code: 'BAD_USER_INPUT';
+  readonly issues: readonly ValidationIssue[];
+};
+```
+
+## In a client
+
+Map the issues onto form fields by path. A path of `['input', 'address', 'zip']`
+is the field `address.zip` of the `input` argument.
+
+```ts
+import type { BadUserInputExtensions, ValidationIssue } from '@nxgt/graphql-validation';
+
+interface GraphQLErrorJson {
+  message: string;
+  extensions?: Partial<BadUserInputExtensions>;
+}
+
+/** Field errors keyed by `address.zip`, relative to the `input` argument. */
+function fieldErrors(errors: readonly GraphQLErrorJson[]): Record<string, string[]> {
+  const byField: Record<string, string[]> = {};
+  for (const error of errors) {
+    if (error.extensions?.code !== 'BAD_USER_INPUT') continue;
+    for (const issue of (error.extensions.issues ?? []) as ValidationIssue[]) {
+      const [, ...field] = issue.path; // drop the argument name, `input`
+      const key = field.join('.');
+      (byField[key] ??= []).push(issue.message);
+    }
+  }
+  return byField;
+}
+
+// { email: ['Invalid email address'], name: ['Too small: ...'] }
+
+/** Translated texts, keyed by the stable `constraint`, not by Zod's `code`. */
+const texts: Record<string, string> = {
+  format: 'Not a valid value',
+  minLength: 'Too short',
+  maxItems: 'Too many items',
+};
+
+const textOf = (issue: ValidationIssue) =>
+  (issue.constraint && texts[issue.constraint]) ?? issue.message;
+```
+
+An issue whose path is just the argument (`['code']` for `check(code: ...)`)
+gives the empty key: show it as a form-level error.
+
+## `validated`
+
+`validated(schema, resolver)` checks the arguments with a Zod schema you write,
+for what a directive cannot say: a rule across arguments or fields, a business
+refinement, an async check. It raises the same error, so a client has one shape
+to handle.
+
+```ts
+import { validated } from '@nxgt/graphql-validation';
+import { z } from 'zod';
+
+const range = z
+  .object({ from: z.number(), to: z.number() })
+  .refine(({ from, to }) => from <= to, {
+    message: 'from must not exceed to',
+    path: ['to'],
+  });
+
+const resolvers = {
+  Query: {
+    // (source, args, context, info): args is z.output of the schema
+    range: validated(range, (_, { from, to }) => to - from),
+  },
+};
+```
+
+A bad `{ from: 4, to: 1 }` gives `Invalid arguments for Query.range. to: from must not exceed to`
+with one issue `{ path: ['to'], message: 'from must not exceed to', code: 'custom' }`.
+
+- The schema is a Zod object schema of the arguments, or its **shape**
+  (`{ name: z.string() }`, wrapped in `z.object` for you).
+- The resolver receives `z.output`: defaults and transforms applied.
+- Async refinements work; the check awaits them.
+- When a field has both `@constraint` and `validated`, the directives run
+  first, then your schema.
+
+```ts
+import { validated } from '@nxgt/graphql-validation';
+import { z } from 'zod';
+
+declare const users: { exists(name: string): Promise<boolean> };
+
+// type Query { claim(name: String! @constraint(minLength: 3)): String }
+const claim = validated(
+  { name: z.string().refine(async (name) => !(await users.exists(name)), 'already taken') },
+  (_, { name }) => name,
+);
+```
+
+```ts
+import type { GraphQLFieldResolver, GraphQLResolveInfo } from 'graphql';
+import type { z } from 'zod';
+
+type ArgsSchema = z.ZodType<Record<string, unknown>> | z.ZodRawShape;
+type SchemaOf<S extends ArgsSchema> = S extends z.ZodType ? S : z.ZodObject<S & z.ZodRawShape>;
+
+declare function validated<S extends ArgsSchema, TSource = unknown, TContext = unknown, TResult = unknown>(
+  schema: S,
+  resolve: (source: TSource, args: z.output<SchemaOf<S>>, context: TContext, info: GraphQLResolveInfo) => TResult,
+): GraphQLFieldResolver<TSource, TContext, z.input<SchemaOf<S>>, Promise<Awaited<TResult>>>;
+```
+
+`validated` validates whatever the field's arguments are; it does not need
+`withValidation` or `constraintTypeDefs` to work.
+
+## `badUserInput`
+
+For code that validates by hand and wants the same error:
+
+```ts
+import { badUserInput } from '@nxgt/graphql-validation';
+import { z } from 'zod';
+
+const result = z.object({ code: z.string().length(4) }).safeParse({ code: 'abc' });
+if (!result.success) throw badUserInput('Query.redeem', result.error);
+// message: "Invalid arguments for Query.redeem. code: Too small: expected string to have exactly 4 characters"
+```
+
+```ts
+import type { GraphQLError } from 'graphql';
+import type { z } from 'zod';
+
+declare function badUserInput(where: string, error: z.ZodError): GraphQLError;
+```

package/docs/roadmap.md

@@ -0,0 +1,31 @@
+# Roadmap
+
+What `@nxgt/graphql-validation` is heading for, phrased as what you get.
+
+## Now
+
+- **`@constraint` on arguments and input fields.** `constraintTypeDefs` for
+  your SDL, then `withValidation(schema)`: every constrained argument is
+  checked by a Zod schema built from its directives, through nested input
+  types and lists, before your resolver runs. The resolver receives the
+  parsed value.
+- **One error a form can use.** An invalid input is one `GraphQLError` with
+  `extensions.code` `BAD_USER_INPUT` and an `issues` list, each with the
+  path of the offending field inside the arguments.
+- **`validated(schema, resolver)`** for what a directive cannot say: rules
+  across fields, business refinements, with the same error.
+- **Formats** `byte`, `date-time`, `date`, `email`, `ipv4`, `ipv6`, `uri`,
+  `uuid`.
+
+## Next
+
+- **Your own formats**, named in `@constraint(format: "...")`.
+- **Schemas that read the context**, `(args, context) => schema`, for checks
+  that need the request (uniqueness in a database, permissions).
+
+## Shipped
+
+- **A Zod codegen plugin**, [`@nxgt/graphql-codegen-zod`](https://www.npmjs.com/package/@nxgt/graphql-codegen-zod):
+  it writes the same schemas as source, from the same rules, so the types your
+  resolvers receive and the variables a client sends come from your SDL. This
+  package gains `@nxgt/graphql-validation/codegen` for it.

package/docs/troubleshooting.md

@@ -0,0 +1,260 @@
+# Troubleshooting
+
+One entry per error you can hit, headed by the message you will search for.
+`withValidation` and `buildSchema` errors happen at startup; the last section
+is the one a client sees.
+
+- [Install](#install)
+- [Startup](#startup)
+- [Silent traps](#silent-traps)
+- [Runtime](#runtime)
+- [The bin](#the-bin)
+
+## Install
+
+### `TS2307: Cannot find module '@nxgt/graphql-validation'` (or its types)
+
+**When:** type-checking an import of the package.
+**Why:** the package is ESM with an `exports` map, which `moduleResolution`
+`node`/`node10` ignores, and `nodenext` is not supported.
+**Fix:**
+
+```jsonc
+{ "compilerOptions": { "moduleResolution": "bundler" } }
+```
+
+## Startup
+
+### `@constraint(minLength) on Query.check(age:) needs a String or an ID, not Int.`
+
+**When:** calling `withValidation`.
+**Why:** a rule narrows one kind of type. `format`, `minLength`, `maxLength`,
+`startsWith`, `endsWith`, `contains`, `notContains` and `pattern` need a
+`String` or an `ID`; `min`, `max`, `exclusiveMin`, `exclusiveMax` and
+`multipleOf` need an `Int` or a `Float`. The same message, with `an Int or a
+Float`, appears for a number rule on a `String`.
+**Fix:** use a rule that fits the type.
+
+```graphql
+check(age: Int @constraint(min: 18)): Boolean
+```
+
+### `@constraint(minItems) on Query.check(name:) needs a list, not String.`
+
+**When:** calling `withValidation`.
+**Why:** `minItems` and `maxItems` apply to a list.
+**Fix:** put them on a list argument, or use `minLength`/`maxLength` for a string.
+
+```graphql
+check(tags: [String!] @constraint(minItems: 1)): Boolean
+```
+
+### `@constraint(maxLength) on In.at needs a String or an ID, not DateTime.`
+
+**When:** calling `withValidation`.
+**Why:** a rule on a custom scalar, an enum or an input object (`..., not In.`)
+has nothing to narrow: only `String`, `ID`, `Int`, `Float` and lists take
+rules. The message names the place (`In.at`, `Query.check(input:)`) and the
+type. This is checked in every input type, even one no argument reaches.
+**Fix:** remove the directive; check a custom scalar in its own definition (for
+example with `@nxgt/graphql-scalars`), or on a field with [`validated`](guide/errors.md#validated).
+
+### `Unknown @constraint format "siret". Known formats: byte, date, date-time, email, ipv4, ipv6, uri, uuid.`
+
+**When:** calling `withValidation`.
+**Why:** `format` takes one of the listed names. Custom formats are on the
+[roadmap](roadmap.md).
+**Fix:** use a known format, or `pattern: "..."`.
+
+### `Invalid @constraint pattern "[a-":`
+
+**When:** calling `withValidation`.
+**Why:** `pattern` is compiled with `new RegExp`; the text after the colon is
+the runtime's own RegExp message, which differs between engines. V8 (Node)
+says `Invalid regular expression: /[a-/: Unterminated character class`.
+**Fix:** write a valid pattern. In SDL, escape backslashes: `"\\d+"`.
+
+### `Unknown directive "@constraint".`
+
+**When:** in the IDE (JetBrains GraphQL, VS Code GraphQL), on every `@constraint`
+in a `.graphql` file. The server runs fine.
+**Why:** the plugin reads your schema files and `constraintTypeDefs` is not one.
+**Fix:** add the shipped file to `graphql.config.yml`, or write a copy into the
+project and list that instead:
+
+```yaml
+schema:
+  - src/**/*.graphql
+  - node_modules/@nxgt/graphql-validation/graphql/constraint.graphqls
+```
+
+```sh
+bunx nxgt-graphql-validation typedefs --out
+```
+
+If the server scans the folder you write it to for its type definitions, the
+copy declares the directive for the server too: drop `constraintTypeDefs`, or
+keep the copy out of the scan. See the next entry.
+
+### `There can be only one directive named "@constraint".`
+
+**When:** building the schema.
+**Why:** `@constraint` is declared twice, usually `constraintTypeDefs` plus a
+`constraint.graphqls` copy that the server's type definitions scan picked up.
+**Fix:** keep one. Either drop `constraintTypeDefs` and let the scanned copy
+declare the directive, or keep `constraintTypeDefs` and exclude the copy from
+the scan (it then serves the IDE only).
+
+### `withValidation: this schema declares no @constraint directive. Add constraintTypeDefs to its type definitions.`
+
+**When:** calling `withValidation`.
+**Why:** the schema has no `@constraint` directive, so there is nothing to
+read. Usually `constraintTypeDefs` was not added, or the schema is code-first and
+declares no directive.
+**Fix:**
+
+```ts
+const typeDefs = [constraintTypeDefs, yourTypeDefs];
+```
+
+### `Directive "@constraint" may not be used on FIELD_DEFINITION.`
+
+**When:** building the schema.
+**Why:** `@constraint` is allowed on arguments and input fields only.
+graphql-constraint-directive also allows output fields; this package refuses
+them, since a resolver's result is the job of output scalars.
+**Fix:** move it to the argument or input field, or use an output scalar.
+
+### `Unknown argument "uniqueTypeName" on directive "@constraint".`
+
+**When:** building the schema, migrating from graphql-constraint-directive.
+**Why:** `uniqueTypeName` is a detail of that package's scalar wrapping and
+does not exist here.
+**Fix:** remove it.
+
+### `@constraint on Named.name(style:) is not repeated on Person.name(style:), which resolves it (@constraint(maxLength: 5) there, no @constraint here). Write the same @constraint on both.`
+
+**When:** calling `withValidation`, with a `@constraint` on an interface
+field's argument.
+**Why:** the objects resolve the field, not the interface, so a constraint
+the object drops would go unchecked. `Named`, `Person` and `style` are your
+interface, object and argument. When the object writes a different constraint
+the message reads `... differs on Person.name(style:), which resolves it
+(@constraint(maxLength: 5) there, @constraint(maxLength: 5, minLength: 1)
+here). Write the same @constraint on both.`
+**Fix:**
+
+```graphql
+interface Named { name(style: String @constraint(maxLength: 5)): String }
+type Person implements Named {
+  name(style: String @constraint(maxLength: 5)): String
+}
+```
+
+### `This schema's @constraint is not constraintTypeDefs': it is allowed on FIELD_DEFINITION; declares uniqueTypeName, which no rule reads. Declare it with constraintTypeDefs.`
+
+**When:** calling `withValidation`, typically after migrating from
+graphql-constraint-directive and keeping its SDL.
+**Why:** the schema declares its own `@constraint`: extra locations would be
+accepted and checked by nothing, extra arguments mean nothing here, and an
+argument of another type would reach a rule as the wrong kind of value. The
+message lists every difference: `repeatable, and only its first use is read`,
+`allowed on <LOCATION>`, `declares <name>, which no rule reads`, or
+`declares minLength: String, not Int`.
+**Fix:** drop the old directive declaration and use the package's.
+
+```ts
+const typeDefs = [constraintTypeDefs, yourTypeDefs]; // no other `directive @constraint`
+```
+
+### `The default value of Query.a(name:) breaks its @constraint: Too small: expected string to have >=2 characters`
+
+**When:** calling `withValidation`; for an argument (`Query.a(name:)`) or an
+input field (`Page.size`).
+**Why:** a request that leaves the value out would be refused for something the
+client never sent. The text after the colon is the first Zod message.
+The default is checked as graphql coerces it: a single value for a list
+(`[String!] = "ab"` is `["ab"]`), an input object filled with its fields' own
+defaults.
+**Fix:** make the default satisfy the constraint, or relax the constraint.
+
+```graphql
+type Query { a(name: String = "xy" @constraint(minLength: 2)): Int }
+```
+
+### `@constraint on @cached(ttl:) checks nothing: a directive's argument reaches no resolver. Remove it.`
+
+**When:** calling `withValidation`, with `@constraint` written on an argument
+of a directive definition (`directive @cached(ttl: Int @constraint(min: 1))`).
+**Why:** graphql allows it there (it is an ARGUMENT_DEFINITION), but no
+resolver receives a directive's argument, so the constraint would check
+nothing.
+**Fix:** remove it; check the directive's arguments where you read them.
+
+## Silent traps
+
+These raise no error.
+
+### A constrained argument is never refused
+
+**When:** an invalid value reaches the resolver.
+**Why:** one of three causes. The schema declares `@constraint` but the constrained
+types and fields have no SDL (code-first, or merged pieces): `@constraint` is
+read from the SDL, and there is none.
+Or `withValidation` was called before a resolver was attached: a resolver set on
+a field afterwards replaces the check. Or the schema you serve is not the one
+you passed (`withValidation` returns the same schema, so use either).
+**Fix:** build from type definitions and call `withValidation` last.
+
+```ts
+const schema = makeExecutableSchema({ typeDefs, resolvers });
+export default withValidation(schema); // last
+```
+
+### `Invalid ISO datetime` for a date-time that looks right
+
+**When:** `format: "date-time"` refuses `2024-03-10t12:00:00z`, `2024-03-10 12:00:00Z` or `2024-03-10T12:00Z`.
+**Why:** only the canonical form is accepted: uppercase `T` and `Z`, seconds
+present, then `Z` or a numeric offset.
+**Fix:** send `2024-03-10T12:00:00Z` or `2024-03-10T12:00:00+02:00`.
+
+## Runtime
+
+### `Invalid arguments for Mutation.signUp. input.email: Invalid email address`
+
+**When:** a request carries an argument that breaks a `@constraint` or a
+`validated` schema.
+**Why:** the message is `Invalid arguments for <Type>.<field>. <path>: <first
+issue>`; `extensions.code` is `BAD_USER_INPUT` and `extensions.issues` lists
+every issue. The resolver did not run.
+**Fix:** send a valid value, or show each issue beside its field. See
+[Errors](guide/errors.md). Common issues:
+
+| Message | Cause |
+| --- | --- |
+| `Invalid email address` | `format: "email"` |
+| `Invalid URL` | `format: "uri"`: not absolute, or a scheme other than `http`, `https`, `ftp` |
+| `Invalid ISO datetime` / `Invalid ISO date` | `format: "date-time"` / `"date"` |
+| `Too small: expected string to have >=2 characters` | `minLength: 2` |
+| `Too big: expected array to have <=2 items` | `maxItems: 2` |
+| `Too small: expected number to be >=18` | `min: 18` |
+| `Invalid string: must match pattern /.../` | `pattern` |
+
+## The bin
+
+### `typedefs failed: <message>`
+
+**When:** `nxgt-graphql-validation typedefs --out <file>` exits 1, for example
+with `typedefs failed: EACCES: permission denied, mkdir 'schema'`, or
+`EISDIR` when `<file>` is a folder.
+**Why:** the file or its folder could not be written; the rest of the line is
+the system's own message.
+**Fix:** point `--out` at a file path you can write, or print to stdout and
+redirect: `nxgt-graphql-validation typedefs > generated/graphql/constraint.graphqls`.
+
+### `Unknown command "<x>".` or `Unexpected arguments: …`
+
+**When:** the bin exits 2 and prints its usage.
+**Why:** the only command is `typedefs`, and its only flag is `--out [<file>]` (and `--help`).
+**Fix:** `nxgt-graphql-validation typedefs [--out [<file>]]`; `--help` prints
+the usage and exits 0.

package/graphql/constraint.graphqls

@@ -0,0 +1,20 @@
+# The @constraint directive of @nxgt/graphql-validation, for your IDE.
+# Generated by `nxgt-graphql-validation typedefs`: do not edit.
+
+directive @constraint(
+	contains: String
+	endsWith: String
+	exclusiveMax: Float
+	exclusiveMin: Float
+	format: String
+	maxItems: Int
+	maxLength: Int
+	max: Float
+	minItems: Int
+	minLength: Int
+	min: Float
+	multipleOf: Float
+	notContains: String
+	pattern: String
+	startsWith: String
+) on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION

package/package.json

@@ -1,6 +1,74 @@
 {
-  "name": "@nxgt/graphql-validation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@nxgt/graphql-validation",
+	"version": "0.2.0",
+	"description": "Validate GraphQL arguments and input fields with @constraint directives, checked by Zod schemas, for graphql 16 and 17",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"bin": {
+		"nxgt-graphql-validation": "./dist/cli.js"
+	},
+	"files": [
+		"dist",
+		"docs",
+		"graphql",
+		"README.md",
+		"package.json",
+		"LICENSE"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./codegen": {
+			"types": "./dist/codegen.d.ts",
+			"import": "./dist/codegen.js",
+			"default": "./dist/codegen.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"keywords": [
+		"graphql",
+		"validation",
+		"constraint",
+		"directive",
+		"zod",
+		"bun",
+		"typescript"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/softistx/nxgt-graphql.git",
+		"directory": "packages/graphql-validation"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bun run ../../build.ts",
+		"test": "bun test src",
+		"typecheck": "tsc --noEmit",
+		"typedefs:write": "bun run src/cli.ts typedefs --out graphql/constraint.graphqls"
+	},
+	"nxgt": {
+		"entrypoints": [
+			"src/index.ts",
+			"src/codegen.ts",
+			"src/cli.ts"
+		]
+	},
+	"devDependencies": {
+		"@types/bun": "^1.4.0",
+		"graphql": "16.11.0",
+		"zod": "4.6.5"
+	},
+	"peerDependencies": {
+		"graphql": "^16.11.0 || ^17.0.0",
+		"typescript": "^6.0.3",
+		"zod": ">=4.6.5 <5"
+	}
+}