What this is

Crank lets you build a state machine as ordinary data. The machine is a struct, %Crank.Machine{}, which holds the current state, whatever data you've accumulated, and any side effects the last transition declared. To advance the machine, you call Crank.crank(machine, event). You get back a new struct. That's the whole interface.

There's no process involved, no message passing, no supervision tree. It's a function that takes a struct and an event and returns a new struct. You can call it in a test, in a LiveView, in an Oban worker, in a script. Anywhere you can call a function.

What you write

A Crank module is a set of functions. Crank calls them at the right moments — Elixir calls this pattern "callbacks." Define the function; the library calls it back when something happens. The functions are never called directly.

There are three callbacks:

init/1 — Crank calls this once when the machine is created. It returns the starting state and any initial data:

def init(opts) do
  {:ok, :idle, %{price: opts[:price] || 100, balance: 0}}
end

handle/3 — Crank calls this every time an event arrives, passing the event, the current state, and the accumulated data. It returns the next state:

def handle({:coin, amount}, :idle, data) do
  {:next_state, :accepting, %{data | balance: amount}}
end

def handle({:coin, amount}, :accepting, data) do
  {:next_state, :accepting, %{data | balance: data.balance + amount}}
end

Each function clause is one transition. Read it like a sentence: "When a coin arrives and we're idle, move to accepting and record the amount." The set of all clauses is the complete specification of the state machine. There's nothing else to configure, no tables to fill in, no DSL to learn.

on_enter/3 — Optional. Crank calls this after a state change, passing the old state, the new state, and the data. Useful for recording that a transition happened — a timestamp, a counter, a log entry — without cluttering the transition logic itself.

That's everything. The rest is pattern matching.

The struct

After each crank/2 call, you get back a %Crank.Machine{} with five fields:

• module — the callback module (so the struct knows which functions to call)
• state — the current state (an atom, a struct, a tuple — any Elixir term)
• data — whatever your init/1 and handle/3 have accumulated
• effects — side effects from the last transition, stored as data (never executed)
• status — :running or {:stopped, reason}

The effects field is important. When handle/3 returns actions like timeouts or replies, the pure core doesn't execute them. It stores them as a list in effects. They can be inspected, asserted on in tests, or ignored. They're just data until something decides to act on them.

Each crank/2 call replaces effects — they don't pile up from previous transitions.

Running it as a process

Everything above works without a process. But sometimes you need one. Maybe you want a timeout that fires after 30 seconds of inactivity. Maybe you want the machine to live in a supervision tree so it restarts on failure. Maybe another process needs to send it a message and get a reply.

Crank.Server handles this. It takes the same module — the exact same one, unchanged — and runs the functions inside OTP's gen_statem:

{:ok, pid} = Crank.Server.start_link(MyApp.VendingMachine, price: 75)
Crank.Server.cast(pid, {:coin, 25})

The logic is the same. What changes is the plumbing around it: who calls the functions, and what happens to the effects afterward. In pure mode, effects are stored as data. In process mode, gen_statem executes them — timeouts fire, replies get sent, telemetry events are emitted.

There isn't one module for pure and another for process. There is one module. It works in both contexts because it's just functions.

When you need handle_event/4

handle/3 is enough for most logic. But when a machine runs as a process, events arrive in different ways. A cast is asynchronous — fire and forget. A call is synchronous — the caller is waiting for a reply. A timeout fires because time passed. A raw message arrives from another process.

Sometimes the function needs to know which of these happened. That's what handle_event/4 is for. It's handle/3 with one extra argument — the event type — prepended:

def handle_event({:call, from}, :status, state, data) do
  {:keep_state, data, [{:reply, from, state}]}
end

The event types are:

• :internal — programmatic events (this is what pure crank/2 always uses)
• :cast — someone called Crank.Server.cast(pid, event)
• {:call, from} — someone called Crank.Server.call(pid, event) and is waiting
• :info — a raw Erlang message from another process
• :timeout, :state_timeout, {:timeout, name} — a timer fired

If a module defines handle_event/4, Crank uses it instead of handle/3. If a module needs both — handle/3 for business logic and handle_event/4 for replies — the specific clauses go in handle_event/4, and a catch-all delegates everything else:

def handle_event({:call, from}, :status, state, data) do
  {:keep_state, data, [{:reply, from, state}]}
end

# Everything that isn't a call goes to handle/3
def handle_event(_event_type, event, state, data) do
  handle(event, state, data)
end

What you return

Every handle/3 (or handle_event/4) clause returns a tuple that tells Crank what should happen next. The most common ones:

• {:next_state, new_state, new_data} — move to a different state
• {:next_state, new_state, new_data, actions} — move and declare side effects
• {:keep_state, new_data} — stay in the same state, update the data
• {:stop, reason, new_data} — shut down the machine

There are a few more ({:keep_state, new_data, actions}, :keep_state_and_data, {:keep_state_and_data, actions}). These match :gen_statem's return values exactly. {:next_state, ...} and {:keep_state, ...} cover nearly everything.

The actions list is where side effects are declared: timeouts, replies, internal events. In pure mode these get stored in machine.effects. In process mode gen_statem executes them.

Example

A door with three states — locked, unlocked, opened — and four transitions:

defmodule MyApp.Door do
  use Crank

  @impl true
  def init(_opts), do: {:ok, :locked, %{}}

  @impl true
  def handle(:unlock, :locked, data), do: {:next_state, :unlocked, data}
  def handle(:lock, :unlocked, data), do: {:next_state, :locked, data}
  def handle(:open, :unlocked, data), do: {:next_state, :opened, data}
  def handle(:close, :opened, data), do: {:next_state, :unlocked, data}
end

Use it:

machine =
  MyApp.Door
  |> Crank.new()
  |> Crank.crank(:unlock)
  |> Crank.crank(:open)

machine.state
#=> :opened

Four clauses. Four transitions. That's the whole machine. If an event arrives that no clause matches — say, :open when the door is :locked — Elixir raises a FunctionClauseError. That's deliberate. A state machine that silently ignores unexpected events is hiding bugs.