[core] Add `state.can(event)` #2546

davidkpiano · 2021-08-22T20:56:08Z

This PR adds state.can(...):

someState.can({ type: 'TOGGLE' }); // `true` if it will cause a transition

changeset-bot · 2021-08-22T20:56:10Z

🦋 Changeset detected

Latest commit: 65c7e62

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

This PR includes changesets to release 1 package

Name	Type
xstate	Minor

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

VanTanev · 2021-08-23T10:23:45Z

If we're adding this in core, I would like to see the full functionality of https://github.com/VanTanev/xstate-helpers/blob/development/src/react/useIsXStateTransitionAvailable.ts - eg, type inference for both event types as strings and event objects - XState supports that in other places.

Also, I strongly believe that the result of state.can() should always be a boolean and never undefined. If there is no machine available on the state, can() should just return false.

Also, what is the best practice around memorizing this? Is machine.transition() expensive enough to want to use @xstate/react/useSelector() around state.can()?

VanTanev · 2021-08-23T10:30:08Z

Patch attached:

diff --git a/packages/core/src/State.ts b/packages/core/src/State.ts
index 17435556..0378407a 100644
--- a/packages/core/src/State.ts
+++ b/packages/core/src/State.ts
@@ -129,7 +129,9 @@ export class State<
    */
   public children: Record<string, ActorRef<any>>;
   public tags: Set<string>;
-  private machine: StateMachine<TContext, any, TEvent, any> | undefined;
+  protected machine:
+    | StateMachine<TContext, any, TEvent, TTypestate>
+    | undefined;
   /**
    * Creates a new State instance for the given `stateValue` and `context`.
    * @param stateValue
@@ -321,16 +323,16 @@ export class State<
   /**
    * Determines whether sending the `event` will cause a transition.
    *
-   * If this state was created outside of a machine (e.g., with `State.from(...)`), `undefined` will be returned.
+   * If this state was created outside of a machine (e.g., with `State.from(...)`), `false` will be returned.
    *
    * @param event The event to test
    * @returns Whether the event will cause a transition
    */
-  public can(event: TEvent): boolean | undefined {
+  public can(event: TEvent | TEvent['type']): boolean {
     if (!this.machine) {
-      return undefined;
+      return false;
     }
 
-    return this.machine.transition(this, event).changed;
+    return !!this.machine.transition(this, event).changed;
   }
 }
diff --git a/packages/core/test/state.test.ts b/packages/core/test/state.test.ts
index 8b56738f..70145a3f 100644
--- a/packages/core/test/state.test.ts
+++ b/packages/core/test/state.test.ts
@@ -590,6 +590,10 @@ describe('State', () => {
             on: {
               NO_CHANGE: 'a',
               ACTION: { actions: 'someAction' },
+              ACTION_WITH_COND: {
+                actions: 'someAction',
+                cond: (_: any, e: any) => e.cond
+              },
               CHANGE: 'b'
             }
           },
@@ -598,15 +602,30 @@ describe('State', () => {
       });
 
       expect(machine.initialState.can({ type: 'UNKNOWN' })).toEqual(false);
+      expect(machine.initialState.can('UNKNOWN')).toEqual(false);
+
       expect(machine.initialState.can({ type: 'NO_CHANGE' })).toEqual(false);
+      expect(machine.initialState.can('NO_CHANGE')).toEqual(false);
+
       expect(machine.initialState.can({ type: 'ACTION' })).toEqual(true);
+      expect(machine.initialState.can('ACTION')).toEqual(true);
+
       expect(machine.initialState.can({ type: 'CHANGE' })).toEqual(true);
+      expect(machine.initialState.can('CHANGE')).toEqual(true);
+
+      expect(
+        machine.initialState.can({ type: 'ACTION_WITH_COND', cond: true })
+      ).toEqual(true);
+      expect(
+        machine.initialState.can({ type: 'ACTION_WITH_COND', cond: false })
+      ).toEqual(false);
+      expect(machine.initialState.can('ACTION_WITH_COND')).toEqual(false);
     });
 
-    it('should return undefined for states created without a machine', () => {
+    it('should return false for states created without a machine', () => {
       const state = State.from('test');
 
-      expect(state.can({ type: 'ANY_EVENT' })).toEqual(undefined);
+      expect(state.can({ type: 'ANY_EVENT' })).toEqual(false);
     });
   });
 });

VanTanev · 2021-08-23T16:39:16Z

After the last commit, this is chef's kiss~!
💯

Only thing left to fix is an incompatibility with StateConfig type.

It might be OK to make machine a public property?

packages/core/src/State.ts

Co-authored-by: Ivan Tanev <vankata.t@gmail.com>

VanTanev · 2021-08-25T16:51:55Z

Oops, my bad for leaving the 2nd machine prop there, sorry.

packages/core/src/State.ts

packages/core/test/state.test.ts

Andarist · 2021-08-26T14:36:11Z

.changeset/nice-pugs-shout.md

+'xstate': minor
+---
+
+You can now know if an event will cause a state change by using the new `state.can(event)` method, which will return `true` if the machine will change the state when sent the `event`, or `false` otherwise:


It would be great to explain what a change is. People could understand this differently. A change is when:

a state value changes

there are actions to be executed (entry/transition/exit)

context value changes

I hope I have not forgotten about anything

We probably should add the most common use-case: Checking buttons that execute transitions but are guarded by some condition.

💯 agree with both comments

Added to changeset. Will add the button example to the documentation in a subsequent PR

packages/core/src/State.ts

Andarist · 2021-08-26T14:41:57Z

How should errors thrown by assign actions and guards be treated? How they should be treated when we implement error-related changes and we actually start capturing all unhandled errors? Should an error be counted as a change (errors will, most likely, try to select a transition - why way or another)?

VanTanev · 2021-08-27T10:06:21Z

@Andarist I think there are two options here, both seem valid:

try-catch around the .can() and return false on caught errors
Do nothing, if .can() throws it's up to the caller to figure it out

davidkpiano · 2021-08-29T21:00:00Z

How should errors thrown by assign actions and guards be treated? How they should be treated when we implement error-related changes and we actually start capturing all unhandled errors? Should an error be counted as a change (errors will, most likely, try to select a transition - why way or another)?

Can this be resolved in a separate PR? Let's keep this one low-scope.

davidkpiano · 2021-08-29T21:05:52Z

@Andarist Ready for re-review

farskid · 2021-09-01T13:43:48Z

packages/core/test/state.test.ts

+  describe('.can', () => {
+    it('should return true for a simple event that results in a transition to a different state', () => {
+      const machine = createMachine({


Should we add an example for when only the context changes?

This would be very same-ish to the one here https://github.com/statelyai/xstate/pull/2546/files#diff-c70d4083bd7a91fd4094f9f0a5925c5d4df0e268c78a40cf97e71f7787b8b300R667 . However, assign actions are treated in a special way in the core - so it would still be worth adding such a test 👍

farskid

Besides the comments, LGTM.

Andarist · 2021-09-01T13:54:36Z

Can this be resolved in a separate PR? Let's keep this one low-scope.

At this stage, this is a design question about this API - both for v4 and for v5 (the answer can differ for both). I feel like it should be answered before merging this PR in because whatever lands on the main branch should be "releasable" and we shouldn't release something that might change (behavior-wise) soon-ish.

If you don't want to keep this PR low-scope but you'd like to make the design of this more tight & explicit before releasing then you could always create a PR targeting this PR.

If the answer is: "nothing should happen in v4 and errors should bubble to the caller" then it's fine. We can refine this in v5 (but a ticket~ should be created so we don't forget about it) but the appropriate tests should be added to validate this and to prevent us from regressing.

davidkpiano · 2021-09-01T16:51:39Z

If the answer is: "nothing should happen in v4 and errors should bubble to the caller" then it's fine. We can refine this in v5 (but a ticket~ should be created so we don't forget about it) but the appropriate tests should be added to validate this and to prevent us from regressing.

This is the answer IMO. Just added a test for this 👍

How would this be refined in v5?

Andarist · 2021-09-10T08:19:56Z

How would this be refined in v5?

That depends on the outcome of the error handling refactor. The behavior has been settled for the v4 though so let's just don't bother with thinking how this related to v5

davidkpiano · 2021-09-10T12:58:18Z

@Andarist Ready for final review 🏁

Andarist · 2021-09-10T14:14:45Z

packages/core/test/state.test.ts

+    it('should return true for an event object that results in a new action', () => {
+      const machine = createMachine({
+        initial: 'a',
+        states: {
+          a: {
+            on: {
+              NEXT: {
+                actions: 'newAction'
+              }
+            }
+          }
+        }
+      });
+
+      expect(machine.initialState.can({ type: 'NEXT' })).toBe(true);
+    });


note - this is basically a duplicate of

xstate/packages/core/test/state.test.ts

Lines 702 to 717 in 65c7e62

it('should return true for a targetless transition with actions', () => {

const machine = createMachine({

initial: 'a',

states: {

a: {

on: {

EV: {

actions: () => {}

}

}

}

}

});

expect(machine.initialState.can({ type: 'EV' })).toBe(true);

});

Add state.can

0132795

davidkpiano changed the title ~~Add state.can~~ [core] Add state.can(event) Aug 22, 2021

Add simple event support and machine warning

aecd167

VanTanev reviewed Aug 23, 2021

View reviewed changes

packages/core/src/State.ts Outdated Show resolved Hide resolved

davidkpiano commented Aug 23, 2021

View reviewed changes

packages/core/src/State.ts Outdated Show resolved Hide resolved

davidkpiano and others added 3 commits August 23, 2021 13:12

Update packages/core/src/State.ts

c8ef318

Update packages/core/src/State.ts

2a288ce

Co-authored-by: Ivan Tanev <vankata.t@gmail.com>

Fix type

658c287

Add changeset

a4cfce1

Andarist reviewed Aug 26, 2021

View reviewed changes

packages/core/src/State.ts Show resolved Hide resolved

Andarist reviewed Aug 26, 2021

View reviewed changes

packages/core/test/state.test.ts Outdated Show resolved Hide resolved

Andarist reviewed Aug 26, 2021

View reviewed changes

packages/core/src/State.ts Show resolved Hide resolved

Add more tests for state.can (#2563)

a984e94

davidkpiano added 2 commits August 29, 2021 17:00

Merge branch 'main' into davidkpiano/can

c13e551

Fix test title

2af2e7a

davidkpiano mentioned this pull request Aug 29, 2021

[v5] Avoid ad-hoc State creation #2576

Closed

farskid reviewed Sep 1, 2021

View reviewed changes

farskid approved these changes Sep 1, 2021

View reviewed changes

Merge branch 'main' into davidkpiano/can

e4fc2d9

Add error test

59db674

davidkpiano added 3 commits September 10, 2021 08:50

Merge branch 'main' into davidkpiano/can

8b85048

Add explanation of changed to changeset

648435c

Add context tests

65c7e62

Andarist reviewed Sep 10, 2021

View reviewed changes

Andarist approved these changes Sep 10, 2021

View reviewed changes

davidkpiano merged commit c78ef98 into main Sep 10, 2021

davidkpiano deleted the davidkpiano/can branch September 10, 2021 14:23

github-actions bot mentioned this pull request Sep 10, 2021

Version Packages #2634

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[core] Add `state.can(event)` #2546

[core] Add `state.can(event)` #2546

davidkpiano commented Aug 22, 2021 •

edited

Loading

changeset-bot bot commented Aug 22, 2021 •

edited

Loading

VanTanev commented Aug 23, 2021 •

edited

Loading

VanTanev commented Aug 23, 2021 •

edited

Loading

VanTanev commented Aug 23, 2021

VanTanev commented Aug 25, 2021

Andarist Aug 26, 2021

VanTanev Aug 27, 2021

farskid Sep 1, 2021

davidkpiano Sep 10, 2021

Andarist commented Aug 26, 2021

VanTanev commented Aug 27, 2021

davidkpiano commented Aug 29, 2021

davidkpiano commented Aug 29, 2021

farskid Sep 1, 2021

Andarist Sep 1, 2021

davidkpiano Sep 10, 2021

farskid left a comment

Andarist commented Sep 1, 2021

davidkpiano commented Sep 1, 2021

Andarist commented Sep 10, 2021

davidkpiano commented Sep 10, 2021

Andarist Sep 10, 2021

	it('should return true for a targetless transition with actions', () => {
	const machine = createMachine({
	initial: 'a',
	states: {
	a: {
	on: {
	EV: {
	actions: () => {}
	}
	}
	}
	}
	});

	expect(machine.initialState.can({ type: 'EV' })).toBe(true);
	});

[core] Add state.can(event) #2546

[core] Add state.can(event) #2546

Conversation

davidkpiano commented Aug 22, 2021 • edited Loading

changeset-bot bot commented Aug 22, 2021 • edited Loading

🦋 Changeset detected

VanTanev commented Aug 23, 2021 • edited Loading

VanTanev commented Aug 23, 2021 • edited Loading

VanTanev commented Aug 23, 2021

VanTanev commented Aug 25, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Andarist commented Aug 26, 2021

VanTanev commented Aug 27, 2021

davidkpiano commented Aug 29, 2021

davidkpiano commented Aug 29, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

farskid left a comment

Choose a reason for hiding this comment

Andarist commented Sep 1, 2021

davidkpiano commented Sep 1, 2021

Andarist commented Sep 10, 2021

davidkpiano commented Sep 10, 2021

Choose a reason for hiding this comment

[core] Add `state.can(event)` #2546

[core] Add `state.can(event)` #2546

davidkpiano commented Aug 22, 2021 •

edited

Loading

changeset-bot bot commented Aug 22, 2021 •

edited

Loading

VanTanev commented Aug 23, 2021 •

edited

Loading

VanTanev commented Aug 23, 2021 •

edited

Loading