Type Alias: HandlerContext<T> {#type-alias-handlercontextt}

HandlerContext<T> = object

Context object passed to every process handler during execution. Provides access to the event data, run metadata, and side-effect APIs.

Type Parameters {#type-parameters}

T {#t}

T = unknown

The validated payload type (inferred from schema if provided).

Properties {#properties}

context {#context}

context: Record<string, unknown>

Mutable key-value context shared across the correlation chain. Deep-copied via structuredClone on each handler invocation, direct mutations to nested objects will not persist. Use setContext to persist changes.

correlationId {#correlationid}

correlationId: string

Correlation ID shared across the entire event chain.

event {#event}

event: string

The event name that triggered this handler.

payload {#payload}

payload: T

The event payload (validated by schema if one was registered).

runId {#runid}

runId: string

Unique identifier of the current run.

Methods {#methods}

effect() {#effect}

effect<R>(effectKey, fn): Promise<R>

Execute a durable side effect. On first execution the function runs and the result is persisted. On retry the stored result is replayed without re-executing, providing effectively-once semantics.

Type Parameters {#effect-type-parameters}

R {#effect-r}

R

The return type of the effect function.

Parameters {#effect-parameters}

effectKey {#effect-effectkey}

string

Unique key identifying this effect within the run.

fn {#effect-fn}

() => R | Promise<R>

The function to execute (or replay).

Returns {#effect-returns}

Promise<R>

The effect’s result.

setContext() {#setcontext}

setContext(key, value): void

Set a key-value pair in the run’s shared context.

Parameters {#setcontext-parameters}

key {#setcontext-key}

string

The context key.

value {#setcontext-value}

unknown

The value to store.

Returns {#setcontext-returns}

void