xstate 5.19.3 → 5.20.0

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

@@ -0,0 +1,159 @@
+import { EventObject, StateNode, TransitionDefinition, Snapshot, MachineContext, ActorLogic, MachineSnapshot } from "../index.js";
+export type AnyStateNode = StateNode<any, any>;
+type JSONSerializable<T extends object, U> = T & {
+    toJSON: () => U;
+};
+type DirectedGraphLabel = JSONSerializable<{
+    text: string;
+}, {
+    text: string;
+}>;
+export type DirectedGraphEdge = JSONSerializable<{
+    id: string;
+    source: AnyStateNode;
+    target: AnyStateNode;
+    label: DirectedGraphLabel;
+    transition: TransitionDefinition<any, any>;
+}, {
+    source: string;
+    target: string;
+    label: ReturnType<DirectedGraphLabel['toJSON']>;
+}>;
+export type DirectedGraphNode = JSONSerializable<{
+    id: string;
+    stateNode: StateNode;
+    children: DirectedGraphNode[];
+    /** The edges representing all transitions from this `stateNode`. */
+    edges: DirectedGraphEdge[];
+}, {
+    id: string;
+    children: DirectedGraphNode[];
+}>;
+interface StatePlan<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject> {
+    /** The target state. */
+    state: TSnapshot;
+    /** The paths that reach the target state. */
+    paths: Array<StatePath<TSnapshot, TEvent>>;
+}
+export interface StatePath<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject> {
+    /** The ending state of the path. */
+    state: TSnapshot;
+    /**
+     * The ordered array of state-event pairs (steps) which reach the ending
+     * `state`.
+     */
+    steps: Steps<TSnapshot, TEvent>;
+    /** The combined weight of all steps in the path. */
+    weight: number;
+}
+export interface StatePlanMap<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject> {
+    [key: string]: StatePlan<TSnapshot, TEvent>;
+}
+export interface Step<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject> {
+    /** The event that resulted in the current state */
+    event: TEvent;
+    /** The current state after taking the event. */
+    state: TSnapshot;
+}
+export type Steps<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject> = Array<Step<TSnapshot, TEvent>>;
+type ExtractEvent<TEvent extends EventObject, TType extends TEvent['type']> = TEvent extends {
+    type: TType;
+} ? TEvent : never;
+export interface VisitedContext<TState, TEvent> {
+    vertices: Set<SerializedSnapshot>;
+    edges: Set<SerializedEvent>;
+    a?: TState | TEvent;
+}
+export interface SerializationConfig<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject> {
+    serializeState: (state: TSnapshot, event: TEvent | undefined, prevState?: TSnapshot) => string;
+    serializeEvent: (event: TEvent) => string;
+}
+type SerializationOptions<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject> = Partial<Pick<SerializationConfig<TSnapshot, TEvent>, 'serializeState' | 'serializeEvent'>>;
+export type TraversalOptions<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TInput> = {
+    input?: TInput;
+} & SerializationOptions<TSnapshot, TEvent> & Partial<Pick<TraversalConfig<TSnapshot, TEvent>, 'events' | 'limit' | 'fromState' | 'stopWhen' | 'toState'>>;
+export interface TraversalConfig<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject> extends SerializationConfig<TSnapshot, TEvent> {
+    events: readonly TEvent[] | ((state: TSnapshot) => readonly TEvent[]);
+    /**
+     * The maximum number of traversals to perform when calculating the state
+     * transition adjacency map.
+     *
+     * @default `Infinity`
+     */
+    limit: number;
+    fromState: TSnapshot | undefined;
+    /** When true, traversal of the adjacency map will stop for that current state. */
+    stopWhen: ((state: TSnapshot) => boolean) | undefined;
+    toState: ((state: TSnapshot) => boolean) | undefined;
+}
+type Brand<T, Tag extends string> = T & {
+    __tag: Tag;
+};
+export type SerializedSnapshot = Brand<string, 'state'>;
+export type SerializedEvent = Brand<string, 'event'>;
+export interface TestMeta<T, TContext extends MachineContext> {
+    test?: (testContext: T, state: MachineSnapshot<TContext, any, any, any, any, any, any, // TMeta
+    any>) => Promise<void> | void;
+    description?: string | ((state: MachineSnapshot<TContext, any, any, any, any, any, any, // TMeta
+    any>) => string);
+    skip?: boolean;
+}
+interface TestStateResult {
+    error: null | Error;
+}
+export interface TestStepResult {
+    step: Step<any, any>;
+    state: TestStateResult;
+    event: {
+        error: null | Error;
+    };
+}
+export interface TestParam<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject> {
+    states?: {
+        [key: string]: (state: TSnapshot) => void | Promise<void>;
+    };
+    events?: {
+        [TEventType in TEvent['type']]?: EventExecutor<TSnapshot, {
+            type: ExtractEvent<TEvent, TEventType>['type'];
+        }>;
+    };
+}
+export interface TestPath<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject> extends StatePath<TSnapshot, TEvent> {
+    description: string;
+    /**
+     * Tests and executes each step in `steps` sequentially, and then tests the
+     * postcondition that the `state` is reached.
+     */
+    test: (params: TestParam<TSnapshot, TEvent>) => Promise<TestPathResult>;
+}
+export interface TestPathResult {
+    steps: TestStepResult[];
+    state: TestStateResult;
+}
+/**
+ * Executes an effect using the `testContext` and `event` that triggers the
+ * represented `event`.
+ */
+export type EventExecutor<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject> = (step: Step<TSnapshot, TEvent>) => Promise<any> | void;
+export interface TestModelOptions<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TInput> extends TraversalOptions<TSnapshot, TEvent, TInput> {
+    stateMatcher: (state: TSnapshot, stateKey: string) => boolean;
+    logger: {
+        log: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+    serializeTransition: (state: TSnapshot, event: TEvent | undefined, prevState?: TSnapshot) => string;
+}
+export type PathGenerator<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TInput> = (behavior: ActorLogic<TSnapshot, TEvent, TInput>, options: TraversalOptions<TSnapshot, TEvent, TInput>) => Array<StatePath<TSnapshot, TEvent>>;
+export interface AdjacencyValue<TState, TEvent> {
+    state: TState;
+    transitions: {
+        [key: SerializedEvent]: {
+            event: TEvent;
+            state: TState;
+        };
+    };
+}
+export interface AdjacencyMap<TState, TEvent> {
+    [key: SerializedSnapshot]: AdjacencyValue<TState, TEvent>;
+}
+export {};

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

@@ -9,7 +9,7 @@ import type { Actor } from "./createActor.js";
 import { Guard, GuardPredicate, UnknownGuard } from "./guards.js";
 import { InspectionEvent } from "./inspection.js";
 import { Spawner } from "./spawn.js";
-import { AnyActorSystem, Clock } from './system.js';
+import { AnyActorSystem, Clock } from "./system.js";
 export type Identity<T> = {
     [K in keyof T]: T[K];
 };

package/dist/{log-12aa30c9.esm.js → log-1c257a58.esm.js}

@@ -1,128 +1,5 @@
-import { T as ProcessingStatus, z as resolveReferencedActor, A as createActor, U as cloneMachineSnapshot, V as XSTATE_ERROR, W as createErrorActorEvent, e as evaluateGuard, M as cancel, O as raise, P as spawnChild, R as stopChild } from './raise-59f80ebb.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;
-}
+import { T as XSTATE_ERROR, U as createErrorActorEvent, w as evaluateGuard, f as cancel, r as raise, h as spawnChild, k as stopChild } from './raise-b0a4e862.esm.js';
+import { a as assign } from './assign-c3259787.esm.js';
 
 function resolveEmit(_, snapshot, args, actionParams, {
   event: eventOrExpr
@@ -184,6 +61,8 @@ eventOrExpr) {
   return emit;
 }
 
+// this is needed to make JSDoc `@link` work properly
+
 /**
  * @remarks
  * `T | unknown` reduces to `unknown` and that can be problematic when it comes
@@ -499,4 +378,4 @@ function log(value = ({
   return log;
 }
 
-export { SpecialTargets as S, assign as a, enqueueActions as b, sendTo as c, emit as e, forwardTo as f, log as l, sendParent as s };
+export { SpecialTargets as S, enqueueActions as a, sendTo as b, emit as e, forwardTo as f, log as l, sendParent as s };

package/dist/{log-179b5431.cjs.js → log-215998b6.cjs.js}

@@ -1,130 +1,7 @@
 'use strict';
 
-var guards_dist_xstateGuards = require('./raise-cbaedcda.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;
-}
+var guards_dist_xstateGuards = require('./raise-5872b9e8.cjs.js');
+var assign = require('./assign-e9c344ea.cjs.js');
 
 function resolveEmit(_, snapshot, args, actionParams, {
   event: eventOrExpr
@@ -186,6 +63,8 @@ eventOrExpr) {
   return emit;
 }
 
+// this is needed to make JSDoc `@link` work properly
+
 /**
  * @remarks
  * `T | unknown` reduces to `unknown` and that can be problematic when it comes
@@ -386,7 +265,7 @@ function resolveEnqueueActions(actorScope, snapshot, args, actionParams, {
     actions.push(action);
   };
   enqueue.assign = (...args) => {
-    actions.push(assign(...args));
+    actions.push(assign.assign(...args));
   };
   enqueue.cancel = (...args) => {
     actions.push(guards_dist_xstateGuards.cancel(...args));
@@ -502,7 +381,6 @@ function log(value = ({
 }
 
 exports.SpecialTargets = SpecialTargets;
-exports.assign = assign;
 exports.emit = emit;
 exports.enqueueActions = enqueueActions;
 exports.forwardTo = forwardTo;

package/dist/{log-210b28c2.development.cjs.js → log-2c8d7f98.development.cjs.js}

@@ -1,136 +1,7 @@
 'use strict';
 
-var guards_dist_xstateGuards = require('./raise-32fab6fb.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;
-}
+var guards_dist_xstateGuards = require('./raise-7a84f9f0.development.cjs.js');
+var assign = require('./assign-c84786ab.development.cjs.js');
 
 function resolveEmit(_, snapshot, args, actionParams, {
   event: eventOrExpr
@@ -198,6 +69,8 @@ eventOrExpr) {
   return emit;
 }
 
+// this is needed to make JSDoc `@link` work properly
+
 /**
  * @remarks
  * `T | unknown` reduces to `unknown` and that can be problematic when it comes
@@ -414,7 +287,7 @@ function resolveEnqueueActions(actorScope, snapshot, args, actionParams, {
     actions.push(action);
   };
   enqueue.assign = (...args) => {
-    actions.push(assign(...args));
+    actions.push(assign.assign(...args));
   };
   enqueue.cancel = (...args) => {
     actions.push(guards_dist_xstateGuards.cancel(...args));
@@ -536,7 +409,6 @@ function log(value = ({
 }
 
 exports.SpecialTargets = SpecialTargets;
-exports.assign = assign;
 exports.emit = emit;
 exports.enqueueActions = enqueueActions;
 exports.forwardTo = forwardTo;