@trellisorg/distributed-lock NPM

@trellisorg/distributed-lock

This library provides a simple way to implement distributed locks using Redis. It is designed to be easy to use and integrate with your existing Node.js applications.

Installation

npm install @trellisorg/distributed-lock ioredis

Setup

Standalone TypeScript

import { RedisMutex } from '@trellisorg/distributed-lock/redis-mutex';
import Redis from 'ioredis';

const redisClient = new Redis({
    host: 'localhost',
    port: 6379,
});

const redisMutex = new RedisMutex({
    client: redisClient,
    lockPrefix: 'my-app',
    lockTimeout: 10_000,
    fifo: false,
});

// Acquire a lock on the resource 'my-resource'
const lock = await redisMutex.lock('my-resource');

// Do some work that requires the lock
console.log('Working with the resource...');

// Release the lock
await lock.unlock();

NestJS

import { Module } from '@nestjs/common';
import { DistributedLockModule } from '@trellisorg/distributed-lock/nest';
import { redisMutexLockAdapter } from '@trellisorg/distributed-lock/redis-mutex';

@Module({
    imports: [
        DistributedLockModule.register([
            {
                config: {
                    lockPrefix: 'my-app',
                    client: {
                        host: 'localhost',
                        port: 6379,
                    },
                    retryOptions: {},
                    lockTimeout: 10_000,
                    fifo: false,
                },
                adapter: redisMutexLockAdapter,
                name: 'redis',
            },
        ]),
    ],
})
export class AppModule {}

Configuration Options

Option	Type	Default	Description
`client`	`RedisOptions`	-	The connection options for Redis. See the `ioredis` documentation for more information.
`lockPrefix`	`string`	`@trellisorg/distributed-lock`	A prefix for the lock keys. This helps to avoid collisions with other applications using Redis.
`lockTimeout`	`number`	`10_000`	The time it takes for a lock to expire after acquisition. This is in milliseconds.
`retryOptions`	`RetryOptions`	`{}`	Options for retrying lock acquisition. See the `promise-retry` documentation for more information.
`fifo`	`boolean`	`false`	Whether to use FIFO ordering for lock acquisition. If `true`, locks will be acquired and released in the order they were requested.

Usage

Standalone TypeScript

import { RedisMutex } from '@trellisorg/distributed-lock/redis-mutex';
import Redis from 'ioredis';

const redisClient = new Redis({
    host: 'localhost',
    port: 6379,
});

const redisMutex = new RedisMutex({
    client: redisClient,
    lockPrefix: 'my-app',
    lockTimeout: 10_000,
    fifo: false,
});

// Acquire a lock on the resource 'my-resource'
const lock = await redisMutex.lock('my-resource');

// Do some work that requires the lock
console.log('Working with the resource...');

// Release the lock
await lock.unlock();

NestJS

import { Injectable } from '@nestjs/common';
import { DistributedLock } from '@trellisorg/distributed-lock';
import { InjectLock } from '@trellisorg/distributed-lock/nest';

@Injectable()
export class MyService {
    constructor(@InjectLock('redis') private readonly redisLock: DistributedLock) {}

    async doSomething() {
        await this.redisLock.withLock('my-resource', async () => {
            // Do some work that requires the lock
            console.log('Working with the resource...');
        });
    }
}