redis-expiry

library1.1.8jsnpmunverified

A Redis-based key expiration and event scheduling library for Node.js (v1.1.8). It allows scheduling key expiration via timeout, absolute date, cron pattern, or immediate expiry, and provides event handlers that fire when keys expire, including regex pattern matching. Unlike simple Redis TTL, redis-expiry persists scheduled expirations across application restarts by storing metadata in Redis. Supports CRUD operations and rescheduling. Suitable for timed tasks, cron jobs, and cache invalidation with guaranteed execution after restart. Release cadence is sporadic; last update was 2020.

database devops

npm install redis-expiry

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REDIS-EXPIRY

redis-expiry

databasejavascriptv1.1.8

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.

default

✓ const redisExpiry = require('redis-expiry');

✗ import redisExpiry from 'redis-expiry';

This package is CommonJS only; ESM import will fail.

function redisExpiry(setterClient, getterClient)

✓ const rexp = redisExpiry(redisSetter, redisGetter);

✗ const rexp = redisExpiry(redisSetter, process.env.REDIS_URL);

Since v1.0.4, the second argument must be a Redis client (getter), not a URL. The URL overload is deprecated.

rexp.on(event, callback, options)

✓ rexp.on(/pattern/, (value, key) => { /* ... */ });

✗ rexp.on(/pattern/, function(value) { /* ... */ });

The callback receives (value, key, stop). When using regex pattern, the callback is invoked per matching key.

rexp.set(key, value).timeout(ms)

✓ await rexp.set('key', 'val').timeout(60000);

✗ rexp.set('key', 'val').timeout(60000);

All scheduling methods return a Promise; you must await or handle .then() to ensure the key is set before expiration.

Initializes redis-expiry with two Redis clients, schedules a key to expire in 10 seconds, attaches an expiration handler, then removes the scheduler.

Debug

Known issues

deprecatedPassing a Redis URL as second argument to redisExpiry() is deprecated since v1.0.4.

fix

Pass a second Redis client instance instead: redisExpiry(setterClient, getterClient).

affects: >=1.0.4

gotchaThe set() method returns an object with scheduling methods (.timeout, .at, .cron, etc.) that are not executed until awaited. Forgetting await may cause the key to never expire.

fix

Always await the result of rexp.set(...).timeout(...) or chain .then() to ensure scheduling completes.

affects: >=1.0.0

breakingThe package uses two separate Redis connections (setter and getter) but does not handle disconnection or reconnection. If a connection drops, events may be lost or the library may hang.

fix

Implement your own reconnection logic on the Redis clients, or use a single client and pass it twice (though this may risk blocking).

affects: >=1.0.0

gotchaCron-based expiration with .cron() reschedules after each expiration. To stop it, the handler must call the provided stop() function; otherwise, the cron continues indefinitely.

fix

In your handler callback, accept the third argument 'stop' and call stop() when you want to halt the cron repetition.

affects: >=1.0.0

gotchaEvent handlers registered with regex patterns (e.g., /myKeyBy(.)/) listen to all keys matching the pattern. If multiple keys match, the handler is invoked for each expiration concurrently unless maxConcurrent is specified.

fix

Set the 'maxConcurrent' option in rexp.on(pattern, callback, { maxConcurrent: 1 }) to serialize callbacks for the same pattern.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: redisExpiry is not a function

Using ESM import 'import redisExpiry from 'redis-expiry'' on a CommonJS-only package.

fix

Use require('redis-expiry') instead, or use dynamic import if you must use ESM: const redisExpiry = (await import('redis-expiry')).default;

Error: The second argument must be a redis client

Passing a Redis URL string as the second argument instead of a client instance (changed in v1.0.4).

fix

Create a second Redis client and pass it: redisExpiry(setterClient, getterClient).

UnhandledPromiseRejectionWarning: TimeoutError: The set operation timed out

The Redis client connection is not ready or disconnected.

fix

Ensure both Redis clients are connected before initializing redis-expiry. Use Redis client's 'ready' event or connect() method.

AssertionError [ERR_ASSERTION]: Invalid cron expression

Cron expression passed to .cron() is invalid or incompatible with cron-parser.

fix

Verify the cron expression format (e.g., '*/4 * * * * *' for every 4 seconds). Refer to https://www.npmjs.com/package/cron-parser for valid syntax.

Upgrade

Version history

1.1.8latest on npm

Audit

Dependencies

redisrequiredRequired for Redis client instances passed during initialization

cron-parseroptionalUsed internally for cron expression parsing when using the .cron() method

Agent activity

15 hits · last 30 days

node