@znight/graphql 0.0.0 → 0.2.0

package/src/format.ts

@@ -0,0 +1,285 @@
+/**
+ * Error formatting (RFC 0005 §5.10, §8.8): what clients see of the errors of a result.
+ *
+ * Execution errors, in order: a `GraphQLException` (or a `GraphQLError` thrown by user code) as is →
+ * the error mappers, in order → an `HttpException` mapped by status (5xx masked) → anything else
+ * masked as `Unexpected error.` with `INTERNAL_SERVER_ERROR`, logged once (unless `exposeErrors`).
+ * The `cause` of a shown `GraphQLException` is logged once too, never sent.
+ * Request errors (parse, validation, variables, limits) carry their code and are never logged
+ * above `debug`.
+ *
+ * Kept apart from the import-free `errors.ts`, which the compiler side may reach.
+ */
+import type { Container, CoreLogger, Token } from '@znight/core'
+import type {
+  ASTNode,
+  DocumentNode,
+  FieldNode,
+  FragmentDefinitionNode,
+  GraphQLField,
+  GraphQLFormattedError,
+  GraphQLNamedType,
+  GraphQLSchema,
+  OperationDefinitionNode,
+  SelectionSetNode,
+} from 'graphql'
+import type { GraphQLContext, GraphQLErrorMapper } from './types.ts'
+
+import { isHttpException, ValidationException } from '@znight/http'
+import { GraphQLError, getNamedType, isObjectType, Kind } from 'graphql'
+
+import { GraphQLErrorCode, GraphQLException } from './errors.ts'
+
+/** A provider resolved once (singleton, instance) or per use, in the current scope (token). */
+export type Resolvable<T> = { readonly instance: T; readonly token?: undefined } | { readonly token: Token }
+
+/** Resolves a {@link Resolvable} (in the current scope for scoped providers). */
+export function resolveIn<T>(container: Container, resolvable: Resolvable<T>): T {
+  return resolvable.token === undefined ? resolvable.instance : (container.get(resolvable.token) as T)
+}
+
+/** Message of masked errors. */
+export const MASKED_MESSAGE = 'Unexpected error.'
+
+/** `HttpException` status → `extensions.code` (other 4xx: `BAD_REQUEST`, 5xx: masked). */
+const STATUS_CODES: ReadonlyMap<number, string> = new Map([
+  [400, GraphQLErrorCode.BadUserInput],
+  [401, GraphQLErrorCode.Unauthenticated],
+  [403, GraphQLErrorCode.Forbidden],
+  [404, GraphQLErrorCode.NotFound],
+  [409, GraphQLErrorCode.Conflict],
+  [429, GraphQLErrorCode.TooManyRequests],
+])
+
+/** Options of {@link ErrorFormatter}. */
+export interface ErrorFormatterOptions {
+  readonly container: Container
+  readonly mappers: readonly Resolvable<GraphQLErrorMapper>[]
+  readonly exposeErrors: boolean
+  readonly logger: CoreLogger
+  readonly schema: GraphQLSchema
+}
+
+/** Formats the errors of execution results. One per plugin, built at boot. */
+export class ErrorFormatter {
+  readonly #container: Container
+  readonly #mappers: readonly Resolvable<GraphQLErrorMapper>[]
+  readonly #expose: boolean
+  readonly #logger: CoreLogger
+  readonly #schema: GraphQLSchema
+
+  constructor(options: ErrorFormatterOptions) {
+    this.#container = options.container
+    this.#mappers = options.mappers
+    this.#expose = options.exposeErrors
+    this.#logger = options.logger
+    this.#schema = options.schema
+  }
+
+  /** Formats the errors of an executed operation (field errors). */
+  format(errors: readonly GraphQLError[], ctx: GraphQLContext): GraphQLFormattedError[] {
+    const result: GraphQLFormattedError[] = new Array(errors.length)
+    // the same cause may fail several fields (a loader rejecting every key): logged once
+    let logged: Set<unknown> | undefined
+    for (let index = 0; index < errors.length; index++) {
+      const error = errors[index] as GraphQLError
+      const original = error.originalError
+      if (original === undefined || original === null) {
+        // produced by graphql-js during execution (non-null violation...): about the schema, shown as is
+        result[index] = withCode(
+          error,
+          error.extensions['code'] === undefined ? GraphQLErrorCode.InternalServerError : undefined,
+        )
+        continue
+      }
+      const exposed = this.#exposed(original, ctx)
+      if (exposed !== undefined) {
+        result[index] = render(error, exposed)
+        // the original failure behind a presented error (`{ cause }`): logged once, never sent
+        const cause = exposed.cause
+        if (cause !== undefined) {
+          logged ??= new Set()
+          if (!logged.has(cause)) {
+            logged.add(cause)
+            this.#log(error, cause, ctx, exposed.code)
+          }
+        }
+        continue
+      }
+      if (original instanceof GraphQLError && !isCompletionError(original)) {
+        result[index] = { ...original.toJSON(), ...located(error) }
+        continue
+      }
+      logged ??= new Set()
+      if (!logged.has(original)) {
+        logged.add(original)
+        this.#log(error, original, ctx, undefined)
+      }
+      result[index] = {
+        message: this.#expose && original instanceof Error ? original.message : MASKED_MESSAGE,
+        ...located(error),
+        extensions: { code: GraphQLErrorCode.InternalServerError },
+      }
+    }
+    return result
+  }
+
+  /** The exception shown for `original`, `undefined` when it must be masked. */
+  #exposed(original: unknown, ctx: GraphQLContext): GraphQLException | undefined {
+    if (original instanceof GraphQLException) return original
+    for (const resolvable of this.#mappers) {
+      let mapped: GraphQLException | undefined
+      try {
+        mapped = resolveIn(this.#container, resolvable).map(original, ctx)
+      } catch (error) {
+        this.#logger.error('GraphQLPlugin: an error mapper failed', { err: error, requestId: ctx.requestId })
+        continue
+      }
+      if (mapped !== undefined) return mapped
+    }
+    if (isHttpException(original)) {
+      const status = original.status
+      if (original instanceof ValidationException) {
+        return new GraphQLException(original.message, {
+          code: GraphQLErrorCode.BadUserInput,
+          extensions: { issues: original.details },
+        })
+      }
+      if (status >= 500) return undefined
+      return new GraphQLException(original.message, {
+        code: STATUS_CODES.get(status) ?? GraphQLErrorCode.BadRequest,
+      })
+    }
+    return undefined
+  }
+
+  /** Logs an unexpected error, or the cause of a presented one (`code`), at `error` level. */
+  #log(error: GraphQLError, cause: unknown, ctx: GraphQLContext, code: string | undefined): void {
+    const coordinate = coordinateOf(this.#schema, ctx.document, ctx.operationName, error.path)
+    const what = code === undefined ? 'unexpected error' : `${code} error`
+    this.#logger.error(`GraphQL: ${what}${coordinate === undefined ? '' : ` in ${coordinate}`}`, {
+      err: cause,
+      requestId: ctx.requestId,
+      ...(code === undefined ? {} : { code }),
+      ...(coordinate === undefined ? {} : { coordinate }),
+      ...(error.path === undefined ? {} : { path: error.path.join('.') }),
+    })
+  }
+}
+
+/**
+ * What graphql-js raises while completing a resolver's value: a built-in scalar or an enum that
+ * cannot represent it (`String cannot represent value: { passwordHash: ... }`), a list value that
+ * is not iterable, a union or interface value that resolves to no member. A server bug whose message
+ * holds the value, masked and logged like any unexpected error. graphql-js throws plain
+ * `GraphQLError`s without code there, told apart from the ones of user code by their message.
+ */
+const COMPLETION_ERROR =
+  /^(?:(?:Int|Float|String|Boolean|ID) cannot represent |Enum "[^"]*" cannot represent |Expected Iterable, but did not find one for field "|Abstract type "|Runtime Object type ")/
+
+function isCompletionError(error: GraphQLError): boolean {
+  return (
+    error.constructor === GraphQLError && error.extensions['code'] === undefined && COMPLETION_ERROR.test(error.message)
+  )
+}
+
+function located(error: GraphQLError): Pick<GraphQLFormattedError, 'locations' | 'path'> {
+  return {
+    ...(error.locations === undefined ? {} : { locations: error.locations }),
+    ...(error.path === undefined ? {} : { path: error.path }),
+  }
+}
+
+/** `{ message, locations, path, extensions: { ...extensions, code } }`. */
+function render(error: GraphQLError, exception: GraphQLException): GraphQLFormattedError {
+  return {
+    message: exception.message,
+    ...located(error),
+    extensions: { ...exception.extensions, code: exception.code },
+  }
+}
+
+/** A graphql-js error formatted with `extensions.code` set to `code` (kept as is without code). */
+export function withCode(error: GraphQLError, code: string | undefined): GraphQLFormattedError {
+  const formatted = error.toJSON()
+  if (code === undefined) return formatted
+  return { ...formatted, extensions: { ...formatted.extensions, code } }
+}
+
+/** A request error (no location): `{ message, extensions: { code } }`. */
+export function requestError(
+  message: string,
+  code: string,
+  nodes?: ASTNode | readonly ASTNode[],
+): GraphQLFormattedError {
+  return withCode(new GraphQLError(message, nodes === undefined ? {} : { nodes }), code)
+}
+
+/**
+ * The schema coordinate (`Book.author`) of the field at `path`, found by walking the operation's
+ * selections (aliases, fragments, inline fragments). Best effort, for logs: `undefined` when the
+ * path crosses a union without a type condition.
+ */
+export function coordinateOf(
+  schema: GraphQLSchema,
+  document: DocumentNode,
+  operationName: string | undefined,
+  path: readonly (string | number)[] | undefined,
+): string | undefined {
+  if (path === undefined || path.length === 0) return undefined
+  const fragments = new Map<string, FragmentDefinitionNode>()
+  let operation: OperationDefinitionNode | undefined
+  for (const definition of document.definitions) {
+    if (definition.kind === Kind.FRAGMENT_DEFINITION) fragments.set(definition.name.value, definition)
+    else if (
+      definition.kind === Kind.OPERATION_DEFINITION &&
+      (operationName === undefined || definition.name?.value === operationName)
+    ) {
+      operation ??= definition
+    }
+  }
+  if (operation === undefined) return undefined
+  let type: GraphQLNamedType | undefined | null = schema.getRootType(operation.operation)
+  let selections: SelectionSetNode[] = [operation.selectionSet]
+  let coordinate: string | undefined
+  for (const segment of path) {
+    if (typeof segment === 'number') continue
+    const found = findField(selections, segment, fragments, type?.name)
+    if (found === undefined || type === undefined || type === null) return undefined
+    const parent: GraphQLNamedType | undefined | null =
+      found.typeCondition === undefined ? type : schema.getType(found.typeCondition)
+    if (!isObjectType(parent)) return undefined
+    const field: GraphQLField<unknown, unknown> | undefined = parent.getFields()[found.field.name.value]
+    coordinate = `${parent.name}.${found.field.name.value}`
+    if (field === undefined) return coordinate
+    type = getNamedType(field.type)
+    selections = found.field.selectionSet === undefined ? [] : [found.field.selectionSet]
+  }
+  return coordinate
+}
+
+function findField(
+  sets: readonly SelectionSetNode[],
+  key: string,
+  fragments: ReadonlyMap<string, FragmentDefinitionNode>,
+  typeCondition: string | undefined,
+): { readonly field: FieldNode; readonly typeCondition: string | undefined } | undefined {
+  for (const set of sets) {
+    for (const selection of set.selections) {
+      if (selection.kind === Kind.FIELD) {
+        if ((selection.alias ?? selection.name).value === key) return { field: selection, typeCondition }
+      } else {
+        const nested = selection.kind === Kind.INLINE_FRAGMENT ? selection : fragments.get(selection.name.value)
+        if (nested === undefined) continue
+        const found = findField(
+          [nested.selectionSet],
+          key,
+          fragments,
+          nested.typeCondition?.name.value ?? typeCondition,
+        )
+        if (found !== undefined) return found
+      }
+    }
+  }
+  return undefined
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+/**
+ * `@znight/graphql`: code-first GraphQL whose schema is derived from TypeScript types at build time
+ * (RFC 0005). Resolvers are providers marked with `@Resolver`, `@Query`, `@Mutation`,
+ * `@Subscription` and `@ResolveField`; the compiler extension (`@znight/graphql/compiler`) generates
+ * `metadata.extensions.graphql`, served by `GraphQLPlugin` on graphql-js 17.
+ */
+
+export type { StandardSchemaV1 } from '@znight/http'
+export type { Float, ID, Int, JSONValue, ResolverOptions } from './decorators.ts'
+export type { GraphQLRequest, GraphQLResultStream } from './execution.ts'
+export type {
+  AnyPubSub,
+  GraphQLErrorMapperRef,
+  GraphQLGuardRef,
+  GraphQLHttpOptions,
+  GraphQLLimits,
+  GraphQLPluginOptions,
+  GraphQLSubscriptionOptions,
+} from './options.ts'
+export type {
+  BatchLoad,
+  BatchLoadClass,
+  BatchLoader,
+  GraphQLArgs,
+  GraphQLContext,
+  GraphQLErrorMapper,
+  GraphQLErrorMapperClass,
+  GraphQLGuard,
+  GraphQLGuardClass,
+  GraphQLOperationKind,
+  GraphQLTransport,
+  LoaderKey,
+  LoaderOptions,
+  LoaderValue,
+  ResolverContext,
+  ScalarDefinition,
+} from './types.ts'
+
+/** `Loader` is both the `@Loader()` parameter decorator and the `Loader<L>` parameter type. */
+export {
+  Args,
+  Ctx,
+  Info,
+  Loader,
+  Mutation,
+  Parent,
+  Query,
+  ResolveField,
+  Resolver,
+  Subscription,
+  scalar,
+  UseGuard,
+} from './decorators.ts'
+export {
+  GraphQLErrorCode,
+  type GraphQLErrorCodeValue,
+  GraphQLException,
+  type GraphQLExceptionOptions,
+} from './errors.ts'
+export { type OrderByKeysOptions, orderByKeys } from './loaders.ts'
+export { MemoryPubSub, type MemoryPubSubOptions } from './memory-pubsub.ts'
+export {
+  GRAPHQL_METADATA_VERSION,
+  type GraphQLArgumentDefinition,
+  type GraphQLBuiltinScalarDefinition,
+  type GraphQLCustomScalarDefinition,
+  type GraphQLDiscriminator,
+  type GraphQLEnumTypeDefinition,
+  type GraphQLEnumValueDefinition,
+  type GraphQLFieldDefinition,
+  type GraphQLInputFieldDefinition,
+  type GraphQLInputTypeDefinition,
+  type GraphQLMetadata,
+  type GraphQLObjectTypeDefinition,
+  type GraphQLResolverBinding,
+  type GraphQLResolverOperation,
+  type GraphQLRootTypes,
+  type GraphQLTypeDefinition,
+  type GraphQLUnionTypeDefinition,
+} from './metadata.ts'
+export { type DirectExecuteOptions, GraphQLPlugin, type MaybePromise } from './plugin.ts'
+export { PubSub, type SubscribeOptions } from './pubsub.ts'
+export { GraphQLTokens } from './tokens.ts'
+export { validateArgs } from './validate-args.ts'

package/src/limits.ts

@@ -0,0 +1,177 @@
+/**
+ * Document limits (RFC 0005 §8.9): depth, aliases and directives, checked in one walk of the parsed
+ * document **before** the specified validation rules, so that an abusive document is rejected
+ * before rules whose cost grows with it (`OverlappingFieldsCanBeMerged`) run. Aliases are counted as
+ * written, and, when the document spreads fragments, as each operation executes them (a fragment
+ * spread several times counts each time). `maxTokens` is enforced by `parse()` itself.
+ */
+import type { DirectiveNode, DocumentNode, FragmentDefinitionNode, SelectionSetNode } from 'graphql'
+
+import { GraphQLError, Kind } from 'graphql'
+
+import { GraphQLErrorCode } from './errors.ts'
+
+/** Resolved limits: `undefined` disables one. */
+export interface DocumentLimits {
+  readonly maxDepth: number | undefined
+  readonly maxAliases: number | undefined
+  readonly maxDirectives: number | undefined
+}
+
+/** The limit errors of `document` (`QUERY_TOO_COMPLEX`), `undefined` when it is within its limits. */
+export function checkLimits(document: DocumentNode, limits: DocumentLimits): GraphQLError[] | undefined {
+  const { maxDepth, maxAliases, maxDirectives } = limits
+  if (maxDepth === undefined && maxAliases === undefined && maxDirectives === undefined) return undefined
+  const counter = { aliases: 0, directives: 0, spreads: 0 }
+  const fragments = new Map<string, FragmentDefinitionNode>()
+  for (const definition of document.definitions) {
+    if (definition.kind === Kind.FRAGMENT_DEFINITION) fragments.set(definition.name.value, definition)
+  }
+  let errors: GraphQLError[] | undefined
+  const fail = (message: string): void => {
+    errors ??= []
+    errors.push(new GraphQLError(message, { extensions: { code: GraphQLErrorCode.QueryTooComplex } }))
+  }
+  // counts every selection once, where it is written (fragment spreads expanded below for aliases)
+  for (const definition of document.definitions) {
+    if (definition.kind === Kind.OPERATION_DEFINITION || definition.kind === Kind.FRAGMENT_DEFINITION) {
+      countDirectives(definition.directives, counter)
+      if (definition.kind === Kind.OPERATION_DEFINITION) {
+        for (const variable of definition.variableDefinitions ?? []) countDirectives(variable.directives, counter)
+      }
+      count(definition.selectionSet, counter)
+    }
+  }
+  if (maxAliases !== undefined) {
+    if (counter.aliases > maxAliases) {
+      fail(`The document has ${counter.aliases} aliases, more than the limit of ${maxAliases}.`)
+    } else if (counter.spreads > 0) {
+      // a fragment spread several times executes its aliases each time: counted as executed
+      const memo = new Map<string, number>()
+      for (const definition of document.definitions) {
+        if (definition.kind !== Kind.OPERATION_DEFINITION) continue
+        const executed = aliasesOf(definition.selectionSet, fragments, memo, new Set(), maxAliases + 1)
+        if (executed > maxAliases) {
+          const name = definition.name === undefined ? 'The operation' : `The operation ${definition.name.value}`
+          fail(`${name} has more than ${maxAliases} aliases once its fragments are expanded.`)
+          break
+        }
+      }
+    }
+  }
+  if (maxDirectives !== undefined && counter.directives > maxDirectives) {
+    fail(`The document has ${counter.directives} directives, more than the limit of ${maxDirectives}.`)
+  }
+  if (maxDepth !== undefined) {
+    const depths = new Map<string, number>()
+    for (const definition of document.definitions) {
+      if (definition.kind !== Kind.OPERATION_DEFINITION) continue
+      const depth = depthOf(definition.selectionSet, fragments, depths, new Set())
+      if (depth > maxDepth) {
+        const name = definition.name === undefined ? 'The operation' : `The operation ${definition.name.value}`
+        fail(`${name} is ${depth} levels deep, more than the limit of ${maxDepth}.`)
+      }
+    }
+  }
+  return errors
+}
+
+interface Counter {
+  aliases: number
+  directives: number
+  spreads: number
+}
+
+function countDirectives(directives: readonly DirectiveNode[] | undefined, counter: Counter): void {
+  if (directives !== undefined) counter.directives += directives.length
+}
+
+function count(set: SelectionSetNode, counter: Counter): void {
+  for (const selection of set.selections) {
+    countDirectives(selection.directives, counter)
+    if (selection.kind === Kind.FIELD) {
+      if (selection.alias !== undefined) counter.aliases++
+      if (selection.selectionSet !== undefined) count(selection.selectionSet, counter)
+    } else if (selection.kind === Kind.INLINE_FRAGMENT) {
+      count(selection.selectionSet, counter)
+    } else {
+      counter.spreads++
+    }
+  }
+}
+
+/**
+ * Aliases a selection set executes, fragment spreads expanded (`a: f { ...F } b: f { ...F }` counts
+ * the aliases of `F` twice). Fragment counts are memoised, so the walk stays linear in the document;
+ * counts saturate at `cap` (one more than the limit) and a fragment cycle counts 0 (validation
+ * rejects it).
+ */
+function aliasesOf(
+  set: SelectionSetNode,
+  fragments: ReadonlyMap<string, FragmentDefinitionNode>,
+  memo: Map<string, number>,
+  visiting: Set<string>,
+  cap: number,
+): number {
+  let total = 0
+  for (const selection of set.selections) {
+    if (selection.kind === Kind.FIELD) {
+      if (selection.alias !== undefined) total++
+      if (selection.selectionSet !== undefined)
+        total += aliasesOf(selection.selectionSet, fragments, memo, visiting, cap)
+    } else if (selection.kind === Kind.INLINE_FRAGMENT) {
+      total += aliasesOf(selection.selectionSet, fragments, memo, visiting, cap)
+    } else {
+      const name = selection.name.value
+      let known = memo.get(name)
+      if (known === undefined) {
+        const fragment = fragments.get(name)
+        if (fragment === undefined || visiting.has(name)) continue
+        visiting.add(name)
+        known = aliasesOf(fragment.selectionSet, fragments, memo, visiting, cap)
+        visiting.delete(name)
+        memo.set(name, known)
+      }
+      total += known
+    }
+    if (total >= cap) return cap
+  }
+  return total
+}
+
+/**
+ * Field nesting of a selection set (`{ a { b } }` is 2). Introspection fields (`__schema`,
+ * `__type`) do not count: `MaxIntrospectionDepthRule` bounds them. Fragment depths are memoised; a
+ * fragment cycle counts 0 (validation rejects it).
+ */
+function depthOf(
+  set: SelectionSetNode,
+  fragments: ReadonlyMap<string, FragmentDefinitionNode>,
+  depths: Map<string, number>,
+  visiting: Set<string>,
+): number {
+  let max = 0
+  for (const selection of set.selections) {
+    let depth = 0
+    if (selection.kind === Kind.FIELD) {
+      if (selection.name.value.startsWith('__')) continue
+      depth =
+        selection.selectionSet === undefined ? 1 : 1 + depthOf(selection.selectionSet, fragments, depths, visiting)
+    } else if (selection.kind === Kind.INLINE_FRAGMENT) {
+      depth = depthOf(selection.selectionSet, fragments, depths, visiting)
+    } else {
+      const name = selection.name.value
+      const known = depths.get(name)
+      if (known === undefined) {
+        const fragment = fragments.get(name)
+        if (fragment === undefined || visiting.has(name)) continue
+        visiting.add(name)
+        depth = depthOf(fragment.selectionSet, fragments, depths, visiting)
+        visiting.delete(name)
+        depths.set(name, depth)
+      } else depth = known
+    }
+    if (depth > max) max = depth
+  }
+  return max
+}

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,
+  })
+}