:warning: Attention: Documentation about v1.x.x is here :warning:

vue-xstate v2

This project aims to give users of VueJS a easy access platform to use xState library in their project.

If you're not familiar with xState check first their site before using this!

Why no longer a mixin?

In this version I've moved away from the mixin structure for three reasons:

1. It adds a lot of overhead
2. It's being considered a bad practice as it does merge properties in runtime and you can accidentally overlap them without warning.
3. In mixin form the instance of the machine was mandatory to be linked to the component, having to make use of strange subscriptions to share it through

With the new approach of a class it can be explicitly initialized, doesn't overwrite any property and it can be instantiated anywhere and shared through props/imports. This also adds an extra benefit, this class can now be used in other projects that don't use vue.

Migration from v1

To migrate your components from v1, you need to remove the mixin from it and the initialization of the machine from your created() hook. To simplify a bit your work, you can add this piece of code in your component to have a map of your data to the new machine.

Note that the subscription system has now been removed as now being a class you can initiate, it can be passed as a property and shared the instance through multiple components.

You will have to replace the types with the ones on your state machine

1public machine: StateMachine<TContext, TStateSchema, TEvents> = new StateMachine(initialContext, machineConfig);
2
3public get context(): TContext {
4  return this.machine.context;
5}
6
7public get currentState(): StateMachineStateName<TStateSchema> {
8  return this.machine.state;
9}
10
11public get stateHash(): StateMachineStateName<TStateSchema> {
12  return this.machine.stateHash;
13}
14
15public dispatch(action: TEvents): void {
16  this.machine.dispatch(action);
17}

Usage

Install

yarn add vue-xstate

or

npm i vue-xstate

:warning: Remember, since version 2.1.0, xstate is a peer dependency and you will have to install it in your project to use with this library.

Create your state machine

Using the documentation of XState, define your context, states, events and state machine. For this case you will only define the objects, you don't need to use any of the methods indicated in that documentation as the mixin takes care of all internally.

I do recommend to keep the types and the machine in a separated file to make it easier to read and maintain. I also recommend to follow the nomenclature pattern. In the future I will try to add a small scaffolding tool to use with npm to generate the base files and types.

Here is an example state machine file:

1/// traffic-light.machine.ts
2
3import { MachineConfig, StateNodeConfig } from 'xstate';
4import { assign } from 'xstate/lib/actions';
5
6// State machine context interface
7export interface TrafficLightContext {
8  carCount: number;
9  finedPlates: string[];
10}
11
12// Initial context used in the xStateInit() method
13export const TrafficLigtInitialContext: TrafficLightContext = {
14  carCount: 0,
15  finedPlates: [],
16};
17
18// Possible states of the machine
19export enum TrafficLightStates {
20  RED = 'RED',
21  AMBER = 'AMBER',
22  GREEN = 'GREEN',
23}
24
25// Possible actions of the whole machine
26export enum TrafficLightActions {
27  GO_GREEN = 'GO_GREEN',
28  GO_AMBER = 'GO_AMBER',
29  GO_RED = 'GO_RED',
30  COUNT_CAR = 'COUNT_CAR',
31  FINE_CAR = 'FINE_CAR',
32}
33
34// Utility interface to get proper types on our config
35export interface TrafficLightSchema {
36  states: {
37    [state in TrafficLightStates]: StateNodeConfig<TrafficLightContext, TrafficLightSchema, TrafficLightEvent>;
38  };
39}
40
41// Events that will be sent on the dispatch with their payload definition
42export type TrafficLightEvent =
43  | { type: TrafficLightActions.GO_GREEN }
44  | { type: TrafficLightActions.GO_AMBER }
45  | { type: TrafficLightActions.GO_RED }
46  | { type: TrafficLightActions.COUNT_CAR }
47  | { type: TrafficLightActions.FINE_CAR; plate: string };
48
49// Definition of the state machine
50export const TrafficLightMachineConfig: MachineConfig<TrafficLightContext, TrafficLightSchema, TrafficLightEvent> = {
51  initial: TrafficLightStates.RED,
52  states: {
53    [TrafficLightStates.RED]: {
54      on: {
55        [TrafficLightActions.GO_GREEN]: {
56          target: TrafficLightStates.GREEN,
57        },
58        [TrafficLightActions.FINE_CAR]: {
59          actions: assign((ctx, event) => ({
60            finedPlates: [...ctx.finedPlates, event.plate],
61          })),
62        },
63      },
64    },
65    [TrafficLightStates.AMBER]: {
66      on: {
67        [TrafficLightActions.GO_RED]: {
68          target: TrafficLightStates.RED,
69        },
70      },
71    },
72    [TrafficLightStates.GREEN]: {
73      on: {
74        [TrafficLightActions.GO_AMBER]: {
75          target: TrafficLightStates.AMBER,
76        },
77        [TrafficLightActions.COUNT_CAR]: {
78          actions: assign((ctx, event) => ({
79            carCount: ctx.carCount + 1,
80          })),
81        },
82      },
83    },
84  },
85};

Remember that in the machine configuration you can use any functionality provided by xState

Initiate the machine in your component

Once you have your class component created do the following:

1import { Component, Vue } from 'vue-property-decorator';
2import { StateMachine } from 'vue-xstate';
3import {
4  TrafficLightContext,
5  TrafficLightStateSchema,
6  TrafficLightEvents,
7  TrafficLigtInitialContext,
8  TrafficLightMachineConfig,
9} from './TrafficLight.machine.ts';
10
11@Component
12class TrafficLight extends Vue {
13  // Your class definition
14  readonly machine: StateMachine<TrafficLightContext, TrafficLightStateSchema, TrafficLightEvents> = new StateMachine(
15    TrafficLigtInitialContext,
16    TrafficLightMachineConfig,
17  );
18}

This will create and initiate the state machine with the defined initial state. Then you can use the StateMachine properties and methods to render and operate your machine. All the properties are reactive in the normal vue flow, which allows you to use them directly in your template/methods.

Documentation

StateMachine class

Now that you have machine initialized, you will have access to the following data, methods and props:

Data

All the properties listed here are getter to prevent you to accidentally modify them. In any case you should always observe the principle of immutability when designing your states.

Name	Type	Description
context	TContext	Contain the context of the state machine, it will change as you move through the actions
state	string	Current state name based on your StateSchema definition
stateHash	string	State hash will provide a unique UUID every time there's a state change in the state machine

Methods

constructor()

The constructor method initialize the state machine.

1new StateMachine(
2    initialContext: TContext,
3    machineConfig: MachineConfig<TContext, TStateSchema, TEvents>,
4    configOptions?: Partial<MachineOptions<TContext, TEvents>>
5)

Method params

Name	Type	Optional	Description
initialContext	TContext	false	Initial context that will be accessible through context data
machineConfig	MachineConfig<TContext, TStateSchema, TEvents>	false	xState machine configuration here
configOptions	Partial<MachineOptions<TContext, TEvents>	true	xState machine options here

dispatch()

This method allows to dispatch events to the state machine

1dispatch(action: TEvents): void

Method params

Name	Type	Description
action	TEvents	Action object with its payload

Changelog

2.1.8

• Dependencies update for security reasons

2.1.7

• Removed parcel from dev dependencies

2.1.6

• Bump packages for a security issue with node-forge

2.1.5

• Bump packages for security issues

2.1.4

• Bump elliptic dependency from 6.5.2 to 6.5.3 for a security issue

2.1.3

• Security internal dependency lodash
• Realizing I suck on handling versions

2.1.2

• Removed js maps from build to thin the package

2.1.1

• Updated documentation

2.1.0

• Removed unnecessary dependecies
• Turned xstate to a peer dependency

For forkers

yarn install

Compiles and minifies to /lib

yarn run build

Run unit tests

yarn run test

Lints and fixes files

yarn run lint

Licence

MIT License