Xstate: Request for small API tweak: `onDone` / `on` should mirror `onEntry` / `onExit`

[LearningNerd]

Bug or feature request?

Small feature request

Description:

Currently, the onEntry and onExit properties of a state work differently than onDone and on event transitions. The difference here is just one of those little "gotchas" that makes the API a tiny bit harder to learn.... and I wasn't able to find a page in the docs or in the API docs that explicitly points this out (only implicitly through the provided examples).

The onDone or other on transitions can take an object:

onDone: {
  target: "otherState",
  actions: ["actionOne", "actionTwo"]
  // or shorthand if only 1 action:
  // actions: "actionOne"
},
on: {
  EVENTNAME: {
    target: "otherState",
    actions: ["actionThree", "actionFour"]
  }
}

But onEntry or onExit only take a string or array for actions:

onEntry: ["actionOne", "actionTwo"] 
// or shorthand if only 1 action:
// onEntry: "actionOne"

Relevant doc pages:

• https://xstate.js.org/docs/guides/actions.html
• https://xstate.js.org/docs/guides/final.html

Potential implementation:

What the API would look like:

It would be nice if onDone and on transition definitions could support the same format as onEntry and onExit, and vice versa -- just for the sake of symmetry and an easier-to-remember API.

Proposed alternate usage to add for onDone and on:

onDone: ["actionOne", "actionTwo"],
on: {
  EVENTNAME: ["actionThree", "actionFour"]
}

Proposed alternate usage to add for onEntry and onExit:

onEntry: {
  actions: ["actionOne", "actionTwo"]
  // or shorthand if only 1 action:
  // actions: "actionOne"
},

Note: Including a target for onEntry or onExit doesn't need to be supported (as I think it currently isn't, since that wouldn't make much sense anyway). If a target were supplied, I guess it would either just be ignored, or could throw an error or warning.

If this is a breaking change: Don't think so! The existing API would work the same; it would just add support for these optional alternatives.

If this is part of the existing SCXML specification: Not sure but I don't think it's relevant for this particular feature

Link to reproduction or proof-of-concept:

I could try to make a pull request for this if you think it's a good idea! :)

[davidkpiano]

Yeah you're right, there is some unfortunate naming inconsistency there.

Some backstory: onEntry and onExit come from SCXML <onentry> and <onexit>, respectively. Those elements can only have executable content (i.e., actions) and not transitions, unlike on and onDone.

A more literal name would be transitions for on, and doneTransition for onDone -- I chose on and onDone out of brevity, but can see the confusion.

It might actually make more sense if onEntry and onExit were renamed (aliased?) to entry and exit - not only would that be shorter, but it would give a clear distinction between those properties and the transition properties:

// Not actual API
{
  entry: ['action1', 'action2'],
  exit: 'action3',
  on: {
    FOO: 'bar'
  },
  initial: 'something',
  states: { /* ... */ },
  onDone: 'baz'
}

We could alias those in a future minor version and then deprecate onEntry and onExit in the next major version potentially 🤔

[mohanaravind]

onEntry and onExit are not getting called in Internet Explorer. I used IE 11 for testing.
I am not sure if I should file it as a separate issue but writing it anyway.

[davidkpiano]

@mohanaravind Internet Explorer is currently not a target for XState development. If you would like to provide IE support, I'd gladly accept a PR.

[mohanaravind]

@davidkpiano Thanks David for your quick response. I tried to dig into the root cause of the issue and the problem was it was always failing at StateNode.js file where the actions were not getting assigned to the right object. After further testing it standalone without other library interference I realized xstate actions for onEntry and onExit are getting called as expected. The problem was due to the polyfill for Object.assign and Array.from getting loaded after the Machine getting created. Once I loaded the module's asynchronously my problem got resolved. Thanks again for xstate