GraphQL validation rule to limit query complexity
npm install graphql-complexity-validation!CI
!npm
!downloads
!license
!typescript
A lightweight, framework-agnostic GraphQL validation rule to limit query complexity and protect your server from expensive queries.
✅ Zero dependencies
✅ Compatible with graphql-js validation
✅ Works with Apollo Server, GraphQL Yoga, Envelop, NestJS
✅ Supports fragments, inline fragments, and introspection
✅ Fully typed (TypeScript)
- Node.js >= 14
- graphql ^14 | ^15 | ^16
---
``bash`
npm install graphql-complexity-validation
or
`bash`
yarn add graphql-complexity-validation
---
`ts
import { validate, parse } from "graphql";
import { createComplexityLimitRule } from "graphql-complexity-validation";
const errors = validate(schema, parse(query), [
createComplexityLimitRule({
maxComplexity: 10,
}),
]);
`
If the query exceeds the configured complexity, a validation error is returned.
---
- Each field has a cost
- Default field cost is 1__schema
- Nested fields add their cost recursively
- Fragments and inline fragments are fully supported
- Introspection fields (, __type, etc.) are ignored by default
- Complexity is calculated per operation during GraphQL's validation phase.
- If a document contains multiple operations, each operation is validated independently.
Example:
`graphql`
query {
user {
posts {
comments {
id
}
}
}
}
Complexity (default):
`
user(1)
└─ posts(1)
└─ comments(1)
└─ id(1)
Total = 4
`
---
`ts`
createComplexityLimitRule({
maxComplexity: number; // required
defaultCost?: number; // default: 1
fieldCosts?: Record
ignoreIntrospection?: boolean; // default: true
message?: (cost, max) => string; // custom error message
});
---
`ts`
createComplexityLimitRule({
maxComplexity: 5,
fieldCosts: {
posts: 3,
comments: 2,
},
});
---
`tsQuery cost ${cost} exceeds the allowed maximum of ${max}
createComplexityLimitRule({
maxComplexity: 10,
message: (cost, max) =>
,`
});
---
`ts
import { ApolloServer } from "@apollo/server";
import { createComplexityLimitRule } from "graphql-complexity-validation";
const server = new ApolloServer({
schema,
validationRules: [
createComplexityLimitRule({
maxComplexity: 20,
}),
],
});
`
---
`ts
import { createYoga } from "graphql-yoga";
import { createComplexityLimitRule } from "graphql-complexity-validation";
const yoga = createYoga({
schema,
validationRules: [
createComplexityLimitRule({
maxComplexity: 20,
}),
],
});
`
---
`ts
import { envelop, useValidationRules } from "@envelop/core";
import { createComplexityLimitRule } from "graphql-complexity-validation";
const getEnveloped = envelop({
plugins: [
useValidationRules([
createComplexityLimitRule({
maxComplexity: 20,
}),
]),
],
});
`
---
`ts
import { GraphQLModule } from "@nestjs/graphql";
import { createComplexityLimitRule } from "graphql-complexity-validation";
GraphQLModule.forRoot({
schema,
validationRules: [
createComplexityLimitRule({
maxComplexity: 20,
}),
],
});
``
---
- No schema traversal at runtime
- No directive setup
- No Apollo-specific plugins
- Uses native GraphQL validation
- Predictable and easy to reason about
Designed for performance, clarity, and portability.
---
Unlike other GraphQL complexity libraries, this package:
- Does not require schema traversal
- Does not rely on directives
- Does not depend on Apollo internals
- Works entirely at the GraphQL validation layer
---
MIT © Mateo Diaz