Futures: Making queries composable (mapping, combining)

[GiacoCorsiglia]

First: fantastic library with super thorough documentation, thank you :)

I'm curious if thought has been given to formalizing the UseQueryResult as The Way to represent async state in React/rendering libraries in general. For now, let's call this type a Future and explore some (I think) useful things we can do. I've used something like this successfully in two separate professional projects.

The minimal definition of a Future might look something like this:

type Future<TData = unknown, TError = unknown> = {
  isLoading: boolean;
  data: TData | undefined;
  error: TError | undefined;
};

This is compatible with both TanStack Query and also SWR. Of course, the real version would need to give thought to the other properties on UseQueryResult (likely, UseQueryResult extends Future with extra properties). It might also be nice to make this a discriminated union somehow.

There are (at least) 3 useful things we can do with this.

mapFuture: transforming query results

mapFuture is like Promise#then for a Future. A simplistic version looks like this:

function mapFuture<TData, TError, UData>(
  future: Future<TData, Terror>,
  mapData: (data: TData) => UData
): Future<UData, TError> {
  // If the data is loaded, transform it.
  if (future.data) {
    return { ...future, data: mapData(future.data) };
  }

  // Otherwise, do nothing.
  return future;
}

This lets you transform the result of your query on the client while preserving the loading state. For example:

// Loads products in the given categories.
function useProducts(categories: string[]) {
  // But the API doesn't support a category filter!
  const products = useQuery({
    queryKey: ["/products"],
    queryFn: () => fetch("/products")
  });
  // So we need to filter on the client.  Might wrap with useMemo().
  return mapFuture(products, (data) => {
    return data.filter((product) => categories.includes(product.categoryId))
  });
}

Sure, you can totally do this in all the components that call useProducts, once they have checked if products.data has loaded, but I would rather encapsulate that in the useProducts hook.

mapFuture can be extended to allow transforming the error, too, similar to how Promise#then supports a second argument that works like Promise#catch.

I think mapFuture makes the Future type a "Functor".

Maybe mapFuture is implemented as a method on Future instead (i.e., products.map() instead of mapFuture(products)).

combineFutures: Like Promise.all for Futures.

You can merge the results of multiple queries in arbitrary ways using combineFutures.

type AllValues<Fs extends Future[], Prop extends "data" | "error"> = {
  [i in keyof Fs]: NonNullable<Fs[i][Prop]>;
}; // This is a mapped tuple.

function combineFutures<Fs extends Future[], TData>(
  futures: [...Fs],
  combineData: (...args: AllValues<Fs, "data">) => TData
): Future<TData, AllErrors<Fs, "error">> {
  // Something along these lines (with more care given to edge cases).
  return {
    isLoading: futures.some((future) => future.isLoading),
    data: combineData(...futures.map((future) => future.data)),
    error: futures.map((future) => future.error),
  };
}

This is similar to, but not the same as, useQueries(), which supports a combine argument. The benefit of having a separate function is that things compose more cleanly. For example,

type HydratedProduct = Product & { category: Category };

function useHydratedProducts(categories: string[]): Future<HydratedProduct[]> {
  // Load products using our hook from above.
  // That hook calls `mapFuture`, but we don't need to care.
  const products = useProducts(categories);

  // Load categories---presumably another useQuery() under the hood.
  const categories = useCategores(categories);

  return combineFutures(
    [products, categories],
    (products, categories) => {
      return products.map((product) => ({
        ...product
        category: categories.find((category) => category.id === product.categoryId)
      });
    },
  );
}

I'm sure there is a functional programming term for combineFutures.

Creating a Future without useQuery().

Occasionally, there are scenarios where you have async state but don't want or need useQuery(). This is why it's useful to have a standalone Future concept—outside of UseQueryResult. For example:

function useHeavyLibrary(): Future<import("heavy-library")> {
  const [library, setLibary] = useState();

  useEffect(() => {
    import("heavy-library").then((library) => setLibrary(library))
  }, []);

  return {
    isLoading: !Boolean(library),
    data: library,
  }
} 

You can compose this with other Futures (e.g., using combineFutures), some of which may have come from useQuery(). Also, if you have implemented, for example, a component that shows a loading state when waiting for the result of a useQuery(), you can use that same component to wait for the heavy library to load—because that component expects a Future.

I would love to hear others' thoughts on this idea.

[TkDodo]

for mapFuture, we have select
for combineFutures, we have useQueries with combine

if you want to build this, I think you can do it in user-land, but I don’t think I want to introduce those concepts into react-query itself.