first commit

docs/persistence/database/migration/src/lock/distributed-lock/distributed-lock.md

@@ -0,0 +1,61 @@
+# distributed-lock
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Provides a `DistributedMigrationLock` that coordinates migration locking across multiple application instances using a pluggable `DistributedLockAdapter`. Also exports `InMemoryDistributedLockAdapter` for testing and single-node use. The distributed lock uses the same exponential back-off polling strategy as the memory lock, delegating actual lock storage to the adapter.
+
+## Features
+
+- `DistributedMigrationLock` — delegates to any `DistributedLockAdapter` with configurable `key` and `ttl`.
+- `InMemoryDistributedLockAdapter` — TTL-based in-memory adapter for testing without external infrastructure.
+- Exponential back-off polling from 50 ms up to 1 s ceiling.
+
+## Usage: Basic Example
+
+```ts
+import { DistributedMigrationLock, InMemoryDistributedLockAdapter } from "@suaveplan/migration";
+
+const lock = new DistributedMigrationLock({
+  adapter: new InMemoryDistributedLockAdapter(),
+  key: "app_migration_lock",
+  ttl: 60_000,
+});
+
+const acquired = await lock.acquire(30_000);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { DistributedMigrationLock } from "@suaveplan/migration";
+import type { DistributedLockAdapter } from "@suaveplan/migration";
+
+class PgAdvisoryLockAdapter implements DistributedLockAdapter {
+  async acquire(key: string, ttl: number) { /* pg_try_advisory_lock */ return true; }
+  async release(key: string) { /* pg_advisory_unlock */ }
+}
+
+const lock = new DistributedMigrationLock({ adapter: new PgAdvisoryLockAdapter() });
+```
+
+## API Reference
+
+### `class DistributedMigrationLock implements MigrationLockAdapter`
+
+**Constructor**: `(config: DistributedLockConfig)`
+
+- `config.adapter` — `DistributedLockAdapter` implementation.
+- `config.key?` — lock key (default `"migration_lock"`).
+- `config.ttl?` — lock TTL in ms (default `60_000`).
+
+### `class InMemoryDistributedLockAdapter implements DistributedLockAdapter`
+
+- `acquire(key, ttl): Promise<boolean>` — acquires if no unexpired entry for `key` exists.
+- `release(key): Promise<void>` — removes the entry.
+
+## Implementation Notes
+
+`isLocked` uses a probe key (`<key>__probe`) with zero TTL to test whether anything is competing for the lock — this avoids reading lock state directly, which the interface does not expose.