xstate 6.0.0-alpha.8 → 6.0.0-beta.0

package/docs/index.md

@@ -0,0 +1,74 @@
+# XState 6.0.0-beta.0
+
+These docs match the installed xstate package. Start with the [quick start](quick-start.md) or the [agent guide](agents.md).
+For differences from v5, read the [migration guide](xstate-v5-to-v6.md).
+The [export stability manifest](api-stability.json) classifies the installed source's public, experimental and internal exports.
+
+- [Quick start](quick-start.md)
+- [Agent guide](agents.md)
+- [Choose XState](choose-xstate.md)
+- [Use with your framework](frameworks.md)
+- [Examples](examples.md)
+- [Why state machines?](why-state-machines.md)
+- [Your first machine](your-first-machine.md)
+- ['Tutorial: build a media player'](tutorial.md)
+- [States, events and transitions](states-events-transitions.md)
+- [Data and effects](data-and-effects.md)
+- [Async logic](async-logic.md)
+- [Actors](actors.md)
+- [Statecharts](statecharts.md)
+- [How XState runs your machine](how-xstate-runs-machines.md)
+- [Model application behavior](modeling.md)
+- [Handle async requests](async-requests.md)
+- [Add retries and timeouts](retries-and-timeouts.md)
+- [Cancel async work](cancellation.md)
+- [Build forms and wizards](forms-and-wizards.md)
+- [Run backend workflows](backend-workflows.md)
+- [Durable execution](durable-execution.md)
+- [Persist and restore actors](persist-and-restore-actors.md)
+- [Test XState logic](testing.md)
+- [Model-based testing](model-based-testing.md)
+- [Inspect actor systems](inspect-actor-systems.md)
+- [Troubleshooting](troubleshooting.md)
+- [Error codes](errors.md)
+- [Machine configuration](configuration.md)
+- [Compact finite state machines](fsm.md)
+- [Setup and provide](setup-and-provide.md)
+- [States](states.md)
+- [Transitions](transitions.md)
+- [Transition functions and graph analysis](transition-functions.md)
+- [Context](context.md)
+- [Input and output](input-output.md)
+- [State input](state-input.md)
+- [Actions](actions.md)
+- [Guards](guards.md)
+- [Delays](delays.md)
+- [Timeouts](timeouts.md)
+- [Internal events](internal-events.md)
+- [Choice states](choice-states.md)
+- [Route states](route-states.md)
+- [Final states](final-states.md)
+- [History states](history-states.md)
+- [Parallel states](parallel-states.md)
+- [Create actors](create-actor.md)
+- [Actor snapshots](snapshots.md)
+- [Selectors](selectors.md)
+- [Invoke actors](invoke.md)
+- [Spawn actors](spawn.md)
+- [Actor logic](actor-logic.md)
+- [Emitted events](emitted-events.md)
+- [Listen and subscribe to actors](listen-and-subscribe.md)
+- [Actor systems](systems.md)
+- [Pure system transitions](system-transitions.md)
+- [Lifecycle and errors](lifecycle-and-errors.md)
+- [TypeScript](typescript.md)
+- [Typestates](typestates.md)
+- [Persistence](persistence.md)
+- [Serialization](serialization.md)
+- [SCXML](scxml.md)
+- [Inspection](inspection.md)
+- [Utilities](utilities.md)
+- [Cheatsheet](cheatsheet.md)
+- [Frequently asked questions](faq.md)
+- [Glossary](glossary.md)
+- [Migrate from XState v5 to v6](xstate-v5-to-v6.md)

package/docs/input-output.md

@@ -0,0 +1,69 @@
+---
+title: Input and output
+description: Pass input to actors and read output when they complete.
+---
+
+Input provides data when an actor is created.
+
+```ts
+const greetingMachine = createMachine({
+  context: ({ input }: { input: { name: string } }) => ({ name: input.name })
+});
+
+const greeting = createActor(greetingMachine, {
+  input: { name: 'Ada' }
+}).start();
+```
+
+When a machine declares `schemas.input` (directly or through `setup(...)`) and the input type does not accept `undefined`, `createActor` requires the `input` option. Restoring a persisted snapshot with `restoreActor(...)` does not take it.
+
+## Final output
+
+```ts
+const machine = createMachine({
+  context: { result: 42 },
+  initial: 'working',
+  states: {
+    working: { on: { finish: { target: 'done' } } },
+    done: { type: 'final' }
+  },
+  output: ({ context }) => ({ result: context.result })
+});
+```
+
+Read output from a completed snapshot or an invocation's done event.
+
+Input configures one actor instance. Output reports its final result.
+
+- An invoice actor can receive a currency and line items as input, then output the calculated total.
+- A file-processing actor can receive a file key as input, then output the generated asset URL.
+
+Actors that run indefinitely may never produce output.
+
+## TypeScript
+
+Declare input and output schemas when they cross actor boundaries.
+
+The output type is inferred from the root `output` when `schemas.output` is not declared. Without a root `output`, the type is the union of the top-level final states' output types. A declared `schemas.output` is authoritative and the root `output` is checked against it.
+
+```ts
+const machine = setup({}).createMachine({
+  context: { shipped: ['sku-1'] },
+  initial: 'done',
+  states: { done: { type: 'final' } },
+  output: ({ context }) => ({
+    status: 'shipped' as const,
+    skus: context.shipped
+  })
+});
+
+// OutputFrom<typeof machine> is { status: 'shipped'; skus: string[] }
+```
+
+## Input and output cheatsheet
+
+```ts
+context: ({ input }) => ({ value: input.value })
+output: ({ context }) => ({ value: context.value })
+createActor(machine, { input: { value: 1 } });
+```

package/docs/inspect-actor-systems.md

@@ -0,0 +1,118 @@
+---
+title: Inspect actor systems
+description: Log transitions in development and attach them to error reports.
+---
+
+An inspector passed to the root actor observes the whole system: the root actor, every invoked or spawned child, and every transition. This guide uses it for a development log and for telemetry.
+
+> **Experimental:** the inspection event types (`InspectionEvent`, `ActorInspectionEvent`, `TransitionInspectionEvent`) may change in a minor release.
+
+## 1. Attach an inspector in development only
+
+Inspection runs on every transition, so keep it out of production builds. Pass `undefined` and `createActor(...)` behaves as if no inspector were given.
+
+```ts
+import { createActor, type InspectionEvent } from 'xstate';
+
+const isDev = process.env.NODE_ENV !== 'production';
+
+const checkout = createActor(checkoutMachine, {
+  inspect: isDev ? inspect : undefined
+}).start();
+```
+
+## 2. Log transitions readably
+
+Inspection emits two events: `@xstate.actor` when an actor is created and `@xstate.transition` when one takes a transition. Events that could not be delivered go to the `onRejectedEvent` option instead. Filter to the type you need, then print the event that arrived and the state it produced.
+
+Transitions identify their actor by `actorRef.sessionId`, which is unique but not readable. `@xstate.actor` carries the actor's `id`, so keep a map of names as actors appear.
+
+```ts
+const names = new Map<string | undefined, string>();
+
+function inspect(inspectionEvent: InspectionEvent) {
+  if (inspectionEvent.type === '@xstate.actor') {
+    names.set(inspectionEvent.actorRef.sessionId, inspectionEvent.id);
+    return;
+  }
+
+  const { actorRef, eventType, snapshot } = inspectionEvent;
+  const value = 'value' in snapshot ? snapshot.value : snapshot.status;
+
+  console.log(
+    `[${names.get(actorRef.sessionId)}] ${eventType} → ${JSON.stringify(value)}`
+  );
+}
+```
+
+The root actor's first transition is `xstate.init`, so the log starts with the initial state. Only machine snapshots have a `value`; a child running async logic reports its `status` instead. A `sessionId` is assigned once an actor starts, which is why the map allows `undefined` keys.
+
+Filter further when a system is noisy. An early `if (!eventType.startsWith('payment.')) return;` keeps payment activity and drops everything else.
+
+## 3. Inspect the whole tree
+
+One inspector on the root covers the system. Every event carries `rootId` for the system and `actorRef.sessionId` for the actor within it, so two children with the same `id` are still distinguishable.
+
+`@xstate.actor` announces each actor and its parent before it transitions, which is enough to draw the tree up front:
+
+```ts
+function logActors(inspectionEvent: InspectionEvent) {
+  if (inspectionEvent.type !== '@xstate.actor') return;
+
+  const { parentRef, id } = inspectionEvent;
+
+  console.log(parentRef ? `${names.get(parentRef.sessionId)} → ${id}` : id);
+}
+```
+
+## 4. Forward transitions to telemetry
+
+Keep the last transition per actor and attach it to error reports. The report then says which state the actor was in and which event got it there.
+
+```ts
+const lastTransitions = new Map<
+  string | undefined,
+  { event: unknown; value: unknown }
+>();
+
+const actor = createActor(checkoutMachine, {
+  inspect: (inspectionEvent) => {
+    if (inspectionEvent.type !== '@xstate.transition') return;
+
+    const { actorRef, event, snapshot } = inspectionEvent;
+
+    lastTransitions.set(actorRef.sessionId, {
+      event,
+      value: 'value' in snapshot ? snapshot.value : snapshot.status
+    });
+  }
+}).start();
+
+actor.subscribe({
+  error: (error) => {
+    reportError(error, {
+      lastTransition: lastTransitions.get(actor.sessionId)
+    });
+  }
+});
+```
+
+Redact before sending. Events and context often carry addresses, card details and tokens.
+
+> **Warning:** An inspector observes; it must not change application state. Send events from your machine, not from an inspector.
+
+## 5. Use the visual inspector
+
+[`@statelyai/inspect`](https://github.com/statelyai/inspect) consumes the same inspection events and draws the running system as a statechart instead of a log.
+
+```bash
+npm install @statelyai/inspect
+```
+
+Create its inspector and pass it to the same `inspect` option, in development only.
+
+## What next?
+
+- [Inspection](inspection.md) for every property on each inspection event type.
+- [Listen and subscribe](listen-and-subscribe.md) for reading actor state in application code.
+- [Systems](systems.md) for how actors are related within a system.

package/docs/inspection.md

@@ -0,0 +1,75 @@
+---
+title: Inspection
+description: Observe actor systems and transitions.
+---
+
+Pass an inspector to the root actor with the `inspect` option.
+
+> **Experimental:** the inspection event types (`InspectionEvent`, `ActorInspectionEvent`, `TransitionInspectionEvent`) may change in a minor release.
+
+```ts
+const actor = createActor(machine, {
+  inspect: (inspectionEvent) => {
+    console.log(inspectionEvent.type, inspectionEvent);
+  }
+});
+```
+
+Inspection emits two event types:
+
+| Type | Contains |
+| --- | --- |
+| `@xstate.actor` | Actor identity and parent information. |
+| `@xstate.transition` | The event, snapshot, source, target and microsteps. |
+
+Both event types carry `rootId`, the session ID of the root actor, and `actorRef`, the actor the event is about. Session IDs are unique across actors, so `rootId` identifies the system and `actorRef.sessionId` identifies an actor within it.
+
+`@xstate.actor` announces every created actor: the root actor and each spawned or invoked child. It is the only topology event, so an inspector can draw the actor graph before any transition occurs.
+
+| Property | Description |
+| --- | --- |
+| `parentRef` | The parent actor, or `undefined` for the root actor. |
+| `id` | The actor's `id`. |
+| `src` | The source logic, or its referenced string. |
+| `snapshot` | The actor's initial snapshot. |
+
+`@xstate.transition` announces a transition. Every property is always present, so an inspector can read each facet without narrowing.
+
+| Property | Description |
+| --- | --- |
+| `eventType` | The event type. |
+| `event` | The event that caused the transition. |
+| `sourceRef` | The actor that sent the event, if any. |
+| `targetRef` | The target actor, usually the same as `actorRef`. |
+| `snapshot` | The resulting snapshot. |
+| `microsteps` | The microstep transition definitions taken. |
+| `actions` | The executed actions, as `{ type, params }`. |
+| `sent` | Events relayed to other actors, as `{ targetRef, targetId, event, delay, id }`. |
+
+Each transition retains the source of its own event, including events queued before the actor starts or while another transition runs. Events sent through the public `actor.send(...)` method have an `undefined` source. Child initialization transitions identify the parent as their source.
+
+Events that could not be delivered (dead letters) are not inspection events. Observe them with the `onRejectedEvent` option on `createActor`, or subscribe later with `actor.system.onRejectedEvent(listener)`. See [dead letters](systems.md#dead-letters).
+
+An event that no transition handled is visible without a separate event type: the `@xstate.transition` event that follows it carries the same `snapshot` reference as the previous transition and an empty `actions` list. Compare references, or use `isUnhandled()` with the pure API.
+
+Actor stop is derivable from `snapshot.status` on the actor's final `@xstate.transition` event, so there is no separate stop event. The v5 `@xstate.event`, `@xstate.snapshot`, `@xstate.action` and `@xstate.microstep` events are gone; `@xstate.transition` carries all of them.
+
+Use inspection for developer tools, logs and visualizers. Do not change application state from an inspector.
+
+If an inspector throws, XState reports the error asynchronously, as it does for snapshot subscriber errors. The actor continues processing, and other inspectors still receive the event.
+
+Use inspection to build a statechart visualizer, or to attach actor and transition details to a failed request trace.
+
+## Inspection cheatsheet
+
+```ts
+createActor(logic, { inspect });
+createActor(logic, { inspect: (event) => console.log(event) });
+event.rootId; // root actor session ID
+event.actorRef; // '@xstate.actor' and '@xstate.transition'
+event.parentRef, event.id, event.src, event.snapshot; // '@xstate.actor'
+event.event, event.snapshot, event.sourceRef, event.targetRef; // '@xstate.transition'
+event.microsteps, event.actions, event.sent; // '@xstate.transition'
+```
+
+Microstep transition records contain the targets selected by function transitions. Inspection and `getMicrosteps()` expose resolved copies with a `definition` reference to the shared transition; the machine's shared transition definitions remain reusable.

package/docs/internal-events.md

@@ -0,0 +1,156 @@
+---
+title: Internal events
+description: Declare events that the machine may raise but no one may send in.
+---
+
+Declare private event payload schemas in `schemas.internalEvents`. These events
+are part of the machine's internal event union, but are excluded from the
+public `actor.send(...)` and `actor.trigger` protocols.
+
+```ts
+const machine = createMachine({
+  schemas: {
+    events: {
+      start: z.object({})
+    },
+    internalEvents: {
+      tick: z.object({ count: z.number() })
+    }
+  },
+  initial: 'idle',
+  states: {
+    idle: {
+      on: {
+        start: (_, enq) => {
+          enq.raise({ type: 'tick', count: 1 });
+        },
+        tick: { target: 'done' }
+      }
+    },
+    done: {}
+  }
+});
+```
+
+Sending `start` raises `tick` internally and the machine transitions to `done`. Sending `tick` directly rejects the event at the delivery boundary:
+
+```ts
+const actor = createActor(machine, {
+  onRejectedEvent: (rejection) => {
+    rejection.event; // { type: 'tick' }
+    rejection.reason; // 'internalEvent'
+  }
+}).start();
+
+actor.send({ type: 'tick' });
+// The event is not delivered. `actor.send` does not throw and the actor
+// does not error; its state is unchanged.
+```
+
+A rejected event never enters the machine. The rejection is reported two ways:
+
+- The `onRejectedEvent` dead-letter hook on `createActor` options receives an `EventRejection` object with the `event`, `targetId`, `sourceRef`, `eventOrigin` (`'external'` or `'actor'`), `reason` and `error`.
+- In development mode, a console warning describes the rejection.
+
+Internal events are still ordinary events in every other respect. They appear
+in `on` handlers and are raised with `enq.raise` like any other event. They do
+not need a duplicate entry in `schemas.events`.
+
+## Wildcard patterns
+
+Entries may use a `.`-segment wildcard, which covers every event type under that prefix.
+
+```ts
+schemas: {
+  internalEvents: {
+    'change.*': z.object({ value: z.string() })
+  }
+}
+```
+
+With that in place, `change.value`, `change.status` and any other `change.*` event can be raised internally but is rejected from outside.
+
+## What counts as "outside"
+
+The check compares the sender to the receiver. An internally executed
+self-targeted effect such as `enq.raise(...)` or `enq.sendTo(self, ...)` is
+allowed. Anything else is rejected: `actor.send` from application code, a
+parent sending to a child, or a sibling actor.
+
+> **Warning:** a rejection is silent unless you observe it. It does not throw and it does not error the actor. Register `onRejectedEvent` or `actor.system.onRejectedEvent(...)` to detect rejected events. Dead letters are not inspection events. Treat internal events as a private surface, and if application code needs to reach that behavior, expose a public event that raises the internal one.
+
+Use internal events for:
+
+- a `tick` that only the machine's own timer logic should produce
+- `change.*` events raised by a form's own validation pass, so no caller can fake a field update
+- upload progress events raised by an invoked actor's callbacks, where an outside `progress` event would corrupt the state
+
+## TypeScript
+
+The keys in `schemas.internalEvents` narrow the actor's public protocol: those
+types, and types matched by a wildcard, are removed from what `actor.send` and
+`actor.trigger` accept, so an invalid send is a type error rather than a
+runtime rejection. They remain fully typed inside the machine for `on`
+handlers, guards, actions, `enq.raise` and [transitions](transitions.md).
+
+The top-level `internalEvents: ['tick']` list was removed before 6.0. Move
+each listed event's schema from `schemas.events` to `schemas.internalEvents`.
+A machine config with a top-level `internalEvents` key throws an error naming
+`schemas.internalEvents`.
+
+## Internal events cheatsheet
+
+```ts
+createMachine({
+  schemas: {
+    events: {
+      start: z.object({})
+    },
+    internalEvents: {
+      tick: z.object({}),
+      'change.*': z.object({ value: z.string() })
+    }
+  },
+  initial: 'idle',
+  states: {
+    idle: {
+      on: {
+        start: (_, enq) => {
+          enq.raise({ type: 'tick' });
+        },
+        tick: { target: 'done' }
+      }
+    },
+    done: {}
+  }
+});
+```
+
+## Validating public input
+
+`eventSchema(machine)` is a Standard Schema for complete public input event
+objects. Validate untrusted input (including agent tool arguments) before sending:
+
+```ts
+const result = await eventSchema(machine)['~standard'].validate(input);
+if (result.issues) {
+  throw new Error(result.issues[0]?.message);
+}
+actor.send(result.value);
+```
+
+The schema validates payloads using `schemas.events`, rejects declared internal
+events (including wildcard descriptors), and rejects `xstate.*` / `@xstate.*`
+runtime events. `xstate.route` is accepted only with a `to` destination identifying
+an explicitly configured route. Route guards and current-state eligibility are
+evaluated during delivery, not schema validation.
+
+Without event schemas, application event names remain open. `types<T>()` provides
+type inference only; use a runtime schema such as Zod to validate payloads.
+Validation is not authorization: a well-formed public event may still require
+application permission checks.
+
+`actor.send(event)` keeps supporting trusted runtime delivery and replay. It does
+not automatically run `eventSchema(machine)`. For event histories,
+`machineVersions().adaptEvents()` retains historical internal/runtime validation
+when given actual machines.