Type Alias: RunStore {#type-alias-runstore}

RunStore = object

Storage backend for runs. Implementations must enforce the VALID_TRANSITIONS state machine and provide atomic claim semantics.

Methods {#methods}

claimIdle() {#claimidle}

claimIdle(limit, leaseOwner?, leaseDurationMs?): Run[]

Atomically claim up to limit idle runs for execution, optionally with lease metadata.

Parameters {#claimidle-parameters}

limit {#claimidle-limit}

number

leaseOwner? {#claimidle-leaseowner}

string

leaseDurationMs? {#claimidle-leasedurationms}

number

Returns {#claimidle-returns}

Run[]

close()? {#close}

optional close(): void

Close the underlying storage connection, if applicable.

Returns {#close-returns}

void

countByState()? {#countbystate}

optional countByState(state): number

Count runs in a given state without loading them.

Parameters {#countbystate-parameters}

state {#countbystate-state}

ProcessState

Returns {#countbystate-returns}

number

create() {#create}

create(processName, eventName, payload, parentRunId?, correlationId?, context?, depth?, idempotencyKey?): Run

Create a new run in idle state for the given process and event.

Parameters {#create-parameters}

processName {#create-processname}

string

eventName {#create-eventname}

string

payload {#create-payload}

unknown

parentRunId? {#create-parentrunid}

string | null

correlationId? {#create-correlationid}

string

context? {#create-context}

Record<string, unknown>

depth? {#create-depth}

number

idempotencyKey? {#create-idempotencykey}

string | null

Returns {#create-returns}

Run

get() {#get}

get(runId): Run | null

Retrieve a run by ID, or null if not found.

Parameters {#get-parameters}

runId {#get-runid}

string

Returns {#get-returns}

Run | null

getAll() {#getall}

getAll(): Run[]

Retrieve all runs in the store.

Returns {#getall-returns}

Run[]

getByIdempotencyKey() {#getbyidempotencykey}

getByIdempotencyKey(key): Run[]

Retrieve all runs with a given idempotency key.

Parameters {#getbyidempotencykey-parameters}

key {#getbyidempotencykey-key}

string

Returns {#getbyidempotencykey-returns}

Run[]

getByProcess() {#getbyprocess}

getByProcess(processName): Run[]

Retrieve all runs for a given process name.

Parameters {#getbyprocess-parameters}

processName {#getbyprocess-processname}

string

Returns {#getbyprocess-returns}

Run[]

getByState() {#getbystate}

getByState(state): Run[]

Retrieve all runs in a given state.

Parameters {#getbystate-parameters}

state {#getbystate-state}

ProcessState

Returns {#getbystate-returns}

Run[]

getByStatePaginated()? {#getbystatepaginated}

optional getByStatePaginated(state, limit, offset, opts?): object

Retrieve a page of runs with total count, optionally filtered by state.

Parameters {#getbystatepaginated-parameters}

state {#getbystatepaginated-state}

ProcessState | null

limit {#getbystatepaginated-limit}

number

offset {#getbystatepaginated-offset}

number

opts? {#getbystatepaginated-opts}

RunQueryOptions

Returns {#getbystatepaginated-returns}

object

runs {#getbystatepaginated-runs}

runs: Run[]

total {#getbystatepaginated-total}

total: number

getByStatusPaginated()? {#getbystatuspaginated}

optional getByStatusPaginated(status, limit, offset, opts?): object

Retrieve a page of runs with total count using operator-facing status semantics.

Parameters {#getbystatuspaginated-parameters}

status {#getbystatuspaginated-status}

RunStatus

limit {#getbystatuspaginated-limit}

number

offset {#getbystatuspaginated-offset}

number

opts? {#getbystatuspaginated-opts}

RunQueryOptions

Returns {#getbystatuspaginated-returns}

object

runs {#getbystatuspaginated-runs}

runs: Run[]

total {#getbystatuspaginated-total}

total: number

getChain() {#getchain}

getChain(runId): Run[]

Retrieve the full causal chain of runs starting from a given run ID.

Parameters {#getchain-parameters}

runId {#getchain-runid}

string

Returns {#getchain-returns}

Run[]

hasActiveRun() {#hasactiverun}

hasActiveRun(processName): boolean

Check whether a process has any active (non-terminal) runs.

Parameters {#hasactiverun-parameters}

processName {#hasactiverun-processname}

string

Returns {#hasactiverun-returns}

boolean

hasIdempotencyKey() {#hasidempotencykey}

hasIdempotencyKey(key): boolean

Check whether an idempotency key has already been used.

Parameters {#hasidempotencykey-parameters}

key {#hasidempotencykey-key}

string

Returns {#hasidempotencykey-returns}

boolean

hasState()? {#hasstate}

optional hasState(state): boolean

Check whether any runs exist in a given state without loading them.

Parameters {#hasstate-parameters}

state {#hasstate-state}

ProcessState

Returns {#hasstate-returns}

boolean

heartbeat() {#heartbeat}

heartbeat(runId, leaseOwner, leaseExpiresAt): void

Update the heartbeat and lease expiry for a running run.

Parameters {#heartbeat-parameters}

runId {#heartbeat-runid}

string

leaseOwner {#heartbeat-leaseowner}

string

leaseExpiresAt {#heartbeat-leaseexpiresat}

number

Returns {#heartbeat-returns}

void

prepareRetry() {#prepareretry}

prepareRetry(runId, retryAfter): void

Mark a run for retry with a delay.

Parameters {#prepareretry-parameters}

runId {#prepareretry-runid}

string

retryAfter {#prepareretry-retryafter}

number

Returns {#prepareretry-returns}

void

pruneCompletedBefore()? {#prunecompletedbefore}

optional pruneCompletedBefore(cutoffMs): string[]

Delete completed non-deferred runs older than the cutoff. Returns the deleted run IDs.

Parameters {#prunecompletedbefore-parameters}

cutoffMs {#prunecompletedbefore-cutoffms}

number

Returns {#prunecompletedbefore-returns}

string[]

reclaimStale() {#reclaimstale}

reclaimStale(): Run[]

Reclaim runs whose leases have expired (crash recovery).

Returns {#reclaimstale-returns}

Run[]

resetAttempt() {#resetattempt}

resetAttempt(runId): void

Reset the attempt counter on a run (used by Engine.requeueDead).

Parameters {#resetattempt-parameters}

runId {#resetattempt-runid}

string

Returns {#resetattempt-returns}

void

setHandlerVersion()? {#sethandlerversion}

optional setHandlerVersion(runId, version): void

Set the handler version on a run.

Parameters {#sethandlerversion-parameters}

runId {#sethandlerversion-runid}

string

version {#sethandlerversion-version}

string

Returns {#sethandlerversion-returns}

void

setResult() {#setresult}

setResult(runId, result): void

Set the handler result on a run.

Parameters {#setresult-parameters}

runId {#setresult-runid}

string

result {#setresult-result}

HandlerResult

Returns {#setresult-returns}

void

transition() {#transition}

transition(runId, state, meta?): Run

Transition a run to a new state, recording metadata in the timeline.

Parameters {#transition-parameters}

runId {#transition-runid}

string

state {#transition-state}

ProcessState

meta? {#transition-meta}

error? {#transition-error}

string

event? {#transition-event}

string

payload? {#transition-payload}

unknown

Returns {#transition-returns}

Run

updateContext() {#updatecontext}

updateContext(runId, key, value): void

Update a single key in the run’s shared context.

Parameters {#updatecontext-parameters}

runId {#updatecontext-runid}

string

key {#updatecontext-key}

string

value {#updatecontext-value}

unknown

Returns {#updatecontext-returns}

void