@znight/graphql 0.0.0 → 0.2.1

package/src/loaders.ts

@@ -0,0 +1,149 @@
+/**
+ * Loaders (RFC 0005 §5.5, §8.6): the DataLoader of a `BatchLoad` provider for one execution, and
+ * `orderByKeys()`.
+ *
+ * The registry of an execution (`Map<token, DataLoader>`) lives in its `GraphQLContext` and is
+ * created on the first `loader()` call: operations that use no loader allocate nothing.
+ */
+import type { Container, Token } from '@znight/core'
+import type { BatchLoad, BatchLoader, LoaderOptions } from './types.ts'
+
+import { ErrorCode, ZnightError } from '@znight/core'
+import DataLoader from 'dataloader'
+
+import { GraphQLErrorCode, GraphQLException } from './errors.ts'
+
+/** DataLoader options of a loader class, read once. */
+type ResolvedLoaderOptions = DataLoader.Options<unknown, unknown, unknown>
+
+/**
+ * Creates the per-execution DataLoaders of loader providers: the provider is resolved in the
+ * current scope (loaders may be request-scoped), its `options` are read once per token.
+ */
+export class LoaderFactory {
+  readonly #container: Container
+  readonly #options = new Map<Token, ResolvedLoaderOptions>()
+
+  constructor(container: Container) {
+    this.#container = container
+  }
+
+  /** A new DataLoader for the loader provider `token`, bound to the instance of the current scope. */
+  create(token: Token): BatchLoader<unknown, unknown> {
+    const provider = this.#container.get(token) as Partial<BatchLoad<unknown, unknown>> | undefined
+    if (provider === null || typeof provider !== 'object' || typeof provider.load !== 'function') {
+      throw new ZnightError(
+        ErrorCode.InvalidLoader,
+        `The loader ${token} does not implement BatchLoad (no load(keys) method)`,
+        { hints: ['A loader is a provider implementing BatchLoad<K, V>: async load(keys) { ... }'] },
+      )
+    }
+    let options = this.#options.get(token)
+    if (options === undefined) {
+      options = readOptions(token, provider.options)
+      this.#options.set(token, options)
+    }
+    return new DataLoader<unknown, unknown, unknown>(
+      keys => loadBatch(token, keys, provider as BatchLoad<unknown, unknown>),
+      options,
+    ) as BatchLoader<unknown, unknown>
+  }
+}
+
+/**
+ * The values of a batch, or ZNIGHT065 (failing every key) when there is not one value per key.
+ * `async` so that a `load()` throwing synchronously rejects with its own error (DataLoader would
+ * replace it with a TypeError).
+ */
+async function loadBatch(
+  token: Token,
+  keys: readonly unknown[],
+  provider: BatchLoad<unknown, unknown>,
+): Promise<readonly unknown[]> {
+  const values: unknown = await provider.load(keys)
+  if (Array.isArray(values) && values.length === keys.length) return values
+  throw new ZnightError(
+    ErrorCode.InvalidLoader,
+    `The loader ${token} returned ${Array.isArray(values) ? `${values.length} values` : 'no array'} for ${keys.length} keys`,
+    { hints: ['load(keys) returns one value (or Error) per key, in the order of the keys: use orderByKeys()'] },
+  )
+}
+
+function readOptions(token: Token, options: LoaderOptions | undefined): ResolvedLoaderOptions {
+  if (options === undefined) return {}
+  const invalid = (reason: string): ZnightError =>
+    new ZnightError(ErrorCode.InvalidLoader, `Invalid options of the loader ${token}: ${reason}`, {
+      hints: ['options: { maxBatchSize?: positive integer, cache?: boolean, cacheKeyFn?: (key) => unknown }'],
+    })
+  if (options === null || typeof options !== 'object') throw invalid('expected an object')
+  const { maxBatchSize, cache, cacheKeyFn } = options
+  if (maxBatchSize !== undefined && !(Number.isSafeInteger(maxBatchSize) && maxBatchSize >= 1)) {
+    throw invalid(`maxBatchSize must be a positive integer (received ${String(maxBatchSize)})`)
+  }
+  if (cache !== undefined && typeof cache !== 'boolean') throw invalid('cache must be a boolean')
+  if (cacheKeyFn !== undefined && typeof cacheKeyFn !== 'function') throw invalid('cacheKeyFn must be a function')
+  return {
+    ...(maxBatchSize === undefined ? {} : { maxBatchSize }),
+    ...(cache === undefined ? {} : { cache }),
+    ...(cacheKeyFn === undefined ? {} : { cacheKeyFn: (key: unknown) => cacheKeyFn.call(options, key) }),
+  }
+}
+
+/** Options of {@link orderByKeys}. */
+export interface OrderByKeysOptions {
+  /**
+   * What a key without value gets: `'error'` (default) a `NOT_FOUND` `GraphQLException` failing that
+   * key only, `'null'` the value `null`.
+   */
+  readonly missing?: 'error' | 'null'
+}
+
+/**
+ * Reorders `values` (rows in any order, some keys possibly missing) to match `keys`, what a
+ * `BatchLoad.load()` must return. Keys are compared with `Map` semantics (`===`, `NaN` equal).
+ *
+ * ```ts
+ * async load(ids: readonly ID[]): Promise<readonly (Author | Error)[]> {
+ *   return orderByKeys(ids, await this.authors.findMany(ids), author => author.id)
+ * }
+ * ```
+ */
+export function orderByKeys<K, V>(
+  keys: readonly K[],
+  values: Iterable<V>,
+  keyOf: (value: V) => K,
+  options?: OrderByKeysOptions & { readonly missing?: 'error' },
+): (V | Error)[]
+export function orderByKeys<K, V>(
+  keys: readonly K[],
+  values: Iterable<V>,
+  keyOf: (value: V) => K,
+  options: OrderByKeysOptions & { readonly missing: 'null' },
+): (V | null)[]
+export function orderByKeys<K, V>(
+  keys: readonly K[],
+  values: Iterable<V>,
+  keyOf: (value: V) => K,
+  options: OrderByKeysOptions = {},
+): (V | Error | null)[] {
+  const missing = options.missing ?? 'error'
+  if (missing !== 'error' && missing !== 'null') {
+    throw new TypeError(`orderByKeys(): missing must be 'error' or 'null' (received ${String(missing)})`)
+  }
+  const byKey = new Map<K, V>()
+  for (const value of values) byKey.set(keyOf(value), value)
+  const result: (V | Error | null)[] = new Array(keys.length)
+  for (let index = 0; index < keys.length; index++) {
+    const key = keys[index] as K
+    const value = byKey.get(key)
+    if (value !== undefined || byKey.has(key)) result[index] = value as V
+    else result[index] = missing === 'null' ? null : notFound(key)
+  }
+  return result
+}
+
+function notFound(key: unknown): GraphQLException {
+  return new GraphQLException(`Not found: ${typeof key === 'string' ? key : String(key)}`, {
+    code: GraphQLErrorCode.NotFound,
+  })
+}

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,222 @@
+/**
+ * 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
+  | GraphQLInterfaceTypeDefinition
+  | 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
+  /** Interfaces the type implements (schema-first, RFC 0007), in declaration order. Absent: none. */
+  readonly interfaces?: readonly string[]
+  /** Declaration order (base members first), then field resolvers by resolver token and source order. */
+  readonly fields: readonly GraphQLFieldDefinition[]
+}
+
+/**
+ * An interface type (schema-first, RFC 0007; code-first emits none). Its fields have no
+ * `resolver`: graphql-js resolves the fields of the concrete object type.
+ */
+export interface GraphQLInterfaceTypeDefinition {
+  readonly kind: 'interface'
+  readonly name: string
+  readonly description?: string
+  /** Interfaces the interface implements, in declaration order. Absent: none. */
+  readonly interfaces?: readonly string[]
+  readonly fields: readonly GraphQLFieldDefinition[]
+  /** How the runtime tells the implementing object types apart (`resolveType`). */
+  readonly discriminator: GraphQLDiscriminator
+}
+
+/** 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
+  /** Wins over the description of the definition (schema-first: the SDL's). */
+  readonly description?: string
+  /** Wins over the `specifiedByURL` of the definition (schema-first: the SDL's `@specifiedBy`). */
+  readonly specifiedByURL?: string
+  /**
+   * Schema-first (RFC 0007): `description` and `specifiedByURL` are the SDL's and replace the
+   * definition's, also when absent, so that the served schema is the SDL.
+   */
+  readonly sdl?: true
+  /** `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 or the implementations of an interface 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'