@nxgt/graphql-validation 0.0.0-stage → 0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,210 @@
-# Temporary Holding Version
+# @nxgt/graphql-validation
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Validate GraphQL arguments and input fields with `@constraint` directives
+written in your schema. Each directive becomes a Zod schema that checks the
+arguments before your resolver runs; an invalid input is one `BAD_USER_INPUT`
+error that lists every reason with its path, so a form can show each one beside
+its field. For schema-first servers on `graphql` 16 and 17 (`graphql-js`,
+GraphQL Yoga, Apollo Server).
+
+## Install
+
+```sh
+bun add @nxgt/graphql-validation graphql zod typescript
+```
+
+Peers, all **required**:
+
+| Peer | Range |
+| --- | --- |
+| `graphql` | `^16.11.0 \|\| ^17.0.0` |
+| `zod` | `>=4.6.5 <5` |
+| `typescript` | `^6.0.3` |
+
+Your `tsconfig.json` needs:
+
+```jsonc
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler" // `nodenext` is not supported
+  }
+}
+```
+
+## Usage
+
+### Constrain arguments and input fields
+
+Add `constraintTypeDefs` to your type definitions, write `@constraint(...)`,
+build the schema with any schema-first builder (`buildSchema` from `graphql`,
+or `makeExecutableSchema` from `@graphql-tools/schema` as below), then call
+`withValidation(schema)` **last**, once every resolver is attached.
+
+```ts
+import { makeExecutableSchema } from '@graphql-tools/schema';
+import { constraintTypeDefs, withValidation } from '@nxgt/graphql-validation';
+
+const typeDefs = [
+  constraintTypeDefs,
+  /* GraphQL */ `
+    input SignUp {
+      email: String! @constraint(format: "email", maxLength: 254)
+      age: Int @constraint(min: 18)
+      tags: [String!] @constraint(maxItems: 5, maxLength: 20)
+    }
+    type Query {
+      user(id: ID! @constraint(format: "uuid")): String
+    }
+    type Mutation {
+      signUp(input: SignUp!): Boolean
+    }
+  `,
+];
+
+const resolvers = {
+  Mutation: {
+    // `input` is already checked: this only runs for a valid one
+    signUp: (_: unknown, { input }: { input: { email: string } }) => {
+      console.log(input.email);
+      return true;
+    },
+  },
+};
+
+export const schema = withValidation(makeExecutableSchema({ typeDefs, resolvers }));
+```
+
+`withValidation` wraps, in place, the resolver of each field that has
+something to check, and returns the same schema. A subscription field is
+checked once, in `subscribe`. Calling it twice wraps nothing twice. A
+constraint that cannot apply throws when you call it, not on the first
+request. The resolver receives the parsed arguments.
+
+Every argument, its rule and its Zod equivalent, and the formats, are in
+[Constraints](docs/guide/constraints.md).
+
+### Read the error
+
+```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", "age"], "message": "Too small: expected number to be >=18", "code": "too_small", "constraint": "min" }
+        ]
+      }
+    }
+  ]
+}
+```
+
+`issues[].path` is relative to the arguments, and `issues[].constraint` names the
+`@constraint` argument that refused. Mapping issues to form fields is
+in [Errors](docs/guide/errors.md).
+
+### Rules a directive cannot say
+
+`validated(schema, resolver)` checks the arguments with a Zod schema you write,
+for rules across fields, refinements and async checks. It raises the same error.
+
+```ts
+import { validated } from '@nxgt/graphql-validation';
+import { z } from 'zod';
+
+const resolvers = {
+  Query: {
+    range: validated(
+      z
+        .object({ from: z.number(), to: z.number() })
+        .refine(({ from, to }) => from <= to, {
+          message: 'from must not exceed to',
+          path: ['to'],
+        }),
+      (_, { from, to }) => to - from,
+    ),
+  },
+};
+```
+
+## IDE support
+
+An IDE's GraphQL plugin (JetBrains GraphQL, VS Code GraphQL) reads your `.graphql`
+files, not `constraintTypeDefs`, so it reports `Unknown directive "@constraint"`.
+The package ships the directive as a file; add it to your `graphql.config.yml`:
+
+```yaml
+schema:
+  - src/**/*.graphql
+  - node_modules/@nxgt/graphql-validation/graphql/constraint.graphqls
+```
+
+If your IDE does not index `node_modules`, or you want the file committed with
+your schema, write it into the project (Node or Bun), and list that path instead:
+
+```sh
+bunx nxgt-graphql-validation typedefs --out
+# or: npx nxgt-graphql-validation typedefs --out
+```
+
+`--out` alone writes `generated/graphql/constraint.graphqls`, `--out <file>` writes
+`<file>`, and without `--out` the SDL is printed. 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".`
+
+## Exports
+
+| Export | Is |
+| --- | --- |
+| `constraintTypeDefs` | the SDL of `@constraint`, to add to `typeDefs` |
+| `withValidation(schema)` | checks every `@constraint` of a schema before its resolvers run |
+| `validated(schema \| shape, resolver)` | a resolver whose arguments a Zod schema checks |
+| `badUserInput(where, zodError)` | builds the error above, for code that validates by hand |
+| `ValidationIssue`, `BadUserInputExtensions` | the types of `extensions.issues` and `extensions` |
+| `ConstraintArgument` | the type of `issues[].constraint`: `'minLength' \| 'format' \| ...` |
+| `ArgsSchema`, `SchemaOf` | the types `validated` accepts |
+
+Also shipped, outside `exports`:
+
+| File | Is |
+| --- | --- |
+| `graphql/constraint.graphqls` | the SDL of `@constraint` for IDEs; reference it by path, it is not importable |
+| `nxgt-graphql-validation` (bin) | `typedefs [--out [<file>]]` prints or writes that SDL; `--help` |
+
+## Traps
+
+- `@constraint` is read from the SDL. A code-first schema does not declare the
+  directive, so `withValidation` throws; one that declares it but whose
+  constrained types and fields have no SDL (code-first, or merged pieces) is
+  checked for nothing, and no error says so. Use type definitions.
+- Call `withValidation` last: a resolver set on a field afterwards replaces
+  the check.
+- A `@constraint` on an interface field's argument must be repeated on each
+  implementing object's field, or `withValidation` throws at startup.
+- `@constraint` is refused on an output field:
+  `Directive "@constraint" may not be used on FIELD_DEFINITION.`
+- `format: "date-time"` takes the canonical RFC 3339 form only (uppercase `T`
+  and `Z`, seconds present).
+
+Every startup error and its fix is in [Troubleshooting](docs/troubleshooting.md).
+
+## Documentation
+
+- [Documentation index](docs/README.md)
+- Guides: [Constraints](docs/guide/constraints.md), [Errors](docs/guide/errors.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Roadmap](docs/roadmap.md): a Zod codegen plugin, your own formats, schemas that read the context

package/dist/bad-user-input.d.ts

@@ -0,0 +1,35 @@
+import { GraphQLError } from 'graphql';
+import type { z } from 'zod';
+import type { ConstraintArgument } from './rules';
+/** One reason an input was refused, at its path inside the arguments. */
+export interface ValidationIssue {
+    /** `['input', 'address', 'zip']`: the argument, then the input fields. */
+    readonly path: readonly (string | number)[];
+    readonly message: string;
+    /** Zod's issue code: `too_small`, `invalid_format`, `custom`, ... */
+    readonly code: string;
+    /**
+     * The `@constraint` argument that refused (`minLength`, `format`), when a
+     * directive did: stable across Zod versions, unlike `code`. Absent for a
+     * refusal of `validated()`'s own schema.
+     */
+    readonly constraint?: ConstraintArgument;
+}
+/** The `extensions` of the error an invalid input becomes. */
+export type BadUserInputExtensions = {
+    readonly code: 'BAD_USER_INPUT';
+    readonly issues: readonly ValidationIssue[];
+};
+/** Names the `@constraint` argument behind an issue, when there is one. */
+export type ConstraintOf = (issue: z.core.$ZodIssue) => ConstraintArgument | undefined;
+/**
+ * The one error an invalid input becomes: `extensions.code` is
+ * `BAD_USER_INPUT`, the code Apollo and most clients already read, and
+ * `extensions.issues` lists every reason with its path, so a form can show
+ * each one beside its field. The message names the field and the first
+ * reason, for a log line.
+ */
+export declare function badUserInput(where: string, error: z.ZodError): GraphQLError;
+/** The parsed arguments, or the error above, its issues named by `constraintOf`. */
+export declare function parseArgs(schema: z.ZodType, args: unknown, where: string, constraintOf?: ConstraintOf): Promise<unknown>;
+//# sourceMappingURL=bad-user-input.d.ts.map

package/dist/bad-user-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bad-user-input.d.ts","sourceRoot":"","sources":["../src/bad-user-input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAED,8DAA8D;AAC9D,MAAM,MAAM,sBAAsB,GAAG;IACpC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CAC5C,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GAAG,CAC1B,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,KACnB,kBAAkB,GAAG,SAAS,CAAC;AA4BpC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,YAAY,CAE3E;AAED,oFAAoF;AACpF,wBAAsB,SAAS,CAC9B,MAAM,EAAE,CAAC,CAAC,OAAO,EACjB,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,YAAY,GACzB,OAAO,CAAC,OAAO,CAAC,CAKlB"}

package/dist/builder/args-schema.d.ts

@@ -0,0 +1,17 @@
+import type { GraphQLField, GraphQLObjectType } from 'graphql';
+import { z } from 'zod';
+import type { InputSchemas } from './input-schema';
+/**
+ * The schema of a field's arguments, or `undefined` when none of them can
+ * break a constraint, so a field with nothing to check is left untouched.
+ * `parent` is the type's name, for errors: `Mutation.signUp(input:)`.
+ */
+export declare function argsSchemaOf(inputs: InputSchemas, parent: string, field: GraphQLField<unknown, unknown>): z.ZodType | undefined;
+/**
+ * Fails when an object type's field does not repeat the `@constraint` its
+ * interface writes on an argument. The object's field is the one that
+ * resolves, and graphql lets it redeclare the argument bare: the interface's
+ * constraint would then check nothing, in silence.
+ */
+export declare function assertInterfaceConstraintsKept(inputs: InputSchemas, type: GraphQLObjectType): void;
+//# sourceMappingURL=args-schema.d.ts.map

package/dist/builder/args-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args-schema.d.ts","sourceRoot":"","sources":["../../src/builder/args-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,YAAY,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAChF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,YAAY,CAC3B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,GACnC,CAAC,CAAC,OAAO,GAAG,SAAS,CAUvB;AAcD;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC7C,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,iBAAiB,GACrB,IAAI,CAoBN"}

package/dist/builder/constraints.d.ts

@@ -0,0 +1,16 @@
+import { type DirectiveNode, type GraphQLDirective } from 'graphql';
+import { type RegisteredRule } from '../rules';
+/** One `@constraint` argument written on an argument or an input field. */
+export interface Constraint {
+    readonly rule: RegisteredRule;
+    readonly value: string | number;
+}
+/**
+ * The constraints written on a node, base rules (`format`) first so the
+ * others narrow the schema they produce. Empty when the schema declares no
+ * `@constraint` or the node carries none.
+ */
+export declare function constraintsOn(directive: GraphQLDirective | undefined, node: {
+    readonly directives?: ReadonlyArray<DirectiveNode> | undefined;
+} | null | undefined): Constraint[];
+//# sourceMappingURL=constraints.d.ts.map

package/dist/builder/constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraints.d.ts","sourceRoot":"","sources":["../../src/builder/constraints.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,aAAa,EAClB,KAAK,gBAAgB,EAErB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,KAAK,cAAc,EAAS,MAAM,UAAU,CAAC;AAEtD,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC5B,SAAS,EAAE,gBAAgB,GAAG,SAAS,EACvC,IAAI,EACD;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,SAAS,CAAA;CAAE,GAClE,IAAI,GACJ,SAAS,GACV,UAAU,EAAE,CAad"}

package/dist/builder/input-schema.d.ts

@@ -0,0 +1,31 @@
+import { type GraphQLArgument, type GraphQLDirective, type GraphQLInputField, type GraphQLInputType, type GraphQLSchema } from 'graphql';
+import { z } from 'zod';
+/**
+ * Builds the schemas of the arguments and input fields of one GraphQL
+ * schema, once each: an input type is walked a single time however many
+ * fields use it, and a recursive one (`input Filter { and: [Filter!] }`) is
+ * reached through `z.lazy`.
+ */
+export declare class InputSchemas {
+    #private;
+    readonly directive: GraphQLDirective | undefined;
+    constructor(schema: GraphQLSchema);
+    /** Whether a value of this type can break a constraint anywhere inside. */
+    isConstrained(type: GraphQLInputType): boolean;
+    /**
+     * Builds every constrained input type, reached by an argument or not, so
+     * a constraint that cannot apply fails at startup wherever it is written.
+     */
+    buildAll(schema: GraphQLSchema): void;
+    /** Whether an argument or input field needs checking at all. */
+    needsCheck(input: GraphQLArgument | GraphQLInputField): boolean;
+    /** The schema of one argument or input field, `where` naming it in errors. */
+    of(input: GraphQLArgument | GraphQLInputField, where: string): z.ZodType;
+    /**
+     * Fails when a default value breaks its own constraint: every request that
+     * leaves the value out would be refused for something the client never
+     * sent. Run once every schema is built, so a recursive type is complete.
+     */
+    checkDefaults(): void;
+}
+//# sourceMappingURL=input-schema.d.ts.map

package/dist/builder/input-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-schema.d.ts","sourceRoot":"","sources":["../../src/builder/input-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EAEtB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAMlB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;GAKG;AACH,qBAAa,YAAY;;IACxB,QAAQ,CAAC,SAAS,EAAE,gBAAgB,GAAG,SAAS,CAAC;gBAWrC,MAAM,EAAE,aAAa;IAwBjC,2EAA2E;IAC3E,aAAa,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO;IAK9C;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAMrC,gEAAgE;IAChE,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,iBAAiB,GAAG,OAAO;IAO/D,8EAA8E;IAC9E,EAAE,CAAC,KAAK,EAAE,eAAe,GAAG,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO;IAYxE;;;;OAIG;IACH,aAAa,IAAI,IAAI;CAgFrB"}

package/dist/builder/leaf.d.ts

@@ -0,0 +1,14 @@
+import { type GraphQLLeafType } from 'graphql';
+import { z } from 'zod';
+import type { Target } from '../rules/rule';
+import type { Constraint } from './constraints';
+/**
+ * The schema of a scalar or enum value with its constraints applied. A leaf
+ * without any is left as graphql parsed it. A constraint that cannot apply
+ * — `minLength` on an `Int`, anything on a custom scalar or an enum — fails
+ * here, at startup, naming `where`.
+ */
+export declare function leafSchema(type: GraphQLLeafType, constraints: readonly Constraint[], where: string): z.ZodType;
+/** What a rule's target reads as in an error. */
+export declare function describeTarget(target: Target): string;
+//# sourceMappingURL=leaf.d.ts.map

package/dist/builder/leaf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaf.d.ts","sourceRoot":"","sources":["../../src/builder/leaf.ts"],"names":[],"mappings":"AAAA,OAAO,EAIN,KAAK,eAAe,EAEpB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAehD;;;;;GAKG;AACH,wBAAgB,UAAU,CACzB,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,SAAS,UAAU,EAAE,EAClC,KAAK,EAAE,MAAM,GACX,CAAC,CAAC,OAAO,CAaX;AAED,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIrD"}