xstate: XState’s state machines and actors for C++

Stately’s XState page introduces the library with a counter: a machine whose context holds a count, three events that change it, an actor that runs the machine, and a subscription that prints the count after each event. In xstate the counter is this program:

It prints:

Three things in it are xstate’s own, and each has a section of this chapter:

create_machine(config, implementations) builds a machine from XState’s config. A machine never changes once it is created, and copying one is cheap. Where a machine is, its state value, its context, its status and the rest, is a snapshot, a plain value the caller keeps, copies or stores.

The core holds XState’s pure functions, each named after XState’s in snake case. get_initial_snapshot, initial_transition and get_initial_microsteps compute where a machine starts, and get_next_snapshot, transition and get_microsteps where an event takes it from a snapshot; get_next_transitions, and can, XState’s snapshot.can, say what it could do. None of them changes anything. transition, initial_transition and the microstep functions also return every action the machine does not perform itself, such as a custom action, a delayed event or a send to another actor, for the caller to execute, as XState’s transition returns them; get_next_snapshot and get_initial_snapshot return the snapshot alone.

Under those functions is the one primitive xstate adds, the macrostep cursor. An event runs one macrostep: the transitions the event selects, then every eventless transition and every raised event that follows, until the machine is stable again. Each of those steps is a microstep. XState runs a macrostep to its end inside one call. xstate’s begin(machine, snapshot, event), and begin_initial(machine, input) for the initial macrostep, return a cursor instead, whose next() runs exactly one microstep and reports whether that microstep settled the macrostep, and whose done() says when one has. The dog’s wakes up, one microstep at a time:

It prints:

wakes up takes two microsteps: the first moves the dog to stretching, and the second takes its eventless transition to awake, whose entry action bark comes back with that microstep. XState’s getMicrosteps returns both at once; the cursor hands them over one at a time, so its caller may stop between two and resume later, since the cursor is a value and a copy of it resumes exactly where the original stopped. The caller pays for each call and stops when it chooses. The library never stops a macrostep on its own: a cycle of eventless transitions never settles, and the caller’s fuel is the only bound. The functions that compute where a machine goes are the cursor run to its end, without a bound.

The core never reads a clock either. Entering a state with after returns its delayed event as an action, a built-in xstate.raise with a delay. The caller hands it to a simulated_clock it owns, XState’s SimulatedClock, which keeps the event until the caller moves time forward and then gives it back, for the caller to send to the machine. The clock schedules only that built-in delayed raise: a custom action stays the caller’s, whatever its type or params.

Pure transitions and the macrostep cursor covers the functions, the cursor and its fuel.

actor_system runs machines as XState’s actors. It is XState’s createActor and its actor system in one: the host creates an actor from a machine, starts it, sends it events, reads its snapshot and subscribes to it. The machine invokes and spawns children, its sendTo, sendParent and forwardTo reach other actors, its children’s done and error events reach it, its timers fire when the host brings the time with clock_tick, and a host_actor, xstate’s counterpart of XState’s fromPromise, waits until the host resolves or rejects it. What the core returns, the layer executes: it creates the child of a spawnChild, delivers the event of a sendTo, arms a timer for a delayed raise or send, and hands a custom action to the host’s on_action. The dog, run as an actor:

It prints:

The same machine and the same event lead to the same snapshot. The custom action bark reaches the host’s on_action, where XState’s actor calls the function setup registered under that name.

The layer runs on xactor, webcpp’s header-only actor system, which already is the system XState’s actors need (xactor’s model): a scheduler on one thread that holds one FIFO mailbox per actor and one FIFO queue of the actors that have work, and whose every turn hands one message to its actor, so that the order of deliveries depends only on the order messages were sent; fuel for each execution; timers; and a lifecycle, under XState’s names. A second actor system inside xstate would duplicate all of it. Every message an actor sends is queued and handled in a turn of its own, where XState handles an event at once, nested in the sender’s call, when its actor is running and idle (Interleaving across actors).

Fuel reaches the actors too. A host call that delivers something opens an execution for each input it applies, and resume() one for each parked actor besides; each execution has the budget’s fuel. Every microstep costs one unit of it, and so does every message an actor sends and every timer it arms. An actor that runs out parks with what it has left to do, until resume() gives it more; XState has no such bound (Fuel). Time is the host’s too: a timer fires when the host calls clock_tick, never on its own.

Actors covers the layer, its fuel and its time included.

XState’s own tests are ported to cases written as JSON, one file per test file of XState’s, each with the tests it leaves out and why. Further cases pin what XState does where its own tests are silent, such as a machine whose root is a history node, an event of the type * or a timer armed twice under one id. The scripts of test/oracle/ run every case on XState 5.33.2 and record what XState produced: oracle.mjs the machine cases, one macrostep at a time through machine.transition, which XState’s pure functions call, and actors.mjs the actor cases, on XState’s actors. xstate’s test suites run the same cases and compare, microstep by microstep, the event, the transitions, the actions and the snapshot. The actor cases are compared actor by actor: the events each actor processed and the snapshot each left, the events it emitted, its status, and the host’s pending requests.

What XState produced is committed, so xstate’s suites run without Node. The oracle lane, b2 libs/xstate/test/oracle//oracle, runs the scripts on XState again, and fails when what XState produces is no longer what the suites hold.

The oracle runs XState’s development build, as XState’s own test suite does. That build makes checks the production build leaves out. Three of them can meet a JSON machine, and xstate makes them too: it refuses an event of the type * sent from outside, a transition that declares a truthy cond, and a forwardTo whose target resolves to no actor (The checks of XState’s development build).

Every program of example/xstate and example/actors, the programs of this documentation that use xstate, has a twin in test/oracle/twins: a JavaScript program that does on XState 5.33.2 what the C++ program does on xstate. The oracle lane runs every twin on XState’s development build and compares what it prints with what the C++ program printed:

So every program of this page that XState can run has run on XState, and printed what the page shows, or what Where xstate differs from XState explains.

xstate is header-only, so installing it puts directories on a program’s include path, and nothing is built but the program (Requirements lists what the program provides). In a webcpp checkout they are libs/xstate/include, webcpp’s configuration, libs/config/include, and, for the actor layer, libs/xactor/include, beside Boost 1.92’s headers. From the root of the checkout, with the program of the next two sections, libs/xstate/example/xstate/qs_toggle.cpp, copied as toggle.cpp, this command builds it:

tools/boost_json.cpp is the one translation unit that includes <boost/json/src.hpp>; without it the link misses Boost.JSON’s definitions. A compiler that does not find Boost on its default include path is given Boost’s include directory with -isystem, which makes Boost’s headers system headers, so the compiler’s warnings stay on the program’s own code: for Homebrew’s Boost, the one under /opt/homebrew/opt/boost. A program that uses the actor layer adds -I libs/xactor/include. GCC takes the same options.

Without exceptions, the program also needs a definition of boost::throw_exception, which Boost.System and Boost.JSON name: webcpp’s tools/throw_exception.cpp defines its two overloads, reports what was thrown on the standard error and aborts, since in such a build a throw is a defect, never a condition:

A program built with exceptions on needs none of -fno-exceptions, -DBOOST_NO_EXCEPTIONS or throw_exception.cpp, since Boost defines the function itself then.

A machine is the logic of an actor: the states it can be in, the events each state accepts, and where each event leads. This one, a toggle, is in one of two states, Inactive or Active, and the event toggle moves it from one to the other.

XState takes the config as a JavaScript object. xstate takes the same config as JSON, read at run time by create_machine: a C++ program has no object literal to write it in, and as data a config can come from a file, a request or Stately Studio’s export. JSON cannot hold a function, so the program gives the machine’s code in the second argument, the implementations: an action’s, for one, under the name the config gives the action. This config needs no code, and its implementations are empty (Handle context data, Implementations).

The examples of this page begin with the core’s header, Boost.JSON’s, and an alias for the namespace:

Then the machine:

create_machine returns a result<machine>: the machine, or the error that refused the config, such as invalid_config for a compound state without initial or unknown_target for a target that names no state. Where XState throws, xstate returns an error; and some configs XState accepts, failing only when it runs them, xstate refuses when the machine is created (A config is refused when it is created). A machine never changes once created, and copying one is cheap: it is a handle to data its copies share. What creation refuses tells what refuses a config.

Before it runs as an actor, the machine can be stepped by hand, which suits a caller that keeps the state itself: a request handler that loads a snapshot, applies an event and stores the result, or a test. A snapshot is where a machine is: its state value, its context and its status. XState’s pure functions compute one snapshot from another. initialTransition returns the snapshot a machine starts in, and transition the snapshot an event leads to, each with the actions the step returned for the caller to execute. They change nothing and keep nothing: the caller holds the snapshot and passes it back with the next event. xstate has the same functions, initial_transition and transition, which return a std::pair:

It prints:

An event is a type and a payload, empty here. The toggle has no actions, so every list is empty; Actions shows what they hold and who executes them.

An event’s macrostep is all the work it causes: one or more microsteps, each a set of transitions taken together, until no eventless transition is enabled and no raised event is queued (Microsteps). Each of these functions runs an event’s macrostep to its end at once. Under them is xstate’s one primitive, the macrostep cursor: begin returns a cursor whose next() runs exactly one microstep, so the caller decides how much work an event may cost, paying for each microstep and stopping where it wants. A machine whose eventless transitions never settle never returns from transition; only the cursor bounds it (The macrostep cursor).

An actor is a running process: it receives events, one at a time, and each event may change its snapshot and make it send events of its own. A machine is the logic an actor runs.

XState’s createActor makes an actor from a machine. In xstate, actors live in an actor_system, which runs them on xactor, and the program names each by the actor_ref the system returns. XState makes a system for each root actor implicitly; xstate makes it explicit because the system owns what a host must decide: the fuel its actors may spend, the time, and the systemIds its actors share (Creating an actor). xactor runs the actors on one thread: each actor has a FIFO mailbox, the actors that have work wait in one FIFO queue, and each turn hands one message to its actor, so the order of deliveries depends on nothing but the order the messages were sent (xactor’s guarantee 2). With fuel bounding each execution, the same inputs make the same run and no run is unbounded. The system’s create_actor, subscribe, start and send are XState’s createActor, actor.subscribe, actor.start and actor.send, and its snapshot_of is actor.getSnapshot. An actor needs the actor layer’s header, <webcpp/xstate/actors.hpp>. The same toggle, as an actor:

It prints:

Actors covers the rest: children, messages between actors, actors the host answers for, time, and what fuel guarantees.

A delayed transition is taken when its state has been active for a given time, with no event. A state lists its delayed transitions under after, keyed by the delay in milliseconds. Here Active goes back to Inactive two seconds after it was entered, unless a toggle leaves it first, which cancels the delay.

The machine never reads a clock. Entering Active arms a timer, which waits until the host brings the time: clock_tick(2000) moves the system’s time to 2000 milliseconds and fires the timers due by then. XState’s actors schedule delays with JavaScript’s setTimeout unless they are given another clock, such as its SimulatedClock; an xstate actor has no clock but the host’s (In the actor layer, Delayed events and time).

It prints:

At 1000 milliseconds the timer is not due, and nothing happens. At 2000 it fires. An after is an event the state raises with a delay when it is entered, xstate.after.2000.toggle.Active here, and cancels when it is left; the delayed transition is a transition on that event, as in XState (In the machine core).

Context is the data a machine carries beside its state: here, how many times the toggle became Active. A context that is data stays in the config, as JSON: "context": {"count": 0} is XState’s context: { count: 0 }, and it is the context the machine starts with. An assign action updates it: on entering Active, incrementCount adds one to the count.

In XState the update is a function written inline in the config, which JSON cannot hold. In xstate the config names the action, and the program registers it under that name in implementations.actions, as XState’s setup({ actions }) registers implementations by name (Implementations). An assign_action receives an action_args, the context, the event and the action’s params, and returns the members it changes, which it merges into the context, as XState’s assign does (Assign).

An implementation returns a result. A failure stops the macrostep and leaves the snapshot it began from, its status error, where XState’s function would throw (Failures are values).

It prints:

The action reads the count with integer_at, which returns none where a member is missing or is not an integer. Boost.JSON’s accessors that check, such as at and as_int64, throw on a mismatch, and a throw aborts a program built without exceptions; if_object, if_contains and is_int64 answer with a pointer or a bool instead, and try_at and try_as_int64 with a boost::system::result:

Context covers context one part at a time: its initial value, assign, how guards and actions read it, and how an actor holds it.

Input is the data an actor is created with. Here it is the most times the toggle may become Active, maxCount, and the initial context is computed from it. A guard is a condition a transition is taken under: countBelowMax lets toggle activate the toggle only while the count is below that maximum.

In XState both are functions written in the config. In xstate the config names the guard, and the program registers it under that name in implementations.guards, as it registers the action: a predicate of an action_args that returns a result<bool> (Guards). The context function, which a config cannot name, goes in implementations.context: it receives the input and returns the initial context, a result<boost::json::value>, in place of the config’s context. A failure it returns, or a value that is not an object, fails the actor’s initial macrostep and leaves it in the status error (Initial context from the input, A context that is not an object). The input is the input of the actor_options given to create_actor, as XState’s is an option of createActor:

It prints:

The last toggle finds a count of 1, not below a maxCount of 1, so the guard refuses it and the snapshot stays; the subscriber hears it all the same. Input and output covers input, and output, the data an actor is done with.

A state machine models how a process goes from state to state when an event occurs. It lists every state the process can be in, every event it reacts to, and, for each state and event, where the process goes next.

Writing this down makes the impossible states visible, since a state that is not listed cannot happen, and the unwanted moves too, since a move that is not listed is never taken. The same state and the same event always lead to the same next state, so a machine is simple to test.

A statechart is a state machine extended for larger processes: a state can contain states (hierarchy), several states can be active at once (parallel states), a state can remember where it was (history), and the process carries data beside its state (context). XState implements statecharts, and xstate runs the same ones, from the same config written as JSON, with a name wherever XState’s config would hold a function (Machines as JSON, implementations by name). What is not ported lists what it does not run yet, and Where xstate differs from XState where it differs. As in Stately’s documentation, "machine" here means a statechart.

In xstate, a machine is the tree of state nodes its config describes, together with the implementations the config names, and it never changes once it is created. Where the machine is at one moment is a separate value, its snapshot (The snapshot). Each event computes a new snapshot from the previous one, and the machine stays as it was.

create_machine(config, implementations) builds a machine from a config, a boost::json::value, and the implementations the config names. It returns a result<machine>: the machine, or the error that refused the config (What creation refuses). Stately’s feedback machine has two states, question and thanks, and goes from the first to the second on the event feedback.good:

It prints:

Boost.JSON parses the config from a string; a program may as well read it from a file or a request. It names no implementation, so the second argument is empty, {}. Once has_value() says the result holds a machine, *feedback is that machine. initial_transition and transition are XState’s pure functions initialTransition and transition: each returns, as a pair, the snapshot the machine reaches and the actions its caller executes, and changes nothing else, so .first is the snapshot. Pure transitions and the macrostep cursor has all of them and the cursor they are built on. Stately’s page runs the machine as an actor, with createActor; in xstate an actor_system does that, as Actors shows.

A config describes the machine: its states, the transitions between them, the actions they run, its context. In xstate it is the object XState’s createMachine takes, written as JSON. JSON holds data only, where XState’s config, a JavaScript object, may also hold functions: an inline action, a guard written as an arrow function, a context computed from the input. That is a choice, for three reasons:

What a function does in XState’s config, a name does in xstate’s: the config names the function, and the implementations hold it (Implementations). An action or a guard is named as XState’s JSON writes it, "entry": "notify", or {"type": "notify", "params": {...}} with fixed params, which the implementation reads from its action_args together with the context and the event. A higher-order guard is a JSON object, {"type": "xstate.not", "guards": [...]} and the like. Appendix A maps each function XState’s config may hold to its form in xstate (Functions become implementations registered by name), and Functions become names gives the three that cannot keep what they do in XState.

The members xstate reads, on any state unless the table says otherwise:

A transition is a target, an object (target, actions, guard, reenter, description, meta) or a list of them (Events and transitions). A target names a sibling of the transition’s state by its key, or a state below that sibling by a path of keys joined by dots, "red.stop"; a state below the transition’s own state by a path that starts with a dot, ".child"; or any state by its id, "#id" (Targets). states, on and after are read in the order JavaScript enumerates an object’s keys, as XState reads them: a key that is an array index, such as "500", first, by number, then the rest as written (State nodes and ids).

xstate reads no other member of a transition but cond, XState v4’s name for guard: a truthy cond refuses the machine, as XState’s development build refuses it (What creation refuses). types, which only TypeScript reads, and schemas, which XState keeps on the machine without using, are left unread. So is options: XState uses its maxIterations to throw on a macrostep that never settles, and in xstate the bound is the fuel of the caller that drives the cursor (Fuel). So is XState’s route, which lets the event {"type": "xstate.route", "to": "#<id>"} reach, from any state, a state that has an id and a route; in xstate that event selects no transition.

Implementations are the code a machine runs that is not its states and transitions: actions, the side effects; guards, the conditions a transition is taken on; delays, the time before a delayed transition; and actors, what a state invokes. Three more compute a value: the initial context from the input, an invoked child’s input, and a final state’s output.

implementations holds them by name, as XState’s setup({ actions, guards, delays, actors }) registers them, so that the config refers to each with a string. In xstate a name is the only way, because a JSON config holds nothing else, and registering by name gives three things:

An action is the exception: an action name the implementations do not hold is not an error. It is a custom action, which xstate returns to its caller to execute, as XState’s transition returns it (Custom actions). That is how a caller’s own effects, a log line, a request, a write, reach it.

Stately’s setup example registers two assign actions, increment and decrement, which the config names under on:

It prints:

increment and decrement are each an assign_action, holding an assigner that returns the members to change, and emplace registers each in implementations.actions under the name the config uses. xstate merges what an assigner returns into the context as Object.assign does, and fails with implementation_failed on a context that is not an object (A context that is not an object). A context and an event are JSON values, which no compiler checks, as XState’s types let TypeScript check them; so an implementation checks what it reads before it reads it, as add does, and returns implementation_failed when the context is not what it expects.

Guards and delays are registered the same way, in implementations.guards and implementations.delays. After Stately’s example, a delayed transition is guarded by canAccess and delayed by shortDelay; its action, trackAccess, is left unregistered:

It prints:

Entering checking returns the delayed xstate.raise of its after event, whose delay, 250, shortDelay resolved. A delay is always a function, here one that ignores its arguments, where XState’s delays also takes a plain number. The example sends the after event itself, as a clock would once the delay has passed; delayed transitions in the machine core shows the simulated_clock that does it. canAccess lets the transition through, leaving checking returns the xstate.cancel of the delayed event, and trackAccess, which nothing implements, comes back as a custom action.

implementations is a value: a module that adds its own entries to another’s copies it and inserts them, where XState’s setup.extend adds implementations to an existing setup. It holds seven members:

Built-in and custom actions lists the built-in actions, each with what the core returns for it. The machine core runs no actor itself: entering a state that invokes one resolves into an xstate.spawnChild action and leaving it into an xstate.stopChild, an invoke’s onDone and onError are transitions on xstate.done.actor.<id> and xstate.error.actor.<id>, and the actor layer runs the child and delivers those events (Invoking actors).

The context’s function receives the input. Every other function the implementations hold receives an action_args: the context as it is when the function runs, the event of the microstep, and the params the config gave the action or the guard, null when it gave none. The root’s output is the one exception to the event: it receives the done event that completed the machine, as XState’s does. For a compound root, that is the done event of the top-level final state, which carries that state’s output; for a parallel root, it is the root’s own done event, which carries none (The machine’s output and its final state). Each function returns a result, and an error it returns stops the macrostep, which leaves the snapshot it began from with the status error, where XState’s implementation would have thrown (Failures are values).

Three rules hold for the implementations, each checked at creation:

A machine never changes once it is created. The state it is in lives in a snapshot, a value of its own, so one machine serves any number of snapshots and actors at once, and nothing one of them does reaches another. A machine is a handle to data its copies share: copying one copies a pointer, not the tree, so a cursor, an actor or a machine_actor keeps a copy. The transitions a microstep reports point into the machine, and stay valid while any copy of it lives.

To run one config with other implementations, create a second machine from it. create_machine takes the whole set of implementations, so a program that changes some of them copies the first machine’s, registry(), and replaces the entries that change. XState’s machine.provide does this in one call; xstate has no provide (What is not ported).

It prints:

add is the function of the previous section’s example. by_ten starts from a copy of the implementations of counter, in which insert_or_assign replaces increment and keeps any other entry. Both machines are created from one parsed config; neither changes the other, nor the config.

A config is checked once, when the machine is created, and a config that is not a machine gives no machine: create_machine returns the error instead. Every machine comes from create_machine, which create_machine_from_definition calls too, so a machine that exists has passed every check, and a mistake in a config shows when the config is loaded, not when an event first reaches it.

The error is a value, not an exception. xstate throws no exception of its own, and builds with exceptions turned off, which the lint checks; where XState throws, xstate returns an error. result<T> is boost::system::result<T, boost::system::error_code>; its error is a code of the category webcpp.xstate, one of the values of errc, and message() spells its name. Check has_value() before using a result.

Here a transition is guarded by isValid, which the implementations do not hold:

It prints:

xstate finds the missing name when the machine is loaded, before any event. XState creates this machine and starts it, and throws only when submit arrives and the guard is evaluated (A config is refused when it is created). XState refuses some configs in createMachine, others only when the machine starts or an event reaches the broken part, and accepts some; xstate refuses each of those below at creation, and the last column says what XState does with it:

Some members hold any value, as in XState: a state’s meta, the root’s version, the output of a final state or of the root, and a transition’s meta and description. Two values are dropped, where XState keeps them: a state’s meta that is null, which xstate reads as no meta, and a state’s description that is not a string, an exception to the first row.

One config is accepted as XState accepts it: a machine whose root is itself a history state, which has no parent to resolve its default target against. A microstep that needs that default fails with unknown_target, where XState throws (History states).

What creation cannot see fails later, and as a value too: an implementation that returns an error fails the microstep that calls it, and the snapshot it leaves has the status error (Actions).

A machine is a tree of state nodes, one for the root and one for each state of its config, and a node holds everything the config says of its state. A program reads the nodes to show a machine, to name a state in a target or a query, or to read what a snapshot’s active states are.

xstate keeps the nodes in one list, in document order: the root first, a parent before its children, and the children in the order JavaScript enumerates the keys of states, as XState reads them. A key that is an array index, such as "0" or "2", comes first, by number, and the others follow as the config writes them: the children b, 10 and 2 are listed 2, 10, b. A node is named by its index in that list, so the tree holds no pointer: size() is the number of nodes, node(index) one of them, for an index below size(), and root() is node(0).

A state_node holds what XState’s StateNode holds once it is initialised: its key in its parent’s states, its id, its path of keys from the root, its type, the index of its parent, its children, its entry and exit actions, its transitions and invokes, its tags, meta, output and description. A state’s id is the id its config gives, or, without one, the machine’s id and the state’s path, joined by dots; the machine’s id, id(), is the root’s id, (machine) when the config gives none, as in XState. An explicit id names its own node only: below, the children of playing, whose id is active, are player.playing.normal and player.playing.fast.

It prints:

Each line gives a node’s index, key, id and type, and type_name spells the type. The index is the node’s order in XState, as long as no two nodes of the machine share an id. Three functions find a node, each returning its index as a result<std::size_t>:

A backslash escapes a dot in an id or a path: #foo\.bar names the node whose id is foo.bar, where #foo.bar names the child bar of the node foo. A name that finds no node is the error unknown_state, where XState’s getStateNodeById throws.

The machine also keeps what it was created from: config() is the config, registry() the implementations, and context() the config’s context, an empty object when the config gives none or null. The reference lists every member of machine (webcpp::xstate::machine).

A machine’s definition is the machine written out as JSON, once its config has been read: every node with its id, key, type, initial transition and children, its transitions with their targets resolved to lists of #id, its entry and exit actions, its order (the root’s is written -1), its invokes and its tags. It is what a program stores, sends or hands to a tool when it needs the machine as data, every target already resolved. XState writes it with machine.toJSON(), which JSON.stringify(machine) calls, and to_json(machine) writes the same definition:

It prints:

The program reads the definition with JSON pointers: the root’s order is -1, a state’s own type is written even where its config leaves it out, and a transition’s target and source are ids. to_json writes XState’s definition key for key, with two exceptions. It leaves out the two values creation drops, a state’s meta that is null and a description that is not a string, which XState writes (What creation refuses). And it adds the higher-order guards, which XState cannot write: they are functions in XState, and JSON.stringify leaves a function out. The members of an object may come in another order than XState’s, so compare two definitions as JSON values, with ==, and not as text.

create_machine_from_definition(definition, implementations, context) loads a definition back, one to_json wrote or one XState wrote. A definition holds names, not code, so the implementations are given again; and it holds no context, so the context is given too. It returns a result<machine>. Here a toggle is written out, stored as text, and loaded back:

It prints:

The reloaded machine takes the original’s step, starts from the context it was given, and writes the definition it was loaded from, the toggle’s version on every node included. XState has no function that creates a machine from a definition.

The loader refuses with invalid_config what XState never writes: a value that is not an object, and a state whose states, on, invoke, entry or exit does not have the JSON type a definition gives it, an object of state objects, an object of lists of transition objects, a list of invoke objects, a list of actions; and, in a state that has states, an initial whose first target is not a string. From any other object it rebuilds the config the definition describes and creates the machine with create_machine, which checks it as it checks any config (What creation refuses): an id that is not a string, or a type xstate does not know, is invalid_config there. So is an entry, exit, actions or tags list that holds null, the list XState writes for one of them that is null, which creation refuses in a config too. A compound state’s initial is rebuilt from its first target, # and the id of a child, with the actions, meta and description of the written initial transition; a target that names none of the children leaves the state without an initial, which is invalid_config too, where a config’s initial that names no child is unknown_target.

Three members repeat what the rest of the definition says and are not read, whatever they hold: key, order and transitions; nor is the version of a state below the root, which repeats the root’s. The root’s version becomes the machine’s, which to_json writes on every node again.

A definition does not hold all of a config either. The definition, XState’s and so the one to_json writes, leaves out the context, the eventless transitions (always) and a history state’s default target; two states may share an id when a key holds a dot; and an entry or exit action named xstate.raise or xstate.cancel, a custom action, cannot be told from the raise and cancel an after adds, which the definition writes under those names, so the loader drops it with them. Given the original’s context, a machine loaded from a definition takes the original’s steps and writes the same definition whenever the original has none of those; one loaded from a definition XState wrote writes it without the two values to_json leaves out. A definition XState wrote has no higher-order guard either: the transition comes back unguarded, and the reloaded machine takes it whatever the guard would have decided. One to_json wrote keeps the guard.

The sections that follow take the config apart: States, Context, Events and transitions, Actions and Input and output.

A config lists the machine’s states under states, each by its key, and names the one the machine starts in with initial. The snapshot’s value says which state is active, here by its key.

It prints:

The snapshot holds both halves of the machine’s condition: value, the finite state, and context, the data no finite set of states could enumerate, such as what the user typed (Context). The event feedback.good moved the machine from prompt to thanks; the context did not change, as no action assigned to it.

Each key under states is a state node, and the machine itself is the root node. A node has an id: the one its config gives with id, or else the machine’s id and the node’s path joined by dots, feedback.prompt here. A machine without an id is (machine), as in XState. machine::node_by_id finds a node by its id and machine::node reads it (State nodes and ids). An id does not change the state value; it is another way for a transition to name the state (Targets).

A snapshot is where a machine is at one moment: its state value, its context, whether it still runs, and what it produced. xstate’s snapshot is a plain struct: XState’s snapshot without its machine, its node objects, its children’s actor objects and the methods that read them. You keep it, copy it, store it, and hand it back to the function that computes the next one.

It holds no pointer into its machine: it names the active state nodes by their index in the machine. A value that points nowhere has no lifetime to manage, so it can wait between two requests or two microsteps, and a copy is independent of the original. A query that needs the tree of nodes takes the machine as an argument instead, as every pure function does (get_meta, can), where XState’s snapshot carries its machine and reads it through its methods.

Two rules follow from this. A snapshot’s nodes are indexes into the machine that computed it, so a snapshot is read and advanced only with that machine, or with one created from the same config. And its members are public so they can be read: the next step reads both value, to select an event’s transitions, and nodes, to select eventless ones and to exit and enter states, so a snapshot edited by hand is not one xstate computed. To put a machine in a given state, build the snapshot with resolve_state (Persisted state).

XState’s 'stopped' is the status of a stopped actor, and the status its transition gives a snapshot that receives the event xstate.stop. In xstate the actor layer reports a stopped actor through status_of (Snapshots and status), and the core runs xstate.stop as any other event (Events).

Its queries are matches (Matching a state value), has_tag (Tags) and remembered (History states); get_meta(machine, snapshot) (Meta and descriptions) and can(machine, snapshot, event) (Whether an event would do anything) take the machine. A snapshot is rebuilt from a state value and a context with resolve_state (Persisted state); XState’s toJSON of a snapshot has no counterpart.

XState’s mapState(snapshot, mapper), which Stately’s page on states shows, walks the active nodes from each state without children up to the root and calls, for each one, the map function the mapper object gives for its path. xstate has no mapState: a program reads snapshot.nodes and maps each node by its id or its path, machine.node(index), as describe does in the example below.

The example prints the members of a snapshot before and after an event that completes the machine:

It prints:

The first snapshot is in form, and in its initial child invalid; nodes lists every active node, from the root down, and tags the one tag form carries. feedback.submit takes the machine to thanks, a final child of the root, so the machine is done: its status is done and its output is the config’s output.

The order of nodes is XState’s, and xstate keeps it because it is not cosmetic: it decides the order in which the regions of a parallel state take their eventless transitions. The nodes a microstep keeps keep their place, those it exits leave, and those it enters are appended in document order; a microstep that ends with the same active nodes, and in which no history state records anything, keeps the order it had. Once a step completes the machine, XState sorts the nodes in reverse document order, a child before its parent, and so does xstate: feedback.thanks before feedback.

Document order is the order of the states in the config as XState reads it: a parent before its children, and siblings in the order JavaScript enumerates the keys of states, a key that is an array index, such as 0 or 10, first, by number, then the rest as written. A parallel state whose config writes its regions b, 10, 2 and a enters them in the order 2, 10, b, a.

A machine starts in its initial state, the child of the root that initial names. A parent state names one too: entering the parent enters its initial child, and, when that child is a parent, the child’s own initial child, and so on until every active branch reaches a state without children. A machine has at most one initial state, so it always knows where to start. A parallel state, the root included, has none: entering it enters every region (Parallel states).

It prints:

timer targets red, so the machine enters red and its initial child walk. initial may be an object, {"target", "actions"}: its actions run when the parent is entered through its initial state, and only then. So timer returns beep, and emergency, which targets red.stop directly, does not. beep has no implementation, so it comes back to the caller to execute (Actions), and types_of lists the types of the actions a step returned. Both transitions start from the same yellow snapshot: a snapshot is a value, and nothing stops a caller from computing two futures of it.

A parent state must name its initial state, even when every transition targets one of its children, and the name must be one of its children. create_machine refuses the machine otherwise:

It prints:

The first config, a parent without initial, is invalid_config; the second, an initial that names no child, is unknown_target. XState’s createMachine refuses the first too, and accepts the second, which throws only when the state is first entered (A config is refused when it is created). xstate refuses both when the machine is created, with every other config error it can detect there, so a mistake in a config shows before the machine runs. Two are left to run time: the #id of an xstate.stateIn guard that names no state, found when the guard is evaluated (Higher-order guards and stateIn), and the default of a history state that is the machine’s root (Shallow and deep history).

A state can contain states, its children, which are active only while it is. A parent state is also called a compound state. Grouping states under a parent lets them share what is common to them: a transition every child takes, an entry or exit action, a sub-process with its own initial state and its own end.

The machine is a parent state too, the root, and it is always active. A machine may have no states besides the root: its transitions are then the root’s, which run actions and target no state, and its state value is {} (The state value).

It prints:

The first next is handled by child1, the deepest active state, whose own transition goes to child2 and so into its initial child grandchild1. The second next finds no transition in grandchild1 or child2, and reaches parent, whose transition targets grandchild2. restart targets child1 from the parent.

Three rules govern transitions on parent states:

A parent state also ends: when one of its final children is reached, the parent is done, and its onDone transition is taken (A parent state is done).

A parallel state’s children, its regions, are all active at the same time, where a parent state has one active child. Parallel states model aspects of a system that change independently, such as a player’s track and its volume. Entering a parallel state enters every region, exiting it exits every region, and an event reaches every region: each region with a transition for it takes it, all in one microstep. A parallel state has "type": "parallel" and needs no initial.

It prints:

The value of a parallel state is an object with one member per region. PLAY reaches both regions and only track handles it; MUTE only volume. RESET is handled by both regions, in a single microstep, which get_microsteps shows: that microstep’s transitions lists the two transitions taken (The microsteps of an event).

A parallel state is done when every one of its regions is (A parallel state is done).

A final state, "type": "final", is a state where a piece of work is complete. A final child completes its parent; a final child of the root completes the machine. A machine may have several final states, or none, if it runs for as long as it lives.

A history state is a pseudostate: it is never active itself. A transition that targets it enters, instead, the children its parent had active when the parent was last exited, so a machine can resume where it left off. When the parent has never been exited, it enters the history state’s target, when it has one, or else the parent’s initial state, or, when the parent is a parallel state, every one of its regions.

It prints:

checkout targets payment.hist before payment was ever exited, so the machine enters the initial state of payment, card. next exits payment while paypal is active, and the history state records it; back returns to paypal. The snapshot’s history holds what each history state remembers, and remembered(id) returns it for one history node, as node indexes, or nullptr before the history state has recorded anything; XState’s is historyValue[id], the node objects.

A history state is "type": "history", and shallow unless it says "history": "deep"; "history": "shallow" and "history": true say shallow. A node with no type, no children and a history member is a history state too, when that member is truthy as JavaScript reads it, as in XState: a history of false, null, "" or 0 leaves the node atomic.

A tag is a name a state carries to say what kind of state it is, such as loading or visible: several states may share it, and a state may carry several. A state lists its tags under tags, one string or a list of strings; create_machine refuses any other tags, null included, with invalid_config (What creation refuses). The snapshot’s tags holds the tags of every active node, each once, and has_tag(tag) says whether one of them is the tag given, as XState’s snapshot.hasTag does.

It prints:

In thanks, both thanks and its child celebrating carry visible, and the snapshot lists it once, in the order of the active nodes. closed writes its one tag as a string. A tag answers what the machine is doing without naming where it is: code that asks has_tag("visible") keeps working when the states are renamed or nested differently, where a test of a state value would need to change. XState types its tags with setup({ types }); a JSON config has no types, so xstate’s tags are any strings.

meta is static data a state carries for whoever reads the machine, such as the text a view shows in that state: any JSON, which the machine never reads itself. get_meta(machine, snapshot) collects the meta of every active node that has one, by the node’s id, as XState’s snapshot.getMeta() does. It takes the machine because the meta belongs to the nodes, and the snapshot names its nodes by index.

A description is a string that documents a state for the people who read the machine; Stately’s editor shows it beside the state. A transition may have a description and a meta too. xstate keeps each where the config put it, a state’s description in state_node::description, and writes them in the machine’s definition (The definition), except a state’s meta that is null and a state’s description that is not a string, which it drops (A state’s null meta, and a description that is not a string).

It prints:

The root’s meta is in both results, because the root is always active; the meta of prompt and then of thanks follows the active state. The description of prompt is read from its node, an optional string.

The config’s context is the initial context of every snapshot the machine starts in. xstate copies it into each one, so every snapshot owns its context and no two snapshots, or two actors, share one. XState hands every actor the config’s object itself, which is why Stately’s page warns that mutating it may change the context of other actors; a boost::json::value held by value leaves nothing for that warning to guard.

A machine without a context, or with "context": null, starts with an empty object, as XState’s does:

It prints:

Write the context as an object. xstate keeps any other value as written, false, a number, a string or a list, and an assign on it fails with implementation_failed. XState starts a context of false, 0 or "" as {}, and its assign, which merges with JavaScript’s Object.assign, drops a context of true or a number and spreads a string or a list into numbered members (A context that is not an object).

Some context is not known when the machine is written: a timestamp, an id, anything that must be computed when the machine starts. XState takes the context as a function for that, which runs once for each actor, when the actor is created, so that each actor computes its own. A function cannot be JSON, so xstate takes it from the implementations, as it takes all the code a machine names: implementations.context, a context_maker. When it is set, it replaces the config’s context.

It runs at the start of every initial macrostep: in each get_initial_snapshot, initial_transition, get_initial_microsteps and begin_initial, and when an actor is constructed. A child is constructed when its parent resolves the spawn of an invoke or a spawn_child_action. A root is constructed on start, not on create_actor, which runs nothing; XState’s createActor runs the function at once (The root is constructed on start).

It prints:

The machine was created while now was 1000, and each snapshot holds the time at which it was computed. xstate itself never reads a clock, and a context_maker that read one would make the initial snapshot depend on the moment it ran, so the time here comes from a variable the function captures, where Stately’s page reads Date.now(). A program whose results must follow from what it is given passes the time in the input (Initial context from the input).

The input is the data a machine is started with, as a function is called with its arguments; Input and output covers it whole. The initial context is often computed from it: a user’s id, a default rating. XState’s context function receives { input }. xstate’s context_maker receives the input itself, a boost::json::value, null when none was given. The input is the second argument of get_initial_snapshot, initial_transition, get_initial_microsteps and begin_initial, and the input of an actor’s actor_options.

It prints:

initial_feedback checks the input before it reads it, and returns an error when the input lacks what it needs: xstate throws no exception, and where XState’s function throws, xstate’s returns the error as a value. A context that cannot be computed fails the initial macrostep on its first next(), before any state is entered: the snapshot’s status is error, its error the code the function returned, and its context an empty object, the snapshot XState’s getInitialSnapshot returns when its function throws. The same machine without an input:

It prints:

An actor takes the same input in its options, as XState’s createActor(machine, { input }) does (Options):

It prints:

Three rules hold for the function:

The context changes through one action: assign. Like any action, it is named by a transition, an entry or an exit, and runs when that transition is taken or that state entered or left (Assign). Its implementation is an assigner: a function of the action_args that returns a partial update, an object. The update is merged into the context as Object.assign merges it: each of its members replaces the context’s member of that name, or is added, and every other member is kept.

XState writes an assign in the config or in the actions of setup. xstate registers it by name, as an assign_action in implementations.actions, because a config is JSON and a function is not. Here update_feedback copies the event’s feedback into the context:

It prints:

The update named feedback only, so rating was kept. The event’s members other than type are its payload, args.event.payload (Events). transition returned no action: the library runs an assign while it computes the microstep and never returns it to the caller, as XState does. The snapshot initial still holds the context it had.

XState’s assign takes either a function that returns the update, assign(({ context, event }, params) => ({ ... })), or an object of property assigners and fixed values. An xstate assigner is the function form: it builds every member of the update itself, as update_feedback builds feedback. XState’s assigner also receives spawn, self and system, and can put an actor it spawns in the context. An xstate assigner receives only the action_args, a context holds no actor, and a child is spawned by a spawn_child_action (Spawning actors, The context function).

The rules of an assign:

Every function of the implementations but the context function, which receives the input (Initial context from the input), receives an action_args: context, the context as it is when the implementation runs; event, the microstep’s event; and params, the params the config gave the action or the guard, null when it gave none. These are the three XState hands an implementation, the first two in its first argument and params in its second. The machine’s output is the one exception to event, as in XState: it receives the done event that completed the machine, that of the top-level final state that completed it or, for a parallel root, the root’s own (The machine’s output and its final state).

A counter shows the first two. belowLimit guards inc, add adds its param by, and report is a log whose value is the count it sees. Each reads its numbers with integer_at, which returns the integer an object holds under a key, or none:

It prints:

Each inc that was taken logged the count twice: report ran before add and after it, and saw each context. The third inc found the count at the limit: the guard was false, no transition was taken, and nothing ran or was returned. report is returned as xstate.log, its value resolved from the context at its turn (Log).

A custom action, one the implementations do not hold, is returned to the caller with the params the config gave it, and nothing of the context, where XState’s carries the context it ran with in its info (Custom actions). The code that executes it reads the context from a snapshot, which holds it as a whole microstep left it: the snapshot of the microstep that returned the action, from the cursor or get_microsteps, holds the context after every action of that microstep (Microsteps). A value that must be computed from the context at the action’s turn is computed by a registered implementation, as the value of report is here.

A snapshot is a plain C++ value: the state value, the context, the status and the rest. A transition never changes the snapshot it begins from; it returns a new one. The same event taken twice from the same snapshot gives two snapshots equal member by member, and the first is still there, to be used again or stored. A counter whose inc adds one, and whose set increments, then assigns the count its event carries, and fails without one:

It prints:

A failure keeps the snapshot a macrostep began from too. When an implementation fails, the macrostep ends in that snapshot, its status error and its error the code the implementation returned: no assign of the failed macrostep reaches the context, not even one that ran before the failure. That is the snapshot XState’s actor keeps, where its pure functions throw (When an implementation fails, Failures are values). A set without a count, from the snapshot second:

It prints:

The count is 1, the count of second: increment ran and made it 2, then setCount failed, and the increment was dropped with the rest of the macrostep.

Since a snapshot is a value, its caller keeps it where it likes: in a variable, a queue, a map of sessions. Its state value and its context are JSON, so they can be stored, in a database or across two requests, and resolve_state(machine, value, context) builds a snapshot back from them, as XState’s machine.resolveState({ value, context }) does. It returns a result and refuses a value that names no state with unknown_state. It restores the value and the context and nothing else: the status comes from the value, done or active, never error, and the output, what history states remember and the children are not restored (Persisted state). Inside a macrostep, the snapshot of each microstep holds the context as that microstep left it, and the macrostep cursor hands each one to its caller (The macrostep cursor).

An actor keeps the snapshot for its caller: it starts in the initial snapshot, takes each event sent to it, and keeps the snapshot each macrostep settles in. Stately’s page shows the context through an actor that a listener watches. Here the actor is one of xstate’s actor_system, and its machine updates the context with update_feedback, the assigner of Updating context with assign:

It prints:

subscribe hands its listener each snapshot the actor settles in while it is active, and the one it is done in, as XState’s subscribe does; snapshot_of returns the latest. The listener runs inside the actor’s turn: it may read the system, but a call from it that changes the system, a send among them, is refused with xactor’s invalid_argument and changes nothing, where XState accepts a send from a subscriber and handles it after the update in progress (A callback that calls the system back). Actors, their fuel (Fuel, parking and resume) and their children are the subject of Actors.

XState types the context with TypeScript, in setup({ types: { context } }), and the compiler checks every implementation against it. An xstate machine is loaded from JSON at run time, so no type exists for a compiler to check: the context is a boost::json::value, and each implementation checks what it reads, before it reads it. It returns an error when a member is missing or of the wrong kind, as integer_at and its callers do in How guards and actions read the context. That error is a value: it ends the macrostep in the snapshot’s status (A snapshot is a value).

Read members with if_object and if_contains, which return a null pointer when the value is not an object or the member is missing. at throws on a missing member, and in a build without exceptions the throw aborts the program.

An event is an object with a type, the string that names what happened, and any other members, its payload, as an event is in XState. xstate’s event holds the two apart: type, a std::string, and payload, a boost::json::object holding every other member. Transitions match the type; the payload is data for the implementations, which receive the event as args.event. The example reads an event from JSON with event_from_json, prints its two parts, and sends it to a machine:

It prints:

An event usually arrives as JSON, in the flat form XState’s actor.send takes, {"type": ..., ...payload}. event_from_json reads that form and to_json writes it, its type first. An event can also be built in C++, from its two members:

event_from_json refuses a value that is not an object, or whose type is missing or not a string, with invalid_event:

It prints:

An event of the type * is read like any other. A machine refuses it as the event of a macrostep, which a caller sends or a clock releases, and takes it only as an event it raised itself without a delay (An event of the type *).

Events whose type starts with xstate. are the machine’s own: xstate.init is the event of the initial macrostep, xstate.after.<delay>.<state id> comes back from a delayed transition (Delayed transitions), xstate.done.state.<state id> is raised when a compound or parallel state completes (Done events), and xstate.done.actor.<id> and xstate.error.actor.<id> come from invoked actors (Done and error events). They select transitions as any other event does, with two exceptions in XState that xstate does not follow yet. When xstate.init comes from outside, XState’s macrostep selects no transition for it, and when xstate.stop, the event that stops an XState actor, comes from outside, it stops the machine. xstate selects transitions for both as for any other event, so an on entry that names one, or a * transition, takes it. A caller should therefore not send xstate.init or xstate.stop, nor make up any other of these events. A caller of the machine core does deliver two kinds itself: each xstate.after... event its clock releases (In the machine core), and the done and error events of the children it runs, since the core runs none. The actor layer delivers both for its actors.

A state’s on maps event descriptors (Event descriptors) to transitions. Each transition is written in one of three forms:

target names the state or states the transition goes to (Targets); a transition without one is targetless. actions lists the actions it runs when it is taken (Actions), guard the condition it is taken on (Guards), and reenter whether it leaves and enters its source again (Self-transitions and reenter). description and meta are for readers and tools: xstate keeps them in the machine’s definition, which to_json writes as XState’s toJSON() does, and does nothing else with them. The root is a state too: its on handles an event in every state, unless a deeper state handles it first.

Creating the machine checks every transition, so a mistake is an error before any event runs: a target that names no state is refused with unknown_target, a guard the implementations do not hold with unknown_guard, and an on key that is the empty string with invalid_config, as XState refuses it and asks for always instead. invalid_config also refuses a transition that declares cond, XState v4’s name for guard, with a value JavaScript reads as true, as XState’s development build does, and an actions that is null, which XState accepts as a list that holds null, and then throws when it takes the transition (What creation refuses lists them all).

An event selects its transitions starting from the deepest active states:

In a parallel state each region selects on its own, so one event can take a transition in each region (Parallel states). The parallel state’s own transitions, and its ancestors’, are tried only when no region selected one. When the transitions selected in two regions would exit a common state, as two that leave the parallel state would, only the first is taken, in the order the state value lists the regions.

In the editor below, escape means three things: in menu it closes the menu, in text it closes the editor, and in saving it does nothing.

It prints:

In menu, its own escape is taken: the deepest state wins. In text, which has no escape, the parent’s is taken and the editor closes. saving declares escape with no target and no actions: a forbidden transition. It is selected, so the search stops there and the parent’s escape is never looked at, and it changes nothing: the editor cannot be closed while it saves. Leaving the event out of saving would have let the parent take it.

An event that selects no transition, or only a forbidden one, changes nothing in its own microstep. The eventless transitions are still selected after it, with that event (Eventless transitions), so the macrostep settles at its first microstep with the snapshot unchanged unless one of them now passes, for example one whose guard reads the event. can(machine, snapshot, event), XState’s snapshot.can(event), says beforehand whether an event would take a transition that has a target or actions (Whether an event would do anything); for escape in saving it says no.

A target is written relative to the state that declares the transition, its source:

The root has no siblings, so a target declared on the root starts with . or #: "a" there is refused with unknown_target, as XState refuses it and suggests ".a".

A state’s id is its id member, or, without one, the machine’s id followed by the state’s path, joined by dots: in the machine below, #machine.b.two names the state two.

It prints:

a goes to its sibling b, and entering b, a compound state, enters its initial child one. one has no next, so the next of b is taken, to the state whose id is c, which enters child. c then goes to its own child other. reset, on the root, returns to a from anywhere, and deep names a child of a sibling, so b is entered at two instead of its initial child.

A transition may name several targets, as a list under target, when each is in a different region of a parallel state (Parallel states): it moves every region it names in one microstep. The list goes under target; a list in the place of the transition is a list of transitions, of which the first enabled is taken.

It prints:

set.dark.custom moves both regions. set.light names one target, yet it also sends theme back to default. A transition leaves every active state inside its domain: its source, when every target is inside the source and it does not reenter, or else the nearest state that contains the source and every target. It enters its targets, their ancestors up to the domain and, of each parallel state among those ancestors or the domain, every region that holds no target, at its initial state. set.light is declared on the root, so its domain is the root: it leaves both regions, and entering mode again under the parallel root enters theme at its initial state. Stately’s page on transitions says such a transition leaves the other region as it is; XState 5.33.2 resets it, and xstate does what XState does. To move one region and keep the others, declare the transition in that region: mode.light, in mode, has mode as its domain, and theme keeps custom.

A transition whose targets are inside its source, the source itself included, does not leave the source by default: the source’s exit and entry actions do not run, and the actors it invokes keep running. Only the states below the source are left and entered. With reenter: true the domain is above the source, so the source is left and entered again: its actions run, and its invoked actors are stopped and started again. A transition without a target leaves and enters no state, whatever its reenter says, as in XState.

A self-transition is one that stays in its source, and there are three kinds:

The machine below names an entry and an exit action for each state. None has an implementation, so each is returned to the caller in the order it runs (Custom actions), and the output shows what each transition left and entered. types_of, a helper of the program, writes the types of a list of actions as [a, b]:

It prints:

In XState v4 a re-entering transition was called external, and the default one internal.

The key of an on entry is an event descriptor: it says which event types its transitions take. Most descriptors are a type and match only that type. Two forms match more. A wildcard is a catch-all, for the events a state does not name; a partial descriptor handles a family of events named with a common prefix, such as every feedback. event, in one place:

* is a wildcard only as the whole descriptor, or as the last token after a dot when no earlier token is * itself. A * inside a longer token is a plain character: mou*se.* is a partial descriptor and matches mou*se.x. Any other descriptor that holds a *, such as mouse*, *.click, mouse.*.click or mouse.*.*, matches only an event of exactly that type. xstate writes no warning about any of them, where XState’s development build writes a console warning about a descriptor that ends in .* and holds another *, such as mouse.*.* or mou*se.*, the first time a state looks up the transitions of an event type (The checks of XState’s development build).

One event can match several descriptors of one state. Their transitions are tried in this order: those of the descriptor equal to the event’s type, then those of each matching wildcard descriptor, the longest first, so feedback.bad.* before feedback.* before *. The first enabled transition is taken, and only when none is does the search go up to the parent.

It prints:

feedback.bad is matched by feedback.bad.*, which is longer than feedback.*; feedbacks is not the token feedback, so only * matches it. Since the wildcard matches the machine’s own events too, a * transition in an active child state takes the xstate.after... event of its parent’s delayed transition before the parent sees it: the deepest state is tried first.

A guard is a condition a transition checks before it is taken: a guarded transition is enabled only when its guard passes. Guards let one event lead to different states depending on data: the event’s payload, the context, or the params the config gives the guard. A guard decides and changes nothing.

In XState a guard is a function, inline in the config or named in setup({ guards }). A JSON config cannot hold a function, so in xstate every guard is a name, and implementations.guards maps each name to a predicate: a function of the action_args every implementation receives, the context, the event and the params, that returns a result<bool>. A guard is written as its name, or as an object with a type, its name, and params, a JSON value that reaches the guard as args.params, null when the config gives none; guards with the same name share one implementation, and their params tell one use from another. XState’s params may also be a function of the context and the event, which JSON cannot hold: an xstate guard reads both from its args.

When one event has a list of transitions, they are tried in order, and the first enabled one is taken; a last transition without a guard is the default, taken when no guard before it passes. integer_at, a helper of the program, returns the integer a JSON object holds under a key, or none:

It prints:

A rating of 3 passes neither guard, so the default is taken. In form, an empty feedback does not pass isValid: no transition is enabled and the machine stays. A guard whose input is wrong, here a submit without feedback, returns an error rather than a guess, and the macrostep fails with it (When a guard cannot run): the last line is the snapshot it began from, form, its status error and its error implementation_failed. XState’s transition throws there instead, Unable to evaluate guard 'isValid' ..., followed by the message of the TypeError its guard raised (Failures are values).

An eventless transition is taken without an event: whenever its state is active and its guard passes, right after the microstep that made it so. It is declared under a state’s always, in any of the forms of a transition in on. It fits a change that follows from a condition rather than from a trigger: the kettle below boils when its temperature, which events update, goes above 100, whatever event raised it.

updateTemperature is an assign that copies the event’s temperature into the context (Updating context with assign); turnOffLight has no implementation, so it is a custom action, returned to the caller. isBoiling reads the context with integer_at, the helper of the quick start (Handle context data), which returns the integer an object holds under a key, or none. The example prints, for each event, every microstep of its macrostep, with the state value it left and the actions it returned, written by the types_of of Self-transitions and reenter:

It prints:

The first update raises the temperature to 105 while the kettle is lukewarm, which has no eventless transition: one microstep. boil takes two: its own transition to heating, and then, since the temperature is already above 100, the eventless transition of heating to boiling. The macrostep settles in boiling, so heating is a transient state there: the machine passes through it and never rests in it. The last update is a targetless transition of the root. Its microstep lowers the temperature in the context, and the eventless transitions, selected after every event’s microstep, now find that the guard of boiling passes.

The rules, which are XState’s:

A delayed transition is taken when its state has been active for a given time. It is declared under a state’s after, whose keys are delays and whose values are transitions in any of the forms of on. Leaving the state before the time has passed cancels it. Delayed transitions make timeouts and retries part of the machine.

A delay is written as a key of after:

A name the implementations do not hold is refused when the machine is created, with unknown_delay; XState takes such a delay as no delay at all, and the transition is taken in the same macrostep (A config is refused when it is created). A key that is not all digits and starts with a digit, a sign or a dot, such as "1.5", "-1" or "1e3", is refused with invalid_config, because time in xstate is whole milliseconds written as digits; XState reads "1e3" and "+5" as numbers (Time in whole milliseconds). A key that starts with a space is a name to xstate, where XState reads " 5" as 5.

Entry actions run on every transition that enters their state, exit actions on every transition that leaves it, and a transition’s actions on that transition. Each of entry, exit and a transition’s actions holds one action or a list of them. create_machine refuses a null one with invalid_config; XState reads it as a list that holds null, and fails when it runs it. A transition with no target runs its actions and nothing else: it leaves and enters no state, even with reenter: true. A transition whose target is its source or one of the source’s descendants does not leave the source either, and the source’s exit and entry actions run only when it sets reenter: true (Self-transitions and reenter).

The machine below lists a custom action at each place: exitAction when it leaves question, track on the transition, showConfetti when it enters thanks. None has an implementation, so each one is returned:

It prints:

The machine left question, took the transition, and entered thanks: the exit action first, then the transition’s, then the entry action.

A machine that only reacts to events, with no states, is written with transitions that have actions and no target (Assign is one; Self-transitions and reenter has the rules).

An action in a config is a string, its name, or an object with a type, its name, and optional params, a JSON value for that use of it. Actions with the same type share one implementation; their params tell one use from another. Here the transition lists two actions with params: track, which has no implementation, and addRating, an assign that adds its param by to the rating:

It prints:

track has no implementation: it is a custom action, returned with the params the config gave it. addRating is a built-in, an assign_action (Built-in and custom actions, Assign), so it changed the context and was not returned; its implementation read its params from args.params. showConfetti, written as a string, has no params, and its params is null.

Every action implementation, and every guard, delay and value maker, receives an action_args, which XState hands an action as ({ context, event }, params):

XState also takes params as a function of the context and the event, computed when the action runs. JSON holds no function, so xstate’s params are the fixed value the config writes. An implementation that needs the context or the event reads them from its action_args. A caller executing a custom action finds the event in the microstep that returned it, and the context as that whole microstep left it, after any assign listed after the action (How guards and actions read the context). A value that must be computed at the action’s turn is computed by a registered implementation (Actions).

Each built-in action is one alternative of action_implementation, registered under the name the config uses, with XState’s arguments as its members. The machine core resolves it as XState resolves the action creator and returns it as XState’s transition() returns it: an action of the same type xstate.*, whose params are XState’s less what is not JSON or has no value. An actor reference is left out, and a targetId or an id names the actor instead; an id, a delay or a label with no value is left out.

There are two exceptions, both sends whose receiver depends on where the machine runs. XState’s pure functions run the machine as an inert actor, which has no parent and a fresh system of its own; xstate’s core returns the send for its caller to resolve: