[@xstate/store] Add wildcard support for store.on('*', ...) (#5467)

* Add wildcard support for store.on()

* Address comments

* Nicer type

Author: davidkpiano

.changeset/bright-walls-sniff.md

@@ -0,0 +1,27 @@
+---
+'@xstate/store': minor
+---
+
+Add wildcard `'*'` support for `store.on('*', …)` to listen to all emitted events. The handler receives the union of all emitted event types.
+
+```ts
+const store = createStore({
+  context: { count: 0 },
+  emits: {
+    increased: (_: { upBy: number }) => {},
+    decreased: (_: { downBy: number }) => {}
+  },
+  on: {
+    inc: (ctx, _, enq) => {
+      enq.emit.increased({ upBy: 1 });
+      return { ...ctx, count: ctx.count + 1 };
+    }
+  }
+});
+
+store.on('*', (ev) => {
+  // ev:
+  // | { type: 'increased'; upBy: number }
+  // | { type: 'decreased'; downBy: number }
+});
+```

packages/xstate-store/src/store.ts

@@ -57,6 +57,10 @@ function createStoreCore<
     if (typeListeners) {
       typeListeners.forEach((listener) => listener(ev));
     }
+    const wildcardListeners = listeners.get('*' as TEmitted['type']);
+    if (wildcardListeners) {
+      wildcardListeners.forEach((listener) => listener(ev));
+    }
   };
 
   const transition = logic.transition;
@@ -270,6 +274,7 @@ export function createStore(
   if ('transition' in definitionOrLogic) {
     return createStoreCore(definitionOrLogic);
   }
+
   const transition = createStoreTransition(definitionOrLogic.on);
   const logic: AnyStoreLogic = {
     getInitialSnapshot: () => ({

packages/xstate-store/src/types.ts

@@ -97,10 +97,12 @@ export interface Store<
       | ((inspectionEvent: StoreInspectionEvent) => void)
   ) => Subscription;
   sessionId: string;
-  on: <TEmittedType extends TEmitted['type']>(
-    eventType: TEmittedType,
-    emittedEventHandler: (
-      emittedEvent: Compute<TEmitted & { type: TEmittedType }>
+  on: <TType extends TEmitted['type'] | '*'>(
+    type: TType,
+    handler: (
+      emitted: Compute<
+        TEmitted & (TType extends '*' ? unknown : { type: TType })
+      >
     ) => void
   ) => Subscription;
   /**
@@ -212,9 +214,9 @@ export type SpecificStoreConfig<
 
 type IsEmptyObject<T> = T extends Record<string, never> ? true : false;
 
-export type AnyStore = Store<any, any, any>;
+type Compute<A> = A extends any ? { [K in keyof A]: A[K] } : never;
 
-type Compute<A> = { [K in keyof A]: A[K] };
+export type AnyStore = Store<any, any, any>;
 
 export type SnapshotFromStore<TStore extends Store<any, any, any>> =
   TStore extends Store<infer TContext, any, any>

packages/xstate-store/test/store.test.ts

@@ -486,6 +486,84 @@ it('emits-only transitions should emit events', () => {
   expect(spy).toHaveBeenCalledTimes(1);
 });
 
+it('wildcard listener receives all emitted events', () => {
+  const spy = vi.fn();
+  const store = createStore({
+    context: { count: 0 },
+    emits: {
+      increased: (_: { upBy: number }) => {},
+      decreased: (_: { downBy: number }) => {}
+    },
+    on: {
+      inc: (ctx, _, enq) => {
+        enq.emit.increased({ upBy: 1 });
+        return { ...ctx, count: ctx.count + 1 };
+      },
+      dec: (ctx, _, enq) => {
+        enq.emit.decreased({ downBy: 1 });
+        return { ...ctx, count: ctx.count - 1 };
+      }
+    }
+  });
+
+  store.on('*', spy);
+
+  store.trigger.inc();
+  expect(spy).toHaveBeenCalledWith({ type: 'increased', upBy: 1 });
+
+  store.trigger.dec();
+  expect(spy).toHaveBeenCalledWith({ type: 'decreased', downBy: 1 });
+
+  expect(spy).toHaveBeenCalledTimes(2);
+});
+
+it('wildcard listener can be unsubscribed', () => {
+  const spy = vi.fn();
+  const store = createStore({
+    context: { count: 0 },
+    emits: {
+      increased: (_: { upBy: number }) => {}
+    },
+    on: {
+      inc: (ctx, _, enq) => {
+        enq.emit.increased({ upBy: 1 });
+        return { ...ctx, count: ctx.count + 1 };
+      }
+    }
+  });
+
+  const sub = store.on('*', spy);
+  store.trigger.inc();
+  expect(spy).toHaveBeenCalledTimes(1);
+
+  sub.unsubscribe();
+  store.trigger.inc();
+  expect(spy).toHaveBeenCalledTimes(1);
+});
+
+it('wildcard listener is called after specific listener', () => {
+  const order: string[] = [];
+  const store = createStore({
+    context: { count: 0 },
+    emits: {
+      increased: (_: { upBy: number }) => {}
+    },
+    on: {
+      inc: (ctx, _, enq) => {
+        enq.emit.increased({ upBy: 1 });
+        return { ...ctx, count: ctx.count + 1 };
+      }
+    }
+  });
+
+  store.on('increased', () => order.push('specific'));
+  store.on('*', () => order.push('wildcard'));
+
+  store.trigger.inc();
+
+  expect(order).toEqual(['specific', 'wildcard']);
+});
+
 it('async effects can be enqueued', async () => {
   const store = createStore({
     context: {

packages/xstate-store/test/types.test.tsx

@@ -89,6 +89,26 @@ describe('emitted', () => {
     );
   });
 
+  it('wildcard listener receives union of all emitted events', () => {
+    const store = createStore({
+      emits: {
+        increased: (_: { upBy: number }) => {},
+        decreased: (_: { downBy: number }) => {}
+      },
+      context: {},
+      on: {}
+    });
+
+    store.on('*', (ev) => {
+      ev satisfies
+        | { type: 'increased'; upBy: number }
+        | { type: 'decreased'; downBy: number };
+
+      // @ts-expect-error
+      ev satisfies { type: 'unknown' };
+    });
+  });
+
   it('works with a discriminated union event payload', () => {
     createStore({
       context: {},