xstate

XState

Treat a statechart as an executable ownership model for time, concurrency, and resource lifetimes.

Recognise a hand-rolled statechart

Each of the following is a lifecycle already being modelled by hand:

• a useState flag for work in flight: isSubmitting, isLoading, pending;
• a .then, .catch, or await block that sets two or more pieces of state in sequence;
• a re-entry guard such as if (submitting) return;
• a line that clears an error or a stale result before a retry;
• a useEffect that starts asynchronous work and needs an ignore flag in its cleanup;
• two booleans that must never both be true, such as isLoading with error;
• a setTimeout or setInterval for retry, debounce, or polling that something must clear;
• a pointerdown, dragstart, or gesture handler that binds listeners to the document and must unbind them;
• handling for a response that arrives after cancel, replacement, or unmount.

Any one of them is the entry point to step 1, however small the request, and whether or not the file imports xstate. When the code already exists, name each defect it has today and the wrong behaviour a user would see, before you propose the machine that removes it.

For a visualisation-only request, inspect the current machine source and go to step 6 instead.

1. Establish the temporal boundary

Inventory the mounted journey, external authority, live resources, concurrent concerns, retry and cancellation policy, and every source of stale or duplicate work. Inspect existing actors and runtime integrations, and confirm the installed XState major version; the XState 4 and 5 APIs differ.

Use XState only where ordering, concurrency, retries, cancellation, stale results, or resource lifetimes make the behaviour temporal. Two tests find that lifetime; classify by what they show, not by what the state renders.

First, an external answer — a network response, a timer, another actor, the platform — makes state temporal whatever it looks like on screen. A disabled button or a spinner is the presentation of temporal state, not presentation state.