[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
  };