Machine version migrations

Machine version migration operations.

Machine version migrations are small snippets of code that migrate existing machine instances from one machine version to another. They consist of a single self-contained javascript file that exports upgradeState and upgradeContext functions.

Example machine version migration

import type {
  UpgradeState,
  UpgradeContext,
} from "@statebacked/machine-def";

export const upgradeState: UpgradeState = (oldState, oldContext) => {
  // oldState is an array describing a full path to a state in the old version of the machine
  // (e.g. ["authenticationPage", "login"] if login is a child state of authenticationPage).
  // oldContext is the most recent context of the machine. It *may not* be a valid context in
  // the given state because upgradeState will be called to migrate history states in
  // addition to current states.

  // a simple renaming of a parent state from "authenticationPage" to "newAuthenticationPage".
  return oldState[0] === "authenticationPage" ? ["newAuthenticationPage"].concat(oldState.slice(1)) : oldState;
};

export const upgradeContext: UpgradeContext = (oldStates, newStates, oldContext) => {
  // oldStates is an array of state paths from the old version of the machine.
  // (e.g. [["a", "b"], ["a", "c"]] if "a" is a parallel state and is in both "b" and "c").
  // newStates is an array of state paths from the new version of the machine.
  // oldContext is the context associated with oldStates in the old version of the machine.

  return {
    ...oldContext,
    upgradeCount: oldContext.upgradeCount + 1
  };
};