Type Alias: EngineOptions {#type-alias-engineoptions}

EngineOptions = object

Configuration options for createEngine.

Properties {#properties}

concurrency? {#concurrency}

optional concurrency: number

Maximum number of runs executed concurrently.

Default Value {#concurrency-default-value}

10

handlerTimeoutMs? {#handlertimeoutms}

optional handlerTimeoutMs: number

Timeout in milliseconds for each handler execution.

Default Value {#handlertimeoutms-default-value}

30000

heartbeatIntervalMs? {#heartbeatintervalms}

optional heartbeatIntervalMs: number

Heartbeat interval in milliseconds (defaults to leaseTimeoutMs / 3). Must be strictly less than leaseTimeoutMs, otherwise the lease expires before the first heartbeat.

Throws {#heartbeatintervalms-throws}

EngineError with code ErrorCode.INVALID_CONFIG if >= leaseTimeoutMs.

leaseTimeoutMs? {#leasetimeoutms}

optional leaseTimeoutMs: number

Lease duration in milliseconds for crash recovery.

Default Value {#leasetimeoutms-default-value}

30000

maxChainDepth? {#maxchaindepth}

optional maxChainDepth: number

Maximum depth of chained event chains.

Default Value {#maxchaindepth-default-value}

10

maxPayloadBytes? {#maxpayloadbytes}

optional maxPayloadBytes: number

Maximum payload size in bytes.

Default Value {#maxpayloadbytes-default-value}

1048576 (1 MB)

onDead()? {#ondead}

optional onDead: (run, error) => void

Called when a run exhausts its retry budget and is marked with dead-letter status.

Parameters {#ondead-parameters}

run {#ondead-run}

Run

error {#ondead-error}

string

Returns {#ondead-returns}

void

onEvent()? {#onevent}

optional onEvent: (event) => void

Unified lifecycle event callback. Fires synchronously for every engine event. Must not throw, exceptions are caught and reported to onInternalError but deliberately not re-emitted as internal:error to prevent recursion.

Parameters {#onevent-parameters}

event {#onevent-event}

EngineEvent

Returns {#onevent-returns}

void

Example {#onevent-example}

const engine = createEngine({
  onEvent(event) {
    if (event.type === 'run:complete') {
      console.log(`${event.run.processName} completed in ${event.durationMs}ms`)
    }
  },
})

onInternalError()? {#oninternalerror}

optional onInternalError: (error, context) => void

Called when an internal error is caught that would otherwise be silently swallowed. The context string identifies the error site (e.g. 'fillSlots', 'heartbeat', 'onRunStart').

Parameters {#oninternalerror-parameters}

error {#oninternalerror-error}

unknown

context {#oninternalerror-context}

string

Returns {#oninternalerror-returns}

void

onRetry()? {#onretry}

optional onRetry: (run, error, attempt) => void

Called when a run is retried after failure.

Parameters {#onretry-parameters}

run {#onretry-run}

Run

error {#onretry-error}

string

attempt {#onretry-attempt}

number

Returns {#onretry-returns}

void

onRunError()? {#onrunerror}

optional onRunError: (run, error) => void

Called when a run transitions to errored.

Parameters {#onrunerror-parameters}

run {#onrunerror-run}

Run

error {#onrunerror-error}

string

Returns {#onrunerror-returns}

void

onRunFinish()? {#onrunfinish}

optional onRunFinish: (run) => void

Called when a run finishes, regardless of outcome (completed or errored).

Parameters {#onrunfinish-parameters}

run {#onrunfinish-run}

Run

Returns {#onrunfinish-returns}

void

onRunStart()? {#onrunstart}

optional onRunStart: (run) => void

Called when a run transitions to running.

Parameters {#onrunstart-parameters}

run {#onrunstart-run}

Run

Returns {#onrunstart-returns}

void

retention? {#retention}

optional retention: number | string

Automatically prune completed non-deferred runs older than this duration. Accepts either milliseconds or a compact string like '30d', '12h', '15m', or '500ms'. Effect records for deleted runs are pruned alongside them.

retry? {#retry}

optional retry: RetryPolicy

Default retry policy applied to all processes without an explicit policy.

server? {#server}

optional server: DevServerOptions

Start a dev dashboard HTTP server. The server holds the Node.js event loop open until stopped.

store? {#store}

optional store: "memory" | { path: string; type: "sqlite"; }

Storage backend: 'memory' (default) or SQLite with a file path.