PersistentAI API Documentation / @persistent-ai/fireflow-types / IFlowLockService

Interface: IFlowLockService

Defined in: packages/fireflow-types/src/execution/services/flow-lock-service.ts:32

Flow lock service — provides distributed named locks for critical sections in flows.

Locks are backed by PostgreSQL and always have a TTL (auto-expire). This prevents deadlocks when a flow crashes between LockAcquire and LockRelease nodes.

Usage in flows: FFDBLockAcquireNode → (critical section) → FFDBLockReleaseNode

Example

const lockSvc = context.services?.flowLock
if (!lockSvc) throw new Error('Flow lock service not available')

const { acquired, lockId } = await lockSvc.acquire('my-resource', 5000, 10000)
if (!acquired) throw new Error('Could not acquire lock — timed out waiting')
try {
  // ... critical section ...
} finally {
  await lockSvc.release('my-resource', lockId)
}

Properties

acquire()

acquire: (lockKey, lockTtlMs, waitTimeoutMs) => Promise<{ acquired: boolean; lockId: string; }>

Defined in: packages/fireflow-types/src/execution/services/flow-lock-service.ts:43

Acquire a named lock.

Parameters

lockKey

string

Unique resource name (e.g. a file path or entity ID).

lockTtlMs

number

Lock auto-expiry in ms. The lock is released automatically if the holder crashes or does not call release(). REQUIRED — never pass 0.

waitTimeoutMs

number

Max time to wait for the lock if another holder has it. Returns { acquired: false } if exceeded.

Returns

Promise<{ acquired: boolean; lockId: string; }>

— lockId must be passed to release().

---

release()

release: (lockKey, lockId) => Promise<{ released: boolean; }>

Defined in: packages/fireflow-types/src/execution/services/flow-lock-service.ts:53

Release a previously acquired lock.

Parameters

lockKey

string

Same key used in acquire().

lockId

string

Token returned by acquire(). Prevents accidental release of another holder's lock.

Returns

Promise<{ released: boolean; }>

if the lock was found and removed, { released: false } if it had already expired or was released by someone else (not an error — idempotent).