Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

graphql-validation-complexity Travis npm

Query complexity validation for GraphQL.js.



import { createComplexityLimitRule } from 'graphql-validation-complexity';

const ComplexityLimitRule = createComplexityLimitRule(1000);
// Then use this rule with validate() or other validation APIs.

For example, with express-graphql or Apollo Server, pass the complexity limit rule to validationRules.

const graphqlMiddleware = graphqlHTTP({
  validationRules: [createComplexityLimitRule(1000)],

const apolloServer = new ApolloServer({
  validationRules: [createComplexityLimitRule(1000)],

You can provide a configuration object with custom global costs for scalars and objects as scalarCost and objectCost respectively, and a custom cost factor for lists as listFactor.

const ComplexityLimitRule = createComplexityLimitRule(1000, {
  scalarCost: 1,
  objectCost: 10, // Default is 0.
  listFactor: 20, // Default is 10.

You can also set custom costs and cost factors as field definition extensions with the getCost and getCostFactor callbacks.

const expensiveField = {
  type: ExpensiveItem,
  extensions: {
    getCost: () => 50,

const expensiveList = {
  type: new GraphQLList(MyItem),
  extensions: {
    getCostFactor: () => 100,

You can also define these via field directives in the SDL.

directive @cost(value: Int) on FIELD_DEFINITION
directive @costFactor(value: Int) on FIELD_DEFINITION

type CustomCostItem {
  expensiveField: ExpensiveItem @cost(value: 50)
  expensiveList: [MyItem] @costFactor(value: 100)

The configuration object also supports an onCost callback for logging query costs and a formatErrorMessage callback for customizing error messages. onCost will be called for every query with its cost. formatErrorMessage will be called with the cost whenever a query exceeds the complexity limit, and should return a string containing the error message.

const ComplexityLimitRule = createComplexityLimitRule(1000, {
  onCost: (cost) => {
    console.log('query cost:', cost);
  formatErrorMessage: (cost) =>
    `query with cost ${cost} exceeds complexity limit`,

The configuration object also supports a createError callback for creating a custom GraphQLError. createError will be called with the cost and the document node whenever an error occurs. formatErrorMessage will be ignored when createError is specified.

const ComplexityLimitRule = createComplexityLimitRule(1000, {
  createError(cost, documentNode) {
    const error = new GraphQLError('custom error', [documentNode]);
    error.meta = { cost };
    return error;

By default, the validation rule applies a custom, lower cost factor for lists of introspection types, to prevent introspection queries from having unreasonably high costs. You can adjust this by setting introspectionListFactor on the configuration object.

const ComplexityLimitRule = createComplexityLimitRule(1000, {
  introspectionListFactor: 10, // Default is 2.


Query complexity validation for GraphQL.js







No packages published