Simplify XState API and improve DX

[VanTanev]

Why are there many ways to do the same thing and how do I know which to choose?

— Kent C. Dodds (@kentcdodds) May 2, 2021

Let's limit the amount of polymorphism in the API and add some helpers for common mistakes.

My proposals:

1. interpreter.send() only takes event: TEvent extends EventObject. It no longer takes TType | Array<TType> | { type: TType } | Array<{ type: TType }>

send({ type: 'EVENT' })
send({ type: 'EVENT_WITH_DATA', data: 1 })

2. Machine event definitions no longer take string state target. Now they only take objects, so the minimum way to write an event with a target is:

{
 on: {
  EVENT: { target: 'state' }
 }
}

3. Action definitions no longer take a single argument; they always take an array:

{
 on: {
  EVENT: { actions: ['someAction'] }
 }
}

4. Add reserved keywords that are not allowed to show up in certain spots; e.g.:

{
 on: {
   // all event definition properties should be reserved, e.g.` actions, cond, target, etc...` and cannot be event names
   // throw error, `actions` is a reserved word
   actions: 'doSomething'
 }
}

5. Remove the property-assignment-function type from assign(). Leave only:

assign({ count: 0 })
assign((context, event) => ({ count: context.count + event.offset }))

[mattpocock]

I'm not necessarily in favour of this change, but I would say that less polymorphism makes type errors more readable.

[davidkpiano]

These things can (and in my opinion, should) be covered by some sort of ESLint plugin.

[kentcdodds]

I think it's important to note that the problem isn't necessarily that these things are possible, but that they are documented. So an eslint ruleset wouldn't help too much by itself. I need the documentation to be simplified and consistent.

[davidkpiano]

To clarify, you would prefer that the documentation only show one way of doing things consistently (with maybe a side-section on shortcuts)?

[kentcdodds]

Exactly

[ChrisShank]

Noting some additional examples that could use some consistency in the docs:

• instantiating machines (i.e. Machine, createMachine, createModel + createMachine)
• Inline config vs. externalized config
• target state nodes (i.e. when to use ids vs. relative targets)

[davidkpiano]

Machine has largely been removed; please let me know if you see it instead of createMachine

[ChrisShank]

sweet will do!

[jtoar]

There's at least one stray reference to it in the Getting Started section, here; see this PR for more details #1910.

[robertpenner]

Machine is in the default XState Viz.

[jtoar]

@robertpenner The Xstate Viz uses an older version of Xstate and it's non trivial to update it right now though I'm sure there'll be an update in the future. I added a note about it here in the PR that changes all the Machine references I could find #2185 (comment), but maybe there should be a note in the visualizer too?

[robertpenner]

#2 - I definitely would not want to be forced to use:

{
  on: {
    EVENT: { target: 'state' }
  }
}

instead of:

{
  on: {
    EVENT: 'state'
  }
}

It's common to have many simple transitions like this. DX is subjective but it definitely includes shortcuts for frequent operations.

[davidkpiano]

Completely agree; it should be easy to quickly prototype machines. I'll make sure to point out the shortcuts in the docs.