xstate 5.30.0 → 5.31.0

package/dist/{StateMachine-89436b8f.development.cjs.js → StateMachine-a2514a01.development.cjs.js}

@@ -1,7 +1,7 @@
 'use strict';
 
-var guards_dist_xstateGuards = require('./raise-f3874442.development.cjs.js');
-var assign = require('./assign-8c16ea04.development.cjs.js');
+var guards_dist_xstateGuards = require('./raise-6e65c93f.development.cjs.js');
+var assign = require('./assign-6da0bff4.development.cjs.js');
 
 const cache = new WeakMap();
 function memo(object, key, fn) {
@@ -301,6 +301,8 @@ class StateMachine {
     this.version = void 0;
     this.schemas = void 0;
     this.implementations = void 0;
+    /** Runtime options for machine execution. */
+    this.options = void 0;
     /** @internal */
     this.__xstatenode = true;
     /** @internal */
@@ -318,6 +320,10 @@ class StateMachine {
     };
     this.version = this.config.version;
     this.schemas = this.config.schemas;
+    this.options = {
+      maxIterations: Infinity,
+      ...this.config.options
+    };
     this.transition = this.transition.bind(this);
     this.getInitialSnapshot = this.getInitialSnapshot.bind(this);
     this.getPersistedSnapshot = this.getPersistedSnapshot.bind(this);

package/dist/{StateMachine-bf2cec8d.esm.js → StateMachine-b9937861.esm.js}

@@ -1,5 +1,5 @@
-import { S as STATE_DELIMITER, y as mapValues, t as toArray, z as formatTransitions, B as toTransitionConfigArray, C as formatTransition, N as NULL_EVENT, D as evaluateGuard, E as createInvokeId, F as getDelayedTransitions, G as formatInitialTransition, H as getCandidates, I as formatRouteTransitions, J as resolveStateValue, K as getAllStateNodes, p as getStateNodes, L as createMachineSnapshot, M as isInFinalState, d as macrostep, O as transitionNode, P as resolveActionsAndContext, e as createInitEvent, i as initialMicrostep, Q as toStatePath, R as isStateId, T as getStateNodeByPath, U as getPersistedSnapshot, V as resolveReferencedActor, c as createActor, $ as $$ACTOR_TYPE } from './raise-b47daa89.esm.js';
-import { a as assign } from './assign-128c3f01.esm.js';
+import { S as STATE_DELIMITER, y as mapValues, t as toArray, z as formatTransitions, B as toTransitionConfigArray, C as formatTransition, N as NULL_EVENT, D as evaluateGuard, E as createInvokeId, F as getDelayedTransitions, G as formatInitialTransition, H as getCandidates, I as formatRouteTransitions, J as resolveStateValue, K as getAllStateNodes, p as getStateNodes, L as createMachineSnapshot, M as isInFinalState, d as macrostep, O as transitionNode, P as resolveActionsAndContext, e as createInitEvent, f as initialMicrostep, Q as toStatePath, R as isStateId, T as getStateNodeByPath, U as getPersistedSnapshot, V as resolveReferencedActor, c as createActor, $ as $$ACTOR_TYPE } from './raise-56f87e05.esm.js';
+import { a as assign } from './assign-c15c199c.esm.js';
 
 const cache = new WeakMap();
 function memo(object, key, fn) {
@@ -299,6 +299,8 @@ class StateMachine {
     this.version = void 0;
     this.schemas = void 0;
     this.implementations = void 0;
+    /** Runtime options for machine execution. */
+    this.options = void 0;
     /** @internal */
     this.__xstatenode = true;
     /** @internal */
@@ -316,6 +318,10 @@ class StateMachine {
     };
     this.version = this.config.version;
     this.schemas = this.config.schemas;
+    this.options = {
+      maxIterations: Infinity,
+      ...this.config.options
+    };
     this.transition = this.transition.bind(this);
     this.getInitialSnapshot = this.getInitialSnapshot.bind(this);
     this.getPersistedSnapshot = this.getPersistedSnapshot.bind(this);

package/dist/{assign-4254ecc7.development.esm.js → assign-4f7ce317.development.esm.js}

@@ -1,4 +1,4 @@
-import { _ as ProcessingStatus, V as resolveReferencedActor, c as createActor, a0 as cloneMachineSnapshot, W as executingCustomAction } from './raise-964ef086.development.esm.js';
+import { _ as ProcessingStatus, V as resolveReferencedActor, c as createActor, a0 as cloneMachineSnapshot, W as executingCustomAction } from './raise-b724c245.development.esm.js';
 
 function createSpawner(actorScope, {
   machine,

package/dist/{assign-f10db67b.cjs.js → assign-53a98e5d.cjs.js}

@@ -1,6 +1,6 @@
 'use strict';
 
-var guards_dist_xstateGuards = require('./raise-f051f097.cjs.js');
+var guards_dist_xstateGuards = require('./raise-69f5aed0.cjs.js');
 
 function createSpawner(actorScope, {
   machine,

package/dist/{assign-8c16ea04.development.cjs.js → assign-6da0bff4.development.cjs.js}

@@ -1,6 +1,6 @@
 'use strict';
 
-var guards_dist_xstateGuards = require('./raise-f3874442.development.cjs.js');
+var guards_dist_xstateGuards = require('./raise-6e65c93f.development.cjs.js');
 
 function createSpawner(actorScope, {
   machine,

package/dist/{assign-128c3f01.esm.js → assign-c15c199c.esm.js}

@@ -1,4 +1,4 @@
-import { Z as ProcessingStatus, V as resolveReferencedActor, c as createActor, _ as cloneMachineSnapshot } from './raise-b47daa89.esm.js';
+import { Z as ProcessingStatus, V as resolveReferencedActor, c as createActor, _ as cloneMachineSnapshot } from './raise-56f87e05.esm.js';
 
 function createSpawner(actorScope, {
   machine,

package/dist/declarations/src/StateMachine.d.ts

@@ -1,7 +1,7 @@
 import { MachineSnapshot } from "./State.js";
 import { StateNode } from "./StateNode.js";
 import { AnyActorSystem } from "./system.js";
-import type { ActorLogic, ActorScope, AnyActorRef, AnyActorScope, DoNotInfer, Equals, EventDescriptor, EventObject, HistoryValue, InternalMachineImplementations, MachineConfig, MachineContext, MachineImplementationsSimplified, MetaObject, ParameterizedObject, ProvidedActor, Snapshot, StateMachineDefinition, StateValue, TransitionDefinition, ResolvedStateMachineTypes, StateSchema, SnapshotStatus } from "./types.js";
+import type { ActorLogic, ActorScope, AnyActorRef, AnyActorScope, DoNotInfer, Equals, EventDescriptor, EventObject, HistoryValue, InternalMachineImplementations, MachineConfig, MachineContext, MachineImplementationsSimplified, MachineOptions, MetaObject, ParameterizedObject, ProvidedActor, Snapshot, StateMachineDefinition, StateValue, TransitionDefinition, ResolvedStateMachineTypes, StateSchema, SnapshotStatus } from "./types.js";
 export declare class StateMachine<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TActor extends ProvidedActor, TAction extends ParameterizedObject, TGuard extends ParameterizedObject, TDelay extends string, TStateValue extends StateValue, TTag extends string, TInput, TOutput, TEmitted extends EventObject, TMeta extends MetaObject, TStateSchema extends StateSchema> implements ActorLogic<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TStateSchema>, TEvent, TInput, AnyActorSystem, TEmitted> {
     /** The raw config used to create the machine. */
     config: MachineConfig<TContext, TEvent, any, any, any, any, any, any, TOutput, any, // TEmitted
@@ -12,6 +12,8 @@ export declare class StateMachine<TContext extends MachineContext, TEvent extend
     version?: string;
     schemas: unknown;
     implementations: MachineImplementationsSimplified<TContext, TEvent>;
+    /** Runtime options for machine execution. */
+    options: MachineOptions;
     root: StateNode<TContext, TEvent>;
     id: string;
     states: StateNode<TContext, TEvent>['states'];

package/dist/declarations/src/index.d.ts

@@ -3,6 +3,7 @@ export * from "./actors/index.js";
 export { assertEvent } from "./assert.js";
 export { Actor, createActor, interpret, type Interpreter, type RequiredActorOptionsKeys as RequiredActorOptionsKeys } from "./createActor.js";
 export { createMachine } from "./createMachine.js";
+export { mapState } from "./mapState.js";
 export { getInitialSnapshot, getNextSnapshot } from "./getNextSnapshot.js";
 export { and, not, or, stateIn } from "./guards.js";
 export type { GuardPredicate, GuardArgs } from "./guards.js";

package/dist/declarations/src/mapState.d.ts

@@ -0,0 +1,25 @@
+import { AnyMachineSnapshot, AnyStateNode, StateSchema, StateSchemaFrom } from "./types.js";
+/**
+ * A mapper object that defines how to transform a snapshot based on its state.
+ * Can be nested to match the state hierarchy of the machine.
+ */
+type StateSchemaMapper<TSnapshot extends AnyMachineSnapshot, T extends StateSchema, TResult> = {
+    /** Maps the snapshot to a value when this state is active. */
+    map?: (snapshot: TSnapshot) => TResult;
+    /** Nested mappers for child states. */
+    states?: {
+        [K in keyof T['states']]?: T['states'][K] extends StateSchema ? StateSchemaMapper<TSnapshot, T['states'][K], TResult> : never;
+    };
+};
+/**
+ * Maps a machine snapshot to an array of result objects based on active states.
+ *
+ * Traverses all active state nodes (from atomic/leaf states up to root) and
+ * collects results from matching `map` functions in the mapper object. Results
+ * are ordered leaf-to-root (most specific state first).
+ */
+export declare function mapState<T extends AnyMachineSnapshot, TResult>(snapshot: T, mapper: StateSchemaMapper<T, StateSchemaFrom<T['machine']>, TResult>): {
+    stateNode: AnyStateNode;
+    result: TResult;
+}[];
+export {};

package/dist/declarations/src/types.d.ts

@@ -455,11 +455,38 @@ export type ContextFactory<TContext extends MachineContext, TActor extends Provi
     StateValue, string, unknown, TODO, // TMeta
     TODO>, TEvent, AnyEventObject>;
 }) => TContext;
+/**
+ * Runtime options for state machine execution.
+ *
+ * @example
+ *
+ * ```ts
+ * const machine = createMachine({
+ *   // ... machine config
+ *   options: {
+ *     maxIterations: 5000
+ *     // other runtime options can be added here
+ *   }
+ * });
+ * ```
+ */
+export interface MachineOptions {
+    /**
+     * Maximum number of microsteps allowed before throwing an infinite loop
+     * error. Defaults to `Infinity` (no limit). Set to a finite number to enable
+     * infinite loop detection.
+     *
+     * @default Infinity
+     */
+    maxIterations?: number;
+}
 export type MachineConfig<TContext extends MachineContext, TEvent extends EventObject, TActor extends ProvidedActor = ProvidedActor, TAction extends ParameterizedObject = ParameterizedObject, TGuard extends ParameterizedObject = ParameterizedObject, TDelay extends string = string, TTag extends string = string, TInput = any, TOutput = unknown, TEmitted extends EventObject = EventObject, TMeta extends MetaObject = MetaObject> = (Omit<StateNodeConfig<DoNotInfer<TContext>, DoNotInfer<TEvent>, DoNotInfer<TActor>, DoNotInfer<TAction>, DoNotInfer<TGuard>, DoNotInfer<TDelay>, DoNotInfer<TTag>, DoNotInfer<TOutput>, DoNotInfer<TEmitted>, DoNotInfer<TMeta>>, 'output'> & {
     /** The initial context (extended state) */
     /** The machine's own version. */
     version?: string;
     output?: Mapper<TContext, DoneStateEvent, TOutput, TEvent> | TOutput;
+    /** Runtime options for machine execution. */
+    options?: MachineOptions;
 }) & (MachineContext extends TContext ? {
     context?: InitialContext<LowInfer<TContext>, TActor, TInput, TEvent>;
 } : {
@@ -933,6 +960,7 @@ export type StateSchema = {
     tags?: unknown;
     description?: unknown;
 };
+export type StateSchemaFrom<T extends AnyStateMachine> = T extends StateMachine<infer _TContext, infer _TEvent, infer _TChildren, infer _TActor, infer _TAction, infer _TGuard, infer _TDelay, infer _TStateValue, infer _TTag, infer _TInput, infer _TOutput, infer _TEmitted, infer _TMeta, infer TStateSchema> ? TStateSchema : never;
 export type StateId<TSchema extends StateSchema, TKey extends string = '(machine)', TParentKey extends string | null = null> = (TSchema extends {
     id: string;
 } ? TSchema['id'] : TParentKey extends null ? TKey : `${TParentKey}.${TKey}`) | (TSchema['states'] extends Record<string, any> ? Values<{

package/dist/{log-30abbb83.cjs.js → log-279b177f.cjs.js}

@@ -1,7 +1,7 @@
 'use strict';
 
-var guards_dist_xstateGuards = require('./raise-f051f097.cjs.js');
-var assign = require('./assign-f10db67b.cjs.js');
+var guards_dist_xstateGuards = require('./raise-69f5aed0.cjs.js');
+var assign = require('./assign-53a98e5d.cjs.js');
 
 function resolveEmit(_, snapshot, args, actionParams, {
   event: eventOrExpr
@@ -108,6 +108,22 @@ eventOrExpr) {
 // TODO: possibly refactor this somehow, use even a simpler type, and maybe even make `machine.options` private or something
 /** @ignore */
 
+/**
+ * Runtime options for state machine execution.
+ *
+ * @example
+ *
+ * ```ts
+ * const machine = createMachine({
+ *   // ... machine config
+ *   options: {
+ *     maxIterations: 5000
+ *     // other runtime options can be added here
+ *   }
+ * });
+ * ```
+ */
+
 let SpecialTargets = /*#__PURE__*/function (SpecialTargets) {
   SpecialTargets["Parent"] = "#_parent";
   SpecialTargets["Internal"] = "#_internal";

package/dist/{log-0e01d593.development.esm.js → log-3e4dba89.development.esm.js}

@@ -1,5 +1,5 @@
-import { W as executingCustomAction, Y as XSTATE_ERROR, Z as createErrorActorEvent, D as evaluateGuard, a as cancel, r as raise, b as spawnChild, s as stopChild } from './raise-964ef086.development.esm.js';
-import { a as assign } from './assign-4254ecc7.development.esm.js';
+import { W as executingCustomAction, Y as XSTATE_ERROR, Z as createErrorActorEvent, D as evaluateGuard, a as cancel, r as raise, b as spawnChild, s as stopChild } from './raise-b724c245.development.esm.js';
+import { a as assign } from './assign-4f7ce317.development.esm.js';
 
 function resolveEmit(_, snapshot, args, actionParams, {
   event: eventOrExpr
@@ -112,6 +112,22 @@ eventOrExpr) {
 // TODO: possibly refactor this somehow, use even a simpler type, and maybe even make `machine.options` private or something
 /** @ignore */
 
+/**
+ * Runtime options for state machine execution.
+ *
+ * @example
+ *
+ * ```ts
+ * const machine = createMachine({
+ *   // ... machine config
+ *   options: {
+ *     maxIterations: 5000
+ *     // other runtime options can be added here
+ *   }
+ * });
+ * ```
+ */
+
 let SpecialTargets = /*#__PURE__*/function (SpecialTargets) {
   SpecialTargets["Parent"] = "#_parent";
   SpecialTargets["Internal"] = "#_internal";

package/dist/{log-f3a45f9f.development.cjs.js → log-8ca142b5.development.cjs.js}

@@ -1,7 +1,7 @@
 'use strict';
 
-var guards_dist_xstateGuards = require('./raise-f3874442.development.cjs.js');
-var assign = require('./assign-8c16ea04.development.cjs.js');
+var guards_dist_xstateGuards = require('./raise-6e65c93f.development.cjs.js');
+var assign = require('./assign-6da0bff4.development.cjs.js');
 
 function resolveEmit(_, snapshot, args, actionParams, {
   event: eventOrExpr
@@ -114,6 +114,22 @@ eventOrExpr) {
 // TODO: possibly refactor this somehow, use even a simpler type, and maybe even make `machine.options` private or something
 /** @ignore */
 
+/**
+ * Runtime options for state machine execution.
+ *
+ * @example
+ *
+ * ```ts
+ * const machine = createMachine({
+ *   // ... machine config
+ *   options: {
+ *     maxIterations: 5000
+ *     // other runtime options can be added here
+ *   }
+ * });
+ * ```
+ */
+
 let SpecialTargets = /*#__PURE__*/function (SpecialTargets) {
   SpecialTargets["Parent"] = "#_parent";
   SpecialTargets["Internal"] = "#_internal";

package/dist/{log-678e6837.esm.js → log-ce7cb9aa.esm.js}

@@ -1,5 +1,5 @@
-import { W as XSTATE_ERROR, Y as createErrorActorEvent, D as evaluateGuard, a as cancel, r as raise, b as spawnChild, s as stopChild } from './raise-b47daa89.esm.js';
-import { a as assign } from './assign-128c3f01.esm.js';
+import { W as XSTATE_ERROR, Y as createErrorActorEvent, D as evaluateGuard, a as cancel, r as raise, b as spawnChild, s as stopChild } from './raise-56f87e05.esm.js';
+import { a as assign } from './assign-c15c199c.esm.js';
 
 function resolveEmit(_, snapshot, args, actionParams, {
   event: eventOrExpr
@@ -106,6 +106,22 @@ eventOrExpr) {
 // TODO: possibly refactor this somehow, use even a simpler type, and maybe even make `machine.options` private or something
 /** @ignore */
 
+/**
+ * Runtime options for state machine execution.
+ *
+ * @example
+ *
+ * ```ts
+ * const machine = createMachine({
+ *   // ... machine config
+ *   options: {
+ *     maxIterations: 5000
+ *     // other runtime options can be added here
+ *   }
+ * });
+ * ```
+ */
+
 let SpecialTargets = /*#__PURE__*/function (SpecialTargets) {
   SpecialTargets["Parent"] = "#_parent";
   SpecialTargets["Internal"] = "#_internal";

package/dist/{raise-b47daa89.esm.js → raise-56f87e05.esm.js}

@@ -2498,7 +2498,13 @@ function macrostep(snapshot, event, actorScope, internalQueue) {
     addMicrostep(step, currentEvent, transitions);
   }
   let shouldSelectEventlessTransitions = true;
+  const maxIterations = snapshot.machine.options?.maxIterations ?? Infinity;
+  let iterationCount = 0;
   while (nextSnapshot.status === 'active') {
+    iterationCount++;
+    if (iterationCount > maxIterations) {
+      throw new Error(`Infinite loop detected: the machine has processed more than ${maxIterations} microsteps without reaching a stable state. This usually happens when there's a cycle of transitions (e.g., eventless transitions or raised events causing state A -> B -> C -> A).`);
+    }
     let enabledTransitions = shouldSelectEventlessTransitions ? selectEventlessTransitions(nextSnapshot, nextEvent) : [];
 
     // eventless transitions should always be selected after selecting *regular* transitions
@@ -2761,4 +2767,4 @@ function raise(eventOrExpr, options) {
   return raise;
 }
 
-export { $$ACTOR_TYPE as $, Actor as A, toTransitionConfigArray as B, formatTransition as C, evaluateGuard as D, createInvokeId as E, getDelayedTransitions as F, formatInitialTransition as G, getCandidates as H, formatRouteTransitions as I, resolveStateValue as J, getAllStateNodes as K, createMachineSnapshot as L, isInFinalState as M, NULL_EVENT as N, transitionNode as O, resolveActionsAndContext as P, toStatePath as Q, isStateId as R, STATE_DELIMITER as S, getStateNodeByPath as T, getPersistedSnapshot as U, resolveReferencedActor as V, XSTATE_ERROR as W, XSTATE_STOP as X, createErrorActorEvent as Y, ProcessingStatus as Z, cloneMachineSnapshot as _, cancel as a, spawnChild as b, createActor as c, macrostep as d, createInitEvent as e, isAtomicStateNode as f, getProperAncestors as g, interpret as h, initialMicrostep as i, and as j, stateIn as k, isMachineSnapshot as l, matchesEventDescriptor as m, not as n, or as o, getStateNodes as p, getAllOwnEventDescriptors as q, raise as r, stopChild as s, toArray as t, matchesState as u, pathToStateValue as v, toObserver as w, stop as x, mapValues as y, formatTransitions as z };
+export { $$ACTOR_TYPE as $, Actor as A, toTransitionConfigArray as B, formatTransition as C, evaluateGuard as D, createInvokeId as E, getDelayedTransitions as F, formatInitialTransition as G, getCandidates as H, formatRouteTransitions as I, resolveStateValue as J, getAllStateNodes as K, createMachineSnapshot as L, isInFinalState as M, NULL_EVENT as N, transitionNode as O, resolveActionsAndContext as P, toStatePath as Q, isStateId as R, STATE_DELIMITER as S, getStateNodeByPath as T, getPersistedSnapshot as U, resolveReferencedActor as V, XSTATE_ERROR as W, XSTATE_STOP as X, createErrorActorEvent as Y, ProcessingStatus as Z, cloneMachineSnapshot as _, cancel as a, spawnChild as b, createActor as c, macrostep as d, createInitEvent as e, initialMicrostep as f, getProperAncestors as g, interpret as h, isAtomicStateNode as i, and as j, stateIn as k, isMachineSnapshot as l, matchesEventDescriptor as m, not as n, or as o, getStateNodes as p, getAllOwnEventDescriptors as q, raise as r, stopChild as s, toArray as t, matchesState as u, pathToStateValue as v, toObserver as w, stop as x, mapValues as y, formatTransitions as z };

package/dist/{raise-f051f097.cjs.js → raise-69f5aed0.cjs.js}

@@ -2500,7 +2500,13 @@ function macrostep(snapshot, event, actorScope, internalQueue) {
     addMicrostep(step, currentEvent, transitions);
   }
   let shouldSelectEventlessTransitions = true;
+  const maxIterations = snapshot.machine.options?.maxIterations ?? Infinity;
+  let iterationCount = 0;
   while (nextSnapshot.status === 'active') {
+    iterationCount++;
+    if (iterationCount > maxIterations) {
+      throw new Error(`Infinite loop detected: the machine has processed more than ${maxIterations} microsteps without reaching a stable state. This usually happens when there's a cycle of transitions (e.g., eventless transitions or raised events causing state A -> B -> C -> A).`);
+    }
     let enabledTransitions = shouldSelectEventlessTransitions ? selectEventlessTransitions(nextSnapshot, nextEvent) : [];
 
     // eventless transitions should always be selected after selecting *regular* transitions

package/dist/{raise-f3874442.development.cjs.js → raise-6e65c93f.development.cjs.js}

@@ -2550,7 +2550,13 @@ function macrostep(snapshot, event, actorScope, internalQueue) {
     addMicrostep(step, currentEvent, transitions);
   }
   let shouldSelectEventlessTransitions = true;
+  const maxIterations = snapshot.machine.options?.maxIterations ?? Infinity;
+  let iterationCount = 0;
   while (nextSnapshot.status === 'active') {
+    iterationCount++;
+    if (iterationCount > maxIterations) {
+      throw new Error(`Infinite loop detected: the machine has processed more than ${maxIterations} microsteps without reaching a stable state. This usually happens when there's a cycle of transitions (e.g., eventless transitions or raised events causing state A -> B -> C -> A).`);
+    }
     let enabledTransitions = shouldSelectEventlessTransitions ? selectEventlessTransitions(nextSnapshot, nextEvent) : [];
 
     // eventless transitions should always be selected after selecting *regular* transitions

package/dist/{raise-964ef086.development.esm.js → raise-b724c245.development.esm.js}

@@ -2548,7 +2548,13 @@ function macrostep(snapshot, event, actorScope, internalQueue) {
     addMicrostep(step, currentEvent, transitions);
   }
   let shouldSelectEventlessTransitions = true;
+  const maxIterations = snapshot.machine.options?.maxIterations ?? Infinity;
+  let iterationCount = 0;
   while (nextSnapshot.status === 'active') {
+    iterationCount++;
+    if (iterationCount > maxIterations) {
+      throw new Error(`Infinite loop detected: the machine has processed more than ${maxIterations} microsteps without reaching a stable state. This usually happens when there's a cycle of transitions (e.g., eventless transitions or raised events causing state A -> B -> C -> A).`);
+    }
     let enabledTransitions = shouldSelectEventlessTransitions ? selectEventlessTransitions(nextSnapshot, nextEvent) : [];
 
     // eventless transitions should always be selected after selecting *regular* transitions
@@ -2823,4 +2829,4 @@ function raise(eventOrExpr, options) {
   return raise;
 }
 
-export { $$ACTOR_TYPE as $, Actor as A, toTransitionConfigArray as B, formatTransition as C, evaluateGuard as D, createInvokeId as E, getDelayedTransitions as F, formatInitialTransition as G, getCandidates as H, formatRouteTransitions as I, resolveStateValue as J, getAllStateNodes as K, createMachineSnapshot as L, isInFinalState as M, NULL_EVENT as N, transitionNode as O, resolveActionsAndContext as P, toStatePath as Q, isStateId as R, STATE_DELIMITER as S, getStateNodeByPath as T, getPersistedSnapshot as U, resolveReferencedActor as V, executingCustomAction as W, XSTATE_STOP as X, XSTATE_ERROR as Y, createErrorActorEvent as Z, ProcessingStatus as _, cancel as a, cloneMachineSnapshot as a0, spawnChild as b, createActor as c, macrostep as d, createInitEvent as e, isAtomicStateNode as f, getProperAncestors as g, interpret as h, initialMicrostep as i, and as j, stateIn as k, isMachineSnapshot as l, matchesEventDescriptor as m, not as n, or as o, getStateNodes as p, getAllOwnEventDescriptors as q, raise as r, stopChild as s, toArray as t, matchesState as u, pathToStateValue as v, toObserver as w, stop as x, mapValues as y, formatTransitions as z };
+export { $$ACTOR_TYPE as $, Actor as A, toTransitionConfigArray as B, formatTransition as C, evaluateGuard as D, createInvokeId as E, getDelayedTransitions as F, formatInitialTransition as G, getCandidates as H, formatRouteTransitions as I, resolveStateValue as J, getAllStateNodes as K, createMachineSnapshot as L, isInFinalState as M, NULL_EVENT as N, transitionNode as O, resolveActionsAndContext as P, toStatePath as Q, isStateId as R, STATE_DELIMITER as S, getStateNodeByPath as T, getPersistedSnapshot as U, resolveReferencedActor as V, executingCustomAction as W, XSTATE_STOP as X, XSTATE_ERROR as Y, createErrorActorEvent as Z, ProcessingStatus as _, cancel as a, cloneMachineSnapshot as a0, spawnChild as b, createActor as c, macrostep as d, createInitEvent as e, initialMicrostep as f, getProperAncestors as g, interpret as h, isAtomicStateNode as i, and as j, stateIn as k, isMachineSnapshot as l, matchesEventDescriptor as m, not as n, or as o, getStateNodes as p, getAllOwnEventDescriptors as q, raise as r, stopChild as s, toArray as t, matchesState as u, pathToStateValue as v, toObserver as w, stop as x, mapValues as y, formatTransitions as z };

package/dist/xstate.cjs.js

@@ -3,10 +3,10 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var actors_dist_xstateActors = require('../actors/dist/xstate-actors.cjs.js');
-var guards_dist_xstateGuards = require('./raise-f051f097.cjs.js');
-var StateMachine = require('./StateMachine-d3e2432b.cjs.js');
-var assign = require('./assign-f10db67b.cjs.js');
-var log = require('./log-30abbb83.cjs.js');
+var guards_dist_xstateGuards = require('./raise-69f5aed0.cjs.js');
+var StateMachine = require('./StateMachine-37420c93.cjs.js');
+var assign = require('./assign-53a98e5d.cjs.js');
+var log = require('./log-279b177f.cjs.js');
 require('../dev/dist/xstate-dev.cjs.js');
 
 /**
@@ -87,6 +87,52 @@ function createMachine(config, implementations) {
   return new StateMachine.StateMachine(config, implementations);
 }
 
+/**
+ * A mapper object that defines how to transform a snapshot based on its state.
+ * Can be nested to match the state hierarchy of the machine.
+ */
+
+/**
+ * Maps a machine snapshot to an array of result objects based on active states.
+ *
+ * Traverses all active state nodes (from atomic/leaf states up to root) and
+ * collects results from matching `map` functions in the mapper object. Results
+ * are ordered leaf-to-root (most specific state first).
+ */
+function mapState(snapshot, mapper) {
+  const results = [];
+  const findMapper = (currentMapper, nodePath) => {
+    let mapper = currentMapper;
+    for (const key of nodePath) {
+      if (!mapper?.states) {
+        return undefined;
+      }
+      const states = mapper.states;
+      if (!(key in states)) {
+        return undefined;
+      }
+      mapper = states[key];
+    }
+    return mapper;
+  };
+  const visited = new Set();
+  for (const atomicNode of snapshot._nodes.filter(guards_dist_xstateGuards.isAtomicStateNode)) {
+    let current = atomicNode;
+    while (current && !visited.has(current)) {
+      visited.add(current);
+      const nodeMapper = findMapper(mapper, current.path);
+      if (nodeMapper?.map) {
+        results.push({
+          stateNode: current,
+          result: nodeMapper.map(snapshot)
+        });
+      }
+      current = current.parent;
+    }
+  }
+  return results;
+}
+
 /** @internal */
 function createInertActorScope(actorLogic) {
   const self = guards_dist_xstateGuards.createActor(actorLogic);
@@ -571,6 +617,7 @@ exports.getMicrosteps = getMicrosteps;
 exports.getNextSnapshot = getNextSnapshot;
 exports.getNextTransitions = getNextTransitions;
 exports.initialTransition = initialTransition;
+exports.mapState = mapState;
 exports.setup = setup;
 exports.toPromise = toPromise;
 exports.transition = transition;

package/dist/xstate.cjs.mjs

@@ -30,6 +30,7 @@ export {
   interpret,
   isMachineSnapshot,
   log,
+  mapState,
   matchesState,
   not,
   or,

package/dist/xstate.development.cjs.js

@@ -3,10 +3,10 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var actors_dist_xstateActors = require('../actors/dist/xstate-actors.development.cjs.js');
-var guards_dist_xstateGuards = require('./raise-f3874442.development.cjs.js');
-var StateMachine = require('./StateMachine-89436b8f.development.cjs.js');
-var assign = require('./assign-8c16ea04.development.cjs.js');
-var log = require('./log-f3a45f9f.development.cjs.js');
+var guards_dist_xstateGuards = require('./raise-6e65c93f.development.cjs.js');
+var StateMachine = require('./StateMachine-a2514a01.development.cjs.js');
+var assign = require('./assign-6da0bff4.development.cjs.js');
+var log = require('./log-8ca142b5.development.cjs.js');
 require('../dev/dist/xstate-dev.development.cjs.js');
 
 /**
@@ -87,6 +87,52 @@ function createMachine(config, implementations) {
   return new StateMachine.StateMachine(config, implementations);
 }
 
+/**
+ * A mapper object that defines how to transform a snapshot based on its state.
+ * Can be nested to match the state hierarchy of the machine.
+ */
+
+/**
+ * Maps a machine snapshot to an array of result objects based on active states.
+ *
+ * Traverses all active state nodes (from atomic/leaf states up to root) and
+ * collects results from matching `map` functions in the mapper object. Results
+ * are ordered leaf-to-root (most specific state first).
+ */
+function mapState(snapshot, mapper) {
+  const results = [];
+  const findMapper = (currentMapper, nodePath) => {
+    let mapper = currentMapper;
+    for (const key of nodePath) {
+      if (!mapper?.states) {
+        return undefined;
+      }
+      const states = mapper.states;
+      if (!(key in states)) {
+        return undefined;
+      }
+      mapper = states[key];
+    }
+    return mapper;
+  };
+  const visited = new Set();
+  for (const atomicNode of snapshot._nodes.filter(guards_dist_xstateGuards.isAtomicStateNode)) {
+    let current = atomicNode;
+    while (current && !visited.has(current)) {
+      visited.add(current);
+      const nodeMapper = findMapper(mapper, current.path);
+      if (nodeMapper?.map) {
+        results.push({
+          stateNode: current,
+          result: nodeMapper.map(snapshot)
+        });
+      }
+      current = current.parent;
+    }
+  }
+  return results;
+}
+
 /** @internal */
 function createInertActorScope(actorLogic) {
   const self = guards_dist_xstateGuards.createActor(actorLogic);
@@ -574,6 +620,7 @@ exports.getMicrosteps = getMicrosteps;
 exports.getNextSnapshot = getNextSnapshot;
 exports.getNextTransitions = getNextTransitions;
 exports.initialTransition = initialTransition;
+exports.mapState = mapState;
 exports.setup = setup;
 exports.toPromise = toPromise;
 exports.transition = transition;

package/dist/xstate.development.cjs.mjs

@@ -30,6 +30,7 @@ export {
   interpret,
   isMachineSnapshot,
   log,
+  mapState,
   matchesState,
   not,
   or,