@leaven-graphql/plugins 0.1.0 → 0.2.1

package/LICENSE

@@ -175,7 +175,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2026 Pegasus Heavy Industries LLC
+   Copyright 2026 Joseph Quinn
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -10,19 +10,66 @@ bun add @leaven-graphql/plugins
 
 ## Quick Start
 
+> **Wiring is manual today.** `ExecutorConfig` has no `plugins` option, and no
+> package in Leaven — core, http, ws, or nestjs — dispatches plugin hooks for
+> you. To run plugins you construct a `PluginManager` yourself and call its
+> hooks around `executor.execute`, as shown below.
+
 ```typescript
-import { createLoggingPlugin, createDepthLimitPlugin } from '@leaven-graphql/plugins';
-import { LeavenExecutor } from '@leaven-graphql/core';
+import { parse } from 'graphql';
+import { LeavenExecutor, type GraphQLRequest } from '@leaven-graphql/core';
+import {
+  createPluginManager,
+  createLoggingPlugin,
+  createDepthLimitPlugin,
+} from '@leaven-graphql/plugins';
+
+const executor = new LeavenExecutor({ schema });
 
-const executor = new LeavenExecutor({
+const plugins = createPluginManager({
   schema,
   plugins: [
-    createLoggingPlugin({ logger: console }),
+    createLoggingPlugin({ level: 'info' }),
     createDepthLimitPlugin({ maxDepth: 10 }),
   ],
 });
+
+// Optional: run the deferred `onRegister` hooks up front so initialization
+// failures surface here instead of on the first request.
+await plugins.init();
+
+async function handleRequest(request: GraphQLRequest, context: unknown) {
+  const pluginContext = plugins.createContext(request, context);
+
+  try {
+    const query = await plugins.beforeParse(request.query, pluginContext);
+    const document = await plugins.afterParse(parse(query), pluginContext);
+
+    // A `beforeExecute` hook may return a response to short-circuit execution
+    // (this is how the caching plugin serves a hit).
+    const cached = await plugins.beforeExecute(document, pluginContext);
+    if (cached) {
+      return await plugins.afterExecute(cached, pluginContext);
+    }
+
+    const { response } = await executor.execute({ ...request, query }, context);
+    return await plugins.afterExecute(response, pluginContext);
+  } catch (error) {
+    throw await plugins.onError(error as Error, pluginContext);
+  }
+}
 ```
 
+Two caveats of this arrangement:
+
+- `LeavenExecutor.execute` parses and validates internally, so the document you
+  hand to `afterParse` is parsed a second time by the executor. Hooks that
+  *rewrite* the document (`afterParse` returning a new `DocumentNode`) cannot
+  reach the executor this way; hooks that *inspect and reject* it — depth limit,
+  complexity — work exactly as intended.
+- `beforeValidate` / `afterValidate` are only dispatched if you validate the
+  document yourself. The pipeline above skips them.
+
 ## Built-in Plugins
 
 ### Logging Plugin
@@ -31,15 +78,41 @@ const executor = new LeavenExecutor({
 import { createLoggingPlugin } from '@leaven-graphql/plugins';
 
 const loggingPlugin = createLoggingPlugin({
+  // Minimum severity to emit (default: 'info')
+  level: 'info',
+  // Any object with debug/info/warn/error methods (default: console)
   logger: console,
-  logLevel: 'info',
-  includeVariables: false,
-  includeResult: false,
+});
+```
+
+`level` is the only filter; there are no options for including variables or
+results. Messages are emitted with a structured payload as the second argument:
+
+```typescript
+// level: 'debug' — before execution
+logger.debug('Executing GraphQL operation', {
+  operationName: 'getUser',
+  query: '{ user(id: "1") { name } }',
 });
 
-// Output:
-// [GraphQL] Query getUser started
-// [GraphQL] Query getUser completed in 15ms
+// level: 'info' or lower — after a successful execution
+logger.info('GraphQL operation completed', {
+  operationName: 'getUser',
+  duration: '15.23ms',
+});
+
+// after an execution that produced errors
+logger.error('GraphQL operation completed with errors', {
+  operationName: 'getUser',
+  duration: '15.23ms',
+  errors: [/* ... */],
+});
+
+// from the onError hook
+logger.error('GraphQL operation failed', {
+  operationName: 'getUser',
+  error: 'Something went wrong',
+});
 ```
 
 ### Tracing Plugin
@@ -47,21 +120,26 @@ const loggingPlugin = createLoggingPlugin({
 ```typescript
 import { createTracingPlugin } from '@leaven-graphql/plugins';
 
-const tracingPlugin = createTracingPlugin({
-  includeResolvers: true,
-  includeValidation: true,
-});
+const tracingPlugin = createTracingPlugin();
+```
 
-// Adds tracing to response extensions:
+Takes no options. It measures each phase from its own hooks, so a phase whose
+hooks were never dispatched is omitted rather than reported as a false zero.
+Durations and offsets are nanoseconds, Apollo Tracing style:
+
+```typescript
 // {
 //   extensions: {
 //     tracing: {
 //       version: 1,
-//       startTime: "2026-01-01T12:00:00.000Z",
+//       startTime: '2026-01-01T12:00:00.000Z',
+//       endTime: '2026-01-01T12:00:00.015Z',
 //       duration: 15000000,
-//       execution: { ... }
-//     }
-//   }
+//       parsing: { startOffset: 1000, duration: 250000 },
+//       validation: { startOffset: 260000, duration: 400000 },
+//       execution: { startOffset: 680000, duration: 14300000 },
+//     },
+//   },
 // }
 ```
 
@@ -70,175 +148,393 @@ const tracingPlugin = createTracingPlugin({
 ```typescript
 import { createDepthLimitPlugin } from '@leaven-graphql/plugins';
 
-const depthLimitPlugin = createDepthLimitPlugin({
-  maxDepth: 10,
-  ignoreIntrospection: true,
-});
+// Bare number form
+const depthLimitPlugin = createDepthLimitPlugin(10);
 
-// Rejects queries that are too deeply nested
+// Equivalent options-object form
+const alsoDepthLimit = createDepthLimitPlugin({ maxDepth: 10 });
 ```
 
+`maxDepth` is the only setting — there is no `ignoreIntrospection`. Only field
+selections add a level of depth. Fragment spreads are resolved through their
+definitions and each fragment is measured once per document, so repeated spreads
+cannot fan out exponentially and recursive fragments terminate.
+
+Throws `DepthLimitError` (HTTP 400, `extensions.code: 'DEPTH_LIMIT'`) when a
+query is too deep, or when analyzing the document would exceed the 100,000-node
+analysis budget (`extensions.reason: 'ANALYSIS_BUDGET_EXCEEDED'`).
+
 ### Complexity Plugin
 
 ```typescript
 import { createComplexityPlugin } from '@leaven-graphql/plugins';
 
 const complexityPlugin = createComplexityPlugin({
+  // Required: reject operations scoring above this
   maxComplexity: 1000,
-  defaultFieldComplexity: 1,
-  scalarCost: 0,
-  objectCost: 1,
-  listFactor: 10,
+  // Cost of a single field (default: 1)
+  defaultComplexity: 1,
+  // Page size assumed for a first/last/limit argument whose value cannot be
+  // determined — an unsupplied variable that also declares no default.
+  // Deliberately pessimistic, since the value is client-controlled (default: 100)
+  unknownMultiplier: 100,
 });
+```
+
+By default a field scores `defaultComplexity` plus its children, and the whole
+subtree is multiplied by any `first` / `last` / `limit` page size, resolved from
+a literal, the request variables, or the operation's declared variable default.
 
-// Calculates and enforces query complexity
+Supply a `calculator` to score fields yourself. Its return value is the field's
+**total** complexity, so incorporate `childComplexity` explicitly:
+
+```typescript
+const customComplexity = createComplexityPlugin({
+  maxComplexity: 1000,
+  calculator: (node, childComplexity) => {
+    const name = (node as { name?: { value: string } }).name?.value;
+    return (name === 'search' ? 10 : 1) + childComplexity;
+  },
+});
 ```
 
+Throws `ComplexityError` (HTTP 400, `extensions.code: 'COMPLEXITY_LIMIT'`) when
+an operation exceeds `maxComplexity`, or when analysis exceeds the node budget.
+
 ### Caching Plugin
 
 ```typescript
 import { createCachingPlugin } from '@leaven-graphql/plugins';
 
 const cachingPlugin = createCachingPlugin({
-  ttl: 60000,           // Cache TTL in ms
-  maxSize: 100,         // Max cached responses
-  keyGenerator: (request) => {
-    return `${request.query}:${JSON.stringify(request.variables)}`;
+  ttl: 60000,           // Cache TTL in ms (default: 60000)
+  maxSize: 100,         // Max cached responses, LRU-evicted (default: 100)
+  // Derives the cache key. Incorporate the caller's identity here so
+  // responses are never served across users.
+  keyFn: (context) => {
+    const userId = (context.context as { user?: { id: string } })?.user?.id ?? 'anonymous';
+    return `${userId}:${context.request.query}:${JSON.stringify(context.request.variables)}`;
   },
 });
 ```
 
+`createCachingPlugin` requires either a `keyFn` or an explicit
+`allowSharedCache: true`. Without a `keyFn` the cache key contains no user or
+tenant identity, so entries are shared across every caller — opt in only for
+data that is genuinely public:
+
+```typescript
+const publicCache = createCachingPlugin({ ttl: 60000, allowSharedCache: true });
+```
+
+A cache hit short-circuits `beforeExecute`, so resolvers — and any field-level
+authorization they perform — do not run.
+
 ## Creating Custom Plugins
 
+`createPlugin` takes **two** arguments: the metadata, then the hooks.
+
 ```typescript
 import { createPlugin } from '@leaven-graphql/plugins';
 
-const metricsPlugin = createPlugin({
-  name: 'metrics',
-  version: '1.0.0',
-
-  beforeParse: (query, context) => {
-    context.startTime = performance.now();
-    return query;
+const metricsPlugin = createPlugin(
+  {
+    name: 'metrics',
+    version: '1.0.0',
+    description: 'Records operation timings',
   },
+  {
+    beforeParse: (query, context) => {
+      // Per-request scratch space lives on `context.state`, a Map
+      context.state.set('startTime', performance.now());
+      return query;
+    },
+
+    afterExecute: (response, context) => {
+      const startTime = context.state.get('startTime') as number;
+
+      metrics.record({
+        operation: context.request.operationName,
+        duration: performance.now() - startTime,
+        errors: response.errors?.length ?? 0,
+      });
+
+      return response;
+    },
+
+    onError: (error, context) => {
+      metrics.recordError({
+        operation: context.request.operationName,
+        error: error.message,
+      });
+      return error;
+    },
+  }
+);
+```
 
-  afterExecute: (result, context) => {
-    const duration = performance.now() - context.startTime;
+A plugin is a plain object, so you can also write one by hand:
 
-    metrics.record({
-      operation: context.operationName,
-      duration,
-      errors: result.errors?.length ?? 0,
-    });
+```typescript
+import type { Plugin } from '@leaven-graphql/plugins';
 
-    return result;
+const auditPlugin: Plugin = {
+  metadata: { name: 'audit', version: '1.0.0' },
+  onRegister: async (schema) => {
+    await auditLog.open(schema);
   },
-
-  onError: (error, context) => {
-    metrics.recordError({
-      operation: context.operationName,
-      error: error.message,
-    });
+  onUnregister: async () => {
+    await auditLog.close();
   },
-});
+  afterExecute: (response) => response,
+};
 ```
 
 ## Plugin Manager
 
 ```typescript
-import { PluginManager, createPluginManager } from '@leaven-graphql/plugins';
+import {
+  createPluginManager,
+  createLoggingPlugin,
+  createTracingPlugin,
+  createDepthLimitPlugin,
+} from '@leaven-graphql/plugins';
 
 const manager = createPluginManager({
   schema,
   plugins: [
-    createLoggingPlugin({ logger: console }),
+    createLoggingPlugin({ level: 'info' }),
     createTracingPlugin(),
-    createDepthLimitPlugin({ maxDepth: 10 }),
+    createDepthLimitPlugin(10),
   ],
 });
 
-// Register additional plugins
-manager.register(myCustomPlugin);
+// Constructor plugins are inserted synchronously (duplicate names and
+// unsatisfied dependencies throw from the constructor), but their async
+// `onRegister` hooks are deferred. `init()` runs them; the manager also awaits
+// it lazily before the first registration change or hook dispatch.
+await manager.init();
+
+// Register additional plugins — async, and rejects if `onRegister` throws
+await manager.register(myCustomPlugin);
+
+// Unregister — resolves to false if no such plugin is registered
+const removed = await manager.unregister('logging'); // true
 
-// Unregister plugins
-manager.unregister('logging');
+// Inspect
+manager.has('tracing');       // boolean
+manager.get('tracing');       // Plugin | undefined
+manager.getPluginNames();     // string[], in registration order
+manager.size;                 // number
 
-// Get registered plugin names
-const plugins = manager.getPluginNames();
+// Remove everything, in reverse registration order
+await manager.clear();
 ```
 
+Registration is transactional: if a plugin's `onRegister` rejects, the plugin is
+removed from the registry and every hook index before the error propagates, so
+its request hooks never run and the registration can be retried.
+
+`init()` is likewise all-or-nothing — a failing deferred `onRegister` unwinds
+the hooks that already succeeded, and the failure is not cached, so a later call
+retries the whole run.
+
 ## Composing Plugins
 
-```typescript
-import { composePlugins } from '@leaven-graphql/plugins';
+`composePlugins` is **name-first and variadic** — the composite needs its own
+name, since it is registered like any other plugin.
 
-const combinedPlugin = composePlugins([
-  createLoggingPlugin({ logger: console }),
+```typescript
+import {
+  composePlugins,
+  createPluginManager,
+  createLoggingPlugin,
+  createTracingPlugin,
+  createDepthLimitPlugin,
+  createComplexityPlugin,
+} from '@leaven-graphql/plugins';
+
+const combinedPlugin = composePlugins(
+  'guardrails',
+  createLoggingPlugin({ level: 'info' }),
   createTracingPlugin(),
-  createDepthLimitPlugin({ maxDepth: 10 }),
-  createComplexityPlugin({ maxComplexity: 500 }),
-]);
+  createDepthLimitPlugin(10),
+  createComplexityPlugin({ maxComplexity: 500 })
+);
 
-const executor = new LeavenExecutor({
-  schema,
-  plugins: [combinedPlugin],
-});
+const manager = createPluginManager({ schema, plugins: [combinedPlugin] });
 ```
 
+The composite delegates every hook, plus `onRegister` / `onUnregister`, to its
+members in order — except `afterExecute`, which runs in reverse, mirroring
+`PluginManager`. Passing an array instead of spread arguments does **not** work:
+the array becomes the composite's `name` and no plugin is delegated to.
+
 ## Plugin Hooks
 
-| Hook | Description |
-|------|-------------|
-| `beforeParse` | Called before parsing the query string |
-| `afterParse` | Called after parsing, receives DocumentNode |
-| `beforeValidate` | Called before schema validation |
-| `afterValidate` | Called after validation with results |
-| `beforeExecute` | Called before resolver execution |
-| `afterExecute` | Called after execution with results |
-| `onError` | Called when an error occurs |
+| Hook | Signature | Return |
+|------|-----------|--------|
+| `beforeParse` | `(query: string, context)` | new query string, or nothing |
+| `afterParse` | `(document: DocumentNode, context)` | new document, or nothing |
+| `beforeValidate` | `(document: DocumentNode, context)` | nothing |
+| `afterValidate` | `(result: { valid, errors }, context)` | nothing |
+| `beforeExecute` | `(document: DocumentNode, context)` | a `GraphQLResponse` to short-circuit execution, or nothing |
+| `afterExecute` | `(response: GraphQLResponse, context)` | replacement response, or nothing |
+| `onError` | `(error: Error, context)` | replacement error, or nothing |
+
+Every hook may return a promise. `beforeExecute` receives the **document**, not
+just the context.
 
 ## API Reference
 
-### Plugin Interface
+### Plugin
 
 ```typescript
-interface Plugin {
+interface PluginMetadata {
+  /** Unique plugin name */
   name: string;
   version?: string;
+  description?: string;
+  /** Names of plugins that must already be registered */
+  dependencies?: string[];
+}
 
-  beforeParse?(query: string, context: PluginContext): string | void;
-  afterParse?(document: DocumentNode, context: PluginContext): DocumentNode | void;
-  beforeValidate?(document: DocumentNode, context: PluginContext): void;
-  afterValidate?(result: ValidationResult, context: PluginContext): void;
-  beforeExecute?(context: PluginContext): void | Promise<void>;
-  afterExecute?(result: ExecutionResult, context: PluginContext): ExecutionResult | void;
-  onError?(error: Error, context: PluginContext): void;
+interface PluginHooks {
+  beforeParse?: BeforeParseHook;
+  afterParse?: AfterParseHook;
+  beforeValidate?: BeforeValidateHook;
+  afterValidate?: AfterValidateHook;
+  beforeExecute?: BeforeExecuteHook;
+  afterExecute?: AfterExecuteHook;
+  onError?: OnErrorHook;
 }
+
+interface Plugin extends PluginHooks {
+  metadata: PluginMetadata;
+  onRegister?: (schema: GraphQLSchema) => void | Promise<void>;
+  onUnregister?: () => void | Promise<void>;
+}
+```
+
+### PluginContext
+
+```typescript
+interface PluginContext<TContext = unknown> {
+  schema: GraphQLSchema;
+  request: GraphQLRequest;
+  /** User context */
+  context: TContext;
+  /** Per-request scratch space shared between hooks */
+  state: Map<string, unknown>;
+}
+```
+
+### Hook types
+
+```typescript
+type BeforeParseHook = (
+  query: string,
+  context: PluginContext
+) => string | void | Promise<string | void>;
+
+type AfterParseHook = (
+  document: DocumentNode,
+  context: PluginContext
+) => DocumentNode | void | Promise<DocumentNode | void>;
+
+type BeforeValidateHook = (
+  document: DocumentNode,
+  context: PluginContext
+) => void | Promise<void>;
+
+type AfterValidateHook = (
+  result: { valid: boolean; errors: readonly GraphQLError[] },
+  context: PluginContext
+) => void | Promise<void>;
+
+type BeforeExecuteHook = (
+  document: DocumentNode,
+  context: PluginContext
+) => GraphQLResponse | void | Promise<GraphQLResponse | void>;
+
+type AfterExecuteHook = (
+  response: GraphQLResponse,
+  context: PluginContext
+) => GraphQLResponse | void | Promise<GraphQLResponse | void>;
+
+type OnErrorHook = (
+  error: Error,
+  context: PluginContext
+) => Error | void | Promise<Error | void>;
 ```
 
 ### createPlugin
 
 ```typescript
-function createPlugin(config: Plugin): Plugin;
+function createPlugin(metadata: PluginMetadata, hooks: PluginHooks): Plugin;
 ```
 
 ### composePlugins
 
 ```typescript
-function composePlugins(plugins: Plugin[]): Plugin;
+function composePlugins(name: string, ...plugins: Plugin[]): Plugin;
 ```
 
 ### PluginManager
 
 ```typescript
+interface PluginManagerConfig {
+  schema: GraphQLSchema;
+  plugins?: Plugin[];
+}
+
 class PluginManager {
-  register(plugin: Plugin): void;
-  unregister(name: string): void;
+  constructor(config: PluginManagerConfig);
+
+  /** Run deferred constructor `onRegister` hooks. Idempotent; retries on failure. */
+  init(): Promise<void>;
+
+  register(plugin: Plugin): Promise<void>;
+  /** Resolves false when no plugin by that name is registered. */
+  unregister(name: string): Promise<boolean>;
+
+  get(name: string): Plugin | undefined;
+  has(name: string): boolean;
   getPluginNames(): string[];
-  execute<T>(hookName: string, ...args: unknown[]): T;
+  get size(): number;
+  clear(): Promise<void>;
+
+  createContext<TContext>(
+    request: GraphQLRequest,
+    userContext: TContext
+  ): PluginContext<TContext>;
+
+  // Hook dispatch — call these around your own execution pipeline
+  beforeParse(query: string, context: PluginContext): Promise<string>;
+  afterParse(document: DocumentNode, context: PluginContext): Promise<DocumentNode>;
+  beforeValidate(document: DocumentNode, context: PluginContext): Promise<void>;
+  afterValidate(
+    result: { valid: boolean; errors: readonly GraphQLError[] },
+    context: PluginContext
+  ): Promise<void>;
+  /** Resolves to a response when a hook short-circuits, otherwise undefined. */
+  beforeExecute(
+    document: DocumentNode,
+    context: PluginContext
+  ): Promise<GraphQLResponse | undefined>;
+  afterExecute(
+    response: GraphQLResponse,
+    context: PluginContext
+  ): Promise<GraphQLResponse>;
+  onError(error: Error, context: PluginContext): Promise<Error>;
 }
+
+function createPluginManager(config: PluginManagerConfig): PluginManager;
 ```
 
+There is no generic `execute(hookName, ...args)` method — each hook has its own
+typed dispatch method above.
+
 ## License
 
-Apache 2.0 - Pegasus Heavy Industries LLC
+Apache 2.0 - Joseph Quinn