graphql-safe-depth

Lightweight, predictable and production-ready GraphQL depth limiting.

A lightweight and dependency-free GraphQL validation rule to limit query depth.

Designed for learning, experimentation, and production APIs that need a simple and predictable way to prevent overly deep GraphQL queries.

🤔 Why graphql-safe-depth?

Most GraphQL depth-limit solutions either:

• Count total fields instead of real execution depth
• Break with introspection queries
• Are hard to reason about or customize

graphql-safe-depth focuses on:

• ✅ Predictable execution depth calculation
• 🧠 Real resolver path depth (not total fields)
• 🔍 Safe introspection handling
• 🧩 Fragment-friendly validation
• ⚡ Minimal and dependency-free core

✨ Features

• ✅ Limits GraphQL query depth
• 🚫 Prevents malicious or accidental deep queries
• 🧠 Counts actual execution depth, not total fields
• 🔍 Ignores introspection fields by default
• 🧩 Works with fragments
• ⚡ Zero external dependencies
• 🧪 Fully tested
• 🛠 Written in TypeScript

📦 Installation

npm i graphql-safe-depth
# or
yarn add graphql-safe-depth

🚀 Usage

Apollo Server (Node.js)

import { ApolloServer } from "apollo-server";
import { createDepthLimitRule } from "graphql-safe-depth";

const server = new ApolloServer({
  typeDefs,
  resolvers,
  validationRules: [createDepthLimitRule({ maxDepth: 3 })],
});

Apollo Server (NestJS)

import { createDepthLimitRule } from "graphql-safe-depth";

GraphQLModule.forRoot({
  autoSchemaFile: true,
  validationRules: [createDepthLimitRule({ maxDepth: 3 })],
});

⚙️ Options

createDepthLimitRule({
  maxDepth: number;
  ignoreIntrospection?: boolean;
  message?: (depth: number, maxDepth: number) => string;
});

maxDepth (required)

Maximum allowed depth for a query

createDepthLimitRule({ maxDepth: 3 });

ignoreIntrospection  (default: true)

If true , GraphQL introspection fields (**schema, **type, __typename) are ignored when calculating depth.

createDepthLimitRule({
  maxDepth: 3,
  ignoreIntrospection: false,
});

message (optional)

Custom error message generator.

createDepthLimitRule({
  maxDepth: 3,
  message: (depth, max) =>
    `Query depth ${depth} exceeds the allowed maximum of ${max}`,
});

📐 How depth is calculated

Depth is calculated based on the deepest execution path, not the number of fields.

✅ Valid query (depth = 3)

query {
  user {
    profile {
      name
    }
  }
}

❌ Invalid query (depth = 4)

query {
  user {
    profile {
      address {
        city
      }
    }
  }
}

🔐 Security note

This library protects against overly deep queries that may cause performance issues or denial-of-service scenarios.

It is recommended to combine it with:

• Query complexity limits
• Proper authentication & authorization
• Rate limiting

🧪 Testing

npm test
or
yarn test

📄 License

MIT © Mateo Diaz