xstate-fetcher: advanced fetching and caching for Xstate!

[mohannad-s-awad]

xstate-fetcher

Hello folks. I am proud to share with you an alpha version of xstate-fetcher. It is a library inspired by react-query (created by the pioneer @tannerlinsley) for managing the complex asynchronous state of queries/mutations (called “fetchers”) using xstate with a global key-based cache.

https://www.npmjs.com/package/xstate-fetcher

https://github.com/mohannad-s-awad/xstate-fetcher

Here is a demo example:

import { actions, createMachine, interpret } from "xstate";
import { createCache, createFetcher, useFetcher } from "xstate-fetcher";

const cache = createCache();

interpret(
  createMachine(
    {
      id: "exampleMachine",
      strict: true,
      preserveActionOrder: true,

      initial: "loading",
      states: {
        loading: {
          entry: actions.log("LOADING!"),
          on: { EXAMPLE_QUERY_LOADED: "loaded" },
        },
        loaded: {
          entry: actions.log("LOADED!"),
          on: { EXAMPLE_QUERY_LOADING: "loading" },
        },
      },

      invoke: {
        id: "exampleQuery",
        src: "exampleQuery",
      },
    },
    {
      services: {
        exampleQuery: () =>
          useFetcher({
            key: "exampleQuery",
            fetchFn: () => Promise.resolve("Hello xstate-fetcher!"),

            // This function maps transitions in exampleQuery's state to exampleMachine's events.
            mapFn: ({ state }) => {
              if (state.matches("request.loading")) {
                return { type: "EXAMPLE_QUERY_LOADING" };
              }
              if (state.matches("request.loaded")) {
                return { type: "EXAMPLE_QUERY_LOADED" };
              }
            },

            cache,
            // Synchronizations can be used, for example, to invalidate exampleQuery when exampleMutation1 or exampleMutation1 is loaded.
            synchronizations: [
              {
                // We synchronize with other fetchers starting with this partial key.
                key: ["exampleMutation"],
                // This function maps exampleMutation1/2's transitions to exampleQuery's events.
                synchronizeFn: ({ state }) => {
                  if (state.matches("request.loaded")) {
                    return { type: "INVALIDATE" };
                  }
                },
              },
            ],
          }),
      },
    }
  )
).start();

setTimeout(() => {
  // Create exampleMutation1 somewhere else in the app.
  // It can also be invoked in a machine similar to exampleQuery.
  const exampleMutation1 = interpret(
    createFetcher({
      type: "MUTATION",
      fetchFn: () => Promise.resolve("Hello xstate-fetcher!"),
    })
  ).start();

  // Create exampleMutation2 somewhere else in the app.
  // It can also be invoked in a machine similar to exampleQuery.
  const exampleMutation2 = interpret(
    createFetcher({
      type: "MUTATION",
      fetchFn: () => Promise.resolve("Hello xstate-fetcher!"),
    })
  ).start();

  // Cache exampleMutation1/2 so they can be observed by other fetchers like exampleQuery for synchronization purposes.
  cache.set(["exampleMutation", 1], exampleMutation1);
  cache.set(["exampleMutation", 2], exampleMutation2);

  // Act on multiple cached fetchers in a single batch.
  // Here we load exampleMutation1/2 by matching their keys partially.
  cache.batch(["exampleMutation"], ({ fetcher }) =>
    fetcher.send({ type: "LOAD" })
  );
}, 1000);

Key features (not a comprehensive list):

• Fetchers have two modes for querying/mutating, and encapsulate the state of both: the request (idle, disabled, loading, loaded, aborted, and failed) and the response (none, fresh, and stale).
• Fetchers are standalone interpreters that usually outlive their invoking machines in the global cache; but can also operate without it. They can be kept actively running in the background even after their invoking machines are disposed.
• Fetchers can be virtually invoked from any machine via “proxies” that facilitate sending/receiving events as well as observing fetchers’ transitions/events and mapping them to invoking machine’s events.
• Fetchers are responsible to synchronize/invalidate their domain data by subscribing to transitions/events of other fetchers using keys and filters. This is a different approach to react-query's where, for example, mutations are usually responsible to synchronize/invalidate other queries, but this approach will also be possible in xstate-fetcher.
• Fetchers can be fully controlled from their granular options and from the global cache: filtered and acted on in batches, similar to react-query.

Coming features (not a final list):

• “Pending” request state for when the source connectivity goes offline.
• Options for loading/reloading on source reconnect, window refocus, and custom time interval.
• Strongly type the different creators, data, abort signals, …etc. of the fetchers
• Write your suggestions here please…

Open design/usage questions for your valuable opinions please:

• Is there a better general approach to integrate the standalone fetchers with the invoking machines?
• Virtual parent-child communication is currently facilitated using an ad-hoc parent set to the fetchers’s parent property to intercept sendParent, respond, and escalate actions then forward them to the invoking machine as part of the proxying logic. Is there a better approach?
• Do you recommend to make the global cache (currently a class) into an xstatemachine too? How am I supposed to handle/simplify synchronous calls/returns (mostly read-only computations)?
• What is the best way to use xstate-fetcher, for example, with UI component machines? Should one expose the fetcher interpreters to the view layer (e.g. Vue components) or should one encapsulate/hide them inside the invoking machines? With the second option, we need to map fetchers’ transitions/events to invoking machines’ events, which introduces some verbosity…

Let me know please of what you think to develop this library further, or even change the whole approach if necessary. I have other questions regarding your newly recommended option predictableActionArguments and how to prepare for v5 migration…

I am also planning to write an article about my experience developing xstate-fetcher using xstate. Where do you suggest a good place to publish my (first) article?

Thank you all!

Mohannad