[v5] System (receptionist)

.changeset/cool-grapes-suffer.md

@@ -0,0 +1,49 @@
+---
+'xstate': major
+---
+
+Actors are now always part of a "system", which is a collection of actors that can communicate with each other. Systems are implicitly created, and can be used to get and set references to any actor in the system via the `key` prop:
+
+```js
+const machine = createMachine({
+  // ...
+  invoke: {
+    src: emailMachine,
+    // Registers `emailMachine` as `emailer` on the system
+    key: 'emailer'
+  }
+});
+```
+
+```js
+const machine = createMachine({
+  // ...
+  entry: assign({
+    emailer: (ctx, ev, { spawn }) => spawn(emailMachine, { key: 'emailer' })
+  })
+});
+```
+
+Any invoked/spawned actor that is part of a system will be able to reference that actor:
+
+```js
+const anotherMachine = createMachine({
+  // ...
+  entry: sendTo(
+    (ctx, ev, { system }) => {
+      return system.get('emailer');
+    },
+    { type: 'SEND_EMAIL', subject: 'Hello', body: 'World' }
+  )
+});
+```
+
+Each top-level `interpret(...)` call creates a separate implicit system. In this example example, `actor1` and `actor2` are part of different systems and are unrelated:
+
+```js
+// Implicit system
+const actor1 = interpret(machine).start();
+
+// Another implicit system
+const actor2 = interpret(machine).start();
+```

packages/core/src/StateMachine.ts

@@ -40,6 +40,7 @@ import type {
   StateMachineDefinition,
   StateValue,
   TransitionDefinition,
+  AnyActorContext,
   PersistedMachineState
 } from './types.js';
 import {
@@ -266,7 +267,7 @@ export class StateMachine<
   public microstep(
     state: State<TContext, TEvent, TResolvedTypesMeta> = this.initialState,
     event: TEvent | SCXML.Event<TEvent>,
-    actorCtx?: ActorContext<any, any> | undefined
+    actorCtx?: AnyActorContext | undefined
   ): Array<State<TContext, TEvent, TResolvedTypesMeta>> {
     const scxmlEvent = toSCXMLEvent(event);
 
@@ -287,7 +288,7 @@ export class StateMachine<
    * This "pre-initial" state is provided to initial actions executed in the initial state.
    */
   private getPreInitialState(
-    actorCtx: ActorContext<any, any> | undefined,
+    actorCtx: AnyActorContext | undefined,
     input: any
   ): State<TContext, TEvent, TResolvedTypesMeta> {
     const [context, actions] = this.getContextAndActions(actorCtx, input);

packages/core/src/StateNode.ts

@@ -259,7 +259,7 @@ export class StateNode<
         const generatedId = createInvokeId(this.id, i);
         const invokeConfig = toInvokeConfig(invocable, generatedId);
         const resolvedId = invokeConfig.id || generatedId;
-        const { src } = invokeConfig;
+        const { src, key } = invokeConfig;
 
         const resolvedSrc = isString(src)
           ? src
@@ -284,6 +284,7 @@ export class StateNode<
           ...invokeConfig,
           src: resolvedSrc,
           id: resolvedId,
+          key,
           toJSON() {
             const { onDone, onError, ...invokeDefValues } = invokeConfig;
             return {

packages/core/src/actions.ts

@@ -90,21 +90,22 @@ export function toActionObject<
   if (typeof action === 'function') {
     const type = 'xstate.function';
     return createDynamicAction({ type, params: {} }, (_event, { state }) => {
-      const a: BaseActionObject = {
+      const actionObject: BaseActionObject = {
         type,
         params: {
           function: action
         },
         execute: (_actorCtx) => {
           return action(state.context as TContext, _event.data as TEvent, {
-            action: a,
+            action: actionObject,
             _event: _event as SCXML.Event<TEvent>,
-            state: state as AnyState
+            state: state as AnyState,
+            system: _actorCtx.system
           });
         }
       };
 
-      return [state, a];
+      return [state, actionObject];
     });
   }
 

packages/core/src/actions/invoke.ts

@@ -59,6 +59,7 @@ export function invoke<
             id,
             src,
             parent: actorContext?.self,
+            key: invokeDef.key,
             input:
               typeof input === 'function'
                 ? input(state.context, _event.data as any)
@@ -84,7 +85,7 @@ export function invoke<
       });
 
       resolvedInvokeAction.execute = (actorCtx) => {
-        const interpreter = actorCtx.self as AnyInterpreter;
+        const parent = actorCtx.self as AnyInterpreter;
         const { id, ref } = resolvedInvokeAction.params;
         if (!ref) {
           if (!IS_PRODUCTION) {
@@ -102,7 +103,7 @@ export function invoke<
           try {
             actorRef.start?.();
           } catch (err) {
-            interpreter.send(error(id, err));
+            parent.send(error(id, err));
             return;
           }
         });

packages/core/src/actions/stop.ts

@@ -2,8 +2,8 @@ import { createDynamicAction } from '../../actions/dynamicAction.js';
 import { stop as stopActionType } from '../actionTypes.js';
 import { ActorStatus } from '../interpreter.js';
 import {
-  ActorContext,
   ActorRef,
+  AnyActorContext,
   BaseDynamicActionObject,
   DynamicStopActionObject,
   EventObject,
@@ -58,7 +58,7 @@ export function stop<
         {
           type: 'xstate.stop',
           params: { actor: actorRef },
-          execute: (actorCtx: ActorContext<any, any>) => {
+          execute: (actorCtx: AnyActorContext) => {
             if (!actorRef) {
               return;
             }

packages/core/src/actors/reducer.ts

@@ -1,4 +1,9 @@
-import { ActorBehavior, ActorContext, EventObject } from '../types';
+import {
+  ActorBehavior,
+  ActorContext,
+  ActorSystem,
+  EventObject
+} from '../types';
 import { isSCXMLEvent } from '../utils';
 
 /**
@@ -9,11 +14,15 @@ import { isSCXMLEvent } from '../utils';
  * @returns An actor behavior
  */
 
-export function fromReducer<TState, TEvent extends EventObject>(
+export function fromReducer<
+  TState,
+  TEvent extends EventObject,
+  TSystem extends ActorSystem<any>
+>(
   transition: (
     state: TState,
     event: TEvent,
-    actorContext: ActorContext<TEvent, TState>
+    actorContext: ActorContext<TEvent, TState, TSystem>
   ) => TState,
   initialState: TState | (({ input }: { input: any }) => TState) // TODO: type
 ): ActorBehavior<TEvent, TState, TState> {

packages/core/src/interpreter.ts

@@ -6,14 +6,15 @@ import type {
   InterpreterFrom,
   PersistedStateFrom,
   SnapshotFrom,
+  ActorSystem,
   AnyActorBehavior,
   RaiseActionObject
 } from './types.js';
 import { stopSignalType } from './actors/index.js';
 import { devToolsAdapter } from './dev/index.js';
 import { IS_PRODUCTION } from './environment.js';
 import { Mailbox } from './Mailbox.js';
-import { registry } from './registry.js';
+import { createSystem } from './system.js';
 import { AreAllImplementationsAssumedToBeProvided } from './typegenTypes.js';
 import {
   ActorRef,
@@ -107,13 +108,15 @@ export class Interpreter<
   // Actor Ref
   public _parent?: ActorRef<any>;
   public ref: ActorRef<TEvent>;
-  private _actorContext: ActorContext<TEvent, SnapshotFrom<TBehavior>>;
+  // TODO: add typings for system
+  private _actorContext: ActorContext<TEvent, SnapshotFrom<TBehavior>, any>;
 
   /**
    * The globally unique process ID for this invocation.
    */
   public sessionId: string;
 
+  public system: ActorSystem<any>;
   private _doneEvent?: DoneEvent;
 
   public src?: string;
@@ -133,11 +136,16 @@ export class Interpreter<
       ...options
     };
 
-    const { clock, logger, parent, id } = resolvedOptions;
+    const { clock, logger, parent, id, key } = resolvedOptions;
     const self = this;
 
-    // TODO: this should come from a "system"
-    this.sessionId = registry.bookId();
+    this.system = parent?.system ?? createSystem();
+
+    if (key) {
+      this.system.set(key, this);
+    }
+
+    this.sessionId = this.system._register(this);
     this.id = id ?? this.sessionId;
     this.logger = logger;
     this.clock = clock;
@@ -152,7 +160,8 @@ export class Interpreter<
       logger: this.logger,
       defer: (fn) => {
         this._deferred.push(fn);
-      }
+      },
+      system: this.system
     };
 
     // Ensure that the send method is bound to this interpreter instance
@@ -277,7 +286,6 @@ export class Interpreter<
       return this;
     }
 
-    registry.register(this.sessionId, this.ref);
     this.status = ActorStatus.Running;
 
     if (this.behavior.start) {
@@ -368,7 +376,7 @@ export class Interpreter<
     this.mailbox = new Mailbox(this._process.bind(this));
 
     this.status = ActorStatus.Stopped;
-    registry.free(this.sessionId);
+    this.system._unregister(this);
 
     return this;
   }

packages/core/src/stateUtils.ts

@@ -45,7 +45,7 @@ import { evaluateGuard, toGuardDefinition } from './guards.js';
 import type { StateNode } from './StateNode.js';
 import { isDynamicAction } from '../actions/dynamicAction.js';
 import {
-  ActorContext,
+  AnyActorContext,
   AnyEventObject,
   AnyHistoryValue,
   AnyState,
@@ -1038,7 +1038,7 @@ export function microstep<
 >(
   transitions: Array<TransitionDefinition<TContext, TEvent>>,
   currentState: State<TContext, TEvent, any>,
-  actorCtx: ActorContext<any, any> | undefined,
+  actorCtx: AnyActorContext | undefined,
   scxmlEvent: SCXML.Event<TEvent>
 ): State<TContext, TEvent, any> {
   const { machine } = currentState;
@@ -1127,7 +1127,7 @@ function microstepProcedure(
   currentState: AnyState,
   mutConfiguration: Set<AnyStateNode>,
   scxmlEvent: SCXML.Event<AnyEventObject>,
-  actorCtx: ActorContext<any, any> | undefined
+  actorCtx: AnyActorContext | undefined
 ): typeof currentState {
   const { machine } = currentState;
   const actions: BaseActionObject[] = [];
@@ -1490,7 +1490,7 @@ export function resolveActionsAndContext<
   actions: BaseActionObject[],
   scxmlEvent: SCXML.Event<TEvent>,
   currentState: State<TContext, TEvent, any>,
-  actorCtx: ActorContext<any, any> | undefined
+  actorCtx: AnyActorContext | undefined
 ): {
   nextState: AnyState;
 } {
@@ -1564,7 +1564,7 @@ export function resolveActionsAndContext<
 export function macrostep<TMachine extends AnyStateMachine>(
   state: StateFromMachine<TMachine>,
   scxmlEvent: SCXML.Event<TMachine['__TEvent']>,
-  actorCtx: ActorContext<any, any> | undefined
+  actorCtx: AnyActorContext | undefined
 ): {
   state: typeof state;
   microstates: Array<typeof state>;
@@ -1650,7 +1650,7 @@ export function macrostep<TMachine extends AnyStateMachine>(
 function stopStep(
   scxmlEvent: SCXML.Event<any>,
   nextState: AnyState,
-  actorCtx: ActorContext<any, any> | undefined
+  actorCtx: AnyActorContext | undefined
 ): AnyState {
   const actions: BaseActionObject[] = [];