class SagaInstance

Represents a single running instance of a saga workflow.

SagaInstance contains the runtime state and execution context for a specific saga execution. Each instance tracks its data, manages timers, and provides methods for saga lifecycle management.

TimeoutNames - Union type of timer names this saga can schedule  T - Type of the saga's persistent data

Properties

internalData

Signature

readonly internalData: any;

record

Signature

readonly record?: Record;

timersToAdd

Timers pending addition in the next persistence cycle

Signature

readonly timersToAdd: {
        name: TimeoutNames;
        config: {
            isCron: true;
            crontab: string;
        } | {
            isCron: false;
            timeout: number;
        };
    }[];

timersToRemove

Timers pending removal in the next persistence cycle

Signature

readonly timersToRemove: TimeoutNames[];

Constructors

(constructor)(internalData, record)

Constructs a new instance of the SagaInstance class

Parameters
Name	Type	Description
`internalData`	`any`
`record`	`Record`

Signature

constructor(internalData: any, record?: Record);

Methods

endSaga(preserveInstanceData)

Marks the saga instance as completed and schedules it for cleanup.

Once a saga is ended, it will not receive any more events or timer callbacks. The instance data can optionally be preserved for debugging or audit purposes.

Parameters
Name	Type	Description
`preserveInstanceData`	`boolean`	Whether to keep instance data after completion
Returns	`void`

Signature

endSaga(preserveInstanceData?: boolean): void;

get(name)

Retrieves a piece of data from the saga instance state.

Parameters
Name	Type	Description
`name`	`K`	The key of the data to retrieve
Returns	`T[K]`	The value associated with the key

Signature

get<K extends keyof T>(name: K): T[K];

lastEvent()

Signature

lastEvent(): EventicleEvent;

removeTimer(name)

Parameters
Name	Type	Description
`name`	`TimeoutNames`
Returns	`void`

Signature

removeTimer(name: TimeoutNames): void;

set(name, value)

Sets a piece of data in the saga instance state.

The value must be JSON-serializable as saga state is persisted. The 'id' field is protected and cannot be modified.

Parameters
Name	Type	Description
`name`	`keyof T`	The key to set
`value`	`any`	The value to store (must be JSON-serializable)
Returns	`void`

Signature

set(name: keyof T, value: any): void;

upsertTimer(name, config)

Create (or overwrite) a timer to call. Can be either a simple timer (millis to wait), or a cron timer.

If the timer is no longer wanted, it must be removed by calling

Parameters
Name	Type	Description
`name`	`TimeoutNames`	The timer to call
`config`	`{ isCron: true; crontab: string; } \| { isCron: false; timeout: number; }`
Returns	`void`

Signature

upsertTimer(name: TimeoutNames, config: {
        isCron: true;
        crontab: string;
    } | {
        isCron: false;
        timeout: number;
    }): void;