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

package/package.json

@@ -1,67 +1,76 @@
 {
-  "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"
-  }
+	"name": "graphql-query-depth-limit-esm",
+	"version": "2.0.0",
+	"description": "GraphQL query depth limiting validation rule with directive support, ignore rules, and fragment cycle detection",
+	"author": "Lafitte Mehdy",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"LICENSE",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"keywords": [
+		"depth-limit",
+		"dos-protection",
+		"esm",
+		"graphql",
+		"security",
+		"validation"
+	],
+	"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",
+	"sideEffects": false,
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"peerDependencies": {
+		"graphql": "^16.0.0"
+	},
+	"devDependencies": {
+		"@apollo/server": "^5.4.0",
+		"@biomejs/biome": "^2.4.0",
+		"@types/node": "^25.2.3",
+		"@vitest/coverage-v8": "^4.0.18",
+		"@vitest/ui": "^4.0.18",
+		"graphql": "^16.12.0",
+		"graphql-yoga": "^5.18.0",
+		"tsup": "^8.5.1",
+		"tsx": "^4.21.0",
+		"typescript": "^5.9.3",
+		"vitest": "^4.0.18"
+	},
+	"scripts": {
+		"build": "tsup",
+		"dev": "tsc --watch",
+		"example:apollo": "tsx examples/servers/apollo-server.ts",
+		"example:yoga": "tsx examples/servers/yoga-server.ts",
+		"lint": "biome check && tsc --noEmit",
+		"lint:fix": "biome check --write && tsc --noEmit",
+		"prepublishOnly": "pnpm run lint && pnpm run build && pnpm test",
+		"test": "vitest run",
+		"test:coverage": "vitest run --coverage",
+		"test:ui": "vitest --ui",
+		"test:watch": "vitest"
+	}
 }

package/dist/depthLimit.d.ts

@@ -1,41 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,273 +0,0 @@
-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.map

@@ -1 +0,0 @@
-{"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/types.d.ts

@@ -1,25 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

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