Expose subscription as an inspection event

.changeset/many-teeth-cough.md

@@ -0,0 +1,30 @@
+---
+'xstate': minor
+---
+
+Exposes actor subscription as an inspection event.
+
+```ts
+import { createMachine, createActor } from 'xstate';
+
+const machine = createMachine({
+  // ...
+});
+
+const actor = createActor(machine, {
+  inspect: (event) => {
+    // event.type === '@xstate.subscription'
+    // event.actorRef === actor to which the subscription belongs to
+    // event.subscriptionId === 'my-observer-id'
+  }
+});
+
+actor.subscribe(
+  (snapshot) => {
+    console.log(snapshot);
+  },
+  undefined,
+  undefined,
+  'my-observer-id'
+);
+```

packages/core/src/createActor.ts

@@ -415,23 +415,31 @@ export class Actor<TLogic extends AnyActorLogic>
   public subscribe(
     nextListener?: (snapshot: SnapshotFrom<TLogic>) => void,
     errorListener?: (error: any) => void,
-    completeListener?: () => void
+    completeListener?: () => void,
+    observerId?: string
   ): Subscription;
   public subscribe(
     nextListenerOrObserver?:
       | ((snapshot: SnapshotFrom<TLogic>) => void)
       | Observer<SnapshotFrom<TLogic>>,
     errorListener?: (error: any) => void,
-    completeListener?: () => void
+    completeListener?: () => void,
+    observerId?: string
   ): Subscription {
     const observer = toObserver(
       nextListenerOrObserver,
       errorListener,
-      completeListener
+      completeListener,
+      observerId
     );
 
     if (this._processingStatus !== ProcessingStatus.Stopped) {
       this.observers.add(observer);
+      this._actorScope.system._sendInspectionEvent({
+        type: '@xstate.subscription',
+        actorRef: this,
+        subscriptionId: observer.id
+      });
     } else {
       switch ((this._snapshot as any).status) {
         case 'done':

packages/core/src/inspection.ts

@@ -10,18 +10,21 @@ export type InspectionEvent =
   | InspectedEventEvent
   | InspectedActorEvent
   | InspectedMicrostepEvent
-  | InspectedActionEvent;
+  | InspectedActionEvent
+  | InspectedSubscriptionEvent;
 
-interface BaseInspectionEventProperties {
+interface BaseInspectionEventProperties<T extends ActorRefLike = ActorRefLike> {
   rootId: string; // the session ID of the root
   /**
    * The relevant actorRef for the inspection event.
    *
    * - For snapshot events, this is the `actorRef` of the snapshot.
    * - For event events, this is the target `actorRef` (recipient of event).
    * - For actor events, this is the `actorRef` of the registered actor.
+   * - For subscription events, this is the `actorRef` of the actor that is being
+   *   subscribed to.
    */
-  actorRef: ActorRefLike;
+  actorRef: T;
 }
 
 export interface InspectedSnapshotEvent extends BaseInspectionEventProperties {
@@ -54,6 +57,12 @@ export interface InspectedEventEvent extends BaseInspectionEventProperties {
   event: AnyEventObject; // { type: string, ... }
 }
 
+export interface InspectedSubscriptionEvent
+  extends BaseInspectionEventProperties<ActorRefLike & { systemId?: string }> {
+  type: '@xstate.subscription';
+  subscriptionId: string | undefined;
+}
+
 export interface InspectedActorEvent extends BaseInspectionEventProperties {
   type: '@xstate.actor';
 }

packages/core/src/types.ts

@@ -1905,6 +1905,7 @@ export type Observer<T> = {
   next?: (value: T) => void;
   error?: (err: unknown) => void;
   complete?: () => void;
+  id?: string;
 };
 
 export interface Subscription {

packages/core/src/utils.ts

@@ -234,7 +234,8 @@ export function normalizeTarget<
 export function toObserver<T>(
   nextHandler?: Observer<T> | ((value: T) => void),
   errorHandler?: (error: any) => void,
-  completionHandler?: () => void
+  completionHandler?: () => void,
+  observerId?: string
 ): Observer<T> {
   const isObserver = typeof nextHandler === 'object';
   const self = isObserver ? nextHandler : undefined;
@@ -244,7 +245,8 @@ export function toObserver<T>(
     error: (isObserver ? nextHandler.error : errorHandler)?.bind(self),
     complete: (isObserver ? nextHandler.complete : completionHandler)?.bind(
       self
-    )
+    ),
+    id: observerId
   };
 }
 

packages/core/test/inspect.test.ts

@@ -11,7 +11,10 @@ import {
   raise,
   setup
 } from '../src';
-import { InspectedActionEvent } from '../src/inspection';
+import {
+  InspectedActionEvent,
+  InspectedSubscriptionEvent
+} from '../src/inspection';
 
 function simplifyEvents(
   inspectionEvents: InspectionEvent[],
@@ -65,6 +68,14 @@ function simplifyEvents(
           action: inspectionEvent.action
         };
       }
+
+      if (inspectionEvent.type === '@xstate.subscription') {
+        return {
+          type: inspectionEvent.type,
+          actorSystemId: inspectionEvent.actorRef?.systemId,
+          subscriptionId: inspectionEvent.subscriptionId
+        };
+      }
     });
 }
 
@@ -1044,6 +1055,55 @@ describe('inspect', () => {
 `);
   });
 
+  it('should inspect subscriptions', () => {
+    const events: InspectedSubscriptionEvent[] = [];
+
+    const machine = setup({}).createMachine({});
+
+    const actor = createActor(machine, {
+      inspect: (ev) => {
+        if (ev.type === '@xstate.subscription') {
+          events.push(ev);
+        }
+      },
+      systemId: 'actor1' // making sure that the systemId is included in the event
+    });
+
+    actor.start();
+    actor.subscribe(
+      (snapshot) => {
+        console.log('sub1', snapshot);
+      },
+      undefined,
+      undefined,
+      'sub1'
+    );
+    actor.subscribe(
+      (snapshot) => {
+        console.log('sub2', snapshot);
+      },
+      undefined,
+      undefined,
+      'sub2'
+    );
+
+    expect(simplifyEvents(events, (ev) => ev.type === '@xstate.subscription'))
+      .toMatchInlineSnapshot(`
+      [
+        {
+          "actorSystemId": "actor1",
+          "subscriptionId": "sub1",
+          "type": "@xstate.subscription",
+        },
+        {
+          "actorSystemId": "actor1",
+          "subscriptionId": "sub2",
+          "type": "@xstate.subscription",
+        },
+      ]
+    `);
+  });
+
   it('@xstate.microstep inspection events should report no transitions if an unknown event was sent', () => {
     const machine = createMachine({});
     expect.assertions(1);