toPromise(actorRef)

[davidkpiano]

This PR introduces toPromise(actor), which creates a promise from an actor that resolves with output when the actor is done.

import { createMachine, createActor, toPromise } from 'xstate';

const actor = createActor(createMachine({
  // ...
  states: {
    // ...
    done: { type: 'final', output: 42 }
  }
});

actor.start();

const output = await toPromise(actor);
// => 42

[changeset-bot]

🦋 Changeset detected

Latest commit: 6e35374

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
xstate	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 6e35374:

Sandbox	Source
XState Example Template	Configuration
XState React Template	Configuration

[ghost]

👇 Click on the image for a new way to code review

Legend

[Andarist]

This supersedes #3977 , right? I certainly like this one better 😉

[Necmttn]

Looking forward to this,
Currently, i have actor machines that execute in serverless environments.

const entryNode = di.editor.getNode(payload.workflowNodeId);
if (!entryNode) {
  throw new Error("Entry node not found");
}
let state = entryNode.actor.getSnapshot();
entryNode.actor.subscribe({
  next: (data) => {
    io.logger.info("STATE", data);
    state = data;
  },
  complete: () => {
    io.logger.log("COMPLETE", state.output);
  },
});
di.engine.execute(entryNode.id, undefined, payload.executionId);
await waitFor(entryNode.actor, (state) => state.matches("complete"), {
  timeout: 1000 * 60 * 5,
});
io.logger.info("STATE", state);

Currently, I'm using the waitFor method to wait for the actor to get the final state, but as API design wise this doesn't feel good to me.
another alternative of it kind a like this;

let state = entryNode.actor.getSnapshot();
await new Promise((resolve, reject) => {
  entryNode.actor.subscribe({
    error(err) {
      reject(err);
    },
    next: (data) => {
      io.logger.info("STATE", data);
      state = data;
    },
    complete: () => {
      resolve(state);
      io.logger.log("COMPLETE", state.output);
    },
  });
});

Which is also doesn't feel like the best.

[Andarist]

This should be enough to "await" the actor with the v5 API:

await waitFor(actorRef, s => s.status === 'done')

We might still implement toPromise later on as a convenience but I don't feel like this one-liner is that bad even today.

[davidkpiano]

This should be enough to "await" the actor with the v5 API:

await waitFor(actorRef, s => s.status === 'done')

We might still implement toPromise later on as a convenience but I don't feel like this one-liner is that bad even today.

For reference, this would be more than a one-liner unfortunately:

await waitFor(actorRef, s => s.status === 'done');
const output = actorRef.getSnapshot().output!;

[Andarist]

Still a one-liner :P

const output = (await waitFor(actorRef, s => s.status === 'done')).output!;

[Andarist]

We can't do much about it as long as we use T extends AnyActorRef pattern. You unwrap here what you provided for the TSnapshot within ActorRef but that's just any (since you are using AnyActorRef)

[Andarist]

Interestingly, this one is not redundant right now. I think this is a problem and I even thought that we had some tests related to this (although maybe indirect ones). I'll take a look at this right now.

[Andarist]

I believe that we'll be able to remove this once this lands: #4570

[davidkpiano]

Approved ✅