graphql-query-depth-limit-esm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lafitte Mehdy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,496 @@
+# graphql-query-depth-limit-esm
+
+[![npm version](https://img.shields.io/npm/v/graphql-query-depth-limit-esm.svg)](https://www.npmjs.com/package/graphql-query-depth-limit-esm)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://github.com/lafittemehdy/graphql-query-depth-limit-esm/actions/workflows/test.yml/badge.svg)](https://github.com/lafittemehdy/graphql-query-depth-limit-esm/actions)
+
+Protect your GraphQL API by limiting query depth before execution.
+
+Prevents deeply nested queries from overloading your server. A lightweight, zero-dependency library that works with any GraphQL server (Apollo, Yoga, etc.) with native ESM and TypeScript support.
+
+## Features
+
+- **Native ESM & TypeScript:** Modern module support with full type safety
+- **Works Anywhere:** Compatible with any GraphQL-compliant server (Apollo, Yoga, etc.)
+- **Fragment Support:** Correctly handles fragment spreads and inline fragments
+- **Flexible Ignore Rules:** Skip specific fields using strings, RegExp, or custom functions
+- **Directive Support:** Field-specific depth limits using `@depth` directive
+- **Zero Dependencies:** Lightweight and focused (small bundle size)
+- **Well Tested:** Comprehensive test suite
+
+## Installation
+
+```bash
+npm install graphql-query-depth-limit-esm
+```
+
+## Quick Start
+
+### Apollo Server Integration
+
+```typescript
+import { ApolloServer } from '@apollo/server';
+import { startStandaloneServer } from '@apollo/server/standalone';
+import { depthLimit } from 'graphql-query-depth-limit-esm';
+
+// Step 1: Define your schema
+const typeDefs = `#graphql
+  directive @depth(max: Int!) on FIELD_DEFINITION
+
+  type Query {
+    # Regular user endpoint with depth limit of 3
+    user(id: ID!): User @depth(max: 3)
+
+    # Admin endpoint with higher depth limit
+    adminUser(id: ID!): User @depth(max: 10)
+
+    # Public endpoint without directive (uses global limit)
+    users: [User!]!
+  }
+
+  type User {
+    id: ID!
+    name: String!
+    email: String!
+    friends: [User!]!
+    posts: [Post!]!
+  }
+
+  type Post {
+    id: ID!
+    title: String!
+    author: User!
+  }
+`;
+
+// Step 2: Define your resolvers
+const resolvers = {
+  Query: {
+    user: (_: unknown, { id }: { id: string }) => ({
+      id,
+      name: "John Doe",
+      email: "john@example.com",
+      friends: [],
+      posts: [],
+    }),
+    adminUser: (_: unknown, { id }: { id: string }) => ({
+      id,
+      name: "Admin User",
+      email: "admin@example.com",
+      friends: [],
+      posts: [],
+    }),
+    users: () => [
+      {
+        id: "1",
+        name: "Alice",
+        email: "alice@example.com",
+        friends: [],
+        posts: [],
+      },
+    ],
+  },
+  User: {
+    friends: (parent: { id: string }) => [
+      {
+        id: `${parent.id}-friend`,
+        name: "Friend User",
+        email: "friend@example.com",
+        friends: [],
+        posts: [],
+      },
+    ],
+    posts: () => [],
+  },
+};
+
+// Step 3: Create and start the server with depth limiting
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  validationRules: [
+    // Global depth limit of 5 with directive support enabled
+    depthLimit(5, { useDirective: true }),
+  ],
+});
+
+const { url } = await startStandaloneServer(server, {
+  listen: { port: 4000 },
+});
+
+console.log(`🚀 Server ready at: ${url}`);
+```
+
+## How It Works
+
+The library calculates query depth during GraphQL validation (before execution). Deeply nested queries are rejected before hitting your business logic.
+
+**Process:**
+1. Client sends a query
+2. Server parses and validates the query
+3. **Query depth calculation runs** (this library)
+4. If validation passes, query executes
+
+The library traverses the query AST to calculate depth. It correctly handles fragments and introspection fields, counting only fields that actually contribute to nesting.
+
+---
+
+## Usage Examples
+
+### Basic Depth Limiting
+
+```typescript
+import { depthLimit } from 'graphql-query-depth-limit-esm';
+import { ApolloServer } from '@apollo/server';
+
+const server = new ApolloServer({
+  schema,
+  validationRules: [depthLimit(10)], // Maximum depth of 10
+});
+```
+
+### With Ignore Rules
+
+Skip specific fields from depth calculation:
+
+```typescript
+import { depthLimit } from 'graphql-query-depth-limit-esm';
+
+const server = new ApolloServer({
+  schema,
+  validationRules: [
+    depthLimit(10, {
+      ignore: [
+        'friends',              // Exact field name
+        /^internal/,            // RegExp pattern
+        (fieldName) => fieldName.startsWith('_'), // Custom function
+      ],
+    }),
+  ],
+});
+```
+
+### With Callback
+
+Monitor query depths:
+
+```typescript
+import { depthLimit } from 'graphql-query-depth-limit-esm';
+
+const server = new ApolloServer({
+  schema,
+  validationRules: [
+    depthLimit(10, undefined, (depths) => {
+      console.log('Query depths:', depths);
+      // Output: { "GetUser": 5, "GetPosts": 3 }
+    }),
+  ],
+});
+```
+
+### With @depth Directive
+
+Apply field-specific depth limits using the `@depth` directive:
+
+```typescript
+import { depthLimit } from 'graphql-query-depth-limit-esm';
+
+// First, add the directive to your schema
+const typeDefs = `#graphql
+  directive @depth(max: Int!) on FIELD_DEFINITION
+
+  type Query {
+    publicUser(id: ID!): User @depth(max: 2)
+    adminUser(id: ID!): User @depth(max: 10)
+  }
+
+  type User {
+    id: ID!
+    name: String!
+    friends: [User]
+  }
+`;
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  validationRules: [
+    depthLimit(5, { useDirective: true }),
+  ],
+});
+```
+
+**How it works:**
+- `publicUser` field has `@depth(max: 2)` - queries can only go 2 levels deep
+- `adminUser` field has `@depth(max: 10)` - queries can go 10 levels deep
+- Fields without `@depth` directive use the global limit (5 in this example)
+- The `@depth` directive can be combined with `@complexity` and other directives
+
+## How Depth is Calculated
+
+Depth is measured by counting nested field selections:
+
+```graphql
+query {
+  user {           # depth 1
+    posts {        # depth 2
+      comments {   # depth 3
+        author {   # depth 4
+          name     # depth 4 (scalar fields don't add depth)
+        }
+      }
+    }
+  }
+}
+# Total depth: 4
+```
+
+### What Doesn't Add Depth
+
+- **Fragment spreads** (`...FragmentName`) - The fragment's fields are counted, not the spread itself
+- **Inline fragments** (`... on Type { }`) - The inline fragment doesn't add depth
+- **Introspection fields** (`__typename`, `__schema`, `__type`, etc.)
+- **Fields matching ignore rules** - Skipped entirely from calculation
+- **Scalar/leaf fields** - Terminal nodes don't increase depth
+
+## Query Depth Examples
+
+**Schema:**
+```graphql
+type Query {
+  user(id: ID!): User
+}
+
+type User {
+  id: ID!
+  name: String!
+  friends: [User]
+  posts: [Post]
+}
+
+type Post {
+  id: ID!
+  title: String!
+  comments: [Comment]
+}
+
+type Comment {
+  id: ID!
+  body: String!
+  author: User
+}
+```
+
+| Query | Depth | Allowed (max 3)? |
+| :--- | :---: | :---: |
+| `{ user { id } }` | 1 | ✅ |
+| `{ user { friends { name } } }` | 2 | ✅ |
+| `{ user { posts { comments { body } } } }` | 3 | ✅ |
+| `{ user { posts { comments { author { name } } } } }` | 4 | ❌ |
+| `{ user { friends { friends { friends { name } } } } }` | 4 | ❌ |
+
+## Integration Examples
+
+### Apollo Server
+
+```typescript
+import { ApolloServer } from '@apollo/server';
+import { depthLimit } from 'graphql-query-depth-limit-esm';
+
+const server = new ApolloServer({
+  schema,
+  validationRules: [depthLimit(10)],
+});
+```
+
+### Express GraphQL
+
+```typescript
+import { graphqlHTTP } from 'express-graphql';
+import { depthLimit } from 'graphql-query-depth-limit-esm';
+
+app.use(
+  '/graphql',
+  graphqlHTTP({
+    schema,
+    validationRules: [depthLimit(10)],
+  }),
+);
+```
+
+### GraphQL Yoga
+
+```typescript
+import { createYoga } from 'graphql-yoga';
+import { depthLimit } from 'graphql-query-depth-limit-esm';
+
+const yoga = createYoga({
+  schema,
+  validationRules: [depthLimit(10)],
+});
+```
+
+## API Reference
+
+### `depthLimit(maxDepth, options?, callback?)`
+
+Creates a GraphQL validation rule that limits query depth.
+
+- `maxDepth` (number, **required**) - Maximum allowed depth for queries
+- `options` (object, optional):
+  - `caseInsensitiveIgnore` (boolean, optional) - Enable case-insensitive matching for string-based ignore rules. Default: `false`
+  - `ignore` (IgnoreRule[], optional) - Fields to exclude from depth calculation
+    - String: Exact field name match (case-sensitive by default)
+    - RegExp: Pattern matching
+    - Function: `(fieldName: string) => boolean` - Custom logic
+  - `useDirective` (boolean, optional) - Enable reading depth limits from `@depth` directive on fields. Default: `false`
+- `callback` (DepthCallback, optional) - Called after validation with depth information
+  - Receives object mapping operation names to their depths
+
+**Returns:** `ValidationRule` - GraphQL validation rule function
+
+### Ignore Rules
+
+Control which fields are excluded from depth calculation:
+
+```typescript
+import { depthLimit } from 'graphql-query-depth-limit-esm';
+
+const server = new ApolloServer({
+  schema,
+  validationRules: [
+    depthLimit(5, {
+      ignore: [
+        'friends',                              // String: exact match
+        /^metadata/,                            // RegExp: pattern match
+        (fieldName) => fieldName.includes('__'), // Function: custom logic
+      ],
+    }),
+  ],
+});
+```
+
+## Security Considerations
+
+This library is designed to protect against denial-of-service (DoS) attacks via deeply nested queries. Recent updates have strengthened the implementation to handle edge cases correctly:
+
+### Correctly Handled Scenarios
+
+✅ **Fragments at Different Depths** - Fragments used multiple times at different nesting levels are calculated correctly. Each usage is evaluated independently to prevent depth limit bypass.
+
+```graphql
+fragment UserInfo on User {
+  posts { title }  # Adds 2 levels
+}
+
+query {
+  user {
+    ...UserInfo          # Depth: 1 + 2 = 3
+    friends {
+      ...UserInfo        # Depth: 2 + 2 = 4 ✓ (calculated independently)
+    }
+  }
+}
+```
+
+✅ **Circular Fragment Detection** - Circular fragment references are detected per-path to prevent infinite recursion while maintaining accurate depth calculation.
+
+✅ **Introspection Fields** - All introspection fields (`__typename`, `__schema`, `__type`, etc.) are automatically excluded from depth calculation.
+
+### Known Limitations
+
+⚠️ **Variables in @depth Directive** - The `@depth` directive only supports integer literals. Variables are not supported because their values are not available during the validation phase.
+
+```graphql
+# ✅ Works
+type Query {
+  user: User @depth(max: 5)
+}
+
+# ❌ Not supported - will fall back to global depth limit
+type Query {
+  user: User @depth(max: $maxDepth)
+}
+```
+
+⚠️ **Case-Sensitive Field Names** - By default, field name matching is case-sensitive (as per GraphQL specification). Use the `caseInsensitiveIgnore` option if you need case-insensitive matching for ignore rules.
+
+```typescript
+// Case-sensitive (default)
+depthLimit(5, { ignore: ['friends'] })  // Only matches 'friends', not 'Friends'
+
+// Case-insensitive
+depthLimit(5, {
+  caseInsensitiveIgnore: true,
+  ignore: ['friends']  // Matches 'friends', 'Friends', 'FRIENDS', etc.
+})
+```
+
+### Security Best Practices
+
+1. **Always use depth limiting in production** - Even if you think your schema is safe
+2. **Combine with complexity limiting** - Use both for comprehensive protection
+3. **Set reasonable limits** - Balance security with legitimate use cases (typically 5-15)
+4. **Monitor query depths** - Use the callback to log and alert on suspicious patterns
+5. **Use field-specific limits** - Apply stricter limits to recursive fields via `@depth` directive
+
+## Why Depth Limiting?
+
+Deeply nested queries can cause:
+
+- **Performance issues** - Exponential data fetching (N+1 problem amplified)
+- **DoS attacks** - Server resource exhaustion
+- **Database overload** - Too many nested joins
+
+### Example Attack
+
+```graphql
+query Attack {
+  user {
+    friends {
+      friends {
+        friends {
+          friends {
+            # ... 100 levels deep
+            # This could fetch millions of records!
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Without depth limiting, this query could:
+- Fetch 10^100 user records (if each user has 10 friends)
+- Exhaust server memory
+- Crash your database
+
+**Depth limiting stops this attack during validation.**
+
+## Comparison with Complexity Limiting
+
+| Feature | Depth Limit | Complexity Limit |
+| :--- | :--- | :--- |
+| **Measures** | Nesting level | Total operation cost |
+| **Prevents** | Deep recursion attacks | Wide/expensive queries |
+| **Example Attack** | `user { friends { friends { ... } } }` | `users(limit: 9999) { id name email ... }` |
+| **Use Case** | Recursive relationships | Pagination/list queries |
+
+**Best Practice:** Use **both** depth and complexity limiting for comprehensive protection.
+
+---
+
+## Requirements
+
+- Node.js 18+
+- GraphQL 16+
+
+## Related Packages
+
+- [graphql-query-complexity-esm](https://github.com/lafittemehdy/graphql-query-complexity-esm) - Query complexity limiting
+- [graphql-rate-limit-redis-esm](https://github.com/lafittemehdy/graphql-rate-limit-redis-esm) - Rate limiting with Redis
+
+## License
+
+MIT License. This code is free to use. It has no opinions. You, I presume, do. Please use them.

package/dist/depthLimit.d.ts

@@ -0,0 +1,41 @@
+import { type ValidationContext } from "graphql";
+import type { DepthCallback, DepthLimitOptions } from "./types.js";
+/**
+ * Creates a GraphQL validation rule that limits query depth.
+ *
+ * This helps prevent DoS attacks and resource exhaustion from excessively deep queries.
+ * The depth limit can be configured globally and optionally overridden per-field using
+ * the @depth directive.
+ *
+ * Security considerations:
+ * - This validator correctly handles fragments used at different depths
+ * - Circular fragment references are detected and handled per-path
+ * - Introspection fields (__typename, __schema, etc.) are automatically ignored
+ *
+ * Limitations:
+ * - Variables in @depth directives are not supported (falls back to global limit)
+ * - Field names are case-sensitive by default (use caseInsensitiveIgnore option if needed)
+ *
+ * @param maxDepth - Maximum allowed depth for queries
+ * @param options - Optional configuration (ignore rules, directive support, case sensitivity)
+ * @param callback - Optional callback invoked with depth information for all operations
+ * @returns A GraphQL validation rule function
+ *
+ * @example
+ * ```typescript
+ * import { depthLimit } from 'graphql-query-depth-limit-esm';
+ * import { validate } from 'graphql';
+ *
+ * const validationRules = [
+ *   depthLimit(5, {
+ *     ignore: ['friends', /.*Connection$/],
+ *     useDirective: true,
+ *     caseInsensitiveIgnore: false
+ *   })
+ * ];
+ *
+ * const errors = validate(schema, query, validationRules);
+ * ```
+ */
+export declare function depthLimit(maxDepth: number, options?: DepthLimitOptions, callback?: DepthCallback): (context: ValidationContext) => {};
+//# sourceMappingURL=depthLimit.d.ts.map

package/dist/depthLimit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"depthLimit.d.ts","sourceRoot":"","sources":["../src/depthLimit.ts"],"names":[],"mappings":"AAAA,OAAO,EAgBL,KAAK,iBAAiB,EACvB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAc,MAAM,YAAY,CAAC;AA8S/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,iBAAiB,EAC3B,QAAQ,CAAC,EAAE,aAAa,IAEiB,SAAS,iBAAiB,QAwDpE"}

package/dist/depthLimit.js

@@ -0,0 +1,273 @@
+import { GraphQLError, getNamedType, isCompositeType, Kind, } from "graphql";
+/**
+ * Determines whether a field should be ignored in depth calculation.
+ *
+ * @param fieldName - The name of the field to check
+ * @param ignore - Array of ignore rules (strings, RegExp, or functions)
+ * @param caseInsensitive - Whether to perform case-insensitive matching for string rules
+ * @returns True if the field should be ignored, false otherwise
+ */
+function shouldIgnoreField(fieldName, ignore, caseInsensitive = false) {
+    // Always ignore introspection fields
+    if (fieldName.startsWith("__")) {
+        return true;
+    }
+    if (!ignore || ignore.length === 0) {
+        return false;
+    }
+    for (const rule of ignore) {
+        if (typeof rule === "string") {
+            const matches = caseInsensitive
+                ? rule.toLowerCase() === fieldName.toLowerCase()
+                : rule === fieldName;
+            if (matches) {
+                return true;
+            }
+        }
+        else if (rule instanceof RegExp) {
+            if (rule.test(fieldName)) {
+                return true;
+            }
+        }
+        else if (typeof rule === "function") {
+            if (rule(fieldName)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Extracts the depth limit from a @depth directive on a field definition.
+ *
+ * Note: This function only supports integer literals in the directive.
+ * Variables (e.g., @depth(max: $var)) are not supported because variable
+ * values are not available during the validation phase. Directives with
+ * variables will be ignored and fall back to the global depth limit.
+ *
+ * @param field - The GraphQL field definition to check
+ * @returns The max depth from the directive, or undefined if not found/invalid
+ */
+function getDepthFromDirective(field) {
+    if (!field?.astNode?.directives) {
+        return undefined;
+    }
+    const depthDirective = field.astNode.directives.find((d) => d.name.value === "depth");
+    if (!depthDirective?.arguments) {
+        return undefined;
+    }
+    const maxArg = depthDirective.arguments.find((arg) => arg.name.value === "max");
+    if (maxArg?.value.kind === "IntValue") {
+        const directiveDepth = Number.parseInt(maxArg.value.value, 10);
+        if (Number.isFinite(directiveDepth) && directiveDepth >= 0) {
+            return directiveDepth;
+        }
+    }
+    return undefined;
+}
+/**
+ * Extracts all fragment definitions from a GraphQL document.
+ *
+ * @param definitions - Array of definition nodes from the GraphQL document
+ * @returns Map of fragment names to their definitions
+ */
+function getFragments(definitions) {
+    const fragments = new Map();
+    for (const definition of definitions) {
+        if (definition.kind === Kind.FRAGMENT_DEFINITION) {
+            fragments.set(definition.name.value, definition);
+        }
+    }
+    return fragments;
+}
+/**
+ * Extracts all operation definitions from a GraphQL document.
+ *
+ * @param definitions - Array of definition nodes from the GraphQL document
+ * @returns Array of operation definitions (queries, mutations, subscriptions)
+ */
+function getOperations(definitions) {
+    return definitions.filter((def) => def.kind === Kind.OPERATION_DEFINITION);
+}
+/**
+ * Recursively calculates the depth of a GraphQL query node.
+ *
+ * This function handles fragment spreads correctly by creating an independent copy
+ * of the visited fragments set for each fragment path. This ensures:
+ * 1. Fragments used at different depths are calculated correctly
+ * 2. Circular fragment references are detected per-path, not globally
+ * 3. The same fragment can be used multiple times without miscalculation
+ *
+ * @param node - The AST node to calculate depth for
+ * @param fragments - Map of all fragment definitions in the document
+ * @param schema - GraphQL schema for type resolution
+ * @param maxDepth - Maximum allowed depth for this node
+ * @param context - Context object containing current depth, parent type, and visited fragments
+ * @param options - Options object containing configuration flags and ignore rules
+ * @returns Object containing final depth and any violation found
+ */
+function calculateDepth(node, fragments, schema, maxDepth, context, options) {
+    const { currentDepth, parentType, visitedFragments } = context;
+    const { useDirective, caseInsensitiveIgnore, ignore } = options;
+    if (currentDepth > maxDepth) {
+        return {
+            depth: currentDepth,
+            violation: { depth: currentDepth, maxDepth },
+        };
+    }
+    if (!node.selectionSet) {
+        return { depth: currentDepth, violation: null };
+    }
+    let maxChildDepth = currentDepth;
+    let violation = null;
+    for (const selection of node.selectionSet.selections) {
+        if (selection.kind === Kind.FIELD) {
+            const fieldNode = selection;
+            const fieldName = fieldNode.name.value;
+            if (shouldIgnoreField(fieldName, ignore, caseInsensitiveIgnore)) {
+                continue;
+            }
+            if (fieldNode.selectionSet) {
+                // Check for field-specific depth limit from @depth directive
+                let fieldMaxDepth = maxDepth;
+                let fieldType;
+                if (schema && parentType) {
+                    const namedType = getNamedType(parentType);
+                    if (isCompositeType(namedType) && "getFields" in namedType) {
+                        const fieldDef = namedType.getFields()[fieldName];
+                        if (fieldDef) {
+                            fieldType = fieldDef.type;
+                            if (useDirective) {
+                                const directiveDepth = getDepthFromDirective(fieldDef);
+                                if (directiveDepth !== undefined) {
+                                    fieldMaxDepth = directiveDepth;
+                                }
+                            }
+                        }
+                    }
+                }
+                const result = calculateDepth(fieldNode, fragments, schema, fieldMaxDepth, {
+                    currentDepth: currentDepth + 1,
+                    parentType: fieldType,
+                    visitedFragments,
+                }, options);
+                if (result.violation && !violation) {
+                    violation = result.violation;
+                }
+                maxChildDepth = Math.max(maxChildDepth, result.depth);
+            }
+        }
+        else if (selection.kind === Kind.FRAGMENT_SPREAD) {
+            const spreadNode = selection;
+            const fragmentName = spreadNode.name.value;
+            // Create a copy of visitedFragments for this path to correctly handle
+            // fragments used at different depths. This prevents the bug where a fragment
+            // used multiple times would only be calculated based on first occurrence.
+            const fragmentVisited = new Set(visitedFragments);
+            if (fragmentVisited.has(fragmentName)) {
+                // Fragment cycle detected - skip to prevent infinite recursion
+                continue;
+            }
+            const fragment = fragments.get(fragmentName);
+            if (fragment) {
+                fragmentVisited.add(fragmentName);
+                const result = calculateDepth(fragment, fragments, schema, maxDepth, {
+                    currentDepth,
+                    parentType,
+                    visitedFragments: fragmentVisited,
+                }, options);
+                if (result.violation && !violation) {
+                    violation = result.violation;
+                }
+                maxChildDepth = Math.max(maxChildDepth, result.depth);
+            }
+        }
+        else if (selection.kind === Kind.INLINE_FRAGMENT) {
+            const inlineFragment = selection;
+            // Inline fragments inherit the visitedFragments set since they don't have names
+            // and cannot create cycles by themselves
+            const result = calculateDepth(inlineFragment, fragments, schema, maxDepth, context, options);
+            if (result.violation && !violation) {
+                violation = result.violation;
+            }
+            maxChildDepth = Math.max(maxChildDepth, result.depth);
+        }
+    }
+    return { depth: maxChildDepth, violation };
+}
+/**
+ * Creates a GraphQL validation rule that limits query depth.
+ *
+ * This helps prevent DoS attacks and resource exhaustion from excessively deep queries.
+ * The depth limit can be configured globally and optionally overridden per-field using
+ * the @depth directive.
+ *
+ * Security considerations:
+ * - This validator correctly handles fragments used at different depths
+ * - Circular fragment references are detected and handled per-path
+ * - Introspection fields (__typename, __schema, etc.) are automatically ignored
+ *
+ * Limitations:
+ * - Variables in @depth directives are not supported (falls back to global limit)
+ * - Field names are case-sensitive by default (use caseInsensitiveIgnore option if needed)
+ *
+ * @param maxDepth - Maximum allowed depth for queries
+ * @param options - Optional configuration (ignore rules, directive support, case sensitivity)
+ * @param callback - Optional callback invoked with depth information for all operations
+ * @returns A GraphQL validation rule function
+ *
+ * @example
+ * ```typescript
+ * import { depthLimit } from 'graphql-query-depth-limit-esm';
+ * import { validate } from 'graphql';
+ *
+ * const validationRules = [
+ *   depthLimit(5, {
+ *     ignore: ['friends', /.*Connection$/],
+ *     useDirective: true,
+ *     caseInsensitiveIgnore: false
+ *   })
+ * ];
+ *
+ * const errors = validate(schema, query, validationRules);
+ * ```
+ */
+export function depthLimit(maxDepth, options, callback) {
+    return function depthLimitValidationRule(context) {
+        const document = context.getDocument();
+        const fragments = getFragments(document.definitions);
+        const operations = getOperations(document.definitions);
+        const depths = {};
+        const schema = context.getSchema();
+        const rootTypeMap = {
+            mutation: schema.getMutationType() ?? undefined,
+            query: schema.getQueryType() ?? undefined,
+            subscription: schema.getSubscriptionType() ?? undefined,
+        };
+        for (const operation of operations) {
+            const operationName = operation.name?.value || "anonymous";
+            const visitedFragments = new Set();
+            const rootType = rootTypeMap[operation.operation];
+            const result = calculateDepth(operation, fragments, schema, maxDepth, {
+                currentDepth: 0,
+                parentType: rootType,
+                visitedFragments,
+            }, {
+                caseInsensitiveIgnore: options?.caseInsensitiveIgnore ?? false,
+                ignore: options?.ignore,
+                useDirective: options?.useDirective ?? false,
+            });
+            depths[operationName] = result.depth;
+            // Report error if depth limit was exceeded (either field-specific or global)
+            if (result.violation) {
+                context.reportError(new GraphQLError(`'${operationName}' has depth ${result.violation.depth} which exceeds maximum operation depth of ${result.violation.maxDepth}`, {
+                    nodes: [operation],
+                }));
+            }
+        }
+        if (callback) {
+            callback(depths);
+        }
+        return {};
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * GraphQL Query Depth Limiting - ESM Compatible
+ *
+ * A GraphQL validation rule that limits the depth of queries.
+ * Prevents deeply nested queries from overloading your server.
+ *
+ * @packageDocumentation
+ */
+export { depthLimit } from "./depthLimit.js";
+export type { DepthCallback, DepthLimitFunction, DepthLimitOptions, IgnoreRule, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * GraphQL Query Depth Limiting - ESM Compatible
+ *
+ * A GraphQL validation rule that limits the depth of queries.
+ * Prevents deeply nested queries from overloading your server.
+ *
+ * @packageDocumentation
+ */
+export { depthLimit } from "./depthLimit.js";

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+import type { ValidationRule } from "graphql";
+export type IgnoreRule = string | RegExp | ((fieldName: string) => boolean);
+export interface DepthLimitOptions {
+    /**
+     * Whether to perform case-insensitive matching for string-based ignore rules
+     * When true, "user" will match "User", "USER", etc.
+     * Note: GraphQL field names are case-sensitive by specification
+     * @default false
+     */
+    caseInsensitiveIgnore?: boolean;
+    /**
+     * Fields to exclude from depth calculation
+     * Can be strings (exact match), RegExp patterns, or custom functions
+     */
+    ignore?: IgnoreRule[];
+    /**
+     * Whether to read depth limits from @depth directive on fields
+     * When enabled, field-specific depth limits override the global maxDepth
+     * @default false
+     */
+    useDirective?: boolean;
+}
+export type DepthCallback = (depths: Record<string, number>) => void;
+export type DepthLimitFunction = (maxDepth: number, options?: DepthLimitOptions, callback?: DepthCallback) => ValidationRule;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;AAE5E,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;OAGG;IACH,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IAEtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;AAErE,MAAM,MAAM,kBAAkB,GAAG,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,iBAAiB,EAC3B,QAAQ,CAAC,EAAE,aAAa,KACrB,cAAc,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "graphql-query-depth-limit-esm",
+  "version": "0.1.0",
+  "description": "GraphQL query depth limiting for ESM projects",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "dev": "tsc --watch",
+    "lint": "biome check --unsafe --write && tsc --noEmit",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "prepublishOnly": "pnpm run build && pnpm run test"
+  },
+  "keywords": [
+    "graphql",
+    "depth",
+    "limit",
+    "validation",
+    "security",
+    "esm"
+  ],
+  "author": "Lafitte Mehdy",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lafittemehdy/graphql-query-depth-limit-esm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lafittemehdy/graphql-query-depth-limit-esm/issues"
+  },
+  "homepage": "https://github.com/lafittemehdy/graphql-query-depth-limit-esm#readme",
+  "peerDependencies": {
+    "graphql": "^16.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.5",
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "^4.0.9",
+    "graphql": "^16.12.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.9"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}