Xstate: Suggestion to rename "send" API

[mastermike501]

Description
[Suggestion for API enhancement] Currently the send() function, according to the docs (screenshot below), doesn't imperatively send an event, but rather creates a new event on the event queue. So I'm suggesting a rename of send() to one of the following:

• queue
• queueEvent
• queueAction

This request will definitely break existing functionality, but I think this rename might help in making this already wonderful project even more readable. 🙂

PS. Hope I understood the docs right! Please close the issue if there is a gap in my understanding and help me to understand the reason to name the API as send(). Thank you!

[mastermike501]

Actually come to think of it, I remember @davidkpiano mentioning that he chose the name send() over the name dispatch() due to the brevity of the name. I just don't recall where he mentioned that.

[davidkpiano]

Hey, good recommendation! One correction:

[...] doesn't imperatively send an event, but rather creates a new event on the event queue.

The send() action creator doesn't do that either; it creates an action object just like all the other action creators.

Re: queueing, it sends an event to a queue, so the terminology is still correct.

---

For historical info, the name send was chosen partially for brevity, but also to be consistent with the semantics in SCXML and Harel's original paper.

Also, it unifies <send>, which is used for sending events to other statecharts in SCXML (send() action creator in XState as well) and matches the semantics of the Actor model (for example, see how Akka does this).

---

But if you're talking about the action creator send(), I think the better solution would be to clean up the docs, and provide clearer examples for these action creators:

import {
  createMachine,
- send
+ actions
} from 'xstate';

// ...

- FOO: { actions: send('BAR') },
+ FOO: { actions: actions.send('BAR') },

Thoughts?

[mastermike501]

Right, so I think the idea of looking at statemachines/statecharts (as you mentioned somewhere in the docs 😅) as microservices is key to understanding the terminology used within the library. Makes perfect sense to align with the terminology standards. 🙂

---

But if you're talking about the action creator send(), I think...

To be honest, I've only started using Xstate for a week so a few of the terminologies still fly over my head. What are the "action creators" that you are referring to?

[davidkpiano]

Action creators are functions that create actions:

send('FOO');
// {
//   type: 'xstate.send',
//   event: {
//     type: 'FOO'
//   }
// }

That action object represents a side-effect (again, "action" is state machine terminology) to be executed by an interpreter.

[mastermike501]

Right, so I think the idea of looking at statemachines/statecharts (as you mentioned somewhere in the docs 😅) as microservices is key to understanding the terminology used within the library. Makes perfect sense to align with the terminology standards. 🙂

But if you're talking about the action creator send(), I think...

To be honest, I've only started using Xstate for a week so a few of the terminologies still fly over my head. What are the "action creators" that you are referring to?

Wait I got it now. I didn't realize that there was a actions export from xstate.

On the grander scale of things, I actually struggled in using the docs, I'm trying to get the hang of xstate first then see how I can contribute towards the documentation.

[Andarist]

But if you're talking about the action creator send(), I think the better solution would be to clean up the docs, and provide clearer examples for these action creators:

Hm, would that verbosity do any good? It's actually not even that much needed as the only possible thing accepted by actions (and similar properties) are actions, so once you know that then actions.send makes things a little bit harder to read (due to its verbosity). And this namespace~ object is also somewhat semantically incorrect because those are not actions but actionCreators.

Some improvements to the docs to make this clearer would, of course, be very much appreciated, but I feel like maybe explaining concepts in more detail beforehand would be better than spreading something like this all over the place. Personally I'm not sure what exactly can be improved, because I think XState has pretty nice docs and I've also seen some praises for them online.

There are only 2 hard problems in computer science - naming things and writing docs 😅

[mastermike501]

Heartily agree with your last statement! 😉

I think the introductions to the whats and whys of statemachines and statecharts have been exemplary, all courtesy of @davidkpiano. However to me, the missing bit seems to be information to help users who are discovering or rediscovering statemachines/statecharts given that the terminology regarding the library and how it works is very specific (maybe even technical).

I fully agree with what David said regarding the shared and common vocabulary between whitepapers and the library. Nevertheless I do believe people often use library docs as and when they need them and it's rare (or nonexistent even!) to find the person who reads all the docs before using; therefore, the context of terms and phrases often get lost, misintepreted or misunderstood. 😅 My suggestion would be to provide these definitions as and when the user needs it.

More specifically, I'm wondering if a "terminology" section (might be too far isolated from usage) or info icons explaining/defining terms peculiar to the said standards would be useful?

[Andarist]

Maybe using more links to the glossary where different things are mentioned in different parts of the docs would help with that?

[mastermike501]

Worth a try I guess. Helping the user understand how to put on the statemachine chart thinking-cap and think like a statemachine would definitely help! 🎉

[davidkpiano]

Hm, would that verbosity do any good?

Probably not, now that I think about it. You're right.

However to me, the missing bit seems to be information to help users who are discovering or rediscovering statemachines/statecharts given that the terminology regarding the library and how it works is very specific (maybe even technical).

Yeah, more introductory/"why" material would be good. I always point to https://statecharts.github.io as a great starting point. Its glossary is great, as well.

[mastermike501]

Hm, would that verbosity do any good?

Probably not, now that I think about it. You're right.

However to me, the missing bit seems to be information to help users who are discovering or rediscovering statemachines/statecharts given that the terminology regarding the library and how it works is very specific (maybe even technical).

Yeah, more introductory/"why" material would be good. I always point to https://statecharts.github.io as a great starting point. Its glossary is great, as well.

Gosh I didn't realize this website existed. I think this might be a case closed. I'll definitely make it a mandatory read for anyone who hasn't before dabbled in statecharts!

[davidkpiano]

In general, there are so many resources online about statecharts. I'll add a "Resources" section to the docs with all the general resources.

One of the biggest goals with this project is that anything you learn about state machines and statecharts (even from decades-old research papers) should be directly applicable to XState. No new/foreign concepts! If you know statecharts, you know XState.

[mastermike501]

Cool! Like I said, it's getting new users into the mindset of the statechart-ist. (Think back of Angular way, react way, redux way, etc) 😅

I'll close this thread then. Thanks @davidkpiano @Andarist!