Registry / security / graphql-query-complexity

graphql-query-complexity

library1.1.0jsnpmunverified

Validation rule for GraphQL query complexity analysis to protect against resource exhaustion and DoS attacks. Current stable version is 1.1.0. The library is actively maintained by Slicknode and works with graphql-js v15 and v16. Key differentiators: supports multiple estimators (simple, directive, field extensions, custom), allows per-field cost calibration, and integrates as a validation rule into existing GraphQL servers.

security devops

npm install graphql-query-complexity

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-QUERY-COMP

graphql-query-complexity

securityjavascriptv1.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createComplexityRule

✓ import { createComplexityRule } from 'graphql-query-complexity';

✗ const createComplexityRule = require('graphql-query-complexity').createComplexityRule;

The library is ESM-only since v1; CommonJS require is not supported.

simpleEstimator

✓ import { simpleEstimator } from 'graphql-query-complexity';

✗ import simpleEstimator from 'graphql-query-complexity';

simpleEstimator is a named export, not a default export.

directiveEstimator

✓ import { directiveEstimator } from 'graphql-query-complexity';

✗ import { directiveEstimator } from 'graphql-query-complexity/estimators';

All estimators are exported from the main package entry, not from subpath exports.

Creates a query complexity validation rule and applies it to a GraphQL document. The rule limits total query complexity to 1000 with each field costing 1 by default.

import { createComplexityRule, simpleEstimator } from 'graphql-query-complexity'; import { validate } from 'graphql'; const rule = createComplexityRule({ maximumComplexity: 1000, variables: {}, onComplete: (complexity) => console.log('Query complexity:', complexity), estimators: [ simpleEstimator({ defaultComplexity: 1 }) ] }); // Use with graphql-js validation // const errors = validate(schema, document, [rule]);

Debug

Known issues

breakingVersion 1.0.0 dropped support for graphql@14. Only graphql@^15.0.0 || ^16.0.0 are supported.

fix

Upgrade graphql peer dependency to v15 or v16.

affects: >=1.0.0

deprecatedThe 'createComplexityRule' function signature changed in v1.1.0: 'estimators' is now required, not optional.

fix

Always provide at least one estimator (e.g., simpleEstimator) to avoid runtime errors.

affects: >=1.1.0

gotchaIf an estimator returns a non-numeric value or throws, no fallback occurs and the validation throws an error.

fix

Ensure all estimators return a number or implement proper error handling. Use simpleEstimator as a catch-all.

affects: >=1.0.0

gotchaThe 'variables' option must be provided as an object; omitting it leads to incorrect complexity calculation for queries using variables.

fix

Always pass the query variables object (can be empty: {}).

affects: >=1.0.0

breakingIn v0.x, the rule was exported as 'complexityValidationRule'. This was renamed to 'createComplexityRule' in v1.0.0.

fix

Update import to use 'createComplexityRule'.

affects: <1.0.0

Errors

Common errors & fixes

Error: No estimator returned a complexity value for field 'foo'

No estimator provided a numeric complexity for a field, or no estimators were configured at all.

fix

Add at least one estimator (e.g., simpleEstimator) in the 'estimators' array.

TypeError: Cannot read properties of undefined (reading 'type')

The 'variables' option is missing or invalid, causing introspection of variable types to fail.

fix

Pass a variables object (e.g., {}) in the configuration.

ValidationError: Query complexity 1500 exceeds maximum allowed complexity of 1000

The calculated query complexity exceeds the set maximumComplexity threshold.

fix

Increase maximumComplexity or reduce query depth/complexity via schema design.

Error: graphql@14 is not supported. Please upgrade to graphql@15 or graphql@16

Using graphql-query-complexity v1 with graphql v14.

fix

Upgrade graphql to v15 or v16.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

graphqlrequiredPeer dependency; required to provide validation rule types and GraphQL schema introspection

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/slicknode/graphql-query-complexity ↗

packagegraphql-query-complexity ↗

homepagehttps://github.com/slicknode/graphql-query-complexity#readme ↗