Statekit
An immutable state transition validator for applications that model workflow as data.
Purpose
Many applications model workflows such as order processing, ticketing, or document approval.
When those workflows are configuration-driven or stored as data rather than hard-coded enums and match statements, validating legal transitions becomes repetitive.
Statekit provides an immutable state-machine definition that validates whether a transition is permitted.
Why use Statekit?
Statekit is intended for applications where states are not known at compile time.
Examples include:
- workflows loaded from configuration
- user-defined business processes
- state machines stored in a database
- plugins that define additional states
Status
Statekit is under active development.
Current release: v0.4.1
Statekit follows semantic versioning. As a pre-1.0 crate, its public API may evolve between minor releases.
Installation
Add this to your Cargo.toml:
[]
= "0.4.1"
Examples
Validation Example
There are two ways to use Statekit.
It can be used statelessly:
use ;
Or it can be used statefully:
use ;
Inspecting a Machine
Statekit exposes transition information so applications can build additional functionality around their state-machine definitions.
for source in machine.sources
targets_from() returns an empty iterator when a state has no outgoing transitions, including unknown states and states that appear only as transition targets.
for state in machine.states
Machine::transitions() exposes immutable Transition values with source and target state names.
for transition in machine.transitions
Iteration order is unspecified.
Terminality
Machine::is_terminal(state) determines whether a specified state has no outgoing transitions. MachineInstance::is_terminal() checks the instance's current state.
let machine = builder
.try_allow?
.build?;
let instance = machine.instance?;
assert!;
assert!;
Invariants
- State names must not be empty or consist entirely of whitespace.
- State names must not begin or end with Unicode whitespace.
- State names are case-sensitive.
- Self-transitions are rejected.
- Cycles between distinct states are permitted.
- A machine must contain at least one transition.
- Duplicate transitions between the same source and target are stored as a single logical transition.
- A transition attempt is rejected unless it is allowed by the machine definition.
- Instances must be initialized with an existing state.
- Instances can transition only to target states permitted by the machine definition.
Validation
try_allow() validates state names and transition relationships when they are added.
build() validates machine-level requirements, including that at least one transition exists.
validate_transition() and transition_to() validate transitions from the allowed list.
Features
Error Handling
All public Statekit errors implement std::error::Error.
Immutability
Once constructed, a machine cannot be modified.
This allows a machine definition to be reused safely without callers mutating its transition structure.
Concurrency Support
An instance can be created from the stateless machine definition to traverse the states permitted by the machine definition.
These instances share the machine definition and can work concurrently even if the machine definition handle has been dropped.
Synchronization of mutable instances is the responsibility of the host application.
Semantic Equality
Two machines are equal when their machine definitions are equal. Two instances are equal when they reference equal machine definitions and are on the same traversal state.
What It Is Not
Statekit is not:
- a process engine
- a policy engine
- a pathfinding library
- a workflow engine
Statekit can be used as a building block for these kinds of systems, but intentionally does not implement them.
Documentation
- Statekit Specification — domain definitions and invariants
- Migration Guide — guidance for upgrading between releases
- Changelog — notable changes by release
- Benchmarks — performance measurements and methodology for Statekit
Acknowledgements
Statekit is built with help from the Rust ecosystem and uses the following crates:
thiserror— ergonomic error definitionsproptest— property-based testingcriterion— benchmarkingtrybuild— UI testing
Thank you to the maintainers and contributors of these projects.
License
MIT