xstate 6.0.0-alpha.35 → 6.0.0-alpha.36

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

@@ -7,7 +7,7 @@ export { createMachineFromConfig } from "./createMachineFromConfig.js";
 export type { ActionJSON, GuardJSON, InvokeJSON, MachineJSON, StateNodeJSON, TransitionJSON } from "./createMachineFromConfig.js";
 export { machineConfigToJSON, serializeMachine, type CodeExpression } from "./serialize.js";
 export { mapState } from "./mapState.js";
-export { machineVersions, type MigrateSnapshotOptions, type MachineVersionsOptions, type ParsedPersistedSnapshot, type PersistedMachineIdentity, type PersistedSnapshotDataFrom, type PersistedSnapshotSource, type SnapshotMigrationHandlers, type PersistedSnapshotFrom } from "./machineVersions.js";
+export { machineVersions, type AdaptEventsOptions, type EventAdapterHandlers, type EventHistorySource, type MigrateSnapshotOptions, type MachineVersionsOptions, type ParsedPersistedSnapshot, type PersistedMachineIdentity, type PersistedSnapshotDataFrom, type PersistedSnapshotSource, type SnapshotMigrationHandlers, type PersistedSnapshotFrom } from "./machineVersions.js";
 export { types, isTypeSchema, type StandardSchemaV1, type TypeSchema } from "./schema.types.js";
 export type { ActorValidationBoundary, ActorValidationEventOrigin, ActorValidationRequest, ActorLogicValidator } from "./validation.types.js";
 export { createSystem, setup } from "./setup.js";

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

@@ -1,5 +1,5 @@
 import type { AnyMachineSchemas } from "./types.v6.js";
-import type { AnyStateMachine, ContextFrom, PersistedSnapshotFor, Snapshot } from "./types.js";
+import type { AnyStateMachine, ContextFrom, EventFrom, PersistedSnapshotFor, Snapshot } from "./types.js";
 export type PersistedMachineIdentity<TMachine extends AnyStateMachine = AnyStateMachine> = {
     id: TMachine['id'];
     version: NonNullable<TMachine['version']>;
@@ -44,12 +44,27 @@ export type MigrateSnapshotOptions<TMachines extends readonly VersionedStateMach
     to: TTargetVersion;
     migrations: SnapshotMigrationHandlers<TMachines, MachineForVersion<TMachines, TTargetVersion>>;
 };
-/** Creates parsers backed by retained versions of one machine. */
+export type EventHistorySource = {
+    id?: string;
+    version?: string;
+};
+export type EventAdapterHandlers<TMachines extends readonly VersionedStateMachine[], TTarget extends VersionedStateMachine> = {
+    [TVersion in Exclude<MachineVersion<TMachines>, TTarget['version']>]?: (events: readonly EventFrom<MachineForVersion<TMachines, TVersion>>[]) => MaybePromise<readonly EventFrom<TTarget>[]>;
+} & {
+    '*'?: (events: readonly unknown[], source: EventHistorySource) => MaybePromise<readonly EventFrom<TTarget>[]>;
+};
+export type AdaptEventsOptions<TMachines extends readonly VersionedStateMachine[], TTargetVersion extends MachineVersion<TMachines>> = {
+    from: EventHistorySource;
+    to: TTargetVersion;
+    adapters: EventAdapterHandlers<TMachines, MachineForVersion<TMachines, TTargetVersion>>;
+};
+/** Creates migration and adaptation utilities backed by retained versions of one machine. */
 export declare function machineVersions<const TMachines extends readonly [
     VersionedStateMachine,
     ...VersionedStateMachine[]
 ]>(machines: TMachines, options?: MachineVersionsOptions<TMachines>): {
     parseSnapshot: (raw: unknown) => Promise<ParsedPersistedSnapshot<TMachines>>;
+    adaptEvents<TTargetVersion extends MachineVersion<TMachines>>(events: readonly unknown[], adaptationOptions: AdaptEventsOptions<TMachines, TTargetVersion>): Promise<EventFrom<MachineForVersion<TMachines, TTargetVersion>>[]>;
     migrateSnapshot<TTargetVersion extends MachineVersion<TMachines>>(raw: unknown, migrationOptions: MigrateSnapshotOptions<TMachines, TTargetVersion>): Promise<PersistedSnapshotFrom<MachineForVersion<TMachines, TTargetVersion>>>;
 };
 export {};

package/dist/xstate.cjs.js

@@ -2004,8 +2004,36 @@ async function finalizeSnapshot(snapshot, target) {
     version: target.version
   };
 }
+async function validateEvents(events, machine) {
+  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 {
+      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}.`);
+    }
+    return {
+      ...validatedPayload,
+      type
+    };
+  }));
+}
 
-/** Creates parsers backed by retained versions of one machine. */
+/** Creates migration and adaptation utilities backed by retained versions of one machine. */
 function machineVersions(machines, options) {
   const byIdentity = new Map();
   const machineId = machines[0].id;
@@ -2076,6 +2104,47 @@ function machineVersions(machines, options) {
   };
   return {
     parseSnapshot,
+    async adaptEvents(events, adaptationOptions) {
+      const target = byIdentity.get(`${machineId}\0${adaptationOptions.to}`);
+      if (!target) {
+        throw new Error(`Target version '${adaptationOptions.to}' is not retained for machine '${machineId}'.`);
+      }
+      const sourceId = adaptationOptions.from.id ?? machineId;
+      const source = byIdentity.get(`${sourceId}\0${adaptationOptions.from.version}`);
+      let sourceError;
+      let sourceValidationFailed = false;
+      if (source) {
+        let sourceEvents;
+        try {
+          sourceEvents = await validateEvents(events, source);
+        } catch (error) {
+          sourceError = error;
+          sourceValidationFailed = true;
+        }
+        if (sourceEvents) {
+          if (source === target) {
+            return sourceEvents;
+          }
+          const adapter = adaptationOptions.adapters[source.version];
+          if (adapter) {
+            return validateEvents(await adapter(sourceEvents), target);
+          }
+        }
+      }
+      const wildcardAdapter = adaptationOptions.adapters['*'];
+      if (wildcardAdapter) {
+        return validateEvents(await wildcardAdapter(events, adaptationOptions.from), target);
+      }
+      if (source) {
+        if (sourceValidationFailed) {
+          throw sourceError instanceof Error ? sourceError : new Error(`Unable to validate event history for machine '${source.id}' version '${source.version}'.`, {
+            cause: sourceError
+          });
+        }
+        throw new Error(`No event adapter from version '${source.version}' to '${target.version}' for machine '${target.id}'.`);
+      }
+      throw new Error(`Unknown event history source '${sourceId}' version '${adaptationOptions.from.version}'.`);
+    },
     async migrateSnapshot(raw, migrationOptions) {
       const target = byIdentity.get(`${machineId}\0${migrationOptions.to}`);
       if (!target) {

package/dist/xstate.development.cjs.js

@@ -2004,8 +2004,36 @@ async function finalizeSnapshot(snapshot, target) {
     version: target.version
   };
 }
+async function validateEvents(events, machine) {
+  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 {
+      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}.`);
+    }
+    return {
+      ...validatedPayload,
+      type
+    };
+  }));
+}
 
-/** Creates parsers backed by retained versions of one machine. */
+/** Creates migration and adaptation utilities backed by retained versions of one machine. */
 function machineVersions(machines, options) {
   const byIdentity = new Map();
   const machineId = machines[0].id;
@@ -2076,6 +2104,47 @@ function machineVersions(machines, options) {
   };
   return {
     parseSnapshot,
+    async adaptEvents(events, adaptationOptions) {
+      const target = byIdentity.get(`${machineId}\0${adaptationOptions.to}`);
+      if (!target) {
+        throw new Error(`Target version '${adaptationOptions.to}' is not retained for machine '${machineId}'.`);
+      }
+      const sourceId = adaptationOptions.from.id ?? machineId;
+      const source = byIdentity.get(`${sourceId}\0${adaptationOptions.from.version}`);
+      let sourceError;
+      let sourceValidationFailed = false;
+      if (source) {
+        let sourceEvents;
+        try {
+          sourceEvents = await validateEvents(events, source);
+        } catch (error) {
+          sourceError = error;
+          sourceValidationFailed = true;
+        }
+        if (sourceEvents) {
+          if (source === target) {
+            return sourceEvents;
+          }
+          const adapter = adaptationOptions.adapters[source.version];
+          if (adapter) {
+            return validateEvents(await adapter(sourceEvents), target);
+          }
+        }
+      }
+      const wildcardAdapter = adaptationOptions.adapters['*'];
+      if (wildcardAdapter) {
+        return validateEvents(await wildcardAdapter(events, adaptationOptions.from), target);
+      }
+      if (source) {
+        if (sourceValidationFailed) {
+          throw sourceError instanceof Error ? sourceError : new Error(`Unable to validate event history for machine '${source.id}' version '${source.version}'.`, {
+            cause: sourceError
+          });
+        }
+        throw new Error(`No event adapter from version '${source.version}' to '${target.version}' for machine '${target.id}'.`);
+      }
+      throw new Error(`Unknown event history source '${sourceId}' version '${adaptationOptions.from.version}'.`);
+    },
     async migrateSnapshot(raw, migrationOptions) {
       const target = byIdentity.get(`${machineId}\0${migrationOptions.to}`);
       if (!target) {

package/dist/xstate.development.esm.js

@@ -2002,8 +2002,36 @@ async function finalizeSnapshot(snapshot, target) {
     version: target.version
   };
 }
+async function validateEvents(events, machine) {
+  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 {
+      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}.`);
+    }
+    return {
+      ...validatedPayload,
+      type
+    };
+  }));
+}
 
-/** Creates parsers backed by retained versions of one machine. */
+/** Creates migration and adaptation utilities backed by retained versions of one machine. */
 function machineVersions(machines, options) {
   const byIdentity = new Map();
   const machineId = machines[0].id;
@@ -2074,6 +2102,47 @@ function machineVersions(machines, options) {
   };
   return {
     parseSnapshot,
+    async adaptEvents(events, adaptationOptions) {
+      const target = byIdentity.get(`${machineId}\0${adaptationOptions.to}`);
+      if (!target) {
+        throw new Error(`Target version '${adaptationOptions.to}' is not retained for machine '${machineId}'.`);
+      }
+      const sourceId = adaptationOptions.from.id ?? machineId;
+      const source = byIdentity.get(`${sourceId}\0${adaptationOptions.from.version}`);
+      let sourceError;
+      let sourceValidationFailed = false;
+      if (source) {
+        let sourceEvents;
+        try {
+          sourceEvents = await validateEvents(events, source);
+        } catch (error) {
+          sourceError = error;
+          sourceValidationFailed = true;
+        }
+        if (sourceEvents) {
+          if (source === target) {
+            return sourceEvents;
+          }
+          const adapter = adaptationOptions.adapters[source.version];
+          if (adapter) {
+            return validateEvents(await adapter(sourceEvents), target);
+          }
+        }
+      }
+      const wildcardAdapter = adaptationOptions.adapters['*'];
+      if (wildcardAdapter) {
+        return validateEvents(await wildcardAdapter(events, adaptationOptions.from), target);
+      }
+      if (source) {
+        if (sourceValidationFailed) {
+          throw sourceError instanceof Error ? sourceError : new Error(`Unable to validate event history for machine '${source.id}' version '${source.version}'.`, {
+            cause: sourceError
+          });
+        }
+        throw new Error(`No event adapter from version '${source.version}' to '${target.version}' for machine '${target.id}'.`);
+      }
+      throw new Error(`Unknown event history source '${sourceId}' version '${adaptationOptions.from.version}'.`);
+    },
     async migrateSnapshot(raw, migrationOptions) {
       const target = byIdentity.get(`${machineId}\0${migrationOptions.to}`);
       if (!target) {

package/dist/xstate.esm.js

@@ -2002,8 +2002,36 @@ async function finalizeSnapshot(snapshot, target) {
     version: target.version
   };
 }
+async function validateEvents(events, machine) {
+  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 {
+      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}.`);
+    }
+    return {
+      ...validatedPayload,
+      type
+    };
+  }));
+}
 
-/** Creates parsers backed by retained versions of one machine. */
+/** Creates migration and adaptation utilities backed by retained versions of one machine. */
 function machineVersions(machines, options) {
   const byIdentity = new Map();
   const machineId = machines[0].id;
@@ -2074,6 +2102,47 @@ function machineVersions(machines, options) {
   };
   return {
     parseSnapshot,
+    async adaptEvents(events, adaptationOptions) {
+      const target = byIdentity.get(`${machineId}\0${adaptationOptions.to}`);
+      if (!target) {
+        throw new Error(`Target version '${adaptationOptions.to}' is not retained for machine '${machineId}'.`);
+      }
+      const sourceId = adaptationOptions.from.id ?? machineId;
+      const source = byIdentity.get(`${sourceId}\0${adaptationOptions.from.version}`);
+      let sourceError;
+      let sourceValidationFailed = false;
+      if (source) {
+        let sourceEvents;
+        try {
+          sourceEvents = await validateEvents(events, source);
+        } catch (error) {
+          sourceError = error;
+          sourceValidationFailed = true;
+        }
+        if (sourceEvents) {
+          if (source === target) {
+            return sourceEvents;
+          }
+          const adapter = adaptationOptions.adapters[source.version];
+          if (adapter) {
+            return validateEvents(await adapter(sourceEvents), target);
+          }
+        }
+      }
+      const wildcardAdapter = adaptationOptions.adapters['*'];
+      if (wildcardAdapter) {
+        return validateEvents(await wildcardAdapter(events, adaptationOptions.from), target);
+      }
+      if (source) {
+        if (sourceValidationFailed) {
+          throw sourceError instanceof Error ? sourceError : new Error(`Unable to validate event history for machine '${source.id}' version '${source.version}'.`, {
+            cause: sourceError
+          });
+        }
+        throw new Error(`No event adapter from version '${source.version}' to '${target.version}' for machine '${target.id}'.`);
+      }
+      throw new Error(`Unknown event history source '${sourceId}' version '${adaptationOptions.from.version}'.`);
+    },
     async migrateSnapshot(raw, migrationOptions) {
       const target = byIdentity.get(`${machineId}\0${migrationOptions.to}`);
       if (!target) {