@apiratorjs/locking-redis
Version:
An extension to the core @apiratorjs/locking library, providing Redis-based implementations of distributed mutexes and semaphores for true cross-process concurrency control in Node.js.
78 lines (52 loc) • 2.7 kB
Markdown
# @apiratorjs/locking-redis
[](https://www.npmjs.com/package/@apiratorjs/locking-redis)
[](https://github.com/apiratorjs/locking-redis/blob/main/LICENSE)
An extension to the core [@apiratorjs/locking](https://github.com/apiratorjs/locking) library, providing Redis-based implementations of distributed mutexes and
semaphores for true cross-process concurrency control in Node.js.
> **Note:** Requires Node.js version **>=16.4.0**
> A running Redis instance (version 5+ recommended).
## Why Use Redis for Distributed Locking?
- **Multi-instance deployments**: If you have multiple Node.js processes or servers behind a load balancer, an in-memory
lock is insufficient. Redis provides a single, centralized coordination point.
- **Fault tolerance**: Configurable timeouts (TTLs) prevent indefinite locks if a process crashes.
- **Scalability**: Redis can handle many simultaneous locking requests at scale.
## Features
- **Redis-Powered Distributed Mutex and Semaphore**. Enables multi-process or multi-instance synchronization across a
shared Redis server.
- **Compatible API**: Same DistributedMutex and DistributedSemaphore interface
as [@apiratorjs/locking](https://github.com/apiratorjs/locking), so you can swap in Redis without changing the rest of
your code.
- **Time-limited locks (TTL)**. Prevents deadlocks if processes crash without releasing.
- **Cancellation, Timeouts, and FIFO**. Cancel blocked acquisitions, specify timeouts, and queue waiters in a
first-in-first-out manner.
## Installation
Install with npm:
```bash
npm install @apiratorjs/locking @apiratorjs/locking-redis
```
Or with yarn:
```bash
yarn add @apiratorjs/locking @apiratorjs/locking-redis
```
## Usage
```typescript
import { DistributedMutex, DistributedSemaphore } from "@apiratorjs/locking";
import { createRedisLockFactory } from "@apiratorjs/locking-redis";
async function setupRedisBackedLocks() {
const lockFactory = await createRedisLockFactory({ url: "redis://localhost:6379" });
// Override the default in-memory factory:
DistributedMutex.factory = lockFactory.createDistributedMutex;
DistributedSemaphore.factory = lockFactory.createDistributedSemaphore;
}
// Then anywhere else in your code:
const mutex = new DistributedMutex({ name: "global-mutex" });
// This will now automatically use Redis under the hood
```
## Contributing
Contributions, issues, and feature requests are welcome!
Please open an issue or submit a pull request on [GitHub](https://github.com/apiratorjs/locking-redis).