saga_state_machine library

A MassTransit-style state machine framework for Dart.

Provides declarative, event-driven saga pattern with fluent builder API.

Example:

class OrderSaga extends Saga {
  String? orderId;
  OrderStatus status = OrderStatus.pending;
}

class OrderStateMachine extends SagaStateMachine<OrderSaga, OrderStatus> {
  OrderStateMachine() {
    initially(
      when<OrderCreated>()
        .set((saga, e) => saga.orderId = e.orderId)
        .transitionTo(OrderStatus.pending),
    );

    during(OrderStatus.pending,
      when<PaymentReceived>().transitionTo(OrderStatus.paid),
      when<OrderCancelled>().transitionTo(OrderStatus.cancelled).finalize(),
      timeout(Duration(hours: 24), transitionTo: OrderStatus.expired),
    );
  }
}

Classes

Activity<TSaga extends Saga, TEvent>

Base interface for activities (side effects).

BehaviorContext<TSaga extends Saga, TEvent>

Context passed to event handlers and activities.

EventHandler<TSaga extends Saga, TEvent, TState>

Defines how to handle a specific event type.

FunctionActivity<TSaga extends Saga, TEvent>

Simple activity that executes a function.

InMemorySagaRepository<TSaga extends Saga>

In-memory implementation of SagaRepository.

NoOpActivity<TSaga extends Saga, TEvent>

Activity that does nothing. Useful as placeholder.

Saga

Base class for all saga instances.

SagaRepository<TSaga extends Saga>

Repository for storing and retrieving saga instances.

SagaStateMachine<TSaga extends Saga, TState>

MassTransit-style state machine for sagas.

Scheduler

Scheduler for delayed/timeout events.

TimeoutEvent

Timeout event marker.

TimeoutHandler<TSaga extends Saga, TState>

Timeout handler configuration.

Typedefs

EventCorrelator<TEvent> = String Function(TEvent event)

Event correlator function.

EventFilter<TEvent> = bool Function(TEvent event)

Predicate function to filter events.

FinalizeCallback<TSaga extends Saga> = void Function(TSaga saga)

Callback for saga finalization.

SagaAction<TSaga extends Saga, TEvent> = FutureOr<void> Function(BehaviorContext<TSaga, TEvent> context)

Async action executed during event handling.

SagaSetter<TSaga extends Saga, TEvent> = void Function(TSaga saga, TEvent event)

Callback types for saga operations. Function that sets saga properties from an event.

StateResolver<TSaga extends Saga, TEvent, TState> = TState Function(BehaviorContext<TSaga, TEvent> context)

Function that dynamically resolves the target state.

TransitionCallback<TSaga extends Saga, TState> = void Function(TSaga saga, TState from, TState to)

Callback for state transitions.