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

package/dist/xstate.cjs.js

@@ -4,7 +4,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var dist_xstateActors = require('./index-21d08fff.cjs.js');
 var createActor = require('./createActor-d5305cc9.cjs.js');
-var StateMachine = require('./StateMachine-94084ac7.cjs.js');
+var StateMachine = require('./StateMachine-1464d5e4.cjs.js');
 var transition = require('./transition-2dcabac8.cjs.js');
 
 /**
@@ -1969,6 +1969,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 {};
@@ -1995,65 +2004,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}'.`);
@@ -2087,16 +2088,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
@@ -2107,15 +2113,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);
@@ -2137,7 +2144,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
@@ -2145,12 +2152,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;
@@ -2160,10 +2170,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);
         }
@@ -2171,7 +2181,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;
       }
@@ -2633,6 +2643,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.development.cjs.js

@@ -4,7 +4,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var dist_xstateActors = require('./index-3d1368f7.development.cjs.js');
 var createActor = require('./createActor-c0f78b8a.development.cjs.js');
-var StateMachine = require('./StateMachine-144215d2.development.cjs.js');
+var StateMachine = require('./StateMachine-76ee1d6e.development.cjs.js');
 var transition = require('./transition-4ba58b71.development.cjs.js');
 
 /**
@@ -1969,6 +1969,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 {};
@@ -1995,65 +2004,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}'.`);
@@ -2087,16 +2088,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
@@ -2107,15 +2113,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);
@@ -2137,7 +2144,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
@@ -2145,12 +2152,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;
@@ -2160,10 +2170,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);
         }
@@ -2171,7 +2181,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;
       }
@@ -2633,6 +2643,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