State Machine
Enforced entity state transitions.
What it shows
Section titled “What it shows”defineTransitions+guardTransition- Each transition as its own domain event for a readable audit trail
Source
Section titled “Source”Feature entry point: src/feature.ts.
Needs the Postgres from the repo root’s docker-compose.yml (docker compose up -d); TEST_DATABASE_URL defaults to postgresql://kumiko:kumiko@localhost:15432/kumiko_test.
cd samples/recipes/state-machinebun testSource code
Section titled “Source code”The feature entry point — embedded straight from the source file, so the code here is exactly what runs. Multi-file samples keep their remaining files next to it on GitHub (link below):
// State Machine Sample// Shows: defineTransitions, guardTransition (manual + auto), state machine via// event-sourced status changes. Each transition is its own domain event so the// audit log reads like the workflow ("invoice-sent", "invoice-cancelled"), not// like a SQL changelog ("status updated to sent").//// Workflow:// draft → sent → paid (happy path)// → cancelled (abort)// cancelled → draft (reopen)//// Roles:// Admin — create, send, cancel, reopen, updateStatus, forceStatus// Accounting — markPaid//// Files:// entities/invoice.ts — entity + table + transition config// events.ts — single source of truth for event names// reducer.ts — derives status + amount from the event stream// handlers/_helpers.ts — shared transitionHandler + successResult// handlers/create.ts — invoice:create (uses executor)// handlers/transitions.ts — the six state-change handlers
import { defineFeature, setFields, typedPayload } from "@cosmicdrift/kumiko-framework/engine";import { invoiceEntity, invoiceTable } from "./entities/invoice";import { emptyEventPayload, eventName, INVOICE_EVENTS, type InvoiceEvents, statusForcedPayload,} from "./events";import { invoiceCreate } from "./handlers/create";import { createInvoiceTransitionHandlers } from "./handlers/transitions";
export { invoiceEntity } from "./entities/invoice";
export const stateMachineFeature = defineFeature("billing", (r) => { r.entity(invoiceEntity);
// Domain events — one per intent. Names live in events.ts so the reducer // and the projection stay in sync. The auto "invoice.created" event from // the executor's create-path covers the initial insert, so we only declare // the state-change events here. const events: InvoiceEvents = { sent: r.defineEvent(INVOICE_EVENTS.sent, emptyEventPayload, { piiFields: "none" }), markedPaid: r.defineEvent(INVOICE_EVENTS.markedPaid, emptyEventPayload, { piiFields: "none" }), cancelled: r.defineEvent(INVOICE_EVENTS.cancelled, emptyEventPayload, { piiFields: "none" }), reopened: r.defineEvent(INVOICE_EVENTS.reopened, emptyEventPayload, { piiFields: "none" }), statusForced: r.defineEvent(INVOICE_EVENTS.statusForced, statusForcedPayload, { piiFields: "none", }), };
// The aggregate table (sample_sm_invoices) is INSERTed by the executor on // invoice:create. State-change events update the same row via this inline // projection — keeps reads consistent with writes inside the same TX. // setFields collapses "UPDATE <table> SET <cols> WHERE id = aggregateId" // into a one-liner. Pass a literal for fixed-target events, a reducer fn // for events that carry the new value in their payload. r.projection({ name: "invoice-status", source: "invoice", table: invoiceTable, apply: { [eventName(INVOICE_EVENTS.sent)]: setFields(invoiceTable, { status: "sent" }), [eventName(INVOICE_EVENTS.markedPaid)]: setFields(invoiceTable, { status: "paid" }), [eventName(INVOICE_EVENTS.cancelled)]: setFields(invoiceTable, { status: "cancelled" }), [eventName(INVOICE_EVENTS.reopened)]: setFields(invoiceTable, { status: "draft" }), [eventName(INVOICE_EVENTS.statusForced)]: setFields(invoiceTable, (e) => ({ status: typedPayload(e, events.statusForced).newStatus, })), }, });
const transitions = createInvoiceTransitionHandlers(events); r.writeHandler(invoiceCreate); r.writeHandler(transitions.invoiceSend); r.writeHandler(transitions.invoiceMarkPaid); r.writeHandler(transitions.invoiceCancel); r.writeHandler(transitions.invoiceReopen); r.writeHandler(transitions.invoiceUpdateStatus); r.writeHandler(transitions.invoiceForceStatus);});📄 On GitHub: samples/recipes/state-machine/src/feature.ts