support for system as actor

.changeset/tasty-baboons-dance.md

@@ -0,0 +1,30 @@
+---
+'xstate': minor
+---
+
+added support for `actor.system.subscribe` to subscribe to registration and unregistration events within an actor's system.
+`actor.system.subscribe` returns a `Subscription` object you can `.unsubscribe` to at any time.
+
+ex:
+
+```js
+// observer object
+const subscription = actor.system.subscribe({
+  next: (event) => console.log(event),
+  error: (err) => console.error(err),
+  complete: () => console.log('done')
+});
+
+// observer parameters
+const subscription = actor.system.subscribe(
+  (event) => console.log(event),
+  (err) => console.error(err),
+  () => console.log('done')
+);
+
+// callback function
+const subscription = actor.system.subscribe((event) => console.log(event));
+
+// unsubscribe
+subscription.unsubscribe();
+```

packages/core/src/index.ts

@@ -20,7 +20,10 @@ export type {
   InspectedActorEvent,
   InspectedEventEvent,
   InspectedSnapshotEvent,
-  InspectionEvent
+  InspectionEvent,
+  RegisteredActorEvent,
+  UnregisteredActorEvent,
+  RegistrationEvent
 } from './system.ts';
 export { toPromise } from './toPromise.ts';
 export {

packages/core/src/system.ts

@@ -1,12 +1,16 @@
+import { ProcessingStatus } from './createActor.ts';
+import { reportUnhandledError } from './reportUnhandledError.ts';
 import {
   AnyEventObject,
   ActorSystemInfo,
   AnyActorRef,
   Observer,
   Snapshot,
+  Subscription,
   HomomorphicOmit,
   EventObject
 } from './types.ts';
+import { toObserver } from './utils.ts';
 
 export interface ScheduledEvent {
   id: string;
@@ -61,6 +65,43 @@ export interface ActorSystem<T extends ActorSystemInfo> {
    */
   _set: <K extends keyof T['actors']>(key: K, actorRef: T['actors'][K]) => void;
   get: <K extends keyof T['actors']>(key: K) => T['actors'][K] | undefined;
+  subscribe: {
+    (
+      observer: Observer<
+        RegistrationEvent<
+          T['actors'][keyof T['actors']],
+          keyof T['actors'] & string
+        >
+      >
+    ): Subscription;
+    (
+      nextListener?: (
+        event: RegistrationEvent<
+          T['actors'][keyof T['actors']],
+          keyof T['actors'] & string
+        >
+      ) => void,
+      errorListener?: (error: any) => void,
+      completeListener?: () => void
+    ): Subscription;
+    (
+      nextListenerOrObserver?:
+        | ((
+            event: RegistrationEvent<
+              T['actors'][keyof T['actors']],
+              keyof T['actors'] & string
+            >
+          ) => void)
+        | Observer<
+            RegistrationEvent<
+              T['actors'][keyof T['actors']],
+              keyof T['actors'] & string
+            >
+          >,
+      errorListener?: (error: any) => void,
+      completeListener?: () => void
+    ): Subscription;
+  };
   inspect: (observer: Observer<InspectionEvent>) => void;
   /**
    * @internal
@@ -102,7 +143,10 @@ export function createSystem<T extends ActorSystemInfo>(
   const children = new Map<string, AnyActorRef>();
   const keyedActors = new Map<keyof T['actors'], AnyActorRef | undefined>();
   const reverseKeyedActors = new WeakMap<AnyActorRef, keyof T['actors']>();
-  const observers = new Set<Observer<InspectionEvent>>();
+  const inspectionObservers = new Set<Observer<InspectionEvent>>();
+  const registrationObservers = new Set<
+    Observer<RegistrationEvent<T['actors'][keyof T['actors']]>>
+  >();
   const timerMap: { [id: ScheduledEventId]: number } = {};
   const clock = options.clock;
 
@@ -164,6 +208,17 @@ export function createSystem<T extends ActorSystemInfo>(
     _bookId: () => `x:${idCounter++}`,
     _register: (sessionId, actorRef) => {
       children.set(sessionId, actorRef);
+      const systemId = reverseKeyedActors.get(actorRef);
+      if (systemId !== undefined) {
+        const event = {
+          type: `@xstate.actor.register`,
+          systemId: systemId as string,
+          actorRef: actorRef as T['actors'][keyof T['actors']]
+        } as const;
+        registrationObservers.forEach((listener) => {
+          listener.next?.(event);
+        });
+      }
       return sessionId;
     },
     _unregister: (actorRef) => {
@@ -173,11 +228,54 @@ export function createSystem<T extends ActorSystemInfo>(
       if (systemId !== undefined) {
         keyedActors.delete(systemId);
         reverseKeyedActors.delete(actorRef);
+        const event = {
+          type: `@xstate.actor.unregister`,
+          systemId: systemId as string,
+          actorRef: actorRef as T['actors'][keyof T['actors']]
+        } as const;
+        registrationObservers.forEach((listener) => {
+          listener.next?.(event);
+        });
       }
     },
     get: (systemId) => {
       return keyedActors.get(systemId) as T['actors'][any];
     },
+    subscribe: (
+      nextListenerOrObserver?:
+        | ((event: RegistrationEvent<T['actors'][keyof T['actors']]>) => void)
+        | Observer<RegistrationEvent<T['actors'][keyof T['actors']]>>,
+      errorListener?: (error: any) => void,
+      completeListener?: () => void
+    ) => {
+      const observer = toObserver(
+        nextListenerOrObserver,
+        errorListener,
+        completeListener
+      );
+
+      if (rootActor._processingStatus !== ProcessingStatus.Stopped) {
+        registrationObservers.add(observer);
+      } else {
+        const snapshot = rootActor.getSnapshot();
+        switch (snapshot.status) {
+          case 'done':
+            try {
+              observer.complete?.();
+            } catch (err) {
+              reportUnhandledError(err);
+            }
+            break;
+          // can this error?
+        }
+      }
+
+      return {
+        unsubscribe: () => {
+          registrationObservers.delete(observer);
+        }
+      };
+    },
     _set: (systemId, actorRef) => {
       const existing = keyedActors.get(systemId);
       if (existing && existing !== actorRef) {
@@ -190,14 +288,16 @@ export function createSystem<T extends ActorSystemInfo>(
       reverseKeyedActors.set(actorRef, systemId);
     },
     inspect: (observer) => {
-      observers.add(observer);
+      inspectionObservers.add(observer);
     },
     _sendInspectionEvent: (event) => {
       const resolvedInspectionEvent: InspectionEvent = {
         ...event,
         rootId: rootActor.sessionId
       };
-      observers.forEach((observer) => observer.next?.(resolvedInspectionEvent));
+      inspectionObservers.forEach(
+        (observer) => observer.next?.(resolvedInspectionEvent)
+      );
     },
     _relay: (source, target, event) => {
       system._sendInspectionEvent({
@@ -262,3 +362,28 @@ export type InspectionEvent =
   | InspectedSnapshotEvent
   | InspectedEventEvent
   | InspectedActorEvent;
+
+export interface RegisteredActorEvent<
+  TActorRef extends AnyActorRef,
+  TSystemId extends string = string
+> {
+  type: `@xstate.actor.register`;
+  systemId: TSystemId;
+  actorRef: TActorRef;
+}
+
+export interface UnregisteredActorEvent<
+  TActorRef extends AnyActorRef,
+  TSystemId extends string = string
+> {
+  type: `@xstate.actor.unregister`;
+  systemId: TSystemId;
+  actorRef: TActorRef;
+}
+
+export type RegistrationEvent<
+  TActorRef extends AnyActorRef = AnyActorRef,
+  TSystemId extends string = string
+> =
+  | RegisteredActorEvent<TActorRef, TSystemId>
+  | UnregisteredActorEvent<TActorRef, TSystemId>;

packages/core/test/system.test.ts

@@ -535,4 +535,118 @@ describe('system', () => {
 
     expect(spy).toHaveBeenCalledTimes(1);
   });
+
+  it('should allow subscribing to system registration events', () => {
+    const aSystemId = 'a_child';
+    const bSystemId = 'b_child';
+    const machine = createMachine({
+      initial: 'a',
+      states: {
+        a: {
+          invoke: {
+            src: createMachine({}),
+            systemId: aSystemId
+          },
+          on: {
+            to_b: 'b'
+          }
+        },
+        b: {
+          invoke: {
+            src: createMachine({}),
+            systemId: bSystemId
+          },
+          on: {
+            to_a: 'a'
+          }
+        }
+      }
+    });
+
+    const actorRef = createActor(machine).start();
+
+    const events: string[] = [];
+
+    actorRef.system.subscribe((event) => {
+      events.push(`${event.type}.${event.systemId}`);
+    });
+
+    actorRef.send({ type: 'to_b' });
+    expect(events).toEqual([
+      `@xstate.actor.unregister.${aSystemId}`,
+      `@xstate.actor.register.${bSystemId}`
+    ]);
+    actorRef.send({ type: 'to_a' });
+    expect(events).toEqual([
+      `@xstate.actor.unregister.${aSystemId}`,
+      `@xstate.actor.register.${bSystemId}`,
+      `@xstate.actor.unregister.${bSystemId}`,
+      `@xstate.actor.register.${aSystemId}`
+    ]);
+  });
+
+  it('should allow unsubscribing from a system registration subscription', () => {
+    const aSystemId = 'a_child';
+    const bSystemId = 'b_child';
+    const machine = createMachine({
+      initial: 'a',
+      states: {
+        a: {
+          invoke: {
+            src: createMachine({}),
+            systemId: aSystemId
+          },
+          on: {
+            to_b: 'b'
+          }
+        },
+        b: {
+          invoke: {
+            src: createMachine({}),
+            systemId: bSystemId
+          },
+          on: {
+            to_a: 'a'
+          }
+        }
+      }
+    });
+
+    const actorRef = createActor(machine).start();
+
+    const events: string[] = [];
+    const unsubscribedEvents: string[] = [];
+
+    const subscription = actorRef.system.subscribe((event) => {
+      events.push(`${event.type}.${event.systemId}`);
+    });
+
+    actorRef.system.subscribe((event) => {
+      unsubscribedEvents.push(`${event.type}.${event.systemId}`);
+    });
+
+    actorRef.send({ type: 'to_b' });
+    expect(events).toEqual([
+      `@xstate.actor.unregister.${aSystemId}`,
+      `@xstate.actor.register.${bSystemId}`
+    ]);
+    expect(unsubscribedEvents).toEqual([
+      `@xstate.actor.unregister.${aSystemId}`,
+      `@xstate.actor.register.${bSystemId}`
+    ]);
+
+    subscription.unsubscribe();
+    actorRef.send({ type: 'to_a' });
+
+    expect(events).toEqual([
+      `@xstate.actor.unregister.${aSystemId}`,
+      `@xstate.actor.register.${bSystemId}`
+    ]);
+    expect(unsubscribedEvents).toEqual([
+      `@xstate.actor.unregister.${aSystemId}`,
+      `@xstate.actor.register.${bSystemId}`,
+      `@xstate.actor.unregister.${bSystemId}`,
+      `@xstate.actor.register.${aSystemId}`
+    ]);
+  });
 });