Add assertEvent (#4547)

* Add assertEvent * Cleanup * Support multiple events * TSDocs * Changeset * Update .changeset/cuddly-taxis-walk.md Co-authored-by: Mateusz Burzyński <mateuszburzynski@gmail.com> * Update packages/core/src/assert.ts Co-authored-by: Mateusz Burzyński <mateuszburzynski@gmail.com> * Update .changeset/cuddly-taxis-walk.md Co-authored-by: Mateusz Burzyński <mateuszburzynski@gmail.com> * Update packages/core/src/assert.ts Co-authored-by: Mateusz Burzyński <mateuszburzynski@gmail.com> * Export * Cleanup * Fixes --------- Co-authored-by: Mateusz Burzyński <mateuszburzynski@gmail.com>
statelyai · Dec 13, 2023 · 8e8d2ba · 8e8d2ba
1 parent dd668c6
commit 8e8d2ba
Show file tree

Hide file tree

Showing 7 changed files with 176 additions and 22 deletions.
diff --git a/.changeset/cuddly-taxis-walk.md b/.changeset/cuddly-taxis-walk.md
@@ -0,0 +1,23 @@
+---
+'xstate': minor
+---
+
+Add `assertEvent(...)` to help provide strong typings for events that can't be easily inferred, such as events in `entry` and `exit` actions, or in `invoke.input`.
+
+The `assertEvent(event, 'someType')` function will _throw_ if the event is not the expected type. This ensures that the `event` is guaranteed to have that type, and assumes that the event object has the expected payload (naturally enforced by TypeScript).
+
+```ts
+// ...
+entry: ({ event }) => {
+  assertEvent(event, 'greet');
+  // event is { type: 'greet'; message: string }
+
+  assertEvent(event, ['greet', 'notify']);
+  // event is { type: 'greet'; message: string }
+  // or { type: 'notify'; message: string; level: 'info' | 'error' }
+},
+exit: ({ event }) => {
+  assertEvent(event, 'doNothing');
+  // event is { type: 'doNothing' }
+}
+```
diff --git a/packages/core/src/assert.ts b/packages/core/src/assert.ts
@@ -0,0 +1,43 @@
+import { EventObject } from './types.ts';
+import { toArray } from './utils.ts';
+
+/**
+ * Asserts that the given event object is of the specified type or types.
+ * Throws an error if the event object is not of the specified types.
+  @example
+
+  ```ts
+  // ...
+  entry: ({ event }) => {
+    assertEvent(event, 'doNothing');
+    // event is { type: 'doNothing' }
+  },
+  // ...
+  exit: ({ event }) => {
+    assertEvent(event, 'greet');
+    // event is { type: 'greet'; message: string }
+
+    assertEvent(event, ['greet', 'notify']);
+    // event is { type: 'greet'; message: string }
+    // or { type: 'notify'; message: string; level: 'info' | 'error' }
+  },
+  ```
+ */
+export function assertEvent<
+  TEvent extends EventObject,
+  TAssertedType extends TEvent['type']
+>(
+  event: TEvent,
+  type: TAssertedType | TAssertedType[]
+): asserts event is TEvent & { type: TAssertedType } {
+  const types = toArray(type);
+  if (!types.includes(event.type as any)) {
+    const typesText =
+      types.length === 1
+        ? `type "${types[0]}"`
+        : `one of types "${types.join('", "')}"`;
+    throw new Error(
+      `Expected event ${JSON.stringify(event)} to have ${typesText}`
+    );
+  }
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -36,6 +36,7 @@ export {
   StateNode,
   type Interpreter
 };
+export { assertEvent } from './assert.ts';
 
 declare global {
   interface SymbolConstructor {

diff --git a/packages/core/test/actor.test.ts b/packages/core/test/actor.test.ts
@@ -164,9 +164,7 @@ describe('spawning machines', () => {
         SET_COMPLETE: {
           actions: sendTo(
             ({ context, event }) => {
-              return context.todoRefs[
-                (event as Extract<TodoEvent, { type: 'SET_COMPLETE' }>).id
-              ];
+              return context.todoRefs[event.id];
             },
             { type: 'SET_COMPLETE' }
           )

diff --git a/packages/core/test/after.test.ts b/packages/core/test/after.test.ts
@@ -287,7 +287,7 @@ describe('delayed transitions', () => {
           delays: {
             someDelay: ({ event }) => {
               spy(event);
-              return (event as any).delay;
+              return event.delay;
             }
           }
         }

diff --git a/packages/core/test/assert.test.ts b/packages/core/test/assert.test.ts
@@ -0,0 +1,100 @@
+import { createActor, createMachine, assertEvent } from '../src';
+
+describe('assertion helpers', () => {
+  it('assertEvent asserts the correct event type', (done) => {
+    const machine = createMachine(
+      {
+        types: {
+          events: {} as
+            | { type: 'greet'; message: string }
+            | { type: 'count'; value: number }
+        },
+        on: {
+          greet: { actions: 'greet' },
+          count: { actions: 'greet' }
+        }
+      },
+      {
+        actions: {
+          greet: ({ event }) => {
+            // @ts-expect-error
+            event.message;
+
+            assertEvent(event, 'greet');
+            event.message satisfies string;
+
+            // @ts-expect-error
+            event.count;
+          }
+        }
+      }
+    );
+
+    const actor = createActor(machine);
+
+    actor.subscribe({
+      error(err) {
+        expect(err).toMatchInlineSnapshot(
+          `[Error: Expected event {"type":"count","value":42} to have type "greet"]`
+        );
+        done();
+      }
+    });
+
+    actor.start();
+
+    actor.send({ type: 'count', value: 42 });
+  });
+
+  it('assertEvent asserts multiple event types', (done) => {
+    const machine = createMachine(
+      {
+        types: {
+          events: {} as
+            | { type: 'greet'; message: string }
+            | { type: 'notify'; message: string; level: 'info' | 'error' }
+            | { type: 'count'; value: number }
+        },
+        on: {
+          greet: { actions: 'greet' },
+          count: { actions: 'greet' }
+        }
+      },
+      {
+        actions: {
+          greet: ({ event }) => {
+            // @ts-expect-error
+            event.message;
+
+            assertEvent(event, ['greet', 'notify']);
+            event.message satisfies string;
+
+            // @ts-expect-error
+            event.level;
+
+            assertEvent(event, ['notify']);
+            event.level satisfies 'info' | 'error';
+
+            // @ts-expect-error
+            event.count;
+          }
+        }
+      }
+    );
+
+    const actor = createActor(machine);
+
+    actor.subscribe({
+      error(err) {
+        expect(err).toMatchInlineSnapshot(
+          `[Error: Expected event {"type":"count","value":42} to have one of types "greet", "notify"]`
+        );
+        done();
+      }
+    });
+
+    actor.start();
+
+    actor.send({ type: 'count', value: 42 });
+  });
+});
diff --git a/packages/core/test/interpreter.test.ts b/packages/core/test/interpreter.test.ts
@@ -16,6 +16,7 @@ import { interval, from } from 'rxjs';
 import { fromObservable } from '../src/actors/observable';
 import { PromiseActorLogic, fromPromise } from '../src/actors/promise';
 import { fromCallback } from '../src/actors/callback';
+import { assertEvent } from '../src/assert.ts';
 
 const lightMachine = createMachine({
   id: 'light',
@@ -246,15 +247,7 @@ describe('interpreter', () => {
               { type: 'FINISH' },
               {
                 delay: ({ context, event }) =>
-                  context.initialDelay +
-                  ('wait' in event
-                    ? (
-                        event as Extract<
-                          DelayExpMachineEvents,
-                          { type: 'ACTIVATE' }
-                        >
-                      ).wait
-                    : 0)
+                  context.initialDelay + ('wait' in event ? event.wait : 0)
               }
             ),
             on: {
@@ -327,14 +320,10 @@ describe('interpreter', () => {
             entry: raise(
               { type: 'FINISH' },
               {
-                delay: ({ context, event }) =>
-                  context.initialDelay +
-                  (
-                    event as Extract<
-                      DelayExpMachineEvents,
-                      { type: 'ACTIVATE' }
-                    >
-                  ).wait
+                delay: ({ context, event }) => {
+                  assertEvent(event, 'ACTIVATE');
+                  return context.initialDelay + event.wait;
+                }
               }
             ),
             on: {
@@ -423,7 +412,7 @@ describe('interpreter', () => {
               return context.delay + 50;
             },
             delayA: ({ context }) => context.delay,
-            delayD: ({ context, event }) => context.delay + (event as any).value
+            delayD: ({ context, event }) => context.delay + event.value
           }
         }
       );