Investigate standardized XState integration

[mweststrate]

This is a subject I want to research soon, so any upfront ideas, inputs, examples are welcome!

cc @RainerAtSpirit @mattruby @davidkpiano

[davidkpiano]

I have to look deeper into MST. Any state management solution is fully compatible with XState and assign() as long as an immutable object is returned. At a cursory glance, I'm not sure that MST is "immutable" by default (I could be wrong), and instead it wants to "own" the state and state changes, which might be in conflict with XState.

The reason XState prefers immutable data structures for context is because it needs to control when context changes occur, and it needs to maintain history (just like Redux). Also, it's preferred change mechanism is property based (like React's setState) because it allows analysis into how certain properties will change, and when they will change, instead of blindly assuming that assign() will change the entire context object.

By the way, I've been using immer heavily with XState. It works extremely well:

foo: {
  on: {
    SOME_EVENT: {
      actions: assign((ctx, e) => produce(ctx, draft => draft.count += e.value))
    }
  }
}

So if MST works similarly, it can fit well.

[mattruby]

MST is great at serializing and deserializing it's current state. I've created a few state machines using MST with a few enums. My first thought was a way to have MST own the actions and context. And xstate own what is called when. But things get interesting when I get into who initializes what when. It would also potentially useful to have an observable flavor of State. It would be neat to have an observable nextEvents and such.

I'm still having a hard time deciding how best to weave the tools together.

[RainerAtSpirit]

Here's an pretty rough POC of mst and xstate integration. https://github.com/RainerAtSpirit/xstatemst.
Like @mattruby I'm having a hard time to decicde, who should be responsible for what. If we e.g. want to use mobx-react observer to react to both context and state changes than we would need to have e.g. State.value and State.nextEvents observables. There're probably more though.

[mattruby]

At one point, I was thinking of creating an MST model that would match xstate's data model. So I would model my State in MST. But I think I'd end up having to create a whole machine interpreter.

[RainerAtSpirit]

I'd rather like using the xstate interpreter for that job.
What about having an XStateAble model that we can add as volatile prop to any other model?

.volatile(self => ({
    xstate: createXStateAble(machineDefinition, {
      actions: {
        fetchData: self.fetchData,
        updateData: self.updateData,
        showErrorMessage: self.showErrorMessage
      }
    })
  }))

xstateable would have the minimum amount of props that a) the UI require and b) are needed to rehydrate the combination at any point in time. Something along the line.

// createXStateAble .ts
import { Instance, types } from "mobx-state-tree"
import { Machine } from "xstate"
import { interpret } from "xstate/lib/interpreter"

export const createXStateAble = (machineDefinition: any, config: any) => {
  const machine = Machine(machineDefinition, config)

  const XStateable = types
    .model("XStateable", {
      machineDefinition: types.frozen(),
      value: types.optional(types.string, ""),
      nextEvents: types.array(types.string)
    })
    .volatile((self: any) => ({
      machine
    }))
    .volatile((self: any) => ({
      service: interpret(self.machine).onTransition(state => {
        self.setValue(state.value)
        self.setNextEvents(state.nextEvents)
      })
    }))
    .actions((self: any) => ({
      setValue(value: string) {
        self.value = value
      },
      setNextEvents(nextEvents: any) {
        self.nextEvents = nextEvents
      },
      afterCreate() {
        self.value = self.machine.initialState.value
        self.service.start()
      }
    }))

  const xstate = ((window as any).xstate = XStateable.create({
    machineDefinition
  }))

  return xstate
}

I've updated https://github.com/RainerAtSpirit/xstatemst. accordingly.

[RainerAtSpirit]

Now that async recipes has landed in immer 2.0 immerjs/immer@5fee518, immer looks like a better companion for xstate to me. As @davidkpiano outlined is plays nicely with assign and it's only purpose would be to produce a new ctx.
I still need to find some time to verify that assumption ;).

[davidkpiano]

Here is how nicely Immer (1.x) plays with XState. It's beautiful:

[RainerAtSpirit]

Immer meets xstate, here's my first pick: https://github.com/RainerAtSpirit/xstatemst/tree/immer.
This will work with immer 1 as well as it's not making usuage of immer 2 async feature.
As an alternative to @davidkpiano design pattern above, this is using an external updateContext action.

export const machine = Machine<
  IPromiseMachineContext,
  IPromiseMachineSchema,
  PromiseMachineEvents
>(machineConfig, {
  actions: {
    fetchData: async function fetchData(ctx, event) {
      const success = Math.random() < 0.5

      await delay(2000)
      if (success) {
        // service is a singleton that will be started/stopped within <App>
        service.send({
          type: "FULFILL",
          data: ["foo", "bar", "baz"]
        })
      } else {
        service.send({ type: "REJECT", message: "No luck today" })
      }
    },
    updateContext: assign((ctx, event) =>
      produce(ctx, draft => {
        switch (event.type) {
          case "FULFILL":
            draft.data = event.data
            draft.message = ""
            break
          case "REJECT":
            draft.message = event.message
            break
        }
      })
    )
  }
})

export const service = interpret(machine)

[mweststrate]

Have been working with a MST-xstate integration last week, first results look very promising! Stay tuned :)

[lu-zen]

Pls integrate mobx too 🙏

[aksonov]

@mweststrate Is there any progress about XState integration?

[mweststrate]

Recently, used the following utility successfully in a project:

import { types } from 'mobx-state-tree'
import { isObject } from 'util'
import { State } from 'xstate'
import { interpret } from 'xstate/lib/interpreter'

export function createXStateStore(machineInitializer) {
  return types
    .model('XStateStore', {
      value: types.optional(types.frozen(), undefined), // contains the .value of the current state
    })
    .volatile(() => ({
      currentState: null, // by making this part of the volatile state, the ref will be observable. Alternatively it could be put in an observable.box in the extend closure.
    }))
    .extend((self) => {
      function setState(state) {
        self.currentState = state

        if (isObject(state.value)) {
          self.value = state.value
        } else {
          self.value = { [state.value]: {} }
        }
      }

      let machine
      let interpreter

      return {
        views: {
          get machine() {
            return machine
          },
          get rootState() {
            return self.currentState.toStrings()[0] // The first one captures the top level step
          },
          get stepState() {
            const stateStrings = self.currentState.toStrings()
            const mostSpecific = stateStrings[stateStrings.length - 1] // The last one is the most specific state
            return mostSpecific.substr(this.rootState.length + 1) // cut of the top level name
          },
          matches(stateString = '') {
            return self.currentState.matches(stateString)
          },
        },
        actions: {
          sendEvent(event) {
            interpreter.send(event)
          },
          afterCreate() {
            machine = machineInitializer(self)
            interpreter = interpret(machine).onTransition(setState)
            // *if* there is some initial value provided, construct a state from that and start with it
            const state = self.value ? State.from(self.value) : undefined
            interpreter.start(state)
          },
        },
      }
    })
}

It worked great (feel free to create a lib out of it). For example with the following (partial) machine definition:

import { address, payment, confirmation } from './states'

export const CheckoutMachineDefinition = {
  id: 'checkout',
  initial: 'address',
  context: {
    address: {
      complete: false,
    },
    payment: {
      complete: false,
    },
  },
  meta: {
    order: [
      {
        name: 'address',
        title: 'Shipping',
        continueButtonTitle: 'Continue To Payment',
        event: 'CHANGE_TO_ADDRESS',
      },
      {
        name: 'payment',
        title: 'Payment',
        continueButtonTitle: 'Continue To Review Order',
        event: 'CHANGE_TO_PAYMENT',
      },
      {
        name: 'confirmation',
        title: 'Review',
        continueButtonTitle: 'Place Order',
        event: 'CHANGE_TO_CONFIRMATION',
      },
    ],
  },
  states: {
    address,
    payment,
    confirmation,
  },
  on: {
    CHANGE_TO_ADDRESS: '#checkout.address.review',
    CHANGE_TO_PAYMENT: '#payment',
    CHANGE_TO_CONFIRMATION: '#confirmation',
  },
}

It can be tested / used like this:

import { Machine } from 'xstate'
import { autorun } from 'mobx'
import { createXStateStore } from './index'
import { CheckoutMachineDefinition } from '../checkoutmachine'

describe('XStateStore', () => {
  const testable = createXStateStore(() =>
    Machine(CheckoutMachineDefinition, {
      guards: {
        validate: () => true,
      },
    }),
  )

  it('creates a default XStateStore', () => {
    const test = testable.create({
      machineDefinition: CheckoutMachineDefinition,
    })
    expect(test.toJSON()).toMatchSnapshot()
  })
  it('updates the value with a string', () => {
    const test = testable.create({ value: 'address' })
    expect(test.value).toEqual({ address: 'shipping' })
  })
  it.skip('updates the value with an empty object string', () => {
    const test = testable.create({ value: { address: '' } })
    expect(test.value).toEqual({ address: {} })
  })
  it('updates the value with an object', () => {
    const test = testable.create({
      value: {
        address: {
          shipping: {},
        },
      },
    })
    expect(test.value).toEqual({
      address: {
        shipping: {},
      },
    })
  })
  describe('stepState - ', () => {
    it('one level', () => {
      const test = testable.create({ value: 'payment' })
      expect(test.value).toMatchInlineSnapshot(`
                Object {
                  "payment": Object {},
                }
            `)
      expect(test.matches('payment')).toBeTruthy()
    })
    it('two levels', () => {
      const test = testable.create({
        value: { address: 'shipping' },
      })
      expect(test.stepState).toBe('shipping')
      expect(test.matches('address')).toBeTruthy()
      expect(test.matches('address.shipping')).toBeTruthy()
    })
    it('three levels', () => {
      const test = testable.create({
        value: { billingAddress: { test1: { test2: {} } } },
      })
      expect(test.stepState).toBe('test1.test2')
    })
  })
  describe('matches - ', () => {
    it('undefined argument', () => {
      try {
        const test = testable.create({ value: { address: { review: { editBilling: 'billing' } } } })
      } catch (e) {
        expect(e).toMatchInlineSnapshot(`[Error: Child state 'review' does not exist on 'address']`)
      }
    })
    it('full state', () => {
      const test = testable.create({ value: { billingAddress: { test1: { test2: {} } } } })
      expect(test.matches('billingAddress.test1.test2')).toBeTruthy()
    })
    it('parent state', () => {
      const test = testable.create({ value: { billingAddress: { test1: { test2: {} } } } })
      expect(test.matches('billingAddress')).toBeTruthy()
    })
    it('child state', () => {
      const test = testable.create({ value: { billingAddress: { test1: { test2: {} } } } })
      expect(test.matches('billingAddress.notThere')).toBeFalsy()
    })
  })
  describe('transitions are reactive - ', () => {
    it('value', () => {
      const store = testable.create()
      const states = []
      autorun(() => {
        states.push(store.value)
      })

      store.sendEvent('CHANGE_TO_ADDRESS')
      store.sendEvent('CHANGE_TO_CONFIRMATION')

      expect(states).toMatchSnapshot()
    })
    it('rootState', () => {
      const store = testable.create()
      const states = []
      autorun(() => {
        states.push(store.rootState)
      })

      store.sendEvent('CHANGE_TO_ADDRESS')
      store.sendEvent('CHANGE_TO_CONFIRMATION')

      expect(states).toMatchSnapshot()
    })
    it('matches', () => {
      const store = testable.create()
      const states = []
      autorun(() => {
        states.push(store.matches('address'))
      })

      store.sendEvent('CHANGE_TO_ADDRESS')
      store.sendEvent('CHANGE_TO_CONFIRMATION')

      expect(states).toMatchSnapshot()
    })
  })
})

So the MST store wraps around the machine definition and interpreter. It has two big benefits: One, the state is serializable as it is stored as a frozen, secondly, everything is observable, so using store.matches can be tracked in a computed view / component etc.

CC @mattruby

[davidkpiano]

I'd be glad to create a small @xstate/mobx-state-tree library.