StatefulSagaBuilder

class StatefulSagaBuilder<C, R, S : Any>(initialState: S)

DSL builder for creating stateful saga executors with typed state management.

StatefulSagaBuilder provides a fluent API for defining saga steps that can share typed state across the execution. This enables "smart compensation" where compensation logic can make decisions based on execution progress from later steps.

Usage Example

data class PaymentState(
val paymentAmount: Long = 0L,
val escrowCaptured: Boolean = false
)

val saga = sagaExecutor<OrderContext, OrderResult>(PaymentState()) {
step("take-payment") { context ->
val payment = paymentService.takePayment(context.amount)
updateState { it.copy(paymentAmount = payment.amount) }
OrderResult(payment.id)
}
compensate {
// Smart compensation using state from later steps
if (state.escrowCaptured) {
paymentService.refund(result.paymentId)
} else {
paymentService.returnEscrow()
}
}

step("capture-escrow") { context ->
paymentService.captureEscrow()
updateState { it.copy(escrowCaptured = true) }
result!! // Pass through previous result
}
compensate {
paymentService.refund(state.paymentAmount)
}
}

Parameters

C

The type of context passed to saga steps

R

The type of result produced by saga steps

S

The type of shared saga state (must be non-null)

Constructors

Link copied to clipboard
constructor(initialState: S)

Properties

Link copied to clipboard

Starts the first saga step with "first do 'name' with { ... }" syntax.

Link copied to clipboard

Alternative: starts any saga step (not necessarily first).

Link copied to clipboard

Starts monitor configuration with "watching" keyword.

Functions

Link copied to clipboard

Marks the last step as idempotent using simple syntax.

Link copied to clipboard

Marks the last step as non-idempotent.

Link copied to clipboard

Build the stateful saga executor.

Link copied to clipboard
fun compensate(compensation: suspend CompensationScope<R, S>.() -> Unit): StatefulSagaBuilder<C, R, S>

Define compensation logic for the current step.

Link copied to clipboard
infix fun <C, R, S : Any> StatefulSagaBuilder<C, R, S>.compensateWith(compensation: suspend CompensationScope<R, S>.() -> Unit): StatefulSagaBuilder<C, R, S>

Adds compensation to the last defined step using simple syntax.

Link copied to clipboard
fun idempotent(value: Boolean = true): StatefulSagaBuilder<C, R, S>

Mark the current step as idempotent (safe to retry).

Link copied to clipboard

Add a monitor to observe saga events.

fun monitor(handler: suspend (SagaEvent) -> Unit): StatefulSagaBuilder<C, R, S>

Add a monitor using a lambda.

Link copied to clipboard
infix fun <C, R, S : Any> StatefulSagaBuilder<C, R, S>.monitoring(handler: (SagaEvent) -> Unit)

Adds a saga monitor using "monitoring with" syntax.

Link copied to clipboard
infix fun <C, R, S : Any> StatefulSagaBuilder<C, R, S>.monitorWith(monitor: SagaMonitor)

Adds a saga monitor instance.

Link copied to clipboard

Set retry policy for current step.

Link copied to clipboard
fun step(step: TypedValue, timeout: Duration? = null, forward: suspend StatefulStepScope<R, S>.(C) -> StepOutcome<R>): StatefulSagaBuilder<C, R, S>

Define a saga step with forward logic using explicit outcome control.

fun step(name: String, timeout: Duration? = null, forward: suspend StatefulStepScope<R, S>.(C) -> StepOutcome<R>): StatefulSagaBuilder<C, R, S>

Define a saga step with string name (convenience overload).

Link copied to clipboard

Alternative syntax: "step 'name' does { ... }"

Link copied to clipboard

Set timeout for current step.