interpret function

The interpret function creates an instance of an interpreted machine, also known as a service. This is a stateful representation of the running machine, which you can subscribe to, send events to, start, and stop.

The interpret function takes three arguments:

1. machine created with the createMachine function (required)
2. an object of getter functions (optional)
3. a persistence string, object or custom class (optional)

import { createMachine, interpret } from 'https://cdn.skypack.dev/ficusjs@6/xstate-service'

const definition = {
  /* define the machine definition */
}

const options = {
  /* define options like actions, guards etc */
}

// create the state machine
const machine = createMachine(definition, options)

// interpret the state machine to create a service
const service = interpret(machine)

A created service can then be passed to as many components as required using the withXStateService function.

Getters

Getters are useful if you want to return a projection of the extended state (the state machine context is the extended state). A projection is a shape derived from the state.

Getters are memoized functions which means the result of the getter is cached for subsequent executions. This is useful when creating projections from large sets of data. State changes will automatically reset the getter cache.

To provide getters for creating projections, create an object containing functions and pass it to the interpret function.

const getters = {
  isGlassFull (context) {
    return context.amount >= 10
  },
  remaining (context) {
    return 10 - context.amount
  }
}

// interpret the state machine to create a service
const service = interpret(machine, getters)

The interpret function extends the one provided by the @xstate/fsm package. The decorated function extends to provide the getters feature.

Persistence

To survive hard refreshes from the user, your state can be persisted to sessionStorage automatically.
This will re-hydrate your state machine on initialisation.

Passing a string as the persistence argument provides a namespace for persisting the state.

const service = interpret(machine, getters, 'food')

createPersist function

You can optionally save state to window.localStorage (for persistence across browser sessions) using the createPersist function:

import { createPersist } from 'https://cdn.skypack.dev/ficusjs@6'

const service = interpret(machine, getters, createPersist('food', 'local'))

When using the createPersist function, the following arguments must be supplied:

Options

Options can be provided when creating persistence.

import { createPersist } from 'https://cdn.skypack.dev/ficusjs@6'

const service = interpret(machine, getters, createPersist('food', 'local', {
  clearOnReload: true,
  saveState (state) {
    return {
      // only save the state value
      value: state.value
    }
  }
}))

options.clearOnReload

Setting options.clearOnReload to true will detect the browser reload state using
the window.performance API and clear the persistence
if a reload type is detected.

createPersist('food', 'local', {
  clearOnReload: true
})

options.saveState

Setting options.saveState provides a way to persist specific data different to that of the store state.
This is useful when the store state contains functions or other data that cannot be serialised into a string when saved
to window.sessionStorage or window.localStorage.

createPersist('food', 'local', {
  saveState (state) {
    return {
      // return properties of state to persist
    }
  }
})

The saveState function is passed the current state and must return an object of data to be serialised into a string.

Custom persistence

You can provide a custom class and persist your application state in whichever way you choose.

Four methods must be implemented:

class MyCustomPersist {
  setState (state) {
    // set the state
  }

  getState () {
    // get the state
  }

  lastUpdated () {
    // get the last updated time in milliseconds since the Unix Epoch
  }

  removeState () {
    // remove the state - this is called by default when setState is null
  }
}

const service = interpret(machine, getters, new MyCustomPersist())