# machina

> Focused finite state machine library for JavaScript and TypeScript. Two factory functions — `createFsm` for single-client FSMs and `createBehavioralFsm` for multi-client FSMs — with TypeScript-inferred state names, return-based transitions, and hierarchical child FSM delegation. States in, states out.

machina v7 is TypeScript-first. Handlers receive `{ ctx, inputName, defer, emit }` as a destructured args object (no `this` binding). Return a state name to transition; return nothing to stay put. String shorthand (`timeout: "yellow"`) handles unconditional transitions. State names, transition targets, `handle()` inputs, and `defer({ until })` targets are all validated at compile time — every config shape, including empty and lifecycle-only states. Hierarchies are typed too: a parent's `handle()` accepts its children's inputs at any depth, and an FSM can declare the inputs it `bubbles` up to whatever mounts it, checked at the `_child` mounting site.

- [Source code](https://github.com/ifandelse/machina.js): GitHub repository
- [npm package](https://www.npmjs.com/package/machina): Install with `npm install machina`

## Guide

- [Introduction](https://machina-js.org/guide/introduction/): What machina is, design philosophy, comparison with XState, what's new in v6
- [Getting Started](https://machina-js.org/guide/getting-started/): Quick start with createFsm — install, configure, handle inputs
- [Concepts](https://machina-js.org/guide/concepts/): Mental model — states, inputs, handlers, transitions, context, lifecycle hooks, deferred input, disposal
- [createFsm](https://machina-js.org/guide/fsm/): Single-client FSM — config, handler signatures, full public API, TypeScript inference, complete example
- [createBehavioralFsm](https://machina-js.org/guide/behavioral-fsm/): Multi-client FSM — one definition serving many independent clients, WeakMap-based state tracking, client-scoped events
- [Hierarchical States](https://machina-js.org/guide/hierarchical/): Child FSMs via _child, any-depth input delegation and bubbling, declaring bubbled inputs (bubbles) with a compile-time coverage contract, compositeState(), auto-reset on parent re-entry
- [Events](https://machina-js.org/guide/events/): Lifecycle events (transitioning, transitioned, handling, handled, nohandler, invalidstate, deferred), wildcard subscribers, custom events
- [Deferred Input](https://machina-js.org/guide/defer/): Queueing inputs for replay — targeted defer, untargeted defer, replay mechanics, per-client queues in BehavioralFsm

## Examples

- [Connectivity](https://machina-js.org/examples/connectivity/): Single-client FSM with async health checks, timers, and AbortController cleanup
- [Traffic Intersection](https://machina-js.org/examples/traffic-intersection/): Hierarchical FSMs — parent controlling phases, child sub-phases, deferred pedestrian requests
- [Dungeon Critters](https://machina-js.org/examples/dungeon-critters/): BehavioralFsm with 100+ independent game entities sharing one FSM definition
- [Shopping Cart](https://machina-js.org/examples/shopping-cart/): Deferred input patterns — targeted defer across multiple transitions, error recovery with catch-all defer
- [React Integration](https://machina-js.org/examples/with-react/): useReducer pattern, event subscriptions in effects, per-component FSM instances
- [machina-explorer](https://machina-js.org/examples/machina-explorer/): Interactive FSM inspector and state diagram visualizer — paste a config, run structural checks, render a mermaid stateDiagram-v2

## Tools

- [machina-inspect](https://machina-js.org/tools/machina-inspect/): Static analysis for FSM configs — builds a directed graph IR, runs structural checks (unreachable states, _onEnter loops, missing handlers), exports graph for downstream tools
- [machina-test](https://machina-js.org/tools/machina-test/): Jest/Vitest testing tools — graph topology matchers (toHaveNoUnreachableStates, toAlwaysReach, toNeverReach) and `walkAll` for property-based runtime testing with randomized inputs, seeded PRNG for deterministic replay, payload generators, and invariant checking after every transition
- [ESLint Plugin](https://machina-js.org/tools/eslint-plugin/): eslint-plugin-machina — surfaces machina-inspect findings inline in your editor via ESLint 9 flat config. Three rules: unreachable-state (warn), onenter-loop (error), missing-handler (off)

## Migration

- [v6 to v7 Migration](https://machina-js.org/migration/v6-to-v7/): What breaks and why — stricter validation surfacing latent typos, defer({ until }) narrowing, any-depth delegation behavior change, bubbles + the wiring contract
- [v4 to v6 Migration](https://machina-js.org/migration/v5-to-v6/): Complete translation guide — handler signatures, config changes, method mapping, event changes, removed features

## Optional

- [API Reference](https://machina-js.org/api/): Auto-generated TypeDoc API documentation — classes, interfaces, type aliases