@leaven-graphql/nestjs 0.1.0 → 0.2.0

package/dist/decorators.d.ts

@@ -1,9 +1,10 @@
 /**
  * @leaven-graphql/nestjs - Decorators
  *
- * Copyright 2026 Pegasus Heavy Industries LLC
+ * Copyright 2026 Joseph Quinn
  * Licensed under the Apache License, Version 2.0
  */
+import { type ExecutionContext } from '@nestjs/common';
 /**
  * Metadata key for resolver complexity
  */
@@ -24,6 +25,12 @@ export declare const CACHE_KEY = "leaven:cache";
  * Metadata key for subscription filter
  */
 export declare const SUBSCRIPTION_FILTER_KEY = "leaven:subscription:filter";
+/**
+ * Extractor backing the {@link Context} decorator.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function contextExtractor(data: string | undefined, ctx: ExecutionContext): unknown;
 /**
  * Inject the GraphQL context
  *
@@ -35,7 +42,13 @@ export declare const SUBSCRIPTION_FILTER_KEY = "leaven:subscription:filter";
  * }
  * ```
  */
-export declare const Context: (...dataOrPipes: (string | import("@nestjs/common").PipeTransform<any, any> | import("@nestjs/common").Type<import("@nestjs/common").PipeTransform<any, any>>)[]) => ParameterDecorator;
+export declare const Context: (...dataOrPipes: (string | import("@nestjs/common").PipeTransform<any, any> | import("@nestjs/common").Type<import("@nestjs/common").PipeTransform<any, any>> | undefined)[]) => ParameterDecorator;
+/**
+ * Extractor backing the {@link Info} decorator.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function infoExtractor(_data: unknown, ctx: ExecutionContext): unknown;
 /**
  * Inject the GraphQL info object
  *
@@ -48,6 +61,12 @@ export declare const Context: (...dataOrPipes: (string | import("@nestjs/common"
  * ```
  */
 export declare const Info: (...dataOrPipes: unknown[]) => ParameterDecorator;
+/**
+ * Extractor backing the {@link Root} decorator.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function rootExtractor(_data: unknown, ctx: ExecutionContext): unknown;
 /**
  * Inject the root/parent value
  *
@@ -64,6 +83,12 @@ export declare const Root: (...dataOrPipes: unknown[]) => ParameterDecorator;
  * Alias for Root decorator
  */
 export declare const Parent: (...dataOrPipes: unknown[]) => ParameterDecorator;
+/**
+ * Extractor backing the {@link Args} decorator.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function argsExtractor(data: string | undefined, ctx: ExecutionContext): unknown;
 /**
  * Inject resolver arguments
  *
@@ -75,7 +100,7 @@ export declare const Parent: (...dataOrPipes: unknown[]) => ParameterDecorator;
  * }
  * ```
  */
-export declare const Args: (...dataOrPipes: (string | import("@nestjs/common").PipeTransform<any, any> | import("@nestjs/common").Type<import("@nestjs/common").PipeTransform<any, any>>)[]) => ParameterDecorator;
+export declare const Args: (...dataOrPipes: (string | import("@nestjs/common").PipeTransform<any, any> | import("@nestjs/common").Type<import("@nestjs/common").PipeTransform<any, any>> | undefined)[]) => ParameterDecorator;
 /**
  * Set complexity for a resolver
  *
@@ -104,6 +129,13 @@ export interface ComplexityEstimatorArgs {
 /**
  * Mark a field as deprecated
  *
+ * @remarks
+ * Records the reason under {@link DEPRECATED_KEY}. `SchemaBuilderService`
+ * reads it off the resolver functions passed via the `resolvers` option and
+ * sets the matching field's `deprecationReason`, so the field is marked
+ * `@deprecated` in the emitted schema. A pre-built `schema` is used as
+ * given, so annotate its fields there instead.
+ *
  * @example
  * ```typescript
  * @Query(() => String)
@@ -117,6 +149,13 @@ export declare function Deprecated(reason: string): MethodDecorator;
 /**
  * Add description to a field
  *
+ * @remarks
+ * Records the text under {@link DESCRIPTION_KEY}. `SchemaBuilderService`
+ * reads it off the resolver functions passed via the `resolvers` option and
+ * sets the matching field's description, so the text appears in the emitted
+ * schema and in introspection. A pre-built `schema` is used as given, so
+ * describe its fields there instead.
+ *
  * @example
  * ```typescript
  * @Query(() => User)
@@ -130,6 +169,11 @@ export declare function Description(text: string): MethodDecorator;
 /**
  * Enable caching for a resolver
  *
+ * @deprecated Has no effect; removal target 0.3.0. The hint is only applied by
+ * `CachingInterceptor`, which requires `info.cacheControl` — an Apollo Server
+ * construct that Leaven never attaches to `GraphQLResolveInfo`. The metadata is
+ * recorded under {@link CACHE_KEY} but nothing in the library reads it.
+ *
  * @example
  * ```typescript
  * @Query(() => Settings)
@@ -153,9 +197,50 @@ export interface CacheHintOptions {
      */
     scope?: 'PUBLIC' | 'PRIVATE';
 }
+/**
+ * Yield only the source events a predicate accepts.
+ *
+ * Cancelling the returned iterator cancels the source, because `for await`
+ * calls `return()` on the source when the loop completes abruptly — including
+ * when the consumer cancels this generator. No extra teardown is performed:
+ * a second `return()` would both replace any in-flight error with a cleanup
+ * error and, for shared engines, release a topic subscription twice.
+ *
+ * A predicate that throws drops the offending event and is reported to
+ * `console.error` rather than tearing down the whole subscription.
+ *
+ * @internal Shared by {@link SubscriptionFilter} and the `filter` option of
+ * the `Subscription` decorator.
+ */
+export declare function filterAsyncIterator<T>(source: AsyncIterable<T>, predicate: (payload: T) => boolean | Promise<boolean>): AsyncGenerator<T>;
+/**
+ * Replace a method descriptor with one that filters the async iterable the
+ * original method produces.
+ *
+ * The wrapper is deliberately synchronous: when the original method returns
+ * an async iterable directly, so does the wrapper, so a direct caller can
+ * still write `for await (const x of resolver.messageAdded())`. Only when the
+ * original returns a promise does the wrapper return one.
+ *
+ * @internal Shared by {@link SubscriptionFilter} and the `filter` option of
+ * the `Subscription` decorator, so a correctness fix lands in one place.
+ */
+export declare function wrapWithFilter(descriptor: PropertyDescriptor, filter: (payload: unknown, variables: unknown, context: unknown) => boolean | Promise<boolean>): void;
 /**
  * Add filter to subscription
  *
+ * Wraps the decorated method so the async iterator it returns yields only
+ * the events the predicate accepts. The predicate receives the published
+ * payload along with the resolver's arguments and context, and may be
+ * asynchronous. Rejected events are dropped without reaching the client.
+ *
+ * The wrapper preserves the original method's return kind: an async iterable
+ * stays an async iterable (so direct callers can `for await` it), and a
+ * promise stays a promise.
+ *
+ * The predicate is also recorded under {@link SUBSCRIPTION_FILTER_KEY} so a
+ * schema builder can inspect it.
+ *
  * @example
  * ```typescript
  * @Subscription(() => Comment)
@@ -190,6 +275,10 @@ export declare function Decorators(...decorators: MethodDecorator[]): MethodDeco
 /**
  * Create a custom context decorator
  *
+ * The underlying param decorator is built once per created decorator, not on
+ * every application, so applying the returned decorator at many call sites
+ * reuses a single factory.
+ *
  * @example
  * ```typescript
  * export const CurrentUser = createContextDecorator<User>('user');

package/dist/decorators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH;;GAEG;AACH,eAAO,MAAM,cAAc,sBAAsB,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,cAAc,sBAAsB,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAEpD;;GAEG;AACH,eAAO,MAAM,SAAS,iBAAiB,CAAC;AAExC;;GAEG;AACH,eAAO,MAAM,uBAAuB,+BAA+B,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO,yLAUnB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI,mDAKhB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI,mDAKhB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,MAAM,mDAAO,CAAC;AAE3B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI,yLAWhB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,GAAG,eAAe,CAE/E;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,EAAE,uBAAuB,KAAK,MAAM,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAE1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAEzD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAEpE;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAC7F,eAAe,CAEjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,GAAG,UAAU,EAAE,eAAe,EAAE,GAAG,eAAe,CAE5E;AAYD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,kBAAkB,CAM/E"}
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"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"}

package/dist/driver.d.ts

@@ -1,18 +1,18 @@
 /**
  * @leaven-graphql/nestjs - Leaven Driver for NestJS GraphQL
  *
- * Copyright 2026 Pegasus Heavy Industries LLC
+ * Copyright 2026 Joseph Quinn
  * Licensed under the Apache License, Version 2.0
  */
 import { type OnModuleInit, type OnModuleDestroy } from '@nestjs/common';
-import type { GraphQLSchema, DocumentNode } from 'graphql';
+import { type GraphQLSchema, type DocumentNode } from 'graphql';
 import { LeavenExecutor } from '@leaven-graphql/core';
 import type { LeavenModuleOptions, GqlContext, GraphQLFormattedError } from './types';
 /**
  * Request handler result
  */
-export interface HandlerResult {
-    data?: Record<string, unknown> | null;
+export interface HandlerResult<TData = Record<string, unknown>> {
+    data?: TData | null;
     errors?: readonly GraphQLFormattedError[];
     extensions?: Record<string, unknown>;
 }
@@ -26,6 +26,13 @@ export declare class LeavenDriver implements OnModuleInit, OnModuleDestroy {
     private executor;
     private schema;
     private readonly options;
+    /** Maximum number of memoized query analyses retained */
+    private static readonly MAX_ANALYSIS_ENTRIES;
+    /**
+     * LRU of {@link QueryAnalysis} keyed by query string and operation name.
+     * Cleared whenever the schema changes, since complexity is schema-dependent.
+     */
+    private readonly analysisCache;
     constructor(options: LeavenModuleOptions);
     /**
      * Initialize the driver with a schema
@@ -33,6 +40,11 @@ export declare class LeavenDriver implements OnModuleInit, OnModuleDestroy {
     onModuleInit(): Promise<void>;
     /**
      * Cleanup resources on module destroy
+     *
+     * `LeavenExecutor.clearCaches()` is genuinely asynchronous for a remote
+     * cache (Redis `FLUSH`), so it is awaited: dropping the promise would both
+     * leave the clear unfinished and turn a rejecting cache into an unhandled
+     * rejection during shutdown.
      */
     onModuleDestroy(): Promise<void>;
     /**
@@ -49,18 +61,61 @@ export declare class LeavenDriver implements OnModuleInit, OnModuleDestroy {
     getExecutor(): LeavenExecutor | null;
     /**
      * Initialize the Leaven executor
+     *
+     * Every option the executor understands is forwarded here. In particular
+     * `introspection` and `maxDepth` are *enforced by the executor* — the former
+     * by validating with `NoSchemaIntrospectionCustomRule`, the latter by
+     * rejecting over-deep documents at parse time — so omitting either would
+     * leave a documented option silently inert.
      */
     private initializeExecutor;
     /**
      * Execute a GraphQL request
+     *
+     * When `maxComplexity` or `maxDepth` is configured, the query is statically
+     * analyzed before execution and its complexity and depth are recorded on the
+     * provided context as `_queryComplexity` and `_queryDepth`, the keys read by
+     * `ComplexityGuard` and `DepthGuard`. With neither limit configured the
+     * analysis is skipped — see {@link attachQueryAnalysis}.
      */
     execute<TData = Record<string, unknown>>(query: string | DocumentNode, variables?: Record<string, unknown>, context?: GqlContext, operationName?: string): Promise<HandlerResult>;
+    /**
+     * Turn an error thrown out of the executor into a response error.
+     *
+     * Leaven errors keep their code, extensions, and message as-is. Unexpected
+     * errors are masked only in production — masking them in development would
+     * hide the real message from the developer — and
+     * `includeStacktraceInErrorResponses` suppresses masking outright, since a
+     * masked error carries no stack to include. A configured `formatError` gets
+     * the last word, exactly as it does for errors the executor reports itself.
+     */
+    private formatThrownError;
+    /**
+     * Start a GraphQL subscription.
+     *
+     * Resolves to an async iterator of results when the operation subscribes
+     * successfully, or to a {@link HandlerResult} carrying `errors` when the
+     * document fails to parse or validate. Callers must distinguish the two by
+     * testing for `Symbol.asyncIterator`. This method rejects only when the
+     * driver has no executor — every error raised while subscribing is reported
+     * through `errors`, and masked in production, exactly as in {@link execute}.
+     *
+     * As with {@link execute}, complexity and depth are recorded on the context
+     * — when a limit is configured — so the guards apply to subscriptions as
+     * well as queries.
+     */
+    subscribe<TData = Record<string, unknown>>(query: string | DocumentNode, variables?: Record<string, unknown>, context?: GqlContext, operationName?: string): Promise<AsyncIterableIterator<HandlerResult<TData>> | HandlerResult<TData>>;
     /**
      * Handle an HTTP request
      */
     handleRequest(request: Request, response: Response): Promise<HandlerResult>;
     /**
      * Parse the request body
+     *
+     * POST requests are dispatched on their content type: `application/json`
+     * bodies carry `{ query, variables, operationName }`, and
+     * `application/graphql` bodies (per the GraphQL-over-HTTP spec) carry the
+     * raw query string. Other methods read the operation from URL parameters.
      */
     private parseRequestBody;
     /**
@@ -68,15 +123,55 @@ export declare class LeavenDriver implements OnModuleInit, OnModuleDestroy {
      */
     private createContext;
     /**
-     * Convert DocumentNode to string
-     */
-    private documentToString;
+     * Analyze the query and record its complexity and depth on the request
+     * context under the `_queryComplexity` / `_queryDepth` keys that
+     * `ComplexityGuard` and `DepthGuard` enforce.
+     *
+     * Analysis is **skipped entirely** unless `maxComplexity` or `maxDepth` is
+     * configured. It costs a full uncached `parse()` plus a full uncached
+     * complexity compilation on top of the executor's own (LRU-cached) parse and
+     * compile — roughly 2.6x the work of the request itself for a small query —
+     * and with no limit configured both guards receive the module's `Infinity`
+     * sentinel and have nothing to enforce.
+     *
+     * When a limit *is* configured, the result is memoized in a small LRU keyed
+     * by query text and operation name, so the surcharge is paid once per
+     * distinct document rather than once per request.
+     *
+     * A document that fails to parse is left to the executor, which reports the
+     * syntax error as a proper GraphQL error response — no limit can be
+     * meaningfully enforced on a document that never executes.
+     *
+     * Every other failure (a broken compiler, a missing schema, a depth
+     * traversal that throws) is an *analysis* failure: it is logged and both
+     * fields are set to `Infinity` so the guards fail closed. Leaving them unset
+     * would hand an attacker who finds one query shape that trips the analyzer
+     * an unlimited-complexity channel. Failures are never memoized.
+     */
+    private attachQueryAnalysis;
+    /**
+     * Store an analysis result, evicting the least recently used entry when the
+     * cache is full.
+     */
+    private memoizeAnalysis;
+    /**
+     * Record a fail-closed sentinel for both analysis fields and log the cause.
+     *
+     * `Infinity` exceeds every finite limit, so a configured `ComplexityGuard`
+     * or `DepthGuard` rejects the request rather than letting it through
+     * unmeasured.
+     */
+    private recordAnalysisFailure;
     /**
      * Check if playground should be enabled
      */
     isPlaygroundEnabled(): boolean;
     /**
      * Check if introspection should be enabled
+     *
+     * This is the value handed to the executor as `ExecutorConfig.introspection`,
+     * which installs `NoSchemaIntrospectionCustomRule` when it is `false`, so a
+     * caller may also use it to decide whether to serve a schema-browsing UI.
      */
     isIntrospectionEnabled(): boolean;
     /**
@@ -89,7 +184,11 @@ export declare class LeavenDriver implements OnModuleInit, OnModuleDestroy {
     getCacheStats(): ReturnType<LeavenExecutor['getCacheStats']> | null;
     /**
      * Clear all caches
+     *
+     * Awaited rather than fired and forgotten: `clearCaches` is asynchronous for
+     * a remote cache, so a floated promise would leave the clear unfinished and
+     * a rejecting cache unhandled.
      */
-    clearCaches(): void;
+    clearCaches(): Promise<void>;
 }
 //# sourceMappingURL=driver.d.ts.map

package/dist/driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAc,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAuB,MAAM,sBAAsB,CAAC;AAC3E,OAAO,KAAK,EACV,mBAAmB,EACnB,UAAU,EACV,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,MAAM,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;;;;GAKG;AACH,qBACa,YAAa,YAAW,YAAY,EAAE,eAAe;IAChE,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;gBAElC,OAAO,EAAE,mBAAmB;IAIxC;;OAEG;IACU,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAO1C;;OAEG;IACU,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAO7C;;OAEG;IACI,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAK7C;;OAEG;IACI,SAAS,IAAI,aAAa,GAAG,IAAI;IAIxC;;OAEG;IACI,WAAW,IAAI,cAAc,GAAG,IAAI;IAI3C;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAe1B;;OAEG;IACU,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClD,KAAK,EAAE,MAAM,GAAG,YAAY,EAC5B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,CAAC,EAAE,UAAU,EACpB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,aAAa,CAAC;IA2DzB;;OAEG;IACU,aAAa,CACxB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,aAAa,CAAC;IAYzB;;OAEG;YACW,gBAAgB;IAiC9B;;OAEG;YACW,aAAa;IAiB3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;OAEG;IACI,mBAAmB,IAAI,OAAO;IAOrC;;OAEG;IACI,sBAAsB,IAAI,OAAO;IAOxC;;OAEG;IACI,OAAO,IAAI,MAAM;IAIxB;;OAEG;IACI,aAAa,IAAI,UAAU,CAAC,cAAc,CAAC,eAAe,CAAC,CAAC,GAAG,IAAI;IAI1E;;OAEG;IACI,WAAW,IAAI,IAAI;CAG3B"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"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"}

package/dist/execution-context.d.ts

@@ -4,12 +4,34 @@
  * Provides a helper class for accessing GraphQL-specific context in guards,
  * interceptors, and other NestJS constructs.
  *
- * Copyright 2026 Pegasus Heavy Industries LLC
+ * Copyright 2026 Joseph Quinn
  * Licensed under the Apache License, Version 2.0
  */
 import type { ExecutionContext, ArgumentsHost } from '@nestjs/common';
 import type { GraphQLResolveInfo } from 'graphql';
 import type { GqlContext } from './types';
+/**
+ * Positional indices of the GraphQL resolver arguments as exposed by
+ * NestJS's `ExecutionContext.getArgs()` for GraphQL invocations:
+ * `[root, args, context, info]`.
+ *
+ * This is the single source of truth for the positional assumption shared by
+ * the execution-context helpers and the param decorators. Use these named
+ * indices instead of hard-coded numbers so a change in argument ordering only
+ * needs to be reflected in one place.
+ *
+ * @internal
+ */
+export declare const GQL_RESOLVER_ARGS: {
+    /** The root/parent value — 1st resolver argument */
+    readonly ROOT: 0;
+    /** The resolver arguments object — 2nd resolver argument */
+    readonly ARGS: 1;
+    /** The GraphQL context object — 3rd resolver argument */
+    readonly CONTEXT: 2;
+    /** The `GraphQLResolveInfo` object — 4th resolver argument */
+    readonly INFO: 3;
+};
 /**
  * GraphQL execution context helper
  *
@@ -120,11 +142,33 @@ export declare class GqlExecutionContext {
      */
     getVariables<T = Record<string, unknown>>(): T;
     /**
-     * Get the path to the current field
+     * Get the field-name path to the current field
+     *
+     * List indices are omitted, so `users[3].email` yields
+     * `['users', 'email']` — the same value this method has always returned,
+     * which keeps `getPath().join('.')` stable as a metric label, log key, or
+     * cache key.
+     *
+     * @deprecated Use {@link getFullPath}, which preserves list indices and so
+     * identifies an individual element rather than a field position.
      */
     getPath(): string[];
+    /**
+     * Get the full path to the current field
+     *
+     * Every path segment is included: field names as strings and list indices
+     * as numbers, so `users[3].email` yields `['users', 3, 'email']` and list
+     * positions remain distinguishable from field names.
+     */
+    getFullPath(): Array<string | number>;
     /**
      * Get the requested fields (first level)
+     *
+     * Resolves fragment spreads (via `info.fragments`) and inline fragments,
+     * and merges the selections of every field node for the current field, so
+     * fields hidden behind `...SomeFragment` or `... on Type { ... }` are
+     * reported. Fragment cycles are tolerated. Returned names are the schema
+     * field names (not client aliases), deduplicated.
      */
     getSelectedFields(): string[];
 }

package/dist/execution-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution-context.d.ts","sourceRoot":"","sources":["../src/execution-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,mBAAmB;IAGV,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IAEjC,OAAO;IAIP;;OAEG;WACW,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,mBAAmB;IAIpE;;;;;OAKG;IACI,UAAU,CAAC,CAAC,GAAG,UAAU,KAAK,CAAC;IAItC;;;;;OAKG;IACI,OAAO,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC;IAIhC;;;;;OAKG;IACI,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC;IAIhD;;;;;OAKG;IACI,OAAO,CAAC,CAAC,GAAG,kBAAkB,KAAK,CAAC;IAI3C;;OAEG;IACI,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAKvD;;OAEG;IACI,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAKnE;;OAEG;IACI,OAAO,IAAI,aAAa;IAI/B;;;OAGG;IACI,OAAO,IAAI,MAAM;IAIxB;;OAEG;IACI,SAAS,IAAI,OAAO;IAI3B;;OAEG;IACI,UAAU,IAAI,QAAQ,GAAG,SAAS;IAIzC;;OAEG;IACI,QAAQ,IAAI,QAAQ,GAAG,SAAS;IAIvC;;OAEG;IACI,YAAY,IAAI,MAAM,GAAG,SAAS;IAKzC;;OAEG;IACI,iBAAiB,IAAI,MAAM,GAAG,SAAS;IAK9C;;OAEG;IACI,iBAAiB,IAAI,MAAM,GAAG,SAAS;IAK9C;;OAEG;IACI,gBAAgB,IAAI,MAAM,GAAG,SAAS;IAK7C;;OAEG;IACI,gBAAgB,IAAI,OAAO,GAAG,UAAU,GAAG,cAAc,GAAG,SAAS;IAK5E;;OAEG;IACI,YAAY,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC;IAKrD;;OAEG;IACI,OAAO,IAAI,MAAM,EAAE;IAiB1B;;OAEG;IACI,iBAAiB,IAAI,MAAM,EAAE;CAQrC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,UAAU,EAAE,OAAO,EAAE,gBAAgB,GAAG,CAAC,CAE1E;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,CAAC,CAEpF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,kBAAkB,EAAE,OAAO,EAAE,gBAAgB,GAAG,CAAC,CAE/E;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,CAAC,CAEpE"}
+{"version":3,"file":"execution-context.d.ts","sourceRoot":"","sources":["../src/execution-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,EAAE,kBAAkB,EAAoB,MAAM,SAAS,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB;IAC5B,oDAAoD;;IAEpD,4DAA4D;;IAE5D,yDAAyD;;IAEzD,8DAA8D;;CAEtD,CAAC;AAEX;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,mBAAmB;IAGV,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IAEjC,OAAO;IAIP;;OAEG;WACW,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,mBAAmB;IAIpE;;;;;OAKG;IACI,UAAU,CAAC,CAAC,GAAG,UAAU,KAAK,CAAC;IAItC;;;;;OAKG;IACI,OAAO,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC;IAIhC;;;;;OAKG;IACI,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC;IAIhD;;;;;OAKG;IACI,OAAO,CAAC,CAAC,GAAG,kBAAkB,KAAK,CAAC;IAI3C;;OAEG;IACI,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAKvD;;OAEG;IACI,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAKnE;;OAEG;IACI,OAAO,IAAI,aAAa;IAI/B;;;OAGG;IACI,OAAO,IAAI,MAAM;IAIxB;;OAEG;IACI,SAAS,IAAI,OAAO;IAI3B;;OAEG;IACI,UAAU,IAAI,QAAQ,GAAG,SAAS;IAIzC;;OAEG;IACI,QAAQ,IAAI,QAAQ,GAAG,SAAS;IAIvC;;OAEG;IACI,YAAY,IAAI,MAAM,GAAG,SAAS;IAKzC;;OAEG;IACI,iBAAiB,IAAI,MAAM,GAAG,SAAS;IAK9C;;OAEG;IACI,iBAAiB,IAAI,MAAM,GAAG,SAAS;IAK9C;;OAEG;IACI,gBAAgB,IAAI,MAAM,GAAG,SAAS;IAK7C;;OAEG;IACI,gBAAgB,IAAI,OAAO,GAAG,UAAU,GAAG,cAAc,GAAG,SAAS;IAK5E;;OAEG;IACI,YAAY,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC;IAKrD;;;;;;;;;;OAUG;IACI,OAAO,IAAI,MAAM,EAAE;IAM1B;;;;;;OAMG;IACI,WAAW,IAAI,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;IAe5C;;;;;;;;OAQG;IACI,iBAAiB,IAAI,MAAM,EAAE;CA8BrC;AAoBD;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,UAAU,EAAE,OAAO,EAAE,gBAAgB,GAAG,CAAC,CAE1E;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,CAAC,CAEpF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,kBAAkB,EAAE,OAAO,EAAE,gBAAgB,GAAG,CAAC,CAE/E;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,CAAC,CAEpE"}

package/dist/graphql-driver.d.ts

@@ -0,0 +1,180 @@
+/**
+ * @leaven-graphql/nestjs - `@nestjs/graphql` driver backed by Leaven
+ *
+ * Copyright 2026 Joseph Quinn
+ * Licensed under the Apache License, Version 2.0
+ */
+import { AbstractGraphQLDriver } from '@nestjs/graphql';
+import type { GqlModuleOptions } from '@nestjs/graphql';
+import type { GraphQLFormattedError } from 'graphql';
+import { LeavenExecutor, type ExecutorConfig } from '@leaven-graphql/core';
+/**
+ * Configuration for {@link LeavenGraphQLDriver}.
+ *
+ * Everything `@nestjs/graphql` understands is accepted unchanged — including
+ * `autoSchemaFile`, `typeDefs`, `path`, `context` and `useGlobalPrefix` — and
+ * the Leaven-specific options below are forwarded to the executor that serves
+ * the finished schema.
+ */
+export interface LeavenDriverConfig extends GqlModuleOptions {
+    /** Document/validation cache configuration passed to the executor. */
+    cache?: ExecutorConfig['cache'];
+    /** Collect per-operation metrics and expose them under `extensions.metrics`. */
+    metrics?: boolean;
+    /**
+     * Maximum allowed query complexity. Enforced by the executor itself, which
+     * rejects an over-budget document before any resolver runs.
+     */
+    maxComplexity?: number;
+    /** Maximum allowed query depth. Enforced by the executor at parse time. */
+    maxDepth?: number;
+    /** Serve GraphiQL on `GET <path>`. Defaults to `false`. */
+    playground?: boolean;
+    /** WebSocket endpoint advertised to GraphiQL, when subscriptions are served. */
+    subscriptionEndpoint?: string;
+    /** Final transformation applied to every error in the response. */
+    formatError?: (error: GraphQLFormattedError) => GraphQLFormattedError;
+    /**
+     * Include stack traces in error responses. Setting this also disables
+     * production masking, since a masked error carries no stack to include.
+     */
+    includeStacktraceInErrorResponses?: boolean;
+}
+/**
+ * A `@nestjs/graphql` driver that executes with Leaven.
+ *
+ * ## Why this class is the bridge
+ *
+ * `GraphQLModule.onModuleInit` calls `generateSchema()` before `start()`.
+ * `generateSchema()` is inherited from {@link AbstractGraphQLDriver} and
+ * delegates to `GraphQLFactory`, which builds the schema from your
+ * `@Resolver()` classes with NestJS's `ExternalContextCreator` wrapped around
+ * every field resolver. That wrapper is what runs guards, interceptors, pipes,
+ * filters and parameter decorators. By the time `start()` receives
+ * `options.schema`, the NestJS execution pipeline is already baked into it —
+ * this driver only has to execute that schema and serve it over HTTP.
+ *
+ * This is the opposite of `LeavenModule.forRoot({ typeDefs, resolvers })`,
+ * where resolvers are plain functions invoked directly by graphql-js and the
+ * NestJS pipeline never runs.
+ *
+ * @example
+ * ```typescript
+ * @Module({
+ *   imports: [
+ *     GraphQLModule.forRoot<LeavenDriverConfig>({
+ *       driver: LeavenGraphQLDriver,
+ *       autoSchemaFile: true,
+ *       playground: true,
+ *       cache: { maxSize: 1000 },
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+export declare class LeavenGraphQLDriver extends AbstractGraphQLDriver<LeavenDriverConfig> {
+    private executor;
+    private options;
+    /**
+     * Serve the schema `@nestjs/graphql` has already built.
+     *
+     * Registers a POST handler for GraphQL operations and, when `playground` is
+     * enabled, a GET handler rendering GraphiQL — both at the module's
+     * normalized path.
+     */
+    start(options: LeavenDriverConfig): Promise<void>;
+    /**
+     * Release the executor.
+     *
+     * `clearCaches()` is genuinely asynchronous for a remote cache (a Redis
+     * `FLUSH`), so it is awaited: dropping the promise would leave the clear
+     * unfinished and turn a rejecting cache into an unhandled rejection during
+     * shutdown.
+     */
+    stop(): Promise<void>;
+    /**
+     * The executor currently serving requests, or `null` before `start()` and
+     * after `stop()`.
+     */
+    getExecutor(): LeavenExecutor | null;
+    /**
+     * Execute one GraphQL operation and write the HTTP response.
+     */
+    private handleOperation;
+    /**
+     * Render GraphiQL.
+     */
+    private servePlayground;
+    /**
+     * Build the GraphQL context for one request.
+     *
+     * `req`/`res` are always present so guards and resolvers can reach the
+     * transport objects (this is what makes `ctx.req.user` work under Passport);
+     * a configured `context` factory or object is merged over them.
+     */
+    private buildContext;
+    /**
+     * Write a GraphQL response with the status the error-handling conventions
+     * require.
+     *
+     * A response carrying `data` is a spec-conformant partial success and stays
+     * 200 whatever the error codes say — anything else makes clients treat it as
+     * a network failure and discard data they were given. Only a total failure
+     * derives its status from the first error's `ErrorCode`, via the
+     * `ERROR_CODES` registry that `@leaven-graphql/http` uses.
+     */
+    private respond;
+    /**
+     * Guarantee an `ErrorCode`, apply production masking, then hand the result
+     * to a configured `formatError`.
+     *
+     * By this point {@link formatExecutionError} has already given every NestJS
+     * `HttpException` its `ErrorCode`; what is left here is the residue — a
+     * resolver that threw a plain `Error` — which must still be coded and, in
+     * production, masked.
+     *
+     * The executor reports errors as already-serialised `GraphQLFormattedError`s
+     * (`GraphQLError.toJSON()`), so `formatError` from `@leaven-graphql/errors`
+     * — whose input is an `Error`/`GraphQLError` — cannot be reused verbatim
+     * here; this reproduces its masking rule for the formatted shape. Errors
+     * *thrown* out of the executor do go through it, in
+     * {@link formatThrownError}.
+     */
+    private finalizeError;
+    /**
+     * Turn an error thrown out of the executor into a response error.
+     *
+     * Leaven errors keep their code, extensions and message. Unexpected errors
+     * are masked only in production — masking them in development would hide the
+     * real message from the developer — and `includeStacktraceInErrorResponses`
+     * suppresses masking outright, since a masked error carries no stack to
+     * include. This matches `LeavenDriver.execute`.
+     */
+    private formatThrownError;
+    /**
+     * Read the operation from the request.
+     *
+     * The adapter may hand over an already-parsed body, a raw string, or nothing
+     * at all when no body-parser is installed; the raw Fetch `Request` is the
+     * last resort.
+     */
+    private static readBody;
+    /**
+     * Serialize one execution error, translating a NestJS `HttpException` into
+     * the equivalent {@link ErrorCode}.
+     *
+     * Installed as the executor's `formatExecutionError` hook, which runs while
+     * the graphql-js `GraphQLError` is still intact — the only point at which
+     * `originalError` is still reachable. After `toJSON()` it is gone, and an
+     * `HttpException` (unlike a `LeavenError`) has no `extensions` of its own
+     * for graphql-js to adopt, so the error would otherwise reach the client as
+     * a bare `INTERNAL_ERROR` with a 500: a guard's `ForbiddenException` would be
+     * indistinguishable from a crash.
+     *
+     * `message`, `path` and `locations` are preserved exactly as serialized;
+     * only `extensions.code` is supplied.
+     */
+    private static formatExecutionError;
+}
+//# sourceMappingURL=graphql-driver.d.ts.map

package/dist/graphql-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql-driver.d.ts","sourceRoot":"","sources":["../src/graphql-driver.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAgB,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AA8C3E;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,sEAAsE;IACtE,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;IAChC,gFAAgF;IAChF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gFAAgF;IAChF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,mEAAmE;IACnE,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,qBAAqB,CAAC;IACtE;;;OAGG;IACH,iCAAiC,CAAC,EAAE,OAAO,CAAC;CAC7C;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,mBAAoB,SAAQ,qBAAqB,CAAC,kBAAkB,CAAC;IAChF,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,OAAO,CAAmC;IAElD;;;;;;OAMG;IACU,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC9D;;;;;;;OAOG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAOlC;;;OAGG;IACI,WAAW,IAAI,cAAc,GAAG,IAAI;IAI3C;;OAEG;YACW,eAAe;IAsE7B;;OAEG;IACH,OAAO,CAAC,eAAe;IASvB;;;;;;OAMG;YACW,YAAY;IAqB1B;;;;;;;;;OASG;IACH,OAAO,CAAC,OAAO;IAiCf;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,aAAa;IA2BrB;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;;OAMG;mBACkB,QAAQ;IAmB7B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;CAoBpC"}