graphql-query-depth-limit-esm 2.0.2 → 2.0.5

package/README.md

@@ -6,13 +6,11 @@
 [![npm version](https://img.shields.io/npm/v/graphql-query-depth-limit-esm?logo=npm)](https://www.npmjs.com/package/graphql-query-depth-limit-esm)
 [![npm downloads](https://img.shields.io/npm/dm/graphql-query-depth-limit-esm?logo=npm)](https://www.npmjs.com/package/graphql-query-depth-limit-esm)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Node >=22](https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Node >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![Provenance](https://img.shields.io/badge/provenance-verified-brightgreen?logo=npm)](https://www.npmjs.com/package/graphql-query-depth-limit-esm)
 
 Production-ready GraphQL query depth limiting as a validation rule. Prevents denial-of-service attacks from deeply nested queries by enforcing a configurable maximum depth.
 
-**[Interactive demo](https://lafittemehdy.github.io/graphql-query-depth-limit-esm/)** — see depth analysis in action with preset queries, an AST tree viewer, and a depth gauge.
-
 ## Interactive Demo
 
 **[Try it live](https://lafittemehdy.github.io/graphql-query-depth-limit-esm/)** or run locally:
@@ -23,7 +21,7 @@ npm install
 npm run dev
 ```
 
-Includes preset queries (simple lookups through deeply nested attacks), an AST tree viewer with depth badges, and a depth gauge with pass/fail verdict.
+Preset queries (simple lookups through deeply nested attacks), an AST tree viewer with depth badges, and a depth gauge with pass/fail verdict.
 
 ## Features
 
@@ -494,6 +492,21 @@ query {
 # Maximum depth: 3
 ```
 
+## Performance
+
+The depth engine uses **iterative DFS** (not recursion) to prevent stack overflow on adversarial queries and to keep traversal overhead constant regardless of nesting depth.
+
+| Characteristic | Detail |
+|---|---|
+| **Algorithm** | Iterative depth-first search with explicit stack |
+| **Time complexity** | O(n) where n = total selection nodes in the query |
+| **Short-circuit** | Stops on first violation when no callback is provided |
+| **Fragment cycles** | Detected per-path with minimal Set allocations |
+| **Stack safety** | No recursion — immune to stack overflow on deep queries |
+| **Runtime dependencies** | Zero — only `graphql` as a peer dependency |
+
+Typical validation completes in **sub-millisecond** time for standard queries (< 50 fields). Even adversarial queries with hundreds of nested selections are analyzed in **single-digit milliseconds** thanks to early termination and per-path fragment cycle detection.
+
 ## Migrating from v1 to v2
 
 v2 introduces three **breaking changes** with more secure defaults:

package/dist/index.cjs

@@ -211,8 +211,11 @@ function calculateDepth(caches, config, fragments, maxDepth, node, parentType, s
     if (!frame.node.selectionSet) {
       continue;
     }
-    const nextFrames = [];
-    for (const selection of frame.node.selectionSet.selections) {
+    for (let selectionIndex = frame.node.selectionSet.selections.length - 1; selectionIndex >= 0; selectionIndex--) {
+      const selection = frame.node.selectionSet.selections[selectionIndex];
+      if (!selection) {
+        continue;
+      }
       switch (selection.kind) {
         case import_graphql2.Kind.FIELD: {
           const fieldName = selection.name.value;
@@ -293,7 +296,7 @@ function calculateDepth(caches, config, fragments, maxDepth, node, parentType, s
               deepestViolation = violation;
             }
           }
-          nextFrames.push({
+          stack.push({
             currentDepth: newDepth,
             hasDirectiveLimit,
             ignoredFieldsOnPath,
@@ -317,7 +320,7 @@ function calculateDepth(caches, config, fragments, maxDepth, node, parentType, s
           const fragmentVisited = new Set(frame.visitedFragments);
           fragmentVisited.add(fragmentName);
           const parentType2 = fragment.typeCondition ? resolveTypeCondition(fragment.typeCondition.name.value, schema, frame.parentType) : frame.parentType;
-          nextFrames.push({
+          stack.push({
             currentDepth: frame.currentDepth,
             hasDirectiveLimit: frame.hasDirectiveLimit,
             ignoredFieldsOnPath: frame.ignoredFieldsOnPath,
@@ -331,7 +334,7 @@ function calculateDepth(caches, config, fragments, maxDepth, node, parentType, s
         }
         case import_graphql2.Kind.INLINE_FRAGMENT: {
           const parentType2 = selection.typeCondition ? resolveTypeCondition(selection.typeCondition.name.value, schema, frame.parentType) : frame.parentType;
-          nextFrames.push({
+          stack.push({
             currentDepth: frame.currentDepth,
             hasDirectiveLimit: frame.hasDirectiveLimit,
             ignoredFieldsOnPath: frame.ignoredFieldsOnPath,
@@ -349,12 +352,6 @@ function calculateDepth(caches, config, fragments, maxDepth, node, parentType, s
         }
       }
     }
-    for (let index = nextFrames.length - 1; index >= 0; index--) {
-      const nextFrame = nextFrames[index];
-      if (nextFrame) {
-        stack.push(nextFrame);
-      }
-    }
   }
   return { depth: globalMaxDepth, violation: deepestViolation };
 }
@@ -455,10 +452,129 @@ function resolveTypeCondition(typeConditionName, schema, currentParentType) {
   return currentParentType;
 }
 
-// src/depth-limit.ts
+// src/depth-options.ts
 var DIRECTIVE_MODES = /* @__PURE__ */ new Set(["cap", "override"]);
 var IGNORE_MODES = /* @__PURE__ */ new Set(["exclude", "skip"]);
 var INTROSPECTION_MODES = /* @__PURE__ */ new Set(["all", "none", "typename"]);
+function assertBooleanOption(name, value) {
+  if (value !== void 0 && typeof value !== "boolean") {
+    throw new TypeError(`Invalid ${name}: expected boolean, received ${typeof value}.`);
+  }
+}
+function isIgnoreRule(rule) {
+  return typeof rule === "function" || rule instanceof RegExp || typeof rule === "string";
+}
+function normalizeIgnoreRules(ignore) {
+  if (ignore == null) {
+    return void 0;
+  }
+  const rules = Array.isArray(ignore) ? ignore : [ignore];
+  for (const [index, rule] of rules.entries()) {
+    if (!isIgnoreRule(rule)) {
+      const receivedType = Array.isArray(rule) ? "array" : rule === null ? "null" : typeof rule;
+      throw new TypeError(
+        `Invalid ignore rule at index ${index}: expected string, RegExp, or function, received ${receivedType}.`
+      );
+    }
+    if (rule instanceof RegExp) {
+      const reason = isUnsafeRegExp(rule);
+      if (reason) {
+        throw new TypeError(
+          `Unsafe RegExp ignore rule at index ${index}: /${rule.source}/${rule.flags} - ${reason}. Use a simpler pattern to avoid catastrophic backtracking.`
+        );
+      }
+    }
+  }
+  return rules;
+}
+function normalizeDepthLimitOptions(options) {
+  assertBooleanOption("caseInsensitiveIgnore", options.caseInsensitiveIgnore);
+  if (options.directiveMode !== void 0 && !DIRECTIVE_MODES.has(options.directiveMode)) {
+    throw new TypeError(
+      `Invalid directiveMode: "${options.directiveMode}". Must be "cap" or "override".`
+    );
+  }
+  if (options.ignoreIntrospection !== void 0 && !INTROSPECTION_MODES.has(options.ignoreIntrospection)) {
+    throw new TypeError(
+      `Invalid ignoreIntrospection: "${options.ignoreIntrospection}". Must be "all", "none", or "typename".`
+    );
+  }
+  if (options.ignoreMode !== void 0 && !IGNORE_MODES.has(options.ignoreMode)) {
+    throw new TypeError(
+      `Invalid ignoreMode: "${options.ignoreMode}". Must be "exclude" or "skip".`
+    );
+  }
+  assertBooleanOption("limitIgnoredRecursion", options.limitIgnoredRecursion);
+  assertBooleanOption("shortCircuit", options.shortCircuit);
+  assertBooleanOption("useDirective", options.useDirective);
+  const ignore = normalizeIgnoreRules(options.ignore);
+  return { ...options, ignore };
+}
+function normalizeDepthLimitArgs(options, callback) {
+  if (callback !== void 0 && typeof callback !== "function") {
+    throw new TypeError("Invalid callback: expected a function.");
+  }
+  if (typeof options === "function") {
+    if (callback) {
+      throw new TypeError("Invalid depthLimit arguments: callback provided twice.");
+    }
+    return { callback: options, options: void 0 };
+  }
+  if (options !== void 0 && (options === null || typeof options !== "object" || Array.isArray(options))) {
+    const receivedType = Array.isArray(options) ? "array" : options === null ? "null" : typeof options;
+    throw new TypeError(`Invalid options: expected an object, received ${receivedType}.`);
+  }
+  return {
+    callback,
+    options: options ? normalizeDepthLimitOptions(options) : void 0
+  };
+}
+function createDepthResultRecord() {
+  return /* @__PURE__ */ Object.create(null);
+}
+function createOperationNameAllocator(operations) {
+  const explicitNames = /* @__PURE__ */ new Set();
+  for (const operation of operations) {
+    if (operation.name?.value) {
+      explicitNames.add(operation.name.value);
+    }
+  }
+  const usedNames = /* @__PURE__ */ new Set();
+  const namedCounts = /* @__PURE__ */ new Map();
+  let anonymousCount = 0;
+  return (operation) => {
+    const explicitName = operation.name?.value;
+    if (explicitName) {
+      let suffix = namedCounts.get(explicitName) ?? 0;
+      let candidate2 = suffix === 0 ? explicitName : `${explicitName}_${suffix}`;
+      while (usedNames.has(candidate2) || suffix > 0 && explicitNames.has(candidate2)) {
+        suffix++;
+        candidate2 = `${explicitName}_${suffix}`;
+      }
+      namedCounts.set(explicitName, suffix + 1);
+      usedNames.add(candidate2);
+      return candidate2;
+    }
+    anonymousCount++;
+    let candidate = anonymousCount === 1 ? "[anonymous]" : `[anonymous:${anonymousCount}]`;
+    while (usedNames.has(candidate) || explicitNames.has(candidate)) {
+      anonymousCount++;
+      candidate = `[anonymous:${anonymousCount}]`;
+    }
+    usedNames.add(candidate);
+    return candidate;
+  };
+}
+function setDepthResult(target, key, value) {
+  Object.defineProperty(target, key, {
+    configurable: true,
+    enumerable: true,
+    value,
+    writable: true
+  });
+}
+
+// src/depth-limit.ts
 function depthLimit(maxDepth, options, callback) {
   if (!Number.isInteger(maxDepth) || maxDepth < 0) {
     throw new Error(`Invalid maxDepth: ${maxDepth}. Must be a non-negative integer.`);
@@ -466,11 +582,6 @@ function depthLimit(maxDepth, options, callback) {
   const normalized = normalizeDepthLimitArgs(options, callback);
   return createValidationRule(maxDepth, normalized.options, normalized.callback);
 }
-function assertBooleanOption(name, value) {
-  if (value !== void 0 && typeof value !== "boolean") {
-    throw new TypeError(`Invalid ${name}: expected boolean, received ${typeof value}.`);
-  }
-}
 function createValidationRule(maxDepth, options, callback) {
   const shortCircuit = options?.shortCircuit ?? callback == null;
   return function depthLimitValidationRule(context) {
@@ -552,118 +663,6 @@ function createValidationRule(maxDepth, options, callback) {
     return {};
   };
 }
-function isIgnoreRule(rule) {
-  return typeof rule === "function" || rule instanceof RegExp || typeof rule === "string";
-}
-function normalizeDepthLimitArgs(options, callback) {
-  if (callback !== void 0 && typeof callback !== "function") {
-    throw new TypeError("Invalid callback: expected a function.");
-  }
-  if (typeof options === "function") {
-    if (callback) {
-      throw new TypeError("Invalid depthLimit arguments: callback provided twice.");
-    }
-    return { callback: options, options: void 0 };
-  }
-  if (options !== void 0 && (options === null || typeof options !== "object" || Array.isArray(options))) {
-    const receivedType = Array.isArray(options) ? "array" : options === null ? "null" : typeof options;
-    throw new TypeError(`Invalid options: expected an object, received ${receivedType}.`);
-  }
-  return {
-    callback,
-    options: options ? normalizeDepthLimitOptions(options) : void 0
-  };
-}
-function normalizeDepthLimitOptions(options) {
-  assertBooleanOption("caseInsensitiveIgnore", options.caseInsensitiveIgnore);
-  if (options.directiveMode !== void 0 && !DIRECTIVE_MODES.has(options.directiveMode)) {
-    throw new TypeError(
-      `Invalid directiveMode: "${options.directiveMode}". Must be "cap" or "override".`
-    );
-  }
-  if (options.ignoreIntrospection !== void 0 && !INTROSPECTION_MODES.has(options.ignoreIntrospection)) {
-    throw new TypeError(
-      `Invalid ignoreIntrospection: "${options.ignoreIntrospection}". Must be "all", "none", or "typename".`
-    );
-  }
-  if (options.ignoreMode !== void 0 && !IGNORE_MODES.has(options.ignoreMode)) {
-    throw new TypeError(
-      `Invalid ignoreMode: "${options.ignoreMode}". Must be "exclude" or "skip".`
-    );
-  }
-  assertBooleanOption("limitIgnoredRecursion", options.limitIgnoredRecursion);
-  assertBooleanOption("shortCircuit", options.shortCircuit);
-  assertBooleanOption("useDirective", options.useDirective);
-  const ignore = normalizeIgnoreRules(options.ignore);
-  return { ...options, ignore };
-}
-function normalizeIgnoreRules(ignore) {
-  if (ignore == null) {
-    return void 0;
-  }
-  const rules = Array.isArray(ignore) ? ignore : [ignore];
-  for (const [index, rule] of rules.entries()) {
-    if (!isIgnoreRule(rule)) {
-      const receivedType = Array.isArray(rule) ? "array" : rule === null ? "null" : typeof rule;
-      throw new TypeError(
-        `Invalid ignore rule at index ${index}: expected string, RegExp, or function, received ${receivedType}.`
-      );
-    }
-    if (rule instanceof RegExp) {
-      const reason = isUnsafeRegExp(rule);
-      if (reason) {
-        throw new TypeError(
-          `Unsafe RegExp ignore rule at index ${index}: /${rule.source}/${rule.flags} \u2014 ${reason}. Use a simpler pattern to avoid catastrophic backtracking.`
-        );
-      }
-    }
-  }
-  return rules;
-}
-function createDepthResultRecord() {
-  return /* @__PURE__ */ Object.create(null);
-}
-function createOperationNameAllocator(operations) {
-  const explicitNames = /* @__PURE__ */ new Set();
-  for (const operation of operations) {
-    if (operation.name?.value) {
-      explicitNames.add(operation.name.value);
-    }
-  }
-  const usedNames = /* @__PURE__ */ new Set();
-  const namedCounts = /* @__PURE__ */ new Map();
-  let anonymousCount = 0;
-  return (operation) => {
-    const explicitName = operation.name?.value;
-    if (explicitName) {
-      let suffix = namedCounts.get(explicitName) ?? 0;
-      let candidate2 = suffix === 0 ? explicitName : `${explicitName}_${suffix}`;
-      while (usedNames.has(candidate2) || suffix > 0 && explicitNames.has(candidate2)) {
-        suffix++;
-        candidate2 = `${explicitName}_${suffix}`;
-      }
-      namedCounts.set(explicitName, suffix + 1);
-      usedNames.add(candidate2);
-      return candidate2;
-    }
-    anonymousCount++;
-    let candidate = anonymousCount === 1 ? "[anonymous]" : `[anonymous:${anonymousCount}]`;
-    while (usedNames.has(candidate) || explicitNames.has(candidate)) {
-      anonymousCount++;
-      candidate = `[anonymous:${anonymousCount}]`;
-    }
-    usedNames.add(candidate);
-    return candidate;
-  };
-}
-function setDepthResult(target, key, value) {
-  Object.defineProperty(target, key, {
-    configurable: true,
-    enumerable: true,
-    value,
-    writable: true
-  });
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ERROR_CODES,