@leaven-graphql/plugins 0.1.0 → 0.2.1

package/dist/builtin.d.ts

@@ -1,10 +1,10 @@
 /**
  * @leaven-graphql/plugins - Built-in plugins
  *
- * Copyright 2026 Pegasus Heavy Industries LLC
+ * Copyright 2026 Joseph Quinn
  * Licensed under the Apache License, Version 2.0
  */
-import type { Plugin, PluginHooks, PluginMetadata } from './types';
+import type { Plugin, PluginContext, PluginHooks, PluginMetadata } from './types';
 /**
  * Create a custom plugin
  */
@@ -15,12 +15,38 @@ export declare function createPlugin(metadata: PluginMetadata, hooks: PluginHook
 export declare function composePlugins(name: string, ...plugins: Plugin[]): Plugin;
 /**
  * Create a caching plugin
+ *
+ * Caches successful responses keyed by query, operation name, and variables.
+ * On a cache hit, `beforeExecute` returns the cached response, which
+ * `PluginManager.beforeExecute` surfaces to its caller so execution can be
+ * skipped entirely. Pipelines that ignore that return value still receive the
+ * cached response, because `afterExecute` substitutes it for the freshly
+ * executed result.
+ *
+ * A cache hit skips execution entirely, so resolvers — and any field-level
+ * authorization they perform — do not run. Caller identity must therefore be
+ * part of the cache key, and the plugin refuses to be constructed unless that
+ * choice is explicit: supply a `keyFn` that incorporates the identity, or set
+ * `allowSharedCache: true` to opt in to a cache shared by every caller (safe
+ * only for data that is identical for everyone, e.g. fully public content).
  */
 export declare function createCachingPlugin(options?: {
     /** Maximum cache size */
     maxSize?: number;
     /** Cache TTL in milliseconds */
     ttl?: number;
+    /**
+     * Derives the cache key for a request. Use this to incorporate user or
+     * tenant identity (e.g. from `context.context`) so cached responses are
+     * not shared across callers.
+     */
+    keyFn?: (context: PluginContext) => string;
+    /**
+     * Opt in to a cache keyed only by query, operation name, and variables —
+     * with NO caller identity, so any caller may be served any other caller's
+     * response. Required when no `keyFn` is supplied.
+     */
+    allowSharedCache?: boolean;
 }): Plugin;
 /**
  * Create a logging plugin
@@ -38,21 +64,66 @@ export declare function createLoggingPlugin(options?: {
 }): Plugin;
 /**
  * Create a tracing plugin
+ *
+ * Emits Apollo Tracing-shaped data (nanosecond offsets/durations) in
+ * `extensions.tracing`. Parsing, validation, and execution phases are each
+ * measured by their own hooks; a phase whose hooks did not run in the request
+ * pipeline is omitted from the output rather than reported as a false zero.
  */
 export declare function createTracingPlugin(): Plugin;
 /**
  * Create a depth limit plugin
+ *
+ * Accepts either the bare number form `createDepthLimitPlugin(10)` or the
+ * options-object form `createDepthLimitPlugin({ maxDepth: 10 })`. Only field
+ * selections add a level of depth, matching `calculateQueryDepth` in
+ * `@leaven-graphql/core`. Fragment spreads are resolved through their
+ * definitions and each fragment is measured once per document, so a document
+ * that spreads fragments repeatedly cannot fan out exponentially; recursive
+ * fragments are detected and terminated after one unrolling.
+ *
+ * Throws {@link DepthLimitError} (HTTP 400, `extensions.code: 'DEPTH_LIMIT'`)
+ * when a query exceeds the configured depth, or when analyzing the document
+ * would exceed the node budget (`extensions.reason:
+ * 'ANALYSIS_BUDGET_EXCEEDED'`).
  */
-export declare function createDepthLimitPlugin(maxDepth: number): Plugin;
+export declare function createDepthLimitPlugin(maxDepth: number | {
+    maxDepth: number;
+}): Plugin;
 /**
  * Create a complexity plugin
+ *
+ * A field scores `defaultComplexity` plus its children, and the whole subtree
+ * is multiplied by any `first`/`last`/`limit` page size — literal or variable.
+ * Fragment spreads are resolved through their definitions and each fragment is
+ * scored once per operation, so repeated spreads cannot fan out exponentially;
+ * recursive fragments are detected and terminated.
+ *
+ * Throws {@link ComplexityError} (HTTP 400,
+ * `extensions.code: 'COMPLEXITY_LIMIT'`) when a query exceeds the configured
+ * complexity, or when analyzing the document would exceed the node budget
+ * (`extensions.reason: 'ANALYSIS_BUDGET_EXCEEDED'`).
  */
 export declare function createComplexityPlugin(options: {
     /** Maximum allowed complexity */
     maxComplexity: number;
     /** Default field complexity */
     defaultComplexity?: number;
-    /** Custom complexity calculator */
+    /**
+     * Page size assumed for a `first`/`last`/`limit` argument whose value cannot
+     * be determined from the document — a variable the request did not supply
+     * that also declares no default. Deliberately pessimistic: the value is
+     * client-controlled, so assuming a small page size would let an unbounded
+     * request score as a cheap one. Defaults to 100.
+     */
+    unknownMultiplier?: number;
+    /**
+     * Custom complexity calculator, invoked for each field node with the
+     * accumulated complexity of its children. Its return value is used as the
+     * field's TOTAL complexity (so incorporate `childComplexity` as desired).
+     * When omitted, a field scores `defaultComplexity` plus its children's
+     * complexity, all multiplied by any `first`/`last`/`limit` argument.
+     */
     calculator?: (node: unknown, childComplexity: number) => number;
 }): Plugin;
 //# sourceMappingURL=builtin.d.ts.map

package/dist/builtin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtin.d.ts","sourceRoot":"","sources":["../src/builtin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEnE;;GAEG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,WAAW,GACjB,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CA6EzE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE;IAC5C,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAsDT;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE;IAC5C,gBAAgB;IAChB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC5C,oBAAoB;IACpB,MAAM,CAAC,EAAE;QACP,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;QAC7C,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;QAC5C,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;QAC5C,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;KAC9C,CAAC;CACH,GAAG,MAAM,CA6DT;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAsD5C;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAuD/D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE;IAC9C,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mCAAmC;IACnC,UAAU,CAAC,EAAE,CACX,IAAI,EAAE,OAAO,EACb,eAAe,EAAE,MAAM,KACpB,MAAM,CAAC;CACb,GAAG,MAAM,CA0ET"}
+{"version":3,"file":"builtin.d.ts","sourceRoot":"","sources":["../src/builtin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAElF;;GAEG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,WAAW,GACjB,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CA0GzE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE;IAC5C,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,MAAM,CAAC;IAC3C;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,MAAM,CAgGT;AAOD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE;IAC5C,gBAAgB;IAChB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC5C,oBAAoB;IACpB,MAAM,CAAC,EAAE;QACP,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;QAC7C,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;QAC5C,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;QAC5C,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;KAC9C,CAAC;CACH,GAAG,MAAM,CA6DT;AAaD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CA+F5C;AAqID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GACtC,MAAM,CA4CR;AAsND;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE;IAC9C,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CACX,IAAI,EAAE,OAAO,EACb,eAAe,EAAE,MAAM,KACpB,MAAM,CAAC;CACb,GAAG,MAAM,CAoDT"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @leaven-graphql/plugins - Plugin system for Leaven
  *
- * Copyright 2026 Pegasus Heavy Industries LLC
+ * Copyright 2026 Joseph Quinn
  * Licensed under the Apache License, Version 2.0
  */
 export { PluginManager, createPluginManager } from './manager';