ESSM: Extremely Simple State Machines
A compile-time typestate state machine library for Rust. States are distinct types, transitions are trait implementations.
Design philosophy
ESSM provides safe state transitions via the typestate pattern. It does NOT provide a runtime state machine wrapper, event dispatch, or async drivers; those are the user's domain. ESSM handles one thing: making sure you can only transition between states that have a defined path, and that the transition hooks (invariants, guards, entry/exit checks) execute in the correct order.
Being extremely simple applies to being the usage which is intended to be very ergonomic and safe (wrong use is a compile error). As well as its implementation which may be surprisingly minimal.
Intended scope
ESSM is designed for small-to-medium sized state machines. Each transition pair requires a separate trait implementation, this is the cost of compile-time type safety.
Getting started
Add essm to your Cargo.toml, then import everything:
use *;
This brings in [State], [Transition], [TransitionResult], [TransitionInfallible],
[ErrorState], [FailedAt], [Primordial], [Terminated], [Infallible],
[InitialState], [InitialStateInfallible], [TerminalState],
[TerminalStateInfallible], and all other public types in one line.
Quick example
use *;
;
;
// Define allowed transitions
let idle = Idle;
let running: Running = idle.transition;
let idle: Idle = running.transition;
Bootstrap and termination
ESSM provides an optional bootstrap pattern via predefined [Primordial] and [Terminated]
pseudo states. These make creation and destruction symmetric with state transitions. Every
lifecycle event uses the same [Transition] pipeline.
Creating initial states
Implement Transition<YourState> for [Primordial] to define how your first
state is created, the [InitialState]/[InitialStateInfallible] traits are automatically
implemented for any transition from Primordial. They define convenient constructors:
#
# use *;
;
/// This is calling InitialStateInfallible::new()
let red = new;
For fallible construction, use a custom error type and impl InitialState<MyError> for MyState {}.
Terminating the machine
Implement Transition<Terminated> for the final state, then call .terminate():
#
# use *;
#
# ;
#
#
# let red = new;
// this is calling TerminalStateInfallible::terminate()
red.terminate;
Primordial and Terminated are optional
You are not required to use [Primordial] or [Terminated]. States can be
constructed directly (e.g., let idle = Idle;) and destroyed by simply letting
them go out of scope. This is perfectly valid and often simpler for small
state machines or ZST states.
However, when bypassing [Primordial] and [Terminated], you are
responsible for calling the lifecycle hooks manually:
state.enter(&ctx)— after constructing a statestate.invariant()— for validating a statestate.leave(&ctx)— before destroying a state
The [InitialState] and [TerminalState] traits automate this for you.
impl Drop on state types
Rust forbids partial moves out of Drop-implementing types (E0509), but
Transition::change must consume self and move data
into the next state. The most universal workaround is Option::take():
# use ;
# use Infallible;
#
#
#
core::mem::take() is an alternative for T: Default types
(no Option wrapper needed).
External crates: The derive_destructure2 crate provides proc macros
(#[derive(destructure)], #[derive(remove_trait_impls)]) that let you
destructure Drop types directly. The drop-with-owned-fields crate
offers a safe ManuallyDrop wrapper.
Unsafe escape hatch: For zero-cost repackaging, wrap the struct in
ManuallyDrop, ptr::read each
field, and never drop the wrapper.
Prefer [TerminalState] for structured teardown — or rely on Rust's automatic
drop for Drop-implementing fields (Vec, String, Box).
Caveats: Your
Dropimpl must handle fields that may have been taken. All patterns above are panic-safe: ifchange()panics, remaining fields hold valid defaults andDropcan still run without UB.
Data-carrying states
When a state carries data, move that data to the next state in change():
#
# use *;
Transition pipeline
Each transition() executes hooks in a fixed order:
1. self.invariant() : invariant check on source state integrity (no context)
2. self.leave(&ctx) : on-exit check, immutable context (&Ctx)
3. self.guard(&ctx) : pure predicate, immutable context (&Ctx)
4. let next = self.change(&mut ctx) : produce next state, mutable context (&mut Ctx)
5. next.enter(&ctx) : on-entry check, immutable context (&Ctx)
6. next.invariant() : invariant check on target state integrity (no context)
Call try_transition() for the zero-argument convenience path (context is ()).
Use try_transition_with() to pass a mutable context that threads
through the entire pipeline; hooks can read from it, and change() can mutate it.
#
# use *;
# ;
# ;
#
let idle = Idle;
let running: Running = idle.transition;
With a user-defined context — set the Transition's Ctx type:
#
# use *;
# ;
# ;
#
let idle = Idle;
let mut ctx = MyCtx ;
let running: Running = idle.transition_with;
Error recovery
In ESSM, errors are states. When a transition fails, it returns an
[ErrorState] which implements [State]. This means you can transition
FROM an error back to a valid state:
#
# use *;
#
# ;
#
#
# ;
#
#
// Recover: from any error back to Idle
let idle = Idle;
let working: Working = idle.try_transition.unwrap;
// Transition fails -- but the error IS a state
match working.try_transition
On failure, try_transition() returns an [ErrorState] that carries both the
original error and a [FailedAt] wrapping the state that survived.
Use [ErrorState::err_origin], [ErrorState::err_next], or [ErrorState::err]
to construct errors from your change() implementation.
Custom error types
You can define your own error types instead of using [Infallible]. For example,
the vending machine example defines a
VendError enum to signal insufficient credit:
#
# use *;
The HasCredit → Dispensing transition checks the credit balance and returns
VendError::NotEnoughCredit via [ErrorState::err_origin] if the balance is too low.
Because the origin state (HasCredit) is preserved in the [ErrorState], the caller
can recover by extracting it and continuing.
Recovery pattern
Since [ErrorState] implements [State], you can implement [Transition] from an
[ErrorState] back to a valid state. Recovery can restore the original state via the
[FailedAt::Origin] variant:
#
# use *;
#
# ;
# ;
// Recovery: ErrorState → HasCredit, restoring the original state
This pattern lets you attempt a fallible transition, recover from failure by restoring the original state, and retry with different inputs.
Customizing transitions
The pipeline is defined by [Transition]'s default methods. Override the hooks, not the pipeline:
| Hook | Trait | Purpose |
|---|---|---|
invariant() |
State |
invariant check on state integrity |
leave() |
State |
On-exit check, immutable context |
guard() |
Transition |
Pure predicate: is the transition allowed? |
change() |
Transition |
Produce the next state from the current one |
enter() |
State |
On-entry check, immutable context |
no_std
ESSM is #![no_std] by default. It uses only core::convert::Infallible.
Tests use std behind #[cfg(test)].
LLM usage
- Design and planning: Completely human. Architecture decisions, API design, trait boundaries, and the transition pipeline are human-authored.
- Implementation: Hybrid. Core traits and library code are human-authored with LLM assistance for boilerplate. All LLM-generated code undergoes close human review before merging.
- Documentation and examples: Partially LLM-generated, human-reviewed. README, doctests, and example programs are drafted with LLM assistance and verified by human review.