machin

TypeScript state machines with built-in persistence.

---

State machines are great for modeling complex workflows. But persisting them usually means gluing together a state machine library, a database layer, and custom sync logic.

machin handles both. Define your machine, pick a storage adapter, and your state transitions are automatically persisted. No manual saves, no sync bugs.

Features

- Awaitable by design
- Postgres, SQLite, and Redis adapters included
- Full TypeScript inference for states, events, and context

Installation

``bash
npm install machin
`

`bash
pnpm add machin
`

`bash
yarn add machin
`

Quick example

`typescript
import { machine } from "machin";
import { withDrizzlePg } from "machin/drizzle/pg";

type Context = { customerId: string | null };

// Define your machine
const orderMachine = machine().define({
initial: "pending",
states: {
pending: {
on: { confirm: { target: "processing" } },
},
processing: {
entry: async (ctx, event: { customerId: string }) => {
// Do async work here
return { ...ctx, customerId: event.customerId };
},
onSuccess: { target: "completed" },
onError: { target: "failed" },
},
completed: {},
failed: {
on: { retry: { target: "processing" } },
},
},
});

// Bind to storage
const boundMachine = withDrizzlePg(orderMachine, { db, table: ordersTable });

// Create an actor and send events
const actor = await boundMachine.createActor("order-123", { customerId: null });
await actor.send("confirm", { customerId: "customer-456" });

console.log(actor.state); // "completed"
`

State is persisted automatically after each transition.

Storage adapters

$3

`typescript
import { withDrizzlePg } from "machin/drizzle/pg";

const machine = withDrizzlePg(machineConfig, { db, table: myTable });
`

$3

`typescript
import { withDrizzleSQLite } from "machin/drizzle/sqlite";

const machine = withDrizzleSQLite(machineConfig, { db, table: myTable });
`

$3

`typescript
import { createClient } from "redis";
import { withRedis } from "machin/redis";

const client = await createClient({ url: "redis://localhost:6379" }).connect();
const machine = withRedis(machineConfig, { client });
`

Table schema

Your table needs these columns:

- id (text, primary key)
- state (text)
- createdAt (timestamp)
- updatedAt (timestamp)

Plus any columns for your context fields.

Type inference utilities

machin provides type inference utilities to extract types from your machine definitions. This is useful for typing database columns, API responses, or any other code that needs to work with machine states, events, or context.

`typescript
import { machine, InferStates, InferEvents, InferContext } from "machin";

const myMachine = machine<{ count: number }>().define({
initial: "idle",
states: {
idle: { on: { start: { target: "running" } } },
running: { on: { stop: { target: "idle" } } },
},
});

// Infer types from the machine
type States = InferStates; // "idle" | "running"
type Events = InferEvents; // "start" | "stop"
type Context = InferContext; // { count: number }
`

$3

The inference utilities are particularly useful for typing your database schema columns:

`typescript
import { pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
import { InferStates } from "machin";
import { orderMachine } from "./order-machine";

// Infer the state type from your machine
type OrderState = InferStates;
// → "pending" | "processing" | "completed" | "failed"

export const ordersTable = pgTable("orders", {
id: uuid().primaryKey(),
state: text().$type().notNull(),
createdAt: timestamp().notNull(),
updatedAt: timestamp().notNull(),
});
``

This ensures your database schema stays in sync with your machine definition - if you add or remove states from your machine, TypeScript will catch any mismatches.

License

MIT