Glossary¶
One term, short definition, tiny code when the spelling matters. See points at the teaching page.
Core terms¶
machine¶
A statechart registered as an event handler. It models a feature lifecycle as named states and transitions.
See The table.
transition table¶
The map that defines a machine: :initial, :data, optional :guards,
optional :actions, optional :schemas, and :states or :regions.
See The idea.
snapshot¶
The machine's live value.
It lives in runtime-db. Read it with
[:rf/machine id]:
nil until the first event on a singleton. A spawned actor has a
snapshot from the moment it is spawned. :state is a keyword, a path
vector, or a region map.
See The snapshot.
:data¶
A machine's private working memory. Guards and actions read it. Actions update
it by returning {:data …}. Merged, not replaced — {:data {:error nil}} sets
that key to nil.
See The idea.
state¶
One named mode of a machine, such as :idle, :submitting, or :authed.
trigger¶
The thing that can fire a transition. A dispatched trigger is the inner
vector, such as [:auth.login/submit credentials]. A timer expiry (:after)
and an eventless :always step are triggers too.
A guard is not a trigger. The runtime samples guards when a trigger runs, and never between, so a guard that turns true on its own moves nothing.
Do not call the inner vector an "event." In re-frame2, the event is the outer vector whose id is the machine id.
See Native to re-frame2.
transition¶
A move from one state to another, usually in response to a trigger under a
state's :on map.
guard¶
A predicate that gates a transition.
Defined in :guards, or written inline for a one-liner. A three-attempt
policy is (< (:attempts data) 2) — the guard sees the count before the
action increments it.
See Guards.
action¶
A function that returns {:data … :fx …}. It may update the machine's private
data or describe effects. It never writes app-db (:rf.error/machine-action-wrote-db).
See Actions.
action effect map¶
The return value from an action.
:data is merged into the machine data. :fx is the ordinary effects vector.
See The effect map.
State structure¶
compound state¶
A state with nested :states and its own :initial. The snapshot's :state
becomes a vector path, such as [:authenticated :settings].
See Hierarchical states.
parallel machine¶
A machine with :type :parallel and :regions. All regions are active at the
same time. The snapshot's :state is a map of region name to region state.
See Parallel regions.
region¶
One orthogonal axis of a parallel machine. Each region has its own :initial
and :states, but all regions share one machine :data.
See Parallel regions.
final state¶
A leaf marked :final? true. At the root, it ends and destroys the machine.
Inside a compound state, it marks that sub-flow as done. A resting end-screen
(:authed) omits :final?.
See Final states; nested finals.
history state¶
A :type :history pseudo-state inside a compound state. Target it to re-enter
the compound where it last exited.
See History states.
state tag¶
A semantic label on a state.
Read it with [:rf.machine/has-tag? id tag]:
See Tags.
Transition forms¶
candidate vector¶
A first-match-wins list of transitions.
:on {:auth.login/failure [{:guard :under-retry-limit :target :error-shown
:action :record-error}
{:target :locked-out :action :record-error}]}
self-transition¶
A transition that stays in the same state.
Targetless self-transitions run an action without exit/entry. :reenter? true
forces exit and re-entry.
See Self-transitions and wildcards.
wildcard transition¶
An :on key that handles a family of events:
Resolution is exact id, namespace wildcard, then total wildcard.
See Self-transitions and wildcards.
forbidden transition¶
A present no-op transition, such as {:on {:logout {}}} or
{:on {:logout nil}}. It consumes the event and prevents parent fallthrough.
See Self-transitions and wildcards.
:always¶
An eventless transition checked after entry and after transitions into the state.
choice state¶
A transient decision node.
:after¶
A delayed transition. Entering the state arms the timer; leaving cancels it.
timeout¶
A named deadline using :timeout and :on-timeout.
Actors and composition¶
singleton¶
A machine registered with reg-machine. One id, one live instance per
frame — the snapshot lives in that frame's
runtime-db, so a second frame runs its own. The snapshot is nil until the
first event. Login is a singleton.
See Actors.
spawned actor¶
A live instance created at run time with :spawn or [:rf.machine/spawn …].
It has an allocated id such as :auth/request#0. The spec heading says
"dynamic actors"; that is an adjective, not a third kind.
See Actors.
actor¶
A live machine instance. A singleton and a spawned child are both actors. Liveness is the presence of a snapshot in runtime-db.
See Actors.
spawn¶
A state-node key that starts a child actor on entry and destroys it on exit.
See Actors.
spawn-all¶
A state-node key that starts several children and joins on their completion.
:join is :all or :any.
See Fan-out and join.
system-id¶
A stable role name bound to a spawned actor. Use it to message a child without threading its generated id.
See Actors.
:on-done¶
A callback or transition that runs when a child or compound sub-flow completes.
:output-key¶
A key on a final state naming which value from :data is reported to the
parent.
:raise¶
A machine-only effect that loops an event back into the same machine before the macrostep commits.
See Raise and internal events.
:internal-events¶
A top-level set of event ids that may be raised internally but are refused when dispatched from outside the machine.
See Raise and internal events.
Runtime terms¶
run-to-completion¶
The guarantee that one machine event settles all :always transitions and
raised events before the next external event is observed.
microstep¶
One internal step inside a macrostep: an :always transition or a raised
event.
macrostep¶
The full processing of one machine event, including all microsteps, ending in one committed snapshot.
commit¶
The single runtime-db write that stores the settled snapshot.
LCA / LCCA¶
Least common compound ancestor. The deepest state that remains active while moving from one hierarchical path to another. Exit actions run up to it; entry actions run down from it.
See Entry/exit cascading.
runtime-db¶
The framework-owned state partition where machine snapshots live. It is separate from app-db.
See runtime-db.
unhandled event¶
An event the current machine configuration does not handle. It is a no-op, not an exception.
fail loud¶
The design posture for invalid definitions: unresolved targets, missing guards/actions, bad timeout shapes, invalid final states, and similar mistakes fail at registration rather than later.
See fail loud.