@znight/graphql 0.2.0 → 0.2.1

package/src/metadata.ts

@@ -43,6 +43,7 @@ export interface GraphQLRootTypes {
 /** A named type of the schema. */
 export type GraphQLTypeDefinition =
   | GraphQLObjectTypeDefinition
+  | GraphQLInterfaceTypeDefinition
   | GraphQLInputTypeDefinition
   | GraphQLEnumTypeDefinition
   | GraphQLUnionTypeDefinition
@@ -54,10 +55,27 @@ 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'
@@ -97,6 +115,15 @@ export interface GraphQLBuiltinScalarDefinition {
 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
 }
@@ -141,7 +168,7 @@ export interface GraphQLEnumValueDefinition {
   readonly deprecationReason?: string
 }
 
-/** How the runtime tells the members of a union apart (`resolveType`). */
+/** How the runtime tells the members of a union or the implementations of an interface apart (`resolveType`). */
 export type GraphQLDiscriminator =
   | {
       readonly by: 'property'

package/src/options.ts

@@ -3,7 +3,15 @@
  */
 import type { ByteSize, GuardRef, RouteMetaEntry } from '@znight/http'
 import type { SubscribeOptions } from './pubsub.ts'
-import type { GraphQLErrorMapper, GraphQLErrorMapperClass, GraphQLGuard, GraphQLGuardClass } from './types.ts'
+import type {
+  GraphQLErrorMapper,
+  GraphQLErrorMapperClass,
+  GraphQLGuard,
+  GraphQLGuardClass,
+  GraphQLResultMapper,
+  GraphQLResultMapperClass,
+  GraphQLResultTypes,
+} from './types.ts'
 
 import { ErrorCode, ZnightError } from '@znight/core'
 import { parseByteSize } from '@znight/http'
@@ -23,6 +31,12 @@ export type GraphQLGuardRef = GraphQLGuardClass | GraphQLGuard
 /** An error mapper: a provider class or an instance. */
 export type GraphQLErrorMapperRef = GraphQLErrorMapperClass | GraphQLErrorMapper
 
+/**
+ * A result mapper: a provider class with `static types`, or an instance (its `types` property, or the
+ * `static types` of its class).
+ */
+export type GraphQLResultMapperRef = GraphQLResultMapperClass | (GraphQLResultMapper & Partial<GraphQLResultTypes>)
+
 /** 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. */
@@ -72,6 +86,11 @@ export interface GraphQLPluginOptions {
   readonly guards?: readonly GraphQLGuardRef[]
   /** Error mappers (classes or instances), tried in order. */
   readonly errorMappers?: readonly GraphQLErrorMapperRef[]
+  /**
+   * Result mappers (classes or instances), tried in order: errors as data (RFC 0008), on the fields
+   * whose union holds one of their `types`.
+   */
+  readonly resultMappers?: readonly GraphQLResultMapperRef[]
   /** Unmasked messages for unexpected errors (development). Default `false`. */
   readonly exposeErrors?: boolean
   /** Introspection; off, suggestions are hidden too. Default `NODE_ENV !== 'production'`. */
@@ -98,6 +117,7 @@ export interface ResolvedGraphQLOptions {
   readonly http: Required<GraphQLHttpOptions> | false
   readonly guards: readonly GraphQLGuardRef[]
   readonly errorMappers: readonly GraphQLErrorMapperRef[]
+  readonly resultMappers: readonly GraphQLResultMapperRef[]
   readonly exposeErrors: boolean
   readonly introspection: boolean
   readonly graphiql: boolean
@@ -126,6 +146,7 @@ const KEYS: ReadonlySet<string> = new Set([
   'http',
   'guards',
   'errorMappers',
+  'resultMappers',
   'exposeErrors',
   'introspection',
   'graphiql',
@@ -291,6 +312,7 @@ export function resolveGraphQLOptions(
     http,
     guards: refs<GraphQLGuardRef>('guards', options['guards'], 'canResolve'),
     errorMappers: refs<GraphQLErrorMapperRef>('errorMappers', options['errorMappers'], 'map'),
+    resultMappers: refs<GraphQLResultMapperRef>('resultMappers', options['resultMappers'], 'toResult'),
     exposeErrors: boolean('exposeErrors', options['exposeErrors'], false),
     introspection: boolean('introspection', options['introspection'], nodeEnv !== 'production'),
     graphiql: boolean('graphiql', options['graphiql'], nodeEnv === 'development'),

package/src/pipeline.ts

@@ -11,6 +11,8 @@
  *
  * A field without guards nor normaliser calls `invoke` from the closure graphql-js needs anyway:
  * no extra wrapper, no promise, no `await`. Plain property fields keep graphql-js' default resolver.
+ * A field that carries results (RFC 0008, `results.ts`) gets one wrapper around the whole pipeline,
+ * catching its errors to turn them into values; no other field does.
  */
 import type { Container, Token } from '@znight/core'
 import type { GraphQLFieldResolver, GraphQLResolveInfo } from 'graphql'
@@ -23,6 +25,7 @@ import type {
   GraphQLObjectTypeDefinition,
   GraphQLResolverBinding,
 } from './metadata.ts'
+import type { Recover } from './results.ts'
 import type { FieldFunctions, FieldFunctionsFactory } from './schema.ts'
 import type { GraphQLTypeRef } from './type-ref.ts'
 import type { GraphQLArgs, GraphQLContext, GraphQLGuard, ResolverContext } from './types.ts'
@@ -44,6 +47,8 @@ export interface PipelineOptions {
   readonly resolver: (binding: GraphQLResolverBinding, coordinate: string) => Resolvable<object>
   /** Input object types by name (null handling of nested input values). */
   readonly inputs: ReadonlyMap<string, GraphQLInputTypeDefinition>
+  /** The {@link Recover} function of a field that carries results (RFC 0008), `undefined` for the others. */
+  readonly results?: (field: GraphQLFieldDefinition, coordinate: string) => Recover | undefined
 }
 
 /** The generated invoker of a binding. */
@@ -80,6 +85,11 @@ function fieldFunctions(
     ...binding.guards.map(token => options.guard(token, coordinate)),
   ]
   const normalize = field.args === undefined ? undefined : normalizers.args(field.args)
+  const recover = options.results?.(field, coordinate)
+  const route =
+    guards.length === 0 && recover === undefined ? undefined : Object.freeze({ meta: binding.meta, coordinate })
+  const parentType = parent.name
+  const fieldName = field.name
 
   let resolve: GraphQLFieldResolver<unknown, unknown>
   if (guards.length === 0) {
@@ -104,9 +114,6 @@ function fieldFunctions(
             }
     }
   } else {
-    const route = Object.freeze({ meta: binding.meta, coordinate })
-    const parentType = parent.name
-    const fieldName = field.name
     const forbidden = (): never => {
       throw new GraphQLException(`Not allowed to resolve ${coordinate}`, { code: GraphQLErrorCode.Forbidden })
     }
@@ -116,7 +123,7 @@ function fieldFunctions(
       const allowed = runGuards(
         container,
         guards,
-        new FieldContext(route, operation, parentType, fieldName, args, p, i),
+        new FieldContext(route as ResolverContext['route'], operation, parentType, fieldName, args, p, i),
       )
       // §8.5: guards (they see the coerced arguments), then null handling, then invoke
       const call = (): unknown => {
@@ -128,7 +135,11 @@ function fieldFunctions(
       return allowed.then(ok => (ok ? call() : forbidden()))
     }
   }
-  if (binding.operation === 'subscription') {
+  const subscription = binding.operation === 'subscription'
+  if (recover !== undefined) {
+    resolve = withResults(resolve, recover, route as ResolverContext['route'], parentType, fieldName, subscription)
+  }
+  if (subscription) {
     // the method gives the source event stream; each event is the field value
     return { subscribe: resolve, resolve: identity }
   }
@@ -139,6 +150,56 @@ function identity(payload: unknown): unknown {
   return payload
 }
 
+/**
+ * The resolve function of a field that carries results (RFC 0008): errors of the whole pipeline
+ * (guards, null handling, `invoke`), thrown or rejected, go through `recover`. Synchronous results
+ * stay synchronous; a promise gets one rejection handler. For a subscription, a value is a source
+ * stream of that single event.
+ */
+function withResults(
+  resolve: GraphQLFieldResolver<unknown, unknown>,
+  recover: Recover,
+  route: ResolverContext['route'],
+  parentType: string,
+  fieldName: string,
+  subscription: boolean,
+): GraphQLFieldResolver<unknown, unknown> {
+  const fail = (error: unknown, p: unknown, a: unknown, c: unknown, i: GraphQLResolveInfo): unknown => {
+    const value = recover(
+      error,
+      new FieldContext(route, c as OperationContext, parentType, fieldName, a as GraphQLArgs, p, i),
+    )
+    return subscription ? once(value) : value
+  }
+  // captures nothing per call: the rejection handler is created in recoverAsync, on the promise path only
+  return (p, a, c, i) => {
+    let result: unknown
+    try {
+      result = resolve(p, a, c, i)
+    } catch (error) {
+      return fail(error, p, a, c, i)
+    }
+    return isThenable(result) ? recoverAsync(result, fail, p, a, c, i) : result
+  }
+}
+
+function recoverAsync(
+  result: PromiseLike<unknown>,
+  fail: (error: unknown, p: unknown, a: unknown, c: unknown, i: GraphQLResolveInfo) => unknown,
+  p: unknown,
+  a: unknown,
+  c: unknown,
+  i: GraphQLResolveInfo,
+): Promise<unknown> {
+  return Promise.resolve(result).then(undefined, error => fail(error, p, a, c, i))
+}
+
+/** A source event stream of one event. */
+// biome-ignore lint/suspicious/useAwait: an async generator is the shortest AsyncIterable of one value
+async function* once(value: unknown): AsyncGenerator<unknown> {
+  yield value
+}
+
 /** Runs guards in order, synchronously until one returns a promise. */
 function runGuards(
   container: Container,

package/src/plugin.ts

@@ -22,7 +22,7 @@ import type { ExecuteOptions, GraphQLRequest, GraphQLResultStream } from './exec
 import type { Resolvable } from './format.ts'
 import type { GraphQLInputTypeDefinition, GraphQLMetadata, GraphQLResolverBinding } from './metadata.ts'
 import type { GraphQLPluginOptions, ResolvedGraphQLOptions } from './options.ts'
-import type { GraphQLErrorMapper, GraphQLGuard } from './types.ts'
+import type { GraphQLErrorMapper, GraphQLGuard, GraphQLResultMapper } from './types.ts'
 
 import { displayName, ErrorCode, resolveOptions, ZnightError } from '@znight/core'
 import { printSchema } from 'graphql'
@@ -35,7 +35,8 @@ import { MemoryPubSub } from './memory-pubsub.ts'
 import { invalidOption, resolveGraphQLOptions } from './options.ts'
 import { globalGuardsApply, pipelineFactory } from './pipeline.ts'
 import { PubSub } from './pubsub.ts'
-import { buildGraphQLSchema, graphqlSection } from './schema.ts'
+import { checkResultTypes, declaredTypes, ResultMappers } from './results.ts'
+import { buildGraphQLSchema, checkGraphQLSection, graphqlSection } from './schema.ts'
 import { GraphQLTokens } from './tokens.ts'
 import { checkSseOptions, HttpTransport } from './transport/http.ts'
 
@@ -120,7 +121,7 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
   }
 
   /**
-   * Providers `TestApp` creates at boot: the classes of the `guards` and `errorMappers` options, and
+   * Providers `TestApp` creates at boot: the classes of the `guards`, `errorMappers` and `resultMappers` options, and
    * the resolvers, guards and loaders of the metadata.
    */
   initRoots(context?: PluginRootsContext): readonly ProviderKey[] {
@@ -128,7 +129,7 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
     try {
       const options: unknown = this.#options
       if (options !== null && typeof options === 'object') {
-        for (const key of ['guards', 'errorMappers'] as const) {
+        for (const key of ['guards', 'errorMappers', 'resultMappers'] as const) {
           const refs: unknown = (options as GraphQLPluginOptions)[key]
           if (Array.isArray(refs)) for (const ref of refs) if (typeof ref === 'function') roots.add(ref as ProviderKey)
         }
@@ -349,6 +350,10 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
     const providers = new Providers(container, metadata)
     const globalGuards = options.guards.map(ref => providers.ref<GraphQLGuard>(ref, 'guard', 'canResolve'))
     const mappers = options.errorMappers.map(ref => providers.ref<GraphQLErrorMapper>(ref, 'error mapper', 'map'))
+    const resultMappers = options.resultMappers.map(ref => ({
+      ...providers.ref<GraphQLResultMapper>(ref, 'result mapper', 'toResult'),
+      types: declaredTypes(ref),
+    }))
     const inputs = new Map<string, GraphQLInputTypeDefinition>()
     const fields: CheckedField[] = []
     const types = Array.isArray(section?.types) ? section.types : []
@@ -371,6 +376,18 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
         })
       }
     }
+    // a malformed section is reported by buildGraphQLSchema, not as types missing from it
+    if (resultMappers.length > 0 && checkGraphQLSection(section).length === 0) checkResultTypes(resultMappers, types)
+    const results = new ResultMappers(
+      container,
+      ctx.logger,
+      resultMappers.map(mapper => ({
+        resolvable: mapper.resolvable,
+        name: mapper.name,
+        types: mapper.types as readonly string[],
+      })),
+      types,
+    )
     const schema = buildGraphQLSchema(
       section,
       pipelineFactory({
@@ -380,6 +397,7 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
         resolver: (binding, coordinate) =>
           providers.token<object>(binding.token, `resolver of ${coordinate}`, binding.method),
         inputs,
+        results: (field, coordinate) => results.recover(field, coordinate),
       }),
     )
     checkFieldDecisions(fields, section.groups, options.enforcement, ctx.logger)
@@ -406,7 +424,11 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
       documentCache: options.documentCache,
       maxActiveSubscriptions: options.subscriptions === false ? undefined : options.subscriptions.maxActive,
     })
-    ctx.logger.debug('GraphQL schema built', { types: types.length, schemaHash: section.schemaHash })
+    ctx.logger.debug('GraphQL schema built', {
+      types: types.length,
+      schemaHash: section.schemaHash,
+      ...(results.fields === 0 ? {} : { resultFields: results.fields }),
+    })
     return { schema, section, executor }
   }
 }

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

@@ -115,12 +115,19 @@ export function builtinScalar(name: string): GraphQLScalarType | undefined {
  * `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>): GraphQLScalarType {
+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,
-    ...(definition.description === undefined ? {} : { description: definition.description }),
-    ...(definition.specifiedByURL === undefined ? {} : { specifiedByURL: definition.specifiedByURL }),
+    ...(description === undefined ? {} : { description }),
+    ...(specifiedByURL === undefined ? {} : { specifiedByURL }),
     coerceOutputValue: (value: unknown) => definition.serialize(value),
     coerceInputValue: (value: unknown) => definition.parseValue(value),
     coerceInputLiteral: