Registry / http-networking / apollo-server-plugin-query-complexity

apollo-server-plugin-query-complexity

library4.0.0jsnpmunverified

The `apollo-server-plugin-query-complexity` package provides a plugin for `@apollo/server` to enforce query complexity limits, safeguarding against overly resource-intensive queries. It is currently at version 4.0.0, aligning with `@apollo/server` v4.x. This plugin differentiates itself by being fully compatible with GraphQL operation variables, a feature that standard `graphql-js` validation rules cannot directly access when integrated with Apollo Server. It leverages `graphql-query-complexity` for its core estimation logic, supporting various estimators like `directiveEstimator` and `simpleEstimator`, which allow developers to define complexity values directly within their schema or through default calculation rules. This mechanism is crucial for preventing denial-of-service attacks by ensuring server stability and fair resource allocation. The project appears actively maintained, with releases typically synchronized with major `@apollo/server` versions.

http-networking auth-security web-framework

npm install apollo-server-plugin-query-complexity

github ↗package ↗

INSTALL

IMPORT

SIG · APOLLO-SERVER-PLUG

apollo-server-plugin-query-complexity

http-networkingjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

ApolloServerPluginQueryComplexity

✓ import ApolloServerPluginQueryComplexity from 'apollo-server-plugin-query-complexity';

✗ const ApolloServerPluginQueryComplexity = require('apollo-server-plugin-query-complexity');

The primary default export for the plugin factory. Primarily designed for ESM usage with Apollo Server v4.

QueryComplexityError

✓ import { QueryComplexityError } from 'apollo-server-plugin-query-complexity';

Named export for the custom error type, useful for distinguishing complexity errors in custom error formatting.

directiveEstimator, simpleEstimator

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

✗ import { directiveEstimator, simpleEstimator } from 'apollo-server-plugin-query-complexity';

These estimators are sourced directly from the `graphql-query-complexity` peer dependency, not from this plugin package itself.

Demonstrates how to integrate the query complexity plugin into an Apollo Server instance with directive-based and simple complexity estimators, setting a maximum complexity limit.

import { ApolloServer } from '@apollo/server'; import ApolloServerPluginQueryComplexity from 'apollo-server-plugin-query-complexity'; import { directiveEstimator, simpleEstimator } from 'graphql-query-complexity'; const typeDefs = `#graphql directive @complexity( value: Int! multipliers: [String!] ) on FIELD_DEFINITION type Query { a: String! # Complexity of 1 b(n: Int!): String! @complexity(value: 1, multipliers: ["n"]) # Complexity of variable "n" } `; const server = new ApolloServer({ typeDefs, resolvers: {}, plugins: [ ApolloServerPluginQueryComplexity({ estimators: [directiveEstimator(), simpleEstimator()], maximumComplexity: 100, }), ], }); // Example of starting the server (assuming a basic setup, e.g., for testing) // This part is illustrative and depends on your Apollo Server integration (e.g., Express, standalone) async function startApolloServer() { // In a real application, you'd likely use startStandaloneServer or integrate with a web framework // For demonstration, let's just log that the server is configured console.log('Apollo Server configured with Query Complexity Plugin.'); console.log('Maximum complexity set to 100.'); } startApolloServer();

Debug

Known issues

breakingVersion 4.x of `apollo-server-plugin-query-complexity` is designed exclusively for `@apollo/server` v4.x and `graphql` v16.x. Attempting to use this plugin version with older Apollo Server (e.g., `apollo-server` v3.x or `apollo-server-express` v3.x) will lead to runtime errors due to fundamental changes in Apollo Server's plugin API.

fix

Ensure your project's `@apollo/server` and `graphql` dependencies are upgraded to their respective v4 and v16 versions, respectively, before installing `apollo-server-plugin-query-complexity@4.x`.

affects: >=4.0.0

gotchaThe default error message for queries exceeding the complexity limit can be generic. For a better user experience, it's highly recommended to implement a custom `formatError` function in your `ApolloServer` configuration to catch `QueryComplexityError` and provide more descriptive feedback, including the requested and maximum complexity values.

fix

Add a `formatError` option to your `ApolloServer` constructor that checks if `error instanceof QueryComplexityError` and returns a custom formatted error object.

affects: >=1.0.0

gotchaMisconfiguring complexity estimators can either render the plugin ineffective (allowing overly complex queries) or too restrictive (rejecting legitimate queries). Ensure all fields in your schema have a valid complexity estimation strategy, combining `directiveEstimator` for annotated fields and `simpleEstimator` or custom estimators for unannotated fields.

fix

Carefully review your `estimators` array in the `ApolloServerPluginQueryComplexity` configuration. Ensure `directiveEstimator()` is included if using `@complexity` directives, and consider `simpleEstimator()` as a fallback or default for fields without explicit directives.

affects: >=1.0.0

gotcha`apollo-server-plugin-query-complexity` lists `graphql-query-complexity` as a peer dependency, meaning it must be installed separately by the user. Forgetting to install `graphql-query-complexity` will result in runtime errors as the plugin won't find its essential estimation logic.

fix

Always install `graphql-query-complexity` alongside `apollo-server-plugin-query-complexity`: `npm install graphql-query-complexity` or `yarn add graphql-query-complexity`.

affects: >=1.0.0

Errors

Common errors & fixes

message: "Query is too complex. Requested complexity XXX is greater than maximum allowed YYY."

The calculated complexity of a GraphQL query, based on the plugin's estimators, exceeded the `maximumComplexity` defined in the plugin configuration.

fix

Either optimize the client-side query to reduce its complexity, or adjust the `maximumComplexity` setting in your `ApolloServerPluginQueryComplexity` configuration if the current limit is too strict for intended use cases. Review your complexity estimators for accuracy.

Error: Cannot find module '@apollo/server' or Error: Cannot find module 'graphql-query-complexity'

One or more of the required peer dependencies (`@apollo/server`, `graphql`, or `graphql-query-complexity`) are not installed in the project or are installed with an incompatible version.

fix

Install the missing peer dependencies using your package manager, ensuring their versions meet the requirements specified by `apollo-server-plugin-query-complexity@4.x`: `npm install @apollo/server@^4.0.0 graphql@^16.6.0 graphql-query-complexity@^0.12.0`.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

@apollo/serverrequiredRequired as the core Apollo Server framework that the plugin integrates with.

graphqlrequiredThe underlying GraphQL.js library, essential for schema parsing and query validation.

graphql-query-complexityrequiredProvides the core logic and estimators for calculating GraphQL query complexity.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/nvdaz/apollo-server-plugin-query-complexity ↗

packagehttps://www.npmjs.com/package/apollo-server-plugin-query-complexity ↗