xstate 6.0.0-alpha.39 → 6.0.0-alpha.40

package/dist/xstate.development.esm.js

@@ -1,8 +1,8 @@
 export { T as TimeoutError, c as createAsyncLogic, a as createCallbackLogic, b as createEmptyActor, d as createEventObservableLogic, e as createLogic, f as createObservableLogic } from './index-17f889df.development.esm.js';
 import { m as matchesEventDescriptor, t as toArray$1, b as builtInActions, X as XSTATE_INIT, f as finalizeTransitionResult, d as deriveDeferredStarts, c as createTransitionEnqueue, w as withActorScope, a as XSTATE_STOP, r as resolveActionsWithContext, e as XSTATE_TIMER, g as createSendToEffect, i as isLazyActorScope, p as parseDelayToMilliseconds, h as isAtomicStateNode, j as createActor } from './createActor-2a03d4b2.development.esm.js';
 export { A as Actor, x as __unsafe_getAllOwnEventDescriptors, z as checkStateIn, j as createActor, k as createListenerLogic, l as createSubscriptionLogic, D as executeEffects, o as getInitialSnapshot, q as getNextSnapshot, v as getStateNodes, E as isBuiltInExecutableAction, u as isMachineSnapshot, n as listenerLogic, y as matchesState, B as pathToStateValue, s as subscriptionLogic, C as toObserver } from './createActor-2a03d4b2.development.esm.js';
-import { S as StateMachine } from './StateMachine-da29dd2e.development.esm.js';
-export { S as StateMachine, a as StateNode } from './StateMachine-da29dd2e.development.esm.js';
+import { S as StateMachine } from './StateMachine-f8c7feca.development.esm.js';
+export { S as StateMachine, a as StateNode } from './StateMachine-f8c7feca.development.esm.js';
 export { a as getInitialMicrosteps, g as getMicrosteps, b as getNextTransitions, i as initialTransition, t as transition } from './transition-f581ffa6.development.esm.js';
 
 /**
@@ -1967,6 +1967,15 @@ function mapState(snapshot, mapper) {
 function isObject(value) {
   return value !== null && typeof value === 'object';
 }
+function isVersionedStateMachine(entry) {
+  return 'transition' in entry && typeof entry.transition === 'function';
+}
+function hasSnapshotSchema(entry) {
+  return 'snapshotSchema' in entry && entry.snapshotSchema !== undefined;
+}
+function hasEventSchema(entry) {
+  return 'eventSchema' in entry && entry.eventSchema !== undefined;
+}
 function getSnapshotSource(raw, defaultId) {
   if (!isObject(raw)) {
     return {};
@@ -1993,65 +2002,57 @@ async function validate(schema, value, description) {
   return result.value;
 }
 async function finalizeSnapshot(snapshot, target) {
-  const context = await validate(target.schemas?.context, snapshot.context, `context for machine '${target.id}' version '${target.version}'`);
-  return {
+  return await validate(target.snapshotSchema, {
     ...snapshot,
-    context,
     machine: {
       id: target.id,
       version: target.version
     },
     version: target.version
-  };
+  }, `snapshot for machine '${target.id}' version '${target.version}'`);
 }
-async function validateEvents(events, machine) {
+async function validateEvents(events, source) {
   return Promise.all(events.map(async (event, index) => {
-    if (!isObject(event) || typeof event.type !== 'string') {
-      throw new Error(`Invalid event at index ${index}.`);
-    }
-    const eventSchemas = machine.schemas?.events;
-    const isFrameworkEvent = event.type.startsWith('xstate.') || event.type.startsWith('@xstate.');
-    const schema = eventSchemas && Object.hasOwn(eventSchemas, event.type) ? eventSchemas[event.type] : undefined;
-    if (eventSchemas && !schema && !isFrameworkEvent) {
-      throw new Error(`Unknown event '${event.type}' for machine '${machine.id}' version '${machine.version}'.`);
-    }
-    if (!schema) {
-      return event;
+    const result = await source.eventSchema['~standard'].validate(event);
+    if (result.issues) {
+      const message = result.issues[0]?.message;
+      if (message?.startsWith('Unknown event ')) {
+        throw new Error(message);
+      }
+      const type = isObject(event) ? event.type : undefined;
+      throw new Error(typeof type === 'string' ? `Invalid event '${type}' at index ${index}${message ? `: ${message}` : '.'}` : `Invalid event at index ${index}${message ? `: ${message}` : '.'}`);
     }
-    const {
-      type,
-      ...payload
-    } = event;
-    const validatedPayload = await validate(schema, payload, `event '${type}' at index ${index}`);
-    if (!isObject(validatedPayload)) {
-      throw new Error(`Invalid event '${type}' at index ${index}.`);
+    const validated = result.value;
+    if (!isObject(validated) || typeof validated.type !== 'string') {
+      throw new Error(`Invalid event at index ${index}.`);
     }
-    return {
-      ...validatedPayload,
-      type
-    };
+    return validated;
   }));
 }
 
-/** Creates migration and adaptation utilities backed by retained versions of one machine. */
-function machineVersions(machines, options) {
+/** Creates migration and adaptation utilities for versions of one machine. */
+function machineVersions(entries, options) {
   const byIdentity = new Map();
-  const machineId = machines[0].id;
-  for (const machine of machines) {
-    if (machine.version === undefined) {
-      throw new Error(`Machine '${machine.id}' must define a version.`);
+  const machinesByIdentity = new Map();
+  const machineId = entries[0].id;
+  for (const entry of entries) {
+    if (entry.version === undefined) {
+      throw new Error(`Machine '${entry.id}' must define a version.`);
     }
-    if (machine.version === '*') {
+    if (entry.version === '*') {
       throw new Error("Machine version '*' is reserved for wildcard migrations.");
     }
-    if (machine.id !== machineId) {
-      throw new Error(`Machine '${machine.id}' does not match machine ID '${machineId}'.`);
+    if (entry.id !== machineId) {
+      throw new Error(`Machine '${entry.id}' does not match machine ID '${machineId}'.`);
     }
-    const key = `${machine.id}\0${machine.version}`;
+    const key = `${entry.id}\0${entry.version}`;
     if (byIdentity.has(key)) {
-      throw new Error(`Duplicate machine identity '${machine.id}' version '${machine.version}'.`);
+      throw new Error(`Duplicate machine identity '${entry.id}' version '${entry.version}'.`);
+    }
+    byIdentity.set(key, entry);
+    if (isVersionedStateMachine(entry)) {
+      machinesByIdentity.set(key, entry);
     }
-    byIdentity.set(key, machine);
   }
   if (options?.unversioned !== undefined && !byIdentity.has(`${machineId}\0${options.unversioned}`)) {
     throw new Error(`Unversioned snapshot version '${options.unversioned}' is not retained for machine '${machineId}'.`);
@@ -2085,16 +2086,21 @@ function machineVersions(machines, options) {
     if (raw.version !== undefined && raw.version !== version) {
       throw new Error(`Persisted snapshot version '${raw.version}' conflicts with machine version '${version}'.`);
     }
-    const machine = byIdentity.get(`${id}\0${version}`);
-    if (!machine) {
+    const source = byIdentity.get(`${id}\0${version}`);
+    if (!source) {
       throw new Error(`Unknown machine identity '${id}' version '${version}'.`);
     }
-    const context = await validate(machine.schemas?.context, raw.context, `context for machine '${id}' version '${version}'`);
+    if (!hasSnapshotSchema(source)) {
+      throw new Error(`Machine version '${version}' does not define a snapshot schema.`);
+    }
+    const snapshot = await validate(source.snapshotSchema, raw, `snapshot for machine '${id}' version '${version}'`);
     return {
-      machine,
+      source,
+      ...(isVersionedStateMachine(source) && {
+        machine: source
+      }),
       snapshot: {
-        ...raw,
-        context,
+        ...snapshot,
         machine: {
           id,
           version
@@ -2105,15 +2111,16 @@ function machineVersions(machines, options) {
   return {
     parseSnapshot,
     async adaptEvents(events, adaptationOptions) {
-      const target = byIdentity.get(`${machineId}\0${adaptationOptions.to}`);
+      const target = machinesByIdentity.get(`${machineId}\0${adaptationOptions.to}`);
       if (!target) {
-        throw new Error(`Target version '${adaptationOptions.to}' is not retained for machine '${machineId}'.`);
+        throw new Error(`Target version '${adaptationOptions.to}' is not backed by a machine for '${machineId}'.`);
       }
       const sourceId = adaptationOptions.from.id ?? machineId;
       const source = byIdentity.get(`${sourceId}\0${adaptationOptions.from.version}`);
       let sourceError;
       let sourceValidationFailed = false;
-      if (source) {
+      const hasTypedSource = source && hasEventSchema(source);
+      if (hasTypedSource) {
         let sourceEvents;
         try {
           sourceEvents = await validateEvents(events, source);
@@ -2135,7 +2142,7 @@ function machineVersions(machines, options) {
       if (wildcardAdapter) {
         return validateEvents(await wildcardAdapter(events, adaptationOptions.from), target);
       }
-      if (source) {
+      if (hasTypedSource) {
         if (sourceValidationFailed) {
           throw sourceError instanceof Error ? sourceError : new Error(`Unable to validate event history for machine '${source.id}' version '${source.version}'.`, {
             cause: sourceError
@@ -2143,12 +2150,15 @@ function machineVersions(machines, options) {
         }
         throw new Error(`No event adapter from version '${source.version}' to '${target.version}' for machine '${target.id}'.`);
       }
+      if (source) {
+        throw new Error(`Machine version '${source.version}' does not define an event schema; only the '*' adapter can handle its event history.`);
+      }
       throw new Error(`Unknown event history source '${sourceId}' version '${adaptationOptions.from.version}'.`);
     },
     async migrateSnapshot(raw, migrationOptions) {
-      const target = byIdentity.get(`${machineId}\0${migrationOptions.to}`);
+      const target = machinesByIdentity.get(`${machineId}\0${migrationOptions.to}`);
       if (!target) {
-        throw new Error(`Target version '${migrationOptions.to}' is not retained for machine '${machineId}'.`);
+        throw new Error(`Target version '${migrationOptions.to}' is not backed by a machine for '${machineId}'.`);
       }
       let source;
       let parseError;
@@ -2158,10 +2168,10 @@ function machineVersions(machines, options) {
         parseError = error;
       }
       if (source) {
-        if (source.machine.version === target.version) {
+        if (source.source.version === target.version) {
           return finalizeSnapshot(source.snapshot, target);
         }
-        const exactMigration = migrationOptions.migrations[source.machine.version];
+        const exactMigration = migrationOptions.migrations[source.source.version];
         if (exactMigration) {
           return finalizeSnapshot(await exactMigration(source.snapshot), target);
         }
@@ -2169,7 +2179,7 @@ function machineVersions(machines, options) {
       const wildcardMigration = migrationOptions.migrations['*'];
       if (!wildcardMigration) {
         if (source) {
-          throw new Error(`No snapshot migration from version '${source.machine.version}' to '${target.version}' for machine '${target.id}'.`);
+          throw new Error(`No snapshot migration from version '${source.source.version}' to '${target.version}' for machine '${target.id}'.`);
         }
         throw parseError;
       }
@@ -2631,6 +2641,12 @@ let SpecialTargets = /*#__PURE__*/function (SpecialTargets) {
 
 /** A persisted snapshot tied to a versioned actor logic identity. */
 
+/**
+ * A persisted snapshot restorable into the given actor logic: any snapshot
+ * created by logic with the same machine `id` is accepted, regardless of
+ * version (version mismatches are handled at runtime, e.g. by `migrate`).
+ */
+
 /** @deprecated Use `AnyActor` instead. */
 
 // Based on RxJS types

package/dist/xstate.esm.js

@@ -1,8 +1,8 @@
 export { T as TimeoutError, c as createAsyncLogic, a as createCallbackLogic, b as createEmptyActor, d as createEventObservableLogic, e as createLogic, f as createObservableLogic } from './index-7020402e.esm.js';
 import { m as matchesEventDescriptor, t as toArray$1, b as builtInActions, X as XSTATE_INIT, f as finalizeTransitionResult, d as deriveDeferredStarts, c as createTransitionEnqueue, w as withActorScope, a as XSTATE_STOP, r as resolveActionsWithContext, e as XSTATE_TIMER, g as createSendToEffect, i as isLazyActorScope, p as parseDelayToMilliseconds, h as isAtomicStateNode, j as createActor } from './createActor-a211c276.esm.js';
 export { A as Actor, x as __unsafe_getAllOwnEventDescriptors, z as checkStateIn, j as createActor, k as createListenerLogic, l as createSubscriptionLogic, D as executeEffects, o as getInitialSnapshot, q as getNextSnapshot, v as getStateNodes, E as isBuiltInExecutableAction, u as isMachineSnapshot, n as listenerLogic, y as matchesState, B as pathToStateValue, s as subscriptionLogic, C as toObserver } from './createActor-a211c276.esm.js';
-import { S as StateMachine } from './StateMachine-2f47d890.esm.js';
-export { S as StateMachine, a as StateNode } from './StateMachine-2f47d890.esm.js';
+import { S as StateMachine } from './StateMachine-6082c3cf.esm.js';
+export { S as StateMachine, a as StateNode } from './StateMachine-6082c3cf.esm.js';
 export { a as getInitialMicrosteps, g as getMicrosteps, b as getNextTransitions, i as initialTransition, t as transition } from './transition-e8a13c00.esm.js';
 
 /**
@@ -1967,6 +1967,15 @@ function mapState(snapshot, mapper) {
 function isObject(value) {
   return value !== null && typeof value === 'object';
 }
+function isVersionedStateMachine(entry) {
+  return 'transition' in entry && typeof entry.transition === 'function';
+}
+function hasSnapshotSchema(entry) {
+  return 'snapshotSchema' in entry && entry.snapshotSchema !== undefined;
+}
+function hasEventSchema(entry) {
+  return 'eventSchema' in entry && entry.eventSchema !== undefined;
+}
 function getSnapshotSource(raw, defaultId) {
   if (!isObject(raw)) {
     return {};
@@ -1993,65 +2002,57 @@ async function validate(schema, value, description) {
   return result.value;
 }
 async function finalizeSnapshot(snapshot, target) {
-  const context = await validate(target.schemas?.context, snapshot.context, `context for machine '${target.id}' version '${target.version}'`);
-  return {
+  return await validate(target.snapshotSchema, {
     ...snapshot,
-    context,
     machine: {
       id: target.id,
       version: target.version
     },
     version: target.version
-  };
+  }, `snapshot for machine '${target.id}' version '${target.version}'`);
 }
-async function validateEvents(events, machine) {
+async function validateEvents(events, source) {
   return Promise.all(events.map(async (event, index) => {
-    if (!isObject(event) || typeof event.type !== 'string') {
-      throw new Error(`Invalid event at index ${index}.`);
-    }
-    const eventSchemas = machine.schemas?.events;
-    const isFrameworkEvent = event.type.startsWith('xstate.') || event.type.startsWith('@xstate.');
-    const schema = eventSchemas && Object.hasOwn(eventSchemas, event.type) ? eventSchemas[event.type] : undefined;
-    if (eventSchemas && !schema && !isFrameworkEvent) {
-      throw new Error(`Unknown event '${event.type}' for machine '${machine.id}' version '${machine.version}'.`);
-    }
-    if (!schema) {
-      return event;
+    const result = await source.eventSchema['~standard'].validate(event);
+    if (result.issues) {
+      const message = result.issues[0]?.message;
+      if (message?.startsWith('Unknown event ')) {
+        throw new Error(message);
+      }
+      const type = isObject(event) ? event.type : undefined;
+      throw new Error(typeof type === 'string' ? `Invalid event '${type}' at index ${index}${message ? `: ${message}` : '.'}` : `Invalid event at index ${index}${message ? `: ${message}` : '.'}`);
     }
-    const {
-      type,
-      ...payload
-    } = event;
-    const validatedPayload = await validate(schema, payload, `event '${type}' at index ${index}`);
-    if (!isObject(validatedPayload)) {
-      throw new Error(`Invalid event '${type}' at index ${index}.`);
+    const validated = result.value;
+    if (!isObject(validated) || typeof validated.type !== 'string') {
+      throw new Error(`Invalid event at index ${index}.`);
     }
-    return {
-      ...validatedPayload,
-      type
-    };
+    return validated;
   }));
 }
 
-/** Creates migration and adaptation utilities backed by retained versions of one machine. */
-function machineVersions(machines, options) {
+/** Creates migration and adaptation utilities for versions of one machine. */
+function machineVersions(entries, options) {
   const byIdentity = new Map();
-  const machineId = machines[0].id;
-  for (const machine of machines) {
-    if (machine.version === undefined) {
-      throw new Error(`Machine '${machine.id}' must define a version.`);
+  const machinesByIdentity = new Map();
+  const machineId = entries[0].id;
+  for (const entry of entries) {
+    if (entry.version === undefined) {
+      throw new Error(`Machine '${entry.id}' must define a version.`);
     }
-    if (machine.version === '*') {
+    if (entry.version === '*') {
       throw new Error("Machine version '*' is reserved for wildcard migrations.");
     }
-    if (machine.id !== machineId) {
-      throw new Error(`Machine '${machine.id}' does not match machine ID '${machineId}'.`);
+    if (entry.id !== machineId) {
+      throw new Error(`Machine '${entry.id}' does not match machine ID '${machineId}'.`);
     }
-    const key = `${machine.id}\0${machine.version}`;
+    const key = `${entry.id}\0${entry.version}`;
     if (byIdentity.has(key)) {
-      throw new Error(`Duplicate machine identity '${machine.id}' version '${machine.version}'.`);
+      throw new Error(`Duplicate machine identity '${entry.id}' version '${entry.version}'.`);
+    }
+    byIdentity.set(key, entry);
+    if (isVersionedStateMachine(entry)) {
+      machinesByIdentity.set(key, entry);
     }
-    byIdentity.set(key, machine);
   }
   if (options?.unversioned !== undefined && !byIdentity.has(`${machineId}\0${options.unversioned}`)) {
     throw new Error(`Unversioned snapshot version '${options.unversioned}' is not retained for machine '${machineId}'.`);
@@ -2085,16 +2086,21 @@ function machineVersions(machines, options) {
     if (raw.version !== undefined && raw.version !== version) {
       throw new Error(`Persisted snapshot version '${raw.version}' conflicts with machine version '${version}'.`);
     }
-    const machine = byIdentity.get(`${id}\0${version}`);
-    if (!machine) {
+    const source = byIdentity.get(`${id}\0${version}`);
+    if (!source) {
       throw new Error(`Unknown machine identity '${id}' version '${version}'.`);
     }
-    const context = await validate(machine.schemas?.context, raw.context, `context for machine '${id}' version '${version}'`);
+    if (!hasSnapshotSchema(source)) {
+      throw new Error(`Machine version '${version}' does not define a snapshot schema.`);
+    }
+    const snapshot = await validate(source.snapshotSchema, raw, `snapshot for machine '${id}' version '${version}'`);
     return {
-      machine,
+      source,
+      ...(isVersionedStateMachine(source) && {
+        machine: source
+      }),
       snapshot: {
-        ...raw,
-        context,
+        ...snapshot,
         machine: {
           id,
           version
@@ -2105,15 +2111,16 @@ function machineVersions(machines, options) {
   return {
     parseSnapshot,
     async adaptEvents(events, adaptationOptions) {
-      const target = byIdentity.get(`${machineId}\0${adaptationOptions.to}`);
+      const target = machinesByIdentity.get(`${machineId}\0${adaptationOptions.to}`);
       if (!target) {
-        throw new Error(`Target version '${adaptationOptions.to}' is not retained for machine '${machineId}'.`);
+        throw new Error(`Target version '${adaptationOptions.to}' is not backed by a machine for '${machineId}'.`);
       }
       const sourceId = adaptationOptions.from.id ?? machineId;
       const source = byIdentity.get(`${sourceId}\0${adaptationOptions.from.version}`);
       let sourceError;
       let sourceValidationFailed = false;
-      if (source) {
+      const hasTypedSource = source && hasEventSchema(source);
+      if (hasTypedSource) {
         let sourceEvents;
         try {
           sourceEvents = await validateEvents(events, source);
@@ -2135,7 +2142,7 @@ function machineVersions(machines, options) {
       if (wildcardAdapter) {
         return validateEvents(await wildcardAdapter(events, adaptationOptions.from), target);
       }
-      if (source) {
+      if (hasTypedSource) {
         if (sourceValidationFailed) {
           throw sourceError instanceof Error ? sourceError : new Error(`Unable to validate event history for machine '${source.id}' version '${source.version}'.`, {
             cause: sourceError
@@ -2143,12 +2150,15 @@ function machineVersions(machines, options) {
         }
         throw new Error(`No event adapter from version '${source.version}' to '${target.version}' for machine '${target.id}'.`);
       }
+      if (source) {
+        throw new Error(`Machine version '${source.version}' does not define an event schema; only the '*' adapter can handle its event history.`);
+      }
       throw new Error(`Unknown event history source '${sourceId}' version '${adaptationOptions.from.version}'.`);
     },
     async migrateSnapshot(raw, migrationOptions) {
-      const target = byIdentity.get(`${machineId}\0${migrationOptions.to}`);
+      const target = machinesByIdentity.get(`${machineId}\0${migrationOptions.to}`);
       if (!target) {
-        throw new Error(`Target version '${migrationOptions.to}' is not retained for machine '${machineId}'.`);
+        throw new Error(`Target version '${migrationOptions.to}' is not backed by a machine for '${machineId}'.`);
       }
       let source;
       let parseError;
@@ -2158,10 +2168,10 @@ function machineVersions(machines, options) {
         parseError = error;
       }
       if (source) {
-        if (source.machine.version === target.version) {
+        if (source.source.version === target.version) {
           return finalizeSnapshot(source.snapshot, target);
         }
-        const exactMigration = migrationOptions.migrations[source.machine.version];
+        const exactMigration = migrationOptions.migrations[source.source.version];
         if (exactMigration) {
           return finalizeSnapshot(await exactMigration(source.snapshot), target);
         }
@@ -2169,7 +2179,7 @@ function machineVersions(machines, options) {
       const wildcardMigration = migrationOptions.migrations['*'];
       if (!wildcardMigration) {
         if (source) {
-          throw new Error(`No snapshot migration from version '${source.machine.version}' to '${target.version}' for machine '${target.id}'.`);
+          throw new Error(`No snapshot migration from version '${source.source.version}' to '${target.version}' for machine '${target.id}'.`);
         }
         throw parseError;
       }
@@ -2631,6 +2641,12 @@ let SpecialTargets = /*#__PURE__*/function (SpecialTargets) {
 
 /** A persisted snapshot tied to a versioned actor logic identity. */
 
+/**
+ * A persisted snapshot restorable into the given actor logic: any snapshot
+ * created by logic with the same machine `id` is accepted, regardless of
+ * version (version mismatches are handled at runtime, e.g. by `migrate`).
+ */
+
 /** @deprecated Use `AnyActor` instead. */
 
 // Based on RxJS types