@doeixd/machine

A TypeScript state-machine library built around immutable snapshots and typestate.

The core runtime is deliberately small: a machine is an object with a context property and transition methods. A transition returns the next machine snapshot. TypeScript can then represent different states as different types, making invalid transitions unavailable at compile time.

If you already know what you need, jump to the main API or task-oriented documentation map. For the design behind the API, continue with the core tenets below.

Install

npm install @doeixd/machine

Node 18 or newer is supported. React and Solid are optional peer dependencies used only by their framework entry points.

Documentation

| Topic | Guide | | --- | --- | | Public API and supported behavior | Supported API | | Mathematical model and guarantee boundaries | State machines from first principles | | Factories, classes, and this behavior | Factories, transition binding | | Async work and ownership | Cancellation, actors | | Multi-machine coordination | Ensembles | | Class-based external-store façade | StoreMachine | | Nested and conditional behavior | Composition guide, guards | | Transition policies | Middleware | | Pattern matching | Advanced matcher, matcher API | | Composition | Nested and conditional machines, delegation, higher-order machines, mixins | | Package entry points | Published modules | | Diagrams and formal output | Statechart extraction |

The complete documentation map also separates supported guides from design notes and historical essays.

The Core Tenets of a State Machine

The central idea of this library is deliberately plain: a machine is a state snapshot with typed functions that return the next snapshot. The API follows the mathematical model instead of hiding it behind a configuration language.

For a classic finite-state machine (S, Σ, δ, s₀, F):

| Formal part | Representation in this library | | --- | --- | | S — control states | A finite union of typestates, tagged objects, or state classes. Each variant exposes only the transitions valid from that state. | | Σ — inputs | Transition method names plus their typed arguments: login(username), resolve(data), and so on. Event objects are available when a runner or actor needs message dispatch. | | δ — transition function | The transition methods themselves. Given the current snapshot and input, each returns the next snapshot. In typestate models this is intentionally a partial function: an invalid transition is absent rather than represented by a failing string lookup. | | s₀ — initial state | The initial snapshot passed to createMachine() or a runner. | | F — final states | Optional terminal typestates with no outgoing transitions. The library does not require every machine to have a final state. |

Real applications usually need an extended state machine: a small, finite set of control states plus data such as a username, count, or response. That data lives under context. Its values need not be finite; the typestate union remains the finite control model.

This mapping drives the design:

• State is explicit. A returned machine is a complete snapshot, so history is not ambient hidden state.
• Valid transitions are structural. If a loading state cannot load again, its TypeScript type simply has no load method.
• Inputs are ordinary function arguments. Refactoring, parameter checking, and autocomplete use normal TypeScript rather than parallel string schemas.
• The core stays executable. Guards can be conditions, actions can be function calls, and transitions can use the rest of the language.
• Analysis is opt-in metadata. When diagrams or formal statecharts matter, annotations describe the same executable transition instead of creating a second machine definition.

There are honest limits to these guarantees. TypeScript checks the model at compile time, but JavaScript can still mutate nested data, read global state, perform effects, or return nondeterministic results. Immutability, determinism, and the Markov property—depending only on the current snapshot and input—are design rules supported by the API, not runtime laws enforced by it.

Read State machines from first principles for the formal model and the exact boundary of these guarantees.

Main API

Main-API machines store data under context.

import { createMachine } from '@doeixd/machine';

const counter = createMachine({ count: 0 }, (next) => ({
  increment() {
    return next({ count: this.context.count + 1 });
  },
  add(amount: number) {
    return next({ count: this.context.count + amount });
  },
}));

const updated = counter.increment().add(4);

console.log(counter.context.count); // 0
console.log(updated.context.count); // 5

The factory form is recommended because it preserves the transition set without manually passing it to every new snapshot. The traditional transition-object overload remains supported.

See the supported API, factory guide, and this binding guide for the available construction forms and composition rules.

Explicit typestates

import { createMachine, type TypeState } from '@doeixd/machine';

type LoggedOut = TypeState<{ status: 'loggedOut' }, {
  login(username: string): LoggedIn;
}>;

type LoggedIn = TypeState<{ status: 'loggedIn'; username: string }, {
  logout(): LoggedOut;
}>;

Each state type lists only its valid transitions. The compiler, rather than a runtime string table, rejects calls to transitions that do not exist on the current state.

Async transitions and cancellation

runMachine owns the current async snapshot and dispatches typed events. Starting another transition aborts the previous in-flight transition.

import {
  createAsyncMachine,
  runMachine,
  type TransitionOptions,
} from '@doeixd/machine';

const machine = createAsyncMachine({ value: 0 }, {
  async load(amount: number, { signal }: TransitionOptions) {
    const response = await fetch(`/value?amount=${amount}`, { signal });
    const value = await response.json() as number;
    return createAsyncMachine({ value }, this);
  },
});

const runner = runMachine(machine);
await runner.dispatch({ type: 'load', args: [5] });
console.log(runner.state.value);

runner.stop();

runner.state is the current context, not the entire machine. The dispatch result is the entire next machine.

See Async cancellation for dispatch ordering, AbortSignal, stale results, and shutdown behavior.

Actors

Actors add queued async dispatch, subscriptions, and stable RPC-style actions.

import { createActor } from '@doeixd/machine';

const actor = createActor(counter);
const unsubscribe = actor.subscribe((state) => {
  console.log(state.context.count);
});

actor.send.increment();
unsubscribe();

See Actors for mailbox ordering, lifecycle, inspection, and promise or observable adapters.

Advanced matching

createMatcher turns a machine union into three complementary APIs: a callable state classifier, reusable type guards, and exhaustive case handling.

import {
  MachineBase,
  classCase,
  createMatcher,
} from '@doeixd/machine';

class Idle extends MachineBase<{ status: 'idle' }> {}
class Loading extends MachineBase<{ status: 'loading'; startedAt: number }> {}
class Success extends MachineBase<{ status: 'success'; data: string }> {}
class Failed extends MachineBase<{ status: 'error'; error: Error }> {}

type FetchMachine = Idle | Loading | Success | Failed;

const matchFetch = createMatcher(
  classCase('idle', Idle),
  classCase('loading', Loading),
  classCase('success', Success),
  classCase('error', Failed),
);

function describeFetch(snapshot: FetchMachine): string {
  matchFetch(snapshot); // 'idle' | 'loading' | 'success' | 'error' | null

  if (matchFetch.is.success(snapshot)) {
    console.log(snapshot.context.data); // narrowed to Success
  }

  return matchFetch.when(snapshot).is(
    matchFetch.case.idle(() => 'Ready'),
    matchFetch.case.loading(state => `Started at ${state.context.startedAt}`),
    matchFetch.case.success(state => `Loaded: ${state.context.data}`),
    matchFetch.case.error(state => `Failed: ${state.context.error.message}`),
    matchFetch.exhaustive,
  );
}

Omitting a case makes the inferred result an error type instead of string. For discriminated contexts, forContext<ContextUnion>() provides concise case builders; customCase accepts arbitrary type-guard predicates. See the matcher API and matcher module.

Middleware and orchestration

The main entry also exports:

• transition middleware, validation, retry, history, snapshots, and time travel;
• createRunner for a stable imperative façade over immutable snapshots;
• createEnsemble for coordinating multiple machine domains through shared external state;
• createStoreMachine for class methods over read-only live fields from an external store;
• pattern matching for class states and discriminated contexts;
• class and functional mixins;
• generator-based transition composition.

These are optional layers. They are not required to use the core machine factories.

Continue with Middleware, conditional transitions, or the higher-order machine guide.

React

import { createMachine, useMachine } from '@doeixd/machine/react';

const initial = createMachine({ count: 0 }, (next) => ({
  increment() {
    return next({ count: this.context.count + 1 });
  },
}));

function Counter() {
  const [machine, actions] = useMachine(() => initial);
  return <button onClick={actions.increment}>{machine.context.count}</button>;
}

See the React API notes for selectors, contexts, ensembles, and actor hooks.

Solid

The Solid entry exports reactive helpers. Import non-reactive factories from the package root.

import { createMachine as createCoreMachine } from '@doeixd/machine';
import { createMachine } from '@doeixd/machine/solid';

const initial = () => createCoreMachine({ count: 0 }, (next) => ({
  increment() {
    return next({ count: this.context.count + 1 });
  },
}));

function Counter() {
  const [machine, actions] = createMachine(initial);
  return <button onClick={actions.increment}>{machine().context.count}</button>;
}

Solid action objects are stable and resolve transitions against the current snapshot. Calling an action that is unavailable in the current typestate throws a descriptive runtime error.

See the Solid API notes for stores, selectors, batching, contexts, async ownership, and effects.

Minimal API

The optional @doeixd/machine/minimal entry uses flat snapshots: state and transitions live on the same object.

import { machine } from '@doeixd/machine/minimal';

const counter = machine({ count: 0 }, (state, next) => ({
  increment: () => next({ count: state.count + 1 }),
  add: (amount: number) => next({ count: state.count + amount }),
}));

const updated = counter.increment().add(4);

console.log(counter.count); // 0
console.log(updated.count); // 5

Use factory() when the same machine should be instantiated with different initial data. Use union() with tagged states when each state has a different set of transitions.

import { tag, type States, union, type UnionOf } from '@doeixd/machine/minimal';

type FetchState = States<{
  idle: {};
  loading: { url: string };
  success: { data: string };
}>;

const State = tag.enum<FetchState>()(
  tag('idle'),
  tag('loading'),
  tag('success'),
);

const createFetch = union<FetchState>()({
  idle: (_state, next) => ({
    load: (url: string) => next(State.loading({ url })),
  }),
  loading: (_state, next) => ({
    resolve: (data: string) => next(State.success({ data })),
    cancel: () => next(State.idle()),
  }),
  success: (_state, next) => ({
    reset: () => next(State.idle()),
  }),
});

type FetchMachine = UnionOf<typeof createFetch>;

const first: FetchMachine = createFetch(State.idle());
const second = first.load('/api/data');
// second.load(...) is a type error: loading states do not have `load`.
// State.loading() is a type error: `url` is required by FetchState.

tag.enum(tag('one'), tag('two')) is also available when each factory should infer an open-ended payload at the call site. The generic, curried form shown above constrains every payload and definition name to an existing States<...> member. See Tagged helpers for both modes.

The main and minimal APIs intentionally use different snapshot shapes; their examples are not interchangeable without adjusting property access. See docs/minimal.md for factories, tagged unions, exhaustive matching, lifecycle hooks, child composition, and the exact boundary of this smaller runtime.

Published modules

Every entry below is built as ESM and CommonJS and includes TypeScript declarations. npm run build fails if any configured export target is missing.

| Subpath | Purpose | | --- | --- | | @doeixd/machine | Complete main API | | @doeixd/machine/core | Main API without React or Solid helpers | | @doeixd/machine/minimal | Flat typestate API | | @doeixd/machine/actor | Actors, spawning, promises, and observables | | @doeixd/machine/adapters | EventTarget, EventEmitter, and Observable adapters | | @doeixd/machine/base | MachineBase only | | @doeixd/machine/context-bound | Context-bound transition helpers | | @doeixd/machine/delegate | Child-transition delegation | | @doeixd/machine/devtools | Browser DevTools connection helper | | @doeixd/machine/extract | Programmatic static statechart extraction | | @doeixd/machine/functional-combinators | Functional construction and transition combinators | | @doeixd/machine/generators | Generator-based transition sequences | | @doeixd/machine/higher-order | Higher-order machine transformations | | @doeixd/machine/matcher | Reusable typed pattern matching | | @doeixd/machine/middleware | Middleware, composition, history, snapshots, and time travel | | @doeixd/machine/mixins | Class and functional machine composition | | @doeixd/machine/multi | Runners, ensembles, and multi-machine coordination | | @doeixd/machine/primitives | Guards and metadata annotations | | @doeixd/machine/runtime-extract | Statechart metadata extraction from live instances | | @doeixd/machine/types | Tagged-state runtime and type helpers | | @doeixd/machine/utils | Events, context helpers, binding, and sequences | | @doeixd/machine/react | React integration | | @doeixd/machine/solid | Solid integration |

Focused subpaths are useful when you want an explicit dependency boundary or a smaller direct bundle. Files such as internal-transitions.ts, entry-react.ts, and entry-solid.ts are implementation details and are deliberately not public subpaths.

See the published module guide for the main exports, intended use, and caveats of each entry point.

Statechart extraction

Metadata helpers annotate transition functions for runtime or build-time extraction. The metadata decorators (transitionTo, describe, guarded, invoke, action, and metadata) support direct and curried forms, and pipe applies the curried operators from left to right. Runtime-enforcing guards retain their direct and fluent APIs.

import { action, describe, pipe, transitionTo } from '@doeixd/machine';

class Loading {}

class Idle {
  start = pipe(
    () => new Loading(),
    transitionTo(Loading),
    describe('Start loading'),
    action({ name: 'recordStart' }),
  );
}

The equivalent nested form remains supported:

const start = describe(
  'Start loading',
  transitionTo(Loading, () => new Loading()),
);

Metadata usually belongs to a transition—the edge between snapshots—so the recommended API is the standalone pipe(value, ...operators), not a .pipe() method added to every machine. Transition decorators keep the original call signature, while annotations are attached as non-enumerable runtime metadata and represented in the TypeScript type. The generic metadata({...}) operator can annotate any object or function, including a complete machine snapshot, without changing its identity. Later pipe operators are the outer decorators; for repeated actions or guards, their metadata therefore appears first.

Run the extractor in this repository with:

npm run extract

From an installed package:

npx --package @doeixd/machine extract --config .statechart.config.ts --validate

The CLI supports JSON, Mermaid, or both, and validates generated JSON against the bundled schema when requested. See docs/statechart-extraction.md.

Immutability and safety guarantees

• Transition helpers return new snapshots by convention and by their types.
• context is typed as readonly at the machine-property level.
• Context objects are not recursively frozen at runtime.
• Methods can still perform side effects; purity is a design rule, not something JavaScript can enforce.
• Runtime controllers validate missing transitions, but most transition validity comes from TypeScript.

Avoid describing the library as “zero runtime” or claiming that immutability and purity are enforced. The core is small, but actors, middleware, extraction, and framework adapters intentionally add runtime behavior.

See Mutability boundaries for practical guidance on immutable snapshots, nested data, and integration points that require mutation.

Development

npm install
npm test
npm run type-check
npm run build
npm run verify:package
npm run extract

npm run build cleans old output, produces ESM/CommonJS/declaration bundles for every configured entrypoint, and verifies the package export map. npm run verify:package can also be run independently after a build.

See docs/README.md for the documentation map and docs/api.md for the supported public surface.

License

MIT