Registry / security / graphql-rate-limit-directive

graphql-rate-limit-directive

library2.0.6jsnpmunverified

A fixed window rate-limiting directive for GraphQL schemas (v2.0.6). It wraps resolvers to enforce per-field or per-object rate limits using a declarative @rateLimit directive. Supports multiple backends (Redis, in-memory via rate-limiter-flexible), custom key generation, and response extensions. Requires graphql ^16.0.0, @graphql-tools/utils ^8-10, and rate-limiter-flexible ^2-5. Differentiated by its directive-based approach and TypeScript support.

security

npm install graphql-rate-limit-directive

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-RATE-LIMIT

graphql-rate-limit-directive

securityjavascriptv2.0.6

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.

rateLimitDirective

✓ import { rateLimitDirective } from 'graphql-rate-limit-directive'

✗ const { rateLimitDirective } = require('graphql-rate-limit-directive')

ESM-only since v2; CommonJS require() still works but is deprecated.

rateLimitDirectiveTypeDefs

✓ const { rateLimitDirectiveTypeDefs } = rateLimitDirective();

✗ import { rateLimitDirectiveTypeDefs } from 'graphql-rate-limit-directive'

TypeDefs must be obtained from the directive factory function, not top-level export.

rateLimitDirectiveTransformer

✓ const { rateLimitDirectiveTransformer } = rateLimitDirective();

✗ import { rateLimitDirectiveTransformer } from 'graphql-rate-limit-directive'

Transformer must be obtained from the directive factory function, not top-level export.

Creates a GraphQL server with @rateLimit directive limiting Query.hello to 10 calls per 60 seconds.

import { rateLimitDirective } from 'graphql-rate-limit-directive'; import { makeExecutableSchema } from '@graphql-tools/schema'; import { ApolloServer } from '@apollo/server'; const { rateLimitDirectiveTypeDefs, rateLimitDirectiveTransformer } = rateLimitDirective(); const typeDefs = ` type Query @rateLimit(limit: 10, duration: 60) { hello: String } `; const resolvers = { Query: { hello: () => 'world' } }; let schema = makeExecutableSchema({ typeDefs: [rateLimitDirectiveTypeDefs, typeDefs], resolvers }); schema = rateLimitDirectiveTransformer(schema); const server = new ApolloServer({ schema }); server.listen(4000).then(({ url }) => console.log(`Server ready at ${url}`));

Debug

Known issues

breakingIn version 2.0.0, the package switched from CommonJS to ESM. require() usage breaks in strict ESM environments.

fix

Use import syntax; configure Node.js for ESM ("type": "module" in package.json) or use dynamic import().

affects: >=2.0.0

breakingThe top-level export no longer includes rateLimitDirectiveTypeDefs and rateLimitDirectiveTransformer directly. They must be obtained from calling rateLimitDirective().

fix

Replace import { rateLimitDirectiveTypeDefs, rateLimitDirectiveTransformer } with const { ... } = rateLimitDirective();

affects: >=2.0.0

deprecatedSupport for graphql versions <16.0.0 and rate-limiter-flexible <2.0.0 is dropped.

fix

Upgrade graphql to ^16.0.0 and rate-limiter-flexible to ^2.0.0 || ^3.0.0 || ^4.0.0 || ^5.0.0

affects: >=2.0.0

gotchaIf you use a custom keyGenerator, it must return a string; otherwise rate limiting may behave unexpectedly.

fix

Ensure keyGenerator returns a string (e.g., String(context.ip)).

affects: >=1.0.0

gotchaThe directive relies on @graphql-tools/schema's makeExecutableSchema. If you use a different schema builder, the transformer may not work.

fix

Adopt makeExecutableSchema from @graphql-tools/schema or wrap the transformer accordingly.

affects: >=1.0.0

gotchaRate limiting applies after resolver invocation, not before when points system is used. This might permit partial execution if resolver fails.

fix

Use 'points' configuration to associate costs; ensure resolver failure doesn't consume points.

affects: >=1.0.0

gotchaIn distributed environments, in-memory rate limiter is not shared. Use Redis backend for consistent limits across instances.

fix

Configure rateLimiterFactory to return an instance of RateLimiterRedis from rate-limiter-flexible.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'graphql-rate-limit-directive'

Package not installed or ESM/CJS misconfiguration.

fix

Run npm install graphql-rate-limit-directive and ensure all peer dependencies are installed. For ESM, add "type": "module" to package.json.

rateLimitDirectiveTransformer is not a function

Using top-level import instead of calling rateLimitDirective().

fix

Use: const { rateLimitDirectiveTransformer } = rateLimitDirective();

Expected a string key but got undefined

keyGenerator function returned undefined or null.

fix

Ensure keyGenerator always returns a string, e.g., keyGenerator: (context) => context.req.ip ?? 'anonymous'

Directive "rateLimit" is not defined

rateLimitDirectiveTypeDefs not included in schema type definitions.

fix

Add rateLimitDirectiveTypeDefs to the typeDefs array in makeExecutableSchema.

Type 'RateLimiterAbstract' is not assignable to type 'RateLimiterAbstract'

Incompatible version of rate-limiter-flexible.

fix

Ensure rate-limiter-flexible is ^2.0.0 || ^3.0.0 || ^4.0.0 || ^5.0.0 and matches the version used in the package lock.

Upgrade

Version history

2.0.6latest on npm

Audit

Dependencies

graphqlrequiredPeer dependency required for Schema/GraphQL type definitions

@graphql-tools/utilsrequiredPeer dependency for schema transformation utilities

rate-limiter-flexiblerequiredPeer dependency providing rate limiting backends (Redis, Memory, etc.)

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/ravangen/graphql-rate-limit ↗

packagegraphql-rate-limit-directive ↗

homepagehttps://github.com/ravangen/graphql-rate-limit#readme ↗