class Saga

Defines a long-running business process that coordinates across events and time.

Sagas implement the Saga pattern for managing complex workflows that span multiple aggregates, external services, and time-based operations. They provide stateful event processing with support for timers, error handling, and process coordination.

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

Key Features: - *\*Stateful Processing\**: Maintains state across multiple events - \**Timer Support\**: Schedule delays and recurring operations - \**Error Handling\**: Custom error handling and compensation logic - \**Event Correlation\**: Match events to specific saga instances - \**Parallel Processing\*\*: Configurable concurrency for high throughput

Properties

errorHandler

Signature

errorHandler: (saga: any, event: EventicleEvent, error: Error) => Promise<void>;

eventHandler

Signature

eventHandler: Map<string, {
        config: HandlerConfig<any, InstanceData, TimeoutNames>;
        handle: (saga: SagaInstance<TimeoutNames, InstanceData>, event: EventicleEvent) => Promise<void>;
    }>;

hotLaneParallelEventCount

Slot count for the hot lane. Defaults to parallelEventCount when isHotPredicate is set.

Signature

hotLaneParallelEventCount?: number;

isHotPredicate

Optional predicate that classifies an incoming event as hot (true) or cold (false). When set, the saga registers two Kafka consumer groups: - cold lane (saga-${name}): processes only events where the predicate returns false - hot lane (saga-${name}-hot): processes only events where the predicate returns true Hot events get a dedicated pool of slots that cannot be saturated by cold flood.

Signature

isHotPredicate?: (event: EventicleEvent) => Promise<boolean> | boolean;

name

Signature

readonly name: string;

parallelEventCount

Signature

parallelEventCount: number;

starts

Signature

starts: Map<string, {
        config: StartHandlerConfig<any, InstanceData, TimeoutNames>;
        handle: (saga: SagaInstance<TimeoutNames, InstanceData>, event: EventicleEvent) => Promise<void>;
    }>;

streams

Signature

streams: string[];

streamSubs

Signature

streamSubs: EventSubscriptionControl[];

timerHandler

Signature

timerHandler: Map<TimeoutNames, {
        handle: (saga: SagaInstance<TimeoutNames, InstanceData>) => Promise<void>;
    }>;

Constructors

(constructor)(name)

Constructs a new instance of the Saga class

Parameters
Name	Type	Description
`name`	`string`

Signature

constructor(name: string);

Methods

on(eventName, config, handler)

Registers an event handler for existing saga instances.

When the specified event type is received, the handler will be called on any existing saga instances that match the event based on the matchInstance configuration.

Parameters
Name	Type	Description
`eventName`	`string`	The event type to handle
`config`	`\~HandlerConfig<T, InstanceData, TimeoutNames>`	Configuration for instance matching and locking
`handler`	`(saga: SagaInstance<TimeoutNames, InstanceData>, event: T) => Promise<void>`	The function to execute for matching instances
Returns	`Saga<TimeoutNames, InstanceData>`

Signature

on<T extends EventicleEvent>(eventName: string, config: HandlerConfig<T, InstanceData, TimeoutNames>, handler: (saga: SagaInstance<TimeoutNames, InstanceData>, event: T) => Promise<void>): Saga<TimeoutNames, InstanceData>;

onError(handler)

Parameters
Name	Type	Description
`handler`	`(saga: any, event: EventicleEvent, error: Error) => Promise<void>`
Returns	`Saga<TimeoutNames, InstanceData>`

Signature

onError(handler: (saga: any, event: EventicleEvent, error: Error) => Promise<void>): Saga<TimeoutNames, InstanceData>;

onTimer(name, handle)

This will be called on the timer.

No event is present.

Parameters
Name	Type	Description
`name`	`TimeoutNames`	The name of the timer
`handle`	`(saga: SagaInstance<TimeoutNames, InstanceData>) => Promise<void>`	the async function to execute.
Returns	`Saga<TimeoutNames, InstanceData>`

Signature

onTimer(name: TimeoutNames, handle: (saga: SagaInstance<TimeoutNames, InstanceData>) => Promise<void>): Saga<TimeoutNames, InstanceData>;

parallelEvents(val)

Parameters
Name	Type	Description
`val`	`number`
Returns	`Saga<TimeoutNames, InstanceData>`

Signature

parallelEvents(val: number): Saga<TimeoutNames, InstanceData>;

startOn(eventName, config, handler)

Registers an event handler that can start new saga instances.

When the specified event type is received and no existing saga instance matches, a new saga instance will be created and the handler called. Only one startOn handler per event type is allowed.

Parameters
Name	Type	Description
`eventName`	`string`	The event type that can start new saga instances
`config`	`\~StartHandlerConfig<T, InstanceData, TimeoutNames>`	Configuration for instance creation
`handler`	`(saga: SagaInstance<TimeoutNames, InstanceData>, event: T) => Promise<void>`	The function to execute when starting a new instance
Returns	`Saga<TimeoutNames, InstanceData>`

Signature

startOn<T extends EventicleEvent>(eventName: string, config: StartHandlerConfig<T, InstanceData, TimeoutNames>, handler: (saga: SagaInstance<TimeoutNames, InstanceData>, event: T) => Promise<void>): Saga<TimeoutNames, InstanceData>;

subscribeStreams(streams)

Parameters
Name	Type	Description
`streams`	`string[]`
Returns	`Saga<TimeoutNames, InstanceData>`

Signature

subscribeStreams(streams: string[]): Saga<TimeoutNames, InstanceData>;

withHotParallelEvents(val)

Configure dedicated slot count for the hot lane.

Parameters
Name	Type	Description
`val`	`number`
Returns	`Saga<TimeoutNames, InstanceData>`

Signature

withHotParallelEvents(val: number): Saga<TimeoutNames, InstanceData>;

withHotPredicate(predicate)

Enable hot/cold prioritisation by subscribing two Kafka consumer groups. The predicate is evaluated for every event in both lanes; each lane only processes events that match its bucket.

Parameters
Name	Type	Description
`predicate`	`(event: EventicleEvent) => Promise<boolean> \| boolean`
Returns	`Saga<TimeoutNames, InstanceData>`

Signature

withHotPredicate(predicate: (event: EventicleEvent) => Promise<boolean> | boolean): Saga<TimeoutNames, InstanceData>;