[v5] Higher-level guards

[davidkpiano]

This PR aims to simplify the implementation details and TS types for guards, as well as adds the following higher-level guards:

• and([someGuard, anotherGuard, ...])
• or([someGuard, anotherGuard, ...])
• not(someGuard)
• Others?

These higher-level guards can be combined at any depth:

on: {
  EVENT: {
    target: 'somewhere',
    guard: and(['stringGuard', or([{ type: 'anotherGuard' }, not(() => false)])])
  }
}

And parameterized guards can use these higher-level guards:

on: {
  EVENT: { target: 'somewhere', guard: 'everythingValid' }
},

// ...

// machine options
guards: {
  thisValid: () => true,
  thatValid: not('thatInvalid'),
  thatInvalid: (context, event) => false,
  everythingValid: and(['thisValid', 'thatValid'])
}

It also will rename cond to guard in transitions, as this has been a common source of confusion.

TODO:

• Add and([...]) + tests
• Add or([...]) + tests
• Add not(...) + tests
• Add other boolean guards (if applicable)
• Enable "guard definitions" in guards instead of just predicates (not in this PR)
• Rename cond to guards
• Simplify types

[changeset-bot]

🦋 Changeset detected

Latest commit: 8fcbddd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
xstate	Major
@xstate/graph	Major
@xstate/immer	Major
@xstate/inspect	Major
@xstate/react	Major
@xstate/test	Major
@xstate/vue	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 0fe1e18:

Sandbox	Source
XState Example Template	Configuration
XState React Template	Configuration

[johnyanarella]

Really like this idea. Captures more interesting visualizable intent, too!

Given the variadic signature, wondering if every() (or all()), some() (or any()), etc. might read better left to right? That said not() reads better than none() would.

[johnyanarella]

After further thought, now I've convinced myself you had it right with and and or.

🤷

[Andarist]

I'm not super convinced that having a custom predicate that is responsible for resolving its children is a good idea - if u need something like this you can already use params, shouldn't children just be reserved for combinators like not, and and or?

In other words - could u prepare a real-life example of such a thing used in practice?

[davidkpiano]

if u need something like this you can already use params

Not exactly, since params are just params - they're not resolved. children are resolved.

The usefulness of this is so that custom guards that might need to reference other guards can be made in userland (such as xor(...), etc.).

[cbmd]

@davidkpiano guards not included in package.json in this PR. Is that intentional?