redis-gcra

library0.7.0jsnpmunverified

An implementation of the Generic Cell Rate Algorithm (GCRA) for rate limiting using Redis. Version 0.7.0 is the latest stable release, updated as of early 2025. It supports both ioredis and node-redis clients, with TypeScript type definitions included. Key differentiators are its reliance on the efficient GCRA algorithm (no token bucket overhead) and minimal dependencies. The package provides three core methods: limit (attempt to consume tokens), peek (check availability without consumption), and reset (clear state for a key). It is actively maintained by Losant with a focus on correctness and performance.

storage devops

npm install redis-gcra

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REDIS-GCRA

redis-gcra

storagejavascriptv0.7.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.

RedisGCRA

✓ import RedisGCRA from 'redis-gcra'

✗ const RedisGCRA = require('redis-gcra')

ESM-only since v0.7.0; CommonJS require will fail.

RedisGCRA (default import)

✓ import redisGcra from 'redis-gcra'

✗ import { default as redisGcra } from 'redis-gcra'

The module is a default export, not a named export.

TypeScript types

✓ import type { Limiter } from 'redis-gcra'

✗ import { Limiter } from 'redis-gcra'

In TypeScript, type-only imports avoid emitting runtime code.

Initializes a GCRA limiter with an ioredis client and performs a rate limit check using the limit method.

import RedisGCRA from 'redis-gcra'; import IORedis from 'ioredis'; const redis = new IORedis(); const limiter = RedisGCRA({ redis, keyPrefix: 'ratelimit:', burst: 60, rate: 1, period: 1000, cost: 1 }); async function checkRateLimit(key) { const result = await limiter.limit({ key }); if (result.allowed) { console.log('Request allowed. Remaining tokens:', result.remaining); } else { console.log('Rate limited. Retry after ms:', result.retryIn); } } checkRateLimit('user:123');

Debug

Known issues

breakingESM-only since v0.7.0: CommonJS require() no longer works; must use import syntax.

fix

Use import rather than require, or stick with v0.6.x if CJS required.

affects: >=0.7.0

breakingNode.js >=20 required as of v0.7.0; older Node.js versions are unsupported.

fix

Upgrade Node.js to v20 or later.

affects: >=0.7.0

gotchaWhen using node-redis, you must use a custom pattern: the library requires the client to expose a defineCommand method. node-redis v4 does not support this; use ioredis or a wrapper.

fix

Use ioredis instead of node-redis for compatibility, or manually adapt node-redis client.

affects: *

deprecatedThe option 'redis' may be renamed in future versions; documentation refers to it as 'redis' but it must be an ioredis-like client.

fix

None yet; follow releases for future changes.

affects: <1.0

gotchaThe limit method returns null if no result from Redis; always check for null before accessing properties.

fix

Guard against null: const result = await limiter.limit(...); if (result) { ... }

affects: *

Errors

Common errors & fixes

Error: redis-gcra requires Node.js >=20

Running on an older Node.js version (e.g., v18).

fix

Upgrade to Node.js v20 or above.

TypeError: limiter.limit is not a function

Incorrect import: using require() in v0.7.0+ which is ESM-only.

fix

Change to import RedisGCRA from 'redis-gcra'.

Error [ERR_REQUIRE_ESM]: require() of ES Module

Using require() on an ESM-only package.

fix

Use import or downgrade to v0.6.x.

Error: redisClient.defineCommand is not a function

Using node-redis v4 which lacks defineCommand; ioredis required.

fix

Switch to ioredis or wrap node-redis with a defineCommand shim.

Upgrade

Version history

0.7.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

35 hits · last 30 days

node

Resources

githubhttps://github.com/Losant/redis-gcra ↗

packageredis-gcra ↗

homepagehttps://github.com/Losant/redis-gcra#readme ↗