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

package/README.md

@@ -6,11 +6,24 @@
 [![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 >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Node >=22](https://img.shields.io/badge/node-%3E%3D22-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.
 
-Explore the library's internal function architecture with the **[interactive node-based visualization](https://lafittemehdy.github.io/graphql-query-depth-limit-esm/architecture.html)**.
+**[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:
+
+```bash
+cd examples/visualization
+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.
 
 ## Features
 
@@ -28,26 +41,31 @@ Explore the library's internal function architecture with the **[interactive nod
 ## Installation
 
 ```bash
-pnpm add graphql-query-depth-limit-esm graphql
+npm install graphql-query-depth-limit-esm graphql
 ```
 
 ```bash
-npm install graphql-query-depth-limit-esm graphql
+pnpm add graphql-query-depth-limit-esm graphql
 ```
 
 ```bash
 yarn add graphql-query-depth-limit-esm graphql
 ```
 
-## Quick Start
+## Quickstart
 
 ```ts
-import { validate } from "graphql";
+import { specifiedRules, validate } from "graphql";
 import { depthLimit } from "graphql-query-depth-limit-esm";
 
-const errors = validate(schema, document, [depthLimit(7, { useDirective: true })]);
+const errors = validate(schema, document, [
+  ...specifiedRules,
+  depthLimit(7, { useDirective: true }),
+]);
 ```
 
+When calling `validate()` directly, include `specifiedRules` unless you intentionally want to replace GraphQL's default validation rules.
+
 The recommended way to use `graphql-query-depth-limit-esm` is the `@depth` directive — a global maximum protects your API, while per-field overrides can tighten limits (and can opt into deeper nesting when `directiveMode: "override"` is enabled).
 
 ### Global Limit with Per-Field Overrides
@@ -85,7 +103,7 @@ Build the schema with the directive type defs, then enable directive support via
 ```ts
 import { makeExecutableSchema } from "@graphql-tools/schema";
 import { depthDirectiveTypeDefs, depthLimit } from "graphql-query-depth-limit-esm";
-import { validate } from "graphql";
+import { specifiedRules, validate } from "graphql";
 
 const schema = makeExecutableSchema({
   typeDefs: [depthDirectiveTypeDefs, yourTypeDefs],
@@ -94,6 +112,7 @@ const schema = makeExecutableSchema({
 
 // Global max of 7 — @depth directives can tighten but never exceed this limit
 const errors = validate(schema, document, [
+  ...specifiedRules,
   depthLimit(7, { useDirective: true }),
 ]);
 ```
@@ -152,11 +171,11 @@ For straightforward global limiting without per-field overrides, call [`depthLim
 
 ```ts
 import { depthLimit } from "graphql-query-depth-limit-esm";
-import { validate } from "graphql";
+import { specifiedRules, validate } from "graphql";
 
 // Reject queries deeper than 10 levels
 const rule = depthLimit(10);
-const errors = validate(schema, document, [rule]);
+const errors = validate(schema, document, [...specifiedRules, rule]);
 ```
 
 ### With Apollo Server
@@ -295,7 +314,7 @@ Monitor query depths with an optional [`callback`](#depthcallback) that receives
 
 ```ts
 const rule = depthLimit(10, {}, (depths) => {
-  // { "GetUser": 3, "ListPosts": 5, "anonymous": 2 }
+  // { "GetUser": 3, "ListPosts": 5, "[anonymous]": 2 }
   for (const [operation, depth] of Object.entries(depths)) {
     console.log(`Operation "${operation}" has depth ${depth}`);
   }
@@ -511,6 +530,17 @@ depthLimit(10, { directiveMode: "override", useDirective: true });
 
 **Impact:** This is transparent to most users. The only observable difference is that error messages may report the depth at the first violation rather than the deepest violation when multiple branches exceed the limit. If you need the true maximum depth, provide a callback.
 
+## Related Packages
+
+This package is part of a suite of GraphQL security tools that work independently or together to protect your API:
+
+| Package | Purpose |
+|---|---|
+| [`graphql-query-complexity-esm`](https://github.com/lafittemehdy/graphql-query-complexity-esm) | Complexity analysis — assign cost scores to fields and reject expensive queries |
+| [`graphql-rate-limit-redis-esm`](https://github.com/lafittemehdy/graphql-rate-limit-redis-esm) | Rate limiting — Redis-backed per-field rate limiting via `@rateLimit` directive |
+
+**Recommended layering:** Use depth limiting as a fast, cheap first gate, complexity analysis for fine-grained cost control, and rate limiting for per-client throttling.
+
 ## License
 
 [MIT](LICENSE)

package/dist/index.cjs

@@ -22,15 +22,16 @@ var index_exports = {};
 __export(index_exports, {
   ERROR_CODES: () => ERROR_CODES,
   depthDirectiveTypeDefs: () => depthDirectiveTypeDefs,
-  depthLimit: () => depthLimit
+  depthLimit: () => depthLimit,
+  isUnsafeRegExp: () => isUnsafeRegExp
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/constants.ts
-var ERROR_CODES = {
+var ERROR_CODES = Object.freeze({
   IGNORE_RULE_ERROR: "IGNORE_RULE_ERROR",
   QUERY_TOO_DEEP: "QUERY_TOO_DEEP"
-};
+});
 
 // src/depth-limit.ts
 var import_graphql3 = require("graphql");
@@ -40,9 +41,10 @@ var import_graphql2 = require("graphql");
 
 // src/directives.ts
 var import_graphql = require("graphql");
-var depthDirectiveTypeDefs = `
-  directive @depth(max: Int!) on FIELD_DEFINITION
-`;
+var depthDirectiveTypeDefs = (
+  /* GraphQL */
+  `directive @depth(max: Int!) on FIELD_DEFINITION`
+);
 function getDepthFromDirective(field) {
   if (!field?.astNode?.directives) {
     return void 0;
@@ -62,6 +64,83 @@ function getDepthFromDirective(field) {
 }
 
 // src/ignore.ts
+var QUANTIFIER_CHARS = /* @__PURE__ */ new Set(["+", "*", "?"]);
+var BRACE_QUANTIFIER = /^\{(\d+)(?:,(\d*))?\}/;
+function isUnsafeRegExp(regex) {
+  const source = regex.source;
+  const length = source.length;
+  const groupStack = [];
+  for (let i = 0; i < length; i++) {
+    const char = source.charAt(i);
+    if (char === "\\") {
+      i++;
+      continue;
+    }
+    if (char === "[") {
+      while (i < length && source[i] !== "]") {
+        if (source[i] === "\\") i++;
+        i++;
+      }
+      continue;
+    }
+    if (char === "(") {
+      groupStack.push(false);
+      if (source[i + 1] === "?") {
+        i++;
+        if (source[i + 1] === "<" && (source[i + 2] === "=" || source[i + 2] === "!")) {
+          i += 2;
+        } else if (source[i + 1] === ":" || source[i + 1] === "=" || source[i + 1] === "!") {
+          i++;
+        }
+      }
+      continue;
+    }
+    if (char === ")") {
+      const groupHadQuantifier = groupStack.pop() ?? false;
+      if (groupHadQuantifier && isFollowedByQuantifier(source, i + 1, length)) {
+        return "nested quantifier: group with inner quantifier followed by outer quantifier";
+      }
+      if (groupStack.length > 0 && isFollowedByQuantifier(source, i + 1, length)) {
+        groupStack[groupStack.length - 1] = true;
+      }
+      continue;
+    }
+    if (QUANTIFIER_CHARS.has(char) || char === "{") {
+      if (char === "{") {
+        const match = BRACE_QUANTIFIER.exec(source.slice(i));
+        if (!match) continue;
+        const minStr = match[1] ?? "0";
+        const min = Number.parseInt(minStr, 10);
+        const fullMatch = match[0] ?? "";
+        const hasComma = fullMatch.includes(",");
+        if (!hasComma && min <= 1) continue;
+        if (hasComma && match[2] !== void 0 && match[2] !== "" && Number.parseInt(match[2], 10) <= 1)
+          continue;
+      }
+      if (groupStack.length > 0) {
+        groupStack[groupStack.length - 1] = true;
+      }
+    }
+  }
+  return null;
+}
+function isFollowedByQuantifier(source, pos, length) {
+  if (pos >= length) return false;
+  const char = source[pos];
+  if (char === "+" || char === "*") return true;
+  if (char === "{") {
+    const match = BRACE_QUANTIFIER.exec(source.slice(pos));
+    if (match) {
+      const minStr = match[1] ?? "0";
+      const min = Number.parseInt(minStr, 10);
+      const fullMatch = match[0] ?? "";
+      const hasComma = fullMatch.includes(",");
+      if (!hasComma && min <= 1) return false;
+      return true;
+    }
+  }
+  return false;
+}
 function shouldIgnoreField(fieldName, ignore, caseInsensitive = false, introspectionMode = "typename") {
   if (introspectionMode === "all" && fieldName.startsWith("__")) {
     return true;
@@ -132,6 +211,7 @@ function calculateDepth(caches, config, fragments, maxDepth, node, parentType, s
     if (!frame.node.selectionSet) {
       continue;
     }
+    const nextFrames = [];
     for (const selection of frame.node.selectionSet.selections) {
       switch (selection.kind) {
         case import_graphql2.Kind.FIELD: {
@@ -213,7 +293,7 @@ function calculateDepth(caches, config, fragments, maxDepth, node, parentType, s
               deepestViolation = violation;
             }
           }
-          stack.push({
+          nextFrames.push({
             currentDepth: newDepth,
             hasDirectiveLimit,
             ignoredFieldsOnPath,
@@ -237,7 +317,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;
-          stack.push({
+          nextFrames.push({
             currentDepth: frame.currentDepth,
             hasDirectiveLimit: frame.hasDirectiveLimit,
             ignoredFieldsOnPath: frame.ignoredFieldsOnPath,
@@ -251,7 +331,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;
-          stack.push({
+          nextFrames.push({
             currentDepth: frame.currentDepth,
             hasDirectiveLimit: frame.hasDirectiveLimit,
             ignoredFieldsOnPath: frame.ignoredFieldsOnPath,
@@ -265,13 +345,22 @@ function calculateDepth(caches, config, fragments, maxDepth, node, parentType, s
         }
         default: {
           const exhaustiveCheck = selection;
-          throw new Error(`Unhandled selection kind: ${exhaustiveCheck.kind}`);
+          throwUnhandledSelectionKind(exhaustiveCheck);
         }
       }
     }
+    for (let index = nextFrames.length - 1; index >= 0; index--) {
+      const nextFrame = nextFrames[index];
+      if (nextFrame) {
+        stack.push(nextFrame);
+      }
+    }
   }
   return { depth: globalMaxDepth, violation: deepestViolation };
 }
+function throwUnhandledSelectionKind(selection) {
+  throw new Error(`Unhandled selection kind: ${selection.kind}`);
+}
 function collectInterfaces(type) {
   const interfaces = [];
   const seen = /* @__PURE__ */ new Set();
@@ -385,19 +474,13 @@ function assertBooleanOption(name, value) {
 function createValidationRule(maxDepth, options, callback) {
   const shortCircuit = options?.shortCircuit ?? callback == null;
   return function depthLimitValidationRule(context) {
-    let anonymousCount = 0;
     const caches = createTraversalCaches();
     const document = context.getDocument();
-    const depths = callback ? {} : void 0;
+    const depths = callback ? createDepthResultRecord() : void 0;
     const { fragments, operations } = extractDefinitions(document.definitions);
     const schema = context.getSchema() ?? void 0;
     const useDirective = Boolean(schema) && (options?.useDirective ?? false);
-    const namedOperationNames = /* @__PURE__ */ new Set();
-    for (const op of operations) {
-      if (op.name?.value) {
-        namedOperationNames.add(op.name.value);
-      }
-    }
+    const nextOperationName = createOperationNameAllocator(operations);
     const config = {
       caseInsensitiveIgnore: options?.caseInsensitiveIgnore ?? false,
       directiveMode: options?.directiveMode ?? "cap",
@@ -418,18 +501,7 @@ function createValidationRule(maxDepth, options, callback) {
       subscription: void 0
     };
     for (const operation of operations) {
-      let operationName;
-      if (operation.name?.value) {
-        operationName = operation.name.value;
-      } else {
-        let candidate = anonymousCount === 0 ? "anonymous" : `anonymous_${anonymousCount}`;
-        while (namedOperationNames.has(candidate)) {
-          anonymousCount++;
-          candidate = `anonymous_${anonymousCount}`;
-        }
-        operationName = candidate;
-        anonymousCount++;
-      }
+      const operationName = nextOperationName(operation);
       const rootType = rootTypeMap[operation.operation];
       let result;
       try {
@@ -475,7 +547,7 @@ function createValidationRule(maxDepth, options, callback) {
       }
     }
     if (callback && depths) {
-      callback(depths);
+      callback({ ...depths });
     }
     return {};
   };
@@ -537,9 +609,53 @@ function normalizeIgnoreRules(ignore) {
         `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,
@@ -552,6 +668,7 @@ function setDepthResult(target, key, value) {
 0 && (module.exports = {
   ERROR_CODES,
   depthDirectiveTypeDefs,
-  depthLimit
+  depthLimit,
+  isUnsafeRegExp
 });
 //# sourceMappingURL=index.cjs.map