scamper

Scamper — Type-safe finite state machine library for Gleam.

Generic over Machine(state, context, event). Build configs with the pipeline operator, then create machines and transition them with events.

let cfg =
  config.new(timestamp_fn)
  |> config.add_transition(from: Idle, on: Start, to: Running)
  |> config.add_transition(from: Running, on: Complete, to: Done)
  |> config.set_final_states([Done])

let machine = scamper.new(cfg, Idle, initial_context)
let assert Ok(machine) = scamper.transition(machine, Start)

Types

Machine

opaque </>

An opaque finite state machine, generic over state, context, and event types.

pub opaque type Machine(state, context, event)

Values

available_events

</>

pub fn available_events(
  machine: Machine(state, context, event),
) -> List(event)

Get the list of events that have at least one matching transition rule from the current state. Does not evaluate guards.

can_transition

</>

pub fn can_transition(
  machine: Machine(state, context, event),
  event: event,
) -> Bool

Check whether a transition is possible for the given event without actually executing it. Does not run callbacks or invariants.

created_at

</>

pub fn created_at(machine: Machine(state, context, event)) -> Int

Get the timestamp when the machine was created.

current_context

</>

pub fn current_context(
  machine: Machine(state, context, event),
) -> context

Get the current context of the machine.

current_state

</>

pub fn current_state(
  machine: Machine(state, context, event),
) -> state

Get the current state of the machine.

elapsed

</>

pub fn elapsed(machine: Machine(state, context, event)) -> Int

Get milliseconds elapsed since the last transition (or since creation if no transitions have occurred).

entered_at

</>

pub fn entered_at(machine: Machine(state, context, event)) -> Int

Get the timestamp when the current state was entered.

get_config

</>

pub fn get_config(
  machine: Machine(state, context, event),
) -> config.Config(state, context, event)

Get the machine’s configuration.

history

</>

pub fn history(
  machine: Machine(state, context, event),
) -> List(history.TransitionRecord(state, event, context))

Get the full transition history (newest first).

is_final

</>

pub fn is_final(machine: Machine(state, context, event)) -> Bool

Check whether the machine is in a final (terminal) state.

new

</>

pub fn new(
  config: config.Config(state, context, event),
  initial_state: state,
  context: context,
) -> Machine(state, context, event)

Create a new state machine with the given configuration, initial state, and context.

restore

</>

pub fn restore(
  config: config.Config(state, context, event),
  state: state,
  context: context,
  history_records: List(
    history.TransitionRecord(state, event, context),
  ),
  created_at: Int,
  entered_at: Int,
) -> Machine(state, context, event)

Restore a machine from serialized components. Used by the serialization module to reconstruct a machine.

transition

</>

pub fn transition(
  machine: Machine(state, context, event),
  event: event,
) -> Result(
  Machine(state, context, event),
  error.TransitionError(state, event),
)

Attempt to transition the machine by processing an event. Returns a new machine on success, or a TransitionError on failure. The input machine is never modified.