@znight/graphql 0.0.0 → 0.2.1

package/src/options.ts

@@ -0,0 +1,331 @@
+/**
+ * Options of `GraphQLPlugin` (RFC 0005 §5.11): their types, defaults and validation (ZNIGHT066).
+ */
+import type { ByteSize, GuardRef, RouteMetaEntry } from '@znight/http'
+import type { SubscribeOptions } from './pubsub.ts'
+import type {
+  GraphQLErrorMapper,
+  GraphQLErrorMapperClass,
+  GraphQLGuard,
+  GraphQLGuardClass,
+  GraphQLResultMapper,
+  GraphQLResultMapperClass,
+  GraphQLResultTypes,
+} from './types.ts'
+
+import { ErrorCode, ZnightError } from '@znight/core'
+import { parseByteSize } from '@znight/http'
+
+/**
+ * A `PubSub` of any event map, for the `pubsub` option: `PubSub<Events>` types are not assignable
+ * to each other (generic methods over `keyof Events`), so the option accepts the structure.
+ */
+export interface AnyPubSub {
+  publish(topic: never, payload: never): Promise<void>
+  subscribe(topic: never, options?: SubscribeOptions): AsyncIterableIterator<unknown>
+}
+
+/** A global GraphQL guard: a provider class or an instance. */
+export type GraphQLGuardRef = GraphQLGuardClass | GraphQLGuard
+
+/** An error mapper: a provider class or an instance. */
+export type GraphQLErrorMapperRef = GraphQLErrorMapperClass | GraphQLErrorMapper
+
+/**
+ * A result mapper: a provider class with `static types`, or an instance (its `types` property, or the
+ * `static types` of its class).
+ */
+export type GraphQLResultMapperRef = GraphQLResultMapperClass | (GraphQLResultMapper & Partial<GraphQLResultTypes>)
+
+/** Options of the GraphQL-over-HTTP endpoint. */
+export interface GraphQLHttpOptions {
+  /** Route metadata of the endpoint (`[Public.meta()]`), seen by HTTP guards and the route decision check. */
+  readonly meta?: readonly RouteMetaEntry[]
+  /** Guards of the endpoint (HTTP `CanActivate`), after the global `HttpPlugin` guards. */
+  readonly guards?: readonly GuardRef[]
+  /** Body limit of the endpoint. Default `'100kb'`. */
+  readonly bodyLimit?: ByteSize
+  /** Queries over `GET`. Default `true`. */
+  readonly get?: boolean
+}
+
+/** Request limits; `false` disables one. */
+export interface GraphQLLimits {
+  /** Tokens of a document (`parse`). Default 2 000. */
+  readonly maxTokens?: number | false
+  /** Field nesting of an operation (introspection fields exempt). Default 12. */
+  readonly maxDepth?: number | false
+  /**
+   * Aliases of a document, as written and as one operation executes them (a fragment spread several
+   * times counts each time). Default 30.
+   */
+  readonly maxAliases?: number | false
+  /** Directives of a document. Default 50. */
+  readonly maxDirectives?: number | false
+}
+
+/** Subscription options. */
+export interface GraphQLSubscriptionOptions {
+  /** Active subscriptions cap (every transport); beyond it, 503. Default 10 000. */
+  readonly maxActive?: number
+  /** Events buffered per subscriber by the default `MemoryPubSub`. Default 100. */
+  readonly bufferSize?: number
+  /** SSE heartbeat (ms), `false` for none. Default: the `HttpPlugin` `sse` option. */
+  readonly heartbeat?: number | false
+  /** SSE maximum duration (ms). Default: none. */
+  readonly maxDuration?: number
+}
+
+/** Options of `GraphQLPlugin.configure()`. */
+export interface GraphQLPluginOptions {
+  /** Path of the endpoint, joined with the `HttpPlugin` prefix. Default `'/graphql'`. */
+  readonly path?: string
+  /** `false`: no HTTP transport (schema, `execute()` and `subscribe()` only). Default `{}`. */
+  readonly http?: GraphQLHttpOptions | false
+  /** Global GraphQL guards (classes or instances): root fields, and field resolvers with metadata. */
+  readonly guards?: readonly GraphQLGuardRef[]
+  /** Error mappers (classes or instances), tried in order. */
+  readonly errorMappers?: readonly GraphQLErrorMapperRef[]
+  /**
+   * Result mappers (classes or instances), tried in order: errors as data (RFC 0008), on the fields
+   * whose union holds one of their `types`.
+   */
+  readonly resultMappers?: readonly GraphQLResultMapperRef[]
+  /** Unmasked messages for unexpected errors (development). Default `false`. */
+  readonly exposeErrors?: boolean
+  /** Introspection; off, suggestions are hidden too. Default `NODE_ENV !== 'production'`. */
+  readonly introspection?: boolean
+  /** GraphiQL on `GET path` with `accept: text/html`. Default `NODE_ENV === 'development'`. */
+  readonly graphiql?: boolean
+  readonly limits?: GraphQLLimits
+  /** Distinct documents kept parsed and validated (LRU); 0 disables the cache. Default 1 000. */
+  readonly documentCache?: number
+  /** `false` disables subscriptions over SSE. */
+  readonly subscriptions?: GraphQLSubscriptionOptions | false
+  /** The `PubSub` provided to the container. Default: a `MemoryPubSub` (closed with the application). */
+  readonly pubsub?: AnyPubSub
+  /**
+   * How the boot check of route decisions on GraphQL fields (RFC 0001, ZNIGHT023) reports problems:
+   * `'error'` (default) fails the boot, `'warn'` logs.
+   */
+  readonly enforcement?: 'error' | 'warn'
+}
+
+/** Options with their defaults, validated. */
+export interface ResolvedGraphQLOptions {
+  readonly path: string
+  readonly http: Required<GraphQLHttpOptions> | false
+  readonly guards: readonly GraphQLGuardRef[]
+  readonly errorMappers: readonly GraphQLErrorMapperRef[]
+  readonly resultMappers: readonly GraphQLResultMapperRef[]
+  readonly exposeErrors: boolean
+  readonly introspection: boolean
+  readonly graphiql: boolean
+  readonly limits: {
+    readonly maxTokens: number | undefined
+    readonly maxDepth: number | undefined
+    readonly maxAliases: number | undefined
+    readonly maxDirectives: number | undefined
+  }
+  readonly documentCache: number
+  readonly subscriptions:
+    | {
+        readonly maxActive: number
+        readonly bufferSize: number
+        readonly heartbeat: number | false | undefined
+        readonly maxDuration: number | undefined
+      }
+    | false
+  readonly bufferSize: number
+  readonly pubsub: AnyPubSub | undefined
+  readonly enforcement: 'error' | 'warn'
+}
+
+const KEYS: ReadonlySet<string> = new Set([
+  'path',
+  'http',
+  'guards',
+  'errorMappers',
+  'resultMappers',
+  'exposeErrors',
+  'introspection',
+  'graphiql',
+  'limits',
+  'documentCache',
+  'subscriptions',
+  'pubsub',
+  'enforcement',
+])
+const PATH = /^\/[A-Za-z0-9\-._~!$&'()*+,;=:@/]*$/
+const LIMIT_DEFAULTS = { maxTokens: 2000, maxDepth: 12, maxAliases: 30, maxDirectives: 50 } as const
+
+function show(value: unknown): string {
+  if (typeof value === 'function') return 'a function'
+  try {
+    return JSON.stringify(value) ?? String(value)
+  } catch {
+    return typeof value
+  }
+}
+
+/** ZNIGHT066 for an invalid option. */
+export function invalidOption(name: string, expected: string, received: unknown): ZnightError {
+  return new ZnightError(
+    ErrorCode.InvalidGraphQLSetup,
+    `GraphQLPlugin: invalid option ${name}: expected ${expected} (received ${show(received)})`,
+    { hints: ['See the options of GraphQLPlugin.configure() (RFC 0005 §5.11)'] },
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function boolean(name: string, value: unknown, fallback: boolean): boolean {
+  if (value === undefined) return fallback
+  if (typeof value !== 'boolean') throw invalidOption(name, 'a boolean', value)
+  return value
+}
+
+function positiveInteger(name: string, value: unknown, fallback: number): number {
+  if (value === undefined) return fallback
+  if (!(Number.isSafeInteger(value) && (value as number) >= 1)) throw invalidOption(name, 'a positive integer', value)
+  return value as number
+}
+
+function limit(name: keyof typeof LIMIT_DEFAULTS, value: unknown): number | undefined {
+  if (value === false) return undefined
+  return positiveInteger(`limits.${name}`, value, LIMIT_DEFAULTS[name])
+}
+
+/** Refs given as classes or instances with `method`. */
+function refs<T>(name: string, value: unknown, method: string): readonly T[] {
+  if (value === undefined) return []
+  if (!Array.isArray(value))
+    throw invalidOption(name, `an array of classes or objects with a ${method}() method`, value)
+  for (const ref of value) {
+    const ok =
+      typeof ref === 'function' ||
+      (ref !== null && typeof ref === 'object' && typeof (ref as Record<string, unknown>)[method] === 'function')
+    if (!ok) throw invalidOption(name, `classes or objects with a ${method}() method`, ref)
+  }
+  return value as readonly T[]
+}
+
+/** Validates the options and applies the defaults (`env`: `process.env`). */
+export function resolveGraphQLOptions(
+  options: unknown,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): ResolvedGraphQLOptions {
+  if (!isRecord(options)) throw invalidOption('options', 'an object', options)
+  for (const key of Object.keys(options)) {
+    if (!KEYS.has(key)) throw invalidOption(key, `one of ${[...KEYS].join(', ')}`, key)
+  }
+  const nodeEnv = env['NODE_ENV']
+  const path = options['path'] ?? '/graphql'
+  if (typeof path !== 'string' || !PATH.test(path)) throw invalidOption('path', "a path starting with '/'", path)
+
+  const rawHttp = options['http'] ?? {}
+  let http: ResolvedGraphQLOptions['http']
+  if (rawHttp === false) {
+    http = false
+  } else {
+    if (!isRecord(rawHttp)) throw invalidOption('http', 'false or { meta?, guards?, bodyLimit?, get? }', rawHttp)
+    const meta = rawHttp['meta'] ?? []
+    if (
+      !Array.isArray(meta) ||
+      !meta.every(entry => isRecord(entry) && typeof entry['key'] === 'string' && entry['key'] !== '')
+    ) {
+      throw invalidOption('http.meta', 'an array of route metadata entries (Decorator.meta())', meta)
+    }
+    const bodyLimit = rawHttp['bodyLimit'] ?? '100kb'
+    if (parseByteSize(bodyLimit) === undefined)
+      throw invalidOption('http.bodyLimit', "a byte size ('100kb', 1048576)", bodyLimit)
+    http = {
+      meta: meta as readonly RouteMetaEntry[],
+      guards: refs<GuardRef>('http.guards', rawHttp['guards'], 'canActivate'),
+      bodyLimit: bodyLimit as ByteSize,
+      get: boolean('http.get', rawHttp['get'], true),
+    }
+  }
+
+  const rawLimits = options['limits'] ?? {}
+  if (!isRecord(rawLimits))
+    throw invalidOption('limits', '{ maxTokens?, maxDepth?, maxAliases?, maxDirectives? }', rawLimits)
+  for (const key of Object.keys(rawLimits)) {
+    if (!(key in LIMIT_DEFAULTS))
+      throw invalidOption(`limits.${key}`, 'maxTokens, maxDepth, maxAliases or maxDirectives', key)
+  }
+
+  const documentCache = options['documentCache'] ?? 1000
+  if (!(Number.isSafeInteger(documentCache) && (documentCache as number) >= 0)) {
+    throw invalidOption('documentCache', 'a non-negative integer', documentCache)
+  }
+
+  const rawSubscriptions = options['subscriptions'] ?? {}
+  let subscriptions: ResolvedGraphQLOptions['subscriptions']
+  let bufferSize = 100
+  if (rawSubscriptions === false) {
+    subscriptions = false
+  } else {
+    if (!isRecord(rawSubscriptions)) {
+      throw invalidOption(
+        'subscriptions',
+        'false or { maxActive?, bufferSize?, heartbeat?, maxDuration? }',
+        rawSubscriptions,
+      )
+    }
+    bufferSize = positiveInteger('subscriptions.bufferSize', rawSubscriptions['bufferSize'], 100)
+    const heartbeat = rawSubscriptions['heartbeat']
+    if (heartbeat !== undefined && heartbeat !== false && !(typeof heartbeat === 'number' && heartbeat > 0)) {
+      throw invalidOption('subscriptions.heartbeat', 'a positive number of milliseconds or false', heartbeat)
+    }
+    const maxDuration = rawSubscriptions['maxDuration']
+    if (maxDuration !== undefined && !(typeof maxDuration === 'number' && maxDuration > 0)) {
+      throw invalidOption('subscriptions.maxDuration', 'a positive number of milliseconds', maxDuration)
+    }
+    subscriptions = {
+      maxActive: positiveInteger('subscriptions.maxActive', rawSubscriptions['maxActive'], 10_000),
+      bufferSize,
+      heartbeat: heartbeat as number | false | undefined,
+      maxDuration: maxDuration as number | undefined,
+    }
+  }
+
+  const pubsub = options['pubsub']
+  if (
+    pubsub !== undefined &&
+    !(
+      isRecord(pubsub) &&
+      typeof (pubsub as { publish?: unknown }).publish === 'function' &&
+      typeof (pubsub as { subscribe?: unknown }).subscribe === 'function'
+    )
+  ) {
+    throw invalidOption('pubsub', 'a PubSub (publish() and subscribe() methods)', pubsub)
+  }
+  const enforcement = options['enforcement'] ?? 'error'
+  if (enforcement !== 'error' && enforcement !== 'warn')
+    throw invalidOption('enforcement', "'error' or 'warn'", enforcement)
+
+  return {
+    path,
+    http,
+    guards: refs<GraphQLGuardRef>('guards', options['guards'], 'canResolve'),
+    errorMappers: refs<GraphQLErrorMapperRef>('errorMappers', options['errorMappers'], 'map'),
+    resultMappers: refs<GraphQLResultMapperRef>('resultMappers', options['resultMappers'], 'toResult'),
+    exposeErrors: boolean('exposeErrors', options['exposeErrors'], false),
+    introspection: boolean('introspection', options['introspection'], nodeEnv !== 'production'),
+    graphiql: boolean('graphiql', options['graphiql'], nodeEnv === 'development'),
+    limits: {
+      maxTokens: limit('maxTokens', rawLimits['maxTokens']),
+      maxDepth: limit('maxDepth', rawLimits['maxDepth']),
+      maxAliases: limit('maxAliases', rawLimits['maxAliases']),
+      maxDirectives: limit('maxDirectives', rawLimits['maxDirectives']),
+    },
+    documentCache: documentCache as number,
+    subscriptions,
+    bufferSize,
+    pubsub: pubsub as AnyPubSub | undefined,
+    enforcement,
+  }
+}

package/src/pipeline.ts

@@ -0,0 +1,338 @@
+/**
+ * The resolver pipeline (RFC 0005 §5.9, §7.3, §8.5): the resolve function of every resolver-backed
+ * field, decided once at boot.
+ *
+ * 1. the resolver instance: the singleton resolved at boot, or `container.get(token)` in the
+ *    current scope (request-scoped and transient resolvers);
+ * 2. guards: global ones (on root fields, and on field resolvers carrying their own metadata), class
+ *    `@UseGuard`, method `@UseGuard`; `false` fails the field with `FORBIDDEN`;
+ * 3. null handling of arguments (`nullAsUndefined`), only where a flag is reachable;
+ * 4. `invoke(resolver, parent, args, context, info)`.
+ *
+ * A field without guards nor normaliser calls `invoke` from the closure graphql-js needs anyway:
+ * no extra wrapper, no promise, no `await`. Plain property fields keep graphql-js' default resolver.
+ * A field that carries results (RFC 0008, `results.ts`) gets one wrapper around the whole pipeline,
+ * catching its errors to turn them into values; no other field does.
+ */
+import type { Container, Token } from '@znight/core'
+import type { GraphQLFieldResolver, GraphQLResolveInfo } from 'graphql'
+import type { OperationContext } from './context.ts'
+import type { Resolvable } from './format.ts'
+import type {
+  GraphQLArgumentDefinition,
+  GraphQLFieldDefinition,
+  GraphQLInputTypeDefinition,
+  GraphQLObjectTypeDefinition,
+  GraphQLResolverBinding,
+} from './metadata.ts'
+import type { Recover } from './results.ts'
+import type { FieldFunctions, FieldFunctionsFactory } from './schema.ts'
+import type { GraphQLTypeRef } from './type-ref.ts'
+import type { GraphQLArgs, GraphQLContext, GraphQLGuard, ResolverContext } from './types.ts'
+
+import { isThenable } from '@znight/http'
+
+import { GraphQLErrorCode, GraphQLException } from './errors.ts'
+import { resolveIn } from './format.ts'
+import { parseTypeRef } from './type-ref.ts'
+
+/** What the pipeline needs, resolved at boot. */
+export interface PipelineOptions {
+  readonly container: Container
+  /** Global guards (plugin option), in order. */
+  readonly globalGuards: readonly Resolvable<GraphQLGuard>[]
+  /** The guard provider of a `@UseGuard` token (memoised by the caller). */
+  readonly guard: (token: Token, coordinate: string) => Resolvable<GraphQLGuard>
+  /** The resolver provider of a binding (memoised by the caller). */
+  readonly resolver: (binding: GraphQLResolverBinding, coordinate: string) => Resolvable<object>
+  /** Input object types by name (null handling of nested input values). */
+  readonly inputs: ReadonlyMap<string, GraphQLInputTypeDefinition>
+  /** The {@link Recover} function of a field that carries results (RFC 0008), `undefined` for the others. */
+  readonly results?: (field: GraphQLFieldDefinition, coordinate: string) => Recover | undefined
+}
+
+/** The generated invoker of a binding. */
+type Invoke = GraphQLResolverBinding['invoke']
+
+/** Mutates a coerced argument or input value in place: `null` → `undefined` where flagged. */
+type Normalize = (value: unknown) => void
+
+/** Whether global guards run on a field: root fields always, field resolvers when they carry metadata (§5.9). */
+export function globalGuardsApply(binding: GraphQLResolverBinding): boolean {
+  return binding.operation !== 'field' || Object.keys(binding.meta).length > 0
+}
+
+/** The {@link FieldFunctionsFactory} of the plugin. */
+export function pipelineFactory(options: PipelineOptions): FieldFunctionsFactory {
+  const normalizers = new NormalizerBuilder(options.inputs)
+  return (binding, coordinate, field, parent) =>
+    fieldFunctions(options, normalizers, binding, coordinate, field, parent)
+}
+
+function fieldFunctions(
+  options: PipelineOptions,
+  normalizers: NormalizerBuilder,
+  binding: GraphQLResolverBinding,
+  coordinate: string,
+  field: GraphQLFieldDefinition,
+  parent: GraphQLObjectTypeDefinition,
+): FieldFunctions {
+  const container = options.container
+  const invoke: Invoke = binding.invoke
+  const target = options.resolver(binding, coordinate)
+  const guards: Resolvable<GraphQLGuard>[] = [
+    ...(globalGuardsApply(binding) ? options.globalGuards : []),
+    ...binding.guards.map(token => options.guard(token, coordinate)),
+  ]
+  const normalize = field.args === undefined ? undefined : normalizers.args(field.args)
+  const recover = options.results?.(field, coordinate)
+  const route =
+    guards.length === 0 && recover === undefined ? undefined : Object.freeze({ meta: binding.meta, coordinate })
+  const parentType = parent.name
+  const fieldName = field.name
+
+  let resolve: GraphQLFieldResolver<unknown, unknown>
+  if (guards.length === 0) {
+    // the common case: one closure, invoke called directly (no promise, no await)
+    if (target.token === undefined) {
+      const instance = target.instance
+      resolve =
+        normalize === undefined
+          ? (p, a, c, i) => invoke(instance, p, a as GraphQLArgs, c as GraphQLContext, i)
+          : (p, a, c, i) => {
+              normalize(a)
+              return invoke(instance, p, a as GraphQLArgs, c as GraphQLContext, i)
+            }
+    } else {
+      const token = target.token
+      resolve =
+        normalize === undefined
+          ? (p, a, c, i) => invoke(container.get(token), p, a as GraphQLArgs, c as GraphQLContext, i)
+          : (p, a, c, i) => {
+              normalize(a)
+              return invoke(container.get(token), p, a as GraphQLArgs, c as GraphQLContext, i)
+            }
+    }
+  } else {
+    const forbidden = (): never => {
+      throw new GraphQLException(`Not allowed to resolve ${coordinate}`, { code: GraphQLErrorCode.Forbidden })
+    }
+    resolve = (p, a, c, i) => {
+      const operation = c as OperationContext
+      const args = a as GraphQLArgs
+      const allowed = runGuards(
+        container,
+        guards,
+        new FieldContext(route as ResolverContext['route'], operation, parentType, fieldName, args, p, i),
+      )
+      // §8.5: guards (they see the coerced arguments), then null handling, then invoke
+      const call = (): unknown => {
+        if (normalize !== undefined) normalize(args)
+        return invoke(resolveIn(container, target), p, args, operation, i)
+      }
+      if (allowed === true) return call()
+      if (allowed === false) return forbidden()
+      return allowed.then(ok => (ok ? call() : forbidden()))
+    }
+  }
+  const subscription = binding.operation === 'subscription'
+  if (recover !== undefined) {
+    resolve = withResults(resolve, recover, route as ResolverContext['route'], parentType, fieldName, subscription)
+  }
+  if (subscription) {
+    // the method gives the source event stream; each event is the field value
+    return { subscribe: resolve, resolve: identity }
+  }
+  return { resolve }
+}
+
+function identity(payload: unknown): unknown {
+  return payload
+}
+
+/**
+ * The resolve function of a field that carries results (RFC 0008): errors of the whole pipeline
+ * (guards, null handling, `invoke`), thrown or rejected, go through `recover`. Synchronous results
+ * stay synchronous; a promise gets one rejection handler. For a subscription, a value is a source
+ * stream of that single event.
+ */
+function withResults(
+  resolve: GraphQLFieldResolver<unknown, unknown>,
+  recover: Recover,
+  route: ResolverContext['route'],
+  parentType: string,
+  fieldName: string,
+  subscription: boolean,
+): GraphQLFieldResolver<unknown, unknown> {
+  const fail = (error: unknown, p: unknown, a: unknown, c: unknown, i: GraphQLResolveInfo): unknown => {
+    const value = recover(
+      error,
+      new FieldContext(route, c as OperationContext, parentType, fieldName, a as GraphQLArgs, p, i),
+    )
+    return subscription ? once(value) : value
+  }
+  // captures nothing per call: the rejection handler is created in recoverAsync, on the promise path only
+  return (p, a, c, i) => {
+    let result: unknown
+    try {
+      result = resolve(p, a, c, i)
+    } catch (error) {
+      return fail(error, p, a, c, i)
+    }
+    return isThenable(result) ? recoverAsync(result, fail, p, a, c, i) : result
+  }
+}
+
+function recoverAsync(
+  result: PromiseLike<unknown>,
+  fail: (error: unknown, p: unknown, a: unknown, c: unknown, i: GraphQLResolveInfo) => unknown,
+  p: unknown,
+  a: unknown,
+  c: unknown,
+  i: GraphQLResolveInfo,
+): Promise<unknown> {
+  return Promise.resolve(result).then(undefined, error => fail(error, p, a, c, i))
+}
+
+/** A source event stream of one event. */
+// biome-ignore lint/suspicious/useAwait: an async generator is the shortest AsyncIterable of one value
+async function* once(value: unknown): AsyncGenerator<unknown> {
+  yield value
+}
+
+/** Runs guards in order, synchronously until one returns a promise. */
+function runGuards(
+  container: Container,
+  guards: readonly Resolvable<GraphQLGuard>[],
+  ctx: ResolverContext,
+  start = 0,
+): boolean | Promise<boolean> {
+  for (let index = start; index < guards.length; index++) {
+    const result = resolveIn(container, guards[index] as Resolvable<GraphQLGuard>).canResolve(ctx)
+    if (isThenable(result)) {
+      return Promise.resolve(result).then(ok => (ok ? runGuards(container, guards, ctx, index + 1) : false))
+    }
+    if (!result) return false
+  }
+  return true
+}
+
+/** What a guard receives (§5.9): a `RouteMetaCarrier` with the field's effective metadata. */
+class FieldContext implements ResolverContext {
+  readonly route: ResolverContext['route']
+  readonly operation: OperationContext
+  readonly parentType: string
+  readonly field: string
+  readonly args: GraphQLArgs
+  readonly parent: unknown
+  readonly info: GraphQLResolveInfo
+
+  constructor(
+    route: ResolverContext['route'],
+    operation: OperationContext,
+    parentType: string,
+    field: string,
+    args: GraphQLArgs,
+    parent: unknown,
+    info: GraphQLResolveInfo,
+  ) {
+    this.route = route
+    this.operation = operation
+    this.parentType = parentType
+    this.field = field
+    this.args = args
+    this.parent = parent
+    this.info = info
+  }
+
+  get http(): ResolverContext['http'] {
+    return this.operation.http
+  }
+}
+
+/** One step of a normaliser: an argument or input field. */
+interface Step {
+  readonly name: string
+  /** The value itself: `null` → `undefined`. */
+  readonly own: boolean
+  /** Nested input values. */
+  readonly nested: Normalize | undefined
+}
+
+/**
+ * Builds normalisers (§7.3) at boot. Values are mutated in place: graphql-js creates the argument
+ * object of every call and the coerced input objects, and the flags of an input type are the same
+ * wherever it is used, so a value shared through a variable is normalised the same way twice.
+ */
+class NormalizerBuilder {
+  readonly #inputs: ReadonlyMap<string, GraphQLInputTypeDefinition>
+  /** Input type → its normaliser (`null`: nothing to do), `PENDING` while being built (cycles). */
+  readonly #types = new Map<string, Normalize | null | typeof PENDING>()
+
+  constructor(inputs: ReadonlyMap<string, GraphQLInputTypeDefinition>) {
+    this.#inputs = inputs
+  }
+
+  /** The normaliser of a field's arguments, `undefined` when no flag is reachable. */
+  args(args: readonly GraphQLArgumentDefinition[]): ((args: unknown) => void) | undefined {
+    const steps = this.#steps(args)
+    return steps === undefined ? undefined : record => applySteps(record, steps)
+  }
+
+  #steps(values: readonly GraphQLArgumentDefinition[]): readonly Step[] | undefined {
+    const steps: Step[] = []
+    for (const value of values) {
+      const own = value.nullAsUndefined === true
+      const ref = parseTypeRef(value.type)
+      const nested = ref === undefined ? undefined : this.#value(ref)
+      if (own || nested !== undefined) steps.push({ name: value.name, own, nested })
+    }
+    return steps.length === 0 ? undefined : steps
+  }
+
+  #value(ref: GraphQLTypeRef): Normalize | undefined {
+    if (ref.kind === 'list') {
+      const item = this.#value(ref.of)
+      return item === undefined
+        ? undefined
+        : value => {
+            if (Array.isArray(value)) for (const entry of value) item(entry)
+          }
+    }
+    return this.#input(ref.name)
+  }
+
+  #input(name: string): Normalize | undefined {
+    const known = this.#types.get(name)
+    if (known === PENDING) {
+      // a cycle through this type: delegate to its normaliser once built
+      return value => {
+        const normalize = this.#types.get(name)
+        if (typeof normalize === 'function') normalize(value)
+      }
+    }
+    if (known !== undefined) return known ?? undefined
+    const type = this.#inputs.get(name)
+    if (type === undefined) return undefined
+    this.#types.set(name, PENDING)
+    const steps = this.#steps(type.fields)
+    const normalize: Normalize | null = steps === undefined ? null : value => applySteps(value, steps)
+    this.#types.set(name, normalize)
+    return normalize ?? undefined
+  }
+}
+
+const PENDING: unique symbol = Symbol('pending')
+
+function applySteps(value: unknown, steps: readonly Step[]): void {
+  if (value === null || typeof value !== 'object') return
+  const record = value as Record<string, unknown>
+  for (const step of steps) {
+    const entry = record[step.name]
+    if (entry === null) {
+      if (step.own) record[step.name] = undefined
+    } else if (entry !== undefined && step.nested !== undefined) {
+      step.nested(entry)
+    }
+  }
+}