[@xstate/store] Add store.inspect(…)

.changeset/sweet-tools-compare.md

@@ -0,0 +1,16 @@
+---
+'@xstate/store': minor
+---
+
+You can now inspect XState stores using the `.inspect(inspector)` method:
+
+```ts
+import { someStore } from './someStore';
+
+someStore.inspect((inspEv) => {
+  console.log(inspEv);
+  // logs "@xstate.event" events and "@xstate.snapshot" events
+  // whenever an event is sent to the store
+});
+// The "@xstate.actor" event is immediately logged
+```

packages/core/src/inspection.ts

@@ -1,4 +1,5 @@
 import {
+  ActorRefLike,
   AnyActorRef,
   AnyEventObject,
   AnyTransitionDefinition,
@@ -21,7 +22,7 @@ interface BaseInspectionEventProperties {
    * - For event events, this is the target `actorRef` (recipient of event).
    * - For actor events, this is the `actorRef` of the registered actor.
    */
-  actorRef: AnyActorRef;
+  actorRef: ActorRefLike;
 }
 
 export interface InspectedSnapshotEvent extends BaseInspectionEventProperties {

packages/core/src/types.ts

@@ -1981,6 +1981,11 @@ export interface ActorRef<
 
 export type AnyActorRef = ActorRef<any, any, any>;
 
+export type ActorRefLike = Pick<
+  AnyActorRef,
+  'sessionId' | 'send' | 'getSnapshot'
+>;
+
 export type UnknownActorRef = ActorRef<Snapshot<unknown>, EventObject>;
 
 export type ActorLogicFrom<T> = ReturnTypeOrValue<T> extends infer R

packages/xstate-store/src/store.ts

@@ -1,3 +1,4 @@
+import type { InspectionEvent } from 'xstate';
 import {
   Recipe,
   EventPayloadMap,
@@ -41,6 +42,11 @@ function setter<TContext extends StoreContext>(
   return recipe(context);
 }
 
+const inspectionObservers = new WeakMap<
+  Store<any, any>,
+  Set<Observer<InspectionEvent>>
+>();
+
 function createStoreCore<
   TContext extends StoreContext,
   TEventPayloadMap extends EventPayloadMap
@@ -76,11 +82,31 @@ function createStoreCore<
   function receive(event: StoreEvent) {
     currentSnapshot = transition(currentSnapshot, event);
 
+    inspectionObservers.get(store)?.forEach((observer) => {
+      observer.next?.({
+        type: '@xstate.snapshot',
+        event,
+        snapshot: currentSnapshot,
+        actorRef: store,
+        rootId: store.sessionId
+      });
+    });
+
     observers?.forEach((o) => o.next?.(currentSnapshot));
   }
 
   const store: Store<TContext, StoreEvent> = {
+    sessionId: 'test',
     send(event) {
+      inspectionObservers.get(store)?.forEach((observer) => {
+        observer.next?.({
+          type: '@xstate.event',
+          event,
+          sourceRef: undefined,
+          actorRef: store,
+          rootId: store.sessionId
+        });
+      });
       receive(event as unknown as StoreEvent);
     },
     getSnapshot() {
@@ -102,6 +128,34 @@ function createStoreCore<
     },
     [symbolObservable](): InteropSubscribable<StoreSnapshot<TContext>> {
       return this;
+    },
+    inspect: (observerOrFn) => {
+      const observer = toObserver(observerOrFn);
+      inspectionObservers.set(
+        store,
+        inspectionObservers.get(store) ?? new Set()
+      );
+      inspectionObservers.get(store)!.add(observer);
+
+      observer.next?.({
+        type: '@xstate.actor',
+        actorRef: store,
+        rootId: store.sessionId
+      });
+
+      observer.next?.({
+        type: '@xstate.snapshot',
+        snapshot: initialSnapshot,
+        event: { type: '@xstate.init' },
+        actorRef: store,
+        rootId: store.sessionId
+      });
+
+      return {
+        unsubscribe() {
+          return inspectionObservers.get(store)?.delete(observer);
+        }
+      };
     }
   };
 

packages/xstate-store/src/types.ts

@@ -1,3 +1,5 @@
+import { InspectionEvent } from 'xstate';
+
 export type EventPayloadMap = Record<string, {} | null | undefined>;
 
 export type ExtractEventsFromPayloadMap<T extends EventPayloadMap> = Values<{
@@ -64,6 +66,19 @@ export interface Store<TContext, Ev extends EventObject>
   send: (event: Ev) => void;
   getSnapshot: () => StoreSnapshot<TContext>;
   getInitialSnapshot: () => StoreSnapshot<TContext>;
+  /**
+   * Subscribes to [inspection events](https://stately.ai/docs/inspection) from
+   * the store.
+   *
+   * Inspectors that call `store.inspect(…)` will immediately receive an
+   * "@xstate.actor" inspection event.
+   */
+  inspect: (
+    observer:
+      | Observer<InspectionEvent>
+      | ((inspectionEvent: InspectionEvent) => void)
+  ) => Subscription;
+  sessionId: string;
 }
 
 export type SnapshotFromStore<TStore extends Store<any, any>> =

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

@@ -166,3 +166,40 @@ it('can be observed', () => {
 
   expect(counts).toEqual([1, 2, 3]);
 });
+
+it('can be inspected', () => {
+  const store = createStore(
+    {
+      count: 0
+    },
+    {
+      inc: {
+        count: (ctx) => ctx.count + 1
+      }
+    }
+  );
+
+  const evs: any[] = [];
+
+  store.inspect((ev) => evs.push(ev));
+
+  store.send({ type: 'inc' });
+
+  expect(evs).toEqual([
+    expect.objectContaining({
+      type: '@xstate.actor'
+    }),
+    expect.objectContaining({
+      type: '@xstate.snapshot',
+      snapshot: expect.objectContaining({ context: { count: 0 } })
+    }),
+    expect.objectContaining({
+      type: '@xstate.event',
+      event: { type: 'inc' }
+    }),
+    expect.objectContaining({
+      type: '@xstate.snapshot',
+      snapshot: expect.objectContaining({ context: { count: 1 } })
+    })
+  ]);
+});