redfour

library2.2.2jsnpmunverified

A Redis-based binary semaphore implementation using pub/sub for fast async wait, unlike polling-based alternatives. Version 2.2.2 is the latest stable release. Key differentiator: uses Redis pub/sub to notify waiters when a lock is released, making it much faster than polling-based locks. Supports Node >=7.6.0. Ideal for coordinating access to shared resources (e.g., token refresh) across multiple processes or servers.

storage

npm install redfour

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REDFOUR

redfour

storagejavascriptv2.2.2

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.

Lock

✓ import Lock from 'redfour'

✗ const { Lock } = require('redfour')

Default export is the Lock class. Named export does not exist.

Lock (CommonJS)

✓ const Lock = require('redfour')

✗ const redfour = require('redfour').default

CommonJS require gets the default export directly.

Lock instance methods

✓ const lock = new Lock({ redis: '...', namespace: 'test' }); await lock.acquireLock(id, ttl); await lock.waitAcquireLock(id, ttl, timeout); await lock.releaseLock(lockObj);

acquireLock and waitAcquireLock return an object with success, id, index, ttl. releaseLock expects that object.

Shows how to create a Lock instance, acquire a lock with a TTL, perform work, and release it.

import Lock from 'redfour'; const lock = new Lock({ redis: process.env.REDIS_URL ?? 'redis://localhost:6379', namespace: 'mylock' }); const id = Math.random().toString(); try { const acquired = await lock.acquireLock(id, 60 * 1000); if (acquired.success) { console.log('Lock acquired'); // Do critical section work... await lock.releaseLock(acquired); } else { console.log('Could not acquire lock'); } } catch (err) { console.error('Error:', err); }

Debug

Known issues

gotchaThe module creates two Redis connections if an existing client is not provided. Be aware of connection overhead.

fix

Reuse an existing Redis client instance by passing it to the constructor.

affects: >=2.0.0

gotchaLock TTL must be provided as milliseconds (not seconds). Common mistake: passing seconds results in unintended short TTL.

fix

Ensure TTL is in milliseconds (e.g., 60000 for 60 seconds).

affects: >=2.0.0

gotchawaitAcquireLock timeout is also in milliseconds. Mistaking it for seconds causes premature timeout.

fix

Pass timeout in milliseconds. For 10 seconds, use 10000.

affects: >=2.0.0

deprecatedNode.js <7.6.0 is not supported due to async/await usage.

fix

Upgrade Node.js to >=7.6.0.

affects: >=2.0.0

gotchaIf the Redis server goes down, acquireLock and waitAcquireLock may hang indefinitely without timeout.

fix

Implement application-level timeouts or use Redis connection retry strategies.

affects: >=2.0.0

Errors

Common errors & fixes

Error: The namespace option is required

Missing 'namespace' option when creating Lock instance.

fix

const lock = new Lock({ redis: '...', namespace: 'myapp' });

TypeError: lock.acquireLock is not a function

Importing named export { Lock } instead of default import when using ES modules.

fix

Use import Lock from 'redfour'; (default import) or const Lock = require('redfour') in CommonJS.

Error: The lock does not exist

Trying to release a lock that has expired or was already released.

fix

Ensure lock is still valid before releasing, or handle the error gracefully.

Error: Lock wait timed out

The timeout in waitAcquireLock expired before the lock was acquired.

fix

Increase timeout value or ensure locks are released promptly.

Upgrade

Version history

2.2.2latest on npm

Audit

Dependencies

redisrequiredRequired to connect to Redis and create client(s) for pub/sub and lock operations.

Agent activity

18 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/mixmaxhq/redfour ↗

packageredfour ↗

homepagehttps://github.com/mixmaxhq/redfour#readme ↗