@multisystemsuite/concurrency-lock

Optimistic and pessimistic row locking, versioning, conflict resolution, and distributed locks (in-memory or custom Redis store).

Version: 1.0.1 · License: MIT

npm readme: @multisystemsuite/concurrency-lock on npm

Installation

pnpm add @multisystemsuite/concurrency-lock

Quick start

import { ConcurrencyLock } from '@multisystemsuite/concurrency-lock';

const lock = new ConcurrencyLock();

// Optimistic — version column
const updated = lock.optimistic({ id: '1', version: 3 }, 3);

// Pessimistic — exclusive lock
const release = await lock.pessimistic('order:42', 30_000);
try {
  await processOrder();
} finally {
  await release();
}

API reference

Optimistic locking

lock.optimistic(entity, expectedVersion, resolution?);

| resolution | Behavior on conflict | |--------------|---------------------| | fail (default) | Throw error | | retry | Return entity unchanged | | overwrite | Increment version anyway |

VersionedEntity: { id: string; version: number }

Pessimistic locking

const release = await lock.pessimistic(key, ttlMs?);
// default ttl: 30_000 ms
await release();

Distributed lock

await lock.distributed('cron:sync', async () => {
  await runJob();
}, 10_000);

Redis / custom store

import { InMemoryLockStore, type LockStore } from '@multisystemsuite/concurrency-lock';

const store: LockStore = new InMemoryLockStore();
// Or implement LockStore for Redis:
// acquire(key, ttlMs) => boolean
// release(key) => void

lock.setRedisStore(store);

LockStore interface

interface LockStore {
  acquire(key: string, ttlMs: number): Promise<boolean>;
  release(key: string): Promise<void>;
}

When to use which mode

| Mode | Use case | |------|----------| | Optimistic | Low contention, version column in DB | | Pessimistic | Short critical sections in one process | | Distributed | Cron jobs, multi-instance workers |

Related packages

See the @multisystemsuite org on npm.

npm

• Package: @multisystemsuite/concurrency-lock
• Install: npm install @multisystemsuite/concurrency-lock