redis-semaphore

library5.7.0jsnpmunverified

Redis-based distributed mutex (lock) and semaphore implementations for Node.js applications. Current stable version 5.7.0. Actively maintained with regular releases. Key differentiators: fully atomic operations using LUA scripts (fail-safe), built-in lock auto-refresh, optional lock-loss detection, and a simple API. Compared to alternatives like 'redlock', redis-semaphore offers more fine-grained control over lock timeout, acquire attempts, and refresh intervals, plus explicit lost-lock handling. Works exclusively with ioredis client. Ships TypeScript types.

database

npm install redis-semaphore

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REDIS-SEMAPHORE

redis-semaphore

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

Mutex

✓ import { Mutex } from 'redis-semaphore'

✗ const Mutex = require('redis-semaphore').Mutex

ESM vs CJS: the package supports both, but ESM is recommended. For CJS, use `const { Mutex } = require('redis-semaphore')`

Semaphore

✓ import { Semaphore } from 'redis-semaphore'

✗ import * as redisSemaphore from 'redis-semaphore'; const Semaphore = redisSemaphore.Semaphore

Named export, not a default export. Use destructured import.

LockOptions

✓ import { LockOptions } from 'redis-semaphore'

TypeScript type for options passed to Mutex constructor. Only relevant with TypeScript.

Mutex (CommonJS)

✓ const { Mutex } = require('redis-semaphore')

✗ const redis = require('redis-semaphore'); new redis.Mutex(...)

Correct destructuring avoids odd capitalization.

Redis.Type (for custom client)

✓ import { Redis as IORedis } from 'ioredis'; client: IORedis

Constructor expects an ioredis-compatible client. Specify the correct type if using custom subclass.

Demonstrates creating a Mutex instance, acquiring the lock, executing critical code, and releasing the lock with error handling.

import Redis from 'ioredis'; import { Mutex } from 'redis-semaphore'; async function main() { const redisClient = new Redis(); const mutex = new Mutex(redisClient, 'resource-key', { lockTimeout: 5000, acquireTimeout: 10000, acquireAttemptsLimit: 50, retryInterval: 100, refreshInterval: 4000, }); await mutex.acquire(); try { console.log('Lock acquired, doing critical work...'); // Simulate work await new Promise(resolve => setTimeout(resolve, 2000)); } finally { await mutex.release(); console.log('Released lock.'); } redisClient.quit(); } main().catch(console.error);

Debug

Known issues

breakingVersion 5.0.0 changed the default lockTimeout from Infinity to 10000 ms. If your code relied on infinite timeout, lock will expire after 10 seconds.

fix

Pass explicit lockTimeout (e.g., 0 for no expiry, though not recommended) to preserve old behavior.

affects: >=5.0.0

breakingVersion 4.0.0 dropped Node.js 10 support. Minimum Node version is now 14.17.0.

fix

Upgrade Node.js to v14.17.0 or later.

affects: >=4.0.0

deprecatedThe `acquireAttemptsLimit` option default changed from Infinity to Number.POSITIVE_INFINITY. No functional change, but the option may be renamed in a future major version.

fix

Use `acquireAttemptsLimit: Infinity` or `Number.POSITIVE_INFINITY` as needed.

affects: >=5.0.0

gotchaThe `mutex.release()` call, even if lock no longer belongs to the current mutex, has no effect. It is safe to always call release.

fix

Understand that release is idempotent and safe to call unconditionally.

affects: >=1.0.0

gotchaWhen using `acquiredExternally` option with a custom `identifier`, ensure the identifier is unique across parallel executors. Sharing the same identifier may treat multiple locks as the same holder.

fix

Use unique identifiers (e.g., from crypto.randomUUID()) unless you explicitly need to share the lock.

affects: >=5.0.0

gotchaThe `onLockLost` callback defaults to throwing an unhandled LostLockError. If not handled, this can crash the process.

fix

Provide an onLockLost callback to avoid unhandled errors, or catch LostLockError globally.

affects: >=5.0.0

Errors

Common errors & fixes

Error: The 'lockTimeout' option must be a number at new Mutex

Passing a non-number value (e.g., string) to lockTimeout option.

fix

Ensure lockTimeout is a number, e.g., `{ lockTimeout: 10000 }`.

TypeError: redisClient.subscribe is not a function

Using a Redis client that is not ioredis-compatible (e.g., redis package v4+).

fix

Install and use `ioredis` as the client: `npm install ioredis` and pass an instance.

LostLockError: Mutex lock lost: 'resource-key'

The lock was expired or removed externally (e.g., by another process or due to network issues) and the refresh cycle detected it.

fix

Either handle the error via onLockLost callback, or avoid long-running critical sections that exceed lockTimeout.

Upgrade

Version history

5.7.0latest on npm

Audit

Dependencies

ioredisrequiredRequired peer dependency – redis client used to interact with Redis server

Agent activity

14 hits · last 30 days

node