Add tracking of loader/action lifecycles for subscription management, etc

[melnikov-s]

Proposing to add an ability to track the lifecycle of a loader and/or action. This can enable subscription management amongst other things where you'd need to associate state to a loader/action and be able to clean up that state when the loader/action is no longer "active".

I'll use a query subscription management as an example of a real world problem, where we'd need lifecycle tracking in order to solve for.

TL;DR:

To effectively manage subscriptions on loaders, we need to determine:

1. Whether a loader or fetcher is executing for the first time or updating.
2. A unique identifier for the loader to store subscriptions.
3. When the loader or fetcher is no longer active or "unmounted."
4. A mechanism to update only the specific loader that received a change event.

Background

For illustration, we will use Apollo Client and watchQuery subscriptions but in theory this should be applicable to any kind of subscription

Apollo Client is a GraphQL client with a built-in reactive cache. It allows you to use useQuery hooks to execute queries with different fetch policies. These fetch policies dictate the data source for the query, either from its global reactive cache or over the network. The default fetch policy reads from the cache, but there are situations where a network fetch is preferred. Other scenarios may require a stale-while-revalidate approach, fetching initial data from the cache, rendering it immediately, and then revalidating over the network to update with the latest data later. Because the cache is global and reactive, mutations that modify the cache should trigger re-renders in components that use useQuery to ensure they display the latest data.

The useQuery hook sets up a subscription when the component mounts, reads the fetch policy, and makes a network request if necessary. Upon re-render or update, it reads from the last result regardless of the fetch policy. If a mutation affects the global state read by useQuery, the hook forces a re-render with the latest data. When the component unmounts, the subscription is unsubscribed.

The Problem

The challenge with useQuery is that it fetches data as you render, while client-side loaders allow for pre-fetching queries. Without the lifecycle concept present in React with useQuery, we lose the ability to manage subscriptions. Consequently, we cannot support fetch-while-revalidate fetch policies, updates to mutations (outside of an action), or network-only fetch policies without over-fetching during unrelated loader revalidations.

To support this functionality, we need a way to track the lifecycle of a loader similarly to how we track the lifecycle of a component. Additionally, we should have the option to revalidate a single loader or fetcher specifically.

Here’s a playground with useQuery that have been migrated to loaders.

useQuery - https://stackblitz.com/edit/getting-started-with-graphql-react-i1bqn1
useLoaderData - https://stackblitz.com/edit/getting-started-with-graphql-react-nnxels

Notice that with useQuery we only make a single request when changing search params while useLoaderData is forced to recall each query on every revalidation if we wish to keep the same network behavior.

Proposal

To track subscriptions across loaders, we need to:

1. Determine if the subscription should be managed outside of the loaders themselves. The new dataStrategy API provides a suitable vector for introducing this functionality.

interface DataStrategyMatch extends AgnosticRouteMatch<...> {
  shouldLoad: boolean;
  data: unknown; // (NEW) current loaderData/fetcher.data for this match, if any
  fetcherId: string | undefined; // (NEW) the id of the fetcher that is calling this loader, if applicable
  onUnload: (cb: () => void) => void; // (NEW) provide a callback to run when this route is unmounted
  resolve: (...) => ...
}

2. Have a way to revalidate the loader/fetcher when a subscription is updated. This can be done with router.revalidate but since we only need to revalidate the specific fetcher/loader that was
   updated, we can add an optional parameter to router.revalidate to only revalidate specific fetchers/loaders.

router.revalidate(routeIds?: string[])

We can now use it in the following way to handle our subscriptions:

let router = createBrowserRouter(routes, {
  unstable_dataStrategy({ request, matches }) {
    // We don't want to track actions
    if (request.method !== 'GET') {
       return Promise.all(matches.map((match) => match.resolve()))
    }

    return Promise.all(
      matches.map(async (match) => {
        // get the unique id for this fetcher or loader that we can use to index a Map
        const id = match.fetcherId ?? match.route.id;

        // a mechanism to detect when a fetcher or loader is canceled because of a revalidation
        // can be done with a runId that is incremented each time a fetcher or loader is called
        const runId = incrementRunId(id);

        // if this is the first time we are loading this fetcher or loader
        // setup a way to unsubscribe when the route/fetcher is unloaded
        if (match.data === undefined) { // only do this for the first time a route/fetcher is loaded
          match.onUnload(() => {
            handleUnsubscribe(id);
          });
        }

        let result = match.resolve(async (handler) => {

          // create a query function that is bound to the route/fetcher id
          const query = (queryToCall) => {
            // fetch an existing subscription or create a new one based on id
            const querySub = getOrCreateSubscription(id, () => {
                // when the subscription needs to update, we can trigger a revalidation
                // for only this fetcher or loader
                if (runId === getCurrentRunId(id)) {
                    router.revalidate([id]);
                }
            });

            return querySub.call(queryToCall);
          }

          try {
            let handlerResult = await handler({query});
          } finally {
            // clean up any subscriptions that might have been called last load
            // but not on subsequent loads
            if (runId === getCurrentRunId(id)) {
                onCompleted(id);
            }
          }
          return handlerResult;
        });

        return result;
      })
    );
  },
});

With these additional APIs, React Router will expose all that is needed to manage subscriptions tied to loaders, not just specifically for Apollo Client but theoretically for any kind of subscription previously managed with React hooks.

[sergiodxa]

You can already manage subscriptions with a loader by using an event stream response, Remix (which is based on RR so it should be the same) can use the EventSource API to subscribe to a loader that returns an event stream.

I imagine a similar thing can be done with plain RR, if you return a stream from a RR loader, actually it should probably be simpler since you can return the stream from the UI loader directly.

[melnikov-s]

You can already manage subscriptions with a loader by using an event stream response, Remix (which is based on RR so it should be the same) can use the EventSource API to subscribe to a loader that returns an event stream.

I imagine a similar thing can be done with plain RR, if you return a stream from a RR loader, actually it should probably be simpler since you can return the stream from the UI loader directly.

I don't think that's equivalent to what's being proposed here. "Subscriptions" is an overloaded term but I'm essentially looking for a way to create and associate some state with a loader/fetcher and be able to clean up that state when it's no longer active. This is almost possible with router.subscribe but it's awkward and there does not appear to be any way to differentiate a loader call vs a fetcher.load.

For our purposes we need it to manage apollo watchQuery subscriptions and in a way that does not affect how the loader is written nor the components that consume useLoaderData, but this proposal is generic enough to be used for any other kind of client-side query library, caching mechanism, reactive shared loader-state that we don't want in search params , etc etc