Required input for spawn when defined inside referenced actor (#5139)

* Make `spawn` input required when defined (with tests)

* changeset `spawn` input required

.changeset/big-pumas-search.md

@@ -0,0 +1,22 @@
+---
+'xstate': patch
+---
+
+Make `spawn` input required when defined inside referenced actor:
+
+```ts
+const childMachine = createMachine({
+  types: { input: {} as { value: number } }
+});
+
+const machine = createMachine({
+  types: {} as { context: { ref: ActorRefFrom<typeof childMachine> } },
+  context: ({ spawn }) => ({
+    ref: spawn(
+      childMachine,
+      // Input is now required!
+      { input: { value: 42 } }
+    )
+  })
+});
+```

packages/core/src/spawn.ts

@@ -13,7 +13,8 @@ import {
   IsNotNever,
   ProvidedActor,
   RequiredActorOptions,
-  TODO
+  TODO,
+  type RequiredLogicInput
 } from './types.ts';
 import { resolveReferencedActor } from './utils.ts';
 
@@ -36,42 +37,56 @@ type SpawnOptions<
     >
   : never;
 
-export type Spawner<TActor extends ProvidedActor> = IsLiteralString<
-  TActor['src']
-> extends true
-  ? {
-      <TSrc extends TActor['src']>(
-        logic: TSrc,
-        ...[options]: SpawnOptions<TActor, TSrc>
-      ): ActorRefFromLogic<GetConcreteByKey<TActor, 'src', TSrc>['logic']>;
-      <TLogic extends AnyActorLogic>(
-        src: TLogic,
-        options?: {
-          id?: never;
-          systemId?: string;
-          input?: InputFrom<TLogic>;
-          syncSnapshot?: boolean;
-        }
-      ): ActorRefFromLogic<TLogic>;
-    }
-  : <TLogic extends AnyActorLogic | string>(
-      src: TLogic,
-      options?: {
-        id?: string;
-        systemId?: string;
-        input?: TLogic extends string ? unknown : InputFrom<TLogic>;
-        syncSnapshot?: boolean;
+export type Spawner<TActor extends ProvidedActor> =
+  IsLiteralString<TActor['src']> extends true
+    ? {
+        <TSrc extends TActor['src']>(
+          logic: TSrc,
+          ...[options]: SpawnOptions<TActor, TSrc>
+        ): ActorRefFromLogic<GetConcreteByKey<TActor, 'src', TSrc>['logic']>;
+        <TLogic extends AnyActorLogic>(
+          src: TLogic,
+          ...[options]: ConditionalRequired<
+            [
+              options?: {
+                id?: never;
+                systemId?: string;
+                input?: InputFrom<TLogic>;
+                syncSnapshot?: boolean;
+              } & { [K in RequiredLogicInput<TLogic>]: unknown }
+            ],
+            IsNotNever<RequiredLogicInput<TLogic>>
+          >
+        ): ActorRefFromLogic<TLogic>;
       }
-    ) => TLogic extends AnyActorLogic ? ActorRefFromLogic<TLogic> : AnyActorRef;
+    : <TLogic extends AnyActorLogic | string>(
+        src: TLogic,
+        ...[options]: ConditionalRequired<
+          [
+            options?: {
+              id?: string;
+              systemId?: string;
+              input?: TLogic extends string ? unknown : InputFrom<TLogic>;
+              syncSnapshot?: boolean;
+            } & (TLogic extends AnyActorLogic
+              ? { [K in RequiredLogicInput<TLogic>]: unknown }
+              : {})
+          ],
+          IsNotNever<
+            TLogic extends AnyActorLogic ? RequiredLogicInput<TLogic> : never
+          >
+        >
+      ) => TLogic extends AnyActorLogic
+        ? ActorRefFromLogic<TLogic>
+        : AnyActorRef;
 
 export function createSpawner(
   actorScope: AnyActorScope,
   { machine, context }: AnyMachineSnapshot,
   event: AnyEventObject,
   spawnedChildren: Record<string, AnyActorRef>
 ): Spawner<any> {
-  const spawn: Spawner<any> = (src, options = {}) => {
-    const { systemId, input } = options;
+  const spawn: Spawner<any> = ((src, options) => {
     if (typeof src === 'string') {
       const logic = resolveReferencedActor(machine, src);
 
@@ -82,38 +97,38 @@ export function createSpawner(
       }
 
       const actorRef = createActor(logic, {
-        id: options.id,
+        id: options?.id,
         parent: actorScope.self,
-        syncSnapshot: options.syncSnapshot,
+        syncSnapshot: options?.syncSnapshot,
         input:
-          typeof input === 'function'
-            ? input({
+          typeof options?.input === 'function'
+            ? options.input({
                 context,
                 event,
                 self: actorScope.self
               })
-            : input,
+            : options?.input,
         src,
-        systemId
+        systemId: options?.systemId
       }) as any;
 
       spawnedChildren[actorRef.id] = actorRef;
 
       return actorRef;
     } else {
       const actorRef = createActor(src, {
-        id: options.id,
+        id: options?.id,
         parent: actorScope.self,
-        syncSnapshot: options.syncSnapshot,
-        input: options.input,
+        syncSnapshot: options?.syncSnapshot,
+        input: options?.input,
         src,
-        systemId
+        systemId: options?.systemId
       });
 
       return actorRef;
     }
-  };
-  return (src, options) => {
+  }) as Spawner<any>;
+  return ((src, options) => {
     const actorRef = spawn(src, options) as TODO; // TODO: fix types
     spawnedChildren[actorRef.id] = actorRef;
     actorScope.defer(() => {
@@ -123,5 +138,5 @@ export function createSpawner(
       actorRef.start();
     });
     return actorRef;
-  };
+  }) as Spawner<any>;
 }

packages/core/src/types.ts

@@ -2,14 +2,14 @@ import type { MachineSnapshot } from './State.ts';
 import type { StateMachine } from './StateMachine.ts';
 import type { StateNode } from './StateNode.ts';
 import { AssignArgs } from './actions/assign.ts';
+import { ExecutableRaiseAction } from './actions/raise.ts';
+import { ExecutableSendToAction } from './actions/send.ts';
 import { PromiseActorLogic } from './actors/promise.ts';
-import { Guard, GuardPredicate, UnknownGuard } from './guards.ts';
 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.js';
-import { InspectionEvent } from './inspection.ts';
-import { ExecutableRaiseAction } from './actions/raise.ts';
-import { ExecutableSendToAction } from './actions/send.ts';
 
 export type Identity<T> = { [K in keyof T]: T[K] };
 
@@ -805,8 +805,8 @@ export type InvokeConfig<
               >
             >;
         /**
-         * The transition to take upon the invoked child machine sending an
-         * error event.
+         * The transition to take upon the invoked child machine sending an error
+         * event.
          */
         onError?:
           | string
@@ -2452,6 +2452,9 @@ export type RequiredActorOptions<TActor extends ProvidedActor> =
   | (undefined extends TActor['id'] ? never : 'id')
   | (undefined extends InputFrom<TActor['logic']> ? never : 'input');
 
+export type RequiredLogicInput<TLogic extends AnyActorLogic> =
+  undefined extends InputFrom<TLogic> ? never : 'input';
+
 type ExtractLiteralString<T extends string | undefined> = T extends string
   ? string extends T
     ? never

packages/core/test/spawn.test.ts

@@ -0,0 +1,18 @@
+import { ActorRefFrom, createActor, createMachine } from '../src';
+
+describe('spawn inside machine', () => {
+  it('input is required when defined in actor', () => {
+    const childMachine = createMachine({
+      types: { input: {} as { value: number } }
+    });
+    const machine = createMachine({
+      types: {} as { context: { ref: ActorRefFrom<typeof childMachine> } },
+      context: ({ spawn }) => ({
+        ref: spawn(childMachine, { input: { value: 42 }, systemId: 'test' })
+      })
+    });
+
+    const actor = createActor(machine).start();
+    expect(actor.system.get('test')).toBeDefined();
+  });
+});

packages/core/test/spawn.types.test.ts

@@ -0,0 +1,49 @@
+import { ActorRefFrom, assign, createMachine } from '../src';
+
+describe('spawn inside machine', () => {
+  it('input is required when defined in actor', () => {
+    const childMachine = createMachine({
+      types: { input: {} as { value: number } }
+    });
+    createMachine({
+      types: {} as { context: { ref: ActorRefFrom<typeof childMachine> } },
+      context: ({ spawn }) => ({
+        ref: spawn(childMachine, { input: { value: 42 } })
+      }),
+      initial: 'idle',
+      states: {
+        Idle: {
+          on: {
+            event: {
+              actions: assign(({ spawn }) => ({
+                ref: spawn(childMachine, { input: { value: 42 } })
+              }))
+            }
+          }
+        }
+      }
+    });
+  });
+
+  it('input is not required when not defined in actor', () => {
+    const childMachine = createMachine({});
+    createMachine({
+      types: {} as { context: { ref: ActorRefFrom<typeof childMachine> } },
+      context: ({ spawn }) => ({
+        ref: spawn(childMachine)
+      }),
+      initial: 'idle',
+      states: {
+        Idle: {
+          on: {
+            some: {
+              actions: assign(({ spawn }) => ({
+                ref: spawn(childMachine)
+              }))
+            }
+          }
+        }
+      }
+    });
+  });
+});