xstate 6.0.0-alpha.64 → 6.0.0-alpha.65

package/README.md

@@ -33,6 +33,13 @@ timers without replaying entry actions. Await `executeEffects()` before persisti
 to retain accepted timer deadlines. The host handles root error snapshots;
 `run()` rejects with the root error. See [durable execution](../../docs/durable-execution.md).
 
+<!-- state context refinements from packages/core/src/setup.ts and packages/core/src/State.ts -->
+
+For [typestates](../../docs/typestates.md), declare state-level `schemas.context`
+in `setup({ states })`. State functions receive narrowed context, transitions
+check the target context requirements, and `snapshot.matches(...)` narrows
+context when reading snapshots.
+
 <!-- typed inline invocation from packages/core/src/setup.ts -->
 
 Use `s.createInvoke({ src, input, onDone })` inline in `s.createMachine(...)` for an actor used in one state. It infers the actor's input and output and the enclosing state's narrowed context without registering that actor in `setup.actors`. See [typed inline invokes](../../docs/invoke.md#typed-inline-invokes).
@@ -41,6 +48,14 @@ Pass an async function directly as `src`, with `schemas.input`, `schemas.output`
 
 The helper requires input for actors whose input excludes `undefined`, and checks child IDs and source compatibility against `schemas.children` declared in the setup or machine.
 
+<!-- graph traversal events from packages/core/src/graph/index.ts -->
+
+`getAllOwnEvents(snapshot)` from `xstate/graph` includes invoke completions, errors, and delayed events. Compose it with custom traversal payloads: supplied `events` replace the defaults. See [model-based testing](../../docs/model-based-testing.md).
+
+<!-- JSON loading and runtime validation from packages/core/src/createMachineFromConfig.ts -->
+
+Revive JSON definitions with `createMachineFromConfig(json, { schemas, validator, ...sources })` to restore runtime validation. The loader validates structural keys and references and copies its input; serialized definitions are independent copies. See [serialization](../../docs/serialization.md).
+
 For flat finite state machines, `xstate/fsm` provides a tiny pure transition
 table with context and TypeScript support:
 
@@ -635,3 +650,15 @@ For these reasons, it is impractical for our team to be bound by decisions taken
 ### Packages
 
 Most of the packages in the XState family declare a peer dependency on XState itself. We’ll be cautious about maintaining compatibility with already-released packages when releasing a new version of XState, **but** each release of packages depending on XState will always adjust the declared peer dependency range to include the latest version of XState. For example, you should always be able to update `xstate` without `@xstate/react`. But when you update `@xstate/react`, we highly recommend updating `xstate` too.
+
+<!-- public input validation contract from src/StateMachine.ts -->
+Validate external input with `machine.eventSchema` before `actor.send()`.
+It validates complete public events, excludes internal/runtime events, and allows
+explicitly configured routes. Payload checks require runtime schemas;
+`types<T>()` supplies types only. See [public input validation](../../docs/internal-events.md#validating-public-input).
+
+<!-- entry effects and terminal transition behavior from packages/core/src/stateUtils.ts and transitionActions.ts -->
+
+Functions passed to `enq(...)` run as effects; their returned context or child patches are ignored, with a development warning. Return a computed patch from the transition, entry, or exit function instead. Entry/exit functions using enqueue must declare exactly `(args, enq)`; default/rest parameter wrappers receive a development diagnostic. See [actions](../../docs/actions.md).
+
+Pure transitions preserve terminal snapshots and return no effects. `snapshot.can(...)` returns `false` for terminal snapshots; active dry runs propagate evaluation errors. See [snapshots](../../docs/snapshots.md) and [states](../../docs/states.md).

package/dist/{createActor-521c8805.development.cjs.js → createActor-1df42c9e.development.cjs.js}

@@ -530,7 +530,33 @@ function withActorScope(args, actorScope) {
 }
 
 function execCustomEffect() {
-  return this.action?.(...this.args);
+  const result = this.action?.(...this.args);
+  {
+    warnOnIgnoredEffectResult(this, result);
+  }
+  return result;
+}
+const warnedEffectResults = new WeakSet();
+
+/**
+ * A function passed to `enq(...)` runs as an effect after the transition is
+ * computed, so a `{ context }` or `{ children }` it returns is never applied.
+ * Development builds say so, once per function.
+ */
+function warnOnIgnoredEffectResult(effect, result) {
+  if (!effect.action || result === null || typeof result !== 'object' || warnedEffectResults.has(effect.action)) {
+    return;
+  }
+  const prototype = Object.getPrototypeOf(result);
+  if (prototype !== Object.prototype && prototype !== null) {
+    return;
+  }
+  const keys = ['context', 'children'].filter(key => key in result);
+  if (!keys.length) {
+    return;
+  }
+  warnedEffectResults.add(effect.action);
+  console.warn(`Action "${effect.type || '(anonymous)'}" returned { ${keys.join(', ')} }, which is ignored: functions passed to enq(...) run as effects after the transition. Return the patch from the transition, entry or exit function instead; a named action can be called there directly and its result returned.`);
 }
 function execEmitEffect(runtime = this.source.system) {
   return runtime.emitEvent(this.source, this.event);
@@ -1059,6 +1085,16 @@ function createTransitionEnqueue(actorScope, actions, internalEvents, actorSubsc
     props[key] = guard(props[key]);
   }
   const enqueue = createEnqueueObject(props, guard((action, ...args) => {
+    // A named action is `undefined` when it has no implementation. Skip it:
+    // an `{ action, args }` record without a function would be emitted as
+    // an event. Speculative passes (`can()`, conflict resolution) run with
+    // `createActors: false`; warn only when the transition really runs.
+    if (typeof action !== 'function') {
+      if (createActors) {
+        warnNotAFunction(action);
+      }
+      return;
+    }
     pushBuiltInAction(actions, action, ...args);
   }));
   enqueueClosers.set(enqueue, () => {
@@ -1083,6 +1119,10 @@ function lateEnqueueCall() {
     throw new Error('enq.* called after the transition function returned');
   }
 }
+function warnNotAFunction(value) {
+  const received = typeof value === 'string' ? `the string "${value}"` : value !== null && typeof value === 'object' ? 'an object' : String(value);
+  console.warn(`enq(...) received ${received} instead of a function, so nothing was enqueued. A named action is undefined when it has no implementation: implement it in setup({ actions }) or the machine config, or pass it to machine.provide({ actions }).`);
+}
 function getBuiltInActionFields(action, args) {
   switch (action) {
     case builtInActions['@xstate.spawn']:
@@ -2288,6 +2328,10 @@ function getDelayedTransitions(stateNode) {
   }));
 }
 function formatTransition(stateNode, descriptor, transitionConfig) {
+  const removedKey = getRemovedTransitionKey(transitionConfig);
+  if (removedKey) {
+    throw new Error(`Transition "${descriptor || 'always'}" in state "${stateNode.id}" uses ${removedKey}, which was removed in v6. Use a transition function.`);
+  }
   const normalizedTarget = normalizeTarget(transitionConfig.target);
   const reenter = transitionConfig.reenter ?? false;
   const target = resolveTarget(stateNode, normalizedTarget);
@@ -2298,14 +2342,46 @@ function formatTransition(stateNode, descriptor, transitionConfig) {
     source: stateNode,
     reenter,
     eventType: descriptor,
-    toJSON: () => ({
-      ...transition,
-      source: `#${stateNode.id}`,
-      target: target ? target.map(t => `#${t.id}`) : undefined
-    })
+    toJSON: () => transitionDefinitionToJSON(transition)
   };
   return transition;
 }
+function transitionDefinitionToJSON(transition) {
+  const {
+    definition: _,
+    ...serializableTransition
+  } = transition;
+  return {
+    ...serializableTransition,
+    source: `#${transition.source.id}`,
+    target: transition.target?.map(target => `#${target.id}`)
+  };
+}
+
+/**
+ * Returns the v5 key of a transition object that v6 would misread, in every
+ * build: `cond` is never read, so the transition would always be taken,
+ * transition `actions` would not run as written, and only a function `guard`
+ * can be called. Development builds explain each key earlier, in
+ * `diagnoseAuthorConfig`. Compiled configs (JSON, SCXML) never set them.
+ */
+function getRemovedTransitionKey(transitionConfig) {
+  const {
+    cond,
+    actions,
+    guard
+  } = transitionConfig;
+  if (cond !== undefined) {
+    return '"cond"';
+  }
+  if (actions !== undefined) {
+    return '"actions"';
+  }
+  if (guard !== undefined && typeof guard !== 'function') {
+    return 'an object-form "guard"';
+  }
+  return undefined;
+}
 function isStateNodeDescendantOf(stateNode, ancestor) {
   for (let current = stateNode.parent; current; current = current.parent) {
     if (current === ancestor) {
@@ -2648,12 +2724,18 @@ function removeConflictingTransitions(enabledTransitions, stateNodeSet, snapshot
 }
 function createTransitionResultResolver(snapshot, event, actorScope, resolveActions, selectionResults) {
   let cache;
-  return transition => {
-    if (!transition.to) {
-      return getTransitionResult(transition, snapshot, event, actorScope, {
-        resolveActions,
-        selectionResult: selectionResults?.get(transition)
-      });
+  return (transition, applied) => {
+    if (!transition.to && !applied) {
+      // An object transition's targets are static, so reading them must not
+      // run its `context` and `input` mappers
+      return {
+        targets: transition.target,
+        context: undefined,
+        reenter: transition.reenter,
+        actions: undefined,
+        internalEvents: undefined,
+        input: undefined
+      };
     }
     let result = cache?.get(transition);
     if (!result) {
@@ -2881,13 +2963,20 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
         children: args.children,
         actions: args.actions,
         actors: args.actors,
+        guards: currentSnapshot.machine.sources.guards,
+        delays: currentSnapshot.machine.sources.delays,
         input,
         stateNode
       }, actorScope) : {
         ...args,
+        guards: currentSnapshot.machine.sources.guards,
+        delays: currentSnapshot.machine.sources.delays,
         input,
         stateNode
-      }, enqueue), '_special' in transitionFn ? {
+      },
+      // This function runs during action resolution, where enqueued
+      // effects are no longer collected.
+      createIgnoredEnqueue(transitionFn, kind, stateNode.id) ), '_special' in transitionFn ? {
         _special: true
       } : {});
       return [[wrappedAction], undefined, undefined];
@@ -2925,7 +3014,7 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
       }
       for (const exitStateNode of statesToExit) {
         const stateInput = getStateInput(currentSnapshot, exitStateNode.id);
-        const [exitActions, nextContext, internalEvents] = exitStateNode.exit ? getStateActionsAndContext(exitStateNode.exit, nextState.context, currentSnapshot.children, stateInput, 'exit', exitStateNode) : [[], undefined, undefined];
+        const [exitActions, nextContext, internalEvents] = exitStateNode.exit ? getStateActionsAndContext(exitStateNode.exit, nextState.context, nextState.children, stateInput, 'exit', exitStateNode) : [[], undefined, undefined];
         if (internalEvents?.length) {
           internalQueue.push(...internalEvents);
         }
@@ -2955,11 +3044,20 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
     let context = nextState.context;
     const transitionActions = [];
     const internalEvents = [];
+    const resolvedTransitions = [];
     for (const t of filteredTransitions) {
-      if (t.actions) {
-        transitionActions.push(...toArray(t.actions));
+      const res = getCurrentTransitionResult(t, true);
+      if (t.to) {
+        const resolvedTransition = {
+          ...t,
+          target: res.targets,
+          definition: t
+        };
+        resolvedTransition.toJSON = () => transitionDefinitionToJSON(resolvedTransition);
+        resolvedTransitions.push(resolvedTransition);
+      } else {
+        resolvedTransitions.push(t);
       }
-      const res = getCurrentTransitionResult(t);
       if (res.context !== undefined) {
         context = mergeContextPatch(context, res.context);
       }
@@ -3115,7 +3213,7 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
         const {
           targets,
           input
-        } = getCurrentTransitionResult(transition);
+        } = getCurrentTransitionResult(transition, true);
         if (input && targets) {
           for (const targetNode of targets.filter(targetNode => enteredTargetsByTransition.get(transition)?.has(targetNode))) {
             stateInputMap[targetNode.id] = input;
@@ -3124,12 +3222,12 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
         }
       }
       const completedNodes = new Set();
-      const children = {
-        ...nextState.children
-      };
       for (const stateNodeToEnter of [...statesToEnter].sort((a, b) => a.order - b.order)) {
         mutStateNodeSet.add(stateNodeToEnter);
         const actions = [];
+        // Read the children for each state: the entry actions of the states
+        // entered before this one may have spawned or stopped children.
+        let children = nextState.children;
 
         // Final states are inert, so (as in SCXML) their invocations never
         // start.
@@ -3168,7 +3266,10 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
             args: [actor]
           });
           if (invokeDef.id) {
-            children[invokeDef.id] = actor;
+            children = {
+              ...children,
+              [invokeDef.id]: actor
+            };
           }
         }
         if (invoked) {
@@ -3288,7 +3389,12 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
       nextStateNodesToExit.forEach(stateNode => {
         if (stateNode.exit) {
           const stateInput = getStateInput(nextState, stateNode.id);
-          const [exitActions,, nextInternalEvents] = getStateActionsAndContext(stateNode.exit, nextState.context, nextState.children, stateInput, 'exit', stateNode);
+          const [exitActions, nextContext, nextInternalEvents] = getStateActionsAndContext(stateNode.exit, nextState.context, nextState.children, stateInput, 'exit', stateNode);
+          if (nextContext) {
+            nextState = cloneMachineSnapshot(nextState, {
+              context: nextContext
+            });
+          }
           allExitActions.push(...exitActions);
           if (nextInternalEvents?.length) {
             internalQueue.push(...nextInternalEvents);
@@ -3309,14 +3415,14 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
       // If context was changed (e.g. by entry actions during self-transition),
       // clone to ensure reference inequality for eventless transition re-evaluation
       if (nextState.context !== originalContext) {
-        return [nextState === currentSnapshot ? cloneMachineSnapshot(nextState) : nextState, executableActions];
+        return [nextState === currentSnapshot ? cloneMachineSnapshot(nextState) : nextState, executableActions, resolvedTransitions];
       }
-      return [nextState, executableActions];
+      return [nextState, executableActions, resolvedTransitions];
     }
     return [cloneMachineSnapshot(nextState, {
       _nodes: nextStateNodes,
       historyValue
-    }), executableActions];
+    }), executableActions, resolvedTransitions];
   }
 }
 
@@ -3426,6 +3532,15 @@ class InfiniteTransitionError extends Error {
   }
 }
 function macrostep(snapshot, event, actorScope, internalQueue, initialMicrosteps = []) {
+  // A done, error or stopped snapshot processes no events, as in an actor:
+  // every event is unhandled. The initial macrostep passes `initialMicrosteps`
+  // and may start from a snapshot that is already done.
+  if (snapshot.status !== 'active' && !initialMicrosteps.length) {
+    return {
+      snapshot,
+      microsteps: [[snapshot, [], []]]
+    };
+  }
   let nextSnapshot = snapshot;
   const microsteps = initialMicrosteps.slice();
   // Whether a transition handled the external event. A handled event always
@@ -3494,6 +3609,7 @@ function macrostep(snapshot, event, actorScope, internalQueue, initialMicrosteps
     };
   }
   function addMicrostep(step, transitions) {
+    transitions = step[2] ?? transitions;
     // collect microsteps; their transitions are surfaced on the enclosing
     // '@xstate.transition' event via its `microsteps[]` facet (there is no
     // standalone microstep event) and returned by `getMicrosteps()`
@@ -3649,6 +3765,42 @@ function assertSyncTransitionResult(res, event, sourceId, kind) {
     throw new Error(kind ? `${kind === 'entry' ? 'Entry' : 'Exit'} functions must be synchronous. The ${kind} function of state "${sourceId}" returned a promise (event "${event.type}"). Move async work into an invoked or spawned actor, or enq.effect.` : `Transition functions must be synchronous. Transition for event "${event.type}" in state "${sourceId}" returned a promise. Move async work into an invoked or spawned actor, or enq.effect.`);
   }
 }
+const ignoredEnqueues = new WeakMap();
+
+/**
+ * The enqueue object that an entry or exit function gets in development when it
+ * is not declared with exactly two parameters. Such a function runs during
+ * action resolution, where enqueued effects are no longer collected, so every
+ * call is ignored. This one warns, once per function.
+ */
+function createIgnoredEnqueue(fn, kind, stateNodeId) {
+  let enqueue = ignoredEnqueues.get(fn);
+  if (enqueue) {
+    return enqueue;
+  }
+  let warned = false;
+  const ignore = (method, result) => (..._args) => {
+    if (!warned) {
+      warned = true;
+      console.warn(`The ${kind} function of state "${stateNodeId}" called ${method}(...), which was ignored. Only ${kind} functions declared with exactly two parameters, (args, enq) => ..., get a working enq. This one has fn.length ${fn.length}; fn.length stops counting at a default or rest parameter.`);
+    }
+    return result?.();
+  };
+  const emptyActor = () => ({});
+  enqueue = createEnqueueObject({
+    cancel: ignore('enq.cancel'),
+    emit: ignore('enq.emit'),
+    log: ignore('enq.log'),
+    raise: ignore('enq.raise'),
+    sendTo: ignore('enq.sendTo'),
+    stop: ignore('enq.stop'),
+    spawn: ignore('enq.spawn', emptyActor),
+    listen: ignore('enq.listen', emptyActor),
+    subscribeTo: ignore('enq.subscribeTo', emptyActor)
+  }, ignore('enq'));
+  ignoredEnqueues.set(fn, enqueue);
+  return enqueue;
+}
 let transitionEffectEnqueue;
 function getTransitionEffectEnqueue() {
   return transitionEffectEnqueue ??= createEnqueueObject({
@@ -3978,6 +4130,17 @@ function isMachineSnapshot(value) {
   return !!value && typeof value === 'object' && 'machine' in value && 'value' in value;
 }
 
+/**
+ * The values that `snapshot.matches(...)` accepts for a state value: a state
+ * key, a dot-delimited path to a descendant state, or a partial state value.
+ * Non-literal state values accept any value.
+ */
+
+/**
+ * `unknown` if `matches(...)` accepts `TTestStateValue` for `TStateValue`,
+ * otherwise `never`. Non-literal test values are always accepted.
+ */
+
 /** @public */
 
 const machineSnapshotMatches = function matches(testValue) {
@@ -4502,7 +4665,14 @@ function getAllOwnEventDescriptors(snapshot) {
   return [...new Set([...snapshot.nodes.flatMap(sn => sn.ownEvents)])];
 }
 
-/** @internal Events synthesized from active transition descriptors. */
+/**
+ * Returns one event per transition of the active state nodes of `snapshot`,
+ * including the internal events for invoked actors (`xstate.done.actor`,
+ * `xstate.error.actor`) and delayed transitions (`xstate.after`). Graph
+ * traversal sends these when the `events` option is not given.
+ *
+ * @public
+ */
 function getAllOwnEvents(snapshot) {
   const events = snapshot.nodes.flatMap(stateNode => [...stateNode.transitions.values()].flatMap(transitions => transitions.map(transition => {
     const event = {
@@ -6063,7 +6233,10 @@ class Actor {
       const [nextSnapshot, effects] = nextState;
       if (nextSnapshot === previousSnapshot && !effects.length &&
       // State machine snapshots only; other logic may ignore events freely.
-      'machine' in previousSnapshot && !event.type.startsWith('xstate.')) {
+      'machine' in previousSnapshot && (
+      // `xstate.route` is sent by users, so a route that matches nothing is
+      // reported like any other unhandled event.
+      !event.type.startsWith('xstate.') || event.type === 'xstate.route')) {
         this._reportUnhandledEvent(event);
       }
       snapshot = nextSnapshot;
@@ -6084,10 +6257,11 @@ class Actor {
   _reportUnhandledEvent(event) {
     safeCall(() => this.options.onUnhandledEvent?.(event, this._snapshot));
     {
+      const to = event.type === 'xstate.route' ? ` to ${JSON.stringify(event.to)}` : '';
       const warned = this._warnedUnhandledTypes ??= new Set();
-      if (!warned.has(event.type)) {
-        warned.add(event.type);
-        console.warn(`Actor ${this.id} received event "${event.type}" in state ${JSON.stringify(this._snapshot.value)} with no matching transition`);
+      if (!warned.has(event.type + to)) {
+        warned.add(event.type + to);
+        console.warn(`Actor ${this.id} received event "${event.type}"${to} in state ${JSON.stringify(this._snapshot.value)} with no matching transition`);
       }
     }
   }