Interface: LockEngine

@roomful/core

---

@roomful/core / LockEngine

Interface: LockEngine

Defined in: packages/core/src/types.ts:1706

Exposes a distributed advisory mutex over UI keys for a room. Use it to claim exclusive ownership of an arbitrary key (an editable cell, a draggable block) so peers can coordinate “only one editor at a time” interactions.

Consistency model — there is NO central lock authority. Each peer broadcasts its lock CLAIMS and RELEASES on the event channel and every peer resolves each key’s holder independently and deterministically: the earliest non-expired, non-released claim wins, with the lower peerId breaking exact ties. Because all peers apply the same rule to the same claims, they converge on the same holder. Locks are ADVISORY (a convention — nothing prevents code that ignores the engine from mutating the same resource) and EVENTUALLY CONSISTENT: during the propagation window of two near-simultaneous claims a peer may briefly see itself as holder before a conflicting earlier claim arrives, then converge. LockEngine.acquire waits a short bounded window for conflicting claims to surface before resolving to narrow that race, but cannot eliminate it in a P2P/relay model. Treat the lock as coordination, not a correctness guarantee; there are no deadlocks by design.

Methods

acquire()

acquire(key, options?): Promise<boolean>

Defined in: packages/core/src/types.ts:1721

Claims exclusive ownership of key. Broadcasts a claim, waits a short bounded window for any conflicting earlier claim to surface, then resolves to whether the local peer is the holder.

With options.timeout, keeps re-attempting until the lock frees (a holder releases or its TTL expires) or the timeout elapses. With options.ttl, the claim self-expires after the TTL so a crashed holder cannot hold it forever.

Parameters

key

string

The lock key to claim.

options?

LockAcquireOptions

Optional TTL and wait-timeout configuration.

Returns

Promise<boolean>

A promise resolving true when the local peer holds the lock, false when another peer holds it.

---

getAll()

getAll(): LockState[]

Defined in: packages/core/src/types.ts:1761

Returns the resolved state of every known lock that currently has a holder.

Returns

LockState[]

The current lock states.

---

getHolder()

getHolder(key): Peer<PresenceData> | null

Defined in: packages/core/src/types.ts:1754

Returns the peer currently holding key, or null when the lock is free.

Parameters

key

string

The lock key to resolve.

Returns

Peer<PresenceData> | null

The holding peer, or null.

---

isLocked()

isLocked(key): boolean

Defined in: packages/core/src/types.ts:1746

Reports whether key is currently held by any peer (including the local peer).

Parameters

key

string

The lock key to test.

Returns

boolean

true when the key has a non-expired holder.

---

release()

release(key): void

Defined in: packages/core/src/types.ts:1730

Releases a lock held by the local peer. No-op when the local peer does not hold key.

Parameters

key

string

The lock key to release.

Returns

void

Nothing.

---

releaseAll()

releaseAll(): void

Defined in: packages/core/src/types.ts:1737

Releases every lock currently held by the local peer.

Returns

void

Nothing.

---

subscribe()

subscribe(key, callback): Unsubscribe

Defined in: packages/core/src/types.ts:1771

Subscribes to changes for a single lock key. Fires with the current state whenever the resolved holder, claim time, or expiry for key changes.

Parameters

key

string

The lock key to observe.

callback

(state) => void

The callback invoked with the latest state for key.

Returns

Unsubscribe

A function that removes the listener.

---

subscribeAll()

subscribeAll(callback): Unsubscribe

Defined in: packages/core/src/types.ts:1780

Subscribes to changes across all locks. Fires with every held lock’s state whenever any lock changes.

Parameters

callback

(states) => void

The callback invoked with the latest lock states.

Returns

Unsubscribe

A function that removes the listener.