Watchers - a proposal for reacting to context changes

[jamesopstad]

This is a proposal to bring reactivity to XState by adding a watch property to state nodes. The watch value is an object or array of objects containing:

• actions
• dependencies - an array of strings that are keys of properties on the machine context

Each time any of the specified context properties change, the actions are executed.

With this proposal it is possible to:

• derive context
• trigger other actions in response to context changes

As watchers are part of the state node definition, they can be located at any position in the state hierarchy. This offers a lot of flexibility and means that the actions triggered by context changes are determined by the current state.

What problems does this solve?

When using XState, there is often a tradeoff between locating application code in XState or in UI components. By moving the code into XState you can lose some of the benefits of using a reactive framework.

The same context value can be updated in response to different events. If further actions should then be executed in response to this change then these need to be duplicated in different parts of the machine definition. This can be repetitive and error-prone.

Examples

Derived context

const machine = createMachine({
  id: 'derived',
  context: {
    firstName: 'John',
    lastName: 'Smith',
    fullName: ''
  },
  watch: {
    actions: assign({
      fullName: (ctx) => ctx.firstName + ' ' + ctx.lastName
    }),
    dependencies: ['firstName', 'lastName']
  },
  on: {
    SET_FIRST_NAME: {
      actions: assign({
        firstName: (_, event) => event.data
      })
    },
    SET_LAST_NAME: {
      actions: assign({
        lastName: (_, event) => event.data
      })
  }
})

Sync value with external service

const machine = createMachine({
  id: 'sync',
  initial: 'inactive',
  context: {
    someValue: someValue
  },
  states: {
    inactive: {
      // ...
    },
    active: {
      watch: [
        {
          actions: 'syncValue',
          dependencies: ['someValue']
        },
        // other watchers
      ],
      on: {
        SOME_ACTION: {
          actions: assign({
            someValue: (_, event) => event.data
          })
        }
      }
    }
  }
})

Implementation

Given the way that XState is implemented, I think it makes sense to implement this by dirty checking the context object. This should happen after any assign actions have executed in response to an event. Watchers with one or more dependencies marked as dirty should then execute their assign actions. Another dirty check should take place and this process should loop until no watchers are called. Any properties that have changed on the context object since the event was fired should then be marked as dirty and the watchers should be traversed one more time to push non-assign actions to the actions array.

It should be noted that if assign actions always used the object form then dirty checking may be unnecessary. The changed properties could instead be determined by the keys in the assigner. I wonder if watchers could render the function form for assigners unnecessary as it is often used when multiple context values depend on each other. I imagine the combination of explicit assignments and watchers with explicit dependencies would also be great for visualisation.

Questions

Should the watchers execute on entering a new state?

This would be desired in some cases, such as the derived context example above. More consideration is needed to decide if this should be the default or an additional option.

Should nested values be allowed as dependencies?

Although this might be possible using dot notation, my feeling is that it's better to encourage flatter data structures and only detect changes at the top level.

Summary

This is a proposal for a new watch property that enables declaring actions that are executed in response to context changes. I am interested in whether you think the idea is worth considering.

[johtso]

This looks interesting!

Another thought would be.. if you trigger 4 actions and a computed property that depends on the context changed by all of them.. do you trigger it 4 times?

[jamesopstad]

For each loop through the watchers a watcher would execute once if one or more dependencies are marked as dirty. Does that answer your question?

[johtso]

So the watchers would be looped through after each assign action? I wonder if we could look ahead and see what assign actions were queued and only execute the watchers once if possible. Not sure if this can be done though as intermediate actions might rely on the watcher having executed..

[jamesopstad]

I've edited the text to try and make things a little clearer. Assignments are batched in XState so the watchers would only be looped through after all assign actions have executed in response to an event. Non-assign actions on watchers will only be added once at the end of the process. Of course, the exact implementation would require a lot more thought. At this stage it's mainly important to establish if the idea has value. One note I've added is that the object syntax for assign has significant benefits as it already offers a way of declaring which properties will change.

[jamesopstad]

It would be great to have some feedback on this proposal. I also wanted to note that if assign actions were limited to the function syntax then all context changes (including in watchers) would be statically analysable. This would allow context changes to be visualised and would also make it possible to catch errors in watchers such as circular dependencies. It would also eliminate the need for dirty checking in this proposal as context changes could be registered by adding the keys in assign objects to a Set.

[davidkpiano]

I'll take a deeper look this weekend, I promise!

[Andarist]

Isn't the potential problem here that you have too many events touching a single context variable? Wouldn't namespacing them (and matching descriptors like NAMESPACE.*) alleviate the problem?

This would introduce an extra step to the microstep algorithm but what I'm most concerned about is that this makes the modeling part potentially more fuzzy. Instead of reacting to business/process-oriented events you want to focus more on an implementation detail (a context variable).

[jamesopstad]

Thanks for having a look.

Isn't the potential problem here that you have too many events touching a single context variable? Wouldn't namespacing them (and matching descriptors like NAMESPACE.*) alleviate the problem?

Do you mean the problem this tries to solve or the problem it creates? Not entirely sure what you're suggesting. Are you able to provide an example?

This would introduce an extra step to the microstep algorithm but what I'm most concerned about is that this makes the modeling part potentially more fuzzy. Instead of reacting to business/process-oriented events you want to focus more on an implementation detail (a context variable).

I agree that this can be seen as adding a layer of indirection that makes the modelling less explicit. I think tooling can really help here though. Actions are still only executed in response to events but now the initial assignments can trigger further actions reactively. My feeling is that this reactivity is what people miss the most when working with XState but I could be wrong or overstating the case. You can think of watchers as analogous to useEffect in React, but much stricter because they only allow XState actions to be executed rather than arbitrary code. There are also similarities to computed and watch in Vue but with explicit dependencies. In XState, different watchers can be applied depending on the current state so it's still very statechart focused.