@znight/graphql 0.0.0 → 0.2.0

package/src/compiler/constants.ts

@@ -0,0 +1,74 @@
+/**
+ * Constants of the compiler extension modules: diagnostic codes, shape options, ordering. This
+ * module must stay free of runtime imports (the compiler loads the extension entry, which must
+ * never load the GraphQL runtime, graphql-js nor dataloader).
+ */
+import type { ErrorCode } from '@znight/core'
+
+import { GraphQLIds } from './ids.ts'
+
+/** Diagnostic codes the extension reports (RFC 0005 §6.6 and the reused framework codes). */
+export const Codes: {
+  /** ZNIGHT005: decorator target, arguments, method shape, look-alikes, `@Resolver` + `@Controller`. */
+  readonly InvalidDecorator: ErrorCode
+  /** ZNIGHT023: a root field without a decision of a required route decorator group (RFC 0001). */
+  readonly MissingRouteDecision: ErrorCode
+  /** ZNIGHT060: a TypeScript type with no GraphQL mapping, a missing annotation. */
+  readonly InvalidType: ErrorCode
+  /** ZNIGHT061: name conflicts, invalid or reserved names, field resolver type mismatches. */
+  readonly NameConflict: ErrorCode
+  /** ZNIGHT062: resolver structure (parent, subscriptions, no query, inheritance, libraries). */
+  readonly InvalidResolver: ErrorCode
+  /** ZNIGHT063: input position problems (dual use, getters, unions, cycles, defaults). */
+  readonly InvalidInput: ErrorCode
+  /** ZNIGHT064: union members that cannot be told apart at runtime. */
+  readonly UnresolvableAbstractType: ErrorCode
+  /** ZNIGHT065: `@Loader()` parameters and loader providers. */
+  readonly InvalidLoader: ErrorCode
+} = Object.freeze({
+  InvalidDecorator: 'ZNIGHT005',
+  MissingRouteDecision: 'ZNIGHT023',
+  InvalidType: 'ZNIGHT060',
+  NameConflict: 'ZNIGHT061',
+  InvalidResolver: 'ZNIGHT062',
+  InvalidInput: 'ZNIGHT063',
+  UnresolvableAbstractType: 'ZNIGHT064',
+  InvalidLoader: 'ZNIGHT065',
+})
+
+/** Root reason given to `AnalyzeContext.addRoot()`. */
+export const ROOT_REASON = 'GraphQL resolver'
+
+/** Async iterables: the return type of `@Subscription` methods (§6.2). */
+export const ASYNC_ITERABLES: ReadonlySet<string> = new Set([
+  'globalThis#AsyncIterable',
+  'globalThis#AsyncIterableIterator',
+  'globalThis#AsyncGenerator',
+])
+
+/** Iterables mapped to lists in output position (§6.2). */
+export const OUTPUT_ITERABLES: ReadonlySet<string> = new Set([
+  'globalThis#Set',
+  'globalThis#ReadonlySet',
+  'globalThis#Iterable',
+])
+
+/**
+ * Identities the shapes keep as references (`ShapeOptions.keep`), before the identities of the
+ * `scalar<T>()` declarations of the application.
+ */
+export const BASE_KEEP: readonly string[] = Object.freeze([
+  ...ASYNC_ITERABLES,
+  ...OUTPUT_ITERABLES,
+  GraphQLIds.ID,
+  GraphQLIds.Int,
+  GraphQLIds.Float,
+  GraphQLIds.JSONValue,
+  GraphQLIds.Loader,
+])
+
+/** Deterministic string comparison (code-unit order, never `localeCompare`). */
+export function compareStrings(a: string, b: string): number {
+  if (a === b) return 0
+  return a < b ? -1 : 1
+}

package/src/compiler/data.ts

@@ -0,0 +1,73 @@
+/**
+ * Data stored by the extension during analysis (`ctx.store()`), read back by `validate` and
+ * `generate`. Only what compiled libraries can encode: primitives, plain objects and arrays,
+ * `ClassInfo` (kept for its identity), `ValueRef`, `BindingHandle` and `Location`. Methods and
+ * parameters are looked up again by name and index (`ctx.classInfo(host.identity)`).
+ */
+
+import type { BindingHandle, ClassInfo, ClassRef, Location, ValueRef } from '@znight/compiler'
+import type { Scope } from '@znight/core'
+import type { MetaEntry } from '@znight/http/compiler'
+
+/** Kind of field a resolver method provides. */
+export type FieldOperation = 'query' | 'mutation' | 'subscription' | 'field'
+
+/** A `@Resolver` class. */
+export interface ResolverData {
+  readonly kind: 'resolver'
+  /** The resolver class; its identity is the provider token. */
+  readonly host: ClassInfo
+  readonly scope: Scope
+  /** Location of `@Resolver`. */
+  readonly location: Location
+  /** Class `@UseGuard` guards. */
+  readonly guards: readonly ClassRef[]
+  /** One entry per field decorator of the class's methods, in source order. */
+  readonly fields: readonly FieldData[]
+}
+
+/** One `@Query`, `@Mutation`, `@Subscription` or `@ResolveField` decorator. */
+export interface FieldData {
+  /** Method name. */
+  readonly method: string
+  readonly operation: FieldOperation
+  /** GraphQL field name (decorator argument, or the method name). */
+  readonly name: string
+  /** Location of the field decorator. */
+  readonly location: Location
+  /** Location of the method name. */
+  readonly methodLocation: Location
+  /** Method `@UseGuard` guards (class guards are on {@link ResolverData.guards}). */
+  readonly guards: readonly ClassRef[]
+  /** Effective route metadata: the class entries a method decision does not replace, then the method's. */
+  readonly meta: readonly MetaEntry[]
+  /** One entry per method parameter, by index (`undefined`: the parameter could not be analysed). */
+  readonly params: readonly (ParamData | undefined)[]
+  /** `false` when a parameter or the method could not be analysed (an error was reported). */
+  readonly complete: boolean
+}
+
+/** What a method parameter receives (§7.3). */
+export type ParamData =
+  | {
+      readonly kind: 'args'
+      /** `@Args('name')`: one argument; `undefined`: the properties of the type are the arguments. */
+      readonly name: string | undefined
+      /** `@Args(..., Schema)`: the Standard Schema validating the value. */
+      readonly schema: ValueRef | undefined
+      readonly location: Location
+    }
+  | { readonly kind: 'parent'; readonly location: Location }
+  | { readonly kind: 'ctx' }
+  | { readonly kind: 'info' }
+  | {
+      readonly kind: 'loader'
+      /** Binding of the loader provider (lazy edge from the resolver). */
+      readonly binding: BindingHandle
+      /** Identity of `L` in `Loader<L>`. */
+      readonly identity: string
+      readonly location: Location
+    }
+
+/** Everything the extension stores. */
+export type GraphQLData = ResolverData

package/src/compiler/defaults.ts

@@ -0,0 +1,92 @@
+/**
+ * Default values of arguments and input fields (RFC 0005 §6.3): an internal value (a `@default`
+ * JSON value, a statically evaluated parameter default) checked against its GraphQL type and turned
+ * into the external value graphql-js expects (`default: { value }`, enum values by name).
+ */
+import type { GraphQLTypeRef } from '../type-ref.ts'
+import type { TypeModel } from './model.ts'
+
+const GRAPHQL_INT_MAX = 2_147_483_647
+const GRAPHQL_INT_MIN = -2_147_483_648
+
+/** The external value, or why the value does not fit the type. */
+export type ExternalValue = { readonly value: unknown } | { readonly error: string }
+
+/** `value` (an internal value) as a GraphQL external value of `ref`; `types` resolves enums and inputs. */
+export function externalValue(
+  value: unknown,
+  ref: GraphQLTypeRef,
+  types: ReadonlyMap<string, TypeModel>,
+): ExternalValue {
+  if (value === null) return ref.nonNull ? { error: 'null for a non-null type' } : { value: null }
+  if (value === undefined) return { error: 'undefined' }
+  if (ref.kind === 'list') {
+    if (!Array.isArray(value)) return externalValue(value, ref.of, types)
+    const items: unknown[] = []
+    for (const item of value) {
+      const converted = externalValue(item, ref.of, types)
+      if ('error' in converted) return converted
+      items.push(converted.value)
+    }
+    return { value: items }
+  }
+  switch (ref.name) {
+    case 'String':
+      return typeof value === 'string' ? { value } : { error: 'expected a string' }
+    case 'ID':
+      return typeof value === 'string' || (typeof value === 'number' && Number.isInteger(value))
+        ? { value }
+        : { error: 'expected a string or an integer' }
+    case 'Int':
+      return typeof value === 'number' &&
+        Number.isInteger(value) &&
+        value <= GRAPHQL_INT_MAX &&
+        value >= GRAPHQL_INT_MIN
+        ? { value }
+        : { error: 'expected a 32-bit integer' }
+    case 'Float':
+      return typeof value === 'number' && Number.isFinite(value) ? { value } : { error: 'expected a finite number' }
+    case 'Boolean':
+      return typeof value === 'boolean' ? { value } : { error: 'expected a boolean' }
+    case 'JSON':
+      return isJson(value) ? { value } : { error: 'expected a JSON value' }
+  }
+  const type = types.get(ref.name)
+  if (type?.kind === 'enum') {
+    const found =
+      type.values.find(entry => entry.value === value) ??
+      (typeof value === 'string' ? type.values.find(entry => entry.name === value) : undefined)
+    return found === undefined
+      ? { error: `expected one of ${type.values.map(entry => entry.name).join(', ')}` }
+      : { value: found.name }
+  }
+  if (type?.kind === 'input') {
+    if (typeof value !== 'object' || Array.isArray(value)) return { error: `expected an object of type ${type.name}` }
+    const record = value as Readonly<Record<string, unknown>>
+    for (const key of Object.keys(record)) {
+      if (!type.fields.some(field => field.name === key)) return { error: `${type.name} has no field '${key}'` }
+    }
+    const result: Record<string, unknown> = {}
+    for (const field of type.fields) {
+      if (!Object.hasOwn(record, field.name) || record[field.name] === undefined) {
+        if (field.ref.nonNull && field.defaultValue === undefined)
+          return { error: `${type.name}.${field.name} is required` }
+        continue
+      }
+      const converted = externalValue(record[field.name], field.ref, types)
+      if ('error' in converted) return { error: `${type.name}.${field.name}: ${converted.error}` }
+      result[field.name] = converted.value
+    }
+    return { value: result }
+  }
+  return { error: `defaults of the scalar ${ref.name} are not supported` }
+}
+
+/** A JSON-compatible value (the `JSON` scalar). */
+function isJson(value: unknown): boolean {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return true
+  if (typeof value === 'number') return Number.isFinite(value)
+  if (Array.isArray(value)) return value.every(isJson)
+  if (typeof value !== 'object') return false
+  return Object.values(value).every(isJson)
+}

package/src/compiler/discriminators.ts

@@ -0,0 +1,53 @@
+/**
+ * Union discriminators (RFC 0005 §5.7): how the runtime tells the members of a union apart, decided
+ * at build time so that `resolveType` is a lookup.
+ */
+import type { ClassInfo } from '@znight/compiler'
+import type { DiscriminatorModel, ObjectModel } from './model.ts'
+
+import { compareStrings } from './constants.ts'
+
+/**
+ * `instanceof` when every member is an exported class (subclasses first), `__typename` when every
+ * member declares it, else the first property of the first member whose literal value differs in
+ * every member; `undefined` when none applies (ZNIGHT064).
+ */
+export function discriminatorOf(
+  members: readonly ObjectModel[],
+  classInfo: (identity: string) => ClassInfo | undefined,
+): DiscriminatorModel | undefined {
+  if (members.every(member => member.classIdentity !== undefined && classInfo(member.classIdentity)?.exported)) {
+    const depth = (identity: string): number => classInfo(identity)?.heritage.length ?? 0
+    return {
+      by: 'class',
+      classes: members
+        .map(member => ({ identity: member.classIdentity as string, name: member.name }))
+        // subclasses first: `instanceof` of a base class also matches its subclasses
+        .sort((a, b) => depth(b.identity) - depth(a.identity) || compareStrings(a.name, b.name)),
+    }
+  }
+  if (members.every(member => member.properties.some(property => property.name === '__typename'))) {
+    return { by: 'typename' }
+  }
+  for (const candidate of members[0]?.properties ?? []) {
+    if (candidate.optional || candidate.literal === undefined) continue
+    const values = literalValues(members, candidate.name)
+    if (values !== undefined) return { by: 'property', property: candidate.name, values }
+  }
+  return undefined
+}
+
+/** Literal value → member name when `property` is a required literal with a distinct value in every member. */
+function literalValues(members: readonly ObjectModel[], property: string): Record<string, string> | undefined {
+  const values = new Map<string, string>()
+  for (const member of members) {
+    const found = member.properties.find(entry => entry.name === property)
+    if (found === undefined || found.optional || found.literal === undefined) return undefined
+    const key = String(found.literal)
+    if (values.has(key)) return undefined
+    values.set(key, member.name)
+  }
+  const sorted: Record<string, string> = {}
+  for (const key of [...values.keys()].sort(compareStrings)) sorted[key] = values.get(key) as string
+  return sorted
+}

package/src/compiler/docs.ts

@@ -0,0 +1,55 @@
+/**
+ * The JSDoc vocabulary of the extension (RFC 0005 §5.14): descriptions, `@param`, `@deprecated`,
+ * `@default`, `@gqlHidden` and `@gqlName`.
+ */
+import type { DocComment, DocTag } from '@znight/compiler'
+
+import { DEFAULT_DEPRECATION_REASON } from '../names.ts'
+
+/** The comment text (before the first tag), `undefined` when empty. */
+export function descriptionOf(doc: DocComment | undefined): string | undefined {
+  return doc === undefined || doc.text === '' ? undefined : doc.text
+}
+
+/** The first tag named `name`. */
+export function tagOf(doc: DocComment | undefined, name: string): DocTag | undefined {
+  return doc?.tags.find(tag => tag.name === name)
+}
+
+/** `@deprecated reason`: the reason (graphql-js' default one without text), `undefined` without the tag. */
+export function deprecationOf(doc: DocComment | undefined): string | undefined {
+  const tag = tagOf(doc, 'deprecated')
+  if (tag === undefined) return undefined
+  const reason = tag.text.trim()
+  return reason === '' ? DEFAULT_DEPRECATION_REASON : reason
+}
+
+/** `true` with a `@gqlHidden` tag. */
+export function isHidden(doc: DocComment | undefined): boolean {
+  return tagOf(doc, 'gqlHidden') !== undefined
+}
+
+/**
+ * The text of `@param name text` (also `@param {Type} name - text`), `undefined` when there is no
+ * such tag or it has no text.
+ */
+export function paramDescription(doc: DocComment | undefined, name: string): string | undefined {
+  for (const tag of doc?.tags ?? []) {
+    if (tag.name !== 'param') continue
+    const match = /^(?:\{[^}]*\}\s*)?\[?([\w$]+)(?:=[^\]]*)?\]?(?:\s+-)?(?:\s+([\s\S]*))?$/.exec(tag.text.trim())
+    if (match?.[1] !== name) continue
+    const text = match[2]?.trim()
+    return text === undefined || text === '' ? undefined : text
+  }
+  return undefined
+}
+
+/** A `@default` value: JSON when it parses, the text otherwise (`@default title`). */
+export function defaultTagValue(tag: DocTag): unknown {
+  const text = tag.text.trim()
+  try {
+    return JSON.parse(text) as unknown
+  } catch {
+    return text
+  }
+}