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();
+```

.claude/settings.local.json

@@ -0,0 +1,5 @@
+{
+  "permissions": {
+    "allow": ["Bash(gh pr view:*)", "Bash(gh pr diff:*)"]
+  }
+}

README.md

@@ -53,7 +53,6 @@ Special thanks to the sponsors who support this open-source project:
   </picture>
 </a>
 
-
 ## Templates
 
 Get started by forking one of these templates on CodeSandbox:
@@ -551,7 +550,6 @@ actor.send({ type: 'PREVIOUS' });
 </tbody>
 </table>
 
-
 ## SemVer Policy
 
 We understand the importance of the public contract and do not intend to release any breaking changes to the **runtime** API in a minor or patch release. We consider this with any changes we make to the XState libraries and aim to minimize their effects on existing users.

packages/core/src/index.ts

@@ -26,7 +26,7 @@ export { isMachineSnapshot, type MachineSnapshot } from './State.ts';
 export { StateMachine } from './StateMachine.ts';
 export { StateNode } from './StateNode.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

@@ -4,6 +4,7 @@ import {
   ActorSystemInfo,
   AnyActorRef,
   Observer,
+  Subscribable,
   HomomorphicOmit,
   EventObject,
   Subscription
@@ -36,6 +37,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(
@@ -45,7 +51,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 */
@@ -73,13 +80,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;
@@ -100,6 +103,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;
 
@@ -120,11 +124,26 @@ 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 }
+        } = system.getSnapshot();
+        updateSnapshot({
+          _scheduledEvents: {
+            ..._scheduledEvents
+          },
+          actors: { ...snapshot.actors }
+        });
 
         system._relay(source, target, event);
       }, delay);
@@ -136,7 +155,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);
@@ -167,14 +195,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) => {
@@ -184,6 +234,14 @@ 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) => {
@@ -192,6 +250,27 @@ export function createSystem<T extends ActorSystemInfo>(
     getAll: () => {
       return Object.fromEntries(keyedActors.entries()) as Partial<T['actors']>;
     },
+    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) {
@@ -202,6 +281,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);
@@ -227,15 +316,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

@@ -9,7 +9,7 @@ import type { Actor, ProcessingStatus } from './createActor.ts';
 import { Guard, GuardPredicate, UnknownGuard } from './guards.ts';
 import { InspectionEvent } from './inspection.ts';
 import { Spawner } from './spawn.ts';
-import { AnyActorSystem, Clock } from './system.ts';
+import { ActorSystem, AnyActorSystem, Clock } from './system.ts';
 
 // this is needed to make JSDoc `@link` work properly
 import type { SimulatedClock } from './SimulatedClock.ts';
@@ -2319,7 +2319,9 @@ export type SnapshotFrom<T> =
                 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

@@ -624,4 +624,65 @@ describe('system', () => {
 
     expect(root.system.get('subchild')).toBeDefined();
   });
+
+  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']
+    ]);
+  });
 });

packages/xstate-react/CHANGELOG.md

@@ -419,7 +419,6 @@
 ### Minor Changes
 
 - [#3778](https://github.com/statelyai/xstate/pull/3778) [`f12248b23`](https://github.com/statelyai/xstate/commit/f12248b2379e4e554d69a238019216feea5211f6) Thanks [@davidkpiano](https://github.com/davidkpiano)! - The `createActorContext(...)` helper has been introduced to make global actors easier to use with React. It outputs a React Context object with the following properties:
-
   - `.Provider` - The React Context provider
   - `.useActor(...)` - A hook that can be used to get the current state and send events to the actor
   - `.useSelector(...)` - A hook that can be used to select some derived state from the actor's state