[core] Add basic support for state invariant

packages/core/src/StateNode.ts

@@ -153,6 +153,7 @@ export class StateNode<
   public tags: string[] = [];
   public transitions!: Map<string, TransitionDefinition<TContext, TEvent>[]>;
   public always?: Array<TransitionDefinition<TContext, TEvent>>;
+  public invariant?: ({ context }: { context: TContext }) => void;
 
   constructor(
     /**
@@ -227,6 +228,7 @@ export class StateNode<
     this.output =
       this.type === 'final' || !this.parent ? this.config.output : undefined;
     this.tags = toArray(config.tags).slice();
+    this.invariant = config.invariant;
   }
 
   /** @internal */

packages/core/src/stateUtils.ts

@@ -22,7 +22,6 @@ import {
   AnyMachineSnapshot,
   AnyStateNode,
   AnyTransitionDefinition,
-  DelayExpr,
   DelayedTransitionDefinition,
   EventObject,
   HistoryValue,
@@ -1690,6 +1689,8 @@ export function macrostep(
     );
     addMicrostate(nextSnapshot, event, []);
 
+    // No need to check invariant since the state is the same
+
     return {
       snapshot: nextSnapshot,
       microstates
@@ -1763,6 +1764,13 @@ export function macrostep(
     addMicrostate(nextSnapshot, nextEvent, enabledTransitions);
   }
 
+  // Check invariants
+  for (const sn of nextSnapshot._nodes) {
+    if (sn.invariant) {
+      sn.invariant({ context: nextSnapshot.context });
+    }
+  }
+
   if (nextSnapshot.status !== 'active') {
     stopChildren(nextSnapshot, nextEvent, actorScope);
   }

packages/core/src/types.ts

@@ -1038,6 +1038,8 @@ export interface StateNodeConfig<
    * A default target for a history state
    */
   target?: string;
+
+  invariant?: ({ context }: { context: TContext }) => void;
 }
 
 export type AnyStateNodeConfig = StateNodeConfig<

packages/core/test/invariant.test.ts

@@ -0,0 +1,74 @@
+import { assign, createActor, createMachine } from '../src';
+
+describe('state invariants', () => {
+  it('throws an error and does not transition if the invariant throws', () => {
+    const machine = createMachine({
+      initial: 'idle',
+      states: {
+        idle: {
+          on: {
+            loadUser: {
+              target: 'userLoaded'
+            }
+          }
+        },
+        userLoaded: {
+          invariant: (x) => {
+            if (!x.context.user) {
+              throw new Error('User not loaded');
+            }
+          }
+        }
+      }
+    });
+    const spy = jest.fn();
+
+    const actor = createActor(machine);
+    actor.subscribe({
+      error: spy
+    });
+    actor.start();
+
+    actor.send({ type: 'loadUser' });
+
+    expect(spy).toHaveBeenCalledWith(new Error('User not loaded'));
+
+    expect(actor.getSnapshot().value).toEqual('idle');
+  });
+
+  it('transitions as normal if the invariant does not fail', () => {
+    const machine = createMachine({
+      initial: 'idle',
+      states: {
+        idle: {
+          on: {
+            loadUser: {
+              target: 'userLoaded',
+              actions: assign({ user: () => ({ name: 'David' }) })
+            }
+          }
+        },
+        userLoaded: {
+          invariant: (x) => {
+            if (!x.context.user) {
+              throw new Error('User not loaded');
+            }
+          }
+        }
+      }
+    });
+    const spy = jest.fn();
+
+    const actor = createActor(machine);
+    actor.subscribe({
+      error: spy
+    });
+    actor.start();
+
+    actor.send({ type: 'loadUser' });
+
+    expect(spy).not.toHaveBeenCalled();
+
+    expect(actor.getSnapshot().value).toEqual('userLoaded');
+  });
+});