@znight/graphql 0.0.0 → 0.2.1

package/src/results.ts

@@ -0,0 +1,206 @@
+/**
+ * Errors as data (RFC 0008): result mappers turn the error of a field into a value of its union.
+ *
+ * Decided at boot, per resolver-backed field: a field carries results when its type, without its
+ * non-null wrapper, is a union (not a list) holding an object type declared by a result mapper
+ * (`static types`). Only those fields get a wrapper (`pipeline.ts`); the others keep their resolve
+ * function. On an error, the applicable mappers run in order; the first value resolving to a member
+ * of the union is the field's value, otherwise the error is thrown back, to `errors[]`.
+ */
+import type { Container, CoreLogger } from '@znight/core'
+import type { GraphQLResolveInfo } from 'graphql'
+import type { Resolvable } from './format.ts'
+import type { GraphQLFieldDefinition, GraphQLTypeDefinition } from './metadata.ts'
+import type { GraphQLResultMapper, ResolverContext } from './types.ts'
+
+import { ErrorCode, ZnightError } from '@znight/core'
+import { isThenable } from '@znight/http'
+
+import { resolveIn } from './format.ts'
+import { typeResolver } from './schema.ts'
+import { parseTypeRef } from './type-ref.ts'
+
+/** A result mapper resolved at boot. */
+export interface ResultMapperEntry {
+  readonly resolvable: Resolvable<GraphQLResultMapper>
+  /** For logs: the class name. */
+  readonly name: string
+  /** Declared object types, checked by {@link checkResultTypes}. */
+  readonly types: readonly string[]
+}
+
+/** The value of a field for an error, or the error thrown back. */
+export type Recover = (error: unknown, ctx: ResolverContext) => unknown
+
+/** The object types a result mapper ref declares: `static types` of a class; for an instance, its `types` property or its class's. */
+export function declaredTypes(ref: unknown): unknown {
+  try {
+    if (typeof ref === 'function') return (ref as { types?: unknown }).types
+    const own = (ref as { types?: unknown }).types
+    if (own !== undefined) return own
+    return ((ref as { constructor?: unknown }).constructor as { types?: unknown } | undefined)?.types
+  } catch {
+    // a throwing getter: reported as no types
+    return undefined
+  }
+}
+
+/**
+ * Checks the declared types of the result mappers against the schema's types: a non-empty array of
+ * names of object types. Every problem in one ZNIGHT066 error.
+ */
+export function checkResultTypes(
+  mappers: readonly { readonly name: string; readonly types: unknown }[],
+  types: readonly GraphQLTypeDefinition[],
+): void {
+  if (mappers.length === 0) return
+  const kinds = new Map(types.map(type => [type?.name, type?.kind]))
+  const problems: string[] = []
+  for (const mapper of mappers) {
+    const declared = mapper.types
+    if (!Array.isArray(declared) || declared.length === 0) {
+      problems.push(
+        `the result mapper ${mapper.name} declares no types (static readonly types = [...object type names])`,
+      )
+      continue
+    }
+    for (const name of declared as unknown[]) {
+      if (typeof name !== 'string' || kinds.get(name) !== 'object') {
+        problems.push(
+          `the result mapper ${mapper.name} declares ${typeof name === 'string' ? name : String(name)}, which is not an object type of the schema`,
+        )
+      }
+    }
+  }
+  if (problems.length === 0) return
+  throw new ZnightError(ErrorCode.InvalidGraphQLSetup, `GraphQLPlugin: ${problems.join('; ')}`, {
+    hints: [
+      "A result mapper declares the object types its values may have: static readonly types = ['NotFoundRejection'] (RFC 0008)",
+    ],
+  })
+}
+
+/** The union of a field type and its members, by union name. */
+interface Union {
+  readonly name: string
+  readonly members: ReadonlySet<string>
+  readonly typeOf: (value: unknown) => string | undefined
+}
+
+/** Decides which fields carry results, and builds their {@link Recover} functions. */
+export class ResultMappers {
+  readonly #container: Container
+  readonly #logger: CoreLogger
+  readonly #mappers: readonly ResultMapperEntry[]
+  readonly #types: readonly GraphQLTypeDefinition[]
+  /** Built on the first field, once the schema construction checked the section's structure. */
+  #index: { readonly objects: ReadonlySet<string>; readonly unions: ReadonlyMap<string, Union> } | undefined
+  #fields = 0
+
+  constructor(
+    container: Container,
+    logger: CoreLogger,
+    mappers: readonly ResultMapperEntry[],
+    types: readonly GraphQLTypeDefinition[],
+  ) {
+    this.#container = container
+    this.#logger = logger
+    this.#mappers = mappers
+    this.#types = types
+  }
+
+  /** Fields that carry results so far. */
+  get fields(): number {
+    return this.#fields
+  }
+
+  /** The {@link Recover} function of `field`, `undefined` when it carries no result. */
+  recover(field: GraphQLFieldDefinition, coordinate: string): Recover | undefined {
+    if (this.#mappers.length === 0) return undefined
+    const ref = parseTypeRef(field.type)
+    if (ref?.kind !== 'named') return undefined
+    this.#index ??= index(this.#types)
+    const objects = this.#index.objects
+    const union = this.#index.unions.get(ref.name)
+    if (union === undefined) return undefined
+    const applicable = this.#mappers.filter(mapper => mapper.types.some(type => union.members.has(type)))
+    if (applicable.length === 0) return undefined
+    this.#fields++
+    const container = this.#container
+    const logger = this.#logger
+    return (error, ctx) => {
+      for (const mapper of applicable) {
+        let value: unknown
+        let type: string | undefined
+        try {
+          value = resolveIn(container, mapper.resolvable).toResult(error, ctx)
+          if (value === undefined || value === null) continue
+          if (isThenable(value)) {
+            // not awaited: the field cannot wait for a mapper, and its rejection must not go unhandled
+            Promise.resolve(value).catch(noop)
+            logger.error(
+              `GraphQLPlugin: the result mapper ${mapper.name} returned a promise: toResult() must be synchronous`,
+              details(ctx, coordinate, error),
+            )
+            continue
+          }
+          // the discriminator reads the value (a getter, a class check): a failure is the mapper's
+          type = union.typeOf(value)
+        } catch (failure) {
+          logger.error(`GraphQLPlugin: the result mapper ${mapper.name} failed`, details(ctx, coordinate, failure))
+          continue
+        }
+        if (type !== undefined && union.members.has(type)) {
+          // the business path: no request id (it may be minted on first read) nor path built for a debug line
+          logger.debug(`GraphQL: error resolved as ${type} in ${coordinate}`, { coordinate, type })
+          return value
+        }
+        if (type !== undefined && objects.has(type)) {
+          logger.debug(
+            `GraphQLPlugin: the result mapper ${mapper.name} returned a value of ${type}, not a member of ${union.name} (${coordinate}): skipped`,
+            details(ctx, coordinate, error),
+          )
+        } else {
+          logger.warn(
+            `GraphQLPlugin: the result mapper ${mapper.name} returned a value of no type of the schema (${coordinate}): skipped`,
+            details(ctx, coordinate, error),
+          )
+        }
+      }
+      throw error
+    }
+  }
+}
+
+function index(types: readonly GraphQLTypeDefinition[]): {
+  readonly objects: ReadonlySet<string>
+  readonly unions: ReadonlyMap<string, Union>
+} {
+  const objects = new Set<string>()
+  const unions = new Map<string, Union>()
+  for (const type of types) {
+    if (type.kind === 'object') objects.add(type.name)
+    else if (type.kind === 'union') {
+      unions.set(type.name, {
+        name: type.name,
+        members: new Set(type.members),
+        typeOf: typeResolver(type.discriminator),
+      })
+    }
+  }
+  return { objects, unions }
+}
+
+function noop(): void {}
+
+function details(ctx: ResolverContext, coordinate: string, err: unknown): Record<string, unknown> {
+  return { err, requestId: ctx.operation.requestId, coordinate, path: pathOf(ctx.info).join('.') }
+}
+
+function pathOf(info: GraphQLResolveInfo): (string | number)[] {
+  const path: (string | number)[] = []
+  for (let step: GraphQLResolveInfo['path'] | undefined = info.path; step !== undefined; step = step.prev) {
+    path.push(step.key)
+  }
+  return path.reverse()
+}

package/src/scalars.ts

@@ -0,0 +1,138 @@
+/**
+ * Scalars of `@znight/graphql` (RFC 0005 §5.7): the built-in `DateTime`, `BigInt` and `JSON`, and
+ * the graphql-js 17 scalar built from a user `ScalarDefinition` (`scalar<T>(name, definition)`).
+ *
+ * Built-in scalars have no description and no `valueToLiteral`, with the `specifiedByURL` of
+ * `BUILTIN_SCALARS`, so that graphql-js `printSchema()` prints what `printSdl()` prints (§7.3).
+ */
+import type { ConstValueNode } from 'graphql'
+import type { ScalarDefinition } from './types.ts'
+
+import { GraphQLScalarType, Kind, valueFromASTUntyped } from 'graphql'
+
+import { BUILTIN_SCALARS } from './names.ts'
+
+/** RFC 3339 date-time with a mandatory offset (`2026-11-02T10:00:00Z`, `...+01:00`). */
+const DATE_TIME =
+  /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])[Tt]([01]\d|2[0-3]):([0-5]\d):([0-5]\d|60)(\.\d+)?([Zz]|[+-]([01]\d|2[0-3]):[0-5]\d)$/
+
+/** An integer in decimal notation (`BigInt` on the wire). */
+const DECIMAL_INTEGER = /^-?\d+$/
+
+function describe(value: unknown): string {
+  if (typeof value === 'string') return JSON.stringify(value)
+  if (typeof value === 'bigint') return `${value}n`
+  if (value === null || typeof value !== 'object') return String(value)
+  return Array.isArray(value) ? 'a list' : 'an object'
+}
+
+function parseDateTime(value: unknown): Date {
+  if (typeof value === 'string' && DATE_TIME.test(value)) {
+    const date = new Date(value)
+    if (!Number.isNaN(date.getTime())) return date
+  }
+  throw new TypeError(`DateTime cannot represent ${describe(value)}: expected an RFC 3339 date-time with an offset`)
+}
+
+function serializeDateTime(value: unknown): string {
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) throw new TypeError('DateTime cannot represent an invalid Date')
+    return value.toISOString()
+  }
+  if (typeof value === 'string' && DATE_TIME.test(value) && !Number.isNaN(Date.parse(value))) return value
+  throw new TypeError(`DateTime cannot represent ${describe(value)}: expected a Date`)
+}
+
+function parseBigInt(value: unknown): bigint {
+  if (typeof value === 'string' && DECIMAL_INTEGER.test(value)) return BigInt(value)
+  if (typeof value === 'number' && Number.isSafeInteger(value)) return BigInt(value)
+  throw new TypeError(`BigInt cannot represent ${describe(value)}: expected an integer as a decimal string`)
+}
+
+function serializeBigInt(value: unknown): string {
+  if (typeof value === 'bigint') return value.toString()
+  if (typeof value === 'number' && Number.isSafeInteger(value)) return String(value)
+  if (typeof value === 'string' && DECIMAL_INTEGER.test(value)) return value
+  throw new TypeError(`BigInt cannot represent ${describe(value)}: expected a bigint`)
+}
+
+function identity(value: unknown): unknown {
+  return value
+}
+
+function specifiedBy(name: string): { specifiedByURL?: string } {
+  const url = BUILTIN_SCALARS.get(name)?.specifiedByURL
+  return url === undefined ? {} : { specifiedByURL: url }
+}
+
+function createBuiltin(name: string): GraphQLScalarType | undefined {
+  switch (name) {
+    case 'DateTime':
+      return new GraphQLScalarType<Date, string>({
+        name,
+        ...specifiedBy(name),
+        coerceOutputValue: serializeDateTime,
+        coerceInputValue: parseDateTime,
+        coerceInputLiteral: (node: ConstValueNode) => parseDateTime(node.kind === Kind.STRING ? node.value : node),
+      })
+    case 'BigInt':
+      return new GraphQLScalarType<bigint, string>({
+        name,
+        ...specifiedBy(name),
+        coerceOutputValue: serializeBigInt,
+        coerceInputValue: parseBigInt,
+        coerceInputLiteral: (node: ConstValueNode) =>
+          parseBigInt(node.kind === Kind.STRING || node.kind === Kind.INT ? node.value : node),
+      })
+    case 'JSON':
+      return new GraphQLScalarType<unknown, unknown>({
+        name,
+        ...specifiedBy(name),
+        coerceOutputValue: identity,
+        coerceInputValue: identity,
+        coerceInputLiteral: (node: ConstValueNode) => valueFromASTUntyped(node),
+      })
+    default:
+      return undefined
+  }
+}
+
+/** Built-in scalars, created on first use and shared by every schema (they hold no state). */
+const builtins = new Map<string, GraphQLScalarType>()
+
+/** The built-in scalar `name` (`DateTime`, `BigInt`, `JSON`), `undefined` for another name. */
+export function builtinScalar(name: string): GraphQLScalarType | undefined {
+  let scalar = builtins.get(name)
+  if (scalar === undefined) {
+    scalar = createBuiltin(name)
+    if (scalar !== undefined) builtins.set(name, scalar)
+  }
+  return scalar
+}
+
+/**
+ * The graphql-js scalar of a {@link ScalarDefinition}: `serialize` → `coerceOutputValue`,
+ * `parseValue` → `coerceInputValue`, `parseLiteral` → `coerceInputLiteral` (default: `parseValue`
+ * of the literal's JSON value). The definition's methods are called on the definition.
+ */
+export function definitionScalar(
+  name: string,
+  definition: ScalarDefinition<unknown>,
+  overrides: { readonly description?: string; readonly specifiedByURL?: string } = {},
+): GraphQLScalarType {
+  const parseLiteral = definition.parseLiteral
+  // a key present in `overrides` wins, even undefined (schema-first: the SDL is the truth)
+  const description = 'description' in overrides ? overrides.description : definition.description
+  const specifiedByURL = 'specifiedByURL' in overrides ? overrides.specifiedByURL : definition.specifiedByURL
+  return new GraphQLScalarType({
+    name,
+    ...(description === undefined ? {} : { description }),
+    ...(specifiedByURL === undefined ? {} : { specifiedByURL }),
+    coerceOutputValue: (value: unknown) => definition.serialize(value),
+    coerceInputValue: (value: unknown) => definition.parseValue(value),
+    coerceInputLiteral:
+      parseLiteral === undefined
+        ? (node: ConstValueNode) => definition.parseValue(valueFromASTUntyped(node))
+        : (node: ConstValueNode) => parseLiteral.call(definition, node),
+  })
+}

package/src/schema-hash.ts

@@ -0,0 +1,18 @@
+/**
+ * `schemaHash` of `metadata.extensions.graphql` (RFC 0005 §7.1): the first 16 hexadecimal
+ * characters of the SHA-256 of the SDL printed by `printSdl()`.
+ *
+ * Separate from the import-free `sdl.ts` because it needs `node:crypto`. That is fine on both sides:
+ * the compiler extension runs at build time on Node.js or Bun, and the runtime targets Node.js >= 24
+ * and Bun >= 1.3, which both provide `node:crypto`. The module reaches nothing else, so the
+ * `./compiler` boundaries hold (tests/boundaries.test.ts).
+ */
+import { createHash } from 'node:crypto'
+
+/** Length of a schema hash, in hexadecimal characters. */
+export const SCHEMA_HASH_LENGTH = 16
+
+/** First 16 hexadecimal characters of the SHA-256 of `sdl` (UTF-8). */
+export function schemaHash(sdl: string): string {
+  return createHash('sha256').update(sdl, 'utf8').digest('hex').slice(0, SCHEMA_HASH_LENGTH)
+}