@nxgt/graphql-validation 0.3.0 → 0.4.0

package/dist/index.js

@@ -4,7 +4,7 @@ import {
 } from "./chunks/index-xcaf9kes.js";
 import {
   checkConstraints2
-} from "./chunks/index-1mzzydy3.js";
+} from "./chunks/index-twevz7yc.js";
 
 // src/bad-user-input.ts
 import { GraphQLError } from "graphql";
@@ -32,6 +32,99 @@ async function parseArgs(schema, args, where, constraintOf) {
     throw errorOf(where, issuesOf(result.error, constraintOf));
   return result.data;
 }
+// src/invalid-input.ts
+import { GraphQLError as GraphQLError2 } from "graphql";
+var INVALID_INPUT = "validation.errors.invalid-input";
+function paramsOf(params) {
+  return params && Object.keys(params).length > 0 ? params : undefined;
+}
+function messageOf(code, params, translate) {
+  return translate?.(code, params) ?? code;
+}
+function fieldsOf(issues, translate) {
+  return issues.map(({ path, code, params: given }) => {
+    const params = paramsOf(given);
+    return {
+      path,
+      code,
+      message: messageOf(code, params, translate),
+      ...params && { params }
+    };
+  });
+}
+function invalidInputError(issues, options = {}) {
+  const { translate, ...graphql } = options;
+  return new GraphQLError2(messageOf(INVALID_INPUT, undefined, translate), {
+    ...graphql,
+    extensions: {
+      code: INVALID_INPUT,
+      http: { status: 400 },
+      fields: fieldsOf(issues, translate)
+    }
+  });
+}
+function fieldsError(code, issues, options = {}) {
+  const { translate, status, params: given, ...graphql } = options;
+  const params = paramsOf(given);
+  return new GraphQLError2(messageOf(code, params, translate), {
+    ...graphql,
+    extensions: {
+      code,
+      ...params && { params },
+      ...status && { http: { status } },
+      fields: fieldsOf(issues, translate)
+    }
+  });
+}
+function inputPath(path) {
+  const [first, ...rest] = path;
+  return (first === "input" && rest.length > 0 ? rest : path).map((key) => String(key)).join(".");
+}
+
+// src/field-issue-of.ts
+var FIELD_CODES = {
+  tooShort: "validation.errors.too-short",
+  tooLong: "validation.errors.too-long",
+  outOfRange: "validation.errors.out-of-range",
+  tooFew: "validation.errors.too-few",
+  tooMany: "validation.errors.too-many",
+  invalidFormat: "validation.errors.invalid-format",
+  invalid: "validation.errors.invalid"
+};
+var TEXT_CHECKS = new Set([
+  "starts_with",
+  "ends_with",
+  "includes"
+]);
+function fieldIssueOf(issue) {
+  return { path: inputPath(issue.path), code: codeOf(issue) };
+}
+function codeOf(issue) {
+  switch (issue.code) {
+    case "too_small":
+    case "too_big": {
+      const small = issue.code === "too_small";
+      switch (issue.origin) {
+        case "string":
+          return small ? FIELD_CODES.tooShort : FIELD_CODES.tooLong;
+        case "number":
+        case "bigint":
+          return FIELD_CODES.outOfRange;
+        case "array":
+        case "set":
+          return small ? FIELD_CODES.tooFew : FIELD_CODES.tooMany;
+        default:
+          return FIELD_CODES.invalid;
+      }
+    }
+    case "not_multiple_of":
+      return FIELD_CODES.outOfRange;
+    case "invalid_format":
+      return TEXT_CHECKS.has(issue.format) ? FIELD_CODES.invalid : FIELD_CODES.invalidFormat;
+    default:
+      return FIELD_CODES.invalid;
+  }
+}
 // src/validated.ts
 import { z } from "zod";
 function validated(schema, resolve) {
@@ -87,11 +180,17 @@ function sameFormats(a, b) {
   return names.length === Object.keys(b).length && names.every((name) => Object.hasOwn(b, name) && a[name] === b[name]);
 }
 export {
+  FIELD_CODES,
+  INVALID_INPUT,
   badUserInput,
   constraintTypeDefs2 as constraintTypeDefs,
+  fieldIssueOf,
+  fieldsError,
+  inputPath,
+  invalidInputError,
   validated,
   withValidation
 };
 
-//# debugId=B588BD3EF63841CA64756E2164756E21
+//# debugId=BC885DEBB67481A464756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1,12 +1,14 @@
 {
   "version": 3,
-  "sources": ["../src/bad-user-input.ts", "../src/validated.ts", "../src/with-validation.ts"],
+  "sources": ["../src/bad-user-input.ts", "../src/invalid-input.ts", "../src/field-issue-of.ts", "../src/validated.ts", "../src/with-validation.ts"],
   "sourcesContent": [
     "import { GraphQLError } from 'graphql';\nimport type { z } from 'zod';\nimport type { ConstraintArgument } from './rules';\n\n/** One reason an input was refused, at its path inside the arguments. */\nexport interface ValidationIssue {\n\t/** `['input', 'address', 'zip']`: the argument, then the input fields. */\n\treadonly path: readonly (string | number)[];\n\treadonly message: string;\n\t/** Zod's issue code: `too_small`, `invalid_format`, `custom`, ... */\n\treadonly code: string;\n\t/**\n\t * The `@constraint` argument that refused (`minLength`, `format`), when a\n\t * directive did: stable across Zod versions, unlike `code`. Absent for a\n\t * refusal of `validated()`'s own schema.\n\t */\n\treadonly constraint?: ConstraintArgument;\n}\n\n/** The `extensions` of the error an invalid input becomes. */\nexport type BadUserInputExtensions = {\n\treadonly code: 'BAD_USER_INPUT';\n\treadonly issues: readonly ValidationIssue[];\n};\n\n/** Names the `@constraint` argument behind an issue, when there is one. */\nexport type ConstraintOf = (\n\tissue: z.core.$ZodIssue,\n) => ConstraintArgument | undefined;\n\nfunction issuesOf(\n\terror: z.ZodError,\n\tconstraintOf?: ConstraintOf,\n): ValidationIssue[] {\n\treturn error.issues.map((issue) => {\n\t\tconst path = issue.path.map((key) =>\n\t\t\ttypeof key === 'number' ? key : String(key),\n\t\t);\n\t\tconst constraint = constraintOf?.(issue);\n\t\treturn constraint\n\t\t\t? { path, message: issue.message, code: issue.code, constraint }\n\t\t\t: { path, message: issue.message, code: issue.code };\n\t});\n}\n\nfunction errorOf(where: string, issues: ValidationIssue[]): GraphQLError {\n\tconst [first] = issues;\n\tconst reason = first\n\t\t? `${first.path.join('.') || 'arguments'}: ${first.message}`\n\t\t: 'refused';\n\tconst extensions: BadUserInputExtensions = { code: 'BAD_USER_INPUT', issues };\n\treturn new GraphQLError(`Invalid arguments for ${where}. ${reason}`, {\n\t\textensions,\n\t});\n}\n\n/**\n * The one error an invalid input becomes: `extensions.code` is\n * `BAD_USER_INPUT`, the code Apollo and most clients already read, and\n * `extensions.issues` lists every reason with its path, so a form can show\n * each one beside its field. The message names the field and the first\n * reason, for a log line.\n */\nexport function badUserInput(where: string, error: z.ZodError): GraphQLError {\n\treturn errorOf(where, issuesOf(error));\n}\n\n/** The parsed arguments, or the error above, its issues named by `constraintOf`. */\nexport async function parseArgs(\n\tschema: z.ZodType,\n\targs: unknown,\n\twhere: string,\n\tconstraintOf?: ConstraintOf,\n): Promise<unknown> {\n\tconst result = await schema.safeParseAsync(args);\n\tif (!result.success)\n\t\tthrow errorOf(where, issuesOf(result.error, constraintOf));\n\treturn result.data;\n}\n",
+    "import { GraphQLError, type GraphQLErrorOptions } from 'graphql';\n\n/** The code of the error `invalidInputError` builds, and its default message. */\nexport const INVALID_INPUT = 'validation.errors.invalid-input';\n\n/** Values a message is built from, such as `{ min: 2 }`. */\nexport type IssueParams = Record<string, string | number>;\n\n/** One field at fault: where it is, why, and what the reason's message needs. */\nexport interface FieldIssue {\n\t/** The field inside the input, dotted: `person.firstName`, `tags.1`. */\n\treadonly path: string;\n\t/** A code your client and your translations know: `validation.errors.too-short`. */\n\treadonly code: string;\n\t/** Values the message needs; an object with no key counts as none. */\n\treadonly params?: IssueParams;\n}\n\n/** One entry of `extensions.fields`: a `FieldIssue` with its message. */\nexport interface FieldError {\n\treadonly path: string;\n\treadonly code: string;\n\t/** `translate(code, params)`, or the code itself without a translator. */\n\treadonly message: string;\n\t/** Present only when the issue had params with at least one key. */\n\treadonly params?: IssueParams;\n}\n\n/** Turns a code (and its params) into the text a person reads. */\nexport type Translate = (code: string, params?: IssueParams) => string;\n\n/** The options of `invalidInputError`: GraphQL's own, and a translator. */\nexport type InvalidInputOptions = GraphQLErrorOptions & {\n\treadonly translate?: Translate;\n};\n\n/** The options of `fieldsError`: also an HTTP status and the error's own params. */\nexport type FieldsErrorOptions = InvalidInputOptions & {\n\t/** `extensions.http.status`, for a server that reads it (409, ...). */\n\treadonly status?: number;\n\treadonly params?: IssueParams;\n};\n\n/** `params` itself, or `undefined` when it holds no key: never `{}`. */\nfunction paramsOf(params: IssueParams | undefined): IssueParams | undefined {\n\treturn params && Object.keys(params).length > 0 ? params : undefined;\n}\n\nfunction messageOf(\n\tcode: string,\n\tparams: IssueParams | undefined,\n\ttranslate: Translate | undefined,\n): string {\n\treturn translate?.(code, params) ?? code;\n}\n\nfunction fieldsOf(\n\tissues: readonly FieldIssue[],\n\ttranslate: Translate | undefined,\n): FieldError[] {\n\treturn issues.map(({ path, code, params: given }) => {\n\t\tconst params = paramsOf(given);\n\t\treturn {\n\t\t\tpath,\n\t\t\tcode,\n\t\t\tmessage: messageOf(code, params, translate),\n\t\t\t...(params && { params }),\n\t\t};\n\t});\n}\n\n/**\n * One 400 error listing every field at fault, for an API that answers invalid\n * input this way: `extensions` is `{ code: 'validation.errors.invalid-input',\n * http: { status: 400 }, fields }`, each field with its translated message\n * (the code itself without `translate`), in the order given. GraphQL's\n * options (`originalError`, `path`, `nodes`, ...) are kept; an `extensions`\n * among them is replaced by this one.\n */\nexport function invalidInputError(\n\tissues: readonly FieldIssue[],\n\toptions: InvalidInputOptions = {},\n): GraphQLError {\n\tconst { translate, ...graphql } = options;\n\treturn new GraphQLError(messageOf(INVALID_INPUT, undefined, translate), {\n\t\t...graphql,\n\t\textensions: {\n\t\t\tcode: INVALID_INPUT,\n\t\t\thttp: { status: 400 },\n\t\t\tfields: fieldsOf(issues, translate),\n\t\t},\n\t});\n}\n\n/**\n * A refusal of your own (a 409 conflict, say) that names the fields at\n * fault: `extensions` is `{ code, params?, http?: { status }, fields }`, the\n * fields worded as `invalidInputError` words them, the message\n * `translate(code, params)` or the code. An `extensions` among the options\n * is replaced by this one.\n */\nexport function fieldsError(\n\tcode: string,\n\tissues: readonly FieldIssue[],\n\toptions: FieldsErrorOptions = {},\n): GraphQLError {\n\tconst { translate, status, params: given, ...graphql } = options;\n\tconst params = paramsOf(given);\n\treturn new GraphQLError(messageOf(code, params, translate), {\n\t\t...graphql,\n\t\textensions: {\n\t\t\tcode,\n\t\t\t...(params && { params }),\n\t\t\t...(status && { http: { status } }),\n\t\t\tfields: fieldsOf(issues, translate),\n\t\t},\n\t});\n}\n\n/**\n * A GraphQL or Zod path as a `FieldIssue` path: dotted, without the leading\n * `input` argument when a field follows it, a symbol written as\n * `String(key)`. `['input', 'person', 'firstName']` is `person.firstName`,\n * `['input', 'tags', 1]` is `tags.1`, `['first']` and `['input']` stay as\n * they are.\n */\nexport function inputPath(path: readonly PropertyKey[]): string {\n\tconst [first, ...rest] = path;\n\treturn (first === 'input' && rest.length > 0 ? rest : path)\n\t\t.map((key) => String(key))\n\t\t.join('.');\n}\n",
+    "import type { z } from 'zod';\nimport { type FieldIssue, inputPath } from './invalid-input';\n\n/**\n * The codes `fieldIssueOf` gives, each under `validation.errors.`: a string's\n * length (`too-short`, `too-long`), a number's or bigint's bound or multiple\n * (`out-of-range`), a list's or set's size (`too-few`, `too-many`), a named\n * format or a pattern (`invalid-format`), anything else (`invalid`).\n */\nexport const FIELD_CODES = {\n\ttooShort: 'validation.errors.too-short',\n\ttooLong: 'validation.errors.too-long',\n\toutOfRange: 'validation.errors.out-of-range',\n\ttooFew: 'validation.errors.too-few',\n\ttooMany: 'validation.errors.too-many',\n\tinvalidFormat: 'validation.errors.invalid-format',\n\tinvalid: 'validation.errors.invalid',\n} as const;\n\n/** The string checks Zod reports as `invalid_format` that are not a format. */\nconst TEXT_CHECKS: ReadonlySet<string> = new Set([\n\t'starts_with',\n\t'ends_with',\n\t'includes',\n]);\n\n/**\n * A Zod issue as a `FieldIssue`, for `invalidInputError`: its path through\n * `inputPath` (dotted, a leading `input` dropped) and one of `FIELD_CODES`,\n * without params. `too-short` / `too-long` for a string's length,\n * `out-of-range` for a number's or bigint's bound or a multiple, `too-few` /\n * `too-many` for a list's or set's size, `invalid-format` for a named format\n * or a pattern, `invalid` for anything else (a prefix, a suffix or a\n * substring included).\n */\nexport function fieldIssueOf(issue: z.core.$ZodIssue): FieldIssue {\n\treturn { path: inputPath(issue.path), code: codeOf(issue) };\n}\n\nfunction codeOf(issue: z.core.$ZodIssue): string {\n\tswitch (issue.code) {\n\t\tcase 'too_small':\n\t\tcase 'too_big': {\n\t\t\tconst small = issue.code === 'too_small';\n\t\t\tswitch (issue.origin) {\n\t\t\t\tcase 'string':\n\t\t\t\t\treturn small ? FIELD_CODES.tooShort : FIELD_CODES.tooLong;\n\t\t\t\tcase 'number':\n\t\t\t\tcase 'bigint':\n\t\t\t\t\treturn FIELD_CODES.outOfRange;\n\t\t\t\tcase 'array':\n\t\t\t\tcase 'set':\n\t\t\t\t\treturn small ? FIELD_CODES.tooFew : FIELD_CODES.tooMany;\n\t\t\t\tdefault:\n\t\t\t\t\treturn FIELD_CODES.invalid;\n\t\t\t}\n\t\t}\n\t\tcase 'not_multiple_of':\n\t\t\treturn FIELD_CODES.outOfRange;\n\t\tcase 'invalid_format':\n\t\t\t// A prefix, a suffix or a substring is not a format: only a named\n\t\t\t// format (`email`, `uuid`, …) or a pattern is.\n\t\t\treturn TEXT_CHECKS.has(issue.format)\n\t\t\t\t? FIELD_CODES.invalid\n\t\t\t\t: FIELD_CODES.invalidFormat;\n\t\tdefault:\n\t\t\treturn FIELD_CODES.invalid;\n\t}\n}\n",
     "import type { GraphQLFieldResolver, GraphQLResolveInfo } from 'graphql';\nimport { z } from 'zod';\nimport { parseArgs } from './bad-user-input';\n\n/** An object schema of the arguments, or its shape. */\nexport type ArgsSchema = z.ZodType<Record<string, unknown>> | z.ZodRawShape;\n\n/** The schema `ArgsSchema` stands for. */\nexport type SchemaOf<S extends ArgsSchema> = S extends z.ZodType\n\t? S\n\t: z.ZodObject<S & z.ZodRawShape>;\n\n/**\n * A resolver whose arguments are checked by `schema` before it runs, for what\n * a `@constraint` cannot say: a rule across arguments, a business refinement,\n * an async check. It receives the parsed arguments (`z.output`), defaults and\n * transforms applied; an invalid input is the same `BAD_USER_INPUT` error as\n * the directives'.\n *\n * ```ts\n * signUp: validated(\n *   z.object({ input: signUpSchema }).refine(({ input }) => input.password !== input.email),\n *   (_, { input }) => users.create(input),\n * )\n * ```\n */\nexport function validated<\n\tS extends ArgsSchema,\n\tTSource = unknown,\n\tTContext = unknown,\n\tTResult = unknown,\n>(\n\tschema: S,\n\tresolve: (\n\t\tsource: TSource,\n\t\targs: z.output<SchemaOf<S>>,\n\t\tcontext: TContext,\n\t\tinfo: GraphQLResolveInfo,\n\t) => TResult,\n): GraphQLFieldResolver<\n\tTSource,\n\tTContext,\n\tz.input<SchemaOf<S>>,\n\tPromise<Awaited<TResult>>\n> {\n\t// `_zod`, not `instanceof`: a schema from another copy of zod is still one.\n\tconst checked = (\n\t\t'_zod' in schema ? schema : z.object(schema as z.ZodRawShape)\n\t) as z.ZodType;\n\treturn async (source, args, context, info): Promise<Awaited<TResult>> => {\n\t\tconst where = `${info.parentType.name}.${info.fieldName}`;\n\t\tconst parsed = (await parseArgs(checked, args, where)) as z.output<\n\t\t\tSchemaOf<S>\n\t\t>;\n\t\treturn await resolve(source, parsed, context, info);\n\t};\n}\n",
     "import {\n\tdefaultFieldResolver,\n\ttype GraphQLField,\n\ttype GraphQLFieldResolver,\n\ttype GraphQLSchema,\n} from 'graphql';\nimport type { z } from 'zod';\nimport { parseArgs } from './bad-user-input';\nimport { checkConstraints } from './builder/check-constraints';\nimport type { FormatSchemas, OwnFormats } from './formats/registry';\nimport { constraintOf } from './rules';\n\n// Symbol.for: two copies of the package in one tree still wrap a field once.\nconst wrapped = Symbol.for('@nxgt/graphql-validation/wrapped');\n// The formats a schema was wrapped with, kept on the schema itself.\nconst wrappedWith = Symbol.for('@nxgt/graphql-validation/formats');\n\n/** What `withValidation` takes besides the schema. */\nexport interface WithValidationOptions<\n\tF extends FormatSchemas = FormatSchemas,\n> {\n\t/**\n\t * The application's own formats, which `@constraint(format: \"...\")` may\n\t * name beside the built-in ones: one Zod string schema each, keyed by its\n\t * name (lowercase letters, digits and hyphens). A built-in name is a type\n\t * error, and refused at startup.\n\t */\n\treadonly formats?: OwnFormats<F>;\n}\n\ntype Resolver = GraphQLFieldResolver<unknown, unknown> & { [wrapped]?: true };\n\nfunction checking(\n\tschema: z.ZodType,\n\twhere: string,\n\tresolve: Resolver,\n): Resolver {\n\tconst check: Resolver = async (source, args, context, info) =>\n\t\tawait resolve(\n\t\t\tsource,\n\t\t\tawait parseArgs(schema, args, where, constraintOf),\n\t\t\tcontext,\n\t\t\tinfo,\n\t\t);\n\tcheck[wrapped] = true;\n\treturn check;\n}\n\n/**\n * Wraps a field once. A subscription field is checked in `subscribe`, which\n * runs once per subscription — graphql's default one when the field has none\n * — and its `resolve` runs once per event, with the same arguments, already\n * checked.\n */\nfunction wrap(\n\tfield: GraphQLField<unknown, unknown>,\n\targs: z.ZodType,\n\twhere: string,\n\tsubscription: boolean,\n): void {\n\tconst subscribe = (field.subscribe ??\n\t\t(subscription ? defaultFieldResolver : undefined)) as Resolver | undefined;\n\tif (subscribe) {\n\t\tif (!subscribe[wrapped]) field.subscribe = checking(args, where, subscribe);\n\t\treturn;\n\t}\n\tconst resolve = (field.resolve ?? defaultFieldResolver) as Resolver;\n\tif (!resolve[wrapped]) field.resolve = checking(args, where, resolve);\n}\n\n/**\n * Checks every `@constraint` of `schema` before the resolvers run. Each\n * field with a constrained argument — directly, or anywhere inside an input\n * type it takes — gets its resolver (and its `subscribe`) wrapped: the\n * arguments are parsed by the Zod schema the directives describe, the\n * resolver receives the parsed value, and an invalid input becomes one\n * `BAD_USER_INPUT` error. Fields with nothing to check are left untouched.\n *\n * The schema is built here, once: a constraint that cannot apply (a\n * `minLength` on an `Int`, an unknown format, a bad pattern) throws now, not\n * on the first request. The resolvers are wrapped in place and the same\n * schema is returned, so it goes wherever it went before; calling it twice\n * wraps nothing twice. Call it last, once every resolver is attached: a\n * resolver set on a field afterwards replaces the check.\n *\n * A `@constraint` on an interface's argument must be repeated on each\n * object's field, which is the one that resolves; a field that drops it\n * fails here.\n *\n * The directives are read from the SDL (`astNode`), so a schema built from\n * type definitions — `buildSchema`, `makeExecutableSchema`, Yoga, Apollo —\n * is checked; a code-first schema with no SDL has no `@constraint` to read.\n *\n * `options.formats` adds the application's own formats; wrapping a schema\n * again throws unless the record has the same names, each the very same\n * schema (no formats after some, or some after none, throws too), since its\n * fields are already checked against the first ones.\n */\nexport function withValidation<\n\tS extends GraphQLSchema,\n\t// biome-ignore lint/complexity/noBannedTypes: no formats of its own by default\n\tconst F extends FormatSchemas = {},\n>(schema: S, options: WithValidationOptions<F> = {}): S {\n\tconst formats: FormatSchemas = options.formats ?? {};\n\tconst holder = schema as unknown as { [wrappedWith]?: FormatSchemas };\n\tconst before = holder[wrappedWith];\n\tif (before && !sameFormats(before, formats)) {\n\t\tthrow new Error(\n\t\t\t'withValidation: this schema is already wrapped with other formats. Call withValidation once, with every format.',\n\t\t);\n\t}\n\tconst directive = checkConstraints(\n\t\tschema,\n\t\t(type, field, args) => {\n\t\t\tconst subscription = type === schema.getSubscriptionType();\n\t\t\twrap(field, args, `${type.name}.${field.name}`, subscription);\n\t\t},\n\t\tformats,\n\t);\n\tif (!directive) {\n\t\tthrow new Error(\n\t\t\t'withValidation: this schema declares no @constraint directive. Add constraintTypeDefs to its type definitions.',\n\t\t);\n\t}\n\tif (!before) Object.defineProperty(schema, wrappedWith, { value: formats });\n\treturn schema;\n}\n\n/** The same names, each the very same schema. */\nfunction sameFormats(a: FormatSchemas, b: FormatSchemas): boolean {\n\tconst names = Object.keys(a);\n\treturn (\n\t\tnames.length === Object.keys(b).length &&\n\t\tnames.every((name) => Object.hasOwn(b, name) && a[name] === b[name])\n\t);\n}\n"
   ],
-  "mappings": "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",
-  "debugId": "B588BD3EF63841CA64756E2164756E21",
+  "mappings": "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",
+  "debugId": "BC885DEBB67481A464756E2164756E21",
   "names": []
 }

package/dist/invalid-input.d.ts

@@ -0,0 +1,61 @@
+import { GraphQLError, type GraphQLErrorOptions } from 'graphql';
+/** The code of the error `invalidInputError` builds, and its default message. */
+export declare const INVALID_INPUT = "validation.errors.invalid-input";
+/** Values a message is built from, such as `{ min: 2 }`. */
+export type IssueParams = Record<string, string | number>;
+/** One field at fault: where it is, why, and what the reason's message needs. */
+export interface FieldIssue {
+    /** The field inside the input, dotted: `person.firstName`, `tags.1`. */
+    readonly path: string;
+    /** A code your client and your translations know: `validation.errors.too-short`. */
+    readonly code: string;
+    /** Values the message needs; an object with no key counts as none. */
+    readonly params?: IssueParams;
+}
+/** One entry of `extensions.fields`: a `FieldIssue` with its message. */
+export interface FieldError {
+    readonly path: string;
+    readonly code: string;
+    /** `translate(code, params)`, or the code itself without a translator. */
+    readonly message: string;
+    /** Present only when the issue had params with at least one key. */
+    readonly params?: IssueParams;
+}
+/** Turns a code (and its params) into the text a person reads. */
+export type Translate = (code: string, params?: IssueParams) => string;
+/** The options of `invalidInputError`: GraphQL's own, and a translator. */
+export type InvalidInputOptions = GraphQLErrorOptions & {
+    readonly translate?: Translate;
+};
+/** The options of `fieldsError`: also an HTTP status and the error's own params. */
+export type FieldsErrorOptions = InvalidInputOptions & {
+    /** `extensions.http.status`, for a server that reads it (409, ...). */
+    readonly status?: number;
+    readonly params?: IssueParams;
+};
+/**
+ * One 400 error listing every field at fault, for an API that answers invalid
+ * input this way: `extensions` is `{ code: 'validation.errors.invalid-input',
+ * http: { status: 400 }, fields }`, each field with its translated message
+ * (the code itself without `translate`), in the order given. GraphQL's
+ * options (`originalError`, `path`, `nodes`, ...) are kept; an `extensions`
+ * among them is replaced by this one.
+ */
+export declare function invalidInputError(issues: readonly FieldIssue[], options?: InvalidInputOptions): GraphQLError;
+/**
+ * A refusal of your own (a 409 conflict, say) that names the fields at
+ * fault: `extensions` is `{ code, params?, http?: { status }, fields }`, the
+ * fields worded as `invalidInputError` words them, the message
+ * `translate(code, params)` or the code. An `extensions` among the options
+ * is replaced by this one.
+ */
+export declare function fieldsError(code: string, issues: readonly FieldIssue[], options?: FieldsErrorOptions): GraphQLError;
+/**
+ * A GraphQL or Zod path as a `FieldIssue` path: dotted, without the leading
+ * `input` argument when a field follows it, a symbol written as
+ * `String(key)`. `['input', 'person', 'firstName']` is `person.firstName`,
+ * `['input', 'tags', 1]` is `tags.1`, `['first']` and `['input']` stay as
+ * they are.
+ */
+export declare function inputPath(path: readonly PropertyKey[]): string;
+//# sourceMappingURL=invalid-input.d.ts.map

package/dist/invalid-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalid-input.d.ts","sourceRoot":"","sources":["../src/invalid-input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEjE,iFAAiF;AACjF,eAAO,MAAM,aAAa,oCAAoC,CAAC;AAE/D,4DAA4D;AAC5D,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAE1D,iFAAiF;AACjF,MAAM,WAAW,UAAU;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED,yEAAyE;AACzE,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED,kEAAkE;AAClE,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,MAAM,CAAC;AAEvE,2EAA2E;AAC3E,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,GAAG;IACvD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAC/B,CAAC;AAEF,oFAAoF;AACpF,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,GAAG;IACtD,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC9B,CAAC;AA8BF;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,OAAO,GAAE,mBAAwB,GAC/B,YAAY,CAUd;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,OAAO,GAAE,kBAAuB,GAC9B,YAAY,CAYd;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAK9D"}

package/docs/README.md

@@ -5,6 +5,7 @@
 | 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 and your own, lists and nested inputs |
+| [Answering invalid input as one error](guide/invalid-input.md) | your API answers invalid input as one 400 error with a list of fields (`invalidInputError`, `fieldIssueOf` for a Zod parse), or a refusal such as a 409 names the fields at fault (`fieldsError`) |
 | [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

package/docs/guide/constraints.md

@@ -302,10 +302,9 @@ What a format of your own is:
   then at most 64 characters. A check of yours with `abort: true`
   (`.refine(…, { message, abort: true })`) stops the rules after it, on the
   server as in a generated client: only its issue is returned. Once an async
-  check of your format is pending, the rules have already run on the server:
-  their issues come first (the error's message is then a rule's, not your
-  format's) and the abort stops nothing. Put an aborting check before any
-  async one.
+  check of your format is pending, a client has already run the rules, so
+  the abort stops nothing on either side; the server lists your format's
+  issues first. Put an aborting check before any async one.
 - **Its messages are yours.** A refusal reads as your schema writes it (the
   package's own messages never name the value; yours may, so keep the input
   out of them if your logs or clients should not see it). Every issue your
@@ -319,13 +318,30 @@ What a format of your own is:
 - **Named in lowercase letters, digits and hyphens**, starting with a letter
   (`siret`, `work-email`, `iso-6346`). A built-in name (`email`, `uuid`, …)
   cannot be replaced: it is a type error, and refused at startup.
-- **An async check stays async.** `withValidation` parses asynchronously, so a
-  `.refine(async …)` works in a request, from this package's zod or another
-  copy. It runs once per value, and when it rejects (`db down`) the operation
-  fails with that error, as a resolver's would. A default value is checked
-  at startup synchronously, so a field whose format is async cannot have a
+- **An async check stays async, and runs once.** `withValidation` parses
+  asynchronously, so a `.refine(async …)` (or an async `.superRefine()`, or
+  any check returning a promise) works in a request, from this package's zod
+  or another copy. It runs once per value, from the first, and when it
+  rejects (`db down`) the operation fails with that error, as a resolver's
+  would: no rejection is left unhandled. A default value is checked at
+  startup synchronously, so a field whose format is async cannot have a
   default: startup throws `The default value of Query.a(s:) cannot be checked
-  at startup: the format "free" checks asynchronously, …`.
+  at startup: the format "free" checks asynchronously, …`. A check that
+  throws on the default value reads the same, since its error ends a run
+  startup cannot wait for.
+
+- **Only Zod's public API runs it.** Your format is parsed with
+  `safeParseAsync` only, never a synchronous `safeParse` that would start an
+  async check and drop it; a `.catch()` and `.refine()`s chained after your
+  checks tell whether the run finished at once and which abort stopped it,
+  and the rules after it run inside it, replayed on its issues as Zod runs
+  them when chained on your schema. No Zod internal is called, so a Zod 4
+  release that changes its internals changes nothing here, and a format
+  from another copy of Zod (another version included) gets its messages
+  from that copy's configuration (`z.config()`). Startup still reads the
+  schema's definition (`_zod.def`, Zod's introspection) to refuse what
+  rewrites the value. The cost, measured on Bun 1.4.2 against 0.3.0: about
+  0.1 µs more per accepted value and 1.5 µs more per refused one.
 
 Call `withValidation` once, with every format. A second call on the same
 schema wraps nothing when its record has the same names, each the very same

package/docs/guide/errors.md

@@ -2,7 +2,9 @@
 
 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).
+[Constraints](constraints.md). For an API that answers invalid input as one
+400 error with a list of fields, see
+[Answering invalid input as one error](invalid-input.md).
 
 ## The error
 

package/docs/guide/invalid-input.md

@@ -0,0 +1,240 @@
+# Answering invalid input as one error
+
+Some APIs answer invalid input as **one 400 error with a list of fields**,
+each with a code a client translates or a message already translated, rather
+than as [`BAD_USER_INPUT`](errors.md) with Zod's issues. `invalidInputError`
+and `fieldsError` build that error, so every resolver and every module words
+it the same way. They do not change what `withValidation` and `validated`
+raise: those still throw `BAD_USER_INPUT`.
+
+## The error
+
+```ts
+import { invalidInputError } from '@nxgt/graphql-validation';
+
+throw invalidInputError(
+  [
+    { path: 'person.lastName', code: 'validation.errors.required' },
+    { path: 'person.firstName', code: 'validation.errors.too-short', params: { min: 2 } },
+  ],
+  { translate: (code, params) => t(code, params) }, // your i18n function
+);
+```
+
+```json
+{
+  "errors": [
+    {
+      "message": "Invalid input",
+      "path": ["createPerson"],
+      "extensions": {
+        "code": "validation.errors.invalid-input",
+        "http": { "status": 400 },
+        "fields": [
+          { "path": "person.lastName", "code": "validation.errors.required", "message": "Required" },
+          { "path": "person.firstName", "code": "validation.errors.too-short", "message": "At least 2 characters", "params": { "min": 2 } }
+        ]
+      }
+    }
+  ],
+  "data": { "createPerson": null }
+}
+```
+
+- `message` is `translate('validation.errors.invalid-input')`, or that code
+  itself without `translate` (also exported as `INVALID_INPUT`).
+- `extensions.code` is `validation.errors.invalid-input`, and
+  `extensions.http.status` is `400`, for a server that sets the response's
+  HTTP status from it (GraphQL Yoga and Apollo Server read this key).
+- `extensions.fields` holds one entry per issue, **in the order given**
+  (duplicates kept): `path` and `code` as you wrote them, `message` as
+  `translate(code, params)` or the code itself, and `params` only when the
+  issue has some.
+- **`params` is never `{}`**: an issue whose `params` has no key is written
+  without it, and `translate` receives `undefined` for it.
+- A `translate` that returns `undefined` at run time (a missing key in some
+  i18n libraries) falls back to the code, as if there were none.
+
+## GraphQL's options
+
+The second argument also takes `GraphQLError`'s own options, so the error
+keeps its cause and its place in the response:
+
+```ts
+throw invalidInputError(issues, {
+  translate,
+  originalError: zodError, // kept: error.originalError
+  path: info.path ? [info.path.key] : undefined,
+});
+```
+
+**`extensions` among them is replaced**, not merged: the error's
+`extensions` is always exactly the shape above. Put anything else your
+server needs in a `formatError` hook.
+
+## From a resolver
+
+A check that needs the database, or a rule your schema cannot say, ends with
+the same error:
+
+```ts
+import { type FieldIssue, invalidInputError } from '@nxgt/graphql-validation';
+
+const resolvers = {
+  Mutation: {
+    async createPerson(_: unknown, { input }: { input: PersonInput }, { t }: Context) {
+      const issues: FieldIssue[] = [];
+      if (!input.person.lastName.trim())
+        issues.push({ path: 'person.lastName', code: 'validation.errors.required' });
+      if (input.person.birthDate > new Date())
+        issues.push({ path: 'person.birthDate', code: 'validation.errors.in-the-future' });
+      if (issues.length) throw invalidInputError(issues, { translate: t });
+      return people.create(input.person);
+    },
+  },
+};
+```
+
+## From a zod parse
+
+`fieldIssueOf(issue)` maps one Zod issue to a `FieldIssue`: its path through
+`inputPath`, and a code under `validation.errors.`, without params:
+
+| Zod issue | `code` |
+| --- | --- |
+| a string too short or too long (`min`, `max`, `length`) | `validation.errors.too-short` / `validation.errors.too-long` |
+| a number or bigint out of its bounds, or not a multiple | `validation.errors.out-of-range` |
+| a list or set too small or too big | `validation.errors.too-few` / `validation.errors.too-many` |
+| a named format (`email`, `uuid`, …) or a pattern (`regex`) | `validation.errors.invalid-format` |
+| anything else: `startsWith`, `endsWith`, `includes`, a refinement, a wrong type, a date's bound | `validation.errors.invalid` |
+
+The codes are also exported as `FIELD_CODES` (`FIELD_CODES.tooShort`, …),
+for your translations.
+
+```ts
+import { fieldIssueOf, invalidInputError } from '@nxgt/graphql-validation';
+import { z } from 'zod';
+
+const PersonInput = z.object({
+  person: z.object({
+    firstName: z.string().min(2),
+    email: z.email(),
+  }),
+});
+
+const result = PersonInput.safeParse(input);
+if (!result.success)
+  throw invalidInputError(result.error.issues.map(fieldIssueOf), {
+    translate: t,
+    originalError: result.error,
+  });
+// fields: person.firstName (validation.errors.too-short),
+//         person.email (validation.errors.invalid-format)
+```
+
+[`@nxgt/graphql-codegen-msw`](https://github.com/softistx/nxgt-graphql/blob/develop/packages/graphql-codegen-msw/docs/guide/handlers.md)'s
+mocks apply the same mapping by default, so a mocked refusal reads as the
+server's. For a code of your own, or params (`{ min: 2 }`), map the issue
+yourself and keep `fieldIssueOf` for the rest:
+
+```ts
+import { type FieldIssue, fieldIssueOf } from '@nxgt/graphql-validation';
+
+const issueOf = (issue: z.core.$ZodIssue): FieldIssue =>
+  issue.code === 'too_small' && issue.origin === 'string'
+    ? { ...fieldIssueOf(issue), params: { min: Number(issue.minimum) } }
+    : fieldIssueOf(issue);
+```
+
+`inputPath` turns a GraphQL or Zod path into a dotted one, dropping the
+leading `input` argument: `inputPath(['input', 'person', 'firstName'])` is
+`person.firstName`, `['input', 'tags', 1]` is `tags.1`; a path that does not
+start with `input` (`['first']`), or is `['input']` alone, is only joined
+with dots. It takes a Zod issue's path as it is, a symbol key written as
+`String(key)`.
+
+The same mapping reads [`BAD_USER_INPUT`](errors.md)'s `issues[].path`, which
+starts with the argument name.
+
+## A refusal that names fields: `fieldsError`
+
+For a refusal of your own that is not a 400, a 409 conflict for instance,
+that still points at the fields at fault:
+
+```ts
+import { fieldsError } from '@nxgt/graphql-validation';
+
+throw fieldsError(
+  'person.errors.duplicate',
+  [{ path: 'person.email', code: 'person.errors.email-taken' }],
+  { translate: t, status: 409, params: { name: existing.name } },
+);
+```
+
+```json
+{
+  "message": "Already registered as Ada",
+  "extensions": {
+    "code": "person.errors.duplicate",
+    "params": { "name": "Ada" },
+    "http": { "status": 409 },
+    "fields": [
+      { "path": "person.email", "code": "person.errors.email-taken", "message": "This email is taken" }
+    ]
+  }
+}
+```
+
+- `message` is `translate(code, params)`, or `code`.
+- `extensions` is `{ code, params?, http?, fields }`, in that order:
+  `params` only when it has a key, `http: { status }` only when `status` is
+  given, `fields` worded as `invalidInputError` words them.
+- GraphQL's options are kept and an `extensions` among them is replaced, as
+  above.
+
+## Types
+
+```ts
+import type { GraphQLError, GraphQLErrorOptions } from 'graphql';
+import type { z } from 'zod';
+
+type IssueParams = Record<string, string | number>;
+
+interface FieldIssue {
+  readonly path: string;
+  readonly code: string;
+  readonly params?: IssueParams; // {} counts as none
+}
+
+/** One entry of `extensions.fields`. */
+interface FieldError {
+  readonly path: string;
+  readonly code: string;
+  readonly message: string;
+  readonly params?: IssueParams;
+}
+
+type Translate = (code: string, params?: IssueParams) => string;
+
+type InvalidInputOptions = GraphQLErrorOptions & { readonly translate?: Translate };
+type FieldsErrorOptions = InvalidInputOptions & {
+  readonly status?: number;
+  readonly params?: IssueParams;
+};
+
+declare const INVALID_INPUT: 'validation.errors.invalid-input';
+declare function invalidInputError(issues: readonly FieldIssue[], options?: InvalidInputOptions): GraphQLError;
+declare function fieldsError(code: string, issues: readonly FieldIssue[], options?: FieldsErrorOptions): GraphQLError;
+declare function inputPath(path: readonly PropertyKey[]): string;
+
+declare const FIELD_CODES: {
+  readonly tooShort: 'validation.errors.too-short';
+  readonly tooLong: 'validation.errors.too-long';
+  readonly outOfRange: 'validation.errors.out-of-range';
+  readonly tooFew: 'validation.errors.too-few';
+  readonly tooMany: 'validation.errors.too-many';
+  readonly invalidFormat: 'validation.errors.invalid-format';
+  readonly invalid: 'validation.errors.invalid';
+};
+declare function fieldIssueOf(issue: z.core.$ZodIssue): FieldIssue;
+```

package/docs/roadmap.md

@@ -4,19 +4,35 @@ What `@nxgt/graphql-validation` is heading for, phrased as what you get.
 
 ## Now
 
-- **Your own formats** (in progress, not released yet). Name a Zod string schema in
-  `@constraint(format: "...")`: `withValidation(schema, { formats })`, one
-  record your module exports, checked at startup, its refusals named
-  `format`. `@nxgt/graphql-codegen-zod` 0.3 reads the same record, so the
-  client refuses what the server refuses, with the same messages.
+Nothing in progress.
 
 ## Next
 
 - **Schemas that read the context**, `(args, context) => schema`, for checks
   that need the request (uniqueness in a database, permissions).
 
+## Later
+
+- **Emit the invalid-input shape directly.** An option for `withValidation`
+  and `validated` to raise the `invalidInputError` shape in place of
+  `BAD_USER_INPUT`, so an API using it needs no mapping of its own.
+
 ## Shipped
 
+- **Answering invalid input as one error** — 0.4.0.
+  `invalidInputError(issues, { translate })` builds one 400 error whose
+  `extensions.fields` lists every field at fault with your own codes,
+  translated; `fieldsError` does the same for a refusal such as a 409
+  conflict; `fieldIssueOf` maps a Zod issue to a field and a code
+  (`too-short`, `invalid-format`, …), the mapping
+  [`@nxgt/graphql-codegen-msw`](https://www.npmjs.com/package/@nxgt/graphql-codegen-msw)'s
+  mocks apply; `inputPath` turns a GraphQL or Zod path into `person.firstName`.
+- **Your own formats** — 0.3.0. Name a Zod string schema in
+  `@constraint(format: "...")`: `withValidation(schema, { formats })`, one
+  record your module exports, checked at startup, its refusals named
+  `format`. `@nxgt/graphql-codegen-zod` 0.3 reads the same record, so the
+  client refuses what the server refuses, with the same messages. From
+  0.3.1 they run through Zod's public API only.
 - **Declarations resolve under `nodenext`** — 0.2.1. `moduleResolution`
   `nodenext` and `node16` find every export, as `bundler` does.
 - **A Zod codegen plugin** — 0.2.0. [`@nxgt/graphql-codegen-zod`](https://www.npmjs.com/package/@nxgt/graphql-codegen-zod)