@leaven-graphql/nestjs 0.1.0 → 0.2.1

package/dist/interceptors.d.ts

@@ -1,7 +1,7 @@
 /**
  * @leaven-graphql/nestjs - Interceptors
  *
- * Copyright 2026 Pegasus Heavy Industries LLC
+ * Copyright 2026 Joseph Quinn
  * Licensed under the Apache License, Version 2.0
  */
 import { type NestInterceptor, type ExecutionContext, type CallHandler } from '@nestjs/common';
@@ -10,7 +10,9 @@ import { Reflector } from '@nestjs/core';
 /**
  * Logging interceptor for GraphQL operations
  *
- * Logs timing and operation information for debugging.
+ * Logs timing and operation information for debugging. Successful
+ * resolutions are logged via `console.log`; failures are logged via
+ * `console.error` with the error attached, then rethrown unchanged.
  *
  * @example
  * ```typescript
@@ -27,7 +29,12 @@ export declare class LoggingInterceptor implements NestInterceptor {
 /**
  * Error formatting interceptor
  *
- * Catches errors and formats them consistently.
+ * Catches errors and formats them consistently by delegating to
+ * `@leaven-graphql/errors`. Leaven errors keep their message and error
+ * code; unexpected errors are masked in production (message replaced,
+ * code set to `INTERNAL_ERROR`) and carry their stack trace in
+ * `extensions.stackTrace` in development. The caught error is never
+ * mutated — a new `GraphQLError` is thrown instead.
  *
  * @example
  * ```typescript
@@ -42,13 +49,35 @@ export declare class ErrorFormattingInterceptor implements NestInterceptor {
     intercept(_context: ExecutionContext, next: CallHandler): Observable<unknown>;
     /**
      * Format an error for GraphQL response
+     *
+     * Returns a new `GraphQLError` built from the formatted representation
+     * rather than mutating the input error.
+     *
+     * `GraphQLError` derives `locations` from the `nodes`, or the
+     * `source`/`positions`, handed to its constructor — never from a `locations`
+     * field — so those are carried over from the converted error. Without them a
+     * client would lose the source position that the driver's own formatting
+     * path (`formatError`) preserves. A masked error reports no locations, and
+     * must not leak them here either.
      */
     private formatError;
 }
 /**
  * Complexity tracking interceptor
  *
- * Tracks query complexity for monitoring.
+ * Tracks query complexity for monitoring. Field complexity declared via
+ * `@Complexity()` is accumulated onto the request context's
+ * `_resolvedFieldComplexity` key, so multiple fields resolved in one request
+ * sum rather than overwrite each other.
+ *
+ * This measurement is **observational only**. It deliberately does not touch
+ * `_queryComplexity`, the key the driver assigns per request and
+ * `ComplexityGuard` compares: NestJS runs guards before interceptors, so a
+ * value accumulated here can never influence the guard for its own request,
+ * and writing to that key would only corrupt the driver's static estimate —
+ * making later fields of a query answer for work they did not do. Read
+ * `_resolvedFieldComplexity` from logging, metrics, or a plugin after
+ * execution.
  *
  * @example
  * ```typescript
@@ -71,7 +100,14 @@ export declare class ComplexityInterceptor implements NestInterceptor {
 /**
  * Caching interceptor
  *
- * Handles cache hints for responses.
+ * Forwards a `@CacheHint()` to `info.cacheControl.setCacheHint()`.
+ *
+ * @deprecated Has no effect; removal target 0.3.0. `info.cacheControl` is an
+ * Apollo Server construct, and nothing in Leaven's execution path attaches it,
+ * so in every supported configuration this interceptor does nothing and
+ * `@CacheHint` has no observable effect. Emit `Cache-Control` from the HTTP
+ * layer instead. Retained only so existing configurations keep compiling, and
+ * so a resolver executed under an Apollo-compatible `info` still gets its hint.
  *
  * @example
  * ```typescript

package/dist/interceptors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interceptors.d.ts","sourceRoot":"","sources":["../src/interceptors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,UAAU,EAA+B,MAAM,MAAM,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC;;;;;;;;;;;;;GAaG;AACH,qBACa,kBAAmB,YAAW,eAAe;IACjD,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;CAYpF;AAED;;;;;;;;;;;;;GAaG;AACH,qBACa,0BAA2B,YAAW,eAAe;IACzD,SAAS,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;IAUpF;;OAEG;IACH,OAAO,CAAC,WAAW;CAUpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBACa,qBAAsB,YAAW,eAAe;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,SAAS;IAE1C,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;CAiBpF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBACa,kBAAmB,YAAW,eAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,SAAS;IAE1C,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;CAsBpF;AAED;;;;;;;;;;;;;GAaG;AACH,qBACa,kBAAmB,YAAW,eAAe;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAExD,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;IAmBnF;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACH,OAAO,CAAC,WAAW;IAQnB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAiB1B;;OAEG;IACI,UAAU,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAIlD;;OAEG;IACI,UAAU,IAAI,cAAc,EAAE;IASrC;;OAEG;IACI,KAAK,IAAI,IAAI;CAGrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"interceptors.d.ts","sourceRoot":"","sources":["../src/interceptors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,UAAU,EAA+B,MAAM,MAAM,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAMzC;;;;;;;;;;;;;;;GAeG;AACH,qBACa,kBAAmB,YAAW,eAAe;IACjD,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;CAiBpF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBACa,0BAA2B,YAAW,eAAe;IACzD,SAAS,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;IAUpF;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,WAAW;CAiBpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBACa,qBAAsB,YAAW,eAAe;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,SAAS;IAE1C,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;CAqBpF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBACa,kBAAmB,YAAW,eAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,SAAS;IAE1C,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;CAuBpF;AAED;;;;;;;;;;;;;GAaG;AACH,qBACa,kBAAmB,YAAW,eAAe;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAExD,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;IAmBnF;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAiB1B;;OAEG;IACI,UAAU,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAIlD;;OAEG;IACI,UAAU,IAAI,cAAc,EAAE;IASrC;;OAEG;IACI,KAAK,IAAI,IAAI;CAGrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/middleware.d.ts

@@ -1,13 +1,17 @@
 /**
  * @leaven-graphql/nestjs - Middleware
  *
- * Copyright 2026 Pegasus Heavy Industries LLC
+ * Copyright 2026 Joseph Quinn
  * Licensed under the Apache License, Version 2.0
  */
 import { type NestMiddleware, type Type } from '@nestjs/common';
 interface Request {
     method: string;
     path: string;
+    /** Full URL including the query string, as populated by Express */
+    originalUrl?: string;
+    url?: string;
+    secure?: boolean;
     body?: Record<string, unknown>;
     headers: Record<string, string | string[] | undefined>;
 }
@@ -26,6 +30,24 @@ import type { LeavenModuleOptions } from './types';
  *
  * This middleware intercepts requests to the GraphQL endpoint
  * and processes them through the Leaven driver.
+ *
+ * ## Scope of the transport this middleware implements
+ *
+ * It calls {@link LeavenDriver.execute} directly and deliberately does NOT go
+ * through {@link LeavenDriver.handleRequest}, which is an alternative
+ * Fetch-native entry point for callers that already hold a `Request`/`Response`
+ * pair (a Bun `fetch` handler, for example). Two consequences follow, and both
+ * are intentional rather than oversights:
+ *
+ * - Only `POST` with a JSON body is served. `GET ?query=` is reserved for the
+ *   playground, and `application/graphql` bodies — which `handleRequest`'s
+ *   parser does support — are not accepted here.
+ * - The context's `req`/`res` are the **Express** request and response, not the
+ *   Fetch `Request`/`Response` that `handleRequest` stores. This is what makes
+ *   `ctx.req.user` work under Passport. See {@link GqlContext} for the full
+ *   contract; a resolver that must work behind either entry point should read
+ *   values placed on the context by the `context` factory rather than reaching
+ *   into `ctx.req`.
  */
 export declare class GraphQLMiddleware implements NestMiddleware {
     private readonly driver;
@@ -40,7 +62,10 @@ export declare class GraphQLMiddleware implements NestMiddleware {
      */
     private handleGraphQLRequest;
     /**
-     * Serve GraphQL Playground HTML
+     * Serve GraphiQL HTML
+     *
+     * Delegates to `@leaven-graphql/playground`, which owns the template and
+     * its escaping, rather than maintaining a second copy here.
      */
     private servePlayground;
     /**
@@ -48,9 +73,80 @@ export declare class GraphQLMiddleware implements NestMiddleware {
      */
     private handleCorsPreFlight;
     /**
-     * Get the playground HTML
+     * Resolve the effective CORS configuration, or `null` when this middleware
+     * must not emit CORS headers at all.
+     *
+     * CORS is **opt-in**, matching the `cors` option's documented "Enable CORS"
+     * semantics: leaving it unset emits no `Access-Control-*` headers and leaves
+     * `OPTIONS` preflights to the application. Only an explicit `true` (or an
+     * options object) turns it on — a stock `LeavenModule.forRoot({ schema })`
+     * must never answer every GraphQL POST with `Access-Control-Allow-Origin: *`.
+     * `false` is equivalent to unset and is accepted for explicitness.
+     */
+    private resolveCorsOptions;
+    /**
+     * Apply CORS headers to a response
+     *
+     * Called for both preflight (OPTIONS) responses and actual GraphQL
+     * responses — browsers require `Access-Control-Allow-Origin` on the
+     * actual response as well as the preflight. No-op when CORS was not
+     * enabled (see {@link resolveCorsOptions}).
+     *
+     * The allowed origin is *reflected*, never defaulted to `*` when an
+     * allowlist is configured: `origin: false` emits no origin header at all,
+     * an array emits the request's `Origin` only when the allowlist contains
+     * it, and `origin: true` echoes the request's `Origin`. `Vary: Origin` is
+     * emitted whenever the value depends on the request so caches cannot serve
+     * one origin's response to another, and `*` is never paired with
+     * `credentials: true` (browsers reject that combination outright).
+     */
+    private applyCorsHeaders;
+    /**
+     * Resolve the `Access-Control-Allow-Origin` value for a request
+     *
+     * Returns `value: undefined` to mean "emit no origin header", and
+     * `varies: true` when the value was derived from the request's `Origin`
+     * header and therefore requires `Vary: Origin`.
+     */
+    private resolveAllowedOrigin;
+    /**
+     * Adapt an Express-style request into a Fetch API `Request`
+     *
+     * The `ContextFactory` contract (types.ts) is declared against the global
+     * Fetch API types, and `driver.createContext` passes genuine Fetch objects.
+     * Adapting here keeps that contract intact **for the factory's first
+     * parameter only**, so factories may call `request.headers.get()`,
+     * `request.json()`, or read `request.url` regardless of how the request
+     * arrived.
+     *
+     * The factory's second parameter is NOT adapted: it is the transport-native
+     * response object, which under this middleware is the Express response.
+     * `response.status(...)` is therefore a method rather than a number and
+     * `response.headers` does not exist — use `response.setHeader(name, value)`
+     * when writing a factory that must work behind `GraphQLMiddleware`.
+     *
+     * The URL's authority is never taken from an untrusted `Host` header
+     * unchecked: `options.publicUrl` wins when configured, otherwise `Host` is
+     * accepted only if it looks like a plain authority, and anything else falls
+     * back to the canonical default. A factory resolving tenancy from
+     * `new URL(request.url).hostname` therefore cannot be steered by a
+     * spoofed header, and a hostile value cannot make `new Request()` throw
+     * and turn every request into a 500.
+     */
+    private toFetchRequest;
+    /**
+     * Resolve the origin (scheme + authority) for the synthesized request URL
+     *
+     * A configured `publicUrl` always wins; otherwise the `Host` header is used
+     * only when it is a plain authority, and anything else falls back to the
+     * canonical origin.
+     */
+    private resolveOrigin;
+    /**
+     * The trusted origin used when no configured or trustworthy authority is
+     * available
      */
-    private getPlaygroundHtml;
+    private canonicalOrigin;
 }
 /**
  * Create middleware module with proper configuration

package/dist/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,cAAc,EAEnB,KAAK,IAAI,EACV,MAAM,gBAAgB,CAAC;AAGxB,UAAU,OAAO;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;CACxD;AAED,UAAU,QAAQ;IAChB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC/B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC9B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC9B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjD,GAAG,IAAI,QAAQ,CAAC;CACjB;AAED,KAAK,YAAY,GAAG,MAAM,IAAI,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD;;;;;GAKG;AACH,qBACa,iBAAkB,YAAW,cAAc;IAE7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADf,MAAM,EAAE,YAAY,EACZ,OAAO,EAAE,mBAAmB;IAG9E;;OAEG;IACU,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BhF;;OAEG;YACW,oBAAoB;IAyClC;;OAEG;IACH,OAAO,CAAC,eAAe;IAOvB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAwC3B;;OAEG;IACH,OAAO,CAAC,iBAAiB;CA6B1B;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAAC,cAAc,CAAC,CAE9D"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,cAAc,EAEnB,KAAK,IAAI,EACV,MAAM,gBAAgB,CAAC;AAKxB,UAAU,OAAO;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;CACxD;AAED,UAAU,QAAQ;IAChB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC/B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC9B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC9B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjD,GAAG,IAAI,QAAQ,CAAC;CACjB;AAED,KAAK,YAAY,GAAG,MAAM,IAAI,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAe,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAUhE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBACa,iBAAkB,YAAW,cAAc;IAE7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADf,MAAM,EAAE,YAAY,EACZ,OAAO,EAAE,mBAAmB;IAG9E;;OAEG;IACU,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAiChF;;OAEG;YACW,oBAAoB;IA4DlC;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAMvB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAK3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,gBAAgB;IAiDxB;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IA2C5B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,cAAc;IAoCtB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAarB;;;OAGG;IACH,OAAO,CAAC,eAAe;CAIxB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAAC,cAAc,CAAC,CAE9D"}

package/dist/module.d.ts

@@ -1,25 +1,51 @@
 /**
  * @leaven-graphql/nestjs - NestJS Module
  *
- * Copyright 2026 Pegasus Heavy Industries LLC
+ * Copyright 2026 Joseph Quinn
  * Licensed under the Apache License, Version 2.0
  */
-import { DynamicModule } from '@nestjs/common';
-import type { LeavenModuleOptions, LeavenModuleAsyncOptions } from './types';
+import { DynamicModule, type MiddlewareConsumer, type NestModule } from '@nestjs/common';
+import { LEAVEN_MODULE_OPTIONS, LEAVEN_DRIVER, LEAVEN_PUBSUB, type LeavenModuleOptions, type LeavenModuleAsyncOptions } from './types';
 /**
- * Injection token for Leaven module options
- */
-export declare const LEAVEN_MODULE_OPTIONS = "LEAVEN_MODULE_OPTIONS";
-/**
- * Injection token for Leaven driver
+ * Injection tokens for the Leaven module options and driver.
+ *
+ * Defined in `./types` (see the note there) and re-exported here so that
+ * existing `import { LEAVEN_MODULE_OPTIONS, LEAVEN_DRIVER } from './module'`
+ * sites keep working.
  */
-export declare const LEAVEN_DRIVER = "LEAVEN_DRIVER";
+export { LEAVEN_MODULE_OPTIONS, LEAVEN_DRIVER, LEAVEN_PUBSUB };
 /**
  * Leaven GraphQL Module for NestJS
  *
  * This module provides integration between NestJS and Leaven GraphQL.
  * It can be used with both schema-first and code-first approaches.
  *
+ * Configuring the module via {@link forRoot} or {@link forRootAsync}
+ * registers the {@link LeavenDriver}, the {@link SchemaBuilderService}
+ * (which builds the schema from `schema` or `typeDefs`/`resolvers` and
+ * hands it to the driver), the {@link SubscriptionManager}, and the
+ * {@link GraphQLMiddleware} serving the HTTP endpoint, which is applied
+ * automatically at `options.path` (default `/graphql`).
+ *
+ * ## What this module does NOT wire
+ *
+ * - **The WebSocket transport.** {@link SubscriptionManager} is registered as a
+ *   provider, but registering it does not open a socket: opening one requires
+ *   `server.upgrade()` on the underlying HTTP server, and this module only has
+ *   a `MiddlewareConsumer`, which cannot express an upgrade route. The manager
+ *   deliberately owns the graphql-ws protocol and nothing else. Callers
+ *   register the upgrade route at `subscriptions.path` themselves and hand each
+ *   socket to the manager — see the package README's "Wiring the WebSocket
+ *   transport".
+ * - **The NestJS execution pipeline around resolvers.** Resolvers supplied via
+ *   `resolvers` (or baked into a pre-built `schema`) are plain functions
+ *   invoked by graphql-js, not Nest handlers, so `@UseGuards`,
+ *   `@UseInterceptors`, and parameter decorators such as `@Args()` never fire
+ *   for them. That requires a `@nestjs/graphql` `AbstractGraphQLDriver` bridge,
+ *   which this package does not ship. `maxComplexity` is unaffected — the
+ *   executor enforces it directly — but `maxDepth`, which is only surfaced for
+ *   {@link DepthGuard}, is not enforced on this path.
+ *
  * @example
  * ```typescript
  * // Schema-first approach
@@ -59,17 +85,56 @@ export declare const LEAVEN_DRIVER = "LEAVEN_DRIVER";
  * export class AppModule {}
  * ```
  */
-export declare class LeavenModule {
+export declare class LeavenModule implements NestModule {
+    private readonly options?;
+    constructor(options?: LeavenModuleOptions | undefined);
     /**
-     * Configure the module synchronously
+     * Register the {@link GraphQLMiddleware} at the configured GraphQL
+     * endpoint (`options.path`, default `/graphql`).
+     *
+     * Called automatically by NestJS during application initialization. When
+     * the module is imported without `forRoot()`/`forRootAsync()` no options
+     * provider exists (and no GraphQL providers are registered), so nothing
+     * is wired.
+     */
+    configure(consumer: MiddlewareConsumer): void;
+    /**
+     * Configure the module synchronously.
+     *
+     * Registers the options and driver providers along with the
+     * {@link SchemaBuilderService}, {@link SubscriptionManager}, and
+     * {@link GraphQLMiddleware} so that importing this module yields a
+     * working GraphQL endpoint.
      */
     static forRoot(options?: LeavenModuleOptions): DynamicModule;
     /**
-     * Configure the module asynchronously
+     * Build the providers backing {@link ComplexityGuard} and
+     * {@link DepthGuard}.
+     *
+     * The guards inject their limits by token, so the tokens must resolve
+     * even when the corresponding option is absent; `Infinity` expresses
+     * "no limit" without the guards having to special-case `undefined`.
+     */
+    private static createLimitProviders;
+    /**
+     * Build the shared {@link PubSub} provider resolved by `@InjectPubSub()`.
+     *
+     * One instance per module so that a publisher and a subscriber in
+     * different providers reach the same topics.
+     */
+    private static createPubSubProvider;
+    /**
+     * Configure the module asynchronously.
+     *
+     * Registers the same providers as {@link forRoot}, with the options
+     * resolved via `useFactory`, `useClass`, or `useExisting`.
      */
     static forRootAsync(options: LeavenModuleAsyncOptions): DynamicModule;
     /**
      * Create async providers based on configuration
+     *
+     * @throws Error when none of `useFactory`, `useClass`, or `useExisting`
+     * is supplied.
      */
     private static createAsyncProviders;
     /**

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,aAAa,EAKd,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EACV,mBAAmB,EACnB,wBAAwB,EAEzB,MAAM,SAAS,CAAC;AAGjB;;GAEG;AACH,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D;;GAEG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAEa,YAAY;IACvB;;OAEG;WACW,OAAO,CAAC,OAAO,GAAE,mBAAwB,GAAG,aAAa;IAmBvE;;OAEG;WACW,YAAY,CAAC,OAAO,EAAE,wBAAwB,GAAG,aAAa;IAiB5E;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAiBnC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,0BAA0B;CAsB1C"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,aAAa,EAKb,KAAK,kBAAkB,EACvB,KAAK,UAAU,EAGhB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAE9B,MAAM,SAAS,CAAC;AAQjB;;;;;;GAMG;AACH,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,qBAEa,YAAa,YAAW,UAAU;IAI3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAAR,OAAO,CAAC,EAAE,mBAAmB,YAAA;IAGhD;;;;;;;;OAQG;IACI,SAAS,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;IAUpD;;;;;;;OAOG;WACW,OAAO,CAAC,OAAO,GAAE,mBAAwB,GAAG,aAAa;IAmCvE;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAiBnC;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IASnC;;;;;OAKG;WACW,YAAY,CAAC,OAAO,EAAE,wBAAwB,GAAG,aAAa;IAiC5E;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAuBnC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,0BAA0B;CAsB1C"}

package/dist/schema-builder.d.ts

@@ -1,25 +1,35 @@
 /**
  * @leaven-graphql/nestjs - Schema Builder Integration
  *
- * Provides integration with NestJS's code-first schema building approach.
+ * Builds the module's `GraphQLSchema` from a pre-built `schema` or from SDL
+ * `typeDefs` (optionally merged with a `resolvers` map) and hands it to the
+ * driver. Code-first generation (`autoSchemaFile`) is not implemented and
+ * fails at bootstrap rather than silently.
  *
- * Copyright 2026 Pegasus Heavy Industries LLC
+ * Copyright 2026 Joseph Quinn
  * Licensed under the Apache License, Version 2.0
  */
 import { type OnModuleInit, type Type } from '@nestjs/common';
-import type { GraphQLSchema } from 'graphql';
+import { type DocumentNode, type GraphQLSchema } from 'graphql';
 import { LeavenDriver } from './driver';
 import type { LeavenModuleOptions, BuildSchemaOptions } from './types';
+/**
+ * Resolver map as accepted by {@link LeavenModuleOptions.resolvers}.
+ */
+type ResolverMap = Record<string, unknown> | Array<Record<string, unknown>>;
 /**
  * Schema source type - determines how to build the schema
+ *
+ * {@link SchemaBuilderService.buildSchema} narrows on a value of this type,
+ * so every supported configuration is enumerated here exactly once.
  */
 export type SchemaSource = {
     type: 'provided';
     schema: GraphQLSchema;
 } | {
     type: 'typeDefs';
-    typeDefs: string;
-    resolvers: Record<string, unknown>;
+    typeDefs: string | DocumentNode | Array<string | DocumentNode>;
+    resolvers?: ResolverMap;
 } | {
     type: 'autoSchema';
     options: BuildSchemaOptions;
@@ -39,22 +49,36 @@ export declare class SchemaBuilderService implements OnModuleInit {
      * Initialize the schema on module init
      */
     onModuleInit(): Promise<void>;
+    /**
+     * Classify the configured options into a {@link SchemaSource}.
+     *
+     * `schema` wins over `typeDefs`, which wins over `autoSchemaFile`.
+     * Returns `null` when no schema source is configured at all.
+     */
+    private resolveSchemaSource;
     /**
      * Build the schema from configured sources
+     *
+     * @throws {Error} When only `autoSchemaFile` is configured. Leaven has no
+     * code-first pipeline, so returning `null` here would leave the driver
+     * without a schema and fail every request at runtime; failing at bootstrap
+     * points at the actual misconfiguration instead.
      */
     buildSchema(): Promise<GraphQLSchema | null>;
     /**
      * Build schema from type definitions (SDL)
+     *
+     * SDL alone is a complete schema and is built with graphql-js directly.
+     * When a resolver map is supplied it is merged in with
+     * `makeExecutableSchema`, after which any `@Description`/`@Deprecated`
+     * metadata recorded on the resolver functions is applied to the matching
+     * schema fields.
      */
     private buildFromTypeDefs;
     /**
-     * Merge multiple type definition strings
+     * Normalize type definitions to a single SDL string
      */
     private mergeTypeDefs;
-    /**
-     * Merge multiple resolver objects
-     */
-    private mergeResolvers;
     /**
      * Get the built schema
      */
@@ -87,6 +111,10 @@ export interface SchemaFileOptions {
 }
 /**
  * Generate a schema file from the current schema
+ *
+ * Creates the parent directory if it does not exist. When
+ * `includeDescriptions` is `false`, all type, field, and argument
+ * descriptions are stripped from the emitted SDL.
  */
 export declare function generateSchemaFile(schema: GraphQLSchema, options: SchemaFileOptions): Promise<void>;
 /**
@@ -116,4 +144,5 @@ export declare function registerResolverMetadata(metadata: ResolverMetadata): vo
  * Clear resolver metadata (for testing)
  */
 export declare function clearResolverMetadata(): void;
+export {};
 //# sourceMappingURL=schema-builder.d.ts.map

package/dist/schema-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-builder.d.ts","sourceRoot":"","sources":["../src/schema-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAc,KAAK,YAAY,EAAU,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAClF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAEvE;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC1E;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAExD;;;;;GAKG;AACH,qBACa,oBAAqB,YAAW,YAAY;IAItB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJhD,OAAO,CAAC,WAAW,CAA8B;gBAGC,OAAO,EAAE,mBAAmB,EACpC,MAAM,EAAE,YAAY;IAG9D;;OAEG;IACU,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ1C;;OAEG;IACU,WAAW,IAAI,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAqBzD;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA4CzB;;OAEG;IACH,OAAO,CAAC,aAAa;IAuBrB;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB;;OAEG;IACI,SAAS,IAAI,aAAa,GAAG,IAAI;IAIxC;;OAEG;IACI,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAK7C;;OAEG;IACI,aAAa,IAAI,OAAO;CAGhC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,cAAc,GAAG,OAAO,CAAC;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;IACnC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;QAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;CACJ;AAOD;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,EAAE,CAExD;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAEzE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}
+{"version":3,"file":"schema-builder.d.ts","sourceRoot":"","sources":["../src/schema-builder.ts"],"names":[],"mappings":"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"}