toPromise(actorRef)

packages/core/src/StateMachine.ts

@@ -362,7 +362,11 @@ export class StateMachine<
   > {
     return getPersistedState(state);
   }
-
+  public getOutput(
+    state: State<TContext, TEvent, TActor, TOutput, TResolvedTypesMeta>
+  ) {
+    return state.output;
+  }
   public createState(
     stateConfig:
       | State<TContext, TEvent, TActor, TOutput, TResolvedTypesMeta>

packages/core/src/actors/callback.ts

@@ -135,6 +135,7 @@ export function fromCallback<TEvent extends EventObject, TInput>(
       };
     },
     getSnapshot: () => undefined,
-    getPersistedState: ({ input, canceled }) => ({ input, canceled })
+    getPersistedState: ({ input, canceled }) => ({ input, canceled }),
+    getOutput: () => undefined
   };
 }

packages/core/src/actors/index.ts

@@ -66,6 +66,7 @@ export function toActorRef<
     },
     status: ActorStatus.Running,
     stop: () => void 0,
+    getOutput: () => undefined,
     ...actorRefLike
   };
 }

packages/core/src/actors/observable.ts

@@ -129,6 +129,7 @@ export function fromObservable<T, TInput>(
       input
     }),
     getStatus: (state) => state,
+    getOutput: (state) => (state.status === 'done' ? state.data : undefined),
     restoreState: (state) => ({
       ...state,
       subscription: undefined
@@ -234,6 +235,7 @@ export function fromEventObservable<T extends EventObject, TInput>(
     restoreState: (state) => ({
       ...state,
       subscription: undefined
-    })
+    }),
+    getOutput: () => undefined
   };
 }

packages/core/src/actors/promise.ts

@@ -122,6 +122,7 @@ export function fromPromise<T, TInput>(
     getSnapshot: (state) => state.data,
     getStatus: (state) => state,
     getPersistedState: (state) => state,
+    getOutput: (state) => state.data,
     restoreState: (state) => state
   };
 

packages/core/src/actors/transition.ts

@@ -60,6 +60,7 @@ export function fromTransition<
     },
     getSnapshot: (state) => state,
     getPersistedState: (state) => state,
-    restoreState: (state) => state
+    restoreState: (state) => state,
+    getOutput: () => undefined
   };
 }

packages/core/src/index.ts

@@ -50,6 +50,8 @@ export {
   fromTransition
 } from './actors/index.ts';
 
+export { toPromise } from './toPromise.ts';
+
 export { stateIn, not, and, or } from './guards.ts';
 
 declare global {

packages/core/src/interpreter.ts

@@ -19,7 +19,8 @@ import type {
   EventFromLogic,
   PersistedStateFrom,
   SnapshotFrom,
-  AnyActorRef
+  AnyActorRef,
+  OutputFrom
 } from './types.ts';
 import {
   ActorRef,
@@ -81,7 +82,7 @@ type InternalStateFrom<TLogic extends ActorLogic<any, any, any>> =
 export class Actor<
   TLogic extends AnyActorLogic,
   TEvent extends EventObject = EventFromLogic<TLogic>
-> implements ActorRef<TEvent, SnapshotFrom<TLogic>>
+> implements ActorRef<TEvent, SnapshotFrom<TLogic>, OutputFrom<TLogic>>
 {
   /**
    * The current internal state of the actor.
@@ -320,6 +321,10 @@ export class Actor<
     return this;
   }
 
+  public getOutput() {
+    return this.logic.getOutput?.(this._state);
+  }
+
   private _process(event: TEvent) {
     // TODO: reexamine what happens when an action (or a guard or smth) throws
     let nextState;

packages/core/src/toPromise.ts

@@ -0,0 +1,20 @@
+import { Actor, ActorRef, AnyActor, AnyActorRef, OutputFrom } from '.';
+
+export function toPromise<T extends AnyActorRef>(
+  actor: T
+): Promise<T extends Actor<infer TLogic> ? OutputFrom<TLogic> : unknown> {
+  return new Promise((resolve, reject) => {
+    actor.subscribe({
+      complete: () => {
+        resolve(
+          actor.getOutput()! as T extends Actor<infer TLogic>
+            ? OutputFrom<TLogic>
+            : unknown
+        );
+      },
+      error: (err) => {
+        reject(err);
+      }
+    });
+  });
+}

packages/core/src/types.ts

@@ -1452,8 +1452,11 @@ export interface ActorLike<TCurrent, TEvent extends EventObject>
   send: (event: TEvent) => void;
 }
 
-export interface ActorRef<TEvent extends EventObject, TSnapshot = any>
-  extends Subscribable<TSnapshot>,
+export interface ActorRef<
+  TEvent extends EventObject,
+  TSnapshot = any,
+  TOutput = unknown
+> extends Subscribable<TSnapshot>,
     InteropObservable<TSnapshot> {
   /**
    * The unique identifier for this actor relative to its parent.
@@ -1466,6 +1469,7 @@ export interface ActorRef<TEvent extends EventObject, TSnapshot = any>
   getSnapshot: () => TSnapshot;
   // TODO: this should return some sort of TPersistedState, not any
   getPersistedState?: () => any;
+  getOutput: () => TOutput | undefined;
   stop: () => void;
   toJSON?: () => any;
   // TODO: figure out how to hide this externally as `sendTo(ctx => ctx.actorRef._parent._parent._parent._parent)` shouldn't be allowed
@@ -1632,6 +1636,7 @@ export interface ActorLogic<
   ) => TInternalState;
   getSnapshot?: (state: TInternalState) => TSnapshot;
   getStatus?: (state: TInternalState) => { status: string; data?: any };
+  getOutput: (state: TInternalState) => TOutput | undefined; // undefined if no output yet
   start?: (
     state: TInternalState,
     actorCtx: ActorContext<TEvent, TSnapshot>

packages/core/test/actor.test.ts

@@ -1035,7 +1035,8 @@ describe('actors', () => {
 
           return undefined;
         },
-        getInitialState: () => undefined
+        getInitialState: () => undefined,
+        getOutput: () => undefined
       };
 
       const pingMachine = createMachine<{

packages/core/test/invoke.test.ts

@@ -2257,7 +2257,8 @@ describe('invoke', () => {
           }
           return count;
         },
-        getInitialState: () => 0
+        getInitialState: () => 0,
+        getOutput: () => undefined
       };
 
       const countMachine = createMachine({
@@ -2293,7 +2294,8 @@ describe('invoke', () => {
 
           return undefined;
         },
-        getInitialState: () => undefined
+        getInitialState: () => undefined,
+        getOutput: () => undefined
       };
 
       const pingMachine = createMachine({

packages/core/test/toPromise.test.ts

@@ -0,0 +1,76 @@
+import {
+  ActorRef,
+  createActor,
+  createMachine,
+  fromPromise,
+  toPromise
+} from '../src';
+
+describe('toPromise', () => {
+  it('should be awaitable', async () => {
+    const promiseActor = createActor(
+      fromPromise(() => Promise.resolve(42))
+    ).start();
+
+    const result = await toPromise(promiseActor);
+
+    ((_accept: number) => {})(result);
+
+    expect(result).toEqual(42);
+  });
+
+  it('should await actors', async () => {
+    const machine = createMachine({
+      types: {} as {
+        output: { count: 42 };
+      },
+      initial: 'pending',
+      states: {
+        pending: {
+          on: {
+            RESOLVE: 'done'
+          }
+        },
+        done: {
+          type: 'final',
+          output: { count: 42 }
+        }
+      }
+    });
+
+    const actor = createActor(machine).start();
+
+    setTimeout(() => {
+      actor.send({ type: 'RESOLVE' });
+    }, 1);
+
+    const data = await toPromise(actor);
+
+    ((_accept: { count: number }) => {})(data);
+
+    expect(data).toEqual({ count: 42 });
+  });
+
+  it('should await already done actors', async () => {
+    const machine = createMachine({
+      types: {} as {
+        output: { count: 42 };
+      },
+      initial: 'done',
+      states: {
+        done: {
+          type: 'final',
+          output: { count: 42 }
+        }
+      }
+    });
+
+    const actor = createActor(machine).start();
+
+    const data = await toPromise(actor);
+
+    ((_accept: { count: number }) => {})(data);
+
+    expect(data).toEqual({ count: 42 });
+  });
+});

packages/core/test/typeHelpers.test.ts

@@ -358,7 +358,8 @@ describe('ActorRefFrom', () => {
   it('should return `ActorRef` based on actor logic', () => {
     const logic: ActorLogic<{ type: 'TEST' }> = {
       transition: () => {},
-      getInitialState: () => undefined
+      getInitialState: () => undefined,
+      getOutput: () => undefined
     };
 
     function acceptActorRef(actorRef: ActorRefFrom<typeof logic>) {

packages/xstate-graph/test/graph.test.ts

@@ -531,7 +531,8 @@ it('simple paths for transition functions', () => {
         }
         return s;
       },
-      getInitialState: () => 0
+      getInitialState: () => 0,
+      getOutput: () => undefined
     },
     {
       events: [{ type: 'a' }, { type: 'b' }, { type: 'reset' }],
@@ -557,7 +558,8 @@ it('shortest paths for transition functions', () => {
         }
         return s;
       },
-      getInitialState: () => 0
+      getInitialState: () => 0,
+      getOutput: () => undefined
     },
     {
       events: [{ type: 'a' }, { type: 'b' }, { type: 'reset' }],

packages/xstate-react/test/useSelector.test.tsx

@@ -336,7 +336,8 @@ describeEachReactMode('useSelector (%s)', ({ suiteKey, render }) => {
           return { unsubscribe: () => {} };
         },
         getSnapshot: () => latestValue,
-        getInitialState: () => latestValue
+        getInitialState: () => latestValue,
+        getOutput: () => undefined
       });
 
     const parentMachine = createMachine({
@@ -476,7 +477,8 @@ describeEachReactMode('useSelector (%s)', ({ suiteKey, render }) => {
           return { unsubscribe: () => {} };
         },
         getSnapshot: () => latestValue,
-        getInitialState: () => latestValue
+        getInitialState: () => latestValue,
+        getOutput: () => undefined
       });
 
     const parentMachine = createMachine({
@@ -513,7 +515,8 @@ describeEachReactMode('useSelector (%s)', ({ suiteKey, render }) => {
           return { unsubscribe: () => {} };
         },
         getSnapshot: () => latestValue,
-        getInitialState: () => latestValue
+        getInitialState: () => latestValue,
+        getOutput: () => undefined
       });
 
     const actor1 = createCustomActor('foo');
@@ -544,7 +547,8 @@ describeEachReactMode('useSelector (%s)', ({ suiteKey, render }) => {
         return { unsubscribe: () => {} };
       },
       getSnapshot: () => undefined,
-      getInitialState: () => undefined
+      getInitialState: () => undefined,
+      getOutput: () => undefined
     });
 
     const App = ({ selector }: { selector: any }) => {

packages/xstate-solid/test/useActor.test.tsx

@@ -25,7 +25,8 @@ const createSimpleActor = <T extends unknown>(value: T) =>
   createActor({
     transition: (s) => s,
     getSnapshot: () => value,
-    getInitialState: () => value
+    getInitialState: () => value,
+    getOutput: () => undefined
   });
 
 describe('useActor', () => {
@@ -641,7 +642,8 @@ describe('useActor', () => {
     const simpleActor = createActor({
       transition: (s) => s,
       getSnapshot: () => 42,
-      getInitialState: () => 42
+      getInitialState: () => 42,
+      getOutput: () => undefined
     });
 
     const Test = () => {

packages/xstate-test/test/testModel.test.ts

@@ -12,7 +12,8 @@ describe('custom test models', () => {
           } else {
             return value * 3 + 1;
           }
-        }
+        },
+        getOutput: () => undefined
       },
       {
         events: (state) => {
@@ -41,7 +42,8 @@ describe('custom test models', () => {
           } else {
             return value * 3 + 1;
           }
-        }
+        },
+        getOutput: () => undefined
       },
       {
         events: (state) => {