[core] Add children to Snapshot interface for all logic types

.changeset/chilly-carpets-draw.md

@@ -0,0 +1,5 @@
+---
+'xstate': patch
+---
+
+Add `children` to `Snapshot` interface

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/State.ts

@@ -458,7 +458,7 @@ export function getPersistedSnapshot<
   const persisted = {
     ...jsonValues,
     context: persistContext(context) as any,
-    children: childrenJson
+    children: childrenJson as Record<string, AnyActorRef | undefined>
   };
 
   return persisted;

packages/core/src/actions/stopChild.ts

@@ -67,15 +67,15 @@ function executeStop(
   // this allows us to prevent an actor from being started if it gets stopped within the same macrostep
   // this can happen, for example, when the invoking state is being exited immediately by an always transition
   if (actorRef._processingStatus !== ProcessingStatus.Running) {
-    actorScope.stopChild(actorRef);
+    actorScope.stopChild?.(actorRef);
     return;
   }
   // stopping a child enqueues a stop event in the child actor's mailbox
   // we need for all of the already enqueued events to be processed before we stop the child
   // the parent itself might want to send some events to a child (for example from exit actions on the invoking state)
   // and we don't want to ignore those events
   actorScope.defer(() => {
-    actorScope.stopChild(actorRef);
+    actorScope.stopChild?.(actorRef);
   });
 }
 

packages/core/src/actors/callback.ts

@@ -4,6 +4,7 @@ import {
   ActorLogic,
   ActorRefFromLogic,
   AnyActorRef,
+  AnyActorScope,
   AnyEventObject,
   EventObject,
   NonReducibleUnknown,
@@ -92,6 +93,7 @@ type InvokeCallback<
   self,
   sendBack,
   receive,
+  spawnChild,
   emit
 }: {
   /**
@@ -111,6 +113,7 @@ type InvokeCallback<
    * listener is then called whenever events are received by the callback actor
    */
   receive: Receiver<TEvent>;
+  spawnChild: AnyActorScope['spawnChild'];
   emit: (emitted: TEmitted) => void;
 }) => (() => void) | void;
 
@@ -191,7 +194,7 @@ export function fromCallback<
   const logic: CallbackActorLogic<TEvent, TInput, TEmitted> = {
     config: invokeCallback,
     start: (state, actorScope) => {
-      const { self, system, emit } = actorScope;
+      const { self, system, emit, spawnChild } = actorScope;
 
       const callbackState: CallbackInstanceState<TEvent> = {
         receivers: undefined,
@@ -216,6 +219,7 @@ export function fromCallback<
           callbackState.receivers ??= new Set();
           callbackState.receivers.add(listener);
         },
+        spawnChild,
         emit
       });
     },
@@ -244,7 +248,9 @@ export function fromCallback<
         status: 'active',
         output: undefined,
         error: undefined,
-        input
+        input,
+        context: undefined,
+        children: {}
       };
     },
     getPersistedSnapshot: (snapshot) => snapshot,

packages/core/src/actors/observable.ts

@@ -2,6 +2,8 @@ import { XSTATE_STOP } from '../constants';
 import { AnyActorSystem } from '../system.ts';
 import {
   ActorLogic,
+  ActorRefFrom,
+  AnyActorScope,
   ActorRefFromLogic,
   EventObject,
   NonReducibleUnknown,
@@ -128,6 +130,7 @@ export function fromObservable<
     input: TInput;
     system: AnyActorSystem;
     self: ObservableActorRef<TContext>;
+    spawnChild: AnyActorScope['spawnChild'];
     emit: (emitted: TEmitted) => void;
   }) => Subscribable<TContext>
 ): ObservableActorLogic<TContext, TInput, TEmitted> {
@@ -181,10 +184,11 @@ export function fromObservable<
         error: undefined,
         context: undefined,
         input,
-        _subscription: undefined
+        _subscription: undefined,
+        children: {}
       };
     },
-    start: (state, { self, system, emit }) => {
+    start: (state, { self, system, spawnChild, emit }) => {
       if (state.status === 'done') {
         // Do not restart a completed observable
         return;
@@ -193,6 +197,7 @@ export function fromObservable<
         input: state.input!,
         system,
         self,
+        spawnChild,
         emit
       }).subscribe({
         next: (value) => {
@@ -333,7 +338,8 @@ export function fromEventObservable<
         error: undefined,
         context: undefined,
         input,
-        _subscription: undefined
+        _subscription: undefined,
+        children: {}
       };
     },
     start: (state, { self, system, emit }) => {

packages/core/src/actors/promise.ts

@@ -2,6 +2,8 @@ import { XSTATE_STOP } from '../constants.ts';
 import { AnyActorSystem } from '../system.ts';
 import {
   ActorLogic,
+  ActorRefFrom,
+  AnyActorScope,
   ActorRefFromLogic,
   AnyActorRef,
   EventObject,
@@ -135,6 +137,7 @@ export function fromPromise<
     system: AnyActorSystem;
     /** The parent actor of the promise actor */
     self: PromiseActorRef<TOutput>;
+    spawnChild: AnyActorScope['spawnChild'];
     signal: AbortSignal;
     emit: (emitted: TEmitted) => void;
   }) => PromiseLike<TOutput>
@@ -175,7 +178,7 @@ export function fromPromise<
           return state;
       }
     },
-    start: (state, { self, system, emit }) => {
+    start: (state, { self, system, spawnChild, emit }) => {
       // TODO: determine how to allow customizing this so that promises
       // can be restarted if necessary
       if (state.status !== 'active') {
@@ -189,6 +192,7 @@ export function fromPromise<
           system,
           self,
           signal: controller.signal,
+          spawnChild,
           emit
         })
       );
@@ -221,7 +225,9 @@ export function fromPromise<
         status: 'active',
         output: undefined,
         error: undefined,
-        input
+        input,
+        context: undefined,
+        children: {}
       };
     },
     getPersistedSnapshot: (snapshot) => snapshot,

packages/core/src/actors/transition.ts

@@ -8,9 +8,7 @@ import {
   Snapshot
 } from '../types.ts';
 
-export type TransitionSnapshot<TContext> = Snapshot<undefined> & {
-  context: TContext;
-};
+export type TransitionSnapshot<TContext> = Snapshot<undefined, TContext>;
 
 export type TransitionActorLogic<
   TContext,
@@ -211,7 +209,8 @@ export function fromTransition<
         context:
           typeof initialContext === 'function'
             ? (initialContext as any)({ input })
-            : initialContext
+            : initialContext,
+        children: {}
       };
     },
     getPersistedSnapshot: (snapshot) => snapshot,

packages/core/src/createActor.ts

@@ -12,6 +12,7 @@ import { symbolObservable } from './symbolObservable.ts';
 import { AnyActorSystem, Clock, createSystem } from './system.ts';
 
 import type {
+  ActorRefFrom,
   ActorScope,
   AnyActorLogic,
   AnyActorRef,
@@ -169,6 +170,21 @@ export class Actor<TLogic extends AnyActorLogic>
         this._deferred.push(fn);
       },
       system: this.system,
+      spawnChild: <T extends AnyActorLogic>(
+        logic: T,
+        actorOptions?: ActorOptions<T>
+      ) => {
+        const actor = createActor(logic, {
+          parent: this,
+          ...actorOptions
+        });
+
+        if (this._processingStatus === ProcessingStatus.Running) {
+          actor.start();
+        }
+
+        return actor as ActorRefFrom<T>;
+      },
       stopChild: (child) => {
         if (child._parent !== this) {
           throw new Error(

packages/core/src/getNextSnapshot.ts

@@ -27,7 +27,12 @@ export function createInertActorScope<T extends AnyActorLogic>(
     sessionId: '',
     stopChild: () => {},
     system: self.system,
-    emit: () => {}
+    emit: () => {},
+    spawnChild(logic) {
+      const child = createActor(logic) as any;
+
+      return child;
+    }
   };
 
   return inertActorScope;

packages/core/src/types.ts

@@ -2148,7 +2148,11 @@ export interface ActorScope<
   defer: (fn: () => void) => void;
   emit: (event: TEmitted) => void;
   system: TSystem;
-  stopChild: (child: AnyActorRef) => void;
+  stopChild?: (child: AnyActorRef) => void;
+  spawnChild?: <T extends AnyActorLogic>(
+    logic: T,
+    actorOptions?: ActorOptions<T>
+  ) => ActorRefFrom<T>;
 }
 
 export type AnyActorScope = ActorScope<
@@ -2160,26 +2164,34 @@ export type AnyActorScope = ActorScope<
 
 export type SnapshotStatus = 'active' | 'done' | 'error' | 'stopped';
 
-export type Snapshot<TOutput> =
+export type Snapshot<TOutput, TContext = unknown> =
   | {
       status: 'active';
       output: undefined;
       error: undefined;
+      context: TContext;
+      children?: Record<string, AnyActorRef | undefined>;
     }
   | {
       status: 'done';
       output: TOutput;
       error: undefined;
+      context: TContext;
+      children?: Record<string, AnyActorRef | undefined>;
     }
   | {
       status: 'error';
       output: undefined;
       error: unknown;
+      context: TContext;
+      children?: Record<string, AnyActorRef | undefined>;
     }
   | {
       status: 'stopped';
       output: undefined;
       error: undefined;
+      context: TContext;
+      children?: Record<string, AnyActorRef | undefined>;
     };
 
 /**

packages/core/test/actor.test.ts

@@ -1158,7 +1158,9 @@ describe('actors', () => {
         getInitialSnapshot: () => ({
           status: 'active',
           output: undefined,
-          error: undefined
+          error: undefined,
+          context: undefined,
+          children: {}
         }),
         getPersistedSnapshot: (s) => s
       };