Need Package Maintenance
Introducing npm Teams! Private packages + team management tools.Learn more »


0.2.5 • Public • Published

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, pass the complexity limit rule to validationRules.

const graphqlMiddleware = graphqlHTTP({
  validationRules: [

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 on fields definitions with getCost and getCostFactor callbacks.

const expensiveField = {
  type: ExpensiveItem,
  getCost: () => 50,
const expensiveList = {
  type: new GraphQLList(MyItem),
  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.



npm i graphql-validation-complexity

DownloadsWeekly Downloads






Unpacked Size

15.9 kB

Total Files


Last publish


  • avatar