murlock

library5.1.0jsnpmunverified

A distributed locking solution for NestJS, providing a decorator for critical sections with Redis-based synchronization. Version 5.1.0 is current. It offers parameter-based locking, retry with exponential backoff, blocking mode, and fail-fast options. Compared to alternatives like nestjs-redis-lock, MurLock emphasizes NestJS decorator integration and configurability. Released as a peer-dependency package requiring @nestjs/common >=10.0.5.

database

npm install murlock

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MURLOCK

murlock

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

MurLockModule

✓ import { MurLockModule } from 'murlock'

✗ const MurLockModule = require('murlock').MurLockModule

ESM import; CommonJS require works but may cause issues with bundlers. TypeScript types included.

MurLock

✓ import { MurLock } from 'murlock'

✗ import MurLock from 'murlock'

Named export, not default. Always use braces.

MurLockException

✓ import { MurLockException } from 'murlock'

✗ import { MurLockException } from 'murlock/dist/...'

Use library root; avoid deep imports.

Shows module import with forRoot configuration and decorator usage on a service method.

import { Module } from '@nestjs/common'; import { MurLockModule } from 'murlock'; import { AppController } from './app.controller'; import { AppService } from './app.service'; @Module({ imports: [ MurLockModule.forRoot({ redisOptions: { url: process.env.REDIS_URL ?? 'redis://localhost:6379' }, wait: 1000, maxAttempts: 3, logLevel: 'log', blocking: false, }), ], controllers: [AppController], providers: [AppService], }) export class AppModule {} // Usage in service import { Injectable } from '@nestjs/common'; import { MurLock } from 'murlock'; @Injectable() export class AppService { @MurLock(5000, 'userId') async someFunction({ userId }: { userId: string }): Promise<void> { // Critical section locked by userId } }

Debug

Known issues

breakingIn version 3.x, the `@MurLock` decorator signature changed: the first argument is now release time (ms) instead of a key prefix.

fix

Update decorator calls: @MurLock(5000, 'key') instead of @MurLock('key', 5000).

affects: >=3.0.0 <5.0.0

deprecatedThe `forRootAsync` method is deprecated since v5.0.0; use `MurLockModule.forRoot` with static config or custom providers.

fix

Replace `MurLockModule.forRootAsync({ ... })` with `MurLockModule.forRoot({ ... })`.

affects: >=5.0.0

gotchaIf `failFastOnRedisError` is set to true (default false), your application will throw an error if Redis is unreachable, potentially breaking startup.

fix

Set `failFastOnRedisError: false` to gracefully handle Redis connection issues.

affects: >=1.0.0

gotchaDecorator key expressions like '0.userId' require the method parameter to be an object; they do not support primitive parameters directly.

fix

Wrap primitive parameters in an object before passing, or use a different key syntax.

affects: >=1.0.0

breakingSince v4.0.0, `redisOptions` no longer accepts a `client` instance; you must pass connection options directly.

fix

Remove custom Redis client; use `redisOptions: { url: '...' }` instead.

affects: >=4.0.0

Errors

Common errors & fixes

Error: Cannot find module 'murlock'

Missing murlock installation or incorrect import path.

fix

Run `npm install murlock redis reflect-metadata` and ensure import is from 'murlock'.

MurLockException: Lock timeout exceeded

The lock was not released within the specified `wait` time (default 1000ms) and `maxAttempts` reached.

fix

Increase `wait` and/or `maxAttempts` in MurLockModule config, or reduce lock hold time.

TypeError: Cannot read properties of undefined (reading 'userId')

Decorator key expression references a property that does not exist on the method's parameter.

fix

Ensure the parameter is an object with the specified property; check parameter index for multi-arg methods.

Error: Redis connection refused

Redis server is not running or URL is incorrect.

fix

Start Redis server or update `redisOptions.url` with correct connection string.

Upgrade

Version history

5.1.0latest on npm

Audit

Dependencies

@nestjs/commonrequiredPeer dependency for NestJS module integration

@nestjs/corerequiredPeer dependency for NestJS module integration

redisrequiredRedis client required for lock storage

reflect-metadatarequiredRequired for decorator metadata reflection

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/felanios/murlock ↗

packagemurlock ↗

homepagehttps://github.com/felanios/murlock#readme ↗