Imported from bedkillerspacex-boop/codex-skill-library (typescript-distributed-lock/SKILL.md). Install upstream with npx skills add bedkillerspacex-boop/codex-skill-library --skill typescript-distributed-lock. Copyright stays with the author.

TypeScript Distributed Lock

Scope And Authorization

• In scope: Adding mutual exclusion for jobs and critical sections in systems you run.
• Out of scope: Locking out other tenants on shared unmanaged infrastructure; using locks as a substitute for correct transaction design when not appropriate.
• Prefer TTLs, fencing, and idempotency; locks are fallible.
• Pair with typescript-cron-safety, code-quality-standards.

When To Use

• Exactly-one leader tasks across replicas.
• Preventing double-billing / double-send side effects.
• Serializing migrations or compaction jobs.
• Coordinating multi-step workflows with leases.
• Replacing unsafe "assume single replica" cron.

Do Not Use As Primary

Domain Focus

Primitives

Workflow

1. Confirm scope and success criteria

1. Record resource protected, max critical section time, replica count, failure modes.
2. Success: multi-instance test shows single winner; lock expires on crash.
3. Prefer DB constraints for money over locks alone.

2. Choose backend

3. Implement Redis-style lock (sketch)

export type RedisLike = {
  set: (k: string, v: string, mode: "EX", ttl: number, flag: "NX") => Promise<"OK" | null>;
  eval: (script: string, keys: string[], args: string[]) => Promise<unknown>;
};

const releaseScript = `
if redis.call("get", KEYS[1]) == ARGV[1] then
  return redis.call("del", KEYS[1])
else
  return 0
end`;

export async function acquire(
  r: RedisLike,
  key: string,
  token: string,
  ttlSec: number,
): Promise<boolean> {
  const res = await r.set(key, token, "EX", ttlSec, "NX");
  return res === "OK";
}

export async function release(r: RedisLike, key: string, token: string): Promise<void> {
  await r.eval(releaseScript, [key], [token]);
}

Renewal: extend TTL only if token matches; stop work if renew fails.

4. Fencing

export function assertFence(resourceFence: number, lockFence: number): void {
  if (lockFence < resourceFence) throw new Error("stale_lock_fence");
}

Resource stores last fence; reject lower tokens after write.

5. Testing

pnpm vitest run tests/distributed-lock
# Start 5 workers; assert sideEffectCounter increments once per period

6. Verify ops

7. Hand off

1. Document lock key namespace and TTLs.
2. Alert on prolonged hold times.
3. Prefer idempotent consumers even with locks.

Good / Bad

Output Checklist

• Resource and TTL design documented
• Backend chosen
• Acquire/release/renew implemented safely
• Fencing or equivalent for critical writes
• Multi-instance tests pass
• Metrics/alerts
• Idempotency paired
• code-quality-standards applied
• Residual risk noted

Rules

• Locks fail; design for timeout and double-delivery.
• Never lock without TTL unless session-scoped DB lock.
• Unique tokens on release.
• Authorized datastores only.
• Cron skill covers scheduling composition.