@znight/graphql 0.0.0 → 0.2.1

package/src/type-ref.ts

@@ -0,0 +1,89 @@
+/**
+ * GraphQL type references as written in `metadata.extensions.graphql` (`'Book!'`, `'[Book!]!'`,
+ * `'[[Int]]'`): parsing and printing.
+ *
+ * Import-free: shared by the compiler extension (which prints them) and the runtime (which parses
+ * them once, at boot, to build the schema). The grammar is the canonical form graphql-js prints
+ * (`String(type)`): no whitespace, no comments, names matching `/^[_A-Za-z][_0-9A-Za-z]*$/`.
+ */
+
+/** A parsed type reference. */
+export type GraphQLTypeRef = NamedTypeRef | ListTypeRef
+
+/** A named type (`Book`, `Book!`). */
+export interface NamedTypeRef {
+  readonly kind: 'named'
+  readonly name: string
+  readonly nonNull: boolean
+}
+
+/** A list type (`[Book]`, `[Book!]!`). */
+export interface ListTypeRef {
+  readonly kind: 'list'
+  /** The item type. */
+  readonly of: GraphQLTypeRef
+  readonly nonNull: boolean
+}
+
+/** Result of one parsing step: the reference and the index after it. */
+interface Step {
+  readonly ref: GraphQLTypeRef
+  readonly end: number
+}
+
+/**
+ * Parses a type reference. Returns `undefined` when `text` is not a canonical reference, so that
+ * callers validating hand-written metadata can collect every problem before failing.
+ */
+export function parseTypeRef(text: string): GraphQLTypeRef | undefined {
+  const step = parseAt(text, 0)
+  return step !== undefined && step.end === text.length ? step.ref : undefined
+}
+
+/** Prints a type reference in its canonical form (the form graphql-js prints). */
+export function printTypeRef(ref: GraphQLTypeRef): string {
+  const inner = ref.kind === 'named' ? ref.name : `[${printTypeRef(ref.of)}]`
+  return ref.nonNull ? `${inner}!` : inner
+}
+
+/** The innermost type name of a reference (`'[Book!]!'` → `'Book'`), `undefined` when malformed. */
+export function namedTypeOf(ref: string | GraphQLTypeRef): string | undefined {
+  let current = typeof ref === 'string' ? parseTypeRef(ref) : ref
+  while (current !== undefined && current.kind === 'list') current = current.of
+  return current?.name
+}
+
+const OPEN_BRACKET = 0x5b // [
+const CLOSE_BRACKET = 0x5d // ]
+const BANG = 0x21 // !
+
+function parseAt(text: string, start: number): Step | undefined {
+  let ref: GraphQLTypeRef
+  let index: number
+  if (text.charCodeAt(start) === OPEN_BRACKET) {
+    const item = parseAt(text, start + 1)
+    if (item === undefined || text.charCodeAt(item.end) !== CLOSE_BRACKET) return undefined
+    index = item.end + 1
+    ref = { kind: 'list', of: item.ref, nonNull: false }
+  } else {
+    index = start
+    if (!isNameStart(text.charCodeAt(index))) return undefined
+    index++
+    while (isNameContinue(text.charCodeAt(index))) index++
+    ref = { kind: 'named', name: text.slice(start, index), nonNull: false }
+  }
+  if (text.charCodeAt(index) === BANG) {
+    return { ref: { ...ref, nonNull: true }, end: index + 1 }
+  }
+  return { ref, end: index }
+}
+
+/** `[_A-Za-z]`. `NaN` (past the end) is never a name character. */
+function isNameStart(code: number): boolean {
+  return code === 0x5f || (code >= 0x41 && code <= 0x5a) || (code >= 0x61 && code <= 0x7a)
+}
+
+/** `[_0-9A-Za-z]`. */
+function isNameContinue(code: number): boolean {
+  return isNameStart(code) || (code >= 0x30 && code <= 0x39)
+}

package/src/types.ts

@@ -0,0 +1,225 @@
+/**
+ * Type-level contracts of `@znight/graphql` (RFC 0005 §5.5, §5.8–§5.10, §7.1): what resolvers,
+ * guards, loaders and error mappers implement or receive. The runtime implements them; the compiler
+ * extension recognises some of them by identity (`compiler/ids.ts`).
+ *
+ * Types only: this module emits no code and imports types only (`graphql` and `@znight/http` are
+ * required peers), so both the runtime and the compiler extension may reference it.
+ */
+import type { Token } from '@znight/core'
+import type { GuardEnforcement, HttpContext, RouteMetaCarrier } from '@znight/http'
+import type { ConstValueNode, DocumentNode, GraphQLResolveInfo } from 'graphql'
+import type { GraphQLException } from './errors.ts'
+
+/** Arguments of a field, after GraphQL coercion (and null handling, §7.3), by argument name. */
+export type GraphQLArgs = Readonly<Record<string, unknown>>
+
+/** Kind of a GraphQL operation. */
+export type GraphQLOperationKind = 'query' | 'mutation' | 'subscription'
+
+/** How an operation reached the server: GraphQL over HTTP, GraphQL over SSE, or `plugin.execute()`. */
+export type GraphQLTransport = 'http' | 'sse' | 'direct'
+
+/**
+ * Options of a loader (§5.5), read once per loader class: the `options` property of a
+ * {@link BatchLoad} provider. They are DataLoader's, except `batchScheduleFn` (Znight batches per
+ * tick of the execution).
+ */
+export interface LoaderOptions<K = unknown> {
+  /** Largest number of keys passed to one `load()` call. Default: unlimited. */
+  readonly maxBatchSize?: number
+  /** Cache values per execution (by key). Default `true`. */
+  readonly cache?: boolean
+  /** Cache key of a key, for object keys (`key => key.id`). Default: the key itself. */
+  cacheKeyFn?(key: K): unknown
+}
+
+/**
+ * A batch loader (§5.5): a provider that loads many keys at once. Inject its per-execution
+ * DataLoader with `@Loader() authors: Loader<AuthorsById>`.
+ *
+ * ```ts
+ * @Injectable()
+ * export class AuthorsById implements BatchLoad<ID, Author> {
+ *   constructor(private readonly authors: AuthorRepository) {}
+ *
+ *   async load(ids: readonly ID[]): Promise<readonly (Author | Error)[]> {
+ *     return orderByKeys(ids, await this.authors.findMany(ids), author => author.id)
+ *   }
+ * }
+ * ```
+ */
+export interface BatchLoad<K, V> {
+  /**
+   * Loads the values of `keys`: one value (or an `Error` failing that key only) per key, in the
+   * order of the keys. Another number of values fails every key of the batch (ZNIGHT065).
+   */
+  load(keys: readonly K[]): Promise<readonly (V | Error)[]>
+  /** DataLoader options, read once per loader class. */
+  readonly options?: LoaderOptions<K>
+}
+
+/** Key type of a {@link BatchLoad} provider. */
+export type LoaderKey<L> = L extends { load(keys: readonly (infer K)[]): unknown } ? K : never
+
+/** Value type of a {@link BatchLoad} provider (`Error`s excluded). */
+export type LoaderValue<L> = L extends { load(keys: never): Promise<readonly (infer V)[]> } ? Exclude<V, Error> : never
+
+/**
+ * The DataLoader of one execution for a loader (§5.5): the part of the `dataloader` API resolvers
+ * use. `Loader<L>` (exported with the `@Loader()` decorator) is this view for the provider `L`.
+ */
+export interface BatchLoader<K, V> {
+  /** The value of `key`, batched with the other keys requested in the same tick. */
+  load(key: K): Promise<V>
+  /** The values of `keys`: a value or an `Error` per key, never a rejection. */
+  loadMany(keys: readonly K[]): Promise<(V | Error)[]>
+  /** Forgets the cached value of `key`. */
+  clear(key: K): this
+  /** Forgets every cached value. */
+  clearAll(): this
+  /** Caches a value for `key` (no effect when `key` is already cached). */
+  prime(key: K, value: V | PromiseLike<V> | Error): this
+}
+
+/** A class of {@link BatchLoad} providers. */
+export type BatchLoadClass<L extends BatchLoad<unknown, unknown> = BatchLoad<unknown, unknown>> = abstract new (
+  ...args: never[]
+) => L
+
+/**
+ * The context of one GraphQL operation (§5.8): a request-scoped external
+ * (`@znight/graphql#GraphQLContext`), injected with `@Ctx()` in resolvers, in request-scoped
+ * providers, or as `Lazy<GraphQLContext>` in singletons. It is not a bag for user data: the
+ * authenticated user is a request-scoped provider filled by a guard.
+ */
+export interface GraphQLContext {
+  /** Id of the request carrying the operation (`HttpContext.requestId` over HTTP). */
+  readonly requestId: string
+  readonly transport: GraphQLTransport
+  /** The HTTP request carrying the operation; `undefined` for `plugin.execute()`. */
+  readonly http: HttpContext | undefined
+  readonly operationType: GraphQLOperationKind
+  readonly operationName: string | undefined
+  /** The parsed (and validated) document, shared through the document cache: never mutate it. */
+  readonly document: DocumentNode
+  readonly variables: Readonly<Record<string, unknown>>
+  /**
+   * Over HTTP, the request's `ctx.signal` (RFC 0006): client gone, SSE stream closed on shutdown or
+   * `maxDuration`. Passed to graphql-js as `abortSignal`. Direct executions get the plugin's own.
+   * A subscription's also aborts when its stream ends (the source ended, or `return()`).
+   */
+  readonly signal: AbortSignal
+  /** Per-operation storage. */
+  readonly state: Map<string | symbol, unknown>
+  /** The DataLoader of the current execution for a loader class (`ctx.loader(AuthorsById)`). */
+  loader<L extends BatchLoad<unknown, unknown>>(loader: BatchLoadClass<L>): BatchLoader<LoaderKey<L>, LoaderValue<L>>
+  /**
+   * The DataLoader of the current execution for a loader provider token: what the generated
+   * `invoke` functions call (`c.loader('src/a.loader.ts#AuthorsById')`), with no class lookup.
+   */
+  loader(token: Token): BatchLoader<unknown, unknown>
+}
+
+/**
+ * What a {@link GraphQLGuard} receives for one resolver call (§5.9). It satisfies the
+ * `RouteMetaCarrier` of `@znight/http`, so route decorators read it: `Roles.get(ctx)`.
+ */
+export interface ResolverContext<TParent = unknown, TArgs extends GraphQLArgs = GraphQLArgs> extends RouteMetaCarrier {
+  /** Effective metadata of the field (method decisions over class decisions) and its schema coordinate. */
+  readonly route: {
+    readonly meta: Readonly<Record<string, unknown>>
+    /** `Query.books`, `Book.author`. */
+    readonly coordinate: string
+  }
+  /** The operation. */
+  readonly operation: GraphQLContext
+  /** Name of the type owning the field (`Query`, `Book`). */
+  readonly parentType: string
+  /** Name of the field. */
+  readonly field: string
+  readonly args: TArgs
+  /** The parent object (`undefined` for root fields, unless a root value is configured). */
+  readonly parent: TParent
+  readonly info: GraphQLResolveInfo
+  /** `operation.http`. */
+  readonly http: HttpContext | undefined
+}
+
+/**
+ * A guard of GraphQL fields (§5.9). Guards run global (plugin option) → class `@UseGuard` → method
+ * `@UseGuard`; `false` fails the field with a `FORBIDDEN` error, a thrown error is mapped (§5.10).
+ * One class may also implement `CanActivate` (HTTP routes).
+ */
+export interface GraphQLGuard {
+  canResolve(ctx: ResolverContext): boolean | Promise<boolean>
+}
+
+/** A class producing {@link GraphQLGuard}s, with the route decorators it enforces (`static enforces`). */
+export type GraphQLGuardClass = (abstract new (...args: never[]) => GraphQLGuard) & GuardEnforcement
+
+/**
+ * Converts application errors to GraphQL errors (§5.10). Mappers are tried in order for every
+ * error of `errors[]` that is not a `GraphQLException` already; the first one returning an
+ * exception wins, `undefined` passes. Synchronous: errors are formatted once the execution
+ * finished, without an extra await per error.
+ */
+export interface GraphQLErrorMapper {
+  map(error: unknown, ctx: GraphQLContext): GraphQLException | undefined
+}
+
+/** 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`,
+ * `parseValue` → `coerceInputValue`, `parseLiteral` → `coerceInputLiteral` (the deprecated
+ * graphql-js names are never passed on).
+ */
+export interface ScalarDefinition<T> {
+  readonly description?: string
+  /** URL of the specification of the scalar (`@specifiedBy`). */
+  readonly specifiedByURL?: string
+  /** Internal value → response value. */
+  serialize(value: T): unknown
+  /** Variable value (JSON) → internal value; throw to reject it. */
+  parseValue(value: unknown): T
+  /** Literal of the document → internal value. Default: `parseValue` of the literal's JSON value. */
+  parseLiteral?(literal: ConstValueNode): T
+}

package/src/validate-args.ts

@@ -0,0 +1,48 @@
+/**
+ * `validateArgs()`: Standard Schema validation of resolver arguments (RFC 0005 §5.4, §7.3), called
+ * by the generated `invoke` functions (README, "Compiler contract").
+ */
+import type { InferSchemaOutput, StandardSchemaV1, StandardSchemaV1Result } from '@znight/http'
+
+import { isThenable, toIssueDetail } from '@znight/http'
+
+import { GraphQLErrorCode, GraphQLException } from './errors.ts'
+
+/**
+ * Validates an argument value (after GraphQL coercion) with a [Standard Schema](https://standardschema.dev)
+ * (Zod, Valibot, ArkType...) and returns the schema **output** (transforms run, defaults applied).
+ *
+ * Synchronous when the schema validates synchronously (no promise, no microtask), a promise
+ * otherwise: generated code `await`s the result, which is free for a plain value.
+ *
+ * @param label what is validated, for the message: the argument name (`'input'`), or `'arguments'`
+ *   for `@Args(Schema)` without name.
+ * @throws GraphQLException `BAD_USER_INPUT`, `extensions.issues: [{ path, message }]`, when the
+ *   value is invalid.
+ * @throws TypeError when `schema` is not a Standard Schema v1 (a programming error, masked).
+ */
+export function validateArgs<S extends StandardSchemaV1>(
+  schema: S,
+  value: unknown,
+  label: string,
+): InferSchemaOutput<S> | Promise<InferSchemaOutput<S>> {
+  const props =
+    schema !== null && (typeof schema === 'object' || typeof schema === 'function')
+      ? (schema as { readonly '~standard'?: { readonly version?: unknown; readonly validate?: unknown } })['~standard']
+      : undefined
+  if (props === null || typeof props !== 'object' || props.version !== 1 || typeof props.validate !== 'function') {
+    throw new TypeError(`The schema of ${label} is not a Standard Schema v1 (missing "~standard.validate")`)
+  }
+  const result = (props.validate as (value: unknown) => StandardSchemaV1Result<InferSchemaOutput<S>>)(value)
+  // sync fast path: most schemas validate synchronously
+  if (isThenable(result)) return Promise.resolve(result).then(settled => unwrap(settled, label))
+  return unwrap(result, label)
+}
+
+function unwrap<T>(result: StandardSchemaV1Result<T>, label: string): T {
+  if (result.issues === undefined) return result.value
+  throw new GraphQLException(`Invalid ${label}`, {
+    code: GraphQLErrorCode.BadUserInput,
+    extensions: { issues: result.issues.map(toIssueDetail) },
+  })
+}