stateledger docs

stateledger is a database-backed finite state machine for Node.js and TypeScript. It persists every transition to your database, guards against concurrent races with Postgres advisory locks, keeps a full audit trail of who moved each entity between states, and lets you query historical state at any past timestamp.

It is intentionally boring | no cryptography, no consensus, no P2P. Just correct, auditable transitions for payments, orders, subscriptions, and any backend where you need to know exactly what happened, in what order.

If you’re new, read them in order. Each page builds on the previous one.

• Getting started
  Install + first transition
• Prisma adapter
  @stateledger/prisma
• Drizzle adapter
  @stateledger/drizzle
• Memory adapter
  @stateledger/memory (for tests)
• Outbox helper
  @stateledger/outbox — atomic side effects
• Guards & callbacks
  Pre/post transition hooks
• Time-travel queries
  stateAt() API
• Advisory locks
  Concurrency model
• Errors
  Typed error reference
• Testing
  Test patterns with the memory adapter
• Cookbook
  Worked examples per use case
• Migrating
  Move an existing status column onto stateledger
• API reference
  Every method and type

stateledger is split into small, focused packages so you install only what you use.

• @stateledger/core — ORM-agnostic engine and adapter interface. Required.
• @stateledger/prisma — Prisma storage adapter for Postgres.
• @stateledger/drizzle — Drizzle storage adapter for Postgres.
• @stateledger/memory — In-memory adapter for tests and prototypes.
• @stateledger/outbox — Transactional outbox for atomic side effects (Stripe, email, Kafka): enqueue() inside your transition tx, a background createWorker() delivers with retries + DLQ.

• • Node.js 18 or newer
• • TypeScript 5.0+ (optional but recommended)
• • PostgreSQL 12+ (for the Prisma and Drizzle adapters)