@znight/graphql 0.2.2 → 0.4.0

package/README.md

@@ -44,7 +44,8 @@ npm install -D @znight/compiler vite
 
 Runs on Node.js >= 24 and Bun >= 1.3 (ESM only). `@znight/http` and `graphql` 17 are required peer
 dependencies, `dataloader` is a dependency, `@znight/testing` an optional peer (for
-`@znight/graphql/testing`).
+`@znight/graphql/testing`), `graphql-yoga` 6 an optional peer (for the Yoga driver,
+`@znight/graphql/yoga`).
 
 ## Contents
 
@@ -61,6 +62,7 @@ dependencies, `dataloader` is a dependency, `@znight/testing` an optional peer (
   - [Errors as data](#errors-as-data)
 - [Plugin options](#plugin-options)
 - [GraphQL over HTTP and SSE](#graphql-over-http-and-sse)
+- [Drivers and the engine](#drivers-and-the-engine)
 - [Security defaults and limits](#security-defaults-and-limits)
 - [Testing](#testing)
 - [The generated SDL and the compiler options](#the-generated-sdl-and-the-compiler-options)
@@ -521,13 +523,14 @@ Built-in scalars appear in the schema only when used: `String`, `Float`, `Int`,
 | Member                            | What                                                                                                                 |
 | --------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
 | `requestId`                       | Id of the request carrying the operation (`HttpContext.requestId` over HTTP, a UUID or `requestId` option otherwise) |
-| `transport`                       | `'http'`, `'sse'` or `'direct'` (`plugin.execute()` / `subscribe()`)                                                 |
+| `transport`                       | `'http'`, `'sse'` or `'direct'` (`plugin.execute()` / `subscribe()`); `'ws'` is reserved for `graphql-ws`            |
 | `http`                            | The `HttpContext` of the request, `undefined` for direct executions outside a request                                |
 | `operationType` / `operationName` | `'query'`, `'mutation'` or `'subscription'`; the selected operation name                                             |
 | `document` / `variables`          | The parsed document (shared by the document cache: never mutate it) and the coerced variables                        |
 | `signal`                          | Over HTTP, the request's `ctx.signal`: client gone, SSE stream closed; passed to graphql-js as `abortSignal`         |
 | `state`                           | A `Map` for per-operation storage                                                                                    |
 | `loader(Class \| token)`          | The DataLoader of the current execution for a loader                                                                 |
+| `serverContext`                   | With a [driver](#drivers-and-the-engine), the context its server gave the engine; `undefined` otherwise              |
 
 - Resolvers receive it with `@Ctx()`; request-scoped providers inject `GraphQLContext`, singletons
   `Lazy<GraphQLContext>`, exactly like `HttpContext`.
@@ -537,6 +540,32 @@ Built-in scalars appear in the schema only when used: `String`, `Float`, `Int`,
   `plugin.execute()` and `plugin.subscribe()` run in the current scope when one is active (a
   controller calling GraphQL), otherwise in a scope of their own.
 
+### Custom parameter decorators
+
+A decorator defined with `createParamDecorator` (`@znight/core`, RFC 0010) works on resolver
+methods when it has a `graphql` resolver, which receives the field's `ResolverContext` (`parent`,
+`args`, `info`, `operation`, `http`, `route.meta`). One definition serves HTTP routes and GraphQL
+fields:
+
+```ts
+import { createParamDecorator } from '@znight/core'
+import type { User } from './user.ts'
+
+export const CurrentUser = createParamDecorator<User>({
+  http: ctx => ctx.state.get('user') as User,
+  graphql: ctx => ctx.operation.state.get('user') as User,
+})
+
+// @Query() me(@CurrentUser() user: User): User { return user }
+```
+
+The resolver runs after the guards (it sees what they stored) and before the method; what it
+throws fails the field like the method would (`errors[]`, or a result mapper). A custom parameter
+is not a GraphQL argument: it never appears in the schema. Resolver classes implementing
+`ParamResolver` are resolved in the operation scope. Custom parameters belong to the field
+resolvers of the schema, so they work the same through the built-in transport, `plugin.execute()`
+and a driver such as `yogaDriver()` (RFC 0009).
+
 ## Authorization
 
 The route decorators of `@znight/http` (`createRouteDecorator`, with RFC 0001's groups) apply to
@@ -786,12 +815,13 @@ ZNIGHT066.
 | `resultMappers` | `[]`                                                                   | `GraphQLResultMapper` classes or instances, tried in order: errors as data on the fields whose union holds one of their `types` ([Errors as data](#errors-as-data))      |
 | `exposeErrors`  | `false`                                                                | Unmasked messages for unexpected errors (development)                                                                                                                    |
 | `introspection` | `NODE_ENV !== 'production'`                                            | Off: graphql-js `NoSchemaIntrospectionCustomRule`, and suggestions are hidden                                                                                            |
-| `graphiql`      | `NODE_ENV === 'development'`                                           | `GET path` with `accept: text/html` serves GraphiQL                                                                                                                      |
+| `graphiql`      | `NODE_ENV === 'development'`                                           | `GET path` with `accept: text/html` serves GraphiQL; with a `driver`, the driver's IDE                                                                                   |
 | `limits`        | `{ maxTokens: 2000, maxDepth: 12, maxAliases: 30, maxDirectives: 50 }` | Request limits (introspection fields exempt from `maxDepth`); `false` disables one                                                                                       |
 | `documentCache` | `1000`                                                                 | Distinct documents kept parsed and validated (LRU); `0` disables                                                                                                         |
 | `subscriptions` | `{ maxActive: 10_000, bufferSize: 100 }`                               | `false` disables subscriptions over SSE. `heartbeat` (ms or `false`) and `maxDuration` (ms) are passed to `HttpResponse.sse()` (default: the `HttpPlugin` `sse` options) |
 | `pubsub`        | a `MemoryPubSub`                                                       | The `PubSub` provided to the container                                                                                                                                   |
 | `enforcement`   | `'error'`                                                              | How the boot check of field decisions reports a problem: `'error'` fails the boot (ZNIGHT023), `'warn'` logs                                                             |
+| `driver`        | the built-in transport                                                 | The GraphQL server serving the schema ([Drivers and the engine](#drivers-and-the-engine)); `heartbeat` and `maxDuration` are refused with one (ZNIGHT066)                |
 
 `HttpPlugin` must be registered unless `http: false` (ZNIGHT066). The plugin instance exposes:
 
@@ -803,14 +833,15 @@ ZNIGHT066.
 | `subscribe(request, options?)` | A stream of results, one per event, until the source ends, `options.signal` aborts, `return()` is called or the application stops |
 | `pubsub`                       | The `PubSub` of the application                                                                                                   |
 | `activeSubscriptions`          | Active subscriptions, every transport                                                                                             |
-| `initRoots()` / `httpRoutes()` | The `PluginInitRoots` contract (`TestApp`) and the `PluginHttpRoutes` contract of `@znight/http`                                  |
+| `engine`                       | The `GraphQLEngine` drivers call (after bootstrap): [Drivers and the engine](#drivers-and-the-engine)                             |
+| `initRoots()` / `httpRoutes()` | The `PluginInitRoots` contract (`TestApp`) and the `PluginHttpRoutes` contract of `@znight/http`, `onHttpDrain()` included        |
 
 `request` is `{ query, operationName?, variables?, extensions? }`; `options` is `{ signal?,
 requestId? }`. A direct execution has no HTTP guards of its own: inside a controller, it runs in the
 route's request scope, after the route's guards. With `http: false`, a controller can hand its
-requests to another GraphQL server that delegates the execution to `execute()` and `subscribe()`:
-the guide's [Serve the schema with GraphQL Yoga](../../docs/guide/graphql.md#yoga) recipe keeps
-guards, loaders, the request scope and error formatting.
+requests to another GraphQL server that delegates the execution to `execute()` and `subscribe()`;
+a [driver](#drivers-and-the-engine) does it without the copying, on the parsed document (GraphQL
+Yoga: [`yogaDriver()`](#graphql-yoga)).
 
 ```ts
 const plugin = app.getPlugin<GraphQLPlugin>('graphql')
@@ -818,10 +849,13 @@ const result = await plugin?.execute({ query: '{ books { total } }' })
 ```
 
 `onStart` logs `GraphQL endpoint ready` with the path, the number of types and the schema hash
-(`GraphQL schema ready` with `http: false`). On shutdown, `onStop` ends the direct subscriptions;
-`HttpPlugin` drains the requests in flight and closes the SSE streams (their `ctx.signal` aborts with
-`'shutdown'`, then the stream ends with a jittered `retry` and **no** `complete` event, so clients
-reconnect to another instance). Plugin order does not matter.
+(`GraphQL schema ready` with `http: false`). On shutdown, `onStop` ends the direct subscriptions
+and those of the engine; `HttpPlugin` drains the requests in flight and closes the SSE streams
+(their `ctx.signal` aborts with `'shutdown'`, then the stream ends with a jittered `retry` and **no**
+`complete` event, so clients reconnect to another instance). When `HttpPlugin` starts draining, it
+calls `GraphQLPlugin.onHttpDrain()`, which ends the engine's subscriptions too (a driver serves them
+as streams `HttpPlugin` does not close) and refuses new ones (503). A route-mounted driver stops in
+`onDispose`, once the drain is over: requests in flight are served. Plugin order does not matter.
 
 ## GraphQL over HTTP and SSE
 
@@ -863,6 +897,201 @@ Adapters need nothing specific. With Express, do not mount `express.json()` befo
 (the body would be consumed). In tests, `TestApp.inject()` runs queries and mutations through every
 adapter in memory and `injectStream()` / `injectSse()` stream subscriptions.
 
+## Drivers and the engine
+
+The built-in GraphQL-over-HTTP and SSE endpoint is the default and the fastest path. A **driver**
+serves the same schema with another GraphQL server, for its protocol features and its plugins
+(RFC 0009): Znight stays the engine, the driver owns the transport.
+
+```ts
+import { yogaDriver } from '@znight/graphql/yoga'
+
+GraphQLPlugin.configure({ guards: [AccessGuard], driver: yogaDriver() })
+```
+
+Resolvers, guards, loaders, result mappers, request-scoped providers and tests do not change: the
+server calls `plugin.engine`, which runs the compiled schema with everything this README describes.
+**GraphQL Yoga** is the first driver ([`@znight/graphql/yoga`](#graphql-yoga)); **Apollo Server**
+follows once it accepts graphql-js 17. Any other graphql-js-shaped server takes the engine as it
+is: a driver is a small object, checked with the [conformance suite](#driver-conformance).
+
+**The engine.** `plugin.engine` (after bootstrap, and the first argument of `driver.start()`):
+
+| Member                          | What                                                                                                                                                                                                                        |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schema`                        | The executable schema; its resolvers are Znight's pipelines                                                                                                                                                                 |
+| `settings`                      | The resolved options a server needs: `path` (prefix included), `introspection`, `ide` (`graphiql`), `exposeErrors`, `maxTokens`, `subscriptions` (`false` or `{ maxActive }`), `http` (`false` or `{ get, bodyLimit }`)     |
+| `parse(source)`                 | graphql-js `parse` through the document cache, with `maxTokens` and the depth, aliases and directives limits; throws a `GraphQLError` (`GRAPHQL_PARSE_FAILED`, `QUERY_TOO_COMPLEX`)                                         |
+| `validate(schema, doc, rules?)` | graphql-js `validate` with `rules` (default `specifiedRules`) plus the engine's, suggestions hidden without introspection; a valid document is cached (default rules), its errors carry `GRAPHQL_VALIDATION_FAILED`         |
+| `rules`                         | The engine's own rules (the limits, `NoSchemaIntrospectionCustomRule` without introspection), for servers that validate themselves                                                                                          |
+| `execute(args, options?)`       | A validated query or mutation, in the current request scope (or one of its own): the `GraphQLContext` is the `contextValue`, `args.contextValue` its `serverContext`; errors mapped and masked, as `GraphQLError` instances |
+| `subscribe(args, options?)`     | A validated subscription: a stream of results (loaders renewed per event), or a single error result; the `maxActive` cap is shared with every transport, and the plugin ends the stream when the application stops          |
+
+`options` is `{ transport?: 'http' | 'sse' | 'ws', signal?, requestId? }`; the signal defaults to
+`args.abortSignal`, then to the HTTP request's. The functions are bound and have graphql-js's
+signatures, so they fit `graphql-http`, `graphql-sse`, `graphql-ws` and Envelop's `useEngine` as
+they are. Every operation produces one `graphql:operation` event with the driver's name, and
+documents rejected by `parse` or `validate` are observed too.
+
+**The driver contract.** A `GraphQLDriver` has a `name` (`builtin` is reserved), optional
+`routes()`, `start(engine, context)` and an optional `stop()`:
+
+```ts
+import type { HttpContext } from '@znight/http'
+import type { GraphQLDriver } from '@znight/graphql'
+
+import { HttpResponse } from '@znight/http'
+import { createHandler, type Handler } from 'graphql-http'
+
+/** graphql-http's handler on the engine: GraphQL over HTTP served by the reference implementation. */
+export function graphqlHttpDriver(): GraphQLDriver {
+  let handler: Handler<HttpContext> | undefined
+  return {
+    name: 'graphql-http',
+    routes: ({ path }) => {
+      const handle = async (ctx: HttpContext) => {
+        const body = ctx.method === 'POST' ? new TextDecoder().decode(await ctx.rawBody()) : null
+        const [text, init] = await (handler as Handler<HttpContext>)({
+          method: ctx.method,
+          url: ctx.url,
+          headers: { get: name => ctx.header(name.toLowerCase()) ?? null },
+          body,
+          raw: ctx,
+          context: undefined,
+        })
+        return new HttpResponse(text ?? undefined, { status: init.status, headers: init.headers ?? {} })
+      }
+      return [
+        { method: 'GET', path, name: 'graphql', handler: handle },
+        { method: 'POST', path, name: 'graphql', handler: handle },
+      ]
+    },
+    start(engine) {
+      handler = createHandler<HttpContext>({
+        schema: engine.schema,
+        parse: engine.parse,
+        validate: engine.validate,
+        execute: args => engine.execute(args),
+      })
+    },
+  }
+}
+```
+
+- **Routes.** A route-mounted driver returns its routes: `GraphQLPlugin.httpRoutes()` gives them to
+  `HttpPlugin` with the `http` option's `meta` and `guards`, and its `bodyLimit` on the routes that
+  are not `GET`. They run in the HTTP pipeline like the built-in endpoint (request id, request
+  scope, `http:request` hooks, global and endpoint guards, route decisions, CORS, security headers,
+  drain), so the engine finds the request scope: `GraphQLContext.http` is the request, and HTTP
+  guards and GraphQL guards see the same request-scoped providers. `routes()` is called once,
+  possibly before `start()`. A driver without routes is server-mounted: it attaches itself to
+  `context.http.adapter` in `start()` and runs outside the pipeline.
+- **Lifecycle.** `onBootstrap` builds the engine, then awaits `start(engine, { logger, container,
+  http })`; a failure fails the boot (ZNIGHT066, the original error as `cause`). The engine's
+  subscriptions end when `HttpPlugin` starts draining (`onHttpDrain()`, whatever the plugin order)
+  and in `onStop`; new ones are then refused (503). `stop()` is awaited in `onDispose` for a
+  route-mounted driver, after `HttpPlugin` drained its requests, and in `onStop` for a
+  server-mounted one (`onDispose` does, for an application that never started).
+- **Options.** The engine options (`guards`, `errorMappers`, `resultMappers`, `exposeErrors`,
+  `introspection`, `limits`, `documentCache`, `subscriptions: false`, `maxActive`, `bufferSize`,
+  `pubsub`, `enforcement`) apply to every driver. `path`, `http` and `graphiql` are read by the
+  driver through its routes and `engine.settings`. `subscriptions.heartbeat` and `maxDuration`
+  configure the built-in SSE transport only: with a driver they are ZNIGHT066 (use the driver's
+  keep-alives). A driver with routes needs `HttpPlugin` and refuses `http: false` (ZNIGHT066).
+- **Errors.** The engine maps and masks errors once; a driver keeps the engine's errors as they
+  are. Request errors raised by the server itself (malformed JSON, a persisted query not found) are
+  the server's; an unexpected error thrown outside the engine is masked like the engine masks one.
+- **Cost.** Without `driver`, the plugin runs the built-in transport's handlers, which call the
+  internal executor directly: an application without driver pays nothing for the abstraction.
+
+`executeOperation()` and `subscribeOperation()` of `@znight/graphql/testing` send their requests to
+the driver's routes like to the built-in endpoint. The repository's tests run the `graphql-http`
+audits against the driver above and the Yoga driver on the four adapters, on Node.js and Bun.
+
+### GraphQL Yoga
+
+`@znight/graphql/yoga` serves the schema with [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server)
+6 (`graphql-yoga`, an optional peer dependency loaded by this entry only):
+
+```ts
+import { GraphQLPlugin } from '@znight/graphql'
+import { yogaDriver } from '@znight/graphql/yoga'
+
+GraphQLPlugin.configure({ driver: yogaDriver({ plugins: [usePersistedOperations({ getPersistedOperation })] }) })
+```
+
+| Export                             | What                                                                                                                       |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `yogaDriver(options?)`             | The driver (`name: 'yoga'`); `driver.yoga` is the Yoga server once started                                                 |
+| `YogaDriverOptions`                | Yoga's options without those Znight owns (below); `graphiql` takes GraphiQL's options                                      |
+| `yogaContext(ctx)`                 | Yoga's context of an operation (`request`, `params`, what plugins added, `znight`: the `HttpContext`), ZNIGHT066 otherwise |
+| `YogaContext`, `YogaServerContext` | Their types                                                                                                                |
+
+- **The engine is Yoga's engine.** The driver installs Envelop's `useEngine` with the engine's
+  `parse`, `validate`, `execute` and `subscribe`, before the application's plugins: one document
+  cache (Yoga's `parserAndValidationCache` is off), the engine's limits and introspection rule,
+  rejected documents observed by the hook, one `graphql:operation` event per operation with
+  `driver: 'yoga'` (`transport: 'sse'` for subscriptions). Plugins wrapping the execution
+  (`useResponseCache`) call the engine; an operation executed by a plugin that replaces it
+  (`useGraphQlJit`) fails with ZNIGHT066, logged once: its resolvers would not get the
+  `GraphQLContext`.
+- **Owned options**, refused with ZNIGHT066 (a type error first): `schema`, `context`,
+  `graphqlEndpoint` (`path`), `maskedErrors` (the engine masks once, see below),
+  `cors` (`HttpPlugin`'s), `maxRequestBodySize` (`http.bodyLimit`), `parserAndValidationCache`,
+  `requestId` (Yoga uses `HttpContext.requestId`), `healthCheckEndpoint`, `landingPage`,
+  `fetchAPI` (the runtime's own), `disposeOnProcessTerminate` (the application stops Yoga),
+  `batching` (one operation per request: the operations of a batch would share the request scope,
+  where each one's `GraphQLContext` would replace the other's) and `multipart` (JSON bodies only,
+  below). Yoga's `logging` is off unless set.
+- **Routes.** `GET` and `POST` on `path`. `GET` serves Yoga's GraphiQL with `graphiql` on, and
+  queries with `http.get` on (405 with `allow: POST` otherwise); a mutation over `GET` is Yoga's 405
+  (`allow: POST`). A `POST` body is `application/json` only, like the built-in transport: any other
+  content type (a form, `multipart/form-data`, `text/plain`, `application/graphql`) is the built-in
+  transport's 415, before Yoga parses it, so a cross-site page cannot run a mutation with the
+  user's cookies (no CSRF: a JSON body always needs a CORS preflight).
+- **Errors.** The engine's errors (masked already) and `GraphQLError`s thrown on purpose (a plugin's
+  rate limit, Yoga's request errors) are sent as they are. Any other error thrown outside the engine
+  (an Envelop plugin's hook, Yoga itself) is logged once by Znight and masked like the engine masks
+  one: `Unexpected error.` with code `INTERNAL_SERVER_ERROR` (its message with `exposeErrors`), a
+  500 for a request error.
+- **The Fetch bridge.** On `honoAdapter()` the native Web `Request` is handed to Yoga as is (a `GET`,
+  or a body with a `content-length` within the limit); otherwise a `Request` is built from
+  `HttpContext` with the body read by `ctx.rawBody()`, so a body past `http.bodyLimit` is
+  `HttpPlugin`'s 413 on every adapter. Yoga's `Response` is sent as is by `HttpPlugin`.
+- **Subscriptions** use Yoga's SSE; the engine caps them (`subscriptions.maxActive`) and ends them
+  when `HttpPlugin` starts draining, whatever the plugin order, when Yoga sends `complete` (not the
+  built-in transport's `retry` hint); a subscription sent during the drain gets a
+  `SERVICE_UNAVAILABLE` error. Queries in flight are served until the drain is over; `stop()` then
+  awaits `yoga.dispose()` (the plugins' `onDispose`), and a request reaching the stopped driver gets
+  a 503.
+- **Cost.** Yoga's request parsing, its plugin chain and the Web objects cost about 13 to 18 µs per
+  request on Bun and 27 to 45 µs on Node.js in the in-process benchmark (`test/bench/http.bench.ts`),
+  against about 1.6 µs and 5.5 µs for the built-in transport.
+
+### Driver conformance
+
+`describeDriverConformance()` of `@znight/graphql/testing` describes the scenarios every driver
+passes (RFC 0009 §12), with the test framework's own functions (`bun:test`, Vitest, Jest,
+`node:test`) and `node:assert`: queries, mutations, a field guard reading a request-scoped
+provider, loaders batching, request-scoped providers per request, result mappers, masking,
+introspection off, limits, HTTP guards on the endpoint, the hook, `POST` bodies other than JSON
+(415, never executed) and mutations over `GET` (405), and over SSE (unless `subscriptions: false`)
+events, completion, client abort, `maxActive` and shutdown in both plugin orders.
+
+```ts
+import { describeDriverConformance } from '@znight/graphql/testing'
+import { yogaDriver } from '@znight/graphql/yoga'
+import { expressAdapter } from '@znight/http/express'
+import { honoAdapter } from '@znight/http/hono'
+import { afterAll, beforeAll, describe, it } from 'bun:test'
+
+describeDriverConformance({
+  driver: () => yogaDriver(), // a new driver per application; () => undefined for the built-in transport
+  test: { describe, it, beforeAll, afterAll },
+  adapters: { express: () => expressAdapter(), hono: () => honoAdapter() },
+})
+```
+
 ## Security defaults and limits
 
 - **Introspection** off in production (`NODE_ENV === 'production'`), and suggestions hidden with it
@@ -1141,8 +1370,9 @@ Boot and execution are those of code-first.
 ## Observability
 
 Every operation goes through the `graphql:operation` hook of `@znight/core` (`GraphQLOperationEvent`:
-`operationType`, `operationName`, `documentId` (SHA-256 of the query text), `transport`,
-`requestId`, `context`, `startTime`, then `outcome` (`success`, `partial`, `error`, `rejected`) and
+`operationType`, `operationName`, `documentId` (SHA-256 of the query text), `transport`, `driver`
+(`builtin`, or the name of the [driver](#drivers-and-the-engine)), `requestId`, `context`,
+`startTime`, then `outcome` (`success`, `partial`, `error`, `rejected`) and
 `errors` with their codes). A subscription produces one event for its whole life. The event is built
 only when the hook has wrappers or listeners, so it costs nothing otherwise.
 
@@ -1186,8 +1416,9 @@ on Node.js, use `node --conditions=@znight/source` instead of `bun`):
   `GraphQLPlugin.execute()` over graphql-js `execute()` for a cached 50-field query (target: under
   10 %; measured 0–9 % on Bun 1.4, 1–7 % on Node.js 24).
 - `bun --conditions=@znight/source test/bench/http.bench.ts`: the endpoint through the `HttpPlugin`
-  pipeline in process (`GET` and `POST`, both JSON media types), next to bare graphql-js and to a
-  controller route answering a constant. `ABORT_REASON=1` removes the cost graphql-js 17.0 adds to
+  pipeline in process (`GET` and `POST`, both JSON media types), next to bare graphql-js, to a
+  controller route answering a constant, and to `GraphQLEngine.execute()` (what a driver calls: on
+  a cached `{ hello }`, within 2 % of `plugin.execute()`). `ABORT_REASON=1` removes the cost graphql-js 17.0 adds to
   every execution (a `DOMException` built when it aborts its own `AbortController`, about 3 µs on
   Node.js): compare with other servers at the same graphql-js version.
 
@@ -1281,7 +1512,17 @@ interface GraphQLResolverBinding {
   guards: Token[] // class @UseGuard guards, then method ones
   meta: Record<string, unknown> // effective route metadata (method over class); {}: none
   loaders?: Token[] // informational: loaders the method injects
-  invoke: (resolver, parent, args: GraphQLArgs, context: GraphQLContext, info: GraphQLResolveInfo) => unknown
+  context?: true // custom parameters (RFC 0010): the pipeline passes the ResolverContext as `f`
+  paramResolvers?: Token[] // class resolvers of custom parameters, passed as `x`
+  invoke(
+    resolver,
+    parent,
+    args: GraphQLArgs,
+    context: GraphQLContext,
+    info: GraphQLResolveInfo,
+    f?: ResolverContext,
+    x?,
+  ): unknown
 }
 ```
 
@@ -1293,7 +1534,9 @@ Type references are strings in graphql-js' canonical form, parsed by
 
 `invoke` maps the graphql-js arguments to the method parameters: `@Args('x')` → `a['x']`,
 `@Args()` → `a`, `@Parent()` → `p`, `@Ctx()` → `c`, `@Info()` → `i`, `@Loader()` →
-`c.loader(token)`. Unused middle parameters are `_`-prefixed and trailing ones omitted, so the code
+`c.loader(token)`, a custom parameter decorator (`createParamDecorator`, RFC 0010) →
+`(D.resolvers.graphql as ParamFunctionOf<typeof D, 'graphql'>)(f, data)` or `x[i].resolve(f, data)`
+(evaluated like a validated argument: synchronous while the resolvers return values). Unused middle parameters are `_`-prefixed and trailing ones omitted, so the code
 type-checks with `noUnusedParameters`. It calls these runtime helpers, kept stable:
 
 - `validateArgs(schema, value, label)`, exported from `@znight/graphql`: validates an argument with
@@ -1341,6 +1584,8 @@ are emitted by schema-first only: code-first sections, hashes and artifacts are
   custom internal enum values (an enum value is its SDL name).
 - **Subscriptions over SSE only.** No `graphql-ws` (WebSocket), no SSE single connection mode, no
   multipart subscriptions.
+- **Drivers**: the built-in transport and GraphQL Yoga (`@znight/graphql/yoga`); Apollo Server once it
+  accepts graphql-js 17. Yoga plugins that replace the execution (`useGraphQlJit`) are refused.
 - No `@defer` / `@stream`, no persisted or trusted documents, no query cost analysis, no response
   cache, no federation or schema stitching, no file uploads (use an HTTP upload route), no operation
   batching.

package/dist/compiler.d.mts

@@ -1,6 +1,6 @@
 import { Scope } from "@znight/core";
 import { MetaEntry } from "@znight/http/compiler";
-import { BindingHandle, ClassInfo, ClassRef, CompilerExtension, Location, ValueRef } from "@znight/compiler";
+import { BindingHandle, ClassInfo, ClassRef, CompilerExtension, Location, StaticValue, ValueRef } from "@znight/compiler";
 /** Kind of field a resolver method provides. */
 type FieldOperation = "query" | "mutation" | "subscription" | "field";
 /** A `@Resolver` class. */
@@ -71,6 +71,26 @@ type ParamData = {
   /** Identity of `L` in `Loader<L>`. */
   readonly identity: string;
   readonly location: Location;
+} | {
+  /** A custom parameter decorator (`createParamDecorator`, RFC 0010). */
+  readonly kind: "custom";
+  /** Canonical identity of the decorator `const` (imported by the generated module). */
+  readonly identity: string;
+  readonly name: string;
+  /** The data argument (a value, possibly holding references, or a reference); `undefined` without argument. */
+  readonly data: {
+    readonly value: StaticValue;
+  } | undefined;
+  /** The class resolver (`x[i].resolve(f, data)`); `undefined` for a function resolver. */
+  readonly resolver: ClassRef | undefined;
+  /**
+   * Parameters of the class resolver's `resolve` (own, inherited or an arrow function property);
+   * `undefined` for a function, or when the compiler cannot read it (the call is cast).
+   */
+  readonly arity?: number;
+  /** The value type could not be checked against the parameter. */
+  readonly cast: boolean;
+  readonly location: Location;
 };
 /** Everything the extension stores. */
 type GraphQLData = ResolverData;

package/dist/compiler.mjs

@@ -417,6 +417,22 @@ function parameterDecorators(param) {
 }
 function analyzeParameter(ctx, cls, param, where) {
 	const decorators = parameterDecorators(param);
+	const custom = typeof ctx.paramDecorator === "function" ? ctx.paramDecorator(param, "graphql", cls) : void 0;
+	if (custom !== void 0) {
+		for (const other of decorators) error(ctx, Codes.InvalidDecorator, other.location, `Parameter '${param.name}' of ${where} has several parameter decorators (@${custom.decorator.name} and @${other.name})`, ["Keep a single parameter decorator"]);
+		if (!custom.ok || decorators.length > 0) return void 0;
+		const data = custom.data;
+		return {
+			kind: "custom",
+			identity: custom.identity,
+			name: custom.name,
+			data: data === void 0 ? void 0 : { value: data.ref ?? data.value },
+			resolver: custom.resolver.kind === "class" ? custom.resolver.ref : void 0,
+			...custom.resolver.kind === "class" && custom.resolver.arity !== void 0 ? { arity: custom.resolver.arity } : {},
+			cast: custom.cast,
+			location: custom.location
+		};
+	}
 	const decorator = decorators[0];
 	if (decorator === void 0) {
 		const lookAlike = param.decorators.find((found) => found.identity !== void 0 && HTTP_LOOK_ALIKES.has(found.identity));
@@ -2627,6 +2643,8 @@ function createImports(ctx) {
 	let args;
 	let context;
 	let info;
+	let resolverContext;
+	let paramFunctionOf;
 	let validateArgs;
 	let isThenable;
 	const hosts = /* @__PURE__ */ new Map();
@@ -2643,6 +2661,14 @@ function createImports(ctx) {
 			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;
@@ -2734,7 +2760,10 @@ function resolverNode(ctx, imports, resolver, field) {
 	];
 	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)]);
+	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);
 }
 /** The provider token a loader parameter is bound to. */
@@ -2744,13 +2773,28 @@ function loaderToken(ctx, param) {
 	if (ref !== void 0 && "token" in ref) return ref.token;
 	return param.identity;
 }
-/** Which `invoke` parameters a field uses: `(r, p, a, c, i)`. */
+/** The provider classes resolving custom parameters, in order of first use (`x[i]`). */
+function paramResolvers(field) {
+	const found = /* @__PURE__ */ new Map();
+	for (const param of field.params) {
+		const resolver = param?.kind === "custom" ? param.resolver : void 0;
+		if (resolver !== void 0 && !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) {
 	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":
+			f ||= param.resolver === void 0 || param.arity !== 0;
+			x ||= param.resolver !== void 0;
+			break;
 		case "parent":
 			p = true;
 			break;
@@ -2767,43 +2811,63 @@ function usedParameters(field) {
 		p,
 		a,
 		c,
-		i
+		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, imports, resolver, field) {
+function invokeNode(ctx, imports, resolver, field, resolvers) {
 	const used = usedParameters(field);
 	const last = used.lastIndexOf(true);
 	const types = [
 		() => ctx.code`unknown`,
 		imports.argsType,
 		imports.contextType,
-		imports.infoType
+		imports.infoType,
+		imports.resolverContextType,
+		() => tupleType(ctx, resolvers.map((ref) => ctx.importType(ref)))
 	];
 	const names = [
 		"p",
 		"a",
 		"c",
-		"i"
+		"i",
+		"f",
+		"x"
 	];
 	const params = [["r", imports.hostType(resolver.host.identity)]];
 	for (let index = 0; index <= last; index++) params.push([`${used[index] ? "" : "_"}${names[index]}`, types[index]()]);
-	const validated = field.params.flatMap((param, index) => param?.kind === "args" && param.schema !== void 0 ? [index] : []);
+	const deferred = field.params.flatMap((param, index) => param !== void 0 && 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;
+		const [p, a, c, i, f, x] = rest;
 		const scope = {
 			p,
 			a,
 			c,
-			i
+			i,
+			f,
+			x,
+			resolvers: positions,
+			imports
 		};
-		if (validated.length === 0) return call(ctx, r, field, (index) => argument(ctx, scope, field, index));
-		return validatingBlock(ctx, imports, r, scope, field, validated);
+		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, nodes) {
+	const joined = nodes.slice(1).reduce((all, node) => ctx.code`${all}, ${node}`, nodes[0]);
+	return ctx.code`readonly [${joined}]`;
+}
+/** An argument whose expression may return a thenable: a validated `@Args`, or a custom parameter. */
+function isDeferred(param) {
+	return param.kind === "args" && param.schema !== void 0 || param.kind === "custom";
+}
 /** `r.method(args)`. */
 function call(ctx, r, field, argumentOf) {
 	return ctx.call(ctx.member(r, field.method), field.params.map((_, index) => argumentOf(index)));
@@ -2817,9 +2881,48 @@ function argument(ctx, scope, field, index) {
 		case "info": return scope.i;
 		case "loader": return ctx.code`${ctx.call(ctx.member(scope.c, "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(void 0);
 	}
 }
+/**
+* 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, scope, param) {
+	const f = scope.f;
+	const data = param.data === void 0 ? ctx.lit(void 0) : dataNode(ctx, param.data.value);
+	let node;
+	if (param.resolver === void 0) {
+		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);
+		if (param.arity === void 0) return ctx.code`(${scope.x}[${position}] as { resolve(ctx: unknown, data: unknown): unknown }).resolve(${f}, ${data}) as never`;
+		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}[${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, value) {
+	return isValueRef(value) ? ctx.ref(value) : ctx.lit(value);
+}
+/** `true` for a {@link ValueRef} (the only non-plain object a static value can hold). */
+function isValueRef(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype !== Object.prototype && prototype !== null && value.kind === "ref";
+}
+/** The expression of a deferred parameter (validation or custom resolver), before any `await`. */
+function deferredValue(ctx, imports, scope, field, index) {
+	const param = field.params[index];
+	return param.kind === "custom" ? customArgument(ctx, scope, param) : validation(ctx, imports, scope, param);
+}
 /** `a['name']`, or `a` for `@Args()`. */
 function argsValue(ctx, scope, name) {
 	const a = scope.a;
@@ -2853,15 +2956,13 @@ function validatingBlock(ctx, imports, r, scope, field, validated) {
 		const statements = [];
 		for (const index of validated) {
 			const name = local.get(index);
-			const param = field.params[index];
-			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([], () => call(ctx, r, field, (position) => {
 				const value = local.get(position);
 				if (value === void 0) 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];
-				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 });
 			statements.push(ctx.code`if (${ctx.call(imports.isThenable(), [name])}) return (${resume})()`);
 		}