@znight/graphql 0.2.0 → 0.2.1

package/src/schema.ts

@@ -17,13 +17,13 @@ import type {
   GraphQLInputType,
   GraphQLNamedType,
   GraphQLOutputType,
-  GraphQLTypeResolver,
 } from 'graphql'
 import type {
   GraphQLArgumentDefinition,
   GraphQLDiscriminator,
   GraphQLFieldDefinition,
   GraphQLInputTypeDefinition,
+  GraphQLInterfaceTypeDefinition,
   GraphQLMetadata,
   GraphQLObjectTypeDefinition,
   GraphQLResolverBinding,
@@ -40,6 +40,7 @@ import {
   GraphQLID,
   GraphQLInputObjectType,
   GraphQLInt,
+  GraphQLInterfaceType,
   GraphQLList,
   GraphQLNonNull,
   GraphQLObjectType,
@@ -90,7 +91,7 @@ export function graphqlSection(metadata: ZnightMetadata): GraphQLMetadata {
 
 const OPERATIONS: ReadonlySet<string> = new Set(['query', 'mutation', 'subscription', 'field'])
 const INPUT_KINDS: ReadonlySet<string> = new Set(['input', 'enum', 'scalar'])
-const OUTPUT_KINDS: ReadonlySet<string> = new Set(['object', 'enum', 'scalar', 'union'])
+const OUTPUT_KINDS: ReadonlySet<string> = new Set(['object', 'interface', 'enum', 'scalar', 'union'])
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
@@ -172,7 +173,10 @@ export function checkGraphQLSection(section: unknown): string[] {
     if (!isRecord(type) || typeof type['name'] !== 'string') continue
     const name = type['name']
     switch (type['kind']) {
-      case 'object': {
+      case 'object':
+      case 'interface': {
+        const isInterface = type['kind'] === 'interface'
+        checkInterfaces(name, type['interfaces'], kinds, problems)
         const fields = type['fields']
         if (!Array.isArray(fields) || fields.length === 0) {
           problems.push(`${name}: fields must be a non-empty array`)
@@ -190,7 +194,25 @@ export function checkGraphQLSection(section: unknown): string[] {
           seen.add(field['name'])
           checkRef(coordinate, field['type'], OUTPUT_KINDS, 'output')
           if (field['args'] !== undefined) checkInputValues(`${coordinate} arguments`, field['args'], false)
-          if (field['resolver'] !== undefined) checkBinding(coordinate, field['resolver'], problems)
+          if (field['resolver'] === undefined) continue
+          if (isInterface)
+            problems.push(`${coordinate}: interface fields have no resolver (bind it on the object types)`)
+          else checkBinding(coordinate, field['resolver'], problems)
+        }
+        if (isInterface) {
+          const implementations = types.filter(
+            other =>
+              isRecord(other) &&
+              other['kind'] === 'object' &&
+              Array.isArray(other['interfaces']) &&
+              other['interfaces'].includes(name),
+          )
+          checkDiscriminator(
+            name,
+            type['discriminator'],
+            implementations.map(other => (other as Record<string, unknown>)['name']),
+            problems,
+          )
         }
         break
       }
@@ -258,6 +280,11 @@ export function checkGraphQLSection(section: unknown): string[] {
             )
           }
         }
+        for (const key of ['description', 'specifiedByURL'] as const) {
+          if (type[key] !== undefined && typeof type[key] !== 'string')
+            problems.push(`${name}: ${key} must be a string`)
+        }
+        if (type['sdl'] !== undefined && type['sdl'] !== true) problems.push(`${name}: sdl must be true when present`)
         break
       default:
         problems.push(`${name}: unknown kind ${show(type['kind'])}`)
@@ -268,6 +295,25 @@ export function checkGraphQLSection(section: unknown): string[] {
   return problems
 }
 
+/** `interfaces` of an object or interface type: absent, or interface type names. */
+function checkInterfaces(
+  name: string,
+  interfaces: unknown,
+  kinds: ReadonlyMap<string, string>,
+  problems: string[],
+): void {
+  if (interfaces === undefined) return
+  if (!Array.isArray(interfaces)) {
+    problems.push(`${name}: interfaces must be an array of interface type names (received ${show(interfaces)})`)
+    return
+  }
+  for (const entry of interfaces) {
+    if (typeof entry !== 'string' || kinds.get(entry) !== 'interface') {
+      problems.push(`${name}: ${show(entry)} is not an interface type`)
+    }
+  }
+}
+
 function checkBinding(coordinate: string, binding: unknown, problems: string[]): void {
   if (!isRecord(binding)) {
     problems.push(`${coordinate}: resolver must be an object (received ${show(binding)})`)
@@ -393,8 +439,8 @@ export function invalidSchema(problems: readonly string[]): never {
   )
 }
 
-/** A union's `resolveType`, from its discriminator: data read once, at boot. */
-function typeResolver(discriminator: GraphQLDiscriminator): GraphQLTypeResolver<unknown, unknown> {
+/** The `resolveType` of a union or an interface, from its discriminator: data read once, at boot. */
+export function typeResolver(discriminator: GraphQLDiscriminator): (value: unknown) => string | undefined {
   switch (discriminator.by) {
     case 'property': {
       const property = discriminator.property
@@ -454,7 +500,7 @@ export function buildGraphQLSchema(section: GraphQLMetadata, functions: FieldFun
     ...(value.defaultValue === undefined ? {} : { default: { value: value.defaultValue } }),
   })
   const fieldConfig = (
-    type: GraphQLObjectTypeDefinition,
+    type: GraphQLObjectTypeDefinition | GraphQLInterfaceTypeDefinition,
     field: GraphQLFieldDefinition,
   ): GraphQLFieldConfig<unknown, unknown> => {
     const config: GraphQLFieldConfig<unknown, unknown> = {
@@ -465,7 +511,7 @@ export function buildGraphQLSchema(section: GraphQLMetadata, functions: FieldFun
         ? {}
         : { args: Object.fromEntries(field.args.map(arg => [arg.name, inputValue(arg)])) }),
     }
-    if (field.resolver === undefined) return config
+    if (field.resolver === undefined || type.kind === 'interface') return config
     const resolved = functions(field.resolver, `${type.name}.${field.name}`, field, type)
     return {
       ...config,
@@ -502,7 +548,7 @@ export function buildGraphQLSchema(section: GraphQLMetadata, functions: FieldFun
 function createType(
   type: GraphQLTypeDefinition,
   fieldConfig: (
-    type: GraphQLObjectTypeDefinition,
+    type: GraphQLObjectTypeDefinition | GraphQLInterfaceTypeDefinition,
     field: GraphQLFieldDefinition,
   ) => GraphQLFieldConfig<unknown, unknown>,
   inputValue: (value: GraphQLArgumentDefinition) => GraphQLInputFieldConfig,
@@ -514,9 +560,18 @@ function createType(
       return new GraphQLObjectType({
         name: type.name,
         ...description,
+        ...interfacesOf(type, lookup),
         // thunk: object types reference each other (cycles)
         fields: () => Object.fromEntries(type.fields.map(field => [field.name, fieldConfig(type, field)])),
       })
+    case 'interface':
+      return new GraphQLInterfaceType({
+        name: type.name,
+        ...description,
+        ...interfacesOf(type, lookup),
+        fields: () => Object.fromEntries(type.fields.map(field => [field.name, fieldConfig(type, field)])),
+        resolveType: typeResolver(type.discriminator),
+      })
     case 'input':
       return new GraphQLInputObjectType({
         name: type.name,
@@ -548,10 +603,33 @@ function createType(
       })
     default: {
       if ('builtin' in type) return builtinScalar(type.name) as GraphQLScalarType
+      // `sdl`: the entry's description and specifiedByURL replace the definition's, absent ones too
+      const sdl = type.sdl === true
+      const overrides = {
+        ...(type.description === undefined && !sdl ? {} : { description: type.description }),
+        ...(type.specifiedByURL === undefined && !sdl ? {} : { specifiedByURL: type.specifiedByURL }),
+      }
       const scalar = type.scalar
-      return scalar instanceof GraphQLScalarType
-        ? scalar
-        : definitionScalar(type.name, scalar as ScalarDefinition<unknown>)
+      if (scalar instanceof GraphQLScalarType) {
+        if (Object.keys(overrides).length === 0) return scalar
+        const config = scalar.toConfig()
+        return new GraphQLScalarType({
+          ...config,
+          description: 'description' in overrides ? overrides.description : config.description,
+          specifiedByURL: 'specifiedByURL' in overrides ? overrides.specifiedByURL : config.specifiedByURL,
+        })
+      }
+      return definitionScalar(type.name, scalar as ScalarDefinition<unknown>, overrides)
     }
   }
 }
+
+/** The `interfaces` thunk of an object or interface type (none: no key, as before RFC 0007). */
+function interfacesOf(
+  type: GraphQLObjectTypeDefinition | GraphQLInterfaceTypeDefinition,
+  lookup: (name: string) => GraphQLNamedType,
+): { interfaces?: () => GraphQLInterfaceType[] } {
+  const names = type.interfaces
+  if (names === undefined || names.length === 0) return {}
+  return { interfaces: () => names.map(name => lookup(name) as GraphQLInterfaceType) }
+}

package/src/sdl.ts

@@ -36,7 +36,7 @@ export interface SdlRoots {
 }
 
 /** A named type of the schema. */
-export type SdlType = SdlObjectType | SdlInputType | SdlEnumType | SdlUnionType | SdlScalarType
+export type SdlType = SdlObjectType | SdlInterfaceType | SdlInputType | SdlEnumType | SdlUnionType | SdlScalarType
 
 /** What every named type has. */
 export interface SdlNamedType {
@@ -47,6 +47,15 @@ export interface SdlNamedType {
 /** An object type (`type Book { ... }`). */
 export interface SdlObjectType extends SdlNamedType {
   readonly kind: 'object'
+  /** Implemented interfaces, in declaration order. */
+  readonly interfaces?: readonly string[]
+  readonly fields: readonly SdlField[]
+}
+
+/** An interface type (`interface Node { ... }`). */
+export interface SdlInterfaceType extends SdlNamedType {
+  readonly kind: 'interface'
+  readonly interfaces?: readonly string[]
   readonly fields: readonly SdlField[]
 }
 
@@ -168,7 +177,8 @@ class SdlPrinter {
     const head = printDescription(type.description, '', true)
     switch (type.kind) {
       case 'object':
-        return `${head}type ${type.name}${printBlock(type.fields.map((field, i) => this.#field(type.name, field, i)))}`
+      case 'interface':
+        return `${head}${type.kind === 'object' ? 'type' : 'interface'} ${type.name}${printImplements(type.interfaces)}${printBlock(type.fields.map((field, i) => this.#field(type.name, field, i)))}`
       case 'input':
         return `${head}input ${type.name}${printBlock(
           type.fields.map(
@@ -277,6 +287,11 @@ class SdlPrinter {
   }
 }
 
+/** graphql-js `printImplementedInterfaces`. */
+function printImplements(interfaces: readonly string[] | undefined): string {
+  return interfaces === undefined || interfaces.length === 0 ? '' : ` implements ${interfaces.join(' & ')}`
+}
+
 /** The `valueToLiteral` of the specified scalars, and graphql-js' default one for the others. */
 function scalarLiteral(value: unknown, name: string): Literal | undefined {
   switch (name) {

package/src/types.ts

@@ -171,6 +171,41 @@ export interface GraphQLErrorMapper {
 /** A class producing {@link GraphQLErrorMapper}s. */
 export type GraphQLErrorMapperClass = abstract new (...args: never[]) => GraphQLErrorMapper
 
+/**
+ * Turns the errors of a field into values of the field (errors as data, RFC 0008). It applies to
+ * the resolver-backed fields whose type is a union holding one of the object types it declares
+ * (`static types`), decided at boot; every other field keeps its errors in `errors[]`.
+ *
+ * ```ts
+ * @Injectable()
+ * export class Rejections implements GraphQLResultMapper {
+ *   static readonly types = ['NotFoundRejection']
+ *
+ *   toResult(error: unknown): NotFoundRejection | undefined {
+ *     if (error instanceof NotFoundException) return { __typename: 'NotFoundRejection', message: error.message }
+ *     return undefined
+ *   }
+ * }
+ * ```
+ */
+export interface GraphQLResultMapper {
+  /**
+   * The value of the field for `error`: an object of a member of the field's union, or `undefined`
+   * to leave the error to the next mapper, then to `errors[]`. Synchronous. `error` is the raw
+   * error, a `GraphQLException` included (a guard returning `false` is `FORBIDDEN`, a Standard
+   * Schema failure of the arguments `BAD_USER_INPUT` with `extensions.issues`).
+   */
+  toResult(error: unknown, ctx: ResolverContext): unknown
+}
+
+/** The object types a result mapper may produce: names of object types of the schema. */
+export interface GraphQLResultTypes {
+  readonly types: readonly string[]
+}
+
+/** A class producing {@link GraphQLResultMapper}s, with the object types it produces (`static types`). */
+export type GraphQLResultMapperClass = (abstract new (...args: never[]) => GraphQLResultMapper) & GraphQLResultTypes
+
 /**
  * The implementation of a custom scalar (§5.7), given to `scalar<T>(name, definition)`. The
  * runtime maps it to graphql-js 17 `GraphQLScalarType` coercers: `serialize` → `coerceOutputValue`,