support for system as actor

.changeset/cuddly-days-grin.md

@@ -0,0 +1,11 @@
+---
+'@xstate/react': minor
+---
+
+`useSelector` now also allows actor.system to be passed in. This works exactly how normally passing an actor would, any changes that cause the selector to change will be automatically up to date.
+
+ex:
+
+```tsx
+const deepChildC = useSelector(actorRef.system, (system) => system.actors.c);
+```

.changeset/tasty-baboons-dance.md

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

README.md

@@ -181,15 +181,15 @@ Read [📽 the slides](http://slides.com/davidkhourshid/finite-state-machines) (
 
 ## Packages
 
-| Package                                                                                       | Description                                                                  |
-| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| 🤖 `xstate`                                                                                   | Core finite state machine and statecharts library + interpreter              |
-| [📉 `@xstate/graph`](https://github.com/statelyai/xstate/tree/main/packages/xstate-graph)     | Graph traversal and model-based testing utilities using XState               |
-| [⚛️ `@xstate/react`](https://github.com/statelyai/xstate/tree/main/packages/xstate-react)     | React hooks and utilities for using XState in React applications             |
-| [💚 `@xstate/vue`](https://github.com/statelyai/xstate/tree/main/packages/xstate-vue)         | Vue composition functions and utilities for using XState in Vue applications |
-| [🎷 `@xstate/svelte`](https://github.com/statelyai/xstate/tree/main/packages/xstate-svelte)   | Svelte utilities for using XState in Svelte applications                     |
-| [🥏 `@xstate/solid`](https://github.com/statelyai/xstate/tree/main/packages/xstate-solid)     | Solid hooks and utilities for using XState in Solid applications             |
-| [🔍 `@statelyai/inspect`](https://github.com/statelyai/inspect) | Inspection utilities for XState                                              |
+| Package                                                                                     | Description                                                                  |
+| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| 🤖 `xstate`                                                                                 | Core finite state machine and statecharts library + interpreter              |
+| [📉 `@xstate/graph`](https://github.com/statelyai/xstate/tree/main/packages/xstate-graph)   | Graph traversal and model-based testing utilities using XState               |
+| [⚛️ `@xstate/react`](https://github.com/statelyai/xstate/tree/main/packages/xstate-react)   | React hooks and utilities for using XState in React applications             |
+| [💚 `@xstate/vue`](https://github.com/statelyai/xstate/tree/main/packages/xstate-vue)       | Vue composition functions and utilities for using XState in Vue applications |
+| [🎷 `@xstate/svelte`](https://github.com/statelyai/xstate/tree/main/packages/xstate-svelte) | Svelte utilities for using XState in Svelte applications                     |
+| [🥏 `@xstate/solid`](https://github.com/statelyai/xstate/tree/main/packages/xstate-solid)   | Solid hooks and utilities for using XState in Solid applications             |
+| [🔍 `@statelyai/inspect`](https://github.com/statelyai/inspect)                             | Inspection utilities for XState                                              |
 
 ## Finite State Machines
 

packages/core/src/index.ts

@@ -23,7 +23,7 @@ export type {
 export { setup } from './setup.ts';
 export { type Spawner } from './spawn.ts';
 export { getStateNodes } from './stateUtils.ts';
-export type { ActorSystem } from './system.ts';
+export type { ActorSystem, AnyActorSystem, SystemSnapshot } from './system.ts';
 export { toPromise } from './toPromise.ts';
 export * from './types.ts';
 export {

packages/core/src/system.ts

@@ -5,6 +5,7 @@ import {
   AnyActorRef,
   Observer,
   Snapshot,
+  Subscribable,
   HomomorphicOmit,
   EventObject,
   AnyTransitionDefinition,
@@ -38,6 +39,11 @@ interface Scheduler {
   cancelAll(actorRef: AnyActorRef): void;
 }
 
+export interface SystemSnapshot {
+  _scheduledEvents: Record<ScheduledEventId, ScheduledEvent>;
+  actors: Record<string, AnyActorRef>;
+}
+
 type ScheduledEventId = string & { __scheduledEventId: never };
 
 function createScheduledEventId(
@@ -47,7 +53,8 @@ function createScheduledEventId(
   return `${actorRef.sessionId}.${id}` as ScheduledEventId;
 }
 
-export interface ActorSystem<T extends ActorSystemInfo> {
+export interface ActorSystem<T extends ActorSystemInfo>
+  extends Subscribable<SystemSnapshot> {
   /** @internal */
   _bookId: () => string;
   /** @internal */
@@ -74,13 +81,9 @@ export interface ActorSystem<T extends ActorSystemInfo> {
     event: AnyEventObject
   ) => void;
   scheduler: Scheduler;
-  getSnapshot: () => {
-    _scheduledEvents: Record<string, ScheduledEvent>;
-  };
+  getSnapshot: () => SystemSnapshot;
   /** @internal */
-  _snapshot: {
-    _scheduledEvents: Record<ScheduledEventId, ScheduledEvent>;
-  };
+  _snapshot: SystemSnapshot;
   start: () => void;
   _clock: Clock;
   _logger: (...args: any[]) => void;
@@ -101,6 +104,7 @@ export function createSystem<T extends ActorSystemInfo>(
   const keyedActors = new Map<keyof T['actors'], AnyActorRef | undefined>();
   const reverseKeyedActors = new WeakMap<AnyActorRef, keyof T['actors']>();
   const inspectionObservers = new Set<Observer<InspectionEvent>>();
+  const systemObservers = new Set<Observer<SystemSnapshot>>();
   const timerMap: { [id: ScheduledEventId]: number } = {};
   const { clock, logger } = options;
 
@@ -121,11 +125,27 @@ export function createSystem<T extends ActorSystemInfo>(
         startedAt: Date.now()
       };
       const scheduledEventId = createScheduledEventId(source, id);
-      system._snapshot._scheduledEvents[scheduledEventId] = scheduledEvent;
+      const snapshot = system.getSnapshot();
+      updateSnapshot({
+        _scheduledEvents: {
+          ...snapshot._scheduledEvents,
+          [scheduledEventId]: scheduledEvent
+        },
+        actors: { ...snapshot.actors }
+      });
 
       const timeout = clock.setTimeout(() => {
         delete timerMap[scheduledEventId];
-        delete system._snapshot._scheduledEvents[scheduledEventId];
+        const {
+          _scheduledEvents: { [scheduledEventId]: _, ..._scheduledEvents },
+          actors
+        } = system.getSnapshot();
+        updateSnapshot({
+          _scheduledEvents: {
+            ..._scheduledEvents
+          },
+          actors: { ...snapshot.actors }
+        });
 
         system._relay(source, target, event);
       }, delay);
@@ -137,7 +157,16 @@ export function createSystem<T extends ActorSystemInfo>(
       const timeout = timerMap[scheduledEventId];
 
       delete timerMap[scheduledEventId];
-      delete system._snapshot._scheduledEvents[scheduledEventId];
+      const {
+        _scheduledEvents: { [scheduledEventId]: _, ..._scheduledEvents },
+        actors
+      } = system.getSnapshot();
+      updateSnapshot({
+        _scheduledEvents: {
+          ..._scheduledEvents
+        },
+        actors: { ...actors }
+      });
 
       if (timeout !== undefined) {
         clock.clearTimeout(timeout);
@@ -168,14 +197,36 @@ export function createSystem<T extends ActorSystemInfo>(
     );
   };
 
+  function updateSnapshot(snapshot: SystemSnapshot) {
+    system._snapshot = snapshot;
+    systemObservers.forEach((listener) => {
+      listener.next?.(snapshot);
+    });
+  }
+
   const system: ActorSystem<T> = {
     _snapshot: {
       _scheduledEvents:
-        (options?.snapshot && (options.snapshot as any).scheduler) ?? {}
+        (options?.snapshot && (options.snapshot as any).scheduler) ?? {},
+      actors: {}
     },
+
     _bookId: () => `x:${idCounter++}`,
     _register: (sessionId, actorRef) => {
       children.set(sessionId, actorRef);
+      const systemId = reverseKeyedActors.get(actorRef);
+      if (systemId !== undefined) {
+        const currentSnapshot = system.getSnapshot();
+        if (currentSnapshot.actors[systemId as any] !== actorRef) {
+          updateSnapshot({
+            _scheduledEvents: { ...currentSnapshot._scheduledEvents },
+            actors: {
+              ...currentSnapshot.actors,
+              [systemId]: actorRef
+            }
+          });
+        }
+      }
       return sessionId;
     },
     _unregister: (actorRef) => {
@@ -185,11 +236,40 @@ export function createSystem<T extends ActorSystemInfo>(
       if (systemId !== undefined) {
         keyedActors.delete(systemId);
         reverseKeyedActors.delete(actorRef);
+        const {
+          _scheduledEvents,
+          actors: { [systemId]: _, ...actors }
+        } = system.getSnapshot();
+        updateSnapshot({
+          _scheduledEvents: { ..._scheduledEvents },
+          actors
+        });
       }
     },
     get: (systemId) => {
       return keyedActors.get(systemId) as T['actors'][any];
     },
+    subscribe: (
+      nextListenerOrObserver:
+        | ((event: SystemSnapshot) => void)
+        | Observer<SystemSnapshot>,
+      errorListener?: (error: any) => void,
+      completeListener?: () => void
+    ) => {
+      const observer = toObserver(
+        nextListenerOrObserver,
+        errorListener,
+        completeListener
+      );
+
+      systemObservers.add(observer);
+
+      return {
+        unsubscribe: () => {
+          systemObservers.delete(observer);
+        }
+      };
+    },
     _set: (systemId, actorRef) => {
       const existing = keyedActors.get(systemId);
       if (existing && existing !== actorRef) {
@@ -200,6 +280,16 @@ export function createSystem<T extends ActorSystemInfo>(
 
       keyedActors.set(systemId, actorRef);
       reverseKeyedActors.set(actorRef, systemId);
+      const currentSnapshot = system.getSnapshot();
+      if (currentSnapshot.actors[systemId as any] !== actorRef) {
+        updateSnapshot({
+          _scheduledEvents: { ...system._snapshot._scheduledEvents },
+          actors: {
+            ...system._snapshot.actors,
+            [systemId]: actorRef
+          }
+        });
+      }
     },
     inspect: (observerOrFn) => {
       const observer = toObserver(observerOrFn);
@@ -225,15 +315,20 @@ export function createSystem<T extends ActorSystemInfo>(
     scheduler,
     getSnapshot: () => {
       return {
-        _scheduledEvents: { ...system._snapshot._scheduledEvents }
+        _scheduledEvents: { ...system._snapshot._scheduledEvents },
+        actors: { ...system._snapshot.actors }
       };
     },
+
     start: () => {
-      const scheduledEvents = system._snapshot._scheduledEvents;
-      system._snapshot._scheduledEvents = {};
-      for (const scheduledId in scheduledEvents) {
+      const { _scheduledEvents } = system.getSnapshot();
+      updateSnapshot({
+        _scheduledEvents: {},
+        actors: { ...system._snapshot.actors }
+      });
+      for (const scheduledId in _scheduledEvents) {
         const { source, target, event, delay, id } =
-          scheduledEvents[scheduledId as ScheduledEventId];
+          _scheduledEvents[scheduledId as ScheduledEventId];
         scheduler.schedule(source, target, event, delay, id);
       }
     },

packages/core/src/types.ts

@@ -6,7 +6,7 @@ import { PromiseActorLogic } from './actors/promise.ts';
 import { Guard, GuardPredicate, UnknownGuard } from './guards.ts';
 import type { Actor, ProcessingStatus } from './createActor.ts';
 import { Spawner } from './spawn.ts';
-import { AnyActorSystem, Clock } from './system.js';
+import { ActorSystem, AnyActorSystem, Clock } from './system.js';
 import { InspectionEvent } from './inspection.ts';
 
 export type Identity<T> = { [K in keyof T]: T[K] };
@@ -2296,7 +2296,9 @@ export type SnapshotFrom<T> = ReturnTypeOrValue<T> extends infer R
               infer _TSystem
             >
           ? TSnapshot
-          : never
+          : R extends ActorSystem<infer _>
+            ? ReturnType<R['getSnapshot']>
+            : never
   : never;
 
 export type EventFromLogic<TLogic extends AnyActorLogic> =

packages/core/test/system.test.ts

@@ -535,4 +535,65 @@ describe('system', () => {
 
     expect(spy).toHaveBeenCalledTimes(1);
   });
+
+  it('should allow subscriptions to a system', () => {
+    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 keysOverTime: string[][] = [
+      Object.keys(actorRef.system.getSnapshot().actors)
+    ];
+    const unsubscribedKeysOverTime: string[][] = [
+      Object.keys(actorRef.system.getSnapshot().actors)
+    ];
+
+    const subscription = actorRef.system.subscribe((event) => {
+      keysOverTime.push(Object.keys(event.actors));
+    });
+
+    actorRef.system.subscribe((event) => {
+      unsubscribedKeysOverTime.push(Object.keys(event.actors));
+    });
+
+    actorRef.send({ type: 'to_b' });
+    expect(keysOverTime).toEqual([['a_child'], [], ['b_child']]);
+    expect(unsubscribedKeysOverTime).toEqual([['a_child'], [], ['b_child']]);
+
+    subscription.unsubscribe();
+    actorRef.send({ type: 'to_a' });
+
+    expect(keysOverTime).toEqual([['a_child'], [], ['b_child']]);
+    expect(unsubscribedKeysOverTime).toEqual([
+      ['a_child'],
+      [],
+      ['b_child'],
+      [],
+      ['a_child']
+    ]);
+  });
 });