redis-bucket

library2.0.0jsnpmunverified

A Redis-backed leaky-bucket rate limiter (v2.0.0) that uses EVAL/EVALSHA-based Lua scripts for atomic operations, enabling shared rate-limiting across distributed instances without Redis modules. Supports tiered capacity and rate metrics with configurable backoff. Actively maintained with TypeScript types included. Compared to alternatives like express-rate-limit (in-memory), it provides centralized state; compared to ratelimiter (Redis-based with custom modules), it works on hosted Redis without module support.

storage testing

npm install redis-bucket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REDIS-BUCKET

redis-bucket

storagejavascriptv2.0.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.

create

✓ import { create } from 'redis-bucket';

✗ import limiter from 'redis-bucket';

This library uses named exports; default import is incorrect in ESM. TypeScript types are included.

limiter module (namespace import)

✓ import * as limiter from 'redis-bucket';

✗ const limiter = require('redis-bucket');

CommonJS require works but is less ideal for TypeScript; the namespace import matches the README pattern. ESM-only is not enforced, but require is less common.

CapacityConfig

✓ import type { CapacityConfig } from 'redis-bucket';

✗ import { CapacityConfig } from 'redis-bucket'; (if using at runtime)

CapacityConfig is a TypeScript type, not a value. Use type-only import to avoid runtime errors.

Creates a Redis client, connects, and initializes a rate limiter with capacity-based limits and exponential backoff.

import { create } from 'redis-bucket'; import { createClient } from 'redis'; const client = createClient(); client.on('error', (err) => console.error('Redis Client Error', err)); await client.connect(); const limit = create({ capacity: { window: 60, min: 10, max: 20 }, backoff: (x) => 2 ** x, eval: async (script, keys, argv) => { return client.eval(script, { keys, arguments: argv.map(String) }); }, evalsha: async (sha, keys, argv) => { return client.evalSha(sha, { keys, arguments: argv.map(String) }); }, }); const result = await limit('user:123'); console.log('Allow:', result.allow, 'Free:', result.free, 'Wait:', result.wait); await client.disconnect();

Debug

Known issues

breakingIn v2.0.0, the 'eval' and 'evalsha' callbacks now receive an array of arguments (argv) as unknown[]; previously they were strings[]. Your callback must handle this type change.

fix

Update callback signature to accept unknown[] and convert as needed.

affects: >=2.0.0

gotchaThe 'eval' callback is required; 'evalsha' is optional but highly recommended for performance. If evalsha is not provided, only EVAL is used (no script caching).

fix

Provide evalsha callback to leverage script caching.

affects: >=1.0.0

deprecatedIn v1.x, the 'script' property was passed directly; in v2.x, the callbacks use different signatures. Old custom scripts will break.

fix

Migrate to v2 callback interface as shown in the API docs.

affects: <2.0.0

breakingFrom v2.0.0, the result property 'free' returns remaining capacity (not always an integer). In v1.x it was always an integer. Ensure your code handles fractional values.

fix

Adjust logic that expects integer free values.

affects: >=2.0.0

gotchaRedis client connection errors are not handled by the limiter; if the client disconnects, eval calls will throw. You must implement reconnection logic outside the library.

fix

Use a Redis client with built-in reconnection (e.g., ioredis) or implement your own retry/handle in the eval callback.

affects: >=1.0.0

breakingIn v2.0.0, the 'capacity' and 'rate' options no longer accept arrays of numbers; they require objects with 'window', 'min', 'max' (for capacity) or 'interval', 'rate' (for rate). Old numeric arrays will cause runtime errors.

fix

Update configuration to use the object format.

affects: >=2.0.0

deprecatedThe 'linear' backoff function was the default in v1.x; in v2.x, exponential is recommended but linear still works if explicitly provided.

fix

If upgrading, consider using exponential backoff or specify your own backoff function.

affects: <2.0.0

Errors

Common errors & fixes

TypeError: client.eval is not a function

Using an incompatible Redis client (e.g., a pool wrapper) that does not expose eval directly.

fix

Use a standard Redis client like 'redis' or 'ioredis' that implements eval. Ensure you are passing the correct client reference.

Error: Connection closed (Error) at ...

Redis connection lost before limit() calls. The limiter does not handle reconnection.

fix

Configure your Redis client to automatically reconnect (e.g., enable retry strategy in ioredis or use a resilient client).

TypeError: limit is not a function

Default import used instead of named import: import limiter from 'redis-bucket' returns an object with create, not a function.

fix

Use import { create } from 'redis-bucket' and then call create(config) to get the limit function.

ERR wrong number of arguments for 'eval' command

The eval callback is not returning the raw Redis reply correctly; the library expects a specific format.

fix

Ensure eval/evalsha callbacks return the result from Redis client's eval/evalsha directly (array of values). Do not modify.

Property 'allow' does not exist on type 'Result' (TypeScript)

Using an older version of the type definitions (v1.x) where result props were named differently (e.g., 'allowed').

fix

Update to redis-bucket@2.0.0 with npm install redis-bucket@latest. If locking, ensure @types are up to date.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

redisrequiredRequired for creating a Redis client to pass to the limiter; the library itself only needs eval/evalsha callbacks.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/plsmphnx/redis-bucket ↗

packageredis-bucket ↗

homepagehttps://github.com/plsmphnx/redis-bucket#readme ↗