@nxgt/graphql-validation 0.0.0-stage → 0.2.0

package/dist/rules/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rules/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAG7B;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC;AAE5D,uCAAuC;AACvC,MAAM,MAAM,kBAAkB,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAEb,EACJ,QAAQ,EAAE,CAAC,IAAI,kBAAkB,GAAG,OAAO,CAAC,cAAc,EAAE;IAAE,QAAQ,EAAE,CAAC,CAAA;CAAE,CAAC,GAC5E,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,SAAS,CACxB,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,CAAC,CAAC,OAAO,EACjB,KAAK,EAAE,MAAM,GAAG,MAAM,GACpB,CAAC,CAAC,OAAO,CAMX;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAC5B,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GAAG,MAAM,GACpB,MAAM,CAMR;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAC3B,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,GACrB,kBAAkB,GAAG,SAAS,CAGhC"}

package/dist/rules/max-items.d.ts

@@ -0,0 +1,2 @@
+export declare const maxItemsRule: import("./rule").Rule<"maxItems", "Int", "list">;
+//# sourceMappingURL=max-items.d.ts.map

package/dist/rules/max-items.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"max-items.d.ts","sourceRoot":"","sources":["../../src/rules/max-items.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,kDAOvB,CAAC"}

package/dist/rules/max-length.d.ts

@@ -0,0 +1,2 @@
+export declare const maxLengthRule: import("./rule").Rule<"maxLength", "Int", "string">;
+//# sourceMappingURL=max-length.d.ts.map

package/dist/rules/max-length.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"max-length.d.ts","sourceRoot":"","sources":["../../src/rules/max-length.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,qDAOxB,CAAC"}

package/dist/rules/max.d.ts

@@ -0,0 +1,2 @@
+export declare const maxRule: import("./rule").Rule<"max", "Float", "number">;
+//# sourceMappingURL=max.d.ts.map

package/dist/rules/max.d.ts.map

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

package/dist/rules/min-items.d.ts

@@ -0,0 +1,2 @@
+export declare const minItemsRule: import("./rule").Rule<"minItems", "Int", "list">;
+//# sourceMappingURL=min-items.d.ts.map

package/dist/rules/min-items.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"min-items.d.ts","sourceRoot":"","sources":["../../src/rules/min-items.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,kDAOvB,CAAC"}

package/dist/rules/min-length.d.ts

@@ -0,0 +1,2 @@
+export declare const minLengthRule: import("./rule").Rule<"minLength", "Int", "string">;
+//# sourceMappingURL=min-length.d.ts.map

package/dist/rules/min-length.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"min-length.d.ts","sourceRoot":"","sources":["../../src/rules/min-length.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,qDAOxB,CAAC"}

package/dist/rules/min.d.ts

@@ -0,0 +1,2 @@
+export declare const minRule: import("./rule").Rule<"min", "Float", "number">;
+//# sourceMappingURL=min.d.ts.map

package/dist/rules/min.d.ts.map

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

package/dist/rules/multiple-of.d.ts

@@ -0,0 +1,2 @@
+export declare const multipleOfRule: import("./rule").Rule<"multipleOf", "Float", "number">;
+//# sourceMappingURL=multiple-of.d.ts.map

package/dist/rules/multiple-of.d.ts.map

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

package/dist/rules/not-contains.d.ts

@@ -0,0 +1,2 @@
+export declare const notContainsRule: import("./rule").Rule<"notContains", "String", "string">;
+//# sourceMappingURL=not-contains.d.ts.map

package/dist/rules/not-contains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-contains.d.ts","sourceRoot":"","sources":["../../src/rules/not-contains.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,eAAe,0DAU1B,CAAC"}

package/dist/rules/pattern.d.ts

@@ -0,0 +1,2 @@
+export declare const patternRule: import("./rule").Rule<"pattern", "String", "string">;
+//# sourceMappingURL=pattern.d.ts.map

package/dist/rules/pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern.d.ts","sourceRoot":"","sources":["../../src/rules/pattern.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,WAAW,sDAQtB,CAAC"}

package/dist/rules/rule.d.ts

@@ -0,0 +1,55 @@
+import type { z } from 'zod';
+import type { StringSchema } from '../formats/format';
+/** The schema each kind of rule narrows. */
+export interface Targets {
+    string: StringSchema;
+    number: z.ZodNumber;
+    list: z.ZodArray<z.ZodType>;
+}
+export type Target = keyof Targets;
+/** What a `@constraint` argument's value can be. */
+interface ValueOf {
+    Int: number;
+    Float: number;
+    String: string;
+}
+/**
+ * One `@constraint` argument: its GraphQL type in the directive's SDL, the
+ * kind of value it narrows, and the same narrowing twice — `toZod` applied to
+ * a schema at startup, `toCode` written as source by a code generator. The
+ * spec beside each rule proves the two accept and refuse the same values.
+ *
+ * A `base` rule (only `format`) replaces the schema instead of narrowing it,
+ * so a builder applies it before every other rule of its target.
+ */
+export interface Rule<A extends string = string, T extends keyof ValueOf = keyof ValueOf, K extends Target = Target> {
+    readonly argument: A;
+    readonly type: T;
+    readonly target: K;
+    readonly base?: true;
+    readonly toZod: (schema: Targets[K], value: ValueOf[T]) => Targets[K];
+    /**
+     * `schema` is the source of the schema this rule narrows. The source names
+     * zod as a free `z`: the generated file imports it.
+     */
+    readonly toCode: (schema: string, value: ValueOf[T]) => string;
+    /**
+     * Whether a Zod issue is this rule's refusal, so the error a client gets
+     * names the rule (`constraint: 'minLength'`), which does not change with
+     * Zod's own issue codes.
+     */
+    readonly owns: (issue: IssueFields) => boolean;
+}
+/** The fields of a Zod issue a rule recognises its refusal by. */
+export interface IssueFields {
+    readonly code: string;
+    readonly origin?: string;
+    readonly format?: string;
+    readonly inclusive?: boolean;
+}
+/** Declares a rule, with its argument name kept literal. */
+export declare function defineRule<const A extends string, T extends keyof ValueOf, K extends Target>(rule: Rule<A, T, K>): Rule<A, T, K>;
+/** A string literal as source: quotes and escapes included. */
+export declare const literal: (value: string) => string;
+export {};
+//# sourceMappingURL=rule.d.ts.map

package/dist/rules/rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule.d.ts","sourceRoot":"","sources":["../../src/rules/rule.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,4CAA4C;AAC5C,MAAM,WAAW,OAAO;IACvB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;CAC5B;AAED,MAAM,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC;AAEnC,oDAAoD;AACpD,UAAU,OAAO;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,IAAI,CACpB,CAAC,SAAS,MAAM,GAAG,MAAM,EACzB,CAAC,SAAS,MAAM,OAAO,GAAG,MAAM,OAAO,EACvC,CAAC,SAAS,MAAM,GAAG,MAAM;IAEzB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACtE;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC;CAC/C;AAED,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CACzB,KAAK,CAAC,CAAC,SAAS,MAAM,EACtB,CAAC,SAAS,MAAM,OAAO,EACvB,CAAC,SAAS,MAAM,EACf,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAEpC;AAED,+DAA+D;AAC/D,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,KAAG,MAA+B,CAAC"}

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

@@ -0,0 +1,2 @@
+export declare const startsWithRule: import("./rule").Rule<"startsWith", "String", "string">;
+//# sourceMappingURL=starts-with.d.ts.map

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,EAClB,MAAM,SAAS,CAAC;AAiDjB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAWpE"}

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).