@znight/graphql 0.0.0 → 0.2.1

package/src/compiler/locate.ts

@@ -0,0 +1,82 @@
+/**
+ * Source locations of diagnostics. Computed only when a diagnostic is reported: the happy path
+ * never reads source text.
+ */
+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*/
+
+const OPENING = new Set(['(', '[', '{', '<'])
+const CLOSING = new Set([')', ']', '}', '>'])
+
+/**
+ * The type annotation of a property, a property signature or a getter (`get x(): T`), from the
+ * location of the member (its name); the member itself when the annotation cannot be found.
+ */
+export function annotationLocation(project: Project, member: Location | undefined): Location | undefined {
+  if (member === undefined) return undefined
+  const file = project.getFile(member.file)
+  if (file === undefined) return member
+  const text = file.text
+  const head = MEMBER_HEAD.exec(text.slice(member.start, member.start + 256))
+  if (head === null) return member
+  const start = member.start + head[0].length
+  let depth = 0
+  let end = start
+  for (let index = start; index < text.length; index++) {
+    const char = text[index] as string
+    if (char === '=' && text[index + 1] === '>') {
+      index++
+      continue
+    }
+    // a getter body or an initializer after the annotation
+    if (depth === 0 && end > start && (char === '{' || char === '=')) break
+    if (OPENING.has(char)) depth++
+    else if (CLOSING.has(char)) {
+      if (depth === 0) break
+      depth--
+    } else if (depth === 0 && (char === ';' || char === ',')) break
+    else if (depth === 0 && char === '\n' && !/^\s*[|&]/.test(text.slice(index + 1, index + 64))) break
+    if (!/\s/.test(char)) end = index + 1
+  }
+  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

@@ -0,0 +1,137 @@
+/**
+ * The schema model built by `validate` (RFC 0005 §6.1) and emitted by `generate` (§7): the GraphQL
+ * types reachable from the root fields, with their TypeScript origins (locations, resolver data).
+ */
+import type { Location } from '@znight/compiler'
+import type { MetaEntry } from '@znight/http/compiler'
+import type { GraphQLTypeRef } from '../type-ref.ts'
+import type { FieldData, ResolverData } from './data.ts'
+
+/** A field of an object type. */
+export interface FieldModel {
+  readonly name: string
+  /** Printed type reference (`'[Book!]!'`). */
+  type: string
+  description: string | undefined
+  deprecationReason: string | undefined
+  readonly args: ArgModel[]
+  /** The resolver method behind the field; `undefined`: the default resolver (`parent[name]`). */
+  binding: { readonly resolver: ResolverData; readonly field: FieldData } | undefined
+  readonly location: Location | undefined
+}
+
+/** An argument or an input field. */
+export interface ArgModel {
+  readonly name: string
+  type: string
+  ref: GraphQLTypeRef
+  readonly description: string | undefined
+  readonly deprecationReason: string | undefined
+  /** External default value (enum values by name); `undefined`: no default. */
+  defaultValue: unknown
+  /** The TypeScript type does not accept `null` (§5.4). */
+  nullAsUndefined: boolean
+  readonly location: Location | undefined
+}
+
+/** What every named type of the model has. */
+interface BaseModel {
+  readonly name: string
+  /** The declaration key (shapes) or a synthetic key (`#root:query`, `#builtin:DateTime`). */
+  readonly key: string
+  readonly description: string | undefined
+  readonly location: Location | undefined
+}
+
+/** An object type (root types included). */
+export interface ObjectModel extends BaseModel {
+  readonly kind: 'object'
+  readonly fields: FieldModel[]
+  /** How the type was first reached (`Query.book → Book`), for "reached from" diagnostics. */
+  readonly trail: string
+  /** The root field the type was first reached from. */
+  readonly root: Location | undefined
+  /** Identity of the class when the type is a non-generic class (union discriminators). */
+  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. */
+export interface DiscriminantProperty {
+  readonly name: string
+  readonly optional: boolean
+  /** The literal value of a literal-typed property. */
+  readonly literal: string | number | boolean | undefined
+}
+
+/** An input object type. */
+export interface InputModel extends BaseModel {
+  readonly kind: 'input'
+  readonly fields: ArgModel[]
+}
+
+/** An enum type. */
+export interface EnumModel extends BaseModel {
+  readonly kind: 'enum'
+  readonly values: readonly EnumValueModel[]
+}
+
+/** A value of an enum. */
+export interface EnumValueModel {
+  readonly name: string
+  readonly value: string | number
+  readonly description: string | undefined
+  readonly deprecationReason: string | undefined
+}
+
+/** A union type. */
+export interface UnionModel extends BaseModel {
+  readonly kind: 'union'
+  members: readonly string[]
+  discriminator: DiscriminatorModel | undefined
+}
+
+/** How the runtime tells union members apart. */
+export type DiscriminatorModel =
+  | { readonly by: 'property'; readonly property: string; readonly values: Readonly<Record<string, string>> }
+  | { readonly by: 'class'; readonly classes: readonly { readonly identity: string; readonly name: string }[] }
+  | { readonly by: 'typename' }
+
+/** A scalar: built in (`DateTime`, `BigInt`, `JSON`) or declared with `scalar<T>()`. */
+export interface ScalarModel extends BaseModel {
+  readonly kind: 'scalar'
+  /** 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 | InterfaceModel | InputModel | EnumModel | UnionModel | ScalarModel
+
+/** The schema of the application, built once per compile. */
+export interface GraphQLModel {
+  readonly roots: { readonly query: string; readonly mutation?: string; readonly subscription?: string }
+  /** Sorted by name. */
+  readonly types: readonly TypeModel[]
+  /** Route metadata entries of every field (effective), for `groups`. */
+  readonly meta: readonly MetaEntry[]
+  /** The SDL (`printSdl`), without trailing newline. */
+  readonly sdl: string
+  readonly schemaHash: string
+}

package/src/compiler/options.ts

@@ -0,0 +1,85 @@
+/**
+ * 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()`. */
+export interface GraphQLCompilerOptions {
+  /**
+   * Path of the SDL artifact, relative to the project root (`'schema.graphql'`), written next to the
+   * 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. 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',
+  schema: false,
+})
+
+const KNOWN = new Set(['sdl', 'number', 'schema'])
+
+/**
+ * Merges `options` onto `base`. Throws a `TypeError` naming the option on an invalid value: options
+ * are written in `znight.config.ts`, the error surfaces when the configuration is loaded.
+ */
+export function resolveOptions(
+  base: ResolvedGraphQLCompilerOptions,
+  options: GraphQLCompilerOptions,
+): ResolvedGraphQLCompilerOptions {
+  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+    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, schema)`)
+  }
+  const sdl = options.sdl === undefined ? base.sdl : options.sdl
+  if (sdl !== false && (typeof sdl !== 'string' || sdl.trim() === '')) {
+    throw new TypeError(
+      '[znight] graphql.configure(): "sdl" must be a path relative to the project root (\'schema.graphql\') or false',
+    )
+  }
+  const number = options.number === undefined ? base.number : options.number
+  if (number !== 'Float' && number !== 'Int') {
+    throw new TypeError(`[znight] graphql.configure(): "number" must be 'Float' or 'Int'`)
+  }
+  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])
+}

package/src/compiler/scalars.ts

@@ -0,0 +1,138 @@
+/**
+ * `scalar<T>(name, definition)` declarations of the application (RFC 0005 §5.7): `T` (a plain type
+ * reference, by identity) maps to the scalar `name` wherever it appears. The definition is an
+ * exported value the generated module imports; its `description` and `specifiedByURL` are read
+ * for the SDL when they are statically evaluable.
+ */
+import type { ArgInfo, Diagnostic, Location, ValidateContext } from '@znight/compiler'
+import type { GraphQLData } from './data.ts'
+
+import { isGraphQLName, SPECIFIED_SCALARS } from '../names.ts'
+import { Codes } from './constants.ts'
+import { GraphQLIds, SCALAR_ALIASES } from './ids.ts'
+
+/** A valid `scalar<T>()` declaration. */
+export interface ScalarDeclaration {
+  /** GraphQL name. */
+  readonly name: string
+  /** Identity of the exported constant (imported by the generated module). */
+  readonly identity: string
+  /** Identity of `T`. */
+  readonly type: string
+  readonly description: string | undefined
+  readonly specifiedByURL: string | undefined
+  /** Location of the constant's name. */
+  readonly location: Location
+}
+
+/** Valid declarations by the identity of their type; invalid ones are reported. */
+export function readScalars(
+  ctx: ValidateContext<GraphQLData>,
+  report: (diagnostic: Diagnostic) => void,
+): ReadonlyMap<string, ScalarDeclaration> {
+  const byType = new Map<string, ScalarDeclaration>()
+  const byName = new Map<string, ScalarDeclaration>()
+  for (const definition of ctx.definitionsOf(GraphQLIds.scalar)) {
+    const fail = (message: string, hints: readonly string[], related: Diagnostic['related'] = []): void =>
+      report({ code: Codes.InvalidDecorator, severity: 'error', message, location: definition.call, hints, related })
+    const [nameArg, definitionArg] = definition.args
+    const name = nameArg?.evaluated === true ? nameArg.value : undefined
+    if (typeof name !== 'string') {
+      fail(`scalar() of ${definition.name} needs a static name`, [`scalar<T>('Name', { ... })`])
+      continue
+    }
+    if (!isGraphQLName(name) || SPECIFIED_SCALARS.has(name)) {
+      report({
+        code: Codes.NameConflict,
+        severity: 'error',
+        message: SPECIFIED_SCALARS.has(name)
+          ? `'${name}' is a specified GraphQL scalar: scalar() cannot redefine it (${definition.name})`
+          : `'${name}' is not a valid GraphQL scalar name (${definition.name})`,
+        location: nameArg?.location ?? definition.call,
+        hints: ['GraphQL names match /^[_A-Za-z][_0-9A-Za-z]*$/ and do not start with __'],
+      })
+      continue
+    }
+    const type = definition.typeArgIdentities?.[0]
+    if (type === undefined) {
+      report({
+        code: Codes.InvalidType,
+        severity: 'error',
+        message: `scalar('${name}') of ${definition.name} needs a named type argument: scalar<T>('${name}', ...)`,
+        location: definition.call,
+        hints: [
+          `Name the TypeScript type of the scalar: export type ${name} = string & { readonly __brand: '${name}' }, then scalar<${name}>('${name}', ...)`,
+        ],
+      })
+      continue
+    }
+    if (SCALAR_ALIASES.has(type)) {
+      fail(
+        `scalar('${name}') of ${definition.name} cannot map ${type.slice(type.indexOf('#') + 1)}: it is a built-in scalar alias`,
+        ['Declare a branded type for the scalar: export type Name = string & { readonly __brand: "Name" }'],
+      )
+      continue
+    }
+    if (!definition.exported) {
+      fail(`The scalar ${definition.name} must be exported: the generated module imports it`, [
+        `export const ${definition.name} = scalar<...>('${name}', ...)`,
+      ])
+      continue
+    }
+    const declaration: ScalarDeclaration = {
+      name,
+      identity: definition.identity,
+      type,
+      description: staticProperty(ctx, definitionArg, 'description'),
+      specifiedByURL: staticProperty(ctx, definitionArg, 'specifiedByURL'),
+      location: definition.location,
+    }
+    const sameType = byType.get(type)
+    if (sameType !== undefined) {
+      report({
+        code: Codes.NameConflict,
+        severity: 'error',
+        message: `${definition.name} and ${sameType.identity} both map ${type.slice(type.indexOf('#') + 1)} to a scalar`,
+        location: definition.location,
+        related: [{ message: 'the other scalar', location: sameType.location }],
+        hints: ['Keep one scalar per TypeScript type'],
+      })
+      continue
+    }
+    // a user scalar named like a built-in one (DateTime) only conflicts when both are used: the model reports it
+    const sameName = byName.get(name)
+    if (sameName !== undefined) {
+      report({
+        code: Codes.NameConflict,
+        severity: 'error',
+        message: `Two scalars are named '${name}': ${definition.identity} and ${sameName.identity}`,
+        location: definition.location,
+        related: [{ message: 'the other scalar', location: sameName.location }],
+        hints: ['Rename one of them'],
+      })
+      continue
+    }
+    byType.set(type, declaration)
+    byName.set(name, declaration)
+  }
+  return byType
+}
+
+/** A string property of an object literal argument, when statically evaluable. */
+function staticProperty(ctx: ValidateContext<GraphQLData>, arg: ArgInfo | undefined, key: string): string | undefined {
+  if (arg === undefined) return undefined
+  if (arg.evaluated && typeof arg.value === 'object' && arg.value !== null && !Array.isArray(arg.value)) {
+    const value = (arg.value as Readonly<Record<string, unknown>>)[key]
+    return typeof value === 'string' ? value : undefined
+  }
+  const node = arg.node
+  if (node.type !== 'ObjectExpression') return undefined
+  for (const property of node.properties) {
+    if (property.type !== 'Property' || property.computed) continue
+    const name = property.key.type === 'Identifier' ? property.key.name : undefined
+    if (name !== key) continue
+    const result = ctx.project.evaluate(arg.location.file, property.value, { refs: 'none' })
+    return result.kind === 'value' && typeof result.value === 'string' ? result.value : undefined
+  }
+  return undefined
+}