fileLock

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, in order:

1. flock — flock(2) via Bun FFI on Unix when bun:ffi can load libc. Not available on Windows, and not available under plain Node (no FFI). Kernel releases the lock when the fd closes (including process death).
2. file — atomic lock-directory creation. This is the strategy used by proper-lockfile: mkdir is atomic on Windows, Unix, and network file systems where open(..., "wx") may not be reliable. Stale detection is always on (fixed STALE_MS + heartbeat) so a crashed holder on this backend can be reclaimed.

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.

Interfaces

• FileLockAcquisition
• FileLockOptions

Type Aliases

• FileLockBackend

Functions

• withFileLock