Registry / storage / redis-mutex-semaphore

redis-mutex-semaphore

library0.3.7jsnpmunverified

Mutex and semaphore library implemented using basic Redis commands. Current stable version 0.3.7. Provides two synchronization primitives: mutex (exclusive lock with TTL) and semaphore (counting semaphore). Key differentiator: simple API using callbacks or promises, supports existing Redis connections, and includes wait/observe mechanisms with priority ordering. Unlike redlock or ioredis-based lock libraries, this uses basic Redis commands (SETNX, WATCH, etc.) without Lua scripting. The create methods reset the Redis key, which can lead to accidental context loss — a common footgun. Minimum Redis version 2.6.0+.

storage devops

npm install redis-mutex-semaphore

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REDIS-MUTEX-SEMAPH

redis-mutex-semaphore

storagejavascriptv0.3.7

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.

createMutexClient

✓ import { createMutexClient } from 'redis-mutex-semaphore'

✗ import redisMutex from 'redis-mutex-semaphore'

Library exports factory function as default. Use default import to get factory, then call .createMutexClient. Not named export.

createSemaphoreClient

✓ import factory from 'redis-mutex-semaphore'; factory.createSemaphoreClient(...)

✗ import { createSemaphoreClient } from 'redis-mutex-semaphore'

createSemaphoreClient is a method on the factory object, not a top-level named export.

factory

✓ import factory from 'redis-mutex-semaphore'; const sem = factory(redisClient); sem.createSemaphoreClient(...)

✗ const factory = require('redis-mutex-semaphore').default

ESM default import works; CJS require returns the factory function directly.

Shows basic mutex usage: create factory from Redis client, create mutex with TTL, acquire lock, release lock.

import factory from 'redis-mutex-semaphore'; import redis from 'redis'; const redisClient = redis.createClient({ host: '127.0.0.1', port: 6379 }); const sync = factory(redisClient); // Create a mutex with 10 second TTL sync.createMutexClient('myLock', 10, (err, mutex) => { if (err) { console.error(err); return; } mutex.get((err, mutexID) => { if (mutexID) { console.log('Lock acquired:', mutexID); // Do critical work mutex.rel(mutexID, (err, result) => { console.log('Released:', result); sync.end(); }); } else { console.log('Failed to acquire lock'); sync.end(); } }); });

Debug

Known issues

gotchaCalling createMutexClient or createSemaphoreClient resets the Redis key, potentially losing existing lock/semaphore state. Use getMutexClient/getSemaphoreClient to retrieve existing instances without reset.

fix

Use getMutexClient(key) or getSemaphoreClient(key) after initial creation to avoid resetting keys.

affects: >=0.0.0

gotchaIf the Redis key does not exist when calling semaphoreClient.get(), it returns error with code ENOTFOUNDKEY.

fix

Ensure semaphore key exists by first calling createSemaphoreClient, or handle ENOTFOUNDKEY error appropriately.

affects: >=0.0.0

gotchaPassing incorrect mutexID to mutexClient.rel() returns error with code ENOACCESS.

fix

Store the mutexID returned from mutexClient.get() and use it exactly in the release call.

affects: >=0.0.0

deprecatedCallback-based API is legacy; promise-based usage (omitting callback) is preferred since v0.3.6.

fix

Use promise syntax: await mutexClient.get() instead of callback.

affects: >=0.3.6

Errors

Common errors & fixes

Error: ENOTFOUNDKEY

Semaphore key does not exist in Redis when calling get() on a semaphore client that was retrieved via getSemaphoreClient (not create).

fix

Ensure you call createSemaphoreClient first to initialize the key, or handle the error with proper fallback.

Error: ENOACCESS

Incorrect mutexID passed to release method, or someone else released the mutex already.

fix

Verify you are using the exact mutexID returned by get() and that the mutex is still held by you.

TypeError: redisSharedObject is not a function

Imported the module incorrectly (e.g., using named import instead of default import).

fix

Use: import factory from 'redis-mutex-semaphore' (ESM) or const factory = require('redis-mutex-semaphore') (CJS).

Upgrade

Version history

0.3.7latest on npm

Audit

Dependencies

redisrequiredRequired for connecting to Redis server. The library uses the standard 'redis' npm package for all Redis commands.

Agent activity

39 hits · last 30 days

node

Amazon

Resources

githubssh://git@github.com/loolaz/redis-mutex-semaphore ↗

packageredis-mutex-semaphore ↗

homepagehttps://github.com/loolaz/redis-mutex-semaphore#readme ↗