@simplystated/f-of-xstate ·

Tools for operating on XState state machines as data.

Query and update your statechart structure.

Pronounciation

Eff of ex state. As in: f(x-state), because it's a set of utilities to operate on XState state charts as data.

Motivation

Statecharts are awesome. A lot of that reputation comes from the fact that they make it far easier to reason about your logic, making hard problems tractable. However, one of the too-often overlooked benefits of representing your logic as data is that once you do that... well... your logic is data! Once your logic is data, you can live out every lisp programmer's dream and write programs to inspect, modify, and even generate your programs. That's where f-of-xstate comes in. We aim to provide a set of utilities to make that easy.

Quickstart

You can play around with f-of-xstate in your browser in this codesandbox.

Installation

yarn add @simplystated/f-of-xstate

or

npm install --save @simplystated/f-of-xstate

API Documentation

Please find our API Documentation here.

Testing

f-of-xstate ships with a fast-check Arbitrary to generate random XState state machine configurations (e.g. the things you can pass to createMachine).

The intention is that this should make it easier to use property-based testing to gain confidence in the correctness of your state machine transformations. All of the functions exposed in this package make use of this arbitrary for testing. You can find examples here.

You can find the documentation for the machine arbitrary here.

Note: arbitraryMachine is not exported from index of f-of-xstate because it is intended to be used for testing and we didn't want to mix it with production code. You can import it as:

import { arbitraryMachine } from "@simplystated/f-of-xstate/dist/arbitrary-machine"

One highly useful thing to do is to open a terminal and look at a few of these:

import { arbitraryMachine } from "@simplystated/f-of-xstate/dist/arbitrary-machine"
import * as fc from "fast-check";
console.log(JSON.stringify(fc.sample(arbitraryMachine, 5), null, 2));

Querying

Given a StateMachine (e.g. something returned from XState's createMachine), you can query for the following, each of which walks the tree of state nodes and returns an array of all items encountered:

• getAllStates
• getAllProperStates
• getAllActions
• getAllConditions
• getAllInvocations
• getAllTransitions

Transforming

Given a StateMachine, f-of-xstate provides utilities to map over its states, supplying a function to transform each state to produce a new machine config (suitable to pass to createMachine).

See:

• mapStates

f-of-xstate also provides some utility mappers for common transformations that can be used with mapStates:

• filterMapStates
• mapTransitions
• filterTransitions
• appendTransitions
• appendActionsToAllTransitions

Example:

import { createMachine, actions } from "xstate";
import { mapStates, filterMapStates, appendActionsToAllTransitions } from "@simplystated/f-of-xstate";
const machine = createMachine(...);
const config = mapStates(
  machine,
  filterMapStates(
    (state) => state.id === "stateToLog",
    appendActionsToAllTransitions([
      actions.log((_, evt) => `Hello ${evt.type}`)
    ])
  )
);
// The updated machine will now log `Hello <event>` for every event on the "stateToLog" state.
const updatedMachine = createMachine(config);

Simply Stated

f-of-xstate is a utility library built by Simply Stated. At Simply Stated, our goal is to help to unlock the power of statecharts for everyone.

License

f-of-xstate is MIT licensed.