@znight/graphql 0.0.0 → 0.2.0

package/src/compiler/model.ts

@@ -0,0 +1,122 @@
+/**
+ * The schema model built by `validate` (RFC 0005 §6.1) and emitted by `generate` (§7): the GraphQL
+ * types reachable from the root fields, with their TypeScript origins (locations, resolver data).
+ */
+import type { Location } from '@znight/compiler'
+import type { MetaEntry } from '@znight/http/compiler'
+import type { GraphQLTypeRef } from '../type-ref.ts'
+import type { FieldData, ResolverData } from './data.ts'
+
+/** A field of an object type. */
+export interface FieldModel {
+  readonly name: string
+  /** Printed type reference (`'[Book!]!'`). */
+  type: string
+  description: string | undefined
+  deprecationReason: string | undefined
+  readonly args: ArgModel[]
+  /** The resolver method behind the field; `undefined`: the default resolver (`parent[name]`). */
+  binding: { readonly resolver: ResolverData; readonly field: FieldData } | undefined
+  readonly location: Location | undefined
+}
+
+/** An argument or an input field. */
+export interface ArgModel {
+  readonly name: string
+  type: string
+  ref: GraphQLTypeRef
+  readonly description: string | undefined
+  readonly deprecationReason: string | undefined
+  /** External default value (enum values by name); `undefined`: no default. */
+  defaultValue: unknown
+  /** The TypeScript type does not accept `null` (§5.4). */
+  nullAsUndefined: boolean
+  readonly location: Location | undefined
+}
+
+/** What every named type of the model has. */
+interface BaseModel {
+  readonly name: string
+  /** The declaration key (shapes) or a synthetic key (`#root:query`, `#builtin:DateTime`). */
+  readonly key: string
+  readonly description: string | undefined
+  readonly location: Location | undefined
+}
+
+/** An object type (root types included). */
+export interface ObjectModel extends BaseModel {
+  readonly kind: 'object'
+  readonly fields: FieldModel[]
+  /** How the type was first reached (`Query.book → Book`), for "reached from" diagnostics. */
+  readonly trail: string
+  /** The root field the type was first reached from. */
+  readonly root: Location | undefined
+  /** Identity of the class when the type is a non-generic class (union discriminators). */
+  readonly classIdentity: string | undefined
+  /** Property names of the declaration, with their literal value when they have one (discriminators). */
+  readonly properties: readonly DiscriminantProperty[]
+}
+
+/** A property of an object type's declaration, as union discriminators see it. */
+export interface DiscriminantProperty {
+  readonly name: string
+  readonly optional: boolean
+  /** The literal value of a literal-typed property. */
+  readonly literal: string | number | boolean | undefined
+}
+
+/** An input object type. */
+export interface InputModel extends BaseModel {
+  readonly kind: 'input'
+  readonly fields: ArgModel[]
+}
+
+/** An enum type. */
+export interface EnumModel extends BaseModel {
+  readonly kind: 'enum'
+  readonly values: readonly EnumValueModel[]
+}
+
+/** A value of an enum. */
+export interface EnumValueModel {
+  readonly name: string
+  readonly value: string | number
+  readonly description: string | undefined
+  readonly deprecationReason: string | undefined
+}
+
+/** A union type. */
+export interface UnionModel extends BaseModel {
+  readonly kind: 'union'
+  members: readonly string[]
+  discriminator: DiscriminatorModel | undefined
+}
+
+/** How the runtime tells union members apart. */
+export type DiscriminatorModel =
+  | { readonly by: 'property'; readonly property: string; readonly values: Readonly<Record<string, string>> }
+  | { readonly by: 'class'; readonly classes: readonly { readonly identity: string; readonly name: string }[] }
+  | { readonly by: 'typename' }
+
+/** A scalar: built in (`DateTime`, `BigInt`, `JSON`) or declared with `scalar<T>()`. */
+export interface ScalarModel extends BaseModel {
+  readonly kind: 'scalar'
+  /** Identity of the exported `scalar<T>()` constant; `undefined` for a built-in scalar. */
+  readonly definition: string | undefined
+  readonly specifiedByURL: string | undefined
+}
+
+/** A named type of the model. */
+export type TypeModel = ObjectModel | InputModel | EnumModel | UnionModel | ScalarModel
+
+/** The schema of the application, built once per compile. */
+export interface GraphQLModel {
+  readonly roots: { readonly query: string; readonly mutation?: string; readonly subscription?: string }
+  /** Sorted by name. */
+  readonly types: readonly TypeModel[]
+  /** Route metadata entries of every field (effective), for `groups`. */
+  readonly meta: readonly MetaEntry[]
+  /** The SDL (`printSdl`), without trailing newline. */
+  readonly sdl: string
+  readonly schemaHash: string
+}

package/src/compiler/options.ts

@@ -0,0 +1,54 @@
+/**
+ * Options of the compiler extension (RFC 0005 §6.7), given with `graphql.configure({ ... })` in
+ * `znight.config.ts`. Import-free.
+ */
+
+/** Options of `graphql.configure()`. */
+export interface GraphQLCompilerOptions {
+  /**
+   * Path of the SDL artifact, relative to the project root (`'schema.graphql'`), written next to the
+   * generated module and checked by `znight generate --check`. Default `false`: no file.
+   */
+  readonly sdl?: string | false
+  /** GraphQL type of `number`. Default `'Float'`; `'Int'` suits counts and identifiers. */
+  readonly number?: 'Float' | 'Int'
+}
+
+/** {@link GraphQLCompilerOptions} with their defaults. */
+export interface ResolvedGraphQLCompilerOptions {
+  readonly sdl: string | false
+  readonly number: 'Float' | 'Int'
+}
+
+/** The defaults. */
+export const DEFAULT_OPTIONS: ResolvedGraphQLCompilerOptions = Object.freeze({ sdl: false, number: 'Float' })
+
+const KNOWN = new Set(['sdl', 'number'])
+
+/**
+ * Merges `options` onto `base`. Throws a `TypeError` naming the option on an invalid value: options
+ * are written in `znight.config.ts`, the error surfaces when the configuration is loaded.
+ */
+export function resolveOptions(
+  base: ResolvedGraphQLCompilerOptions,
+  options: GraphQLCompilerOptions,
+): ResolvedGraphQLCompilerOptions {
+  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+    throw new TypeError('[znight] graphql.configure() expects an options object: { sdl?, number? }')
+  }
+  for (const key of Object.keys(options)) {
+    if (!KNOWN.has(key))
+      throw new TypeError(`[znight] graphql.configure(): unknown option "${key}" (options: sdl, number)`)
+  }
+  const sdl = options.sdl === undefined ? base.sdl : options.sdl
+  if (sdl !== false && (typeof sdl !== 'string' || sdl.trim() === '')) {
+    throw new TypeError(
+      '[znight] graphql.configure(): "sdl" must be a path relative to the project root (\'schema.graphql\') or false',
+    )
+  }
+  const number = options.number === undefined ? base.number : options.number
+  if (number !== 'Float' && number !== 'Int') {
+    throw new TypeError(`[znight] graphql.configure(): "number" must be 'Float' or 'Int'`)
+  }
+  return Object.freeze({ sdl, number })
+}

package/src/compiler/scalars.ts

@@ -0,0 +1,138 @@
+/**
+ * `scalar<T>(name, definition)` declarations of the application (RFC 0005 §5.7): `T` (a plain type
+ * reference, by identity) maps to the scalar `name` wherever it appears. The definition is an
+ * exported value the generated module imports; its `description` and `specifiedByURL` are read
+ * for the SDL when they are statically evaluable.
+ */
+import type { ArgInfo, Diagnostic, Location, ValidateContext } from '@znight/compiler'
+import type { GraphQLData } from './data.ts'
+
+import { isGraphQLName, SPECIFIED_SCALARS } from '../names.ts'
+import { Codes } from './constants.ts'
+import { GraphQLIds, SCALAR_ALIASES } from './ids.ts'
+
+/** A valid `scalar<T>()` declaration. */
+export interface ScalarDeclaration {
+  /** GraphQL name. */
+  readonly name: string
+  /** Identity of the exported constant (imported by the generated module). */
+  readonly identity: string
+  /** Identity of `T`. */
+  readonly type: string
+  readonly description: string | undefined
+  readonly specifiedByURL: string | undefined
+  /** Location of the constant's name. */
+  readonly location: Location
+}
+
+/** Valid declarations by the identity of their type; invalid ones are reported. */
+export function readScalars(
+  ctx: ValidateContext<GraphQLData>,
+  report: (diagnostic: Diagnostic) => void,
+): ReadonlyMap<string, ScalarDeclaration> {
+  const byType = new Map<string, ScalarDeclaration>()
+  const byName = new Map<string, ScalarDeclaration>()
+  for (const definition of ctx.definitionsOf(GraphQLIds.scalar)) {
+    const fail = (message: string, hints: readonly string[], related: Diagnostic['related'] = []): void =>
+      report({ code: Codes.InvalidDecorator, severity: 'error', message, location: definition.call, hints, related })
+    const [nameArg, definitionArg] = definition.args
+    const name = nameArg?.evaluated === true ? nameArg.value : undefined
+    if (typeof name !== 'string') {
+      fail(`scalar() of ${definition.name} needs a static name`, [`scalar<T>('Name', { ... })`])
+      continue
+    }
+    if (!isGraphQLName(name) || SPECIFIED_SCALARS.has(name)) {
+      report({
+        code: Codes.NameConflict,
+        severity: 'error',
+        message: SPECIFIED_SCALARS.has(name)
+          ? `'${name}' is a specified GraphQL scalar: scalar() cannot redefine it (${definition.name})`
+          : `'${name}' is not a valid GraphQL scalar name (${definition.name})`,
+        location: nameArg?.location ?? definition.call,
+        hints: ['GraphQL names match /^[_A-Za-z][_0-9A-Za-z]*$/ and do not start with __'],
+      })
+      continue
+    }
+    const type = definition.typeArgIdentities?.[0]
+    if (type === undefined) {
+      report({
+        code: Codes.InvalidType,
+        severity: 'error',
+        message: `scalar('${name}') of ${definition.name} needs a named type argument: scalar<T>('${name}', ...)`,
+        location: definition.call,
+        hints: [
+          `Name the TypeScript type of the scalar: export type ${name} = string & { readonly __brand: '${name}' }, then scalar<${name}>('${name}', ...)`,
+        ],
+      })
+      continue
+    }
+    if (SCALAR_ALIASES.has(type)) {
+      fail(
+        `scalar('${name}') of ${definition.name} cannot map ${type.slice(type.indexOf('#') + 1)}: it is a built-in scalar alias`,
+        ['Declare a branded type for the scalar: export type Name = string & { readonly __brand: "Name" }'],
+      )
+      continue
+    }
+    if (!definition.exported) {
+      fail(`The scalar ${definition.name} must be exported: the generated module imports it`, [
+        `export const ${definition.name} = scalar<...>('${name}', ...)`,
+      ])
+      continue
+    }
+    const declaration: ScalarDeclaration = {
+      name,
+      identity: definition.identity,
+      type,
+      description: staticProperty(ctx, definitionArg, 'description'),
+      specifiedByURL: staticProperty(ctx, definitionArg, 'specifiedByURL'),
+      location: definition.location,
+    }
+    const sameType = byType.get(type)
+    if (sameType !== undefined) {
+      report({
+        code: Codes.NameConflict,
+        severity: 'error',
+        message: `${definition.name} and ${sameType.identity} both map ${type.slice(type.indexOf('#') + 1)} to a scalar`,
+        location: definition.location,
+        related: [{ message: 'the other scalar', location: sameType.location }],
+        hints: ['Keep one scalar per TypeScript type'],
+      })
+      continue
+    }
+    // a user scalar named like a built-in one (DateTime) only conflicts when both are used: the model reports it
+    const sameName = byName.get(name)
+    if (sameName !== undefined) {
+      report({
+        code: Codes.NameConflict,
+        severity: 'error',
+        message: `Two scalars are named '${name}': ${definition.identity} and ${sameName.identity}`,
+        location: definition.location,
+        related: [{ message: 'the other scalar', location: sameName.location }],
+        hints: ['Rename one of them'],
+      })
+      continue
+    }
+    byType.set(type, declaration)
+    byName.set(name, declaration)
+  }
+  return byType
+}
+
+/** A string property of an object literal argument, when statically evaluable. */
+function staticProperty(ctx: ValidateContext<GraphQLData>, arg: ArgInfo | undefined, key: string): string | undefined {
+  if (arg === undefined) return undefined
+  if (arg.evaluated && typeof arg.value === 'object' && arg.value !== null && !Array.isArray(arg.value)) {
+    const value = (arg.value as Readonly<Record<string, unknown>>)[key]
+    return typeof value === 'string' ? value : undefined
+  }
+  const node = arg.node
+  if (node.type !== 'ObjectExpression') return undefined
+  for (const property of node.properties) {
+    if (property.type !== 'Property' || property.computed) continue
+    const name = property.key.type === 'Identifier' ? property.key.name : undefined
+    if (name !== key) continue
+    const result = ctx.project.evaluate(arg.location.file, property.value, { refs: 'none' })
+    return result.kind === 'value' && typeof result.value === 'string' ? result.value : undefined
+  }
+  return undefined
+}

package/src/compiler/sdl-view.ts

@@ -0,0 +1,59 @@
+/**
+ * The SDL view of the model (`sdl.ts` prints it), from which `schemaHash` and the SDL artifact
+ * derive.
+ */
+import type { SdlInputValue, SdlType } from '../sdl.ts'
+import type { ArgModel, TypeModel } from './model.ts'
+
+/** The SDL view of a model type. */
+export function sdlType(model: TypeModel): SdlType {
+  const base = model.description === undefined ? {} : { description: model.description }
+  switch (model.kind) {
+    case 'object':
+      return {
+        kind: 'object',
+        name: model.name,
+        ...base,
+        fields: model.fields.map(field => ({
+          name: field.name,
+          type: field.type,
+          ...(field.description === undefined ? {} : { description: field.description }),
+          ...(field.deprecationReason === undefined ? {} : { deprecationReason: field.deprecationReason }),
+          ...(field.args.length === 0 ? {} : { args: field.args.map(sdlInputValue) }),
+        })),
+      }
+    case 'input':
+      return { kind: 'input', name: model.name, ...base, fields: model.fields.map(sdlInputValue) }
+    case 'enum':
+      return {
+        kind: 'enum',
+        name: model.name,
+        ...base,
+        values: model.values.map(value => ({
+          name: value.name,
+          ...(value.description === undefined ? {} : { description: value.description }),
+          ...(value.deprecationReason === undefined ? {} : { deprecationReason: value.deprecationReason }),
+        })),
+      }
+    case 'union':
+      return { kind: 'union', name: model.name, ...base, members: model.members }
+    case 'scalar':
+      return {
+        kind: 'scalar',
+        name: model.name,
+        ...base,
+        ...(model.definition === undefined ? { builtin: true } : {}),
+        ...(model.specifiedByURL === undefined ? {} : { specifiedByURL: model.specifiedByURL }),
+      }
+  }
+}
+
+function sdlInputValue(arg: ArgModel): SdlInputValue {
+  return {
+    name: arg.name,
+    type: arg.type,
+    ...(arg.description === undefined ? {} : { description: arg.description }),
+    ...(arg.deprecationReason === undefined ? {} : { deprecationReason: arg.deprecationReason }),
+    ...(arg.defaultValue === undefined ? {} : { defaultValue: arg.defaultValue }),
+  }
+}

package/src/context.ts

@@ -0,0 +1,181 @@
+/**
+ * The implementation of `GraphQLContext` (RFC 0005 §5.8): one per operation, passed to graphql-js
+ * as `contextValue` and stored in the request scope (`@znight/graphql#GraphQLContext`).
+ *
+ * Everything that is not needed by every operation is computed on first read: the request id (a
+ * UUID for direct executions), the HTTP context of an enclosing request, the signal, the state map
+ * and the loader registry.
+ */
+import type { Container, ScopeContext, Token } from '@znight/core'
+import type { HttpContext } from '@znight/http'
+import type { DocumentNode, OperationDefinitionNode } from 'graphql'
+import type { LoaderFactory } from './loaders.ts'
+import type {
+  BatchLoad,
+  BatchLoadClass,
+  BatchLoader,
+  GraphQLContext,
+  GraphQLOperationKind,
+  GraphQLTransport,
+  LoaderKey,
+  LoaderValue,
+} from './types.ts'
+
+import { randomUUID } from 'node:crypto'
+import { ErrorCode, ZnightError } from '@znight/core'
+import { HttpTokens } from '@znight/http'
+
+/** What every operation context of a plugin shares. */
+export interface ContextRuntime {
+  readonly container: Container
+  readonly loaders: LoaderFactory
+  /** The plugin's own signal (aborted by `onStop`): the signal of direct executions. */
+  readonly signal: AbortSignal
+}
+
+/** What a request carries that the context exposes (a `GraphQLRequest`). */
+export interface ContextRequest {
+  readonly variables?: Readonly<Record<string, unknown>> | null | undefined
+}
+
+/** How the request reached the executor (`ExecuteOptions`). */
+export interface ContextOptions {
+  readonly transport?: GraphQLTransport
+  readonly http?: HttpContext
+  readonly signal?: AbortSignal
+  readonly requestId?: string
+}
+
+const NO_VARIABLES: Readonly<Record<string, unknown>> = Object.freeze({})
+
+/**
+ * The `GraphQLContext` of one operation. Built from references the executor already holds (the
+ * operation node, the request, the options, the enclosing scope): one allocation per operation,
+ * every field read on demand.
+ */
+export class OperationContext implements GraphQLContext {
+  readonly document: DocumentNode
+  readonly #runtime: ContextRuntime
+  readonly #operation: OperationDefinitionNode
+  readonly #request: ContextRequest
+  readonly #options: ContextOptions
+  readonly #scope: ScopeContext | undefined
+  #requestId: string | undefined
+  #http: HttpContext | null | undefined
+  #signal: AbortSignal | undefined
+  #ended: AbortSignal | undefined
+  #state: Map<string | symbol, unknown> | undefined
+  #loaders: Map<Token, BatchLoader<unknown, unknown>> | undefined
+
+  constructor(
+    runtime: ContextRuntime,
+    document: DocumentNode,
+    operation: OperationDefinitionNode,
+    request: ContextRequest,
+    options: ContextOptions,
+    scope: ScopeContext | undefined,
+  ) {
+    this.#runtime = runtime
+    this.document = document
+    this.#operation = operation
+    this.#request = request
+    this.#options = options
+    this.#scope = scope
+    this.#requestId = options.requestId
+  }
+
+  get transport(): GraphQLTransport {
+    return this.#options.transport ?? 'direct'
+  }
+
+  get operationType(): GraphQLOperationKind {
+    return this.#operation.operation
+  }
+
+  get operationName(): string | undefined {
+    return this.#operation.name?.value
+  }
+
+  get requestId(): string {
+    let id = this.#requestId
+    if (id === undefined) {
+      const http = this.http
+      const scoped = http === undefined ? this.#scope?.get(HttpTokens.RequestId) : undefined
+      id = http?.requestId ?? (typeof scoped === 'string' ? scoped : randomUUID())
+      this.#requestId = id
+    }
+    return id
+  }
+
+  get http(): HttpContext | undefined {
+    let http = this.#http
+    if (http === undefined) {
+      // a controller calling plugin.execute(): the HTTP request of the enclosing scope
+      http = this.#options.http ?? this.#scope?.get(HttpTokens.Context) ?? null
+      this.#http = http
+    }
+    return http ?? undefined
+  }
+
+  get variables(): Readonly<Record<string, unknown>> {
+    return this.#request.variables ?? NO_VARIABLES
+  }
+
+  get signal(): AbortSignal {
+    let signal = this.#signal
+    if (signal === undefined) {
+      // HttpContext.signal is created on first read: only read it when someone asks
+      const base = this.#options.signal ?? this.http?.signal ?? this.#runtime.signal
+      const ended = this.#ended
+      signal = ended === undefined ? base : AbortSignal.any([base, ended])
+      this.#signal = signal
+    }
+    return signal
+  }
+
+  /**
+   * Ties {@link signal} to the end of a subscription: it also aborts when `ended` does (the stream
+   * ended by itself or with `return()`). Called before any resolver runs.
+   */
+  endsWith(ended: AbortSignal): void {
+    this.#ended = ended
+  }
+
+  get state(): Map<string | symbol, unknown> {
+    this.#state ??= new Map()
+    return this.#state
+  }
+
+  loader<L extends BatchLoad<unknown, unknown>>(loader: BatchLoadClass<L>): BatchLoader<LoaderKey<L>, LoaderValue<L>>
+  loader(token: Token): BatchLoader<unknown, unknown>
+  loader(key: Token | BatchLoadClass): BatchLoader<unknown, unknown> {
+    const token = typeof key === 'string' ? key : this.#tokenOf(key)
+    let loaders = this.#loaders
+    if (loaders === undefined) {
+      loaders = new Map()
+      this.#loaders = loaders
+    }
+    let loader = loaders.get(token)
+    if (loader === undefined) {
+      loader = this.#runtime.loaders.create(token)
+      loaders.set(token, loader)
+    }
+    return loader
+  }
+
+  /** Starts a new execution (a subscription event): loaders and their caches are renewed. */
+  resetLoaders(): void {
+    this.#loaders = undefined
+  }
+
+  #tokenOf(loader: BatchLoadClass): Token {
+    const token = typeof loader === 'function' ? this.#runtime.container.tokenOf(loader) : undefined
+    if (token === undefined) {
+      const name = typeof loader === 'function' ? loader.name || '<anonymous>' : String(loader)
+      throw new ZnightError(ErrorCode.MissingProvider, `GraphQLContext.loader(): ${name} is not a provider`, {
+        hints: ['Add @Injectable() to the loader class (it implements BatchLoad<K, V>)'],
+      })
+    }
+    return token
+  }
+}