depth-validator

A GraphQL query depth validator for NestJS, Apollo Server, or any GraphQL-JS compliant server.

This package provides a lightweight, framework-agnostic validation rule to prevent malicious or overly nested GraphQL queries from being executed. It supports inline fragments, named fragments, custom error messages, and operation skipping.

Features

• Prevents deeply nested GraphQL queries
• Supports fragments and inline fragments
• Fully customizable error messages
• Compatible with graphql-js, Apollo Server, NestJS, and more

Installation

npm install depth-validator

Note: This package treats graphql as a peer dependency. You must install graphql in your host project:

npm install graphql

Usage

NestJS Example (ApolloFederationDriver)

import { GraphQLModule } from '@nestjs/graphql';
import { ApolloFederationDriver } from '@nestjs/graphql';
import depthLimitValidator from 'depth-validator';

GraphQLModule.forRootAsync({
  driver: ApolloFederationDriver,
  useFactory: async () => ({
    autoSchemaFile: true,
    validationRules: [
      depthLimitValidator({
        maxDepth: 5,
        skip: ['IntrospectionQuery'],
        errorMessage: (depth, max, operation) =>
          `Operation "${operation}" exceeds depth ${depth} (max allowed ${max})`,
      }),
    ],
  }),
});

Apollo Server Example

import { ApolloServer } from 'apollo-server';
import { makeExecutableSchema } from '@graphql-tools/schema';
import depthLimitValidator from 'depth-validator';

const schema = makeExecutableSchema({ typeDefs, resolvers });

const server = new ApolloServer({
  schema,
  validationRules: [
    depthLimitValidator({
      maxDepth: 4,
    }),
  ],
});

API

depthLimitValidator(options: DepthValidatorOptions): ValidationRule

| Option | Type | Required | Description | |----------------|----------------------------------------------------------------------|----------|----------------------------------------------------------------| | maxDepth | number | true | Maximum allowed depth of a query | | skip | string[] | false | List of operation names to exclude from validation | | errorMessage | (depth: number, maxDepth: number, operationName?: string) => string| false | Custom function to format validation error messages |

Example Rejection

A query like:

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

...with a maxDepth of 2 will be rejected with:

{
  "errors": [
    {
      "message": "Operation \"GetUser\" exceeds depth 4 (max allowed 2)"
    }
  ]
}