@znight/graphql 0.2.0 → 0.2.1

package/src/compiler/constants.ts

@@ -25,6 +25,10 @@ export const Codes: {
   readonly UnresolvableAbstractType: ErrorCode
   /** ZNIGHT065: `@Loader()` parameters and loader providers. */
   readonly InvalidLoader: ErrorCode
+  /** ZNIGHT067: schema-first SDL files (RFC 0007): reading, syntax, validation, unsupported constructs. */
+  readonly InvalidSdl: ErrorCode
+  /** ZNIGHT068: schema-first resolvers against the SDL (RFC 0007): coverage and type conformance. */
+  readonly SchemaMismatch: ErrorCode
 } = Object.freeze({
   InvalidDecorator: 'ZNIGHT005',
   MissingRouteDecision: 'ZNIGHT023',
@@ -34,6 +38,8 @@ export const Codes: {
   InvalidInput: 'ZNIGHT063',
   UnresolvableAbstractType: 'ZNIGHT064',
   InvalidLoader: 'ZNIGHT065',
+  InvalidSdl: 'ZNIGHT067',
+  SchemaMismatch: 'ZNIGHT068',
 })
 
 /** Root reason given to `AnalyzeContext.addRoot()`. */

package/src/compiler/data.ts

@@ -20,6 +20,16 @@ export interface ResolverData {
   readonly scope: Scope
   /** Location of `@Resolver`. */
   readonly location: Location
+  /**
+   * `@Resolver('Event')`: the SDL object type its `@ResolveField` methods belong to (schema-first,
+   * RFC 0007), with the location of the argument.
+   */
+  readonly typeName?: { readonly name: string; readonly location: Location }
+  /**
+   * Schema-first: a class the analysis rejected (an error was reported); it only tells which fields
+   * its methods name (never bound, never a provider).
+   */
+  readonly invalid?: true
   /** Class `@UseGuard` guards. */
   readonly guards: readonly ClassRef[]
   /** One entry per field decorator of the class's methods, in source order. */

package/src/compiler/generate.ts

@@ -17,7 +17,7 @@ import type { GenerateContext, GenInput, GenNode, GenParam } from '@znight/compi
 import type { Token } from '@znight/core'
 import type { MetaEntry } from '@znight/http/compiler'
 import type { FieldData, GraphQLData, ParamData, ResolverData } from './data.ts'
-import type { ArgModel, FieldModel, GraphQLModel, TypeModel } from './model.ts'
+import type { ArgModel, DiscriminatorModel, FieldModel, GraphQLModel, TypeModel } from './model.ts'
 import type { ResolvedGraphQLCompilerOptions } from './options.ts'
 
 import { GRAPHQL_METADATA_VERSION } from '../metadata.ts'
@@ -106,7 +106,13 @@ function typeNode(ctx: Context, imports: Imports, type: TypeModel): GenNode {
   if (type.description !== undefined && type.kind !== 'scalar') head.push(['description', type.description])
   switch (type.kind) {
     case 'object':
-      return ctx.obj([...head, ['fields', ctx.arr(type.fields.map(field => fieldNode(ctx, imports, field)))]])
+    case 'interface': {
+      const entries: [string, GenInput][] = [...head]
+      if (type.interfaces.length > 0) entries.push(['interfaces', ctx.lit([...type.interfaces])])
+      entries.push(['fields', ctx.arr(type.fields.map(field => fieldNode(ctx, imports, field)))])
+      if (type.kind === 'interface') entries.push(['discriminator', discriminatorNode(ctx, type.discriminator)])
+      return ctx.obj(entries)
+    }
     case 'input':
       return ctx.obj([...head, ['fields', ctx.arr(type.fields.map(field => inputValueNode(ctx, field)))]])
     case 'enum':
@@ -127,36 +133,44 @@ function typeNode(ctx: Context, imports: Imports, type: TypeModel): GenNode {
           ),
         ],
       ])
-    case 'union': {
-      const discriminator = type.discriminator
-      let node: GenNode
-      if (discriminator === undefined || discriminator.by === 'typename') node = ctx.obj([['by', 'typename']])
-      else if (discriminator.by === 'property') {
-        node = ctx.obj([
-          ['by', 'property'],
-          ['property', discriminator.property],
-          ['values', ctx.obj(Object.entries(discriminator.values))],
-        ])
-      } else {
-        node = ctx.obj([
-          ['by', 'class'],
-          [
-            'classes',
-            ctx.arr(discriminator.classes.map(entry => ctx.arr([ctx.importValue(entry.identity), entry.name]))),
-          ],
-        ])
+    case 'union':
+      return ctx.obj([
+        ...head,
+        ['members', ctx.lit([...type.members])],
+        ['discriminator', discriminatorNode(ctx, type.discriminator)],
+      ])
+    case 'scalar': {
+      // built-in scalars carry no description (the runtime builds them, sdl.ts prints them alike);
+      // code-first user scalars bring theirs with the imported definition, schema-first ones take
+      // the SDL's (they win over the definition's)
+      if (type.definition === undefined) return ctx.obj([...head, ['builtin', ctx.lit(true)]])
+      const entries: [string, GenInput][] = [...head, ['scalar', ctx.importValue(type.definition)]]
+      if (type.fromSdl === true) {
+        if (type.description !== undefined) entries.push(['description', type.description])
+        if (type.specifiedByURL !== undefined) entries.push(['specifiedByURL', type.specifiedByURL])
+        entries.push(['sdl', ctx.lit(true)])
       }
-      return ctx.obj([...head, ['members', ctx.lit([...type.members])], ['discriminator', node]])
+      return ctx.obj(entries)
     }
-    case 'scalar':
-      // built-in scalars carry no description (the runtime builds them, sdl.ts prints them alike);
-      // user scalars bring theirs with the imported definition
-      return type.definition === undefined
-        ? ctx.obj([...head, ['builtin', ctx.lit(true)]])
-        : ctx.obj([...head, ['scalar', ctx.importValue(type.definition)]])
   }
 }
 
+/** How the runtime tells the members of a union or the implementations of an interface apart. */
+function discriminatorNode(ctx: Context, discriminator: DiscriminatorModel | undefined): GenNode {
+  if (discriminator === undefined || discriminator.by === 'typename') return ctx.obj([['by', 'typename']])
+  if (discriminator.by === 'property') {
+    return ctx.obj([
+      ['by', 'property'],
+      ['property', discriminator.property],
+      ['values', ctx.obj(Object.entries(discriminator.values))],
+    ])
+  }
+  return ctx.obj([
+    ['by', 'class'],
+    ['classes', ctx.arr(discriminator.classes.map(entry => ctx.arr([ctx.importValue(entry.identity), entry.name])))],
+  ])
+}
+
 function fieldNode(ctx: Context, imports: Imports, field: FieldModel): GenNode {
   const entries: [string, GenInput][] = [
     ['name', field.name],

package/src/compiler/graphql-js.ts

@@ -0,0 +1,42 @@
+/**
+ * The graphql-js modules schema-first compiles use (RFC 0007 §7): the language (parser, AST), the
+ * type system (`validateSchema`, type predicates) and the utilities (`buildASTSchema`,
+ * `concatAST`, `valueFromASTUntyped`). Loaded lazily, on the first schema-first compile, with
+ * `createRequire`: code-first compiles never load graphql-js, and the execution engine
+ * (`graphql/execution`, the `graphql` root entry) and dataloader are never loaded at build time
+ * (tests/boundaries.test.ts). graphql is a required peer of `@znight/graphql`.
+ */
+import type * as Language from 'graphql/language'
+import type * as Type from 'graphql/type'
+import type * as Utilities from 'graphql/utilities'
+
+import { createRequire } from 'node:module'
+
+/** The build-time graphql-js modules. */
+export interface GraphQLBuildModules {
+  readonly language: typeof Language
+  readonly type: typeof Type
+  readonly utilities: typeof Utilities
+}
+
+/** The only graphql-js modules the compiler extension may load (checked by tests/boundaries.test.ts). */
+export const GRAPHQL_BUILD_MODULES: readonly string[] = Object.freeze([
+  'graphql/language',
+  'graphql/type',
+  'graphql/utilities',
+])
+
+let loaded: GraphQLBuildModules | undefined
+
+/** The graphql-js modules, loaded on first use. */
+export function graphqlModules(): GraphQLBuildModules {
+  if (loaded === undefined) {
+    const load = createRequire(import.meta.url)
+    loaded = Object.freeze({
+      language: load('graphql/language') as typeof Language,
+      type: load('graphql/type') as typeof Type,
+      utilities: load('graphql/utilities') as typeof Utilities,
+    })
+  }
+  return loaded
+}

package/src/compiler/index.ts

@@ -32,6 +32,7 @@ import { buildModel } from './builder.ts'
 import { generateGraphQL } from './generate.ts'
 import { EXTENSION_NAME, GraphQLIds } from './ids.ts'
 import { DEFAULT_OPTIONS, resolveOptions } from './options.ts'
+import { buildSchemaFirstModel } from './schema-first.ts'
 
 export type { FieldData, FieldOperation, GraphQLData, ParamData, ResolverData } from './data.ts'
 export type { GraphQLCompilerOptions, ResolvedGraphQLCompilerOptions } from './options.ts'
@@ -41,7 +42,7 @@ const NO_ARGUMENT: DecoratorSpec = { targets: ['parameter'], params: [] }
 
 /** Decorators owned by the extension, by canonical identity (static / value arguments, §4.6). */
 const decorators: Readonly<Record<string, DecoratorSpec>> = Object.freeze({
-  [GraphQLIds.Resolver]: { targets: ['class'], params: ['static'] },
+  [GraphQLIds.Resolver]: { targets: ['class'], params: ['static', 'static'] },
   [GraphQLIds.Query]: FIELD,
   [GraphQLIds.Mutation]: FIELD,
   [GraphQLIds.Subscription]: FIELD,
@@ -74,9 +75,13 @@ function createExtension(options: ResolvedGraphQLCompilerOptions): GraphQLCompil
     name: EXTENSION_NAME,
     decorators,
     options,
-    analyzeClass: analyzeGraphQLClass,
+    analyzeClass: (cls, ctx) => analyzeGraphQLClass(cls, ctx, options),
     validate(ctx) {
-      models.set(ctx.graph.extensions, buildModel(ctx, options))
+      const schema = options.schema
+      models.set(
+        ctx.graph.extensions,
+        schema === false ? buildModel(ctx, options) : buildSchemaFirstModel(ctx, schema, options.sdl),
+      )
     },
     generate(ctx) {
       return generateGraphQL(ctx, modelOf(ctx.graph), options)

package/src/compiler/locate.ts

@@ -2,7 +2,7 @@
  * Source locations of diagnostics. Computed only when a diagnostic is reported: the happy path
  * never reads source text.
  */
-import type { Location, Project } from '@znight/compiler'
+import type { Location, MethodInfo, Project } from '@znight/compiler'
 
 /** From the member name: `name?: ` or `name(): ` (a getter), up to the annotation. */
 const MEMBER_HEAD = /^(?:[\w$]+|'[^']*'|"[^"]*")\s*\??\s*(?:\(\s*\))?\s*:\s*/
@@ -42,3 +42,41 @@ export function annotationLocation(project: Project, member: Location | undefine
   }
   return end > start ? file.location({ start, end }) : member
 }
+
+/**
+ * The return type annotation of a method, from the location of its name: after the parameter list
+ * (balanced brackets), `: T` up to the body; `undefined` when it cannot be found.
+ */
+export function returnTypeLocation(project: Project, method: MethodInfo): Location | undefined {
+  const file = project.getFile(method.location.file)
+  if (file === undefined) return undefined
+  const text = file.text
+  let index = text.indexOf('(', method.location.end)
+  if (index === -1) return undefined
+  let depth = 0
+  for (; index < text.length; index++) {
+    const char = text[index] as string
+    if (OPENING.has(char)) depth++
+    else if (CLOSING.has(char) && --depth === 0) break
+  }
+  const head = /^\s*:\s*/.exec(text.slice(index + 1, index + 64))
+  if (head === null) return undefined
+  const start = index + 1 + head[0].length
+  let end = start
+  depth = 0
+  for (let cursor = start; cursor < text.length; cursor++) {
+    const char = text[cursor] as string
+    if (char === '=' && text[cursor + 1] === '>') {
+      cursor++
+      continue
+    }
+    if (depth === 0 && (char === '{' || char === ';') && end > start) break
+    if (OPENING.has(char)) depth++
+    else if (CLOSING.has(char)) {
+      if (depth === 0) break
+      depth--
+    }
+    if (!/\s/.test(char)) end = cursor + 1
+  }
+  return end > start ? file.location({ start, end }) : undefined
+}

package/src/compiler/model.ts

@@ -55,6 +55,16 @@ export interface ObjectModel extends BaseModel {
   readonly classIdentity: string | undefined
   /** Property names of the declaration, with their literal value when they have one (discriminators). */
   readonly properties: readonly DiscriminantProperty[]
+  /** Implemented interfaces (schema-first, RFC 0007), in declaration order; empty in code-first. */
+  readonly interfaces: readonly string[]
+}
+
+/** An interface type (schema-first, RFC 0007). Its fields have no binding. */
+export interface InterfaceModel extends BaseModel {
+  readonly kind: 'interface'
+  readonly fields: FieldModel[]
+  readonly interfaces: readonly string[]
+  discriminator: DiscriminatorModel | undefined
 }
 
 /** A property of an object type's declaration, as union discriminators see it. */
@@ -104,10 +114,15 @@ export interface ScalarModel extends BaseModel {
   /** Identity of the exported `scalar<T>()` constant; `undefined` for a built-in scalar. */
   readonly definition: string | undefined
   readonly specifiedByURL: string | undefined
+  /**
+   * Schema-first: the description and `specifiedByURL` come from the SDL and are emitted in the
+   * metadata, where they win over the definition's (RFC 0007 §5.2).
+   */
+  readonly fromSdl?: true
 }
 
 /** A named type of the model. */
-export type TypeModel = ObjectModel | InputModel | EnumModel | UnionModel | ScalarModel
+export type TypeModel = ObjectModel | InterfaceModel | InputModel | EnumModel | UnionModel | ScalarModel
 
 /** The schema of the application, built once per compile. */
 export interface GraphQLModel {

package/src/compiler/options.ts

@@ -1,6 +1,6 @@
 /**
- * Options of the compiler extension (RFC 0005 §6.7), given with `graphql.configure({ ... })` in
- * `znight.config.ts`. Import-free.
+ * Options of the compiler extension (RFC 0005 §6.7, RFC 0007 §4.1), given with
+ * `graphql.configure({ ... })` in `znight.config.ts`. Import-free.
  */
 
 /** Options of `graphql.configure()`. */
@@ -10,20 +10,32 @@ export interface GraphQLCompilerOptions {
    * 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. */
+  /** GraphQL type of `number`. Default `'Float'`; `'Int'` suits counts and identifiers. Code-first only. */
   readonly number?: 'Float' | 'Int'
+  /**
+   * Schema-first mode (RFC 0007): globs of the `.graphql` files that define the schema, relative to
+   * the project root (`'src/**\/*.graphql'`, `!` negations allowed). Resolvers are bound to their
+   * fields by name and checked against the SDL. Default `false`: code-first.
+   */
+  readonly schema?: string | readonly string[] | false
 }
 
 /** {@link GraphQLCompilerOptions} with their defaults. */
 export interface ResolvedGraphQLCompilerOptions {
   readonly sdl: string | false
   readonly number: 'Float' | 'Int'
+  /** The schema-first globs; `false`: code-first. */
+  readonly schema: readonly string[] | false
 }
 
 /** The defaults. */
-export const DEFAULT_OPTIONS: ResolvedGraphQLCompilerOptions = Object.freeze({ sdl: false, number: 'Float' })
+export const DEFAULT_OPTIONS: ResolvedGraphQLCompilerOptions = Object.freeze({
+  sdl: false,
+  number: 'Float',
+  schema: false,
+})
 
-const KNOWN = new Set(['sdl', 'number'])
+const KNOWN = new Set(['sdl', 'number', 'schema'])
 
 /**
  * Merges `options` onto `base`. Throws a `TypeError` naming the option on an invalid value: options
@@ -34,11 +46,11 @@ export function resolveOptions(
   options: GraphQLCompilerOptions,
 ): ResolvedGraphQLCompilerOptions {
   if (typeof options !== 'object' || options === null || Array.isArray(options)) {
-    throw new TypeError('[znight] graphql.configure() expects an options object: { sdl?, number? }')
+    throw new TypeError('[znight] graphql.configure() expects an options object: { sdl?, number?, schema? }')
   }
   for (const key of Object.keys(options)) {
     if (!KNOWN.has(key))
-      throw new TypeError(`[znight] graphql.configure(): unknown option "${key}" (options: sdl, number)`)
+      throw new TypeError(`[znight] graphql.configure(): unknown option "${key}" (options: sdl, number, schema)`)
   }
   const sdl = options.sdl === undefined ? base.sdl : options.sdl
   if (sdl !== false && (typeof sdl !== 'string' || sdl.trim() === '')) {
@@ -50,5 +62,24 @@ export function resolveOptions(
   if (number !== 'Float' && number !== 'Int') {
     throw new TypeError(`[znight] graphql.configure(): "number" must be 'Float' or 'Int'`)
   }
-  return Object.freeze({ sdl, number })
+  return Object.freeze({ sdl, number, schema: resolveSchema(base.schema, options.schema) })
+}
+
+function resolveSchema(
+  base: readonly string[] | false,
+  schema: GraphQLCompilerOptions['schema'],
+): readonly string[] | false {
+  if (schema === undefined) return base
+  if (schema === false) return false
+  const globs = typeof schema === 'string' ? [schema] : schema
+  if (
+    !Array.isArray(globs) ||
+    globs.length === 0 ||
+    globs.some(glob => typeof glob !== 'string' || glob.trim() === '')
+  ) {
+    throw new TypeError(
+      '[znight] graphql.configure(): "schema" must be a glob or a non-empty list of globs relative to the project root (\'src/**/*.graphql\'), or false',
+    )
+  }
+  return Object.freeze([...globs])
 }