Function: crawlMachine()

Documentation / @xmachines/play-router / crawlMachine

function crawlMachine(machine): StateVisit[];

Defined in: crawl-machine.ts:74

Crawl state machine graph using breadth-first traversal

Visits all state nodes in the machine, including deeply nested states, and returns complete list of visits with path and parent information. This enables systematic discovery of all states for route extraction and tree building.

Architectural Context: Implements Actor Authority (INV-01) by extracting routing information from the state machine definition rather than external configuration. The BFS traversal ensures all nested states are discovered, enabling the Actor to define the complete navigation structure through its machine definition.

Parameters

Parameter	Type	Description
machine	AnyStateMachine	XState v5 state machine to crawl

Returns

StateVisit[]

Array of state visits in breadth-first order

Examples

Basic machine crawl

import { createMachine } from "xstate";
import { crawlMachine } from "@xmachines/play-router";

const machine = createMachine({
  initial: "home",
  states: {
    home: {},
    dashboard: {
      initial: "overview",
      states: {
        overview: {},
        settings: {},
      },
    },
  },
});

const visits = crawlMachine(machine);
// Returns visits for: root, home, dashboard, dashboard.overview, dashboard.settings
console.log(visits.map((v) => v.path.join(".")));
// ['', 'home', 'dashboard', 'dashboard.overview', 'dashboard.settings']

Extract state paths and parents

import { crawlMachine } from "@xmachines/play-router";

const visits = crawlMachine(machine);
visits.forEach((visit) => {
  console.log({
    path: visit.path.join(".") || "root",
    hasParent: !!visit.parent,
    hasChildren: Object.keys(visit.node.states).length > 0,
  });
});

See

• RFC Play v1
• extractRoute for extracting route from individual states
• extractMachineRoutes for complete route extraction
• StateVisit for visit structure

Remarks

BFS Traversal: Breadth-first search ensures systematic discovery of all states at each nesting level before descending deeper. This produces a predictable ordering useful for route tree construction and debugging.

Path Format: Paths use array notation (['dashboard', 'settings']) which can be joined with dots for state IDs ('dashboard.settings') matching XState’s hierarchical state naming convention.