xstate 5.19.4 → 5.20.0

package/dist/assign-c3259787.esm.js

@@ -0,0 +1,127 @@
+import { V as ProcessingStatus, R as resolveReferencedActor, c as createActor, W as cloneMachineSnapshot } from './raise-b0a4e862.esm.js';
+
+function createSpawner(actorScope, {
+  machine,
+  context
+}, event, spawnedChildren) {
+  const spawn = (src, options) => {
+    if (typeof src === 'string') {
+      const logic = resolveReferencedActor(machine, src);
+      if (!logic) {
+        throw new Error(`Actor logic '${src}' not implemented in machine '${machine.id}'`);
+      }
+      const actorRef = createActor(logic, {
+        id: options?.id,
+        parent: actorScope.self,
+        syncSnapshot: options?.syncSnapshot,
+        input: typeof options?.input === 'function' ? options.input({
+          context,
+          event,
+          self: actorScope.self
+        }) : options?.input,
+        src,
+        systemId: options?.systemId
+      });
+      spawnedChildren[actorRef.id] = actorRef;
+      return actorRef;
+    } else {
+      const actorRef = createActor(src, {
+        id: options?.id,
+        parent: actorScope.self,
+        syncSnapshot: options?.syncSnapshot,
+        input: options?.input,
+        src,
+        systemId: options?.systemId
+      });
+      return actorRef;
+    }
+  };
+  return (src, options) => {
+    const actorRef = spawn(src, options); // TODO: fix types
+    spawnedChildren[actorRef.id] = actorRef;
+    actorScope.defer(() => {
+      if (actorRef._processingStatus === ProcessingStatus.Stopped) {
+        return;
+      }
+      actorRef.start();
+    });
+    return actorRef;
+  };
+}
+
+function resolveAssign(actorScope, snapshot, actionArgs, actionParams, {
+  assignment
+}) {
+  if (!snapshot.context) {
+    throw new Error('Cannot assign to undefined `context`. Ensure that `context` is defined in the machine config.');
+  }
+  const spawnedChildren = {};
+  const assignArgs = {
+    context: snapshot.context,
+    event: actionArgs.event,
+    spawn: createSpawner(actorScope, snapshot, actionArgs.event, spawnedChildren),
+    self: actorScope.self,
+    system: actorScope.system
+  };
+  let partialUpdate = {};
+  if (typeof assignment === 'function') {
+    partialUpdate = assignment(assignArgs, actionParams);
+  } else {
+    for (const key of Object.keys(assignment)) {
+      const propAssignment = assignment[key];
+      partialUpdate[key] = typeof propAssignment === 'function' ? propAssignment(assignArgs, actionParams) : propAssignment;
+    }
+  }
+  const updatedContext = Object.assign({}, snapshot.context, partialUpdate);
+  return [cloneMachineSnapshot(snapshot, {
+    context: updatedContext,
+    children: Object.keys(spawnedChildren).length ? {
+      ...snapshot.children,
+      ...spawnedChildren
+    } : snapshot.children
+  }), undefined, undefined];
+}
+/**
+ * Updates the current context of the machine.
+ *
+ * @example
+ *
+ * ```ts
+ * import { createMachine, assign } from 'xstate';
+ *
+ * const countMachine = createMachine({
+ *   context: {
+ *     count: 0,
+ *     message: ''
+ *   },
+ *   on: {
+ *     inc: {
+ *       actions: assign({
+ *         count: ({ context }) => context.count + 1
+ *       })
+ *     },
+ *     updateMessage: {
+ *       actions: assign(({ context, event }) => {
+ *         return {
+ *           message: event.message.trim()
+ *         };
+ *       })
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @param assignment An object that represents the partial context to update, or
+ *   a function that returns an object that represents the partial context to
+ *   update.
+ */
+function assign(assignment) {
+  function assign(_args, _params) {
+  }
+  assign.type = 'xstate.assign';
+  assign.assignment = assignment;
+  assign.resolve = resolveAssign;
+  return assign;
+}
+
+export { assign as a };

package/dist/assign-c84786ab.development.cjs.js

@@ -0,0 +1,135 @@
+'use strict';
+
+var guards_dist_xstateGuards = require('./raise-7a84f9f0.development.cjs.js');
+
+function createSpawner(actorScope, {
+  machine,
+  context
+}, event, spawnedChildren) {
+  const spawn = (src, options) => {
+    if (typeof src === 'string') {
+      const logic = guards_dist_xstateGuards.resolveReferencedActor(machine, src);
+      if (!logic) {
+        throw new Error(`Actor logic '${src}' not implemented in machine '${machine.id}'`);
+      }
+      const actorRef = guards_dist_xstateGuards.createActor(logic, {
+        id: options?.id,
+        parent: actorScope.self,
+        syncSnapshot: options?.syncSnapshot,
+        input: typeof options?.input === 'function' ? options.input({
+          context,
+          event,
+          self: actorScope.self
+        }) : options?.input,
+        src,
+        systemId: options?.systemId
+      });
+      spawnedChildren[actorRef.id] = actorRef;
+      return actorRef;
+    } else {
+      const actorRef = guards_dist_xstateGuards.createActor(src, {
+        id: options?.id,
+        parent: actorScope.self,
+        syncSnapshot: options?.syncSnapshot,
+        input: options?.input,
+        src,
+        systemId: options?.systemId
+      });
+      return actorRef;
+    }
+  };
+  return (src, options) => {
+    const actorRef = spawn(src, options); // TODO: fix types
+    spawnedChildren[actorRef.id] = actorRef;
+    actorScope.defer(() => {
+      if (actorRef._processingStatus === guards_dist_xstateGuards.ProcessingStatus.Stopped) {
+        return;
+      }
+      actorRef.start();
+    });
+    return actorRef;
+  };
+}
+
+function resolveAssign(actorScope, snapshot, actionArgs, actionParams, {
+  assignment
+}) {
+  if (!snapshot.context) {
+    throw new Error('Cannot assign to undefined `context`. Ensure that `context` is defined in the machine config.');
+  }
+  const spawnedChildren = {};
+  const assignArgs = {
+    context: snapshot.context,
+    event: actionArgs.event,
+    spawn: createSpawner(actorScope, snapshot, actionArgs.event, spawnedChildren),
+    self: actorScope.self,
+    system: actorScope.system
+  };
+  let partialUpdate = {};
+  if (typeof assignment === 'function') {
+    partialUpdate = assignment(assignArgs, actionParams);
+  } else {
+    for (const key of Object.keys(assignment)) {
+      const propAssignment = assignment[key];
+      partialUpdate[key] = typeof propAssignment === 'function' ? propAssignment(assignArgs, actionParams) : propAssignment;
+    }
+  }
+  const updatedContext = Object.assign({}, snapshot.context, partialUpdate);
+  return [guards_dist_xstateGuards.cloneMachineSnapshot(snapshot, {
+    context: updatedContext,
+    children: Object.keys(spawnedChildren).length ? {
+      ...snapshot.children,
+      ...spawnedChildren
+    } : snapshot.children
+  }), undefined, undefined];
+}
+/**
+ * Updates the current context of the machine.
+ *
+ * @example
+ *
+ * ```ts
+ * import { createMachine, assign } from 'xstate';
+ *
+ * const countMachine = createMachine({
+ *   context: {
+ *     count: 0,
+ *     message: ''
+ *   },
+ *   on: {
+ *     inc: {
+ *       actions: assign({
+ *         count: ({ context }) => context.count + 1
+ *       })
+ *     },
+ *     updateMessage: {
+ *       actions: assign(({ context, event }) => {
+ *         return {
+ *           message: event.message.trim()
+ *         };
+ *       })
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @param assignment An object that represents the partial context to update, or
+ *   a function that returns an object that represents the partial context to
+ *   update.
+ */
+function assign(assignment) {
+  if (guards_dist_xstateGuards.executingCustomAction) {
+    console.warn('Custom actions should not call `assign()` directly, as it is not imperative. See https://stately.ai/docs/actions#built-in-actions for more details.');
+  }
+  function assign(_args, _params) {
+    {
+      throw new Error(`This isn't supposed to be called`);
+    }
+  }
+  assign.type = 'xstate.assign';
+  assign.assignment = assignment;
+  assign.resolve = resolveAssign;
+  return assign;
+}
+
+exports.assign = assign;

package/dist/assign-e9c344ea.cjs.js

@@ -0,0 +1,129 @@
+'use strict';
+
+var guards_dist_xstateGuards = require('./raise-5872b9e8.cjs.js');
+
+function createSpawner(actorScope, {
+  machine,
+  context
+}, event, spawnedChildren) {
+  const spawn = (src, options) => {
+    if (typeof src === 'string') {
+      const logic = guards_dist_xstateGuards.resolveReferencedActor(machine, src);
+      if (!logic) {
+        throw new Error(`Actor logic '${src}' not implemented in machine '${machine.id}'`);
+      }
+      const actorRef = guards_dist_xstateGuards.createActor(logic, {
+        id: options?.id,
+        parent: actorScope.self,
+        syncSnapshot: options?.syncSnapshot,
+        input: typeof options?.input === 'function' ? options.input({
+          context,
+          event,
+          self: actorScope.self
+        }) : options?.input,
+        src,
+        systemId: options?.systemId
+      });
+      spawnedChildren[actorRef.id] = actorRef;
+      return actorRef;
+    } else {
+      const actorRef = guards_dist_xstateGuards.createActor(src, {
+        id: options?.id,
+        parent: actorScope.self,
+        syncSnapshot: options?.syncSnapshot,
+        input: options?.input,
+        src,
+        systemId: options?.systemId
+      });
+      return actorRef;
+    }
+  };
+  return (src, options) => {
+    const actorRef = spawn(src, options); // TODO: fix types
+    spawnedChildren[actorRef.id] = actorRef;
+    actorScope.defer(() => {
+      if (actorRef._processingStatus === guards_dist_xstateGuards.ProcessingStatus.Stopped) {
+        return;
+      }
+      actorRef.start();
+    });
+    return actorRef;
+  };
+}
+
+function resolveAssign(actorScope, snapshot, actionArgs, actionParams, {
+  assignment
+}) {
+  if (!snapshot.context) {
+    throw new Error('Cannot assign to undefined `context`. Ensure that `context` is defined in the machine config.');
+  }
+  const spawnedChildren = {};
+  const assignArgs = {
+    context: snapshot.context,
+    event: actionArgs.event,
+    spawn: createSpawner(actorScope, snapshot, actionArgs.event, spawnedChildren),
+    self: actorScope.self,
+    system: actorScope.system
+  };
+  let partialUpdate = {};
+  if (typeof assignment === 'function') {
+    partialUpdate = assignment(assignArgs, actionParams);
+  } else {
+    for (const key of Object.keys(assignment)) {
+      const propAssignment = assignment[key];
+      partialUpdate[key] = typeof propAssignment === 'function' ? propAssignment(assignArgs, actionParams) : propAssignment;
+    }
+  }
+  const updatedContext = Object.assign({}, snapshot.context, partialUpdate);
+  return [guards_dist_xstateGuards.cloneMachineSnapshot(snapshot, {
+    context: updatedContext,
+    children: Object.keys(spawnedChildren).length ? {
+      ...snapshot.children,
+      ...spawnedChildren
+    } : snapshot.children
+  }), undefined, undefined];
+}
+/**
+ * Updates the current context of the machine.
+ *
+ * @example
+ *
+ * ```ts
+ * import { createMachine, assign } from 'xstate';
+ *
+ * const countMachine = createMachine({
+ *   context: {
+ *     count: 0,
+ *     message: ''
+ *   },
+ *   on: {
+ *     inc: {
+ *       actions: assign({
+ *         count: ({ context }) => context.count + 1
+ *       })
+ *     },
+ *     updateMessage: {
+ *       actions: assign(({ context, event }) => {
+ *         return {
+ *           message: event.message.trim()
+ *         };
+ *       })
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @param assignment An object that represents the partial context to update, or
+ *   a function that returns an object that represents the partial context to
+ *   update.
+ */
+function assign(assignment) {
+  function assign(_args, _params) {
+  }
+  assign.type = 'xstate.assign';
+  assign.assignment = assignment;
+  assign.resolve = resolveAssign;
+  return assign;
+}
+
+exports.assign = assign;

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

@@ -25,8 +25,8 @@ export declare class StateMachine<TContext extends MachineContext, TEvent extend
     /**
      * Clones this state machine with the provided implementations.
      *
-     * @param implementations Options (`actions`, `guards`, `actors`, `delays`)
-     *   to recursively merge with the existing options.
+     * @param implementations Options (`actions`, `guards`, `actors`, `delays`) to
+     *   recursively merge with the existing options.
      * @returns A new `StateMachine` instance with the provided implementations.
      */
     provide(implementations: InternalMachineImplementations<ResolvedStateMachineTypes<TContext, DoNotInfer<TEvent>, TActor, TAction, TGuard, TDelay, TTag, TEmitted>>): StateMachine<TContext, TEvent, TChildren, TActor, TAction, TGuard, TDelay, TStateValue, TTag, TInput, TOutput, TEmitted, TMeta, TConfig>;

package/dist/declarations/src/graph/TestModel.d.ts

@@ -0,0 +1,71 @@
+import type { AdjacencyMap, StatePath, Step, TraversalOptions } from "./types.js";
+import { EventObject, ActorLogic, Snapshot, AnyStateMachine, EventFromLogic, SnapshotFrom, InputFrom } from "../index.js";
+import type { PathGenerator, TestModelOptions, TestParam, TestPath, TestPathResult } from "./types.js";
+type GetPathOptions<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TInput> = Partial<TraversalOptions<TSnapshot, TEvent, TInput>> & {
+    /**
+     * Whether to allow deduplicate paths so that paths that are contained by
+     * longer paths are included.
+     *
+     * @default false
+     */
+    allowDuplicatePaths?: boolean;
+};
+/**
+ * Creates a test model that represents an abstract model of a system under test
+ * (SUT).
+ *
+ * The test model is used to generate test paths, which are used to verify that
+ * states in the model are reachable in the SUT.
+ */
+export declare class TestModel<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TInput> {
+    testLogic: ActorLogic<TSnapshot, TEvent, TInput>;
+    options: TestModelOptions<TSnapshot, TEvent, TInput>;
+    defaultTraversalOptions?: TraversalOptions<TSnapshot, TEvent, TInput>;
+    getDefaultOptions(): TestModelOptions<TSnapshot, TEvent, TInput>;
+    constructor(testLogic: ActorLogic<TSnapshot, TEvent, TInput>, options?: Partial<TestModelOptions<TSnapshot, TEvent, TInput>>);
+    getPaths(pathGenerator: PathGenerator<TSnapshot, TEvent, TInput>, options?: GetPathOptions<TSnapshot, TEvent, TInput>): Array<TestPath<TSnapshot, TEvent>>;
+    getShortestPaths(options?: GetPathOptions<TSnapshot, TEvent, TInput>): Array<TestPath<TSnapshot, TEvent>>;
+    getShortestPathsFrom(paths: Array<TestPath<TSnapshot, TEvent>>, options?: GetPathOptions<TSnapshot, TEvent, TInput>): Array<TestPath<TSnapshot, TEvent>>;
+    getSimplePaths(options?: GetPathOptions<TSnapshot, TEvent, TInput>): Array<TestPath<TSnapshot, TEvent>>;
+    getSimplePathsFrom(paths: Array<TestPath<TSnapshot, TEvent>>, options?: GetPathOptions<TSnapshot, TEvent, TInput>): Array<TestPath<TSnapshot, TEvent>>;
+    private _toTestPath;
+    getPathsFromEvents(events: TEvent[], options?: GetPathOptions<TSnapshot, TEvent, TInput>): Array<TestPath<TSnapshot, TEvent>>;
+    /**
+     * An array of adjacencies, which are objects that represent each `state` with
+     * the `nextState` given the `event`.
+     */
+    getAdjacencyMap(): AdjacencyMap<TSnapshot, TEvent>;
+    testPath(path: StatePath<TSnapshot, TEvent>, params: TestParam<TSnapshot, TEvent>, options?: Partial<TestModelOptions<TSnapshot, TEvent, TInput>>): Promise<TestPathResult>;
+    testState(params: TestParam<TSnapshot, TEvent>, state: TSnapshot, options?: Partial<TestModelOptions<TSnapshot, TEvent, TInput>>): Promise<void>;
+    private _getStateTestKeys;
+    private _getEventExec;
+    testTransition(params: TestParam<TSnapshot, TEvent>, step: Step<TSnapshot, TEvent>): Promise<void>;
+    private _resolveOptions;
+}
+/**
+ * Creates a test model that represents an abstract model of a system under test
+ * (SUT).
+ *
+ * The test model is used to generate test paths, which are used to verify that
+ * states in the `machine` are reachable in the SUT.
+ *
+ * @example
+ *
+ * ```js
+ * const toggleModel = createModel(toggleMachine).withEvents({
+ *   TOGGLE: {
+ *     exec: async (page) => {
+ *       await page.click('input');
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @param machine The state machine used to represent the abstract model.
+ * @param options Options for the created test model:
+ *
+ *   - `events`: an object mapping string event types (e.g., `SUBMIT`) to an event
+ *       test config (e.g., `{exec: () => {...}, cases: [...]}`)
+ */
+export declare function createTestModel<TMachine extends AnyStateMachine>(machine: TMachine, options?: Partial<TestModelOptions<SnapshotFrom<TMachine>, EventFromLogic<TMachine>, InputFrom<TMachine>>>): TestModel<SnapshotFrom<TMachine>, EventFromLogic<TMachine>, unknown>;
+export {};

package/dist/declarations/src/graph/adjacency.d.ts

@@ -0,0 +1,8 @@
+import { ActorLogic, ActorSystem, EventObject, Snapshot } from "../index.js";
+import { TraversalOptions, AdjacencyMap } from "./types.js";
+export declare function getAdjacencyMap<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TInput, TSystem extends ActorSystem<any> = ActorSystem<any>>(logic: ActorLogic<TSnapshot, TEvent, TInput, TSystem>, options: TraversalOptions<TSnapshot, TEvent, TInput>): AdjacencyMap<TSnapshot, TEvent>;
+export declare function adjacencyMapToArray<TSnapshot, TEvent>(adjMap: AdjacencyMap<TSnapshot, TEvent>): Array<{
+    state: TSnapshot;
+    event: TEvent;
+    nextState: TSnapshot;
+}>;

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

@@ -0,0 +1,14 @@
+import { EventObject, AnyStateMachine, AnyActorLogic, EventFromLogic, Snapshot, InputFrom } from "../index.js";
+import type { SerializedSnapshot, StatePath, DirectedGraphNode, TraversalOptions, AnyStateNode, TraversalConfig } from "./types.js";
+/**
+ * Returns all state nodes of the given `node`.
+ *
+ * @param stateNode State node to recursively get child state nodes from
+ */
+export declare function getStateNodes(stateNode: AnyStateNode | AnyStateMachine): AnyStateNode[];
+export declare function serializeSnapshot(snapshot: Snapshot<any>): SerializedSnapshot;
+export declare function createDefaultMachineOptions<TMachine extends AnyStateMachine>(machine: TMachine, options?: TraversalOptions<ReturnType<TMachine['transition']>, EventFromLogic<TMachine>, InputFrom<TMachine>>): TraversalOptions<ReturnType<TMachine['transition']>, EventFromLogic<TMachine>, InputFrom<TMachine>>;
+export declare function createDefaultLogicOptions(): TraversalOptions<any, any, any>;
+export declare function toDirectedGraph(stateMachine: AnyStateNode | AnyStateMachine): DirectedGraphNode;
+export declare function resolveTraversalOptions<TLogic extends AnyActorLogic>(logic: TLogic, traversalOptions?: TraversalOptions<ReturnType<TLogic['transition']>, EventFromLogic<TLogic>, InputFrom<TLogic>>, defaultOptions?: TraversalOptions<ReturnType<TLogic['transition']>, EventFromLogic<TLogic>, InputFrom<TLogic>>): TraversalConfig<ReturnType<TLogic['transition']>, EventFromLogic<TLogic>>;
+export declare function joinPaths<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject>(headPath: StatePath<TSnapshot, TEvent>, tailPath: StatePath<TSnapshot, TEvent>): StatePath<TSnapshot, TEvent>;

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

@@ -0,0 +1,9 @@
+export { TestModel, createTestModel } from "./TestModel.js";
+export { adjacencyMapToArray, getAdjacencyMap } from "./adjacency.js";
+export { getStateNodes, joinPaths, serializeSnapshot, toDirectedGraph } from "./graph.js";
+export type { AdjacencyMap, AdjacencyValue } from "./types.js";
+export { getPathsFromEvents } from "./pathFromEvents.js";
+export * from "./pathGenerators.js";
+export { getShortestPaths } from "./shortestPaths.js";
+export { getSimplePaths } from "./simplePaths.js";
+export * from "./types.js";

package/dist/declarations/src/graph/pathFromEvents.d.ts

@@ -0,0 +1,3 @@
+import { ActorLogic, ActorSystem, EventObject, Snapshot } from "../index.js";
+import { StatePath, TraversalOptions } from "./types.js";
+export declare function getPathsFromEvents<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TInput, TSystem extends ActorSystem<any> = ActorSystem<any>>(logic: ActorLogic<TSnapshot, TEvent, TInput, TSystem>, events: TEvent[], options?: TraversalOptions<TSnapshot, TEvent, TInput>): Array<StatePath<TSnapshot, TEvent>>;

package/dist/declarations/src/graph/pathGenerators.d.ts

@@ -0,0 +1,4 @@
+import { EventObject, Snapshot } from "../index.js";
+import { PathGenerator } from "./types.js";
+export declare const createShortestPathsGen: <TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TInput>() => PathGenerator<TSnapshot, TEvent, TInput>;
+export declare const createSimplePathsGen: <TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TInput>() => PathGenerator<TSnapshot, TEvent, TInput>;

package/dist/declarations/src/graph/shortestPaths.d.ts

@@ -0,0 +1,3 @@
+import { AnyActorLogic, EventFromLogic, InputFrom } from "../index.js";
+import { StatePath, TraversalOptions } from "./types.js";
+export declare function getShortestPaths<TLogic extends AnyActorLogic>(logic: TLogic, options?: TraversalOptions<ReturnType<TLogic['transition']>, EventFromLogic<TLogic>, InputFrom<TLogic>>): Array<StatePath<ReturnType<TLogic['transition']>, EventFromLogic<TLogic>>>;

package/dist/declarations/src/graph/simplePaths.d.ts

@@ -0,0 +1,3 @@
+import { AnyActorLogic, EventFromLogic, InputFrom } from "../index.js";
+import { StatePath, TraversalOptions } from "./types.js";
+export declare function getSimplePaths<TLogic extends AnyActorLogic>(logic: TLogic, options?: TraversalOptions<ReturnType<TLogic['transition']>, EventFromLogic<TLogic>, InputFrom<TLogic>>): Array<StatePath<ReturnType<TLogic['transition']>, EventFromLogic<TLogic>>>;