@znight/graphql 0.0.0 → 0.2.0

package/src/memory-pubsub.ts

@@ -0,0 +1,133 @@
+/**
+ * `MemoryPubSub` (RFC 0005 §5.6, §8.7): the in-process `PubSub` of `GraphQLPlugin`, one RFC 0006
+ * `EventChannel` per subscriber.
+ */
+import type { SubscribeOptions } from './pubsub.ts'
+
+import { EventChannel } from '@znight/http'
+
+import { GraphQLErrorCode, GraphQLException } from './errors.ts'
+import { PubSub } from './pubsub.ts'
+
+/** Options of {@link MemoryPubSub}. */
+export interface MemoryPubSubOptions {
+  /**
+   * Events buffered per subscriber. A subscriber that falls further behind gets a final
+   * `SUBSCRIPTION_OVERFLOW` error and its subscription ends. Default 100.
+   */
+  readonly bufferSize?: number
+}
+
+const DEFAULT_BUFFER_SIZE = 100
+const PUBLISHED: Promise<void> = Promise.resolve()
+
+/** One subscriber: its channel, and whether it overflowed. */
+class Subscriber<T> implements AsyncIterableIterator<T> {
+  readonly channel: EventChannel<T>
+  readonly #iterator: AsyncIterator<T>
+  overflowed = false
+
+  constructor(channel: EventChannel<T>) {
+    this.channel = channel
+    this.#iterator = channel[Symbol.asyncIterator]()
+  }
+
+  async next(): Promise<IteratorResult<T>> {
+    const step = await this.#iterator.next()
+    if (step.done === true && this.overflowed) {
+      this.overflowed = false
+      throw new GraphQLException('The subscriber fell behind the events: the subscription ended', {
+        code: GraphQLErrorCode.SubscriptionOverflow,
+      })
+    }
+    return step
+  }
+
+  return(): Promise<IteratorResult<T>> {
+    this.overflowed = false
+    return this.#iterator.return?.() ?? Promise.resolve({ done: true, value: undefined })
+  }
+
+  [Symbol.asyncIterator](): AsyncIterableIterator<T> {
+    return this
+  }
+}
+
+/**
+ * In-process fan-out of events to subscribers: what `GraphQLPlugin` provides as `PubSub` by default.
+ * Deployments with several instances supply their own `PubSub` (`pubsub` option).
+ *
+ * ```ts
+ * GraphQLPlugin.configure({ pubsub: new MemoryPubSub({ bufferSize: 500 }) })
+ * ```
+ */
+export class MemoryPubSub<Events extends object = Record<string, unknown>> extends PubSub<Events> {
+  readonly #bufferSize: number
+  readonly #topics = new Map<string, Set<Subscriber<unknown>>>()
+  #closed = false
+
+  constructor(options: MemoryPubSubOptions = {}) {
+    super()
+    const bufferSize = options.bufferSize ?? DEFAULT_BUFFER_SIZE
+    if (!(Number.isSafeInteger(bufferSize) && bufferSize >= 1)) {
+      throw new TypeError(`MemoryPubSub: bufferSize must be a positive integer (received ${String(bufferSize)})`)
+    }
+    this.#bufferSize = bufferSize
+  }
+
+  /** Subscribers of every topic. */
+  get subscribers(): number {
+    let count = 0
+    for (const subscribers of this.#topics.values()) count += subscribers.size
+    return count
+  }
+
+  publish<K extends keyof Events & string>(topic: K, payload: Events[K]): Promise<void> {
+    const subscribers = this.#topics.get(topic)
+    if (subscribers !== undefined) {
+      for (const subscriber of subscribers) {
+        const channel = subscriber.channel
+        // `false` from an open channel is an overflow ('close'): it closes after its buffered events
+        if (!channel.closed && !channel.push(payload)) subscriber.overflowed = true
+      }
+    }
+    return PUBLISHED
+  }
+
+  subscribe<K extends keyof Events & string>(
+    topic: K,
+    options: SubscribeOptions = {},
+  ): AsyncIterableIterator<Events[K]> {
+    const channel = new EventChannel<Events[K]>({
+      capacity: this.#bufferSize,
+      overflow: 'close',
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    })
+    const subscriber = new Subscriber(channel)
+    if (this.#closed) {
+      channel.close()
+      return subscriber
+    }
+    let subscribers = this.#topics.get(topic)
+    if (subscribers === undefined) {
+      subscribers = new Set()
+      this.#topics.set(topic, subscribers)
+    }
+    const set = subscribers
+    set.add(subscriber as Subscriber<unknown>)
+    channel.onClose(() => {
+      set.delete(subscriber as Subscriber<unknown>)
+      if (set.size === 0 && this.#topics.get(topic) === set) this.#topics.delete(topic)
+    })
+    return subscriber
+  }
+
+  /** Ends every subscription; later subscriptions end at once. */
+  close(): void {
+    this.#closed = true
+    for (const subscribers of [...this.#topics.values()]) {
+      for (const subscriber of [...subscribers]) subscriber.channel.close()
+    }
+    this.#topics.clear()
+  }
+}

package/src/metadata.ts

@@ -0,0 +1,195 @@
+/**
+ * GraphQL section of the generated metadata (`__ZNIGHT_METADATA__.extensions.graphql`, RFC 0005
+ * §7), produced by the `@znight/graphql/compiler` extension and consumed by `GraphQLPlugin`, which
+ * validates it at boot (ZNIGHT066), because metadata can be hand-written.
+ *
+ * Data, not code, except `invoke` (one arrow per resolver) and the scalar implementations imported
+ * from user code. The SDL printer (`sdl.ts`) reads the same shape without its functions.
+ *
+ * Import-free: types, type-only imports and one constant, shared by the compiler extension and the
+ * runtime.
+ */
+import type { Token } from '@znight/core'
+import type { HttpRouteGroupDefinition } from '@znight/http'
+import type { GraphQLResolveInfo, GraphQLScalarType } from 'graphql'
+import type { GraphQLArgs, GraphQLContext, ScalarDefinition } from './types.ts'
+
+/** Format version of `metadata.extensions.graphql` (another version is ZNIGHT066 at boot). */
+export const GRAPHQL_METADATA_VERSION = 1
+
+/** The schema of the application. The section is omitted when the application has no resolver. */
+export interface GraphQLMetadata {
+  /** {@link GRAPHQL_METADATA_VERSION}. */
+  readonly version: number
+  /** First 16 hexadecimal characters of the SHA-256 of the SDL (`printSdl`): logs, caches. */
+  readonly schemaHash: string
+  readonly roots: GraphQLRootTypes
+  /** Every named type except the graphql-js specified scalars, sorted by name (code-unit order). */
+  readonly types: readonly GraphQLTypeDefinition[]
+  /**
+   * Route decorator groups used on resolvers that must be known at runtime (required, or holding
+   * several keys), by group name: the shape of `extensions.http.groups` (RFC 0001).
+   */
+  readonly groups?: Readonly<Record<string, HttpRouteGroupDefinition>>
+}
+
+/** Names of the root operation types (`Query`, `Mutation`, `Subscription`). */
+export interface GraphQLRootTypes {
+  readonly query: string
+  readonly mutation?: string
+  readonly subscription?: string
+}
+
+/** A named type of the schema. */
+export type GraphQLTypeDefinition =
+  | GraphQLObjectTypeDefinition
+  | GraphQLInputTypeDefinition
+  | GraphQLEnumTypeDefinition
+  | GraphQLUnionTypeDefinition
+  | GraphQLBuiltinScalarDefinition
+  | GraphQLCustomScalarDefinition
+
+/** An object type: resolver return types, their fields, the root types. */
+export interface GraphQLObjectTypeDefinition {
+  readonly kind: 'object'
+  readonly name: string
+  readonly description?: string
+  /** Declaration order (base members first), then field resolvers by resolver token and source order. */
+  readonly fields: readonly GraphQLFieldDefinition[]
+}
+
+/** An input object type. */
+export interface GraphQLInputTypeDefinition {
+  readonly kind: 'input'
+  readonly name: string
+  readonly description?: string
+  readonly fields: readonly GraphQLInputFieldDefinition[]
+}
+
+/** An enum: a TypeScript `enum`, or a named alias of a union of string literals. */
+export interface GraphQLEnumTypeDefinition {
+  readonly kind: 'enum'
+  readonly name: string
+  readonly description?: string
+  /** Declaration order. */
+  readonly values: readonly GraphQLEnumValueDefinition[]
+}
+
+/** A union of object types. */
+export interface GraphQLUnionTypeDefinition {
+  readonly kind: 'union'
+  readonly name: string
+  readonly description?: string
+  /** Member type names, sorted. */
+  readonly members: readonly string[]
+  readonly discriminator: GraphQLDiscriminator
+}
+
+/** A scalar implemented by `@znight/graphql`: `DateTime`, `BigInt` or `JSON` (`names.ts`). */
+export interface GraphQLBuiltinScalarDefinition {
+  readonly kind: 'scalar'
+  readonly name: string
+  readonly description?: string
+  readonly builtin: true
+}
+
+/** A scalar declared with `scalar<T>(name, definition)`: the definition is imported from user code. */
+export interface GraphQLCustomScalarDefinition {
+  readonly kind: 'scalar'
+  readonly name: string
+  /** `ScalarDefinition<T>` of any `T` (its methods are bivariant), or a graphql-js scalar named `name`. */
+  readonly scalar: ScalarDefinition<unknown> | GraphQLScalarType
+}
+
+/** A field of an object type. */
+export interface GraphQLFieldDefinition {
+  readonly name: string
+  /** Type reference (`'Book!'`, `'[Book!]!'`, `'Int'`), parsed by `type-ref.ts`. */
+  readonly type: string
+  readonly description?: string
+  readonly deprecationReason?: string
+  readonly args?: readonly GraphQLArgumentDefinition[]
+  /** Absent: the graphql-js default resolver (`parent[name]`). */
+  readonly resolver?: GraphQLResolverBinding
+}
+
+/** An argument of a field. */
+export interface GraphQLArgumentDefinition {
+  readonly name: string
+  readonly type: string
+  readonly description?: string
+  readonly deprecationReason?: string
+  /**
+   * Default value, as an external value: JSON-compatible, enum values by GraphQL name (passed to
+   * graphql-js as `default: { value }`). Absent: no default.
+   */
+  readonly defaultValue?: unknown
+  /** The TypeScript type does not accept `null`: a `null` sent by the client becomes `undefined` (§5.4). */
+  readonly nullAsUndefined?: true
+}
+
+/** A field of an input object type. */
+export interface GraphQLInputFieldDefinition extends GraphQLArgumentDefinition {}
+
+/** A value of an enum. */
+export interface GraphQLEnumValueDefinition {
+  /** GraphQL name (the member name, or the literal). */
+  readonly name: string
+  /** Internal value (the member value, or the literal), what resolvers receive and return. */
+  readonly value: string | number
+  readonly description?: string
+  readonly deprecationReason?: string
+}
+
+/** How the runtime tells the members of a union apart (`resolveType`). */
+export type GraphQLDiscriminator =
+  | {
+      readonly by: 'property'
+      readonly property: string
+      /** Literal value of the property (as a string) → member type name. */
+      readonly values: Readonly<Record<string, string>>
+    }
+  | {
+      readonly by: 'class'
+      /** Member classes and their type names, subclasses first (`instanceof` order). */
+      readonly classes: readonly (readonly [cls: abstract new (...args: never[]) => unknown, name: string])[]
+    }
+  | { readonly by: 'typename' }
+
+/** Kind of field a resolver method provides. */
+export type GraphQLResolverOperation = 'query' | 'mutation' | 'subscription' | 'field'
+
+/** The resolver method behind a field. */
+export interface GraphQLResolverBinding {
+  /** Provider token of the resolver class. */
+  readonly token: Token
+  readonly method: string
+  readonly operation: GraphQLResolverOperation
+  /** Guard provider tokens: class `@UseGuard` guards, then method ones. */
+  readonly guards: readonly Token[]
+  /**
+   * Effective field metadata (`createRouteDecorator` values, method decisions over class ones, one
+   * decision per group). Empty: no metadata, so global guards skip a field resolver (§5.9).
+   */
+  readonly meta: Readonly<Record<string, unknown>>
+  /** Informational: loader provider tokens the method injects. */
+  readonly loaders?: readonly Token[]
+  /**
+   * Calls the method: maps the graphql-js arguments to the method parameters (§7.3). Synchronous
+   * unless an argument is validated with a Standard Schema.
+   */
+  readonly invoke: (
+    // biome-ignore lint/suspicious/noExplicitAny: generated invokers receive the concrete resolver class
+    resolver: any,
+    parent: unknown,
+    args: GraphQLArgs,
+    context: GraphQLContext,
+    info: GraphQLResolveInfo,
+  ) => unknown
+}
+
+declare module '@znight/core' {
+  interface ZnightExtensionsMetadata {
+    readonly graphql?: GraphQLMetadata
+  }
+}

package/src/names.ts

@@ -0,0 +1,47 @@
+/**
+ * GraphQL naming rules and built-in types (RFC 0005 §5.7, §6.4).
+ *
+ * Import-free: shared by the compiler extension (naming diagnostics, ZNIGHT061) and the runtime
+ * (structural validation of `metadata.extensions.graphql` and the built-in scalars, ZNIGHT066).
+ */
+
+/** Grammar of a GraphQL name (types, fields, arguments, enum values). */
+export const GRAPHQL_NAME: RegExp = /^[_A-Za-z][_0-9A-Za-z]*$/
+
+/** `true` when `name` is a GraphQL name that user types may take (not reserved with `__`). */
+export function isGraphQLName(name: string): boolean {
+  return GRAPHQL_NAME.test(name) && !name.startsWith('__')
+}
+
+/** Names an enum value may not take (GraphQL spec §3.9). */
+export const RESERVED_ENUM_VALUES: ReadonlySet<string> = new Set(['true', 'false', 'null'])
+
+/** Names of the root operation types; user types may not take them (ZNIGHT061). */
+export const ROOT_TYPE_NAMES: {
+  readonly query: 'Query'
+  readonly mutation: 'Mutation'
+  readonly subscription: 'Subscription'
+} = Object.freeze({ query: 'Query', mutation: 'Mutation', subscription: 'Subscription' })
+
+/** Scalars of the GraphQL specification: always present, never declared in the metadata nor printed. */
+export const SPECIFIED_SCALARS: ReadonlySet<string> = new Set(['String', 'Int', 'Float', 'Boolean', 'ID'])
+
+/** A scalar `@znight/graphql` implements itself (`kind: 'scalar', builtin: true` in the metadata). */
+export interface BuiltinScalarInfo {
+  /** `@specifiedBy(url:)`. Absent: none. */
+  readonly specifiedByURL?: string
+}
+
+/**
+ * The scalars `@znight/graphql` implements (§5.7): `DateTime` (`Date`), `BigInt` (`bigint`) and
+ * `JSON` (`JSONValue`). They have no description. The runtime builds them with exactly these
+ * properties and without `valueToLiteral`, so that graphql-js `printSchema` and `printSdl()` agree.
+ */
+export const BUILTIN_SCALARS: ReadonlyMap<string, BuiltinScalarInfo> = new Map<string, BuiltinScalarInfo>([
+  ['BigInt', {}],
+  ['DateTime', { specifiedByURL: 'https://datatracker.ietf.org/doc/html/rfc3339' }],
+  ['JSON', {}],
+])
+
+/** The default `@deprecated` reason of graphql-js: printed as a bare `@deprecated`. */
+export const DEFAULT_DEPRECATION_REASON = 'No longer supported'

package/src/options.ts

@@ -0,0 +1,309 @@
+/**
+ * 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 } 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
+
+/** 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[]
+  /** 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 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',
+  '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'),
+    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,
+  }
+}