xstate 6.0.0-alpha.32 → 6.0.0-alpha.33

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, migrateSnapshot, type MachineVersionsOptions, type ParsedPersistedSnapshot, type PersistedMachineIdentity, type PersistedSnapshotDataFrom, type SnapshotMigrationHandlers, type PersistedSnapshotFrom } from "./machineVersions.js";
+export { machineVersions, 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

@@ -26,26 +26,30 @@ export type ParsedPersistedSnapshot<TMachines extends readonly AnyStateMachine[]
 export type MachineVersionsOptions<TMachines extends readonly AnyStateMachine[]> = {
     unversioned?: NonNullable<TMachines[number]['version']>;
 };
-type ParsedSnapshotSource = {
-    machine: VersionedStateMachine;
-    snapshot: Snapshot<unknown> & {
-        context: unknown;
-        machine: PersistedMachineIdentity;
-        [key: string]: unknown;
-    };
-};
-type SourceVersion<TSource extends ParsedSnapshotSource> = TSource extends unknown ? NonNullable<TSource['machine']['version']> : never;
-type SourceForVersion<TSource extends ParsedSnapshotSource, TVersion extends string> = TSource extends unknown ? TSource['machine']['version'] extends TVersion ? TSource : never : never;
-export type SnapshotMigrationHandlers<TSource extends ParsedSnapshotSource, TTarget extends AnyStateMachine> = {
-    [TVersion in SourceVersion<TSource>]?: (snapshot: SourceForVersion<TSource, TVersion>['snapshot']) => PersistedSnapshotDataFrom<TTarget>;
+type MaybePromise<T> = T | PromiseLike<T>;
+type MachineVersion<TMachines extends readonly VersionedStateMachine[]> = TMachines[number]['version'];
+type MachineForVersion<TMachines extends readonly VersionedStateMachine[], TVersion extends string> = {
+    [K in keyof TMachines]: TMachines[K] extends VersionedStateMachine ? TMachines[K]['version'] extends TVersion ? TMachines[K] : never : never;
+}[number];
+export type PersistedSnapshotSource = {
+    id?: string;
+    version?: string;
+};
+export type SnapshotMigrationHandlers<TMachines extends readonly VersionedStateMachine[], TTarget extends VersionedStateMachine> = {
+    [TVersion in Exclude<MachineVersion<TMachines>, TTarget['version']>]?: (snapshot: PersistedSnapshotFrom<MachineForVersion<TMachines, TVersion>>) => MaybePromise<PersistedSnapshotDataFrom<TTarget>>;
+} & {
+    '*'?: (snapshot: unknown, source: PersistedSnapshotSource) => MaybePromise<PersistedSnapshotDataFrom<TTarget>>;
+};
+export type MigrateSnapshotOptions<TMachines extends readonly VersionedStateMachine[], TTargetVersion extends MachineVersion<TMachines>> = {
+    to: TTargetVersion;
+    migrations: SnapshotMigrationHandlers<TMachines, MachineForVersion<TMachines, TTargetVersion>>;
 };
 /** Creates parsers 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>>;
+    parseSnapshot: (raw: unknown) => Promise<ParsedPersistedSnapshot<TMachines>>;
+    migrateSnapshot<TTargetVersion extends MachineVersion<TMachines>>(raw: unknown, migrationOptions: MigrateSnapshotOptions<TMachines, TTargetVersion>): Promise<PersistedSnapshotFrom<MachineForVersion<TMachines, TTargetVersion>>>;
 };
-/** Migrates a parsed persisted snapshot directly to a target machine. */
-export declare function migrateSnapshot<TSource extends ParsedSnapshotSource, TTarget extends VersionedStateMachine>(source: TSource, target: TTarget, migrations: SnapshotMigrationHandlers<TSource, TTarget>): Promise<PersistedSnapshotFrom<TTarget>>;
 export {};

package/dist/xstate.cjs.js

@@ -1970,6 +1970,21 @@ function mapState(snapshot, mapper) {
 function isObject(value) {
   return value !== null && typeof value === 'object';
 }
+function getSnapshotSource(raw, defaultId) {
+  if (!isObject(raw)) {
+    return {};
+  }
+  if (isObject(raw.machine)) {
+    return {
+      id: typeof raw.machine.id === 'string' ? raw.machine.id : undefined,
+      version: typeof raw.machine.version === 'string' ? raw.machine.version : undefined
+    };
+  }
+  return {
+    id: typeof raw.version === 'string' ? defaultId : undefined,
+    version: typeof raw.version === 'string' ? raw.version : undefined
+  };
+}
 async function validate(schema, value, description) {
   if (!schema) {
     return value;
@@ -1980,6 +1995,18 @@ 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 {
+    ...snapshot,
+    context,
+    machine: {
+      id: target.id,
+      version: target.version
+    },
+    version: target.version
+  };
+}
 
 /** Creates parsers backed by retained versions of one machine. */
 function machineVersions(machines, options) {
@@ -1989,6 +2016,9 @@ function machineVersions(machines, options) {
     if (machine.version === undefined) {
       throw new Error(`Machine '${machine.id}' must define a version.`);
     }
+    if (machine.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}'.`);
     }
@@ -2001,83 +2031,85 @@ function machineVersions(machines, options) {
   if (options?.unversioned !== undefined && !byIdentity.has(`${machineId}\0${options.unversioned}`)) {
     throw new Error(`Unversioned snapshot version '${options.unversioned}' is not retained for machine '${machineId}'.`);
   }
-  return {
-    async parseSnapshot(raw) {
-      if (!isObject(raw)) {
-        throw new Error('Persisted snapshot is missing machine identity.');
-      }
-      let id;
-      let version;
-      if (isObject(raw.machine)) {
-        ({
+  const parseSnapshot = async raw => {
+    if (!isObject(raw)) {
+      throw new Error('Persisted snapshot is missing machine identity.');
+    }
+    let id;
+    let version;
+    if (isObject(raw.machine)) {
+      ({
+        id,
+        version
+      } = raw.machine);
+      if (typeof id !== 'string' || typeof version !== 'string') {
+        throw new Error('Persisted snapshot has an invalid machine identity.');
+      }
+    } else if (typeof raw.version === 'string') {
+      id = machineId;
+      version = raw.version;
+    } else if (raw.version === undefined && options?.unversioned !== undefined) {
+      id = machineId;
+      version = options.unversioned;
+    } else {
+      throw new Error('Persisted snapshot is missing machine identity.');
+    }
+    if (raw.version !== undefined && typeof raw.version !== 'string') {
+      throw new Error('Persisted snapshot has an invalid version.');
+    }
+    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) {
+      throw new Error(`Unknown machine identity '${id}' version '${version}'.`);
+    }
+    const context = await validate(machine.schemas?.context, raw.context, `context for machine '${id}' version '${version}'`);
+    return {
+      machine,
+      snapshot: {
+        ...raw,
+        context,
+        machine: {
           id,
           version
-        } = raw.machine);
-        if (typeof id !== 'string' || typeof version !== 'string') {
-          throw new Error('Persisted snapshot has an invalid machine identity.');
         }
-      } else if (typeof raw.version === 'string') {
-        id = machineId;
-        version = raw.version;
-      } else if (raw.version === undefined && options?.unversioned !== undefined) {
-        id = machineId;
-        version = options.unversioned;
-      } else {
-        throw new Error('Persisted snapshot is missing machine identity.');
       }
-      if (raw.version !== undefined && typeof raw.version !== 'string') {
-        throw new Error('Persisted snapshot has an invalid version.');
+    };
+  };
+  return {
+    parseSnapshot,
+    async migrateSnapshot(raw, migrationOptions) {
+      const target = byIdentity.get(`${machineId}\0${migrationOptions.to}`);
+      if (!target) {
+        throw new Error(`Target version '${migrationOptions.to}' is not retained for machine '${machineId}'.`);
       }
-      if (raw.version !== undefined && raw.version !== version) {
-        throw new Error(`Persisted snapshot version '${raw.version}' conflicts with machine version '${version}'.`);
+      let source;
+      let parseError;
+      try {
+        source = await parseSnapshot(raw);
+      } catch (error) {
+        parseError = error;
       }
-      const machine = byIdentity.get(`${id}\0${version}`);
-      if (!machine) {
-        throw new Error(`Unknown machine identity '${id}' version '${version}'.`);
+      if (source) {
+        if (source.machine.version === target.version) {
+          return finalizeSnapshot(source.snapshot, target);
+        }
+        const exactMigration = migrationOptions.migrations[source.machine.version];
+        if (exactMigration) {
+          return finalizeSnapshot(await exactMigration(source.snapshot), target);
+        }
       }
-      const context = await validate(machine.schemas?.context, raw.context, `context for machine '${id}' version '${version}'`);
-      return {
-        machine,
-        snapshot: {
-          ...raw,
-          context,
-          machine: {
-            id,
-            version
-          }
+      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}'.`);
         }
-      };
-    }
-  };
-}
-
-/** Migrates a parsed persisted snapshot directly to a target machine. */
-async function migrateSnapshot(source, target, migrations) {
-  if (target.version === undefined) {
-    throw new Error(`Target machine '${target.id}' must define a version.`);
-  }
-  if (source.machine.id !== target.id) {
-    throw new Error(`Cannot migrate machine '${source.machine.id}' to '${target.id}'.`);
-  }
-  let snapshot;
-  if (source.machine.version === target.version) {
-    snapshot = source.snapshot;
-  } else {
-    const migrate = migrations[source.machine.version];
-    if (!migrate) {
-      throw new Error(`No snapshot migration from version '${source.machine.version}' to '${target.version}' for machine '${target.id}'.`);
+        throw parseError;
+      }
+      const snapshot = await wildcardMigration(raw, getSnapshotSource(raw, machineId));
+      return finalizeSnapshot(snapshot, target);
     }
-    snapshot = migrate(source.snapshot);
-  }
-  const context = await validate(target.schemas?.context, snapshot.context, `context for machine '${target.id}' version '${target.version}'`);
-  return {
-    ...snapshot,
-    context,
-    machine: {
-      id: target.id,
-      version: target.version
-    },
-    version: target.version
   };
 }
 
@@ -2881,7 +2913,6 @@ exports.isTypeSchema = isTypeSchema;
 exports.machineConfigToJSON = machineConfigToJSON;
 exports.machineVersions = machineVersions;
 exports.mapState = mapState;
-exports.migrateSnapshot = migrateSnapshot;
 exports.serializeMachine = serializeMachine;
 exports.setup = setup;
 exports.toPromise = toPromise;

package/dist/xstate.cjs.mjs

@@ -38,7 +38,6 @@ export {
   machineVersions,
   mapState,
   matchesState,
-  migrateSnapshot,
   pathToStateValue,
   serializeMachine,
   setup,

package/dist/xstate.development.cjs.js

@@ -1970,6 +1970,21 @@ function mapState(snapshot, mapper) {
 function isObject(value) {
   return value !== null && typeof value === 'object';
 }
+function getSnapshotSource(raw, defaultId) {
+  if (!isObject(raw)) {
+    return {};
+  }
+  if (isObject(raw.machine)) {
+    return {
+      id: typeof raw.machine.id === 'string' ? raw.machine.id : undefined,
+      version: typeof raw.machine.version === 'string' ? raw.machine.version : undefined
+    };
+  }
+  return {
+    id: typeof raw.version === 'string' ? defaultId : undefined,
+    version: typeof raw.version === 'string' ? raw.version : undefined
+  };
+}
 async function validate(schema, value, description) {
   if (!schema) {
     return value;
@@ -1980,6 +1995,18 @@ 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 {
+    ...snapshot,
+    context,
+    machine: {
+      id: target.id,
+      version: target.version
+    },
+    version: target.version
+  };
+}
 
 /** Creates parsers backed by retained versions of one machine. */
 function machineVersions(machines, options) {
@@ -1989,6 +2016,9 @@ function machineVersions(machines, options) {
     if (machine.version === undefined) {
       throw new Error(`Machine '${machine.id}' must define a version.`);
     }
+    if (machine.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}'.`);
     }
@@ -2001,83 +2031,85 @@ function machineVersions(machines, options) {
   if (options?.unversioned !== undefined && !byIdentity.has(`${machineId}\0${options.unversioned}`)) {
     throw new Error(`Unversioned snapshot version '${options.unversioned}' is not retained for machine '${machineId}'.`);
   }
-  return {
-    async parseSnapshot(raw) {
-      if (!isObject(raw)) {
-        throw new Error('Persisted snapshot is missing machine identity.');
-      }
-      let id;
-      let version;
-      if (isObject(raw.machine)) {
-        ({
+  const parseSnapshot = async raw => {
+    if (!isObject(raw)) {
+      throw new Error('Persisted snapshot is missing machine identity.');
+    }
+    let id;
+    let version;
+    if (isObject(raw.machine)) {
+      ({
+        id,
+        version
+      } = raw.machine);
+      if (typeof id !== 'string' || typeof version !== 'string') {
+        throw new Error('Persisted snapshot has an invalid machine identity.');
+      }
+    } else if (typeof raw.version === 'string') {
+      id = machineId;
+      version = raw.version;
+    } else if (raw.version === undefined && options?.unversioned !== undefined) {
+      id = machineId;
+      version = options.unversioned;
+    } else {
+      throw new Error('Persisted snapshot is missing machine identity.');
+    }
+    if (raw.version !== undefined && typeof raw.version !== 'string') {
+      throw new Error('Persisted snapshot has an invalid version.');
+    }
+    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) {
+      throw new Error(`Unknown machine identity '${id}' version '${version}'.`);
+    }
+    const context = await validate(machine.schemas?.context, raw.context, `context for machine '${id}' version '${version}'`);
+    return {
+      machine,
+      snapshot: {
+        ...raw,
+        context,
+        machine: {
           id,
           version
-        } = raw.machine);
-        if (typeof id !== 'string' || typeof version !== 'string') {
-          throw new Error('Persisted snapshot has an invalid machine identity.');
         }
-      } else if (typeof raw.version === 'string') {
-        id = machineId;
-        version = raw.version;
-      } else if (raw.version === undefined && options?.unversioned !== undefined) {
-        id = machineId;
-        version = options.unversioned;
-      } else {
-        throw new Error('Persisted snapshot is missing machine identity.');
       }
-      if (raw.version !== undefined && typeof raw.version !== 'string') {
-        throw new Error('Persisted snapshot has an invalid version.');
+    };
+  };
+  return {
+    parseSnapshot,
+    async migrateSnapshot(raw, migrationOptions) {
+      const target = byIdentity.get(`${machineId}\0${migrationOptions.to}`);
+      if (!target) {
+        throw new Error(`Target version '${migrationOptions.to}' is not retained for machine '${machineId}'.`);
       }
-      if (raw.version !== undefined && raw.version !== version) {
-        throw new Error(`Persisted snapshot version '${raw.version}' conflicts with machine version '${version}'.`);
+      let source;
+      let parseError;
+      try {
+        source = await parseSnapshot(raw);
+      } catch (error) {
+        parseError = error;
       }
-      const machine = byIdentity.get(`${id}\0${version}`);
-      if (!machine) {
-        throw new Error(`Unknown machine identity '${id}' version '${version}'.`);
+      if (source) {
+        if (source.machine.version === target.version) {
+          return finalizeSnapshot(source.snapshot, target);
+        }
+        const exactMigration = migrationOptions.migrations[source.machine.version];
+        if (exactMigration) {
+          return finalizeSnapshot(await exactMigration(source.snapshot), target);
+        }
       }
-      const context = await validate(machine.schemas?.context, raw.context, `context for machine '${id}' version '${version}'`);
-      return {
-        machine,
-        snapshot: {
-          ...raw,
-          context,
-          machine: {
-            id,
-            version
-          }
+      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}'.`);
         }
-      };
-    }
-  };
-}
-
-/** Migrates a parsed persisted snapshot directly to a target machine. */
-async function migrateSnapshot(source, target, migrations) {
-  if (target.version === undefined) {
-    throw new Error(`Target machine '${target.id}' must define a version.`);
-  }
-  if (source.machine.id !== target.id) {
-    throw new Error(`Cannot migrate machine '${source.machine.id}' to '${target.id}'.`);
-  }
-  let snapshot;
-  if (source.machine.version === target.version) {
-    snapshot = source.snapshot;
-  } else {
-    const migrate = migrations[source.machine.version];
-    if (!migrate) {
-      throw new Error(`No snapshot migration from version '${source.machine.version}' to '${target.version}' for machine '${target.id}'.`);
+        throw parseError;
+      }
+      const snapshot = await wildcardMigration(raw, getSnapshotSource(raw, machineId));
+      return finalizeSnapshot(snapshot, target);
     }
-    snapshot = migrate(source.snapshot);
-  }
-  const context = await validate(target.schemas?.context, snapshot.context, `context for machine '${target.id}' version '${target.version}'`);
-  return {
-    ...snapshot,
-    context,
-    machine: {
-      id: target.id,
-      version: target.version
-    },
-    version: target.version
   };
 }
 
@@ -2884,7 +2916,6 @@ exports.isTypeSchema = isTypeSchema;
 exports.machineConfigToJSON = machineConfigToJSON;
 exports.machineVersions = machineVersions;
 exports.mapState = mapState;
-exports.migrateSnapshot = migrateSnapshot;
 exports.serializeMachine = serializeMachine;
 exports.setup = setup;
 exports.toPromise = toPromise;

package/dist/xstate.development.cjs.mjs

@@ -38,7 +38,6 @@ export {
   machineVersions,
   mapState,
   matchesState,
-  migrateSnapshot,
   pathToStateValue,
   serializeMachine,
   setup,