@nxgt/graphql-validation 0.0.0-stage → 0.1.0

package/dist/rules/starts-with.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"starts-with.d.ts","sourceRoot":"","sources":["../../src/rules/starts-with.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,yDAOzB,CAAC"}

package/dist/typedefs-command.d.ts

@@ -0,0 +1,10 @@
+/** Where `--out` writes when it is given no file. */
+export declare const DEFAULT_OUT = "generated/graphql/constraint.graphqls";
+/** The `.graphqls` file's content: a header, then the SDL. */
+export declare function graphqls(): string;
+/**
+ * Runs the bin on `argv`: 0 done, 1 the file could not be written, 2 a usage
+ * error (nxgt-mongo-backup's convention). `--help` anywhere wins.
+ */
+export declare function main(argv: readonly string[]): Promise<number>;
+//# sourceMappingURL=typedefs-command.d.ts.map

package/dist/typedefs-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typedefs-command.d.ts","sourceRoot":"","sources":["../src/typedefs-command.ts"],"names":[],"mappings":"AAOA,qDAAqD;AACrD,eAAO,MAAM,WAAW,0CAA0C,CAAC;AAUnE,8DAA8D;AAC9D,wBAAgB,QAAQ,IAAI,MAAM,CAEjC;AAOD;;;GAGG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA+BnE"}

package/dist/validated.d.ts

@@ -0,0 +1,22 @@
+import type { GraphQLFieldResolver, GraphQLResolveInfo } from 'graphql';
+import { z } from 'zod';
+/** An object schema of the arguments, or its shape. */
+export type ArgsSchema = z.ZodType<Record<string, unknown>> | z.ZodRawShape;
+/** The schema `ArgsSchema` stands for. */
+export type SchemaOf<S extends ArgsSchema> = S extends z.ZodType ? S : z.ZodObject<S & z.ZodRawShape>;
+/**
+ * A resolver whose arguments are checked by `schema` before it runs, for what
+ * a `@constraint` cannot say: a rule across arguments, a business refinement,
+ * an async check. It receives the parsed arguments (`z.output`), defaults and
+ * transforms applied; an invalid input is the same `BAD_USER_INPUT` error as
+ * the directives'.
+ *
+ * ```ts
+ * signUp: validated(
+ *   z.object({ input: signUpSchema }).refine(({ input }) => input.password !== input.email),
+ *   (_, { input }) => users.create(input),
+ * )
+ * ```
+ */
+export 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>>>;
+//# sourceMappingURL=validated.d.ts.map

package/dist/validated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validated.d.ts","sourceRoot":"","sources":["../src/validated.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AACxE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC;AAE5E,0CAA0C;AAC1C,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,UAAU,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,GAC7D,CAAC,GACD,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;AAElC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CACxB,CAAC,SAAS,UAAU,EACpB,OAAO,GAAG,OAAO,EACjB,QAAQ,GAAG,OAAO,EAClB,OAAO,GAAG,OAAO,EAEjB,MAAM,EAAE,CAAC,EACT,OAAO,EAAE,CACR,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,kBAAkB,KACpB,OAAO,GACV,oBAAoB,CACtB,OAAO,EACP,QAAQ,EACR,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CACzB,CAYA"}

package/dist/with-validation.d.ts

@@ -0,0 +1,26 @@
+import { type GraphQLSchema } from 'graphql';
+/**
+ * Checks every `@constraint` of `schema` before the resolvers run. Each
+ * field with a constrained argument — directly, or anywhere inside an input
+ * type it takes — gets its resolver (and its `subscribe`) wrapped: the
+ * arguments are parsed by the Zod schema the directives describe, the
+ * resolver receives the parsed value, and an invalid input becomes one
+ * `BAD_USER_INPUT` error. Fields with nothing to check are left untouched.
+ *
+ * The schema is built here, once: a constraint that cannot apply (a
+ * `minLength` on an `Int`, an unknown format, a bad pattern) throws now, not
+ * on the first request. The resolvers are wrapped in place and the same
+ * schema is returned, so it goes wherever it went before; calling it twice
+ * wraps nothing twice. Call it last, once every resolver is attached: a
+ * resolver set on a field afterwards replaces the check.
+ *
+ * A `@constraint` on an interface's argument must be repeated on each
+ * object's field, which is the one that resolves; a field that drops it
+ * fails here.
+ *
+ * The directives are read from the SDL (`astNode`), so a schema built from
+ * type definitions — `buildSchema`, `makeExecutableSchema`, Yoga, Apollo —
+ * is checked; a code-first schema with no SDL has no `@constraint` to read.
+ */
+export declare function withValidation<S extends GraphQLSchema>(schema: S): S;
+//# sourceMappingURL=with-validation.d.ts.map

package/dist/with-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-validation.d.ts","sourceRoot":"","sources":["../src/with-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAIN,KAAK,aAAa,EAGlB,MAAM,SAAS,CAAC;AA2EjB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAgCpE"}

package/docs/README.md

@@ -0,0 +1,15 @@
+# @nxgt/graphql-validation documentation
+
+## Guides
+
+| Page | Read it when |
+| --- | --- |
+| [Constraints](guide/constraints.md) | you write `@constraint` in your schema: setup with `withValidation`, every argument and its Zod equivalent, the formats, lists and nested inputs |
+| [Errors](guide/errors.md) | you handle the `BAD_USER_INPUT` error in a client, build it yourself with `badUserInput`, or add rules a directive cannot say with `validated` |
+
+## Reference
+
+| Page | Read it when |
+| --- | --- |
+| [Troubleshooting](troubleshooting.md) | you have an error message and want its cause |
+| [Roadmap](roadmap.md) | you want to know what is coming, and what is not |

package/docs/guide/constraints.md

@@ -0,0 +1,291 @@
+# Constraints
+
+How to declare checks with `@constraint` and turn them on with
+`withValidation`. For the error an invalid input becomes, see
+[Errors](errors.md).
+
+## Smallest complete example
+
+```ts
+import { makeExecutableSchema } from '@graphql-tools/schema';
+import { graphql } from 'graphql';
+import { constraintTypeDefs, withValidation } from '@nxgt/graphql-validation';
+
+const schema = withValidation(
+  makeExecutableSchema({
+    typeDefs: [
+      constraintTypeDefs,
+      /* GraphQL */ `
+        type Query {
+          greet(name: String! @constraint(minLength: 2)): String
+        }
+      `,
+    ],
+    resolvers: { Query: { greet: (_, { name }) => `Hello ${name}` } },
+  }),
+);
+
+const result = await graphql({ schema, source: '{ greet(name: "A") }' });
+// result.errors[0].message:
+//   "Invalid arguments for Query.greet. name: Too small: expected string to have >=2 characters"
+```
+
+## The flow
+
+1. Put `constraintTypeDefs` in your type definitions. It is a string: the SDL
+   of the `@constraint` directive.
+2. Write `@constraint(...)` on arguments and input fields.
+3. Build the schema: `buildSchema`, `makeExecutableSchema`, GraphQL Yoga,
+   Apollo Server, anything that builds from type definitions.
+4. Attach every resolver, then call `withValidation(schema)` **last**: a
+   resolver set on a field afterwards replaces the check.
+
+```ts
+import { buildSchema } from 'graphql';
+import { constraintTypeDefs, withValidation } from '@nxgt/graphql-validation';
+
+const schema = buildSchema(`${constraintTypeDefs}
+  type Query { code(value: String @constraint(pattern: "^[A-Z]{3}$")): String }
+`);
+// ... set field resolvers on `schema` here ...
+withValidation(schema);
+```
+
+What `withValidation` does:
+
+- It wraps the resolver of every field that has a constrained argument, directly
+  or anywhere inside an input type it takes: `subscribe` for a subscription
+  field, `resolve` otherwise.
+- It wraps in place and returns the same schema, typed as you passed it.
+  Calling it twice wraps nothing twice.
+- The resolver receives the parsed arguments (`z.output` of the schema the
+  directives describe). An argument or input field the client left out stays
+  **absent** from them, not `undefined`: `{ input: { email } }`, with
+  `Object.keys(input)` equal to `['email']`. A `@oneOf` input keeps its one key.
+- Each issue it raises carries `constraint`, the `@constraint` argument that
+  refused (see [Errors](errors.md#the-error)).
+- A default value that breaks its own constraint throws at the call, naming
+  the place: `The default value of Query.a(name:) breaks its @constraint: Too
+  small: expected string to have >=2 characters`. It works for arguments and
+  input fields (`The default value of Page.size breaks ...`).
+- It builds every schema once, at the call, so a constraint that cannot apply
+  throws then, with the place named, not on the first request. This includes
+  constraints in input types no argument reaches.
+- A subscription field is checked once, in `subscribe`, before it starts, not
+  on every event.
+
+```ts
+import type { GraphQLSchema } from 'graphql';
+
+declare function withValidation<S extends GraphQLSchema>(schema: S): S;
+declare const constraintTypeDefs: string;
+```
+
+The directives are read from the SDL. A **code-first** schema does not declare
+`@constraint`, so `withValidation` throws `this schema declares no @constraint
+directive`. A schema that declares it but whose constrained types and fields
+have no SDL (built with `new GraphQLObjectType`, or from merged pieces) is not
+checked, and nothing says so.
+
+## The `@constraint` arguments
+
+They are those of [graphql-constraint-directive](https://github.com/confuser/graphql-constraint-directive),
+minus `uniqueTypeName`. A rule narrows the type it names; on any other type the
+schema fails to build (see [Troubleshooting](../troubleshooting.md)).
+
+| Argument | GraphQL type | Applies to | Zod equivalent |
+| --- | --- | --- | --- |
+| `format` | `String` | `String`, `ID` | the schema of the [format](#formats), applied first |
+| `minLength` | `Int` | `String`, `ID` | `.min(n)` |
+| `maxLength` | `Int` | `String`, `ID` | `.max(n)` |
+| `startsWith` | `String` | `String`, `ID` | `.startsWith(s)` |
+| `endsWith` | `String` | `String`, `ID` | `.endsWith(s)` |
+| `contains` | `String` | `String`, `ID` | `.includes(s)` |
+| `notContains` | `String` | `String`, `ID` | `.refine(...)`, message `Must not contain "s"` |
+| `pattern` | `String` | `String`, `ID` | `.regex(new RegExp(p))` |
+| `min` | `Float` | `Int`, `Float` | `.gte(n)` |
+| `max` | `Float` | `Int`, `Float` | `.lte(n)` |
+| `exclusiveMin` | `Float` | `Int`, `Float` | `.gt(n)` |
+| `exclusiveMax` | `Float` | `Int`, `Float` | `.lt(n)` |
+| `multipleOf` | `Float` | `Int`, `Float` | `.multipleOf(n)` |
+| `minItems` | `Int` | a list | `.min(n)` on the array |
+| `maxItems` | `Int` | a list | `.max(n)` on the array |
+
+An `Int` is also checked to be an integer. Several arguments combine:
+
+```graphql
+input Product {
+  sku: String! @constraint(startsWith: "SKU-", maxLength: 12, pattern: "^SKU-[0-9]+$")
+  price: Float! @constraint(exclusiveMin: 0, multipleOf: 0.01)
+}
+```
+
+The directive must be the one `constraintTypeDefs` declares. A `@constraint`
+declared otherwise, typically graphql-constraint-directive's SDL kept after a
+migration, makes `withValidation` throw at startup: `This schema's @constraint
+is not constraintTypeDefs': it is allowed on FIELD_DEFINITION; declares
+uniqueTypeName, which no rule reads. Declare it with constraintTypeDefs.` An
+argument of another type is named too (`declares minLength: String, not Int`).
+See [Troubleshooting](../troubleshooting.md).
+
+`@constraint` is allowed on `ARGUMENT_DEFINITION` and `INPUT_FIELD_DEFINITION`
+only. On an output field `buildSchema` fails with
+`Directive "@constraint" may not be used on FIELD_DEFINITION.`, where
+graphql-constraint-directive allows it: a resolver's result is the job of
+output scalars, and a directive that checked nothing there would be a promise
+broken in silence. Use [`@nxgt/graphql-scalars`](https://www.npmjs.com/package/@nxgt/graphql-scalars)
+for that.
+
+### Lists
+
+`minItems` and `maxItems` apply to the list; every other rule applies to its
+items. A nullable argument also accepts `null` and absence.
+
+```graphql
+type Query {
+  # at least one tag, at most 5; each tag 1 to 20 characters
+  search(tags: [String!]! @constraint(minItems: 1, maxItems: 5, minLength: 1, maxLength: 20)): [String!]
+}
+```
+
+### Nested and recursive inputs
+
+Constraints on input fields are found through any depth of input types, lists
+of them, and recursive ones. The issue path says where:
+
+```graphql
+input Address { zip: String! @constraint(pattern: "^[0-9]{5}$") }
+input SignUp { name: String, address: Address! }
+type Mutation { signUp(input: SignUp!): Boolean }
+```
+
+A bad `zip` is reported at `['input', 'address', 'zip']`.
+
+### Interfaces
+
+An interface field is resolved by the objects that implement it, so a
+`@constraint` on an interface field's argument must be written again, the same,
+on each implementing object's field. If an object drops it or writes a
+different one, `withValidation` throws at startup rather than let the argument
+go unchecked, printing both.
+
+```graphql
+interface Named { name(style: String @constraint(maxLength: 5)): String }
+type Person implements Named {
+  name(style: String @constraint(maxLength: 5)): String
+}
+```
+
+### Format first
+
+`format` replaces the base string schema, and every other rule narrows it, so
+the order you write them in does not matter:
+
+```graphql
+email: String! @constraint(maxLength: 12, format: "email")
+# the email format, then at most 12 characters
+```
+
+## Formats
+
+`@constraint(format: "...")` takes one of these names. Anything else fails at
+startup with `Unknown @constraint format "siret". Known formats: byte, date,
+date-time, email, ipv4, ipv6, uri, uuid.`
+
+| Format | Zod schema | Accepts |
+| --- | --- | --- |
+| `byte` | `z.base64()` | base64 text |
+| `date-time` | `z.iso.datetime({ offset: true })` | RFC 3339 with an offset: `2024-03-10T12:00:00Z`, `2024-03-10T12:00:00+02:00` |
+| `date` | `z.iso.date()` | `YYYY-MM-DD`, a real day |
+| `email` | `z.email()` | an email address |
+| `ipv4` | `z.ipv4()` | a dotted IPv4 address |
+| `ipv6` | `z.ipv6()` | an IPv6 address |
+| `uri` | `z.url({ protocol: /^(https?\|ftp)$/ })` | an absolute `http`, `https` or `ftp` URL; the scheme is required |
+| `uuid` | `z.uuid()` | an 8-4-4-4-12 UUID |
+
+Where they differ from graphql-constraint-directive's (validator.js):
+
+- `date-time` is the canonical form only: an uppercase `T` and `Z`, seconds
+  present. A lowercase `t` or `z`, or a space for `T`, is refused.
+- `uri` requires the scheme (`example.com` is refused) and nothing but `http`,
+  `https` and `ftp` gets in: no `javascript:`, no `mailto:`.
+
+## In your IDE
+
+An IDE's GraphQL plugin does not run your server, so it does not know
+`@constraint` and reports `Unknown directive "@constraint"`. Point
+`graphql.config.yml` at the file the package ships (by path; it is not an
+`exports` subpath, so do not `import` it):
+
+```yaml
+schema:
+  - src/**/*.graphql
+  - node_modules/@nxgt/graphql-validation/graphql/constraint.graphqls
+```
+
+To keep a copy in the project, for an IDE that does not index `node_modules` or
+to commit it with your schema:
+
+```sh
+bunx nxgt-graphql-validation typedefs --out
+```
+
+and list `generated/graphql/constraint.graphqls` in `graphql.config.yml` in place of the
+`node_modules/...` line.
+
+`npx` works the same. `--out` alone writes `generated/graphql/constraint.graphqls`,
+`--out <file>` writes `<file>`, creating the folder, and without it the SDL goes
+to stdout (`--help` or `-h`, anywhere on the line, lists the flags). It exits 0 when done, 1 when the file
+cannot be written (`typedefs failed: <message>` on stderr), and 2 on a usage
+error (`Unknown command "<x>".`, `Unexpected arguments: …`, or no command). Regenerate the file after upgrading the
+package.
+
+The schema must declare `@constraint` once. Pick one source for the server:
+
+- **The generated file is part of your schema.** If the server loads its
+  type definitions by scanning `*.graphql(s)` files and the copy sits among
+  them, it already declares the directive: do not add `constraintTypeDefs`.
+- **`constraintTypeDefs` declares it.** Then the copy is for the IDE only:
+  keep it out of the folders the server scans (or exclude it from the glob).
+
+Both give the same schema, and `withValidation` accepts either: it checks that
+the directive declared is this package's. Both at once throw
+`There can be only one directive named "@constraint".`
+
+## A realistic schema
+
+```ts
+import { createYoga, createSchema } from 'graphql-yoga';
+import { constraintTypeDefs, withValidation } from '@nxgt/graphql-validation';
+
+const schema = withValidation(
+  createSchema({
+    typeDefs: [
+      constraintTypeDefs,
+      /* GraphQL */ `
+        input Signup {
+          email: String! @constraint(format: "email", maxLength: 254)
+          password: String! @constraint(minLength: 12)
+          website: String @constraint(format: "uri")
+        }
+        type Mutation {
+          signup(input: Signup!): ID!
+        }
+        type Query { ok: Boolean }
+      `,
+    ],
+    resolvers: {
+      Mutation: {
+        // runs only for a valid `input`
+        signup: (_, { input }) => createUser(input),
+      },
+    },
+  }),
+);
+
+declare function createUser(input: { email: string }): string;
+
+export const yoga = createYoga({ schema });
+```
+
+For rules the directive cannot say, see [`validated`](errors.md#validated).

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,30 @@
+# 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
+
+- **A Zod codegen plugin** that writes the same schemas as source, from the
+  same rules, so the types your resolvers receive come from your SDL.
+- **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
+
+Nothing yet.