sagaExecutor

Factory function for creating sagas with DSL.

This function provides a convenient way to create saga executors using Kotlin's DSL syntax.

Usage Example

val saga = sagaExecutor<OrderContext, OrderResult> {
    step("reserve-inventory") { context ->
        val reservationId = inventoryService.reserve(context.items)  // Can be suspend
        ReservationResult(reservationId)
    }
    compensate { result ->
        inventoryService.release(result.reservationId)  // Can be suspend
    }

    step("charge-payment") { context ->
        val transactionId = paymentService.charge(context.amount)  // Can be suspend
        PaymentResult(transactionId)
    }
    compensate { result ->
        paymentService.refund(result.transactionId)  // Can be suspend
    }
}

// Execute within a coroutine
runBlocking {
    val result = saga.execute(OrderContext(items = listOf("item1"), amount = 99.99))
    when (result) {
        is SagaResult.Completed -> println("Success: ${result.value}")
        is SagaResult.Aborted -> println("Aborted: ${result.error.message}")
        is SagaResult.CompensationFailure -> println("Critical failure")
    }
}

Parameters

Factory function for creating journal-aware stateless saga executors with deferred RunId.

Unlike the sagaExecutor(journal, runId, ...) overload, this factory does not require a RunId at build time. The JournalInterceptor is constructed fresh on each call to SagaExecutor.execute(context, runId, ...), allowing the same executor instance to be reused across multiple saga runs with different identifiers.

When decodeEffectPayload is provided, F004 effect-key short-circuiting is active: before each step that declares an effectKey, the executor scans the journal for a prior ca.acendas.kstate.saga.journal.EntryPhase.Effect entry with a matching key and step name. If found, the step's forward lambda is skipped and the decoded result is used instead.

F004 collision detection is always active when a journal is present — it does not require a payload decoder.

Parameters

Factory function for creating stateful sagas with typed state management.

This overload of sagaExecutor creates a saga with shared state that is accessible in both forward actions and compensation logic. The state type is inferred from the initialState parameter.

Usage Example

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

val saga = sagaExecutor<Cart, Order>(PaymentState()) {
    first `do` "take-payment" with { cart ->
        updateState { it.copy(paymentAmount = payment.amount) }
        createOrder(cart)
    } and undo {
        if (state.escrowCaptured) refund() else returnEscrow()
    }

    then `do` "capture-escrow" with { cart ->
        cashManager.captureEscrow()
        updateState { it.copy(escrowCaptured = true) }
        result!!
    }
}

Parameters

Factory function for creating journal-aware stateful saga executors with deferred RunId.

Unlike the sagaExecutor(initialState, journal, runId, ...) overload, this factory does not require a RunId at build time. The JournalInterceptor is constructed fresh on each call to StatefulSagaExecutor.execute(context, runId, ...), allowing the same executor instance to be reused across multiple saga runs with different identifiers.

When decodeEffectPayload is provided, F004 effect-key short-circuiting is active: before each step that declares an effectKey, the executor scans the journal for a prior ca.acendas.kstate.saga.journal.EntryPhase.Effect entry with a matching key and step name. If found, the step's forward lambda is skipped and the decoded result is used instead.

Parameters