@znight/graphql 0.3.0 → 0.5.0

package/src/compiler/generate.ts

@@ -13,7 +13,7 @@
  * ```
  */
 
-import type { GenerateContext, GenInput, GenNode, GenParam } from '@znight/compiler'
+import type { ClassRef, GenerateContext, GenInput, GenNode, GenParam, StaticValue, ValueRef } from '@znight/compiler'
 import type { Token } from '@znight/core'
 import type { MetaEntry } from '@znight/http/compiler'
 import type { FieldData, GraphQLData, ParamData, ResolverData } from './data.ts'
@@ -34,6 +34,8 @@ interface Imports {
   argsType(): GenNode
   contextType(): GenNode
   infoType(): GenNode
+  resolverContextType(): GenNode
+  paramFunctionOf(): GenNode
   validateArgs(): GenNode
   isThenable(): GenNode
   hostType(identity: string): GenNode
@@ -63,6 +65,8 @@ function createImports(ctx: Context): Imports {
   let args: GenNode | undefined
   let context: GenNode | undefined
   let info: GenNode | undefined
+  let resolverContext: GenNode | undefined
+  let paramFunctionOf: GenNode | undefined
   let validateArgs: GenNode | undefined
   let isThenable: GenNode | undefined
   const hosts = new Map<string, GenNode>()
@@ -79,6 +83,14 @@ function createImports(ctx: Context): Imports {
       info ??= ctx.importFrom('graphql', 'GraphQLResolveInfo', { type: true })
       return info
     },
+    resolverContextType: () => {
+      resolverContext ??= ctx.importFrom(RUNTIME_MODULE, 'ResolverContext', { type: true })
+      return resolverContext
+    },
+    paramFunctionOf: () => {
+      paramFunctionOf ??= ctx.importFrom('@znight/core', 'ParamFunctionOf', { type: true })
+      return paramFunctionOf
+    },
     validateArgs: () => {
       validateArgs ??= ctx.importFrom(RUNTIME_MODULE, 'validateArgs')
       return validateArgs
@@ -208,7 +220,13 @@ function resolverNode(ctx: Context, imports: Imports, resolver: ResolverData, fi
   ]
   const loaders = field.params.flatMap(param => (param?.kind === 'loader' ? [loaderToken(ctx, param)] : []))
   if (loaders.length > 0) entries.push(['loaders', ctx.lit(loaders)])
-  entries.push(['invoke', invokeNode(ctx, imports, resolver, field)])
+  // custom parameters (RFC 0010): the pipeline builds the ResolverContext and resolves the class resolvers
+  const resolvers = paramResolvers(field)
+  if (field.params.some(param => param?.kind === 'custom')) entries.push(['context', ctx.lit(true)])
+  if (resolvers.length > 0) {
+    entries.push(['paramResolvers', ctx.lit(resolvers.map(ref => ctx.tokenOf(ref) ?? ref.token))])
+  }
+  entries.push(['invoke', invokeNode(ctx, imports, resolver, field, resolvers)])
   return ctx.obj(entries)
 }
 
@@ -222,14 +240,31 @@ function loaderToken(ctx: Context, param: Extract<ParamData, { kind: 'loader' }>
 
 // ------------------------------------------------------------------------------------------- invoke
 
-/** Which `invoke` parameters a field uses: `(r, p, a, c, i)`. */
-function usedParameters(field: FieldData): readonly [p: boolean, a: boolean, c: boolean, i: boolean] {
+/** The provider classes resolving custom parameters, in order of first use (`x[i]`). */
+function paramResolvers(field: FieldData): ClassRef[] {
+  const found = new Map<string, ClassRef>()
+  for (const param of field.params) {
+    const resolver = param?.kind === 'custom' ? param.resolver : undefined
+    if (resolver !== undefined && !found.has(resolver.token)) found.set(resolver.token, resolver)
+  }
+  return [...found.values()]
+}
+
+/** Which `invoke` parameters a field uses: `(r, p, a, c, i, f, x)`. */
+function usedParameters(field: FieldData): readonly boolean[] {
   let p = false
   let a = false
   let c = false
   let i = false
+  let f = false
+  let x = false
   for (const param of field.params) {
     switch (param?.kind) {
+      case 'custom':
+        // a class resolver whose `resolve()` takes no parameter does not read `f`
+        f ||= param.resolver === undefined || param.arity !== 0
+        x ||= param.resolver !== undefined
+        break
       case 'parent':
         p = true
         break
@@ -245,39 +280,73 @@ function usedParameters(field: FieldData): readonly [p: boolean, a: boolean, c:
         break
     }
   }
-  return [p, a, c, i]
+  return [p, a, c, i, f, x]
 }
 
 /**
  * `(r: Resolver, p: unknown, a: GraphQLArgs, c: GraphQLContext, i: GraphQLResolveInfo) => r.m(...)`:
  * unused middle parameters are `_`-prefixed, trailing ones omitted (`noUnusedParameters`).
  */
-function invokeNode(ctx: Context, imports: Imports, resolver: ResolverData, field: FieldData): GenNode {
+function invokeNode(
+  ctx: Context,
+  imports: Imports,
+  resolver: ResolverData,
+  field: FieldData,
+  resolvers: readonly ClassRef[],
+): GenNode {
   const used = usedParameters(field)
   const last = used.lastIndexOf(true)
-  const types = [() => ctx.code`unknown`, imports.argsType, imports.contextType, imports.infoType]
-  const names = ['p', 'a', 'c', 'i']
+  const types = [
+    () => ctx.code`unknown`,
+    imports.argsType,
+    imports.contextType,
+    imports.infoType,
+    imports.resolverContextType,
+    () =>
+      tupleType(
+        ctx,
+        resolvers.map(ref => ctx.importType(ref)),
+      ),
+  ]
+  const names = ['p', 'a', 'c', 'i', 'f', 'x']
   const params: [string, GenNode][] = [['r', imports.hostType(resolver.host.identity)]]
   for (let index = 0; index <= last; index++) {
     params.push([`${used[index] ? '' : '_'}${names[index] as string}`, (types[index] as () => GenNode)()])
   }
-  const validated = field.params.flatMap((param, index) =>
-    param?.kind === 'args' && param.schema !== undefined ? [index] : [],
-  )
+  const deferred = field.params.flatMap((param, index) => (param !== undefined && isDeferred(param) ? [index] : []))
+  const positions = new Map(resolvers.map((ref, position) => [ref.token, position]))
   return ctx.arrow(params, (r, ...rest) => {
-    const [p, a, c, i] = rest as (GenParam | undefined)[]
-    const scope: Scope = { p, a, c, i }
-    if (validated.length === 0) return call(ctx, r, field, index => argument(ctx, scope, field, index))
-    return validatingBlock(ctx, imports, r, scope, field, validated)
+    const [p, a, c, i, f, x] = rest as (GenParam | undefined)[]
+    const scope: Scope = { p, a, c, i, f, x, resolvers: positions, imports }
+    if (deferred.length === 0) return call(ctx, r, field, index => argument(ctx, scope, field, index))
+    return validatingBlock(ctx, imports, r, scope, field, deferred)
   })
 }
 
+/** `readonly [A, B]`. */
+function tupleType(ctx: Context, nodes: readonly GenNode[]): GenNode {
+  const joined = nodes.slice(1).reduce((all, node) => ctx.code`${all}, ${node}`, nodes[0] as GenNode)
+  return ctx.code`readonly [${joined}]`
+}
+
+/** An argument whose expression may return a thenable: a validated `@Args`, or a custom parameter. */
+function isDeferred(param: ParamData): boolean {
+  return (param.kind === 'args' && param.schema !== undefined) || param.kind === 'custom'
+}
+
 /** The parameters of the `invoke` arrow (absent when not declared). */
 interface Scope {
   readonly p: GenNode | undefined
   readonly a: GenNode | undefined
   readonly c: GenNode | undefined
   readonly i: GenNode | undefined
+  /** The `ResolverContext` of custom parameters. */
+  readonly f: GenNode | undefined
+  /** The class resolver instances (`x[i]`). */
+  readonly x: GenNode | undefined
+  /** Position of each class resolver token in `x`. */
+  readonly resolvers: ReadonlyMap<string, number>
+  readonly imports: Imports
 }
 
 /** `r.method(args)`. */
@@ -302,11 +371,62 @@ function argument(ctx: Context, scope: Scope, field: FieldData, index: number):
       return ctx.code`${ctx.call(ctx.member(scope.c as GenNode, 'loader'), [loaderToken(ctx, param)])} as never`
     case 'args':
       return ctx.code`${argsValue(ctx, scope, param.name)} as never`
+    case 'custom':
+      return customArgument(ctx, scope, param)
     default:
       return ctx.lit(undefined)
   }
 }
 
+/**
+ * A custom parameter (RFC 0010): `(D.resolvers.graphql as ParamFunctionOf<typeof D, 'graphql'>)(f, data)`
+ * or `x[i].resolve(f, data)`, cast with `as never` when the value type could not be checked.
+ */
+function customArgument(ctx: Context, scope: Scope, param: Extract<ParamData, { kind: 'custom' }>): GenNode {
+  const f = scope.f as GenNode
+  const data = param.data === undefined ? ctx.lit(undefined) : dataNode(ctx, param.data.value)
+  let node: GenNode
+  if (param.resolver === undefined) {
+    const decorator = ctx.importValue(param.identity)
+    const type = ctx.code`${scope.imports.paramFunctionOf()}<typeof ${decorator}, 'graphql'>`
+    node = ctx.call(ctx.code`${ctx.member(decorator, 'resolvers', 'graphql')} as ${type}`, [f, data])
+  } else {
+    const position = scope.resolvers.get(param.resolver.token) as number
+    if (param.arity === undefined) {
+      // a `resolve` the compiler cannot read (inherited from a mixin...): the instance is cast to a
+      // method taking both arguments (method parameters are bivariant), the value with `as never`
+      return ctx.code`(${scope.x as GenNode}[${position}] as { resolve(ctx: unknown, data: unknown): unknown }).resolve(${f}, ${data}) as never`
+    }
+    // a `resolve(ctx)` that ignores the data gets no data argument (TypeScript checks the arity)
+    const arity = Math.min(param.arity, 2)
+    let args = ctx.code``
+    if (arity === 1) args = f
+    else if (arity === 2) args = ctx.code`${f}, ${data}`
+    node = ctx.code`${scope.x as GenNode}[${position}].resolve(${args})`
+  }
+  return param.cast ? ctx.code`${node} as never` : node
+}
+
+/** The data argument of a custom parameter: a literal (references imported) or a reference. */
+function dataNode(ctx: Context, value: StaticValue): GenNode {
+  return isValueRef(value) ? ctx.ref(value as ValueRef) : ctx.lit(value as never)
+}
+
+/** `true` for a {@link ValueRef} (the only non-plain object a static value can hold). */
+function isValueRef(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype !== Object.prototype && prototype !== null && (value as { kind?: unknown }).kind === 'ref'
+}
+
+/** The expression of a deferred parameter (validation or custom resolver), before any `await`. */
+function deferredValue(ctx: Context, imports: Imports, scope: Scope, field: FieldData, index: number): GenNode {
+  const param = field.params[index] as ParamData
+  return param.kind === 'custom'
+    ? customArgument(ctx, scope, param)
+    : validation(ctx, imports, scope, param as Extract<ParamData, { kind: 'args' }>)
+}
+
 /** `a['name']`, or `a` for `@Args()`. */
 function argsValue(ctx: Context, scope: Scope, name: string | undefined): GenNode {
   const a = scope.a as GenNode
@@ -356,8 +476,7 @@ function validatingBlock(
       const statements: GenNode[] = []
       for (const index of validated) {
         const name = local.get(index) as GenNode
-        const param = field.params[index] as Extract<ParamData, { kind: 'args' }>
-        statements.push(ctx.code`const ${name} = ${validation(ctx, imports, scope, param)}`)
+        statements.push(ctx.code`const ${name} = ${deferredValue(ctx, imports, scope, field, index)}`)
         const resume = ctx.arrow(
           [],
           () =>
@@ -366,8 +485,7 @@ function validatingBlock(
               if (value === undefined) return argument(ctx, scope, field, position)
               if (position < index) return ctx.code`${value} as never`
               if (position === index) return ctx.code`await ${value} as never`
-              const later = field.params[position] as Extract<ParamData, { kind: 'args' }>
-              return ctx.code`await ${validation(ctx, imports, scope, later)} as never`
+              return ctx.code`await ${deferredValue(ctx, imports, scope, field, position)} as never`
             }),
           { async: true },
         )

package/src/metadata.ts

@@ -12,7 +12,7 @@
 import type { Token } from '@znight/core'
 import type { HttpRouteGroupDefinition } from '@znight/http'
 import type { GraphQLResolveInfo, GraphQLScalarType } from 'graphql'
-import type { GraphQLArgs, GraphQLContext, ScalarDefinition } from './types.ts'
+import type { GraphQLArgs, GraphQLContext, ResolverContext, ScalarDefinition } from './types.ts'
 
 /** Format version of `metadata.extensions.graphql` (another version is ZNIGHT066 at boot). */
 export const GRAPHQL_METADATA_VERSION = 1
@@ -201,18 +201,34 @@ export interface GraphQLResolverBinding {
   readonly meta: Readonly<Record<string, unknown>>
   /** Informational: loader provider tokens the method injects. */
   readonly loaders?: readonly Token[]
+  /**
+   * The method has custom parameters (`createParamDecorator`, RFC 0010): the pipeline passes the
+   * field's `ResolverContext` to `invoke` (`f`). Absent otherwise.
+   */
+  readonly context?: true
+  /**
+   * Provider classes resolving custom parameters (`ParamResolver`), in order of first use: the
+   * pipeline resolves them in the operation scope and passes the instances to `invoke` (`x`).
+   * Absent when there is none.
+   */
+  readonly paramResolvers?: readonly Token[]
   /**
    * Calls the method: maps the graphql-js arguments to the method parameters (§7.3). Synchronous
-   * unless an argument is validated with a Standard Schema.
+   * unless an argument is validated with a Standard Schema or a custom parameter resolver returns a
+   * promise. `field` and `resolvers` are passed only to methods with custom parameters (declared as
+   * a method so that a generated invoke requiring them is accepted).
    */
-  readonly invoke: (
+  invoke(
     // biome-ignore lint/suspicious/noExplicitAny: generated invokers receive the concrete resolver class
     resolver: any,
     parent: unknown,
     args: GraphQLArgs,
     context: GraphQLContext,
     info: GraphQLResolveInfo,
-  ) => unknown
+    field?: ResolverContext,
+    // biome-ignore lint/suspicious/noExplicitAny: generated invokers receive the tuple of resolver classes
+    resolvers?: any,
+  ): unknown
 }
 
 declare module '@znight/core' {

package/src/pipeline.ts

@@ -45,6 +45,8 @@ export interface PipelineOptions {
   readonly guard: (token: Token, coordinate: string) => Resolvable<GraphQLGuard>
   /** The resolver provider of a binding (memoised by the caller). */
   readonly resolver: (binding: GraphQLResolverBinding, coordinate: string) => Resolvable<object>
+  /** The provider of a custom parameter resolver class (RFC 0010; memoised by the caller). */
+  readonly paramResolver?: (token: Token, coordinate: string) => Resolvable<object>
   /** Input object types by name (null handling of nested input values). */
   readonly inputs: ReadonlyMap<string, GraphQLInputTypeDefinition>
   /** The {@link Recover} function of a field that carries results (RFC 0008), `undefined` for the others. */
@@ -52,7 +54,15 @@ export interface PipelineOptions {
 }
 
 /** The generated invoker of a binding. */
-type Invoke = GraphQLResolverBinding['invoke']
+type Invoke = (
+  resolver: object,
+  parent: unknown,
+  args: GraphQLArgs,
+  context: GraphQLContext,
+  info: GraphQLResolveInfo,
+  field?: ResolverContext,
+  resolvers?: readonly object[],
+) => unknown
 
 /** Mutates a coerced argument or input value in place: `null` → `undefined` where flagged. */
 type Normalize = (value: unknown) => void
@@ -78,7 +88,6 @@ function fieldFunctions(
   parent: GraphQLObjectTypeDefinition,
 ): FieldFunctions {
   const container = options.container
-  const invoke: Invoke = binding.invoke
   const target = options.resolver(binding, coordinate)
   const guards: Resolvable<GraphQLGuard>[] = [
     ...(globalGuardsApply(binding) ? options.globalGuards : []),
@@ -86,10 +95,16 @@ function fieldFunctions(
   ]
   const normalize = field.args === undefined ? undefined : normalizers.args(field.args)
   const recover = options.results?.(field, coordinate)
+  const custom = binding.context === true
   const route =
-    guards.length === 0 && recover === undefined ? undefined : Object.freeze({ meta: binding.meta, coordinate })
+    guards.length === 0 && recover === undefined && !custom
+      ? undefined
+      : Object.freeze({ meta: binding.meta, coordinate })
   const parentType = parent.name
   const fieldName = field.name
+  const invoke: Invoke = custom
+    ? customInvoke(options, binding, coordinate, route as ResolverContext['route'], parentType, fieldName)
+    : (binding.invoke as Invoke)
 
   let resolve: GraphQLFieldResolver<unknown, unknown>
   if (guards.length === 0) {
@@ -120,15 +135,21 @@ function fieldFunctions(
     resolve = (p, a, c, i) => {
       const operation = c as OperationContext
       const args = a as GraphQLArgs
-      const allowed = runGuards(
-        container,
-        guards,
-        new FieldContext(route as ResolverContext['route'], operation, parentType, fieldName, args, p, i),
+      const fieldContext = new FieldContext(
+        route as ResolverContext['route'],
+        operation,
+        parentType,
+        fieldName,
+        args,
+        p,
+        i,
       )
-      // §8.5: guards (they see the coerced arguments), then null handling, then invoke
+      const allowed = runGuards(container, guards, fieldContext)
+      // §8.5: guards (they see the coerced arguments), then null handling, then invoke (custom
+      // parameters share the guards' ResolverContext)
       const call = (): unknown => {
         if (normalize !== undefined) normalize(args)
-        return invoke(resolveIn(container, target), p, args, operation, i)
+        return invoke(resolveIn(container, target), p, args, operation, i, fieldContext)
       }
       if (allowed === true) return call()
       if (allowed === false) return forbidden()
@@ -150,6 +171,48 @@ function identity(payload: unknown): unknown {
   return payload
 }
 
+/**
+ * The invoke of a method with custom parameters (RFC 0010): the generated `invoke` receives the
+ * field's `ResolverContext` (the guards' one when the field has guards, else a new one) and the
+ * instances of its parameter resolvers: one frozen array resolved at boot when they are all
+ * singletons, otherwise resolved in the operation scope on every call.
+ */
+function customInvoke(
+  options: PipelineOptions,
+  binding: GraphQLResolverBinding,
+  coordinate: string,
+  route: ResolverContext['route'],
+  parentType: string,
+  fieldName: string,
+): Invoke {
+  const generated = binding.invoke as Invoke
+  const container = options.container
+  const tokens = binding.paramResolvers ?? []
+  const resolvers = tokens.map(token => {
+    if (options.paramResolver === undefined) throw new TypeError(`No parameter resolver for ${coordinate}`)
+    return options.paramResolver(token, coordinate)
+  })
+  const context = (p: unknown, a: GraphQLArgs, c: GraphQLContext, i: GraphQLResolveInfo, f?: ResolverContext) =>
+    f ?? new FieldContext(route, c as OperationContext, parentType, fieldName, a, p, i)
+  if (resolvers.length === 0) {
+    return (r, p, a, c, i, f) => generated(r, p, a, c, i, context(p, a, c, i, f))
+  }
+  if (resolvers.every(resolver => resolver.token === undefined)) {
+    const instances = Object.freeze(resolvers.map(resolver => resolveIn(container, resolver)))
+    return (r, p, a, c, i, f) => generated(r, p, a, c, i, context(p, a, c, i, f), instances)
+  }
+  return (r, p, a, c, i, f) =>
+    generated(
+      r,
+      p,
+      a,
+      c,
+      i,
+      context(p, a, c, i, f),
+      resolvers.map(resolver => resolveIn(container, resolver)),
+    )
+}
+
 /**
  * The resolve function of a field that carries results (RFC 0008): errors of the whole pipeline
  * (guards, null handling, `invoke`), thrown or rejected, go through `recover`. Synchronous results

package/src/plugin.ts

@@ -493,6 +493,8 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
         guard: (token, coordinate) => providers.token<GraphQLGuard>(token, `guard of ${coordinate}`, 'canResolve'),
         resolver: (binding, coordinate) =>
           providers.token<object>(binding.token, `resolver of ${coordinate}`, binding.method),
+        paramResolver: (token, coordinate) =>
+          providers.token<object>(token, `parameter resolver of ${coordinate}`, 'resolve'),
         inputs,
         results: (field, coordinate) => results.recover(field, coordinate),
       }),

package/src/types.ts

@@ -131,9 +131,17 @@ export interface GraphQLContext {
   loader(token: Token): BatchLoader<unknown, unknown>
 }
 
+declare module '@znight/core' {
+  /** Custom parameter decorators (`createParamDecorator`) resolve GraphQL parameters from the {@link ResolverContext}. */
+  interface ParamContexts {
+    graphql: ResolverContext
+  }
+}
+
 /**
- * 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)`.
+ * What a {@link GraphQLGuard} receives for one resolver call (§5.9), and the context of custom
+ * parameter resolvers (RFC 0010). 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. */