RoomKitBackend
BookingStateMachine
Validate and query booking state transitions
Overview
BookingStateMachine is an injectable service that enforces the booking lifecycle. It validates state transitions, reports allowed targets for a given state, and identifies terminal states.
import { BookingStateMachine } from '@roomkit/nestjs';State Diagram
requested ──→ confirmed ──→ in_progress ──→ completed
│ │ │
└──────────────┴──────────────┴──→ cancelledTransition Table
| From | Allowed Targets |
|---|---|
requested | confirmed, cancelled |
confirmed | in_progress, cancelled |
in_progress | completed, cancelled |
completed | (terminal) |
cancelled | (terminal) |
Methods
canTransition
Check whether a transition from one status to another is allowed.
canTransition(from: BookingStatus, to: BookingStatus): boolean| Parameter | Type | Description |
|---|---|---|
from | BookingStatus | The current booking status |
to | BookingStatus | The target booking status |
const allowed = stateMachine.canTransition('requested', 'confirmed');
// true
const blocked = stateMachine.canTransition('completed', 'in_progress');
// falsevalidateTransition
Validate a transition and throw if it is not allowed. Use this when you need to enforce transitions strictly.
validateTransition(from: BookingStatus, to: BookingStatus): void| Parameter | Type | Description |
|---|---|---|
from | BookingStatus | The current booking status |
to | BookingStatus | The target booking status |
stateMachine.validateTransition('requested', 'confirmed');
// No error thrown
stateMachine.validateTransition('completed', 'requested');
// Throws InvalidStateTransitionErrorThrows InvalidStateTransitionError with context { currentStatus, attemptedStatus, allowedTransitions }.
getAllowedTransitions
Get all valid target states for a given status.
getAllowedTransitions(from: BookingStatus): BookingStatus[]| Parameter | Type | Description |
|---|---|---|
from | BookingStatus | The current booking status |
const targets = stateMachine.getAllowedTransitions('confirmed');
// ['in_progress', 'cancelled']
const noTargets = stateMachine.getAllowedTransitions('completed');
// []isTerminal
Check whether a status is terminal (no further transitions allowed). Returns true for completed and cancelled.
isTerminal(status: BookingStatus): boolean| Parameter | Type | Description |
|---|---|---|
status | BookingStatus | The booking status to check |
stateMachine.isTerminal('completed'); // true
stateMachine.isTerminal('cancelled'); // true
stateMachine.isTerminal('confirmed'); // false