# 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

```js
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
  };
};
```



## Operations
- [Provisionally create a new machine version migration.](https://api-docs.statebacked.dev/operation/operation-post-machines-parameter-migrations.md)
- [Finalize creation of a machine version migration.](https://api-docs.statebacked.dev/operation/operation-put-machines-parameter-migrations-parameter.md)

[Powered by Bump.sh](https://bump.sh)