Skip to content

State Machine

Enforced entity state transitions.

  • defineTransitions + guardTransition
  • Each transition as its own domain event for a readable audit trail

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.

Terminal window
cd samples/recipes/state-machine
bun test

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