statekit 0.1.0

An immutable state-machine for validating predefined transitions.
Documentation

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

Stable API for v0.1.

Future releases will expand functionality while maintaining semantic versioning.

Installation

[dependencies]
statekit = "0.1"

Example

use statekit::{Machine, StateError};

fn main() -> Result<(), StateError> {
    let machine = Machine::builder()
        .allow("queued", "running")
        .allow("running", "completed")
        .allow("running", "failed")
        .build()?;

    let result = machine.validate_transition("queued", "running");

    assert!(result.is_ok());

    Ok(())
}

Invariants

  • Validation occurs when build() is called.
  • State names must not be empty.
  • State names are case-sensitive.
  • Self-transitions are rejected.
  • A machine must define at least one transition.

Features

Error

All public errors implement std::error::Error

Immutabilitu

Once constructed, a machine cannot be modified.

This makes it inexpensive to share safely between threads and application components.

What it is Not

Statekit is not:

  • a process engine
  • a policy engine
  • pathfinding code
  • workflow engine

It can be used as a building block for these kinds of systems, but it intentionally does not implement them.

License

MIT