src/file-lock
Cascading cross-process mutual exclusion via a lockfile.
Serializes concurrent processes (two bun run demo shells, a CLI beside a
server) on the same key. For in-process / worker-thread exclusion use
withProcessLock from ./process-lock.ts instead.
Backends:
- file (default) —
proper-lockfileatomic lock-directory creation, heartbeat, stale recovery, and ownership-safe release. Bun and Node use this same protocol. - flock (explicit compatibility option) —
flock(2)via Bun FFI on Unix. It remains available to callers that selected it explicitly, but a runtime-dependent cascade cannot coordinate Bun and Node.
The first backend that can be initialized is used for the whole call. A busy lock waits; an unavailable backend falls through to the next. Callers may only bound how long to wait (FileLockOptions.timeoutMs); stale timing is not configurable so every holder and waiter agrees.