[v5] systemId for spawn() (#3990)

* Add systemId to spawn() options

* Add changeset

.changeset/great-kangaroos-confess.md

@@ -0,0 +1,19 @@
+---
+'xstate': major
+---
+
+You can now add a `systemId` to spawned actors to reference them anywhere in the system.
+
+```ts
+const machine = createMachine({
+  // ...
+  context: ({ spawn }) => ({
+    actorRef: spawn(
+      createMachine({
+        // ...
+      }),
+      { systemId: 'actorRef' }
+    )
+  })
+});
+```

.vscode/launch.json

@@ -6,13 +6,7 @@
       "request": "launch",
       "name": "Jest Current File",
       "program": "${workspaceFolder}/node_modules/.bin/jest",
-      "args": [
-        "${file}",
-        "--config",
-        "jest.config.js",
-        "--no-cache",
-        "--testTimeout=2147483647"
-      ],
+      "args": ["${file}", "--config", "jest.config.js", "--no-cache"],
       "console": "integratedTerminal",
       "internalConsoleOptions": "neverOpen",
       "disableOptimisticBPs": true,

packages/core/src/spawn.ts

@@ -21,6 +21,7 @@ export function createSpawner<
   mutCapturedActions: InvokeActionObject[]
 ): Spawner {
   return (src, options = {}) => {
+    const { systemId } = options;
     if (isString(src)) {
       const referenced = resolveReferencedActor(machine.options.actors[src]);
 
@@ -49,7 +50,8 @@ export function createSpawner<
             src: actorRef, // TODO
             ref: actorRef,
             meta: undefined,
-            input
+            input,
+            systemId
           }) as any as InvokeActionObject
         );
 
@@ -65,7 +67,8 @@ export function createSpawner<
       const actorRef = interpret(src, {
         id: options.id || 'anonymous',
         parent: self,
-        input: options.input
+        input: options.input,
+        systemId
       });
 
       mutCapturedActions.push(

packages/core/src/types.ts

@@ -127,6 +127,7 @@ export type Spawner = <T extends ActorBehavior<any, any> | string>( // TODO: rea
   behavior: T,
   options?: Partial<{
     id: string;
+    systemId?: string;
     input: any;
   }>
 ) => T extends ActorBehavior<infer TActorEvent, infer TActorEmitted>

packages/core/test/system.test.ts

@@ -5,11 +5,12 @@ import {
   assign,
   createMachine,
   interpret,
-  sendTo
+  sendTo,
+  stop
 } from '../src/index.ts';
 
 describe('system', () => {
-  it('should register an actor (implicit system)', (done) => {
+  it('should register an invoked actor', (done) => {
     type MySystem = ActorSystem<{
       actors: {
         receiver: ActorRef<{ type: 'HELLO' }>;
@@ -51,7 +52,56 @@ describe('system', () => {
     interpret(machine).start();
   });
 
-  it('system can be immediatelly accessed outside the actor', () => {
+  it('should register a spawned actor', (done) => {
+    type MySystem = ActorSystem<{
+      actors: {
+        receiver: ActorRef<{ type: 'HELLO' }>;
+      };
+    }>;
+
+    const machine = createMachine({
+      id: 'parent',
+      context: ({ spawn }) => ({
+        ref: spawn(
+          fromCallback((_, receive) => {
+            receive((event) => {
+              expect(event.type).toBe('HELLO');
+              done();
+            });
+          }),
+          { systemId: 'receiver' }
+        )
+      }),
+      on: {
+        toggle: {
+          actions: assign({
+            machineRef: ({ spawn }) => {
+              return spawn(
+                createMachine({
+                  id: 'childmachine',
+                  entry: ({ system }) => {
+                    const receiver = (system as MySystem)?.get('receiver');
+
+                    if (receiver) {
+                      receiver.send({ type: 'HELLO' });
+                    } else {
+                      throw new Error('no');
+                    }
+                  }
+                })
+              );
+            }
+          })
+        }
+      }
+    });
+
+    const actor = interpret(machine).start();
+
+    actor.send({ type: 'toggle' });
+  });
+
+  it('system can be immediately accessed outside the actor', () => {
     const machine = createMachine({
       invoke: {
         systemId: 'someChild',
@@ -71,7 +121,7 @@ describe('system', () => {
     expect(actor.system.get('test')).toBe(actor);
   });
 
-  it('should remove actor from receptionist if stopped', () => {
+  it('should remove invoked actor from receptionist if stopped', () => {
     const machine = createMachine({
       initial: 'active',
       states: {
@@ -97,6 +147,29 @@ describe('system', () => {
     expect(actor.system.get('test')).toBeUndefined();
   });
 
+  it('should remove spawned actor from receptionist if stopped', () => {
+    const machine = createMachine({
+      context: ({ spawn }) => ({
+        ref: spawn(createMachine({}), {
+          systemId: 'test'
+        })
+      }),
+      on: {
+        toggle: {
+          actions: stop(({ context }) => context.ref)
+        }
+      }
+    });
+
+    const actor = interpret(machine).start();
+
+    expect(actor.system.get('test')).toBeDefined();
+
+    actor.send({ type: 'toggle' });
+
+    expect(actor.system.get('test')).toBeUndefined();
+  });
+
   it('should throw an error if an actor with the system ID already exists', () => {
     const machine = createMachine({
       initial: 'inactive',