graphql-limiter

library1.3.0jsnpmunverified

GraphQLGate is a rate-limiting library for Node.js and Express that uses query complexity analysis to prevent abusive GraphQL queries. It assigns weights to fields, mutations, and queries to estimate response size, then throttles requests based on token bucket, fixed window, or sliding window algorithms backed by Redis. Version 1.3.0 is current; developed under OSLabs, inspired by IBM research. Key differentiators: depth limits, bounded list enforcement, and customizable type weights. Ships TypeScript definitions.

security

npm install graphql-limiter

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-LIMITER

graphql-limiter

securityjavascriptv1.3.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.

expressGraphQLRateLimiter

✓ import { expressGraphQLRateLimiter } from 'graphql-limiter'

✗ const expressGraphQLRateLimiter = require('graphql-limiter')

Package is ESM-only. Use named import.

graphQLRateLimiter

✓ import { graphQLRateLimiter } from 'graphql-limiter'

✗ import graphQLRateLimiter from 'graphql-limiter'

There is no default export. Must destructure named export.

setRequestTime

✓ import { setRequestTime } from 'graphql-limiter'

Utility to set custom timestamp for request windowing.

setMD5Operation

✓ import { setMD5Operation } from 'graphql-limiter'

Utility to hash operation for sliding window counter.

Demonstrates GraphQL rate limiting with token bucket algorithm, depth limit, and bounded list enforcement on an Express server.

import { expressGraphQLRateLimiter } from 'graphql-limiter'; import express from 'express'; import { graphqlHTTP } from 'express-graphql'; import { buildSchema } from 'graphql'; const schema = buildSchema(` type Query { hello: String } `); const app = express(); app.use('/graphql', expressGraphQLRateLimiter(schema, { rateLimiter: { type: 'TOKEN_BUCKET', refillRate: 10, capacity: 100 }, depthLimit: 5, enforceBoundedLists: true }), graphqlHTTP({ schema }) ); app.listen(4000, () => console.log('Server running on port 4000'));

Debug

Known issues

gotchaRedis must be running before middleware initializes, otherwise requests silently fail.

fix

Start Redis server (e.g., redis-server) or use mocked Redis in development.

affects: >=1.0.0

gotchaList types without @listSize directive will cause infinite complexity if enforceBoundedLists is false.

fix

Set enforceBoundedLists: true or annotate all list fields with @listSize.

affects: >=1.0.0

deprecatedThe 'graphqlLimiter' config option is deprecated; use 'rateLimiter' instead.

fix

Rename 'graphqlLimiter' to 'rateLimiter' in config.

affects: >=0.9.0

gotchaType weights apply globally; cannot differentiate per-type in a single schema.

fix

Use multiple instances for different complexity tiers, or override via middleware per route.

affects: >=1.0.0

gotchaSliding window algorithms require a high-resolution clock; may not work correctly with clustered Node processes.

fix

Use token bucket or fixed window in clustered environments.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'graphql-limiter'

Missing package installation or incorrect import path.

fix

Run 'npm install graphql-limiter --save' and ensure import is correct.

TypeError: expressGraphQLRateLimiter is not a function

Using default import instead of named import.

fix

Use 'import { expressGraphQLRateLimiter } from 'graphql-limiter' instead of default import.

Redis connection refused - ECONNREFUSED 127.0.0.1:6379

Redis server not running or misconfigured.

fix

Start Redis server or set custom Redis options via config.redis.options.

Query complexity exceeded maximum allowed complexity

Query depth or computed complexity over limit.

fix

Increase rateLimiter.capacity or refillRate, or simplify the query.

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

graphqlrequiredpeer dependency for schema introspection and type system

ioredisrequiredrequired for rate limiter state caching

expressoptionalmiddleware integration for GraphQL endpoint

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/oslabs-beta/graphql-gate ↗

packagegraphql-limiter ↗

homepagehttps://github.com/oslabs-beta/GraphQL-Gate#readme ↗