toPromise(actorRef)

packages/core/src/index.ts

@@ -33,7 +33,7 @@ export type {
   InspectionEvent,
   ActorSystem
 } from './system.ts';
-
+export { toPromise } from './toPromise.ts';
 export { and, not, or, stateIn } from './guards.ts';
 export { setup } from './setup.ts';
 

packages/core/src/toPromise.ts

@@ -0,0 +1,47 @@
+import { AnyActorRef, OutputFrom } from './types.ts';
+
+/**
+ * Returns a promise that resolves to the `output` of the actor when it is done.
+ *
+ * @example
+ * ```ts
+ * const machine = createMachine({
+ *   // ...
+ *   output: {
+ *     count: 42
+ *   }
+ * });
+ *
+ * const actor = createActor(machine);
+ *
+ * actor.start();
+ *
+ * const output = await toPromise(actor);
+ *
+ * console.log(output);
+ * // logs { count: 42 }
+ * ```
+ */
+export function toPromise<T extends AnyActorRef>(
+  actor: T
+): Promise<OutputFrom<T>> {
+  // TODO: this is typed as `any`
+  const currentSnapshot = actor.getSnapshot();
+
+  if (currentSnapshot.status === 'done') {
+    return Promise.resolve(currentSnapshot.output);
+  }
+
+  if (currentSnapshot.status === 'error') {
+    return Promise.reject(currentSnapshot.error);
+  }
+
+  return new Promise((resolve, reject) => {
+    actor.subscribe({
+      complete: () => {
+        resolve(actor.getSnapshot().output);
+      },
+      error: reject
+    });
+  });
+}

packages/core/src/types.ts

@@ -159,7 +159,9 @@ export type OutputFrom<T> = T extends ActorLogic<
   infer _TSystem
 >
   ? (TSnapshot & { status: 'done' })['output']
-  : never;
+  : T extends ActorRef<infer TSnapshot, infer _TEvent>
+    ? (TSnapshot & { status: 'done' })['output']
+    : never;
 
 export type ActionFunction<
   TContext extends MachineContext,

packages/core/test/toPromise.test.ts

@@ -0,0 +1,142 @@
+import { 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);
+
+    result satisfies number;
+
+    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);
+
+    data satisfies { count: number };
+
+    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);
+
+    data satisfies { count: number };
+
+    expect(data).toEqual({ count: 42 });
+  });
+
+  it('should handle errors', async () => {
+    const machine = createMachine({
+      initial: 'pending',
+      states: {
+        pending: {
+          on: {
+            REJECT: {
+              actions: () => {
+                throw new Error('oh noes');
+              }
+            }
+          }
+        }
+      }
+    });
+
+    const actor = createActor(machine).start();
+
+    setTimeout(() => {
+      actor.send({ type: 'REJECT' });
+    });
+
+    try {
+      await toPromise(actor);
+    } catch (err) {
+      expect(err).toEqual(new Error('oh noes'));
+    }
+  });
+
+  it('should immediately resolve for a done actor', async () => {
+    const machine = createMachine({
+      initial: 'done',
+      states: {
+        done: {
+          type: 'final'
+        }
+      },
+      output: {
+        count: 100
+      }
+    });
+
+    const actor = createActor(machine).start();
+
+    expect(actor.getSnapshot().status).toBe('done');
+    expect(actor.getSnapshot().output).toEqual({ count: 100 });
+
+    const output = await toPromise(actor);
+
+    expect(output).toEqual({ count: 100 });
+  });
+
+  it('should immediately reject for an actor that had an error', async () => {
+    expect.assertions(3);
+    const machine = createMachine({
+      entry: () => {
+        throw new Error('oh noes');
+      }
+    });
+
+    const actor = createActor(machine).start();
+
+    expect(actor.getSnapshot().status).toBe('error');
+    expect(actor.getSnapshot().error).toEqual(new Error('oh noes'));
+
+    try {
+      await toPromise(actor);
+    } catch (err) {
+      expect(err).toEqual(new Error('oh noes'));
+    }
+  });
+});