graphql-query-depth-limit-esm 0.1.0 → 2.0.0

package/dist/index.d.cts

@@ -0,0 +1,273 @@
+import * as graphql from 'graphql';
+import { ValidationRule } from 'graphql';
+
+/**
+ * Error extension codes for depth limit violations.
+ */
+declare const ERROR_CODES: {
+    readonly IGNORE_RULE_ERROR: "IGNORE_RULE_ERROR";
+    readonly QUERY_TOO_DEEP: "QUERY_TOO_DEEP";
+};
+
+/**
+ * Callback invoked after depth validation with per-operation depth results.
+ *
+ * @example
+ * ```typescript
+ * const callback: DepthCallback = (depths) => {
+ *   console.log(depths); // { "GetUser": 3, "ListPosts": 5 }
+ * };
+ * ```
+ */
+type DepthCallback = (depths: Record<string, number>) => void;
+/**
+ * Function signature for the depthLimit validation rule factory.
+ */
+interface DepthLimitFunction {
+    (maxDepth: number, options?: DepthLimitOptions, callback?: DepthCallback): graphql.ValidationRule;
+    (maxDepth: number, callback?: DepthCallback): graphql.ValidationRule;
+}
+/**
+ * Configuration options for the depth limit validation rule.
+ *
+ * @example
+ * ```typescript
+ * const options: DepthLimitOptions = {
+ *   caseInsensitiveIgnore: true,
+ *   directiveMode: "cap",
+ *   ignore: ["metadata", /.*Connection$/],
+ *   ignoreIntrospection: "typename",
+ *   ignoreMode: "exclude",
+ *   shortCircuit: true,
+ *   useDirective: true,
+ * };
+ * ```
+ */
+interface DepthLimitOptions {
+    /**
+     * Enable case-insensitive matching for string ignore rules.
+     *
+     * Does not affect `RegExp` rules — use the `i` flag on RegExp patterns
+     * for case-insensitive regex matching.
+     *
+     * @default false
+     */
+    caseInsensitiveIgnore?: boolean;
+    /**
+     * Controls how `@depth` directives interact with the global `maxDepth`.
+     *
+     * - `"cap"` (default): directives can only tighten below the global max
+     * - `"override"`: the first directive replaces the global max for its subtree
+     *
+     * @default "cap"
+     */
+    directiveMode?: DirectiveMode;
+    /** Rule or array of rules defining which fields to skip during depth calculation. */
+    ignore?: IgnoreRule | IgnoreRule[];
+    /**
+     * Controls which introspection fields are ignored during depth calculation.
+     *
+     * - `"all"`: ignore every `__`-prefixed field and skip its entire subtree
+     *   (regardless of `ignoreMode`)
+     * - `"typename"` (default): only ignore `__typename`
+     * - `"none"`: count all introspection fields toward depth
+     *
+     * **Note:** When set to `"all"`, introspection fields are always fully
+     * skipped — including their subtree — even when `ignoreMode` is `"exclude"`.
+     * This is intentional: `"all"` is a security hardening mode that completely
+     * eliminates introspection fields from depth calculation.
+     *
+     * @default "typename"
+     */
+    ignoreIntrospection?: IntrospectionMode;
+    /**
+     * Controls whether ignored fields skip their entire subtree or only the depth increment.
+     *
+     * - `"exclude"` (default): only the depth increment is skipped; children are still traversed
+     * - `"skip"`: the field and its entire subtree are excluded from depth calculation
+     *
+     * **Warning:** Using `"exclude"` on a **recursive** field (e.g., `friends: [User]` where
+     * `User` has a `friends` field) effectively allows unbounded depth on that edge because
+     * the depth increment is suppressed at every level of recursion. If the ignored field
+     * appears in a self-referential chain, the depth counter never advances along that path.
+     * Use `"skip"` instead if unbounded traversal is not intended, or combine `"exclude"`
+     * with a `@depth` directive on the field to cap the subtree independently.
+     *
+     * @default "exclude"
+     */
+    ignoreMode?: IgnoreMode;
+    /**
+     * Guard against unbounded depth from ignored recursive fields.
+     *
+     * When `true` and `ignoreMode` is `"exclude"`, the engine tracks which
+     * ignored field names have appeared on the current traversal path. If the
+     * same ignored field name is encountered again (indicating recursion),
+     * subsequent occurrences increment depth normally instead of being suppressed.
+     *
+     * This prevents the scenario where `ignoreMode: "exclude"` on a recursive
+     * field (e.g., `friends: [User]`) allows unbounded depth because the depth
+     * counter never advances.
+     *
+     * Has no effect when `ignoreMode` is `"skip"` (the subtree is already removed).
+     *
+     * **Note:** When no schema is available in the validation context, the
+     * recursion guard uses field names alone (without type prefixes). This
+     * means identically named fields on unrelated types may collide on the
+     * same path, causing conservative over-counting. For full type-aware
+     * tracking, ensure a schema is present.
+     *
+     * @default false
+     */
+    limitIgnoredRecursion?: boolean;
+    /**
+     * Bail immediately on the first depth violation instead of traversing
+     * the full query tree.
+     *
+     * By default, this is automatically determined:
+     * - `true` when no `callback` is provided (fastest path for validation-only use)
+     * - `false` when a `callback` is provided (full traversal needed for accurate depths)
+     *
+     * Set explicitly to override the automatic behavior. For example,
+     * `shortCircuit: false` without a callback traverses the full tree and
+     * reports exact depth in error messages rather than a lower-bound
+     * (`"at least N"`).
+     *
+     * @default undefined (auto-detected from callback presence)
+     */
+    shortCircuit?: boolean;
+    /**
+     * Read `@depth(max: Int!)` directives from field definitions.
+     *
+     * Requires a schema in the validation context. When no schema is available
+     * (e.g., custom `ValidationContext` with `getSchema()` returning null),
+     * this option silently falls back to the global `maxDepth` because
+     * directives cannot be resolved without type information.
+     *
+     * @default false
+     */
+    useDirective?: boolean;
+}
+/**
+ * Controls how `@depth` directives interact with the global `maxDepth`.
+ *
+ * - `"cap"` — directives can only tighten the limit below the global `maxDepth` (secure default)
+ * - `"override"` — the first directive replaces the global limit for its subtree
+ */
+type DirectiveMode = "cap" | "override";
+/**
+ * Controls how ignored fields affect depth traversal.
+ *
+ * - `"exclude"` — skip the depth increment but still traverse children (secure default)
+ * - `"skip"` — skip the field and its entire subtree
+ *
+ * **Caveat:** `"exclude"` on recursive fields allows unbounded depth along
+ * ignored edges because the depth counter never advances. See {@link DepthLimitOptions.ignoreMode}
+ * for details and mitigation strategies.
+ */
+type IgnoreMode = "exclude" | "skip";
+/**
+ * Rule for ignoring fields during depth calculation.
+ *
+ * - `string` — exact field name match (case-sensitive by default)
+ * - `RegExp` — pattern match against field names
+ * - `function` — custom predicate receiving the field name
+ *
+ * **Note:** User-provided `RegExp` patterns are executed against field names.
+ * Patterns with catastrophic backtracking (e.g., `/^(a+)+$/`) may cause
+ * performance issues. Use simple, linear-time patterns where possible.
+ *
+ * @example
+ * ```typescript
+ * const rules: IgnoreRule[] = [
+ *   "metadata",
+ *   /^internal/,
+ *   (name) => name.endsWith("Connection"),
+ * ];
+ * ```
+ */
+type IgnoreRule = ((fieldName: string) => boolean) | RegExp | string;
+/**
+ * Controls which introspection fields are ignored during depth calculation.
+ *
+ * - `"all"` — ignore every `__`-prefixed field and skip its entire subtree,
+ *   regardless of `ignoreMode`
+ * - `"typename"` — only ignore `__typename` (secure default)
+ * - `"none"` — count all introspection fields toward depth
+ *
+ * **Note:** Scalar introspection fields (e.g., `__typename`) never increase
+ * depth regardless of this setting because only composite fields with nested
+ * selections contribute to depth. This setting controls whether such fields
+ * are _ignored_ (skipping the depth increment entirely), which matters when
+ * they appear as nested selections within composite fields.
+ */
+type IntrospectionMode = "all" | "none" | "typename";
+
+/**
+ * Creates a GraphQL validation rule that limits query depth.
+ *
+ * Prevents DoS attacks and resource exhaustion from excessively deep queries
+ * by enforcing a maximum depth on operations. Supports per-field overrides
+ * via the `@depth` directive, customizable ignore rules, and an optional
+ * callback for monitoring.
+ *
+ * Security considerations:
+ * - The global `maxDepth` is a hard ceiling by default (`directiveMode: "cap"`)
+ * - Correctly handles fragments reused at different depths
+ * - Circular fragment references are detected per-path
+ * - Only `__typename` is ignored by default (`ignoreIntrospection: "typename"`)
+ * - Short-circuits on first violation when no callback is provided
+ *
+ * Limitations:
+ * - Variables in `@depth` directives are not supported (falls back to global limit)
+ * - Field names are case-sensitive by default (use `caseInsensitiveIgnore` if needed)
+ * - `useDirective: true` requires a schema in the validation context; without one
+ *   it silently falls back to the global limit (directives cannot be resolved)
+ * - RegExp ignore rules are executed against field names; patterns with catastrophic
+ *   backtracking (e.g., `/^(a+)+$/`) may cause performance issues
+ *
+ * @param maxDepth - Maximum allowed depth for queries (must be a non-negative integer)
+ * @param options - Optional configuration for ignore rules, directives, and case sensitivity
+ * @param callback - Optional callback invoked with depth results for each operation
+ * @returns A GraphQL validation rule function
+ * @throws {Error} If `maxDepth` is not a non-negative integer
+ *
+ * @example
+ * ```typescript
+ * import { depthLimit } from "graphql-query-depth-limit-esm";
+ * import { validate } from "graphql";
+ *
+ * const errors = validate(schema, document, [
+ *   depthLimit(5, {
+ *     ignore: ["friends", /.*Connection$/],
+ *     useDirective: true,
+ *   }),
+ * ]);
+ *
+ * const withCallback = depthLimit(5, (depths) => {
+ *   console.log(depths);
+ * });
+ * ```
+ */
+declare function depthLimit(maxDepth: number, callback?: DepthCallback): ValidationRule;
+declare function depthLimit(maxDepth: number, options?: DepthLimitOptions, callback?: DepthCallback): ValidationRule;
+
+/**
+ * GraphQL SDL type definition for the `@depth` directive.
+ *
+ * Include this in your schema definition to enable per-field depth
+ * overrides when using `depthLimit` with `{ useDirective: true }`.
+ *
+ * @example
+ * ```ts
+ * import { makeExecutableSchema } from "@graphql-tools/schema";
+ * import { depthDirectiveTypeDefs } from "graphql-query-depth-limit-esm";
+ *
+ * const schema = makeExecutableSchema({
+ *   typeDefs: [depthDirectiveTypeDefs, yourTypeDefs],
+ *   resolvers,
+ * });
+ * ```
+ */
+declare const depthDirectiveTypeDefs = "\n  directive @depth(max: Int!) on FIELD_DEFINITION\n";
+
+export { type DepthCallback, type DepthLimitFunction, type DepthLimitOptions, type DirectiveMode, ERROR_CODES, type IgnoreMode, type IgnoreRule, type IntrospectionMode, depthDirectiveTypeDefs, depthLimit };

package/dist/index.d.ts

@@ -1,11 +1,273 @@
+import * as graphql from 'graphql';
+import { ValidationRule } from 'graphql';
+
 /**
- * GraphQL Query Depth Limiting - ESM Compatible
+ * Error extension codes for depth limit violations.
+ */
+declare const ERROR_CODES: {
+    readonly IGNORE_RULE_ERROR: "IGNORE_RULE_ERROR";
+    readonly QUERY_TOO_DEEP: "QUERY_TOO_DEEP";
+};
+
+/**
+ * Callback invoked after depth validation with per-operation depth results.
+ *
+ * @example
+ * ```typescript
+ * const callback: DepthCallback = (depths) => {
+ *   console.log(depths); // { "GetUser": 3, "ListPosts": 5 }
+ * };
+ * ```
+ */
+type DepthCallback = (depths: Record<string, number>) => void;
+/**
+ * Function signature for the depthLimit validation rule factory.
+ */
+interface DepthLimitFunction {
+    (maxDepth: number, options?: DepthLimitOptions, callback?: DepthCallback): graphql.ValidationRule;
+    (maxDepth: number, callback?: DepthCallback): graphql.ValidationRule;
+}
+/**
+ * Configuration options for the depth limit validation rule.
+ *
+ * @example
+ * ```typescript
+ * const options: DepthLimitOptions = {
+ *   caseInsensitiveIgnore: true,
+ *   directiveMode: "cap",
+ *   ignore: ["metadata", /.*Connection$/],
+ *   ignoreIntrospection: "typename",
+ *   ignoreMode: "exclude",
+ *   shortCircuit: true,
+ *   useDirective: true,
+ * };
+ * ```
+ */
+interface DepthLimitOptions {
+    /**
+     * Enable case-insensitive matching for string ignore rules.
+     *
+     * Does not affect `RegExp` rules — use the `i` flag on RegExp patterns
+     * for case-insensitive regex matching.
+     *
+     * @default false
+     */
+    caseInsensitiveIgnore?: boolean;
+    /**
+     * Controls how `@depth` directives interact with the global `maxDepth`.
+     *
+     * - `"cap"` (default): directives can only tighten below the global max
+     * - `"override"`: the first directive replaces the global max for its subtree
+     *
+     * @default "cap"
+     */
+    directiveMode?: DirectiveMode;
+    /** Rule or array of rules defining which fields to skip during depth calculation. */
+    ignore?: IgnoreRule | IgnoreRule[];
+    /**
+     * Controls which introspection fields are ignored during depth calculation.
+     *
+     * - `"all"`: ignore every `__`-prefixed field and skip its entire subtree
+     *   (regardless of `ignoreMode`)
+     * - `"typename"` (default): only ignore `__typename`
+     * - `"none"`: count all introspection fields toward depth
+     *
+     * **Note:** When set to `"all"`, introspection fields are always fully
+     * skipped — including their subtree — even when `ignoreMode` is `"exclude"`.
+     * This is intentional: `"all"` is a security hardening mode that completely
+     * eliminates introspection fields from depth calculation.
+     *
+     * @default "typename"
+     */
+    ignoreIntrospection?: IntrospectionMode;
+    /**
+     * Controls whether ignored fields skip their entire subtree or only the depth increment.
+     *
+     * - `"exclude"` (default): only the depth increment is skipped; children are still traversed
+     * - `"skip"`: the field and its entire subtree are excluded from depth calculation
+     *
+     * **Warning:** Using `"exclude"` on a **recursive** field (e.g., `friends: [User]` where
+     * `User` has a `friends` field) effectively allows unbounded depth on that edge because
+     * the depth increment is suppressed at every level of recursion. If the ignored field
+     * appears in a self-referential chain, the depth counter never advances along that path.
+     * Use `"skip"` instead if unbounded traversal is not intended, or combine `"exclude"`
+     * with a `@depth` directive on the field to cap the subtree independently.
+     *
+     * @default "exclude"
+     */
+    ignoreMode?: IgnoreMode;
+    /**
+     * Guard against unbounded depth from ignored recursive fields.
+     *
+     * When `true` and `ignoreMode` is `"exclude"`, the engine tracks which
+     * ignored field names have appeared on the current traversal path. If the
+     * same ignored field name is encountered again (indicating recursion),
+     * subsequent occurrences increment depth normally instead of being suppressed.
+     *
+     * This prevents the scenario where `ignoreMode: "exclude"` on a recursive
+     * field (e.g., `friends: [User]`) allows unbounded depth because the depth
+     * counter never advances.
+     *
+     * Has no effect when `ignoreMode` is `"skip"` (the subtree is already removed).
+     *
+     * **Note:** When no schema is available in the validation context, the
+     * recursion guard uses field names alone (without type prefixes). This
+     * means identically named fields on unrelated types may collide on the
+     * same path, causing conservative over-counting. For full type-aware
+     * tracking, ensure a schema is present.
+     *
+     * @default false
+     */
+    limitIgnoredRecursion?: boolean;
+    /**
+     * Bail immediately on the first depth violation instead of traversing
+     * the full query tree.
+     *
+     * By default, this is automatically determined:
+     * - `true` when no `callback` is provided (fastest path for validation-only use)
+     * - `false` when a `callback` is provided (full traversal needed for accurate depths)
+     *
+     * Set explicitly to override the automatic behavior. For example,
+     * `shortCircuit: false` without a callback traverses the full tree and
+     * reports exact depth in error messages rather than a lower-bound
+     * (`"at least N"`).
+     *
+     * @default undefined (auto-detected from callback presence)
+     */
+    shortCircuit?: boolean;
+    /**
+     * Read `@depth(max: Int!)` directives from field definitions.
+     *
+     * Requires a schema in the validation context. When no schema is available
+     * (e.g., custom `ValidationContext` with `getSchema()` returning null),
+     * this option silently falls back to the global `maxDepth` because
+     * directives cannot be resolved without type information.
+     *
+     * @default false
+     */
+    useDirective?: boolean;
+}
+/**
+ * Controls how `@depth` directives interact with the global `maxDepth`.
+ *
+ * - `"cap"` — directives can only tighten the limit below the global `maxDepth` (secure default)
+ * - `"override"` — the first directive replaces the global limit for its subtree
+ */
+type DirectiveMode = "cap" | "override";
+/**
+ * Controls how ignored fields affect depth traversal.
+ *
+ * - `"exclude"` — skip the depth increment but still traverse children (secure default)
+ * - `"skip"` — skip the field and its entire subtree
+ *
+ * **Caveat:** `"exclude"` on recursive fields allows unbounded depth along
+ * ignored edges because the depth counter never advances. See {@link DepthLimitOptions.ignoreMode}
+ * for details and mitigation strategies.
+ */
+type IgnoreMode = "exclude" | "skip";
+/**
+ * Rule for ignoring fields during depth calculation.
+ *
+ * - `string` — exact field name match (case-sensitive by default)
+ * - `RegExp` — pattern match against field names
+ * - `function` — custom predicate receiving the field name
+ *
+ * **Note:** User-provided `RegExp` patterns are executed against field names.
+ * Patterns with catastrophic backtracking (e.g., `/^(a+)+$/`) may cause
+ * performance issues. Use simple, linear-time patterns where possible.
+ *
+ * @example
+ * ```typescript
+ * const rules: IgnoreRule[] = [
+ *   "metadata",
+ *   /^internal/,
+ *   (name) => name.endsWith("Connection"),
+ * ];
+ * ```
+ */
+type IgnoreRule = ((fieldName: string) => boolean) | RegExp | string;
+/**
+ * Controls which introspection fields are ignored during depth calculation.
+ *
+ * - `"all"` — ignore every `__`-prefixed field and skip its entire subtree,
+ *   regardless of `ignoreMode`
+ * - `"typename"` — only ignore `__typename` (secure default)
+ * - `"none"` — count all introspection fields toward depth
+ *
+ * **Note:** Scalar introspection fields (e.g., `__typename`) never increase
+ * depth regardless of this setting because only composite fields with nested
+ * selections contribute to depth. This setting controls whether such fields
+ * are _ignored_ (skipping the depth increment entirely), which matters when
+ * they appear as nested selections within composite fields.
+ */
+type IntrospectionMode = "all" | "none" | "typename";
+
+/**
+ * Creates a GraphQL validation rule that limits query depth.
+ *
+ * Prevents DoS attacks and resource exhaustion from excessively deep queries
+ * by enforcing a maximum depth on operations. Supports per-field overrides
+ * via the `@depth` directive, customizable ignore rules, and an optional
+ * callback for monitoring.
+ *
+ * Security considerations:
+ * - The global `maxDepth` is a hard ceiling by default (`directiveMode: "cap"`)
+ * - Correctly handles fragments reused at different depths
+ * - Circular fragment references are detected per-path
+ * - Only `__typename` is ignored by default (`ignoreIntrospection: "typename"`)
+ * - Short-circuits on first violation when no callback is provided
+ *
+ * Limitations:
+ * - Variables in `@depth` directives are not supported (falls back to global limit)
+ * - Field names are case-sensitive by default (use `caseInsensitiveIgnore` if needed)
+ * - `useDirective: true` requires a schema in the validation context; without one
+ *   it silently falls back to the global limit (directives cannot be resolved)
+ * - RegExp ignore rules are executed against field names; patterns with catastrophic
+ *   backtracking (e.g., `/^(a+)+$/`) may cause performance issues
+ *
+ * @param maxDepth - Maximum allowed depth for queries (must be a non-negative integer)
+ * @param options - Optional configuration for ignore rules, directives, and case sensitivity
+ * @param callback - Optional callback invoked with depth results for each operation
+ * @returns A GraphQL validation rule function
+ * @throws {Error} If `maxDepth` is not a non-negative integer
+ *
+ * @example
+ * ```typescript
+ * import { depthLimit } from "graphql-query-depth-limit-esm";
+ * import { validate } from "graphql";
+ *
+ * const errors = validate(schema, document, [
+ *   depthLimit(5, {
+ *     ignore: ["friends", /.*Connection$/],
+ *     useDirective: true,
+ *   }),
+ * ]);
+ *
+ * const withCallback = depthLimit(5, (depths) => {
+ *   console.log(depths);
+ * });
+ * ```
+ */
+declare function depthLimit(maxDepth: number, callback?: DepthCallback): ValidationRule;
+declare function depthLimit(maxDepth: number, options?: DepthLimitOptions, callback?: DepthCallback): ValidationRule;
+
+/**
+ * GraphQL SDL type definition for the `@depth` directive.
+ *
+ * Include this in your schema definition to enable per-field depth
+ * overrides when using `depthLimit` with `{ useDirective: true }`.
  *
- * A GraphQL validation rule that limits the depth of queries.
- * Prevents deeply nested queries from overloading your server.
+ * @example
+ * ```ts
+ * import { makeExecutableSchema } from "@graphql-tools/schema";
+ * import { depthDirectiveTypeDefs } from "graphql-query-depth-limit-esm";
  *
- * @packageDocumentation
+ * const schema = makeExecutableSchema({
+ *   typeDefs: [depthDirectiveTypeDefs, yourTypeDefs],
+ *   resolvers,
+ * });
+ * ```
  */
-export { depthLimit } from "./depthLimit.js";
-export type { DepthCallback, DepthLimitFunction, DepthLimitOptions, IgnoreRule, } from "./types.js";
-//# sourceMappingURL=index.d.ts.map
+declare const depthDirectiveTypeDefs = "\n  directive @depth(max: Int!) on FIELD_DEFINITION\n";
+
+export { type DepthCallback, type DepthLimitFunction, type DepthLimitOptions, type DirectiveMode, ERROR_CODES, type IgnoreMode, type IgnoreRule, type IntrospectionMode, depthDirectiveTypeDefs, depthLimit };