[core] createInvoke(…) helper function

README.md

@@ -181,16 +181,16 @@ 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                                              |
-| [🏪 `@xstate/store`](https://github.com/statelyai/xstate/tree/main/packages/xstate-store) | Small library for simple state management |
+| 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                                              |
+| [🏪 `@xstate/store`](https://github.com/statelyai/xstate/tree/main/packages/xstate-store)   | Small library for simple state management                                    |
 
 ## Finite State Machines
 

packages/core/src/actions/spawnChild.ts

@@ -172,17 +172,18 @@ type SpawnArguments<
   TExpressionEvent extends EventObject,
   TEvent extends EventObject,
   TActor extends ProvidedActor
-> = IsLiteralString<TActor['src']> extends true
-  ? DistributeActors<TContext, TExpressionEvent, TEvent, TActor>
-  : [
-      src: string | AnyActorLogic,
-      options?: {
-        id?: ResolvableActorId<TContext, TExpressionEvent, TEvent, string>;
-        systemId?: string;
-        input?: unknown;
-        syncSnapshot?: boolean;
-      }
-    ];
+> =
+  IsLiteralString<TActor['src']> extends true
+    ? DistributeActors<TContext, TExpressionEvent, TEvent, TActor>
+    : [
+        src: string | AnyActorLogic,
+        options?: {
+          id?: ResolvableActorId<TContext, TExpressionEvent, TEvent, string>;
+          systemId?: string;
+          input?: unknown;
+          syncSnapshot?: boolean;
+        }
+      ];
 
 export function spawnChild<
   TContext extends MachineContext,

packages/core/src/actors/transition.ts

@@ -196,11 +196,7 @@ export function fromTransition<
     transition: (snapshot, event, actorScope) => {
       return {
         ...snapshot,
-        context: transition(
-          snapshot.context,
-          event,
-          actorScope as any
-        )
+        context: transition(snapshot.context, event, actorScope as any)
       };
     },
     getInitialSnapshot: (_, input) => {

packages/core/src/invoke.ts

@@ -0,0 +1,160 @@
+import {
+  ActorLogic,
+  AnyActorLogic,
+  DoneActorEvent,
+  DoNotInfer,
+  ErrorActorEvent,
+  EventObject,
+  InputFrom,
+  MachineContext,
+  Mapper,
+  MetaObject,
+  NonReducibleUnknown,
+  OutputFrom,
+  ParameterizedObject,
+  ProvidedActor,
+  SingleOrArray,
+  SnapshotEvent,
+  SnapshotFrom,
+  TransitionConfigOrTarget
+} from './types';
+
+export type InvokeObject<
+  TContext extends MachineContext,
+  TEvent extends EventObject,
+  TActor extends ProvidedActor,
+  TAction extends ParameterizedObject,
+  TGuard extends ParameterizedObject,
+  TDelay extends string,
+  TEmitted extends EventObject,
+  TMeta extends MetaObject
+> = {
+  (context: TContext): void;
+  id?: string;
+  systemId?: string;
+  src: AnyActorLogic;
+  input?:
+    | Mapper<TContext, TEvent, NonReducibleUnknown, TEvent>
+    | NonReducibleUnknown;
+  onDone?:
+    | string
+    | SingleOrArray<
+        TransitionConfigOrTarget<
+          TContext,
+          DoneActorEvent<any>, // TODO: consider replacing with `unknown`
+          TEvent,
+          TActor,
+          TAction,
+          TGuard,
+          TDelay,
+          TEmitted,
+          TMeta
+        >
+      >;
+  onError?:
+    | string
+    | SingleOrArray<
+        TransitionConfigOrTarget<
+          TContext,
+          ErrorActorEvent,
+          TEvent,
+          TActor,
+          TAction,
+          TGuard,
+          TDelay,
+          TEmitted,
+          TMeta
+        >
+      >;
+
+  onSnapshot?:
+    | string
+    | SingleOrArray<
+        TransitionConfigOrTarget<
+          TContext,
+          SnapshotEvent,
+          TEvent,
+          TActor,
+          TAction,
+          TGuard,
+          TDelay,
+          TEmitted,
+          TMeta
+        >
+      >;
+};
+
+export function createInvoke<
+  TContext extends MachineContext,
+  TEvent extends EventObject,
+  TActor extends ProvidedActor,
+  TAction extends ParameterizedObject,
+  TGuard extends ParameterizedObject,
+  TDelay extends string,
+  TEmitted extends EventObject,
+  TMeta extends MetaObject,
+  // Logic-specific types
+  TSrc extends AnyActorLogic
+>(_config: {
+  id?: string;
+  systemId?: string;
+  src: TSrc;
+  input?: Mapper<TContext, TEvent, InputFrom<TSrc>, TEvent> | InputFrom<TSrc>;
+  onDone?:
+    | string
+    | SingleOrArray<
+        TransitionConfigOrTarget<
+          TContext,
+          DoneActorEvent<OutputFrom<TSrc>>,
+          TEvent,
+          TActor,
+          TAction,
+          TGuard,
+          TDelay,
+          TEmitted,
+          TMeta
+        >
+      >;
+  onError?:
+    | string
+    | SingleOrArray<
+        TransitionConfigOrTarget<
+          TContext,
+          ErrorActorEvent,
+          TEvent,
+          TActor,
+          TAction,
+          TGuard,
+          TDelay,
+          TEmitted,
+          TMeta
+        >
+      >;
+
+  onSnapshot?:
+    | string
+    | SingleOrArray<
+        TransitionConfigOrTarget<
+          TContext,
+          SnapshotFrom<TSrc>,
+          TEvent,
+          TActor,
+          TAction,
+          TGuard,
+          TDelay,
+          TEmitted,
+          TMeta
+        >
+      >;
+}): InvokeObject<
+  TContext,
+  TEvent,
+  TActor,
+  TAction,
+  TGuard,
+  TDelay,
+  TEmitted,
+  TMeta
+> {
+  return null!;
+}

packages/core/src/system.ts

@@ -161,8 +161,8 @@ export function createSystem<T extends ActorSystemInfo>(
       ...event,
       rootId: rootActor.sessionId
     };
-    inspectionObservers.forEach(
-      (observer) => observer.next?.(resolvedInspectionEvent)
+    inspectionObservers.forEach((observer) =>
+      observer.next?.(resolvedInspectionEvent)
     );
   };
 

packages/core/src/types.ts

@@ -8,6 +8,7 @@ import type { Actor, ProcessingStatus } from './createActor.ts';
 import { Spawner } from './spawn.ts';
 import { AnyActorSystem, Clock } from './system.js';
 import { InspectionEvent } from './inspection.ts';
+import { InvokeObject } from './invoke.ts';
 
 export type Identity<T> = { [K in keyof T]: T[K] };
 
@@ -916,6 +917,20 @@ export interface StateNodeConfig<
       TMeta
     >
   >;
+
+  invoke2?: SingleOrArray<
+    InvokeObject<
+      TContext,
+      TEvent,
+      TActor,
+      TAction,
+      TGuard,
+      TDelay,
+      TEmitted,
+      TMeta
+    >
+  >;
+
   /** The mapping of event types to their potential transition(s). */
   on?: TransitionsConfig<
     TContext,

packages/core/test/invoke.test.ts

@@ -24,6 +24,7 @@ import {
   AnyEventObject
 } from '../src/index.ts';
 import { sleep } from '@xstate-repo/jest-utils';
+import { createInvoke } from '../src/invoke.ts';
 
 const user = { name: 'David' };
 
@@ -3437,3 +3438,27 @@ describe('invoke input', () => {
     createActor(machine).start();
   });
 });
+
+const machine = createMachine({
+  context: { number: 42 },
+  invoke2: createInvoke({
+    id: 'double',
+    input: ({ context }) => ({
+      count: context.number
+    }),
+    src: fromPromise(async ({ input }: { input: { count: number } }) => {
+      return input.count * 2;
+    }),
+    onDone: {
+      actions: ({ context, event }) => {
+        context.number satisfies number;
+        // @ts-expect-error
+        context.number satisfies string;
+
+        event.output satisfies number;
+        // @ts-expect-error
+        event.output satisfies string;
+      }
+    }
+  })
+});

packages/xstate-graph/src/TestModel.ts

@@ -455,7 +455,7 @@ export function createTestModel<TMachine extends AnyStateMachine>(
     },
     events: (state) => {
       const events =
-        typeof getEvents === 'function' ? getEvents(state) : getEvents ?? [];
+        typeof getEvents === 'function' ? getEvents(state) : (getEvents ?? []);
 
       return __unsafe_getAllOwnEventDescriptors(state).flatMap(
         (eventType: string) => {