@multisystemsuite/deadlock-guard

Deadlock detection and retry with exponential backoff, lock-order analysis, metrics, and Prometheus export.

Version: 1.0.1 · License: MIT

npm readme: @multisystemsuite/deadlock-guard on npm

Installation

pnpm add @multisystemsuite/deadlock-guard

Quick start

import { DeadlockGuard } from '@multisystemsuite/deadlock-guard';

const deadlockGuard = new DeadlockGuard({
  maxRetries: 5,
  retryDelayMs: 50,
});

await deadlockGuard.execute(async () => {
  await inventory.update();
}, ['inventory', 'orders']);

Configuration

| Option | Default | Description | |--------|---------|-------------| | maxRetries | 5 | Max retry attempts after deadlock | | retryDelayMs | 50 | Base delay; doubles each attempt | | onDeadlock | — | (error, attempt) => void callback |

API reference

execute<T>(fn, resources?): Promise<T>

Runs fn with deadlock retry. Optional resources array enforces consistent lock order.

Throws if lock order violates prior acquisitions (prevents deadlock cycles).

analyzeLockOrder(resources)

const { valid, suggestion } = guard.analyzeLockOrder(['orders', 'inventory']);
// suggestion: "Acquire locks in order: inventory -> orders"

Metrics

| Method | Description | |--------|-------------| | getMetrics() | { attempts, deadlocks, successes, alerts } | | toPrometheusMetrics() | MetricPoint[] for exporters | | resetMetrics() | Clear counters |

Prometheus metric names:

• db_deadlock_attempts_total
• db_deadlock_total
• db_deadlock_success_total
• db_deadlock_alerts_total

Best practices

1. Always pass resources in alphabetical or schema-defined order.
2. Keep transactions short inside execute.
3. Log onDeadlock for alerting when retries are frequent.

Related packages

See the @multisystemsuite org on npm.

npm

• Package: @multisystemsuite/deadlock-guard
• Install: npm install @multisystemsuite/deadlock-guard