@znight/graphql 0.0.0 → 0.2.0

package/src/decisions.ts

@@ -0,0 +1,169 @@
+/**
+ * The boot check of route decisions on GraphQL fields (RFC 0001 §5.2, RFC 0005 §5.9): every root
+ * field decides every required group, and every decision of a required or enforced group is
+ * enforced by a guard of the field's chain (`static enforces`). Problems are one ZNIGHT023 error
+ * (`enforcement: 'error'`) or one warning per group.
+ *
+ * A small re-implementation of `@znight/http`'s internal checker for fields instead of routes.
+ */
+import type { CoreLogger } from '@znight/core'
+import type { HttpRouteGroupDefinition, RouteDecoratorInfo } from '@znight/http'
+
+import { ErrorCode, ZnightError } from '@znight/core'
+
+/** A resolver-backed field as seen by the check. */
+export interface CheckedField {
+  /** `Query.books (BookResolver.books)`. */
+  readonly description: string
+  /** Root fields must decide every required group. */
+  readonly root: boolean
+  /** Effective metadata. */
+  readonly meta: Readonly<Record<string, unknown>>
+  /** Guard classes of its chain (global when they apply, class, method); instances give their constructor. */
+  readonly guards: readonly { readonly cls: unknown; readonly name: string }[]
+}
+
+interface GroupInfo {
+  readonly group: string
+  readonly required: boolean
+}
+
+/** The groups listed by `static enforces` of a guard class (ZNIGHT005 when malformed). */
+export function enforcedBy(guard: unknown, name: string): readonly RouteDecoratorInfo[] {
+  if (typeof guard !== 'function') return []
+  let enforces: unknown
+  try {
+    enforces = (guard as { enforces?: unknown }).enforces
+  } catch (error) {
+    throw invalidEnforces(name, 'reading it threw', error)
+  }
+  if (enforces === undefined) return []
+  if (!Array.isArray(enforces)) throw invalidEnforces(name, 'expected an array of route decorators')
+  for (const entry of enforces as unknown[]) {
+    const info = (typeof entry === 'function' || (typeof entry === 'object' && entry !== null) ? entry : {}) as {
+      key?: unknown
+      group?: unknown
+      required?: unknown
+    }
+    if (typeof info.key !== 'string' || typeof info.group !== 'string' || typeof info.required !== 'boolean') {
+      throw invalidEnforces(name, 'every entry must be a route decorator ({ key, group, required })')
+    }
+  }
+  return enforces as readonly RouteDecoratorInfo[]
+}
+
+function invalidEnforces(name: string, reason: string, cause?: unknown): ZnightError {
+  return new ZnightError(
+    ErrorCode.InvalidDecorator,
+    `GraphQLPlugin: invalid static enforces of the guard ${name}: ${reason}`,
+    {
+      hints: [
+        'static readonly enforces = [Public, Authenticated, Roles] (decorators created with createRouteDecorator)',
+      ],
+      ...(cause === undefined ? {} : { cause }),
+    },
+  )
+}
+
+/** Runs the check. `groups`: `metadata.extensions.graphql.groups`. */
+export function checkFieldDecisions(
+  fields: readonly CheckedField[],
+  groups: Readonly<Record<string, HttpRouteGroupDefinition>> | undefined,
+  mode: 'error' | 'warn',
+  logger: CoreLogger,
+): void {
+  const keys = new Map<string, GroupInfo>()
+  const required = new Set<string>()
+  for (const [group, definition] of Object.entries(groups ?? {})) {
+    for (const key of definition.keys) keys.set(key, { group, required: definition.required })
+    if (definition.required) required.add(group)
+  }
+  const enforcedOf = new Map<unknown, ReadonlySet<string>>()
+  const enforced = (guard: { readonly cls: unknown; readonly name: string }): ReadonlySet<string> => {
+    let groupsOf = enforcedOf.get(guard.cls)
+    if (groupsOf === undefined) {
+      const infos = enforcedBy(guard.cls, guard.name)
+      for (const info of infos) {
+        if (!keys.has(info.key)) keys.set(info.key, { group: info.group, required: info.required })
+        if (info.required) required.add(info.group)
+      }
+      groupsOf = new Set(infos.map(info => info.group))
+      enforcedOf.set(guard.cls, groupsOf)
+    }
+    return groupsOf
+  }
+  const chains = fields.map(field => {
+    const set = new Set<string>()
+    for (const guard of field.guards) for (const group of enforced(guard)) set.add(group)
+    return set
+  })
+  const known = new Set<string>()
+  for (const chain of chains) for (const group of chain) known.add(group)
+  const groupOf = (key: string): string => keys.get(key)?.group ?? key
+
+  const problems = new Map<string, { missing: string[]; unenforced: string[] }>()
+  const problem = (group: string): { missing: string[]; unenforced: string[] } => {
+    let entry = problems.get(group)
+    if (entry === undefined) {
+      entry = { missing: [], unenforced: [] }
+      problems.set(group, entry)
+    }
+    return entry
+  }
+  fields.forEach((field, index) => {
+    const decided = new Set(Object.keys(field.meta).map(groupOf))
+    if (field.root) {
+      for (const group of required) if (!decided.has(group)) problem(group).missing.push(field.description)
+    }
+    const chain = chains[index] as Set<string>
+    for (const group of decided) {
+      if ((required.has(group) || known.has(group)) && !chain.has(group))
+        problem(group).unenforced.push(field.description)
+    }
+  })
+  if (problems.size === 0) return
+  const messages: string[] = []
+  const hints: string[] = []
+  for (const group of [...problems.keys()].sort()) {
+    const entry = problems.get(group) as { missing: string[]; unenforced: string[] }
+    const members = [...keys]
+      .filter(([, info]) => info.group === group)
+      .map(([key]) => key)
+      .sort()
+    const parts: string[] = []
+    if (entry.missing.length > 0) {
+      parts.push(
+        `${count(entry.missing.length)} ${entry.missing.length === 1 ? 'has' : 'have'} no "${group}" decision: ${entry.missing.join(', ')}`,
+      )
+      hints.push(
+        `Add a decision of the "${group}" group (${members.join(', ') || group}) to the resolver method or to its class`,
+      )
+    }
+    if (entry.unenforced.length > 0) {
+      parts.push(
+        `no guard enforces the "${group}" group on ${count(entry.unenforced.length)}: ${entry.unenforced.join(', ')}`,
+      )
+      hints.push(
+        `Register a GraphQL guard declaring \`static enforces\` with the decorators of the "${group}" group: GraphQLPlugin.configure({ guards: [...] }) or @UseGuard(...)`,
+      )
+    }
+    const message = parts.join('; ')
+    if (mode === 'warn') logger.warn(`GraphQLPlugin: ${message}`, { code: ErrorCode.MissingRouteDecision, group })
+    else messages.push(message)
+  }
+  if (mode === 'error') {
+    hints.push("Tests that deliberately run without guards can set enforcement: 'warn'")
+    const text = messages.join('; ')
+    throw new ZnightError(
+      ErrorCode.MissingRouteDecision,
+      `GraphQLPlugin: ${text.charAt(0).toUpperCase()}${text.slice(1)}`,
+      {
+        hints,
+      },
+    )
+  }
+}
+
+function count(fields: number): string {
+  return fields === 1 ? '1 field' : `${fields} fields`
+}

package/src/decorators.ts

@@ -0,0 +1,196 @@
+/**
+ * Marker decorators of `@znight/graphql` (RFC 0005 §5.14). Like every Znight decorator they do
+ * nothing at runtime: the compiler extension (`@znight/graphql/compiler`) reads them from the source
+ * code, derives the schema from the TypeScript types they reach and generates
+ * `metadata.extensions.graphql`. Arguments marked _static_ must be statically evaluable (literals,
+ * `const` references); _value_ arguments may also be references to exported bindings (schemas,
+ * guard classes). See docs/internals/architecture.md §4.6.
+ *
+ * Also here: `scalar<T>()`, the scalar aliases (`ID`, `Int`, `Float`, `JSONValue`) and `Loader<L>`,
+ * which shares its name with the `@Loader()` decorator (one identity, `@znight/graphql#Loader`, for
+ * the parameter decorator and the parameter type).
+ */
+import type { ClassMarker, MethodMarker, ParameterMarker, Scope } from '@znight/core'
+import type { StandardSchemaV1 } from '@znight/http'
+import type { GraphQLScalarType } from 'graphql'
+import type { BatchLoad, BatchLoader, GraphQLGuardClass, LoaderKey, LoaderValue, ScalarDefinition } from './types.ts'
+
+function marker(): void {
+  // intentionally empty: decorators are compile-time markers
+}
+
+const classMarker: ClassMarker = marker
+const methodMarker: MethodMarker = marker
+const parameterMarker: ParameterMarker = marker
+const classOrMethodMarker: ClassMarker & MethodMarker = marker
+
+/** GraphQL `ID`: a string on the wire and in TypeScript. Recognised by the compiler through the alias. */
+export type ID = string
+
+/** GraphQL `Int` (32-bit signed integer). A `number` in TypeScript; plain `number` maps to `Float`. */
+export type Int = number
+
+/** GraphQL `Float`. Same as `number`, for symmetry with {@link Int}. */
+export type Float = number
+
+/** Any JSON value: the `JSON` scalar. */
+export type JSONValue = string | number | boolean | null | readonly JSONValue[] | { readonly [key: string]: JSONValue }
+
+/**
+ * The DataLoader of the current execution for the loader provider `L`, injected with `@Loader()`:
+ * created on first use, cached for the operation (or for one subscription event), then dropped.
+ *
+ * ```ts
+ * @ResolveField()
+ * author(@Parent() book: Book, @Loader() authors: Loader<AuthorsById>): Promise<Author> {
+ *   return authors.load(book.authorId)
+ * }
+ * ```
+ */
+export type Loader<L extends BatchLoad<unknown, unknown>> = BatchLoader<LoaderKey<L>, LoaderValue<L>>
+
+/** Options of {@link Resolver} (static). */
+export interface ResolverOptions {
+  /** Provider scope. Default: `singleton`; `request` creates one resolver per operation. */
+  readonly scope?: Scope
+}
+
+/**
+ * Declares a resolver: a provider (singleton by default) whose `@Query`, `@Mutation`,
+ * `@Subscription` and `@ResolveField` methods are fields of the schema. Route decorators of
+ * `@znight/http` (`createRouteDecorator`) on the class are the default decisions of its fields.
+ *
+ * ```ts
+ * @Resolver()
+ * export class BookResolver {
+ *   constructor(private readonly catalog: CatalogService) {}
+ *
+ *   @Query()
+ *   book(@Args('id') id: ID): Promise<Book | null> {
+ *     return this.catalog.find(id)
+ *   }
+ * }
+ * ```
+ *
+ * @param options static: `{ scope? }`.
+ */
+export function Resolver(_options?: ResolverOptions): ClassMarker {
+  return classMarker
+}
+
+/**
+ * A field of the `Query` root type. The method's declared return type is the field type
+ * (`Promise<T>` unwrapped), its `@Args` the arguments, its JSDoc the description.
+ *
+ * @param name static: field name. Default: the method name.
+ */
+export function Query(_name?: string): MethodMarker {
+  return methodMarker
+}
+
+/**
+ * A field of the `Mutation` root type.
+ *
+ * @param name static: field name. Default: the method name.
+ */
+export function Mutation(_name?: string): MethodMarker {
+  return methodMarker
+}
+
+/**
+ * A field of the `Subscription` root type. The method returns an `AsyncIterable<T>` (an async
+ * generator, or `pubsub.subscribe(...)`), each value being the field value of one event.
+ *
+ * @param name static: field name. Default: the method name.
+ */
+export function Subscription(_name?: string): MethodMarker {
+  return methodMarker
+}
+
+/**
+ * A field resolver: adds a field to the type of the `@Parent()` parameter (mandatory), or replaces
+ * the property field of the same name.
+ *
+ * @param name static: field name. Default: the method name.
+ */
+export function ResolveField(_name?: string): MethodMarker {
+  return methodMarker
+}
+
+/**
+ * Field arguments. Without a name, the properties of the parameter type become arguments
+ * (`@Args() filter: BookFilter`); with a name, one argument (`@Args('id') id: ID`). With a Standard
+ * Schema, the value is validated (and transformed) after GraphQL coerced it; a failure is a
+ * `BAD_USER_INPUT` error listing the issues.
+ *
+ * @param name static: argument name.
+ * @param schema value: a Standard Schema validating the value (its output is injected).
+ */
+export function Args(): ParameterMarker
+export function Args(name: string, schema?: StandardSchemaV1): ParameterMarker
+export function Args(schema: StandardSchemaV1): ParameterMarker
+export function Args(_nameOrSchema?: string | StandardSchemaV1, _schema?: StandardSchemaV1): ParameterMarker {
+  return parameterMarker
+}
+
+/** The parent object of a field resolver (`@ResolveField` only; its type is the parent type). */
+export function Parent(): ParameterMarker {
+  return parameterMarker
+}
+
+/** The `GraphQLContext` of the operation. */
+export function Ctx(): ParameterMarker {
+  return parameterMarker
+}
+
+/** The graphql-js `GraphQLResolveInfo` of the call (escape hatch). */
+export function Info(): ParameterMarker {
+  return parameterMarker
+}
+
+/** The DataLoader of the current execution for the `Loader<L>` parameter type (see {@link Loader}). */
+export function Loader(): ParameterMarker {
+  return parameterMarker
+}
+
+/**
+ * Guards of the fields of a resolver class or of one field, run after the global guards (class
+ * guards, then method guards). Guards are providers implementing `GraphQLGuard`.
+ *
+ * @param guards value: guard classes.
+ */
+export function UseGuard(..._guards: [GraphQLGuardClass, ...GraphQLGuardClass[]]): ClassMarker & MethodMarker {
+  return classOrMethodMarker
+}
+
+/**
+ * Maps the TypeScript type `T` to the GraphQL scalar `name` wherever it appears. `name` is static;
+ * the returned definition must be exported (`export const`): the generated module imports it.
+ * Returns `definition` unchanged.
+ *
+ * ```ts
+ * export type EmailAddress = string & { readonly __brand: 'EmailAddress' }
+ *
+ * export const EmailAddressScalar = scalar<EmailAddress>('EmailAddress', {
+ *   serialize: value => value,
+ *   parseValue: value => {
+ *     if (typeof value !== 'string' || !value.includes('@')) throw new TypeError('Expected an e-mail address')
+ *     return value.toLowerCase() as EmailAddress
+ *   },
+ * })
+ *
+ * export const UrlScalar = scalar<URL>('URL', GraphQLURL) // a graphql-js GraphQLScalarType
+ * ```
+ *
+ * @param name static: the GraphQL name of the scalar.
+ * @param definition value: a {@link ScalarDefinition} or a graphql-js `GraphQLScalarType` (whose
+ *   name must be `name`, ZNIGHT066 at boot otherwise).
+ */
+export function scalar<T>(name: string, definition: ScalarDefinition<T>): ScalarDefinition<T>
+export function scalar<T>(name: string, definition: GraphQLScalarType): GraphQLScalarType<T>
+export function scalar<T>(
+  _name: string,
+  definition: ScalarDefinition<T> | GraphQLScalarType,
+): ScalarDefinition<T> | GraphQLScalarType {
+  return definition
+}

package/src/errors.ts

@@ -0,0 +1,89 @@
+/**
+ * GraphQL errors shown to clients (RFC 0005 §5.10, §8.8): `GraphQLException` and the
+ * `extensions.code` values the plugin produces (Apollo conventions, which clients already know).
+ *
+ * Import-free: the exception is a plain `Error` subclass, rendered by the runtime as
+ * `{ message, locations, path, extensions: { code, ...extensions } }`.
+ */
+
+/** `extensions.code` values produced by `@znight/graphql`. Applications may use their own codes too. */
+export const GraphQLErrorCode: {
+  /** The document does not parse (syntax error, `limits.maxTokens`). */
+  readonly ParseFailed: 'GRAPHQL_PARSE_FAILED'
+  /** The document is not valid against the schema. */
+  readonly ValidationFailed: 'GRAPHQL_VALIDATION_FAILED'
+  /** Invalid variables or arguments (Standard Schema issues in `extensions.issues`), HTTP 400. */
+  readonly BadUserInput: 'BAD_USER_INPUT'
+  /** The document exceeds `limits.maxDepth`, `maxAliases` or `maxDirectives`. */
+  readonly QueryTooComplex: 'QUERY_TOO_COMPLEX'
+  /** HTTP 401. */
+  readonly Unauthenticated: 'UNAUTHENTICATED'
+  /** A guard returned `false`, or HTTP 403. */
+  readonly Forbidden: 'FORBIDDEN'
+  /** HTTP 404, or a key missing from `orderByKeys`. */
+  readonly NotFound: 'NOT_FOUND'
+  /** HTTP 409. */
+  readonly Conflict: 'CONFLICT'
+  /** HTTP 429. */
+  readonly TooManyRequests: 'TOO_MANY_REQUESTS'
+  /** Any other HTTP 4xx. */
+  readonly BadRequest: 'BAD_REQUEST'
+  /** A subscriber fell behind its buffer: its stream ends with this error. */
+  readonly SubscriptionOverflow: 'SUBSCRIPTION_OVERFLOW'
+  /** Too many active subscriptions (`subscriptions.maxActive`), HTTP 503. */
+  readonly ServiceUnavailable: 'SERVICE_UNAVAILABLE'
+  /** An unexpected error, masked (`Unexpected error.`) unless `exposeErrors`. */
+  readonly InternalServerError: 'INTERNAL_SERVER_ERROR'
+} = Object.freeze({
+  ParseFailed: 'GRAPHQL_PARSE_FAILED',
+  ValidationFailed: 'GRAPHQL_VALIDATION_FAILED',
+  BadUserInput: 'BAD_USER_INPUT',
+  QueryTooComplex: 'QUERY_TOO_COMPLEX',
+  Unauthenticated: 'UNAUTHENTICATED',
+  Forbidden: 'FORBIDDEN',
+  NotFound: 'NOT_FOUND',
+  Conflict: 'CONFLICT',
+  TooManyRequests: 'TOO_MANY_REQUESTS',
+  BadRequest: 'BAD_REQUEST',
+  SubscriptionOverflow: 'SUBSCRIPTION_OVERFLOW',
+  ServiceUnavailable: 'SERVICE_UNAVAILABLE',
+  InternalServerError: 'INTERNAL_SERVER_ERROR',
+})
+
+/** One of the {@link GraphQLErrorCode} values. */
+export type GraphQLErrorCodeValue = (typeof GraphQLErrorCode)[keyof typeof GraphQLErrorCode]
+
+/** Options of {@link GraphQLException}. */
+export interface GraphQLExceptionOptions {
+  /** `extensions.code` (`'NOT_FOUND'`, `'CONFLICT'`, or an application code). */
+  readonly code: GraphQLErrorCodeValue | (string & Record<never, never>)
+  /** Extra `extensions` entries, sent to the client (`code` always wins). */
+  readonly extensions?: Readonly<Record<string, unknown>>
+  /**
+   * The original error: never sent, logged once at `error` level with the request id, the schema
+   * coordinate and the path when the exception is shown for a field.
+   */
+  readonly cause?: unknown
+}
+
+/**
+ * An error whose message and extensions are sent to the client as they are (§5.10): throw it from a
+ * resolver or return it from a `GraphQLErrorMapper`.
+ *
+ * ```ts
+ * throw new GraphQLException(`No book ${id}`, { code: 'NOT_FOUND', extensions: { bookId: id } })
+ * ```
+ */
+export class GraphQLException extends Error {
+  /** `extensions.code`. */
+  readonly code: string
+  /** Extra `extensions` entries. */
+  readonly extensions: Readonly<Record<string, unknown>> | undefined
+
+  constructor(message: string, options: GraphQLExceptionOptions) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'GraphQLException'
+    this.code = options.code
+    this.extensions = options.extensions
+  }
+}