dflockd-client 1.0.0 → 1.1.0

package/README.md

@@ -10,10 +10,10 @@ npm install dflockd-client
 
 ## Usage
 
-Start the dflockd server first:
+Start the [dflockd](https://github.com/mtingers/dflockd) server:
 
 ```bash
-uv run dflockd
+dflockd
 ```
 
 ### `withLock` (recommended)
@@ -98,14 +98,58 @@ without blocking. If the lock is contended, `enqueue()` returns `"queued"` and
 
 ### Options
 
-| Option           | Type     | Default       | Description                                      |
-|------------------|----------|---------------|--------------------------------------------------|
-| `key`            | `string` | *(required)*  | Lock name                                        |
-| `acquireTimeoutS`| `number` | `10`          | Seconds to wait for the lock before giving up    |
-| `leaseTtlS`      | `number` | server default| Server-side lease duration in seconds             |
-| `host`           | `string` | `127.0.0.1`   | Server host                                      |
-| `port`           | `number` | `6388`        | Server port                                      |
-| `renewRatio`     | `number` | `0.5`         | Renew at `lease * ratio` seconds (e.g. 50% of TTL)|
+| Option             | Type                          | Default                  | Description                                      |
+|--------------------|-------------------------------|--------------------------|--------------------------------------------------|
+| `key`              | `string`                      | *(required)*             | Lock name                                        |
+| `acquireTimeoutS`  | `number`                      | `10`                     | Seconds to wait for the lock before giving up    |
+| `leaseTtlS`        | `number`                      | server default           | Server-side lease duration in seconds             |
+| `servers`          | `Array<[string, number]>`     | `[["127.0.0.1", 6388]]` | List of `[host, port]` pairs                     |
+| `shardingStrategy` | `ShardingStrategy`            | `stableHashShard`        | Function mapping `(key, numServers)` to a server index |
+| `host`             | `string`                      | `127.0.0.1`              | Server host *(deprecated — use `servers`)*       |
+| `port`             | `number`                      | `6388`                   | Server port *(deprecated — use `servers`)*       |
+| `renewRatio`       | `number`                      | `0.5`                    | Renew at `lease * ratio` seconds (e.g. 50% of TTL)|
+
+### Multi-server sharding
+
+Distribute locks across multiple dflockd instances. Each key is consistently
+routed to the same server using CRC32-based hashing (matching Python's
+`zlib.crc32`).
+
+```ts
+import { DistributedLock } from "dflockd-client";
+
+const lock = new DistributedLock({
+  key: "my-resource",
+  servers: [
+    ["10.0.0.1", 6388],
+    ["10.0.0.2", 6388],
+    ["10.0.0.3", 6388],
+  ],
+});
+
+await lock.withLock(async () => {
+  // critical section — routed to a consistent server based on key
+});
+```
+
+You can supply a custom sharding strategy:
+
+```ts
+import { DistributedLock, ShardingStrategy } from "dflockd-client";
+
+const roundRobin: ShardingStrategy = (_key, numServers) => {
+  return Math.floor(Math.random() * numServers);
+};
+
+const lock = new DistributedLock({
+  key: "my-resource",
+  servers: [
+    ["10.0.0.1", 6388],
+    ["10.0.0.2", 6388],
+  ],
+  shardingStrategy: roundRobin,
+});
+```
 
 ### Error handling
 

package/dist/client.cjs

@@ -37,6 +37,7 @@ __export(client_exports, {
   enqueue: () => enqueue,
   release: () => release,
   renew: () => renew,
+  stableHashShard: () => stableHashShard,
   waitForLock: () => waitForLock
 });
 module.exports = __toCommonJS(client_exports);
@@ -93,6 +94,24 @@ function connect(host, port) {
     sock.on("error", reject);
   });
 }
+var CRC32_TABLE = new Uint32Array(256);
+for (let i = 0; i < 256; i++) {
+  let c = i;
+  for (let j = 0; j < 8; j++) {
+    c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+  }
+  CRC32_TABLE[i] = c;
+}
+function crc32(buf) {
+  let crc = 4294967295;
+  for (let i = 0; i < buf.length; i++) {
+    crc = CRC32_TABLE[(crc ^ buf[i]) & 255] ^ crc >>> 8;
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+function stableHashShard(key, numServers) {
+  return (crc32(Buffer.from(key, "utf-8")) >>> 0) % numServers;
+}
 async function acquire(sock, key, acquireTimeoutS, leaseTtlS) {
   const arg = leaseTtlS == null ? String(acquireTimeoutS) : `${acquireTimeoutS} ${leaseTtlS}`;
   sock.write(encodeLines("l", key, arg));
@@ -164,8 +183,8 @@ var DistributedLock = class {
   key;
   acquireTimeoutS;
   leaseTtlS;
-  host;
-  port;
+  servers;
+  shardingStrategy;
   renewRatio;
   token = null;
   lease = 0;
@@ -176,14 +195,26 @@ var DistributedLock = class {
     this.key = opts.key;
     this.acquireTimeoutS = opts.acquireTimeoutS ?? 10;
     this.leaseTtlS = opts.leaseTtlS;
-    this.host = opts.host ?? DEFAULT_HOST;
-    this.port = opts.port ?? DEFAULT_PORT;
+    if (opts.servers) {
+      if (opts.servers.length === 0) {
+        throw new LockError("servers list must not be empty");
+      }
+      this.servers = opts.servers;
+    } else {
+      this.servers = [[opts.host ?? DEFAULT_HOST, opts.port ?? DEFAULT_PORT]];
+    }
+    this.shardingStrategy = opts.shardingStrategy ?? stableHashShard;
     this.renewRatio = opts.renewRatio ?? 0.5;
   }
+  pickServer() {
+    const idx = this.shardingStrategy(this.key, this.servers.length);
+    return this.servers[idx];
+  }
   /** Acquire the lock. Returns `true` on success, `false` on timeout. */
   async acquire() {
     this.closed = false;
-    this.sock = await connect(this.host, this.port);
+    const [host, port] = this.pickServer();
+    this.sock = await connect(host, port);
     try {
       const result = await acquire(
         this.sock,
@@ -219,7 +250,8 @@ var DistributedLock = class {
    */
   async enqueue() {
     this.closed = false;
-    this.sock = await connect(this.host, this.port);
+    const [host, port] = this.pickServer();
+    this.sock = await connect(host, port);
     try {
       const result = await enqueue(this.sock, this.key, this.leaseTtlS);
       if (result.status === "acquired") {
@@ -324,6 +356,7 @@ var DistributedLock = class {
   enqueue,
   release,
   renew,
+  stableHashShard,
   waitForLock
 });
 //# sourceMappingURL=client.cjs.map

package/dist/client.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import * as net from \"net\";\n\nconst DEFAULT_HOST = \"127.0.0.1\";\nconst DEFAULT_PORT = 6388;\n\n// ---------------------------------------------------------------------------\n// Errors\n// ---------------------------------------------------------------------------\n\nexport class AcquireTimeoutError extends Error {\n  constructor(key: string) {\n    super(`timeout acquiring '${key}'`);\n    this.name = \"AcquireTimeoutError\";\n  }\n}\n\nexport class LockError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"LockError\";\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Low-level helpers\n// ---------------------------------------------------------------------------\n\nfunction encodeLines(...lines: string[]): Buffer {\n  return Buffer.from(lines.map((l) => l + \"\\n\").join(\"\"), \"utf-8\");\n}\n\n/**\n * Read one newline-terminated line from the socket.\n * Resolves with the line (without trailing \\r\\n).\n * Rejects if the connection closes before a full line arrives.\n */\nfunction readline(sock: net.Socket): Promise<string> {\n  return new Promise((resolve, reject) => {\n    let buf = \"\";\n\n    const onData = (chunk: Buffer) => {\n      buf += chunk.toString(\"utf-8\");\n      const idx = buf.indexOf(\"\\n\");\n      if (idx !== -1) {\n        cleanup();\n        resolve(buf.slice(0, idx).replace(/\\r$/, \"\"));\n      }\n    };\n\n    const onError = (err: Error) => {\n      cleanup();\n      reject(err);\n    };\n\n    const onClose = () => {\n      cleanup();\n      reject(new LockError(\"server closed connection\"));\n    };\n\n    const cleanup = () => {\n      sock.removeListener(\"data\", onData);\n      sock.removeListener(\"error\", onError);\n      sock.removeListener(\"close\", onClose);\n    };\n\n    sock.on(\"data\", onData);\n    sock.on(\"error\", onError);\n    sock.on(\"close\", onClose);\n  });\n}\n\nfunction connect(host: string, port: number): Promise<net.Socket> {\n  return new Promise((resolve, reject) => {\n    const sock = net.createConnection({ host, port }, () => resolve(sock));\n    sock.on(\"error\", reject);\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Protocol functions\n// ---------------------------------------------------------------------------\n\nexport async function acquire(\n  sock: net.Socket,\n  key: string,\n  acquireTimeoutS: number,\n  leaseTtlS?: number,\n): Promise<{ token: string; lease: number }> {\n  const arg =\n    leaseTtlS == null\n      ? String(acquireTimeoutS)\n      : `${acquireTimeoutS} ${leaseTtlS}`;\n\n  sock.write(encodeLines(\"l\", key, arg));\n\n  const resp = await readline(sock);\n  if (resp === \"timeout\") {\n    throw new AcquireTimeoutError(key);\n  }\n  if (!resp.startsWith(\"ok \")) {\n    throw new LockError(`acquire failed: '${resp}'`);\n  }\n\n  const parts = resp.split(\" \");\n  if (parts.length < 2) {\n    throw new LockError(`bad ok response: '${resp}'`);\n  }\n  const token = parts[1];\n  const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 30;\n  return { token, lease };\n}\n\nexport async function renew(\n  sock: net.Socket,\n  key: string,\n  token: string,\n  leaseTtlS?: number,\n): Promise<number> {\n  const arg = leaseTtlS == null ? token : `${token} ${leaseTtlS}`;\n  sock.write(encodeLines(\"n\", key, arg));\n\n  const resp = await readline(sock);\n  if (!resp.startsWith(\"ok\")) {\n    throw new LockError(`renew failed: '${resp}'`);\n  }\n\n  const parts = resp.split(\" \");\n  if (parts.length >= 2 && /^\\d+$/.test(parts[1])) {\n    return parseInt(parts[1], 10);\n  }\n  return -1;\n}\n\nexport async function enqueue(\n  sock: net.Socket,\n  key: string,\n  leaseTtlS?: number,\n): Promise<{ status: \"acquired\" | \"queued\"; token: string | null; lease: number | null }> {\n  const arg = leaseTtlS == null ? \"\" : String(leaseTtlS);\n  sock.write(encodeLines(\"e\", key, arg));\n\n  const resp = await readline(sock);\n  if (resp.startsWith(\"acquired \")) {\n    const parts = resp.split(\" \");\n    const token = parts[1];\n    const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 33;\n    return { status: \"acquired\", token, lease };\n  }\n  if (resp === \"queued\") {\n    return { status: \"queued\", token: null, lease: null };\n  }\n  throw new LockError(`enqueue failed: '${resp}'`);\n}\n\nexport async function waitForLock(\n  sock: net.Socket,\n  key: string,\n  waitTimeoutS: number,\n): Promise<{ token: string; lease: number }> {\n  sock.write(encodeLines(\"w\", key, String(waitTimeoutS)));\n\n  const resp = await readline(sock);\n  if (resp === \"timeout\") {\n    throw new AcquireTimeoutError(key);\n  }\n  if (!resp.startsWith(\"ok \")) {\n    throw new LockError(`wait failed: '${resp}'`);\n  }\n\n  const parts = resp.split(\" \");\n  const token = parts[1];\n  const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 33;\n  return { token, lease };\n}\n\nexport async function release(\n  sock: net.Socket,\n  key: string,\n  token: string,\n): Promise<void> {\n  sock.write(encodeLines(\"r\", key, token));\n\n  const resp = await readline(sock);\n  if (resp !== \"ok\") {\n    throw new LockError(`release failed: '${resp}'`);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// DistributedLock\n// ---------------------------------------------------------------------------\n\nexport interface DistributedLockOptions {\n  key: string;\n  acquireTimeoutS?: number;\n  leaseTtlS?: number;\n  host?: string;\n  port?: number;\n  renewRatio?: number;\n}\n\nexport class DistributedLock {\n  readonly key: string;\n  readonly acquireTimeoutS: number;\n  readonly leaseTtlS: number | undefined;\n  readonly host: string;\n  readonly port: number;\n  readonly renewRatio: number;\n\n  token: string | null = null;\n  lease: number = 0;\n\n  private sock: net.Socket | null = null;\n  private renewTimer: ReturnType<typeof setTimeout> | null = null;\n  private closed = false;\n\n  constructor(opts: DistributedLockOptions) {\n    this.key = opts.key;\n    this.acquireTimeoutS = opts.acquireTimeoutS ?? 10;\n    this.leaseTtlS = opts.leaseTtlS;\n    this.host = opts.host ?? DEFAULT_HOST;\n    this.port = opts.port ?? DEFAULT_PORT;\n    this.renewRatio = opts.renewRatio ?? 0.5;\n  }\n\n  /** Acquire the lock. Returns `true` on success, `false` on timeout. */\n  async acquire(): Promise<boolean> {\n    this.closed = false;\n    this.sock = await connect(this.host, this.port);\n    try {\n      const result = await acquire(\n        this.sock,\n        this.key,\n        this.acquireTimeoutS,\n        this.leaseTtlS,\n      );\n      this.token = result.token;\n      this.lease = result.lease;\n    } catch (err) {\n      await this.close();\n      if (err instanceof AcquireTimeoutError) return false;\n      throw err;\n    }\n    this.startRenew();\n    return true;\n  }\n\n  /** Release the lock and close the connection. */\n  async release(): Promise<void> {\n    try {\n      this.stopRenew();\n      if (this.sock && this.token) {\n        await release(this.sock, this.key, this.token);\n      }\n    } finally {\n      await this.close();\n    }\n  }\n\n  /**\n   * Two-phase step 1: connect and join the FIFO queue.\n   * Returns `\"acquired\"` (fast-path, lock is already held) or `\"queued\"`.\n   * If acquired immediately, the renew loop starts automatically.\n   */\n  async enqueue(): Promise<\"acquired\" | \"queued\"> {\n    this.closed = false;\n    this.sock = await connect(this.host, this.port);\n    try {\n      const result = await enqueue(this.sock, this.key, this.leaseTtlS);\n      if (result.status === \"acquired\") {\n        this.token = result.token;\n        this.lease = result.lease ?? 0;\n        this.startRenew();\n      }\n      return result.status;\n    } catch (err) {\n      await this.close();\n      throw err;\n    }\n  }\n\n  /**\n   * Two-phase step 2: block until the lock is granted.\n   * Returns `true` if granted, `false` on timeout.\n   * If already acquired during `enqueue()`, returns `true` immediately.\n   */\n  async wait(timeoutS?: number): Promise<boolean> {\n    if (this.token !== null) {\n      // Already acquired during enqueue (fast path)\n      return true;\n    }\n    if (!this.sock) {\n      throw new LockError(\"not connected; call enqueue() first\");\n    }\n    const timeout = timeoutS ?? this.acquireTimeoutS;\n    try {\n      const result = await waitForLock(this.sock, this.key, timeout);\n      this.token = result.token;\n      this.lease = result.lease;\n    } catch (err) {\n      await this.close();\n      if (err instanceof AcquireTimeoutError) return false;\n      throw err;\n    }\n    this.startRenew();\n    return true;\n  }\n\n  /**\n   * Run `fn` while holding the lock, then release automatically.\n   *\n   * ```ts\n   * const lock = new DistributedLock({ key: \"my-resource\" });\n   * await lock.withLock(async () => {\n   *   // critical section\n   * });\n   * ```\n   */\n  async withLock<T>(fn: () => T | Promise<T>): Promise<T> {\n    const ok = await this.acquire();\n    if (!ok) {\n      throw new AcquireTimeoutError(this.key);\n    }\n    try {\n      return await fn();\n    } finally {\n      await this.release();\n    }\n  }\n\n  /** Close the underlying socket (idempotent). */\n  async close(): Promise<void> {\n    if (this.closed) return;\n    this.closed = true;\n    this.stopRenew();\n    if (this.sock) {\n      this.sock.destroy();\n      this.sock = null;\n    }\n    this.token = null;\n  }\n\n  // -- internals --\n\n  private startRenew(): void {\n    const interval = Math.max(1, this.lease * this.renewRatio) * 1000;\n    const loop = async () => {\n      if (!this.sock || !this.token) return;\n      try {\n        await renew(this.sock, this.key, this.token, this.leaseTtlS);\n      } catch {\n        console.error(\n          `lock lost (renew failed): key=${this.key} token=${this.token}`,\n        );\n        this.token = null;\n        return;\n      }\n      this.renewTimer = setTimeout(loop, interval);\n    };\n    this.renewTimer = setTimeout(loop, interval);\n  }\n\n  private stopRenew(): void {\n    if (this.renewTimer != null) {\n      clearTimeout(this.renewTimer);\n      this.renewTimer = null;\n    }\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import * as net from \"net\";\n\nconst DEFAULT_HOST = \"127.0.0.1\";\nconst DEFAULT_PORT = 6388;\n\n// ---------------------------------------------------------------------------\n// Errors\n// ---------------------------------------------------------------------------\n\nexport class AcquireTimeoutError extends Error {\n  constructor(key: string) {\n    super(`timeout acquiring '${key}'`);\n    this.name = \"AcquireTimeoutError\";\n  }\n}\n\nexport class LockError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"LockError\";\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Low-level helpers\n// ---------------------------------------------------------------------------\n\nfunction encodeLines(...lines: string[]): Buffer {\n  return Buffer.from(lines.map((l) => l + \"\\n\").join(\"\"), \"utf-8\");\n}\n\n/**\n * Read one newline-terminated line from the socket.\n * Resolves with the line (without trailing \\r\\n).\n * Rejects if the connection closes before a full line arrives.\n */\nfunction readline(sock: net.Socket): Promise<string> {\n  return new Promise((resolve, reject) => {\n    let buf = \"\";\n\n    const onData = (chunk: Buffer) => {\n      buf += chunk.toString(\"utf-8\");\n      const idx = buf.indexOf(\"\\n\");\n      if (idx !== -1) {\n        cleanup();\n        resolve(buf.slice(0, idx).replace(/\\r$/, \"\"));\n      }\n    };\n\n    const onError = (err: Error) => {\n      cleanup();\n      reject(err);\n    };\n\n    const onClose = () => {\n      cleanup();\n      reject(new LockError(\"server closed connection\"));\n    };\n\n    const cleanup = () => {\n      sock.removeListener(\"data\", onData);\n      sock.removeListener(\"error\", onError);\n      sock.removeListener(\"close\", onClose);\n    };\n\n    sock.on(\"data\", onData);\n    sock.on(\"error\", onError);\n    sock.on(\"close\", onClose);\n  });\n}\n\nfunction connect(host: string, port: number): Promise<net.Socket> {\n  return new Promise((resolve, reject) => {\n    const sock = net.createConnection({ host, port }, () => resolve(sock));\n    sock.on(\"error\", reject);\n  });\n}\n\n// ---------------------------------------------------------------------------\n// CRC32 (same algorithm as Python's zlib.crc32)\n// ---------------------------------------------------------------------------\n\nconst CRC32_TABLE = new Uint32Array(256);\nfor (let i = 0; i < 256; i++) {\n  let c = i;\n  for (let j = 0; j < 8; j++) {\n    c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;\n  }\n  CRC32_TABLE[i] = c;\n}\n\nfunction crc32(buf: Buffer): number {\n  let crc = 0xffffffff;\n  for (let i = 0; i < buf.length; i++) {\n    crc = CRC32_TABLE[(crc ^ buf[i]) & 0xff] ^ (crc >>> 8);\n  }\n  return (crc ^ 0xffffffff) >>> 0;\n}\n\n// ---------------------------------------------------------------------------\n// Sharding\n// ---------------------------------------------------------------------------\n\nexport type ShardingStrategy = (key: string, numServers: number) => number;\n\nexport function stableHashShard(key: string, numServers: number): number {\n  return (crc32(Buffer.from(key, \"utf-8\")) >>> 0) % numServers;\n}\n\n// ---------------------------------------------------------------------------\n// Protocol functions\n// ---------------------------------------------------------------------------\n\nexport async function acquire(\n  sock: net.Socket,\n  key: string,\n  acquireTimeoutS: number,\n  leaseTtlS?: number,\n): Promise<{ token: string; lease: number }> {\n  const arg =\n    leaseTtlS == null\n      ? String(acquireTimeoutS)\n      : `${acquireTimeoutS} ${leaseTtlS}`;\n\n  sock.write(encodeLines(\"l\", key, arg));\n\n  const resp = await readline(sock);\n  if (resp === \"timeout\") {\n    throw new AcquireTimeoutError(key);\n  }\n  if (!resp.startsWith(\"ok \")) {\n    throw new LockError(`acquire failed: '${resp}'`);\n  }\n\n  const parts = resp.split(\" \");\n  if (parts.length < 2) {\n    throw new LockError(`bad ok response: '${resp}'`);\n  }\n  const token = parts[1];\n  const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 30;\n  return { token, lease };\n}\n\nexport async function renew(\n  sock: net.Socket,\n  key: string,\n  token: string,\n  leaseTtlS?: number,\n): Promise<number> {\n  const arg = leaseTtlS == null ? token : `${token} ${leaseTtlS}`;\n  sock.write(encodeLines(\"n\", key, arg));\n\n  const resp = await readline(sock);\n  if (!resp.startsWith(\"ok\")) {\n    throw new LockError(`renew failed: '${resp}'`);\n  }\n\n  const parts = resp.split(\" \");\n  if (parts.length >= 2 && /^\\d+$/.test(parts[1])) {\n    return parseInt(parts[1], 10);\n  }\n  return -1;\n}\n\nexport async function enqueue(\n  sock: net.Socket,\n  key: string,\n  leaseTtlS?: number,\n): Promise<{ status: \"acquired\" | \"queued\"; token: string | null; lease: number | null }> {\n  const arg = leaseTtlS == null ? \"\" : String(leaseTtlS);\n  sock.write(encodeLines(\"e\", key, arg));\n\n  const resp = await readline(sock);\n  if (resp.startsWith(\"acquired \")) {\n    const parts = resp.split(\" \");\n    const token = parts[1];\n    const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 33;\n    return { status: \"acquired\", token, lease };\n  }\n  if (resp === \"queued\") {\n    return { status: \"queued\", token: null, lease: null };\n  }\n  throw new LockError(`enqueue failed: '${resp}'`);\n}\n\nexport async function waitForLock(\n  sock: net.Socket,\n  key: string,\n  waitTimeoutS: number,\n): Promise<{ token: string; lease: number }> {\n  sock.write(encodeLines(\"w\", key, String(waitTimeoutS)));\n\n  const resp = await readline(sock);\n  if (resp === \"timeout\") {\n    throw new AcquireTimeoutError(key);\n  }\n  if (!resp.startsWith(\"ok \")) {\n    throw new LockError(`wait failed: '${resp}'`);\n  }\n\n  const parts = resp.split(\" \");\n  const token = parts[1];\n  const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 33;\n  return { token, lease };\n}\n\nexport async function release(\n  sock: net.Socket,\n  key: string,\n  token: string,\n): Promise<void> {\n  sock.write(encodeLines(\"r\", key, token));\n\n  const resp = await readline(sock);\n  if (resp !== \"ok\") {\n    throw new LockError(`release failed: '${resp}'`);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// DistributedLock\n// ---------------------------------------------------------------------------\n\nexport interface DistributedLockOptions {\n  key: string;\n  acquireTimeoutS?: number;\n  leaseTtlS?: number;\n  /** @deprecated Use `servers` instead. */\n  host?: string;\n  /** @deprecated Use `servers` instead. */\n  port?: number;\n  servers?: Array<[host: string, port: number]>;\n  shardingStrategy?: ShardingStrategy;\n  renewRatio?: number;\n}\n\nexport class DistributedLock {\n  readonly key: string;\n  readonly acquireTimeoutS: number;\n  readonly leaseTtlS: number | undefined;\n  readonly servers: Array<[string, number]>;\n  readonly shardingStrategy: ShardingStrategy;\n  readonly renewRatio: number;\n\n  token: string | null = null;\n  lease: number = 0;\n\n  private sock: net.Socket | null = null;\n  private renewTimer: ReturnType<typeof setTimeout> | null = null;\n  private closed = false;\n\n  constructor(opts: DistributedLockOptions) {\n    this.key = opts.key;\n    this.acquireTimeoutS = opts.acquireTimeoutS ?? 10;\n    this.leaseTtlS = opts.leaseTtlS;\n\n    if (opts.servers) {\n      if (opts.servers.length === 0) {\n        throw new LockError(\"servers list must not be empty\");\n      }\n      this.servers = opts.servers;\n    } else {\n      this.servers = [[opts.host ?? DEFAULT_HOST, opts.port ?? DEFAULT_PORT]];\n    }\n\n    this.shardingStrategy = opts.shardingStrategy ?? stableHashShard;\n    this.renewRatio = opts.renewRatio ?? 0.5;\n  }\n\n  private pickServer(): [string, number] {\n    const idx = this.shardingStrategy(this.key, this.servers.length);\n    return this.servers[idx];\n  }\n\n  /** Acquire the lock. Returns `true` on success, `false` on timeout. */\n  async acquire(): Promise<boolean> {\n    this.closed = false;\n    const [host, port] = this.pickServer();\n    this.sock = await connect(host, port);\n    try {\n      const result = await acquire(\n        this.sock,\n        this.key,\n        this.acquireTimeoutS,\n        this.leaseTtlS,\n      );\n      this.token = result.token;\n      this.lease = result.lease;\n    } catch (err) {\n      await this.close();\n      if (err instanceof AcquireTimeoutError) return false;\n      throw err;\n    }\n    this.startRenew();\n    return true;\n  }\n\n  /** Release the lock and close the connection. */\n  async release(): Promise<void> {\n    try {\n      this.stopRenew();\n      if (this.sock && this.token) {\n        await release(this.sock, this.key, this.token);\n      }\n    } finally {\n      await this.close();\n    }\n  }\n\n  /**\n   * Two-phase step 1: connect and join the FIFO queue.\n   * Returns `\"acquired\"` (fast-path, lock is already held) or `\"queued\"`.\n   * If acquired immediately, the renew loop starts automatically.\n   */\n  async enqueue(): Promise<\"acquired\" | \"queued\"> {\n    this.closed = false;\n    const [host, port] = this.pickServer();\n    this.sock = await connect(host, port);\n    try {\n      const result = await enqueue(this.sock, this.key, this.leaseTtlS);\n      if (result.status === \"acquired\") {\n        this.token = result.token;\n        this.lease = result.lease ?? 0;\n        this.startRenew();\n      }\n      return result.status;\n    } catch (err) {\n      await this.close();\n      throw err;\n    }\n  }\n\n  /**\n   * Two-phase step 2: block until the lock is granted.\n   * Returns `true` if granted, `false` on timeout.\n   * If already acquired during `enqueue()`, returns `true` immediately.\n   */\n  async wait(timeoutS?: number): Promise<boolean> {\n    if (this.token !== null) {\n      // Already acquired during enqueue (fast path)\n      return true;\n    }\n    if (!this.sock) {\n      throw new LockError(\"not connected; call enqueue() first\");\n    }\n    const timeout = timeoutS ?? this.acquireTimeoutS;\n    try {\n      const result = await waitForLock(this.sock, this.key, timeout);\n      this.token = result.token;\n      this.lease = result.lease;\n    } catch (err) {\n      await this.close();\n      if (err instanceof AcquireTimeoutError) return false;\n      throw err;\n    }\n    this.startRenew();\n    return true;\n  }\n\n  /**\n   * Run `fn` while holding the lock, then release automatically.\n   *\n   * ```ts\n   * const lock = new DistributedLock({ key: \"my-resource\" });\n   * await lock.withLock(async () => {\n   *   // critical section\n   * });\n   * ```\n   */\n  async withLock<T>(fn: () => T | Promise<T>): Promise<T> {\n    const ok = await this.acquire();\n    if (!ok) {\n      throw new AcquireTimeoutError(this.key);\n    }\n    try {\n      return await fn();\n    } finally {\n      await this.release();\n    }\n  }\n\n  /** Close the underlying socket (idempotent). */\n  async close(): Promise<void> {\n    if (this.closed) return;\n    this.closed = true;\n    this.stopRenew();\n    if (this.sock) {\n      this.sock.destroy();\n      this.sock = null;\n    }\n    this.token = null;\n  }\n\n  // -- internals --\n\n  private startRenew(): void {\n    const interval = Math.max(1, this.lease * this.renewRatio) * 1000;\n    const loop = async () => {\n      if (!this.sock || !this.token) return;\n      try {\n        await renew(this.sock, this.key, this.token, this.leaseTtlS);\n      } catch {\n        console.error(\n          `lock lost (renew failed): key=${this.key} token=${this.token}`,\n        );\n        this.token = null;\n        return;\n      }\n      this.renewTimer = setTimeout(loop, interval);\n    };\n    this.renewTimer = setTimeout(loop, interval);\n  }\n\n  private stopRenew(): void {\n    if (this.renewTimer != null) {\n      clearTimeout(this.renewTimer);\n      this.renewTimer = null;\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,UAAqB;AAErB,IAAM,eAAe;AACrB,IAAM,eAAe;AAMd,IAAM,sBAAN,cAAkC,MAAM;AAAA,EAC7C,YAAY,KAAa;AACvB,UAAM,sBAAsB,GAAG,GAAG;AAClC,SAAK,OAAO;AAAA,EACd;AACF;AAEO,IAAM,YAAN,cAAwB,MAAM;AAAA,EACnC,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAMA,SAAS,eAAe,OAAyB;AAC/C,SAAO,OAAO,KAAK,MAAM,IAAI,CAAC,MAAM,IAAI,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO;AACjE;AAOA,SAAS,SAAS,MAAmC;AACnD,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,QAAI,MAAM;AAEV,UAAM,SAAS,CAAC,UAAkB;AAChC,aAAO,MAAM,SAAS,OAAO;AAC7B,YAAM,MAAM,IAAI,QAAQ,IAAI;AAC5B,UAAI,QAAQ,IAAI;AACd,gBAAQ;AACR,gBAAQ,IAAI,MAAM,GAAG,GAAG,EAAE,QAAQ,OAAO,EAAE,CAAC;AAAA,MAC9C;AAAA,IACF;AAEA,UAAM,UAAU,CAAC,QAAe;AAC9B,cAAQ;AACR,aAAO,GAAG;AAAA,IACZ;AAEA,UAAM,UAAU,MAAM;AACpB,cAAQ;AACR,aAAO,IAAI,UAAU,0BAA0B,CAAC;AAAA,IAClD;AAEA,UAAM,UAAU,MAAM;AACpB,WAAK,eAAe,QAAQ,MAAM;AAClC,WAAK,eAAe,SAAS,OAAO;AACpC,WAAK,eAAe,SAAS,OAAO;AAAA,IACtC;AAEA,SAAK,GAAG,QAAQ,MAAM;AACtB,SAAK,GAAG,SAAS,OAAO;AACxB,SAAK,GAAG,SAAS,OAAO;AAAA,EAC1B,CAAC;AACH;AAEA,SAAS,QAAQ,MAAc,MAAmC;AAChE,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,UAAM,OAAW,qBAAiB,EAAE,MAAM,KAAK,GAAG,MAAM,QAAQ,IAAI,CAAC;AACrE,SAAK,GAAG,SAAS,MAAM;AAAA,EACzB,CAAC;AACH;AAMA,IAAM,cAAc,IAAI,YAAY,GAAG;AACvC,SAAS,IAAI,GAAG,IAAI,KAAK,KAAK;AAC5B,MAAI,IAAI;AACR,WAAS,IAAI,GAAG,IAAI,GAAG,KAAK;AAC1B,QAAI,IAAI,IAAI,aAAc,MAAM,IAAK,MAAM;AAAA,EAC7C;AACA,cAAY,CAAC,IAAI;AACnB;AAEA,SAAS,MAAM,KAAqB;AAClC,MAAI,MAAM;AACV,WAAS,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK;AACnC,UAAM,aAAa,MAAM,IAAI,CAAC,KAAK,GAAI,IAAK,QAAQ;AAAA,EACtD;AACA,UAAQ,MAAM,gBAAgB;AAChC;AAQO,SAAS,gBAAgB,KAAa,YAA4B;AACvE,UAAQ,MAAM,OAAO,KAAK,KAAK,OAAO,CAAC,MAAM,KAAK;AACpD;AAMA,eAAsB,QACpB,MACA,KACA,iBACA,WAC2C;AAC3C,QAAM,MACJ,aAAa,OACT,OAAO,eAAe,IACtB,GAAG,eAAe,IAAI,SAAS;AAErC,OAAK,MAAM,YAAY,KAAK,KAAK,GAAG,CAAC;AAErC,QAAM,OAAO,MAAM,SAAS,IAAI;AAChC,MAAI,SAAS,WAAW;AACtB,UAAM,IAAI,oBAAoB,GAAG;AAAA,EACnC;AACA,MAAI,CAAC,KAAK,WAAW,KAAK,GAAG;AAC3B,UAAM,IAAI,UAAU,oBAAoB,IAAI,GAAG;AAAA,EACjD;AAEA,QAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,MAAI,MAAM,SAAS,GAAG;AACpB,UAAM,IAAI,UAAU,qBAAqB,IAAI,GAAG;AAAA,EAClD;AACA,QAAM,QAAQ,MAAM,CAAC;AACrB,QAAM,QAAQ,MAAM,UAAU,IAAI,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI;AAC3D,SAAO,EAAE,OAAO,MAAM;AACxB;AAEA,eAAsB,MACpB,MACA,KACA,OACA,WACiB;AACjB,QAAM,MAAM,aAAa,OAAO,QAAQ,GAAG,KAAK,IAAI,SAAS;AAC7D,OAAK,MAAM,YAAY,KAAK,KAAK,GAAG,CAAC;AAErC,QAAM,OAAO,MAAM,SAAS,IAAI;AAChC,MAAI,CAAC,KAAK,WAAW,IAAI,GAAG;AAC1B,UAAM,IAAI,UAAU,kBAAkB,IAAI,GAAG;AAAA,EAC/C;AAEA,QAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,MAAI,MAAM,UAAU,KAAK,QAAQ,KAAK,MAAM,CAAC,CAAC,GAAG;AAC/C,WAAO,SAAS,MAAM,CAAC,GAAG,EAAE;AAAA,EAC9B;AACA,SAAO;AACT;AAEA,eAAsB,QACpB,MACA,KACA,WACwF;AACxF,QAAM,MAAM,aAAa,OAAO,KAAK,OAAO,SAAS;AACrD,OAAK,MAAM,YAAY,KAAK,KAAK,GAAG,CAAC;AAErC,QAAM,OAAO,MAAM,SAAS,IAAI;AAChC,MAAI,KAAK,WAAW,WAAW,GAAG;AAChC,UAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,UAAM,QAAQ,MAAM,CAAC;AACrB,UAAM,QAAQ,MAAM,UAAU,IAAI,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI;AAC3D,WAAO,EAAE,QAAQ,YAAY,OAAO,MAAM;AAAA,EAC5C;AACA,MAAI,SAAS,UAAU;AACrB,WAAO,EAAE,QAAQ,UAAU,OAAO,MAAM,OAAO,KAAK;AAAA,EACtD;AACA,QAAM,IAAI,UAAU,oBAAoB,IAAI,GAAG;AACjD;AAEA,eAAsB,YACpB,MACA,KACA,cAC2C;AAC3C,OAAK,MAAM,YAAY,KAAK,KAAK,OAAO,YAAY,CAAC,CAAC;AAEtD,QAAM,OAAO,MAAM,SAAS,IAAI;AAChC,MAAI,SAAS,WAAW;AACtB,UAAM,IAAI,oBAAoB,GAAG;AAAA,EACnC;AACA,MAAI,CAAC,KAAK,WAAW,KAAK,GAAG;AAC3B,UAAM,IAAI,UAAU,iBAAiB,IAAI,GAAG;AAAA,EAC9C;AAEA,QAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,QAAM,QAAQ,MAAM,CAAC;AACrB,QAAM,QAAQ,MAAM,UAAU,IAAI,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI;AAC3D,SAAO,EAAE,OAAO,MAAM;AACxB;AAEA,eAAsB,QACpB,MACA,KACA,OACe;AACf,OAAK,MAAM,YAAY,KAAK,KAAK,KAAK,CAAC;AAEvC,QAAM,OAAO,MAAM,SAAS,IAAI;AAChC,MAAI,SAAS,MAAM;AACjB,UAAM,IAAI,UAAU,oBAAoB,IAAI,GAAG;AAAA,EACjD;AACF;AAmBO,IAAM,kBAAN,MAAsB;AAAA,EAClB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,QAAuB;AAAA,EACvB,QAAgB;AAAA,EAER,OAA0B;AAAA,EAC1B,aAAmD;AAAA,EACnD,SAAS;AAAA,EAEjB,YAAY,MAA8B;AACxC,SAAK,MAAM,KAAK;AAChB,SAAK,kBAAkB,KAAK,mBAAmB;AAC/C,SAAK,YAAY,KAAK;AAEtB,QAAI,KAAK,SAAS;AAChB,UAAI,KAAK,QAAQ,WAAW,GAAG;AAC7B,cAAM,IAAI,UAAU,gCAAgC;AAAA,MACtD;AACA,WAAK,UAAU,KAAK;AAAA,IACtB,OAAO;AACL,WAAK,UAAU,CAAC,CAAC,KAAK,QAAQ,cAAc,KAAK,QAAQ,YAAY,CAAC;AAAA,IACxE;AAEA,SAAK,mBAAmB,KAAK,oBAAoB;AACjD,SAAK,aAAa,KAAK,cAAc;AAAA,EACvC;AAAA,EAEQ,aAA+B;AACrC,UAAM,MAAM,KAAK,iBAAiB,KAAK,KAAK,KAAK,QAAQ,MAAM;AAC/D,WAAO,KAAK,QAAQ,GAAG;AAAA,EACzB;AAAA;AAAA,EAGA,MAAM,UAA4B;AAChC,SAAK,SAAS;AACd,UAAM,CAAC,MAAM,IAAI,IAAI,KAAK,WAAW;AACrC,SAAK,OAAO,MAAM,QAAQ,MAAM,IAAI;AACpC,QAAI;AACF,YAAM,SAAS,MAAM;AAAA,QACnB,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,MACP;AACA,WAAK,QAAQ,OAAO;AACpB,WAAK,QAAQ,OAAO;AAAA,IACtB,SAAS,KAAK;AACZ,YAAM,KAAK,MAAM;AACjB,UAAI,eAAe,oBAAqB,QAAO;AAC/C,YAAM;AAAA,IACR;AACA,SAAK,WAAW;AAChB,WAAO;AAAA,EACT;AAAA;AAAA,EAGA,MAAM,UAAyB;AAC7B,QAAI;AACF,WAAK,UAAU;AACf,UAAI,KAAK,QAAQ,KAAK,OAAO;AAC3B,cAAM,QAAQ,KAAK,MAAM,KAAK,KAAK,KAAK,KAAK;AAAA,MAC/C;AAAA,IACF,UAAE;AACA,YAAM,KAAK,MAAM;AAAA,IACnB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,UAA0C;AAC9C,SAAK,SAAS;AACd,UAAM,CAAC,MAAM,IAAI,IAAI,KAAK,WAAW;AACrC,SAAK,OAAO,MAAM,QAAQ,MAAM,IAAI;AACpC,QAAI;AACF,YAAM,SAAS,MAAM,QAAQ,KAAK,MAAM,KAAK,KAAK,KAAK,SAAS;AAChE,UAAI,OAAO,WAAW,YAAY;AAChC,aAAK,QAAQ,OAAO;AACpB,aAAK,QAAQ,OAAO,SAAS;AAC7B,aAAK,WAAW;AAAA,MAClB;AACA,aAAO,OAAO;AAAA,IAChB,SAAS,KAAK;AACZ,YAAM,KAAK,MAAM;AACjB,YAAM;AAAA,IACR;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,KAAK,UAAqC;AAC9C,QAAI,KAAK,UAAU,MAAM;AAEvB,aAAO;AAAA,IACT;AACA,QAAI,CAAC,KAAK,MAAM;AACd,YAAM,IAAI,UAAU,qCAAqC;AAAA,IAC3D;AACA,UAAM,UAAU,YAAY,KAAK;AACjC,QAAI;AACF,YAAM,SAAS,MAAM,YAAY,KAAK,MAAM,KAAK,KAAK,OAAO;AAC7D,WAAK,QAAQ,OAAO;AACpB,WAAK,QAAQ,OAAO;AAAA,IACtB,SAAS,KAAK;AACZ,YAAM,KAAK,MAAM;AACjB,UAAI,eAAe,oBAAqB,QAAO;AAC/C,YAAM;AAAA,IACR;AACA,SAAK,WAAW;AAChB,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAM,SAAY,IAAsC;AACtD,UAAM,KAAK,MAAM,KAAK,QAAQ;AAC9B,QAAI,CAAC,IAAI;AACP,YAAM,IAAI,oBAAoB,KAAK,GAAG;AAAA,IACxC;AACA,QAAI;AACF,aAAO,MAAM,GAAG;AAAA,IAClB,UAAE;AACA,YAAM,KAAK,QAAQ;AAAA,IACrB;AAAA,EACF;AAAA;AAAA,EAGA,MAAM,QAAuB;AAC3B,QAAI,KAAK,OAAQ;AACjB,SAAK,SAAS;AACd,SAAK,UAAU;AACf,QAAI,KAAK,MAAM;AACb,WAAK,KAAK,QAAQ;AAClB,WAAK,OAAO;AAAA,IACd;AACA,SAAK,QAAQ;AAAA,EACf;AAAA;AAAA,EAIQ,aAAmB;AACzB,UAAM,WAAW,KAAK,IAAI,GAAG,KAAK,QAAQ,KAAK,UAAU,IAAI;AAC7D,UAAM,OAAO,YAAY;AACvB,UAAI,CAAC,KAAK,QAAQ,CAAC,KAAK,MAAO;AAC/B,UAAI;AACF,cAAM,MAAM,KAAK,MAAM,KAAK,KAAK,KAAK,OAAO,KAAK,SAAS;AAAA,MAC7D,QAAQ;AACN,gBAAQ;AAAA,UACN,iCAAiC,KAAK,GAAG,UAAU,KAAK,KAAK;AAAA,QAC/D;AACA,aAAK,QAAQ;AACb;AAAA,MACF;AACA,WAAK,aAAa,WAAW,MAAM,QAAQ;AAAA,IAC7C;AACA,SAAK,aAAa,WAAW,MAAM,QAAQ;AAAA,EAC7C;AAAA,EAEQ,YAAkB;AACxB,QAAI,KAAK,cAAc,MAAM;AAC3B,mBAAa,KAAK,UAAU;AAC5B,WAAK,aAAa;AAAA,IACpB;AAAA,EACF;AACF;","names":[]}

package/dist/client.d.cts

@@ -6,6 +6,8 @@ declare class AcquireTimeoutError extends Error {
 declare class LockError extends Error {
     constructor(message: string);
 }
+type ShardingStrategy = (key: string, numServers: number) => number;
+declare function stableHashShard(key: string, numServers: number): number;
 declare function acquire(sock: net.Socket, key: string, acquireTimeoutS: number, leaseTtlS?: number): Promise<{
     token: string;
     lease: number;
@@ -25,16 +27,20 @@ interface DistributedLockOptions {
     key: string;
     acquireTimeoutS?: number;
     leaseTtlS?: number;
+    /** @deprecated Use `servers` instead. */
     host?: string;
+    /** @deprecated Use `servers` instead. */
     port?: number;
+    servers?: Array<[host: string, port: number]>;
+    shardingStrategy?: ShardingStrategy;
     renewRatio?: number;
 }
 declare class DistributedLock {
     readonly key: string;
     readonly acquireTimeoutS: number;
     readonly leaseTtlS: number | undefined;
-    readonly host: string;
-    readonly port: number;
+    readonly servers: Array<[string, number]>;
+    readonly shardingStrategy: ShardingStrategy;
     readonly renewRatio: number;
     token: string | null;
     lease: number;
@@ -42,6 +48,7 @@ declare class DistributedLock {
     private renewTimer;
     private closed;
     constructor(opts: DistributedLockOptions);
+    private pickServer;
     /** Acquire the lock. Returns `true` on success, `false` on timeout. */
     acquire(): Promise<boolean>;
     /** Release the lock and close the connection. */
@@ -75,4 +82,4 @@ declare class DistributedLock {
     private stopRenew;
 }
 
-export { AcquireTimeoutError, DistributedLock, type DistributedLockOptions, LockError, acquire, enqueue, release, renew, waitForLock };
+export { AcquireTimeoutError, DistributedLock, type DistributedLockOptions, LockError, type ShardingStrategy, acquire, enqueue, release, renew, stableHashShard, waitForLock };

package/dist/client.d.ts

@@ -6,6 +6,8 @@ declare class AcquireTimeoutError extends Error {
 declare class LockError extends Error {
     constructor(message: string);
 }
+type ShardingStrategy = (key: string, numServers: number) => number;
+declare function stableHashShard(key: string, numServers: number): number;
 declare function acquire(sock: net.Socket, key: string, acquireTimeoutS: number, leaseTtlS?: number): Promise<{
     token: string;
     lease: number;
@@ -25,16 +27,20 @@ interface DistributedLockOptions {
     key: string;
     acquireTimeoutS?: number;
     leaseTtlS?: number;
+    /** @deprecated Use `servers` instead. */
     host?: string;
+    /** @deprecated Use `servers` instead. */
     port?: number;
+    servers?: Array<[host: string, port: number]>;
+    shardingStrategy?: ShardingStrategy;
     renewRatio?: number;
 }
 declare class DistributedLock {
     readonly key: string;
     readonly acquireTimeoutS: number;
     readonly leaseTtlS: number | undefined;
-    readonly host: string;
-    readonly port: number;
+    readonly servers: Array<[string, number]>;
+    readonly shardingStrategy: ShardingStrategy;
     readonly renewRatio: number;
     token: string | null;
     lease: number;
@@ -42,6 +48,7 @@ declare class DistributedLock {
     private renewTimer;
     private closed;
     constructor(opts: DistributedLockOptions);
+    private pickServer;
     /** Acquire the lock. Returns `true` on success, `false` on timeout. */
     acquire(): Promise<boolean>;
     /** Release the lock and close the connection. */
@@ -75,4 +82,4 @@ declare class DistributedLock {
     private stopRenew;
 }
 
-export { AcquireTimeoutError, DistributedLock, type DistributedLockOptions, LockError, acquire, enqueue, release, renew, waitForLock };
+export { AcquireTimeoutError, DistributedLock, type DistributedLockOptions, LockError, type ShardingStrategy, acquire, enqueue, release, renew, stableHashShard, waitForLock };

package/dist/client.js

@@ -52,6 +52,24 @@ function connect(host, port) {
     sock.on("error", reject);
   });
 }
+var CRC32_TABLE = new Uint32Array(256);
+for (let i = 0; i < 256; i++) {
+  let c = i;
+  for (let j = 0; j < 8; j++) {
+    c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+  }
+  CRC32_TABLE[i] = c;
+}
+function crc32(buf) {
+  let crc = 4294967295;
+  for (let i = 0; i < buf.length; i++) {
+    crc = CRC32_TABLE[(crc ^ buf[i]) & 255] ^ crc >>> 8;
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+function stableHashShard(key, numServers) {
+  return (crc32(Buffer.from(key, "utf-8")) >>> 0) % numServers;
+}
 async function acquire(sock, key, acquireTimeoutS, leaseTtlS) {
   const arg = leaseTtlS == null ? String(acquireTimeoutS) : `${acquireTimeoutS} ${leaseTtlS}`;
   sock.write(encodeLines("l", key, arg));
@@ -123,8 +141,8 @@ var DistributedLock = class {
   key;
   acquireTimeoutS;
   leaseTtlS;
-  host;
-  port;
+  servers;
+  shardingStrategy;
   renewRatio;
   token = null;
   lease = 0;
@@ -135,14 +153,26 @@ var DistributedLock = class {
     this.key = opts.key;
     this.acquireTimeoutS = opts.acquireTimeoutS ?? 10;
     this.leaseTtlS = opts.leaseTtlS;
-    this.host = opts.host ?? DEFAULT_HOST;
-    this.port = opts.port ?? DEFAULT_PORT;
+    if (opts.servers) {
+      if (opts.servers.length === 0) {
+        throw new LockError("servers list must not be empty");
+      }
+      this.servers = opts.servers;
+    } else {
+      this.servers = [[opts.host ?? DEFAULT_HOST, opts.port ?? DEFAULT_PORT]];
+    }
+    this.shardingStrategy = opts.shardingStrategy ?? stableHashShard;
     this.renewRatio = opts.renewRatio ?? 0.5;
   }
+  pickServer() {
+    const idx = this.shardingStrategy(this.key, this.servers.length);
+    return this.servers[idx];
+  }
   /** Acquire the lock. Returns `true` on success, `false` on timeout. */
   async acquire() {
     this.closed = false;
-    this.sock = await connect(this.host, this.port);
+    const [host, port] = this.pickServer();
+    this.sock = await connect(host, port);
     try {
       const result = await acquire(
         this.sock,
@@ -178,7 +208,8 @@ var DistributedLock = class {
    */
   async enqueue() {
     this.closed = false;
-    this.sock = await connect(this.host, this.port);
+    const [host, port] = this.pickServer();
+    this.sock = await connect(host, port);
     try {
       const result = await enqueue(this.sock, this.key, this.leaseTtlS);
       if (result.status === "acquired") {
@@ -282,6 +313,7 @@ export {
   enqueue,
   release,
   renew,
+  stableHashShard,
   waitForLock
 };
 //# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import * as net from \"net\";\n\nconst DEFAULT_HOST = \"127.0.0.1\";\nconst DEFAULT_PORT = 6388;\n\n// ---------------------------------------------------------------------------\n// Errors\n// ---------------------------------------------------------------------------\n\nexport class AcquireTimeoutError extends Error {\n  constructor(key: string) {\n    super(`timeout acquiring '${key}'`);\n    this.name = \"AcquireTimeoutError\";\n  }\n}\n\nexport class LockError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"LockError\";\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Low-level helpers\n// ---------------------------------------------------------------------------\n\nfunction encodeLines(...lines: string[]): Buffer {\n  return Buffer.from(lines.map((l) => l + \"\\n\").join(\"\"), \"utf-8\");\n}\n\n/**\n * Read one newline-terminated line from the socket.\n * Resolves with the line (without trailing \\r\\n).\n * Rejects if the connection closes before a full line arrives.\n */\nfunction readline(sock: net.Socket): Promise<string> {\n  return new Promise((resolve, reject) => {\n    let buf = \"\";\n\n    const onData = (chunk: Buffer) => {\n      buf += chunk.toString(\"utf-8\");\n      const idx = buf.indexOf(\"\\n\");\n      if (idx !== -1) {\n        cleanup();\n        resolve(buf.slice(0, idx).replace(/\\r$/, \"\"));\n      }\n    };\n\n    const onError = (err: Error) => {\n      cleanup();\n      reject(err);\n    };\n\n    const onClose = () => {\n      cleanup();\n      reject(new LockError(\"server closed connection\"));\n    };\n\n    const cleanup = () => {\n      sock.removeListener(\"data\", onData);\n      sock.removeListener(\"error\", onError);\n      sock.removeListener(\"close\", onClose);\n    };\n\n    sock.on(\"data\", onData);\n    sock.on(\"error\", onError);\n    sock.on(\"close\", onClose);\n  });\n}\n\nfunction connect(host: string, port: number): Promise<net.Socket> {\n  return new Promise((resolve, reject) => {\n    const sock = net.createConnection({ host, port }, () => resolve(sock));\n    sock.on(\"error\", reject);\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Protocol functions\n// ---------------------------------------------------------------------------\n\nexport async function acquire(\n  sock: net.Socket,\n  key: string,\n  acquireTimeoutS: number,\n  leaseTtlS?: number,\n): Promise<{ token: string; lease: number }> {\n  const arg =\n    leaseTtlS == null\n      ? String(acquireTimeoutS)\n      : `${acquireTimeoutS} ${leaseTtlS}`;\n\n  sock.write(encodeLines(\"l\", key, arg));\n\n  const resp = await readline(sock);\n  if (resp === \"timeout\") {\n    throw new AcquireTimeoutError(key);\n  }\n  if (!resp.startsWith(\"ok \")) {\n    throw new LockError(`acquire failed: '${resp}'`);\n  }\n\n  const parts = resp.split(\" \");\n  if (parts.length < 2) {\n    throw new LockError(`bad ok response: '${resp}'`);\n  }\n  const token = parts[1];\n  const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 30;\n  return { token, lease };\n}\n\nexport async function renew(\n  sock: net.Socket,\n  key: string,\n  token: string,\n  leaseTtlS?: number,\n): Promise<number> {\n  const arg = leaseTtlS == null ? token : `${token} ${leaseTtlS}`;\n  sock.write(encodeLines(\"n\", key, arg));\n\n  const resp = await readline(sock);\n  if (!resp.startsWith(\"ok\")) {\n    throw new LockError(`renew failed: '${resp}'`);\n  }\n\n  const parts = resp.split(\" \");\n  if (parts.length >= 2 && /^\\d+$/.test(parts[1])) {\n    return parseInt(parts[1], 10);\n  }\n  return -1;\n}\n\nexport async function enqueue(\n  sock: net.Socket,\n  key: string,\n  leaseTtlS?: number,\n): Promise<{ status: \"acquired\" | \"queued\"; token: string | null; lease: number | null }> {\n  const arg = leaseTtlS == null ? \"\" : String(leaseTtlS);\n  sock.write(encodeLines(\"e\", key, arg));\n\n  const resp = await readline(sock);\n  if (resp.startsWith(\"acquired \")) {\n    const parts = resp.split(\" \");\n    const token = parts[1];\n    const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 33;\n    return { status: \"acquired\", token, lease };\n  }\n  if (resp === \"queued\") {\n    return { status: \"queued\", token: null, lease: null };\n  }\n  throw new LockError(`enqueue failed: '${resp}'`);\n}\n\nexport async function waitForLock(\n  sock: net.Socket,\n  key: string,\n  waitTimeoutS: number,\n): Promise<{ token: string; lease: number }> {\n  sock.write(encodeLines(\"w\", key, String(waitTimeoutS)));\n\n  const resp = await readline(sock);\n  if (resp === \"timeout\") {\n    throw new AcquireTimeoutError(key);\n  }\n  if (!resp.startsWith(\"ok \")) {\n    throw new LockError(`wait failed: '${resp}'`);\n  }\n\n  const parts = resp.split(\" \");\n  const token = parts[1];\n  const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 33;\n  return { token, lease };\n}\n\nexport async function release(\n  sock: net.Socket,\n  key: string,\n  token: string,\n): Promise<void> {\n  sock.write(encodeLines(\"r\", key, token));\n\n  const resp = await readline(sock);\n  if (resp !== \"ok\") {\n    throw new LockError(`release failed: '${resp}'`);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// DistributedLock\n// ---------------------------------------------------------------------------\n\nexport interface DistributedLockOptions {\n  key: string;\n  acquireTimeoutS?: number;\n  leaseTtlS?: number;\n  host?: string;\n  port?: number;\n  renewRatio?: number;\n}\n\nexport class DistributedLock {\n  readonly key: string;\n  readonly acquireTimeoutS: number;\n  readonly leaseTtlS: number | undefined;\n  readonly host: string;\n  readonly port: number;\n  readonly renewRatio: number;\n\n  token: string | null = null;\n  lease: number = 0;\n\n  private sock: net.Socket | null = null;\n  private renewTimer: ReturnType<typeof setTimeout> | null = null;\n  private closed = false;\n\n  constructor(opts: DistributedLockOptions) {\n    this.key = opts.key;\n    this.acquireTimeoutS = opts.acquireTimeoutS ?? 10;\n    this.leaseTtlS = opts.leaseTtlS;\n    this.host = opts.host ?? DEFAULT_HOST;\n    this.port = opts.port ?? DEFAULT_PORT;\n    this.renewRatio = opts.renewRatio ?? 0.5;\n  }\n\n  /** Acquire the lock. Returns `true` on success, `false` on timeout. */\n  async acquire(): Promise<boolean> {\n    this.closed = false;\n    this.sock = await connect(this.host, this.port);\n    try {\n      const result = await acquire(\n        this.sock,\n        this.key,\n        this.acquireTimeoutS,\n        this.leaseTtlS,\n      );\n      this.token = result.token;\n      this.lease = result.lease;\n    } catch (err) {\n      await this.close();\n      if (err instanceof AcquireTimeoutError) return false;\n      throw err;\n    }\n    this.startRenew();\n    return true;\n  }\n\n  /** Release the lock and close the connection. */\n  async release(): Promise<void> {\n    try {\n      this.stopRenew();\n      if (this.sock && this.token) {\n        await release(this.sock, this.key, this.token);\n      }\n    } finally {\n      await this.close();\n    }\n  }\n\n  /**\n   * Two-phase step 1: connect and join the FIFO queue.\n   * Returns `\"acquired\"` (fast-path, lock is already held) or `\"queued\"`.\n   * If acquired immediately, the renew loop starts automatically.\n   */\n  async enqueue(): Promise<\"acquired\" | \"queued\"> {\n    this.closed = false;\n    this.sock = await connect(this.host, this.port);\n    try {\n      const result = await enqueue(this.sock, this.key, this.leaseTtlS);\n      if (result.status === \"acquired\") {\n        this.token = result.token;\n        this.lease = result.lease ?? 0;\n        this.startRenew();\n      }\n      return result.status;\n    } catch (err) {\n      await this.close();\n      throw err;\n    }\n  }\n\n  /**\n   * Two-phase step 2: block until the lock is granted.\n   * Returns `true` if granted, `false` on timeout.\n   * If already acquired during `enqueue()`, returns `true` immediately.\n   */\n  async wait(timeoutS?: number): Promise<boolean> {\n    if (this.token !== null) {\n      // Already acquired during enqueue (fast path)\n      return true;\n    }\n    if (!this.sock) {\n      throw new LockError(\"not connected; call enqueue() first\");\n    }\n    const timeout = timeoutS ?? this.acquireTimeoutS;\n    try {\n      const result = await waitForLock(this.sock, this.key, timeout);\n      this.token = result.token;\n      this.lease = result.lease;\n    } catch (err) {\n      await this.close();\n      if (err instanceof AcquireTimeoutError) return false;\n      throw err;\n    }\n    this.startRenew();\n    return true;\n  }\n\n  /**\n   * Run `fn` while holding the lock, then release automatically.\n   *\n   * ```ts\n   * const lock = new DistributedLock({ key: \"my-resource\" });\n   * await lock.withLock(async () => {\n   *   // critical section\n   * });\n   * ```\n   */\n  async withLock<T>(fn: () => T | Promise<T>): Promise<T> {\n    const ok = await this.acquire();\n    if (!ok) {\n      throw new AcquireTimeoutError(this.key);\n    }\n    try {\n      return await fn();\n    } finally {\n      await this.release();\n    }\n  }\n\n  /** Close the underlying socket (idempotent). */\n  async close(): Promise<void> {\n    if (this.closed) return;\n    this.closed = true;\n    this.stopRenew();\n    if (this.sock) {\n      this.sock.destroy();\n      this.sock = null;\n    }\n    this.token = null;\n  }\n\n  // -- internals --\n\n  private startRenew(): void {\n    const interval = Math.max(1, this.lease * this.renewRatio) * 1000;\n    const loop = async () => {\n      if (!this.sock || !this.token) return;\n      try {\n        await renew(this.sock, this.key, this.token, this.leaseTtlS);\n      } catch {\n        console.error(\n          `lock lost (renew failed): key=${this.key} token=${this.token}`,\n        );\n        this.token = null;\n        return;\n      }\n      this.renewTimer = setTimeout(loop, interval);\n    };\n    this.renewTimer = setTimeout(loop, interval);\n  }\n\n  private stopRenew(): void {\n    if (this.renewTimer != null) {\n      clearTimeout(this.renewTimer);\n      this.renewTimer = null;\n    }\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import * as net from \"net\";\n\nconst DEFAULT_HOST = \"127.0.0.1\";\nconst DEFAULT_PORT = 6388;\n\n// ---------------------------------------------------------------------------\n// Errors\n// ---------------------------------------------------------------------------\n\nexport class AcquireTimeoutError extends Error {\n  constructor(key: string) {\n    super(`timeout acquiring '${key}'`);\n    this.name = \"AcquireTimeoutError\";\n  }\n}\n\nexport class LockError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"LockError\";\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Low-level helpers\n// ---------------------------------------------------------------------------\n\nfunction encodeLines(...lines: string[]): Buffer {\n  return Buffer.from(lines.map((l) => l + \"\\n\").join(\"\"), \"utf-8\");\n}\n\n/**\n * Read one newline-terminated line from the socket.\n * Resolves with the line (without trailing \\r\\n).\n * Rejects if the connection closes before a full line arrives.\n */\nfunction readline(sock: net.Socket): Promise<string> {\n  return new Promise((resolve, reject) => {\n    let buf = \"\";\n\n    const onData = (chunk: Buffer) => {\n      buf += chunk.toString(\"utf-8\");\n      const idx = buf.indexOf(\"\\n\");\n      if (idx !== -1) {\n        cleanup();\n        resolve(buf.slice(0, idx).replace(/\\r$/, \"\"));\n      }\n    };\n\n    const onError = (err: Error) => {\n      cleanup();\n      reject(err);\n    };\n\n    const onClose = () => {\n      cleanup();\n      reject(new LockError(\"server closed connection\"));\n    };\n\n    const cleanup = () => {\n      sock.removeListener(\"data\", onData);\n      sock.removeListener(\"error\", onError);\n      sock.removeListener(\"close\", onClose);\n    };\n\n    sock.on(\"data\", onData);\n    sock.on(\"error\", onError);\n    sock.on(\"close\", onClose);\n  });\n}\n\nfunction connect(host: string, port: number): Promise<net.Socket> {\n  return new Promise((resolve, reject) => {\n    const sock = net.createConnection({ host, port }, () => resolve(sock));\n    sock.on(\"error\", reject);\n  });\n}\n\n// ---------------------------------------------------------------------------\n// CRC32 (same algorithm as Python's zlib.crc32)\n// ---------------------------------------------------------------------------\n\nconst CRC32_TABLE = new Uint32Array(256);\nfor (let i = 0; i < 256; i++) {\n  let c = i;\n  for (let j = 0; j < 8; j++) {\n    c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;\n  }\n  CRC32_TABLE[i] = c;\n}\n\nfunction crc32(buf: Buffer): number {\n  let crc = 0xffffffff;\n  for (let i = 0; i < buf.length; i++) {\n    crc = CRC32_TABLE[(crc ^ buf[i]) & 0xff] ^ (crc >>> 8);\n  }\n  return (crc ^ 0xffffffff) >>> 0;\n}\n\n// ---------------------------------------------------------------------------\n// Sharding\n// ---------------------------------------------------------------------------\n\nexport type ShardingStrategy = (key: string, numServers: number) => number;\n\nexport function stableHashShard(key: string, numServers: number): number {\n  return (crc32(Buffer.from(key, \"utf-8\")) >>> 0) % numServers;\n}\n\n// ---------------------------------------------------------------------------\n// Protocol functions\n// ---------------------------------------------------------------------------\n\nexport async function acquire(\n  sock: net.Socket,\n  key: string,\n  acquireTimeoutS: number,\n  leaseTtlS?: number,\n): Promise<{ token: string; lease: number }> {\n  const arg =\n    leaseTtlS == null\n      ? String(acquireTimeoutS)\n      : `${acquireTimeoutS} ${leaseTtlS}`;\n\n  sock.write(encodeLines(\"l\", key, arg));\n\n  const resp = await readline(sock);\n  if (resp === \"timeout\") {\n    throw new AcquireTimeoutError(key);\n  }\n  if (!resp.startsWith(\"ok \")) {\n    throw new LockError(`acquire failed: '${resp}'`);\n  }\n\n  const parts = resp.split(\" \");\n  if (parts.length < 2) {\n    throw new LockError(`bad ok response: '${resp}'`);\n  }\n  const token = parts[1];\n  const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 30;\n  return { token, lease };\n}\n\nexport async function renew(\n  sock: net.Socket,\n  key: string,\n  token: string,\n  leaseTtlS?: number,\n): Promise<number> {\n  const arg = leaseTtlS == null ? token : `${token} ${leaseTtlS}`;\n  sock.write(encodeLines(\"n\", key, arg));\n\n  const resp = await readline(sock);\n  if (!resp.startsWith(\"ok\")) {\n    throw new LockError(`renew failed: '${resp}'`);\n  }\n\n  const parts = resp.split(\" \");\n  if (parts.length >= 2 && /^\\d+$/.test(parts[1])) {\n    return parseInt(parts[1], 10);\n  }\n  return -1;\n}\n\nexport async function enqueue(\n  sock: net.Socket,\n  key: string,\n  leaseTtlS?: number,\n): Promise<{ status: \"acquired\" | \"queued\"; token: string | null; lease: number | null }> {\n  const arg = leaseTtlS == null ? \"\" : String(leaseTtlS);\n  sock.write(encodeLines(\"e\", key, arg));\n\n  const resp = await readline(sock);\n  if (resp.startsWith(\"acquired \")) {\n    const parts = resp.split(\" \");\n    const token = parts[1];\n    const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 33;\n    return { status: \"acquired\", token, lease };\n  }\n  if (resp === \"queued\") {\n    return { status: \"queued\", token: null, lease: null };\n  }\n  throw new LockError(`enqueue failed: '${resp}'`);\n}\n\nexport async function waitForLock(\n  sock: net.Socket,\n  key: string,\n  waitTimeoutS: number,\n): Promise<{ token: string; lease: number }> {\n  sock.write(encodeLines(\"w\", key, String(waitTimeoutS)));\n\n  const resp = await readline(sock);\n  if (resp === \"timeout\") {\n    throw new AcquireTimeoutError(key);\n  }\n  if (!resp.startsWith(\"ok \")) {\n    throw new LockError(`wait failed: '${resp}'`);\n  }\n\n  const parts = resp.split(\" \");\n  const token = parts[1];\n  const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 33;\n  return { token, lease };\n}\n\nexport async function release(\n  sock: net.Socket,\n  key: string,\n  token: string,\n): Promise<void> {\n  sock.write(encodeLines(\"r\", key, token));\n\n  const resp = await readline(sock);\n  if (resp !== \"ok\") {\n    throw new LockError(`release failed: '${resp}'`);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// DistributedLock\n// ---------------------------------------------------------------------------\n\nexport interface DistributedLockOptions {\n  key: string;\n  acquireTimeoutS?: number;\n  leaseTtlS?: number;\n  /** @deprecated Use `servers` instead. */\n  host?: string;\n  /** @deprecated Use `servers` instead. */\n  port?: number;\n  servers?: Array<[host: string, port: number]>;\n  shardingStrategy?: ShardingStrategy;\n  renewRatio?: number;\n}\n\nexport class DistributedLock {\n  readonly key: string;\n  readonly acquireTimeoutS: number;\n  readonly leaseTtlS: number | undefined;\n  readonly servers: Array<[string, number]>;\n  readonly shardingStrategy: ShardingStrategy;\n  readonly renewRatio: number;\n\n  token: string | null = null;\n  lease: number = 0;\n\n  private sock: net.Socket | null = null;\n  private renewTimer: ReturnType<typeof setTimeout> | null = null;\n  private closed = false;\n\n  constructor(opts: DistributedLockOptions) {\n    this.key = opts.key;\n    this.acquireTimeoutS = opts.acquireTimeoutS ?? 10;\n    this.leaseTtlS = opts.leaseTtlS;\n\n    if (opts.servers) {\n      if (opts.servers.length === 0) {\n        throw new LockError(\"servers list must not be empty\");\n      }\n      this.servers = opts.servers;\n    } else {\n      this.servers = [[opts.host ?? DEFAULT_HOST, opts.port ?? DEFAULT_PORT]];\n    }\n\n    this.shardingStrategy = opts.shardingStrategy ?? stableHashShard;\n    this.renewRatio = opts.renewRatio ?? 0.5;\n  }\n\n  private pickServer(): [string, number] {\n    const idx = this.shardingStrategy(this.key, this.servers.length);\n    return this.servers[idx];\n  }\n\n  /** Acquire the lock. Returns `true` on success, `false` on timeout. */\n  async acquire(): Promise<boolean> {\n    this.closed = false;\n    const [host, port] = this.pickServer();\n    this.sock = await connect(host, port);\n    try {\n      const result = await acquire(\n        this.sock,\n        this.key,\n        this.acquireTimeoutS,\n        this.leaseTtlS,\n      );\n      this.token = result.token;\n      this.lease = result.lease;\n    } catch (err) {\n      await this.close();\n      if (err instanceof AcquireTimeoutError) return false;\n      throw err;\n    }\n    this.startRenew();\n    return true;\n  }\n\n  /** Release the lock and close the connection. */\n  async release(): Promise<void> {\n    try {\n      this.stopRenew();\n      if (this.sock && this.token) {\n        await release(this.sock, this.key, this.token);\n      }\n    } finally {\n      await this.close();\n    }\n  }\n\n  /**\n   * Two-phase step 1: connect and join the FIFO queue.\n   * Returns `\"acquired\"` (fast-path, lock is already held) or `\"queued\"`.\n   * If acquired immediately, the renew loop starts automatically.\n   */\n  async enqueue(): Promise<\"acquired\" | \"queued\"> {\n    this.closed = false;\n    const [host, port] = this.pickServer();\n    this.sock = await connect(host, port);\n    try {\n      const result = await enqueue(this.sock, this.key, this.leaseTtlS);\n      if (result.status === \"acquired\") {\n        this.token = result.token;\n        this.lease = result.lease ?? 0;\n        this.startRenew();\n      }\n      return result.status;\n    } catch (err) {\n      await this.close();\n      throw err;\n    }\n  }\n\n  /**\n   * Two-phase step 2: block until the lock is granted.\n   * Returns `true` if granted, `false` on timeout.\n   * If already acquired during `enqueue()`, returns `true` immediately.\n   */\n  async wait(timeoutS?: number): Promise<boolean> {\n    if (this.token !== null) {\n      // Already acquired during enqueue (fast path)\n      return true;\n    }\n    if (!this.sock) {\n      throw new LockError(\"not connected; call enqueue() first\");\n    }\n    const timeout = timeoutS ?? this.acquireTimeoutS;\n    try {\n      const result = await waitForLock(this.sock, this.key, timeout);\n      this.token = result.token;\n      this.lease = result.lease;\n    } catch (err) {\n      await this.close();\n      if (err instanceof AcquireTimeoutError) return false;\n      throw err;\n    }\n    this.startRenew();\n    return true;\n  }\n\n  /**\n   * Run `fn` while holding the lock, then release automatically.\n   *\n   * ```ts\n   * const lock = new DistributedLock({ key: \"my-resource\" });\n   * await lock.withLock(async () => {\n   *   // critical section\n   * });\n   * ```\n   */\n  async withLock<T>(fn: () => T | Promise<T>): Promise<T> {\n    const ok = await this.acquire();\n    if (!ok) {\n      throw new AcquireTimeoutError(this.key);\n    }\n    try {\n      return await fn();\n    } finally {\n      await this.release();\n    }\n  }\n\n  /** Close the underlying socket (idempotent). */\n  async close(): Promise<void> {\n    if (this.closed) return;\n    this.closed = true;\n    this.stopRenew();\n    if (this.sock) {\n      this.sock.destroy();\n      this.sock = null;\n    }\n    this.token = null;\n  }\n\n  // -- internals --\n\n  private startRenew(): void {\n    const interval = Math.max(1, this.lease * this.renewRatio) * 1000;\n    const loop = async () => {\n      if (!this.sock || !this.token) return;\n      try {\n        await renew(this.sock, this.key, this.token, this.leaseTtlS);\n      } catch {\n        console.error(\n          `lock lost (renew failed): key=${this.key} token=${this.token}`,\n        );\n        this.token = null;\n        return;\n      }\n      this.renewTimer = setTimeout(loop, interval);\n    };\n    this.renewTimer = setTimeout(loop, interval);\n  }\n\n  private stopRenew(): void {\n    if (this.renewTimer != null) {\n      clearTimeout(this.renewTimer);\n      this.renewTimer = null;\n    }\n  }\n}\n"],"mappings":";AAAA,YAAY,SAAS;AAErB,IAAM,eAAe;AACrB,IAAM,eAAe;AAMd,IAAM,sBAAN,cAAkC,MAAM;AAAA,EAC7C,YAAY,KAAa;AACvB,UAAM,sBAAsB,GAAG,GAAG;AAClC,SAAK,OAAO;AAAA,EACd;AACF;AAEO,IAAM,YAAN,cAAwB,MAAM;AAAA,EACnC,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAMA,SAAS,eAAe,OAAyB;AAC/C,SAAO,OAAO,KAAK,MAAM,IAAI,CAAC,MAAM,IAAI,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO;AACjE;AAOA,SAAS,SAAS,MAAmC;AACnD,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,QAAI,MAAM;AAEV,UAAM,SAAS,CAAC,UAAkB;AAChC,aAAO,MAAM,SAAS,OAAO;AAC7B,YAAM,MAAM,IAAI,QAAQ,IAAI;AAC5B,UAAI,QAAQ,IAAI;AACd,gBAAQ;AACR,gBAAQ,IAAI,MAAM,GAAG,GAAG,EAAE,QAAQ,OAAO,EAAE,CAAC;AAAA,MAC9C;AAAA,IACF;AAEA,UAAM,UAAU,CAAC,QAAe;AAC9B,cAAQ;AACR,aAAO,GAAG;AAAA,IACZ;AAEA,UAAM,UAAU,MAAM;AACpB,cAAQ;AACR,aAAO,IAAI,UAAU,0BAA0B,CAAC;AAAA,IAClD;AAEA,UAAM,UAAU,MAAM;AACpB,WAAK,eAAe,QAAQ,MAAM;AAClC,WAAK,eAAe,SAAS,OAAO;AACpC,WAAK,eAAe,SAAS,OAAO;AAAA,IACtC;AAEA,SAAK,GAAG,QAAQ,MAAM;AACtB,SAAK,GAAG,SAAS,OAAO;AACxB,SAAK,GAAG,SAAS,OAAO;AAAA,EAC1B,CAAC;AACH;AAEA,SAAS,QAAQ,MAAc,MAAmC;AAChE,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,UAAM,OAAW,qBAAiB,EAAE,MAAM,KAAK,GAAG,MAAM,QAAQ,IAAI,CAAC;AACrE,SAAK,GAAG,SAAS,MAAM;AAAA,EACzB,CAAC;AACH;AAMA,IAAM,cAAc,IAAI,YAAY,GAAG;AACvC,SAAS,IAAI,GAAG,IAAI,KAAK,KAAK;AAC5B,MAAI,IAAI;AACR,WAAS,IAAI,GAAG,IAAI,GAAG,KAAK;AAC1B,QAAI,IAAI,IAAI,aAAc,MAAM,IAAK,MAAM;AAAA,EAC7C;AACA,cAAY,CAAC,IAAI;AACnB;AAEA,SAAS,MAAM,KAAqB;AAClC,MAAI,MAAM;AACV,WAAS,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK;AACnC,UAAM,aAAa,MAAM,IAAI,CAAC,KAAK,GAAI,IAAK,QAAQ;AAAA,EACtD;AACA,UAAQ,MAAM,gBAAgB;AAChC;AAQO,SAAS,gBAAgB,KAAa,YAA4B;AACvE,UAAQ,MAAM,OAAO,KAAK,KAAK,OAAO,CAAC,MAAM,KAAK;AACpD;AAMA,eAAsB,QACpB,MACA,KACA,iBACA,WAC2C;AAC3C,QAAM,MACJ,aAAa,OACT,OAAO,eAAe,IACtB,GAAG,eAAe,IAAI,SAAS;AAErC,OAAK,MAAM,YAAY,KAAK,KAAK,GAAG,CAAC;AAErC,QAAM,OAAO,MAAM,SAAS,IAAI;AAChC,MAAI,SAAS,WAAW;AACtB,UAAM,IAAI,oBAAoB,GAAG;AAAA,EACnC;AACA,MAAI,CAAC,KAAK,WAAW,KAAK,GAAG;AAC3B,UAAM,IAAI,UAAU,oBAAoB,IAAI,GAAG;AAAA,EACjD;AAEA,QAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,MAAI,MAAM,SAAS,GAAG;AACpB,UAAM,IAAI,UAAU,qBAAqB,IAAI,GAAG;AAAA,EAClD;AACA,QAAM,QAAQ,MAAM,CAAC;AACrB,QAAM,QAAQ,MAAM,UAAU,IAAI,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI;AAC3D,SAAO,EAAE,OAAO,MAAM;AACxB;AAEA,eAAsB,MACpB,MACA,KACA,OACA,WACiB;AACjB,QAAM,MAAM,aAAa,OAAO,QAAQ,GAAG,KAAK,IAAI,SAAS;AAC7D,OAAK,MAAM,YAAY,KAAK,KAAK,GAAG,CAAC;AAErC,QAAM,OAAO,MAAM,SAAS,IAAI;AAChC,MAAI,CAAC,KAAK,WAAW,IAAI,GAAG;AAC1B,UAAM,IAAI,UAAU,kBAAkB,IAAI,GAAG;AAAA,EAC/C;AAEA,QAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,MAAI,MAAM,UAAU,KAAK,QAAQ,KAAK,MAAM,CAAC,CAAC,GAAG;AAC/C,WAAO,SAAS,MAAM,CAAC,GAAG,EAAE;AAAA,EAC9B;AACA,SAAO;AACT;AAEA,eAAsB,QACpB,MACA,KACA,WACwF;AACxF,QAAM,MAAM,aAAa,OAAO,KAAK,OAAO,SAAS;AACrD,OAAK,MAAM,YAAY,KAAK,KAAK,GAAG,CAAC;AAErC,QAAM,OAAO,MAAM,SAAS,IAAI;AAChC,MAAI,KAAK,WAAW,WAAW,GAAG;AAChC,UAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,UAAM,QAAQ,MAAM,CAAC;AACrB,UAAM,QAAQ,MAAM,UAAU,IAAI,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI;AAC3D,WAAO,EAAE,QAAQ,YAAY,OAAO,MAAM;AAAA,EAC5C;AACA,MAAI,SAAS,UAAU;AACrB,WAAO,EAAE,QAAQ,UAAU,OAAO,MAAM,OAAO,KAAK;AAAA,EACtD;AACA,QAAM,IAAI,UAAU,oBAAoB,IAAI,GAAG;AACjD;AAEA,eAAsB,YACpB,MACA,KACA,cAC2C;AAC3C,OAAK,MAAM,YAAY,KAAK,KAAK,OAAO,YAAY,CAAC,CAAC;AAEtD,QAAM,OAAO,MAAM,SAAS,IAAI;AAChC,MAAI,SAAS,WAAW;AACtB,UAAM,IAAI,oBAAoB,GAAG;AAAA,EACnC;AACA,MAAI,CAAC,KAAK,WAAW,KAAK,GAAG;AAC3B,UAAM,IAAI,UAAU,iBAAiB,IAAI,GAAG;AAAA,EAC9C;AAEA,QAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,QAAM,QAAQ,MAAM,CAAC;AACrB,QAAM,QAAQ,MAAM,UAAU,IAAI,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI;AAC3D,SAAO,EAAE,OAAO,MAAM;AACxB;AAEA,eAAsB,QACpB,MACA,KACA,OACe;AACf,OAAK,MAAM,YAAY,KAAK,KAAK,KAAK,CAAC;AAEvC,QAAM,OAAO,MAAM,SAAS,IAAI;AAChC,MAAI,SAAS,MAAM;AACjB,UAAM,IAAI,UAAU,oBAAoB,IAAI,GAAG;AAAA,EACjD;AACF;AAmBO,IAAM,kBAAN,MAAsB;AAAA,EAClB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,QAAuB;AAAA,EACvB,QAAgB;AAAA,EAER,OAA0B;AAAA,EAC1B,aAAmD;AAAA,EACnD,SAAS;AAAA,EAEjB,YAAY,MAA8B;AACxC,SAAK,MAAM,KAAK;AAChB,SAAK,kBAAkB,KAAK,mBAAmB;AAC/C,SAAK,YAAY,KAAK;AAEtB,QAAI,KAAK,SAAS;AAChB,UAAI,KAAK,QAAQ,WAAW,GAAG;AAC7B,cAAM,IAAI,UAAU,gCAAgC;AAAA,MACtD;AACA,WAAK,UAAU,KAAK;AAAA,IACtB,OAAO;AACL,WAAK,UAAU,CAAC,CAAC,KAAK,QAAQ,cAAc,KAAK,QAAQ,YAAY,CAAC;AAAA,IACxE;AAEA,SAAK,mBAAmB,KAAK,oBAAoB;AACjD,SAAK,aAAa,KAAK,cAAc;AAAA,EACvC;AAAA,EAEQ,aAA+B;AACrC,UAAM,MAAM,KAAK,iBAAiB,KAAK,KAAK,KAAK,QAAQ,MAAM;AAC/D,WAAO,KAAK,QAAQ,GAAG;AAAA,EACzB;AAAA;AAAA,EAGA,MAAM,UAA4B;AAChC,SAAK,SAAS;AACd,UAAM,CAAC,MAAM,IAAI,IAAI,KAAK,WAAW;AACrC,SAAK,OAAO,MAAM,QAAQ,MAAM,IAAI;AACpC,QAAI;AACF,YAAM,SAAS,MAAM;AAAA,QACnB,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,MACP;AACA,WAAK,QAAQ,OAAO;AACpB,WAAK,QAAQ,OAAO;AAAA,IACtB,SAAS,KAAK;AACZ,YAAM,KAAK,MAAM;AACjB,UAAI,eAAe,oBAAqB,QAAO;AAC/C,YAAM;AAAA,IACR;AACA,SAAK,WAAW;AAChB,WAAO;AAAA,EACT;AAAA;AAAA,EAGA,MAAM,UAAyB;AAC7B,QAAI;AACF,WAAK,UAAU;AACf,UAAI,KAAK,QAAQ,KAAK,OAAO;AAC3B,cAAM,QAAQ,KAAK,MAAM,KAAK,KAAK,KAAK,KAAK;AAAA,MAC/C;AAAA,IACF,UAAE;AACA,YAAM,KAAK,MAAM;AAAA,IACnB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,UAA0C;AAC9C,SAAK,SAAS;AACd,UAAM,CAAC,MAAM,IAAI,IAAI,KAAK,WAAW;AACrC,SAAK,OAAO,MAAM,QAAQ,MAAM,IAAI;AACpC,QAAI;AACF,YAAM,SAAS,MAAM,QAAQ,KAAK,MAAM,KAAK,KAAK,KAAK,SAAS;AAChE,UAAI,OAAO,WAAW,YAAY;AAChC,aAAK,QAAQ,OAAO;AACpB,aAAK,QAAQ,OAAO,SAAS;AAC7B,aAAK,WAAW;AAAA,MAClB;AACA,aAAO,OAAO;AAAA,IAChB,SAAS,KAAK;AACZ,YAAM,KAAK,MAAM;AACjB,YAAM;AAAA,IACR;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,KAAK,UAAqC;AAC9C,QAAI,KAAK,UAAU,MAAM;AAEvB,aAAO;AAAA,IACT;AACA,QAAI,CAAC,KAAK,MAAM;AACd,YAAM,IAAI,UAAU,qCAAqC;AAAA,IAC3D;AACA,UAAM,UAAU,YAAY,KAAK;AACjC,QAAI;AACF,YAAM,SAAS,MAAM,YAAY,KAAK,MAAM,KAAK,KAAK,OAAO;AAC7D,WAAK,QAAQ,OAAO;AACpB,WAAK,QAAQ,OAAO;AAAA,IACtB,SAAS,KAAK;AACZ,YAAM,KAAK,MAAM;AACjB,UAAI,eAAe,oBAAqB,QAAO;AAC/C,YAAM;AAAA,IACR;AACA,SAAK,WAAW;AAChB,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAM,SAAY,IAAsC;AACtD,UAAM,KAAK,MAAM,KAAK,QAAQ;AAC9B,QAAI,CAAC,IAAI;AACP,YAAM,IAAI,oBAAoB,KAAK,GAAG;AAAA,IACxC;AACA,QAAI;AACF,aAAO,MAAM,GAAG;AAAA,IAClB,UAAE;AACA,YAAM,KAAK,QAAQ;AAAA,IACrB;AAAA,EACF;AAAA;AAAA,EAGA,MAAM,QAAuB;AAC3B,QAAI,KAAK,OAAQ;AACjB,SAAK,SAAS;AACd,SAAK,UAAU;AACf,QAAI,KAAK,MAAM;AACb,WAAK,KAAK,QAAQ;AAClB,WAAK,OAAO;AAAA,IACd;AACA,SAAK,QAAQ;AAAA,EACf;AAAA;AAAA,EAIQ,aAAmB;AACzB,UAAM,WAAW,KAAK,IAAI,GAAG,KAAK,QAAQ,KAAK,UAAU,IAAI;AAC7D,UAAM,OAAO,YAAY;AACvB,UAAI,CAAC,KAAK,QAAQ,CAAC,KAAK,MAAO;AAC/B,UAAI;AACF,cAAM,MAAM,KAAK,MAAM,KAAK,KAAK,KAAK,OAAO,KAAK,SAAS;AAAA,MAC7D,QAAQ;AACN,gBAAQ;AAAA,UACN,iCAAiC,KAAK,GAAG,UAAU,KAAK,KAAK;AAAA,QAC/D;AACA,aAAK,QAAQ;AACb;AAAA,MACF;AACA,WAAK,aAAa,WAAW,MAAM,QAAQ;AAAA,IAC7C;AACA,SAAK,aAAa,WAAW,MAAM,QAAQ;AAAA,EAC7C;AAAA,EAEQ,YAAkB;AACxB,QAAI,KAAK,cAAc,MAAM;AAC3B,mBAAa,KAAK,UAAU;AAC5B,WAAK,aAAa;AAAA,IACpB;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dflockd-client",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "TypeScript client for the dflockd distributed lock daemon",
   "type": "module",
   "exports": {
@@ -24,6 +24,7 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
+    "test": "npx tsx --test src/client.test.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [