Consider renaming cond to guard

[davidprae]

I would like to request that the transition property cond be renamed to guard. This will help lessen the cognitive load of learning Xstate for newcomers (can consolidate jargon into one term). And I feel like it just makes sense to call them the same thing since that's how actions are treated: you specify one or more actions in the actions property.

So from

active: {
  on: {
    TOGGLE_STATUS: {
      target: 'inactive',
      cond: 'canBeInactive',
    },
  },
},

to

active: {
  on: {
    TOGGLE_STATUS: {
      target: 'inactive',
      guard: 'canBeInactive',
    },
  },
},

I vote for guard over cond because

1. It's the full word instead of an awkward truncation
2. I think it makes more sense from a conceptual standpoint
3. It's more "Xstate-specific" when compared to "condition" (which is such a general programming term) so will be more likely to stick in developers' minds as a part of Xstate's toolbox.
4. It'd be easier to switch over in current Xstate projects since it's just a property renaming

Building off that recommendation:

To further align Xstate ideas and terminology, I'd like to also suggest we pluralize guard to guards to match even more closely to the mental model of actions. guards should support an array of multiple guards (I believe there to be plenty of use cases for this) just like actions does. This helps eliminate needless, nonfunctional memorization of Xstate implementation details. Why would it be different?

Thanks for reading and considering!

[davidkpiano]

Your wish will be granted (in version 5): #1456 🧞

However, this will be a bit different:

I'd like to also suggest we pluralize guard to guards to match even more closely to the mental model of actions. guards should support an array of multiple guards (I believe there to be plenty of use cases for this) just like actions does.

The reason is that there is ambiguity here:

// "and" or "or"??
guards: ['guardOne', 'guardTwo']

What does this mean? "guardOne and guardTwo"? Or "guardOne or guardTwo"? You can argue both; some might naturally think that it means "and", but some might think it naturally means "one of these guards" (or).

In that PR, there is an even better solution: make it explicit, and allow for guards to be infinitely nested:

import { and, or, not } from 'xstate/guards';

// ...
{
  guard: and(['guardOne', 'guardTwo'])
}

// ...
{
  guard: or(['guardOne', 'guardTwo'])
}

// Have some fun!
{
  guard: and(['guardOne', or(['guardTwo', 'guardThree', not('guardFour')])])
}

This provides even more explicitness and flexibility versus just assuming that an array means "and" (or "or").

[davidprae]

That sounds great to me! In this case, the singular "guard" makes sense since we're constructing "one guard" out of many. 👍

Can we look forward to more funtional-type concepts like this going forward with Xstate? 🙌

Thanks!

[davidkpiano]

Sure; one area is that instead of XState supporting spawning/invoking promises/observables/callbacks/machines...

• Spawning and invoking are (and will be) exactly the same thing: creating an actor
• You can only spawn actors. There will be no special, built-in support for different things; only actors.

For developers, this just means a slight refactoring:

invoke: {
- src: (ctx, e) => new Promise(/* ... */),
  // creates a "promise actor creator"
+ src: invokePromise((ctx, e) => new Promise(/* ... */)) 
}

But it also opens the door to being able to invoke/spawn anything, not just promises/observables/callbacks/machines.

There was an "XState Wish List" thread started a year ago here: https://spectrum.chat/statecharts/general/xstate-wish-list~6f025b10-fcbc-4ab5-ae59-5201112f06f2 and I'm keeping track of most of these here: https://github.com/davidkpiano/xstate/projects/1

Maybe I should make a 2020 wish list discussion thread 🤔

[davidprae]

Awesome, I think that's great! This is another area where I think Xstate could clear up/consolidate terminology.

Thinking out loud: Option 1

I think "invoke" over "spawn" would promote a more immediately intuitive mental model from people coming from just any programming ecosystem. The "invoke" term can be referring to things beyond purely "creating" something like "spawing" is limited to. "invoke" is like "do and/or create" where "spawn" is just "create". So it makes more sense for "running" a callback.

Thinking out loud: Option 2

That said, since you mentioned "Spawning and invoking are (and will be) exactly the same thing: creating an actor. You can only spawn actors". You could force people to adopt the mental model of "SPAWN ONLY", so "CREATE ONLY". Which, if I understand correctly, invokePromise(myPromise) results in a new actor, it's an "actor creator". Same thing with invokeCallback(myCallback), it creates a singular actor that takes responsibility of your callback.

If we go this route, and you want this mental model to be on the surface and for people to understand it while working with Xstate, I'd vote for only the "spawn" terminology. I think the intent of "spawn" in general would be more immediately understood by more people than the more vague "invoke" ("spawn" clearly always "creates something"). If my understanding is correct, I'd like the above example to be more like

import { spawnFromPromise } from 'xstate/actors';

...

someState: {
    spawn: { 
       src: spawnFromPromise((ctx, e) => new Promise(/* ... */))
    }
}

I'd be happy and more in favor of being more explicit with spawnActorFrom... and property name changes:

import { spawnActorFromPromise } from 'xstate/actors';

...

someState: {
    spawnActor: {
       actor: spawnActorFromPromise((ctx, e) => new Promise(/* ... */))
    }
}

I think it's more readable; the code documents itself better:

"In someState, we want to spawn an actor. What actor? This actor that I'm creating from a promise".

It'll help people to learn Xstate as well since the code straight up explains itself.

And thanks for the links! I did know about the wishlist, it's just a bit too ephemeral and the kanban board is cool but that's "official/accepted" projects? I think there should be an intermediate project management solution. Something that isn't accepted yet, but isn't so ephemeral. I think "Proposals" like how TC39 handles new JS features would be awesome. Anyone can propose and it can work it's way up in a discussion format from Proposal Level 4 to Proposal Level 1 and done.