Patterns for sharing a machine as a lib

[cristiano-belloni]

Quick question: what are the best practices / patterns for sharing machines / actors?

I have a small machine to do exponential backoff requests, and I'd like to share it in a library. I don't know how users will use it - if directly interpreting it, invoking it or spawning it as an actor. I thought of just using sendParent or sendUpdate, but doing in an interpreted machine (without parent) throws an error. In the end I came out with this pattern of having placeholder actions in the states or transitions I want to expose:

In the machine definition:

// ...
        success: {
          entry: "updateSuccess",
          type: "final",
        },
        failure: {
          entry: "updateFailure",
          type: "final",
        },
        waiting: {
          entry: "updateRetry",
          after: {
            DELAY: {
              target: "started",
            },
          },
        },
// ...

In the machine config:

// ...
        actions: {
        updateFailure: noop,
        updateSuccess: noop,
        updateRetry: noop,
        incrementAttempts: assign({
          attempts: (context) => context.attempts + 1,
        }),
// ...

function noop() {
  return null;
}

And finally if someone consumes it as an actor:

const machine = createMachine(failingPromiseFactory).withConfig({
      actions: {
        updateFailure: sendParent((context) => ({
          type: "FAILURE",
          attempts: context.attempts,
          errors: context.errors,
        })),
        updateSuccess: sendParent((context) => ({
          type: "SUCCESS",
          attempts: context.attempts,
          errors: context.errors,
          result: context.result,
        })),
        updateRetry: sendParent("RETRY"),
      },

But that seems quite verbose. I was wondering if there's a better pattern to share a machine (or a collection of machines) in a lib, retaining the flexibility of it being used directly or as an actor.

[davidkpiano]

This has me thinking that maybe sendParent shouldn't throw if there is no parent, but rather gracefully continue...

Anyway, is your plan to have this consumable as an XState machine, or a general-purpose utility?

As an XState machine:

Use sendParent, as you have described above. The assumption is that this machine is to be invoked.

As a general-purpose utility:

You can try this pattern:

export function exponentialBackoff(getPromise, { onSuccess, onFailure, onRetry }) {
  const machine = createMachine(/* ... */)
    .withConfig({
      actions: { onSuccess, onFailure, onRetry }
    });

  interpret(machine).start();
}

Which can be generally consumed like this:

import { exponentialBackoff } from '...';

exponentialBackoff(() => fetch('some/api'), {
  onSuccess: res => console.log(res),
  onFailure: res => console.error(res),
  // ...
});

[cristiano-belloni]

@davidkpiano thanks for the quick response.

Anyway, is your plan to have this consumable as an XState machine, or a general-purpose utility?

Both. I would like to export the same machine to beinterpreted (maybe even as a sub-machine) or invoked or spawned. Your general purpose pattern makes sense (and I will use it), but I realized what I would like would be what you suggested:

maybe sendParent shouldn't throw if there is no parent, but rather gracefully continue...

I guess that, with that, it would really handy to write standalone machines that duplicate as actors with the same code...

[Andarist]

maybe sendParent shouldn't throw if there is no parent, but rather gracefully continue...

With such a change you still wouldn't achieve your goal though, right? As you wouldn't easily expose such a machine for interpret's use case.

---

This is just a random thought, not a super fleshed out one - maybe you should write your machine with an assumption of a parent (so using sendParent etc) but put actions configured in the second argument of the createMachine call and if one would like to use it with bare interpret API then they should just do what u have kinda proposed already - interpret(machine.withConfig()). That way though it would work out of the box for invoke/spawn when how to communicate with the "caller" is known. In the case of the interpret call this is unknown though, so the integration has to be provided by the caller itself.

[cristiano-belloni]

Thanks for your response, @Andarist

With such a change you still wouldn't achieve your goal though, right? As you wouldn't easily expose such a machine for interpret's use case.

Why not? If I write a machine with sendParent and they are ignored when the machine is interpreted, whoever needs the machine will just hook up on the .onTransition callback.

maybe you should write your machine with an assumption of a parent (so using sendParent etc) but put actions configured in the second argument of the createMachine call and if one would like to use it with bare interpret API then they should just do what u have kinda proposed already - interpret(machine.withConfig())

But I guess they wouldn't need to do that if sendParent didn't throw, correct?

[Andarist]

Why not? If I write a machine with sendParent and they are ignored when the machine is interpreted, whoever needs the machine will just hook up on the .onTransition callback.

And how exactly they would listen to those actions? Yes, it's doable - but I would consider this to be quite cumbersome as they would have to "decode" that information from what sendParent looks like. Providing things explicitly without the machine itself thinking that it sends events to some entity seems a better solution to me.