Finite State Machines (FSM) with Signals
In complex multi-step workflows—such as checkout wizards, payment gateways, document verification, or multi-stage uploads—managing UI state through scattered boolean flags (isLoading, isVerifying, isPaid, hasError) inevitably leads to impossible states (for example, showing both a loading spinner and a payment confirmation banner simultaneously).
The Finite State Machine (FSM) pattern eliminates these bugs by guaranteeing that the system occupies strictly one valid state at any point in time, and transitions only occur in response to explicit events from permitted states.
Why FSM + @pravosleva/reactive-engine Needs Zero External Libraries
- TypeScript Discriminated Unions: Machine states are modeled as a strict union type discriminated by
statusand stored inside a singlethis.engine.signal<PaymentState>(). TypeScript automatically narrows context properties for every step. - Deterministic event dispatcher
send(event): All transitions are encapsulated inside anAbstractService. If a user double-clicks "Pay Now", the machine safely ignores the duplicateSTART_PAYMENTevent because that transition is disallowed while in'processing'. - Reactive entry/exit side effects (
effect): Anengine.effect()observesstatustransitions, automatically launching async operations with anAbortControlleron state entry and aborting in-flight requests upon state exit (such as clicking "Cancel").
Practical Example: Payment Gateway (PaymentMachineService.ts)
1. States, Events & Service Setup
typescript
import { AbstractService } from '@pravosleva/reactive-engine'
// 1. All possible machine states (strict Discriminated Union)
export type PaymentState =
| { status: 'idle' }
| { status: 'validating'; amount: number }
| { status: 'processing'; amount: number; attempt: number }
| { status: 'succeeded'; transactionId: string; amount: number }
| { status: 'failed'; reason: string; amount: number; attempt: number }
// 2. All valid events capable of triggering state transitions
export type PaymentEvent =
| { type: 'START_PAYMENT'; amount: number }
| { type: 'VALIDATION_PASSED' }
| { type: 'VALIDATION_FAILED'; reason: string }
| { type: 'PAYMENT_SUCCEEDED'; transactionId: string }
| { type: 'PAYMENT_FAILED'; reason: string }
| { type: 'RETRY' }
| { type: 'CANCEL' }
| { type: 'RESET' }
export class PaymentMachineService extends AbstractService {
// Single source of truth for the current FSM state
public state = this.engine.signal<PaymentState>({ status: 'idle' }, 'payment:fsmState')
// Derived computed flags for ergonomic UI bindings
public isBusy = this.engine.computed(() => {
const s = this.state.value.status
return s === 'validating' || s === 'processing'
}, 'payment:isBusy')
public canRetry = this.engine.computed(() => {
const current = this.state.value
return current.status === 'failed' && current.attempt < 3
}, 'payment:canRetry')
private activeController: AbortController | null = null
// Reactive effect executes side effects on state entry
// and aborts in-flight requests upon state exit
private stopSideEffects = this.engine.effect(() => {
const current = this.state.value
this.abortInFlight()
if (current.status === 'validating') {
const controller = new AbortController()
this.activeController = controller
void this.runValidation(current.amount, controller.signal)
return
}
if (current.status === 'processing') {
const controller = new AbortController()
this.activeController = controller
void this.runCharge(current.amount, current.attempt, controller.signal)
}
}, 'payment:fsmSideEffects')
/**
* Single entry point for transitioning the machine state.
* Disallowed transitions for the current status are deterministically ignored.
*/
public send(event: PaymentEvent): boolean {
const current = this.state.value
switch (current.status) {
case 'idle':
if (event.type === 'START_PAYMENT' && event.amount > 0) {
this.state.value = { status: 'validating', amount: event.amount }
return true
}
return false
case 'validating':
if (event.type === 'VALIDATION_PASSED') {
this.state.value = {
status: 'processing',
amount: current.amount,
attempt: 1,
}
return true
}
if (event.type === 'VALIDATION_FAILED') {
this.state.value = {
status: 'failed',
reason: event.reason,
amount: current.amount,
attempt: 1,
}
return true
}
if (event.type === 'CANCEL') {
this.state.value = { status: 'idle' }
return true
}
return false
case 'processing':
if (event.type === 'PAYMENT_SUCCEEDED') {
this.state.value = {
status: 'succeeded',
transactionId: event.transactionId,
amount: current.amount,
}
return true
}
if (event.type === 'PAYMENT_FAILED') {
this.state.value = {
status: 'failed',
reason: event.reason,
amount: current.amount,
attempt: current.attempt,
}
return true
}
if (event.type === 'CANCEL') {
this.state.value = { status: 'idle' }
return true
}
return false
case 'failed':
if (event.type === 'RETRY' && current.attempt < 3) {
this.state.value = {
status: 'processing',
amount: current.amount,
attempt: current.attempt + 1,
}
return true
}
if (event.type === 'RESET') {
this.state.value = { status: 'idle' }
return true
}
return false
case 'succeeded':
if (event.type === 'RESET') {
this.state.value = { status: 'idle' }
return true
}
return false
}
}
private async runValidation(amount: number, signal: AbortSignal) {
try {
const res = await fetch('/api/payments/validate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ amount }),
signal,
})
if (!res.ok) {
this.send({ type: 'VALIDATION_FAILED', reason: 'Transaction limit exceeded' })
return
}
this.send({ type: 'VALIDATION_PASSED' })
} catch (err: unknown) {
if (err instanceof DOMException && err.name === 'AbortError') return
this.send({ type: 'VALIDATION_FAILED', reason: 'Limit validation network error' })
}
}
private async runCharge(amount: number, attempt: number, signal: AbortSignal) {
try {
const res = await fetch('/api/payments/charge', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ amount, attempt }),
signal,
})
if (!res.ok) {
this.send({ type: 'PAYMENT_FAILED', reason: `Gateway error (${res.status})` })
return
}
const payload: unknown = await res.json()
const txId =
typeof payload === 'object' &&
payload !== null &&
'transactionId' in payload &&
typeof payload.transactionId === 'string'
? payload.transactionId
: 'tx_unknown'
this.send({ type: 'PAYMENT_SUCCEEDED', transactionId: txId })
} catch (err: unknown) {
if (err instanceof DOMException && err.name === 'AbortError') return
this.send({ type: 'PAYMENT_FAILED', reason: 'Network error while charging card' })
}
}
private abortInFlight() {
if (this.activeController) {
this.activeController.abort()
this.activeController = null
}
}
public dispose() {
this.stopSideEffects()
this.abortInFlight()
}
}2. Usage in Vanilla JS or UI Layer
typescript
import { ReactiveEngine } from '@pravosleva/reactive-engine'
import { PaymentMachineService } from './PaymentMachineService.js'
const engine = new ReactiveEngine()
const payment = engine.inject(PaymentMachineService)
// Observe machine state transitions: TypeScript narrows context properties per case
engine.effect(() => {
const current = payment.state.value
switch (current.status) {
case 'idle':
console.log('Waiting for payment amount')
break
case 'validating':
console.log(`Validating transaction limits for ${current.amount}...`)
break
case 'processing':
console.log(`Charging ${current.amount} (attempt #${current.attempt})...`)
break
case 'succeeded':
console.log(`Payment succeeded! Transaction ID: ${current.transactionId}`)
break
case 'failed':
console.warn(`Error: ${current.reason}. Retry available: ${payment.canRetry.value}`)
break
}
})
// 1. Start the payment flow
payment.send({ type: 'START_PAYMENT', amount: 4990 })
// 2. Duplicate clicks while processing are safely ignored (returns false)
payment.send({ type: 'START_PAYMENT', amount: 4990 })
// 3. The user can cancel mid-flight during validation or charging:
// the active fetch is immediately cancelled via AbortController
// payment.send({ type: 'CANCEL' })FSM Design Best Practices
- Co-locate context inside union variants instead of separate signals: Properties like
transactionIdonly make sense in'succeeded', whilereasononly applies to'failed'. Keeping them inside a singlesignal<PaymentState>prevents stale context fields across transitions. - Use exhaustive
switch (current.status)withoutdefault: In TypeScript, an exhaustiveswitchover the discriminant ensures at compile time that adding a new status forces you to handle every valid transition. - Integrating external state machine libraries (e.g., XState v5): If your project already uses XState, encapsulate
createActor(machine)inside anAbstractServiceand mirror snapshots viaactor.subscribe((snapshot) => { this.snapshotSignal.value = snapshot })so downstreamcomputedandeffectnodes react seamlessly.