{"id":47925,"library":"graphql-query-complexity","title":"graphql-query-complexity","description":"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.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/slicknode/graphql-query-complexity","tags":["javascript","graphql","query","validation","cost","complexity","analysis","typescript"],"install":[{"cmd":"npm install graphql-query-complexity","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-query-complexity","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-query-complexity","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; required to provide validation rule types and GraphQL schema introspection","package":"graphql","optional":false}],"imports":[{"note":"The library is ESM-only since v1; CommonJS require is not supported.","wrong":"const createComplexityRule = require('graphql-query-complexity').createComplexityRule;","symbol":"createComplexityRule","correct":"import { createComplexityRule } from 'graphql-query-complexity';"},{"note":"simpleEstimator is a named export, not a default export.","wrong":"import simpleEstimator from 'graphql-query-complexity';","symbol":"simpleEstimator","correct":"import { simpleEstimator } from 'graphql-query-complexity';"},{"note":"All estimators are exported from the main package entry, not from subpath exports.","wrong":"import { directiveEstimator } from 'graphql-query-complexity/estimators';","symbol":"directiveEstimator","correct":"import { directiveEstimator } from 'graphql-query-complexity';"}],"quickstart":{"code":"import { createComplexityRule, simpleEstimator } from 'graphql-query-complexity';\nimport { validate } from 'graphql';\n\nconst rule = createComplexityRule({\n  maximumComplexity: 1000,\n  variables: {},\n  onComplete: (complexity) => console.log('Query complexity:', complexity),\n  estimators: [\n    simpleEstimator({ defaultComplexity: 1 })\n  ]\n});\n\n// Use with graphql-js validation\n// const errors = validate(schema, document, [rule]);","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade graphql peer dependency to v15 or v16.","message":"Version 1.0.0 dropped support for graphql@14. Only graphql@^15.0.0 || ^16.0.0 are supported.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always provide at least one estimator (e.g., simpleEstimator) to avoid runtime errors.","message":"The 'createComplexityRule' function signature changed in v1.1.0: 'estimators' is now required, not optional.","severity":"deprecated","affected_versions":">=1.1.0"},{"fix":"Ensure all estimators return a number or implement proper error handling. Use simpleEstimator as a catch-all.","message":"If an estimator returns a non-numeric value or throws, no fallback occurs and the validation throws an error.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always pass the query variables object (can be empty: {}).","message":"The 'variables' option must be provided as an object; omitting it leads to incorrect complexity calculation for queries using variables.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update import to use 'createComplexityRule'.","message":"In v0.x, the rule was exported as 'complexityValidationRule'. This was renamed to 'createComplexityRule' in v1.0.0.","severity":"breaking","affected_versions":"<1.0.0"}],"env_vars":null,"search_vec":"'1.1.0':24 'activ':28 'allow':51 'analysi':11,73 'attack':19 'calibr':56 'complex':4,10,72 'cost':55,71 'current':20 'custom':50 'differenti':42 'direct':47 'dos':18 'estim':45 'exhaust':16 'exist':64 'extens':49 'field':48,54 'graphql':2,8,36,65,68 'graphql-j':35 'graphql-query-complex':1 'integr':58 'javascript':67 'js':37 'key':41 'librari':26 'maintain':29 'multipl':44 'per':53 'per-field':52 'protect':13 'queri':3,9,69 'resourc':15 'rule':6,62 'server':66 'simpl':46 'slicknod':31 'stabl':21 'support':43 'typescript':74 'v15':38 'v16':40 'valid':5,61,70 'version':22 'work':33","created_at":"2026-06-07T16:54:02.162380+00:00","updated_at":"2026-06-07T16:54:02.162380+00:00","problems":[{"fix":"Add at least one estimator (e.g., simpleEstimator) in the 'estimators' array.","cause":"No estimator provided a numeric complexity for a field, or no estimators were configured at all.","error":"Error: No estimator returned a complexity value for field 'foo'"},{"fix":"Pass a variables object (e.g., {}) in the configuration.","cause":"The 'variables' option is missing or invalid, causing introspection of variable types to fail.","error":"TypeError: Cannot read properties of undefined (reading 'type')"},{"fix":"Increase maximumComplexity or reduce query depth/complexity via schema design.","cause":"The calculated query complexity exceeds the set maximumComplexity threshold.","error":"ValidationError: Query complexity 1500 exceeds maximum allowed complexity of 1000"},{"fix":"Upgrade graphql to v15 or v16.","cause":"Using graphql-query-complexity v1 with graphql v14.","error":"Error: graphql@14 is not supported. Please upgrade to graphql@15 or graphql@16"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/slicknode/graphql-query-complexity#readme","github":"https://github.com/slicknode/graphql-query-complexity","docs":null,"changelog":null,"pypi":null,"npm":"graphql-query-complexity","openapi_spec":null,"status_page":null,"smithery":null,"categories":["security","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}