Proposal - useSequentialQueries

[Newbie012]

• See stackblitz for API implementation (type-safe, but no actual runtime).
• See original tweet for reference
• Related blog post

The issue

When we have dependent queries inside the same component, we have a few ways to tackle it:

1. Set enabled based on the previous query with type assertions or code validation (since TypeScript can't know based on the enabled property if the previous query data is ready or not:

function Component(props: { postId: number }) {
  const api = useApi();
  const postQuery = useQuery(postQueries.byId({ api, postId: props.postId }));
  const authorQuery = useQuery({
    enabled: !!postQuery.data?.authorId,
    ...authorQueries.byId({ api, authorId: postQuery.data!.authorId })
  });

  // ...
}

2. Move the dependent query to a child

function ComponentA(props: { postId: number }) {
  const api = useApi();
  const postQuery = useQuery(postQueries.byId({ api, postId: props.postId }));

  if (!postQuery.data) {
      return /* ... */;
  }

  return <ComponentB post={postQuery.data} />
}

function ComponentB(props: { post: Post }) {
  const api = useApi();
  const authorQuery = useQuery(authorQueries.byId({ api, authorId: postQuery.data!.authorId }));

  // ...
}

3. Hoist the previous query to a HOC:

function WithPost(params: { postId: number}, Component: React.FC<{ post: Post }>) {
  const api = useApi();
  const postQuery = useQuery(postQueries.byId({ api, postId: params.postId }));

  if (!postQuery.data) {
      return /* ... */;
  }

  return <Component post={postQuery.data} />
}

function Component(props: { post: Post }) {
  const api = useApi();
  const authorQuery = useQuery(authorQueries.byId({ api, authorId: postQuery.data!.authorId }));

  // ...
}

function ComponentWithPost(props: { postId: number }) {
  return <WithPost postId={props.postId} Component={Component} />
}

All of these approaches come with a cost. Either it impacts your DX or your UX.

---

The proposal - useSequentialQueries

A custom hook that invokes queries in a sequential way (one after another) while granting each query access to the previous queries.

For instance:

function Component(props: { postId: number }) {
  const api = useApi();
  const { author, post } = useSequentialQueries(
      ["post", () => postQueries.byId({ api, postId: props.postId })],
      ["author", ({ post }) => authorQueries.byId({ api, authorId: post.authorId })]
  );

  if (!post.data || !author.data) {
      return /* ... */;
  }

  return `${post.data.title} by ${author.data.name}`;
}

I'll break down what's going on here:

• We first invoke useSequentialQueries with a dynamic amount of arguments.
• Each argument is a tuple of [query name, query payload]:

["MyFirstQuery", () => ({ queryKey: ["..."], queryFn: () => ... })]

• Each query can access the previous queries data by the name we supplied to them:

["MyFirstQuery", () => ({ queryKey: ["first"], queryFn: () => ... })],
["MySecondQuery", (prev) => ({ queryKey: ["second"], queryFn: () => foo(prev.MyFirstQuery.foo) })]

• We can get the results of the queries by the names we supplied previously:

const { MyFirstQuery, MySecondQuery } = useSequentialQueries(
  ["MyFirstQuery", () => ...],
  ["MySecondQuery", ({ post }) => ...]
);

Edge cases

• future queries should be marked as "idle"
• if the first query has failed, only this query should be marked as "error" while the rest should stay "idle"

[TkDodo]

Just for reference: there is no idle state anymore in v4.

why would we need the tuple syntax (with a name) if we could just do:

const [author, post] = useSequentialQueries([
  () => postQueries.byId({ api, postId: props.postId })],
  ({ authorId }) => authorQueries.byId({ api, authorId })]
]);

where each entry would get, as an input, the result of the queryFn of the previous query. Of course, if you need access to the post in a third query, you would have to add it to the result of the second query. But that is totally possible by just adding it to the result of the queryFn.

[Newbie012]

Thanks for the feedback 🙂

We don't really need a name with a tuple. While it adds a little complexity to the API, it makes it easier to access to all of the previous queries without pushing it to the queryFn. My inspiration came from fp-ts' Do notation (bind).

About the idle status - since it doesn't exist anymore, how would you approach it? return undefined until the query will be invoked?

[TkDodo]

About the idle status - since it doesn't exist anymore, how would you approach it? return undefined until the query will be invoked?

I think we should return full query objects for every query, so it would be in loading status with isFetching: false.

[Newbie012]

Sounds logical. It took me a while to respond back because I'm not sure anymore if this is the right approach to solve all of the dependent queries. I had a case where I had 3 dependent queries on a single one, but I'm afraid that this kind of API would be too complex.

[artem-malko]

Hey, @Newbie012 sorry for breaking in, but is the problem with "Move the dependent query to a child"? Looks like you will have better application in a such way? Moreover, React team recommends to split your components as much as you can) So, what is a cost of this idea?

[artem-malko]

Thx for the answer.

As you said, you are trying to render a "page" component as soon, as possible, but sequential queries do not allow you to do that. More over, all of your children in the "page" component will be waiting for all data.

In other hand, you can render the "page" a part by part, when you have data.

But it might be, that I didn't catch your idea. Can you give me an example?

[Newbie012]

I accidentally omitted the second part of my comment - the page should accept partial data. You could do that in a single component as well, but you'll have to do some manual type assertions which will break your type safety which will possibly cause a runtime error next time a dev will apply some changes on that component.

[artem-malko]

Hm, I still can not get it)

Let's imagine, you have a post page with author info and comments. So, my idea here is to fetch only a post. When it is ready, we can fetch author info and comments. Something like this:

// @page

const Page = () => {
  const postData = useQuery(post);
  
  // Handle loading/error state 
 
  return <>
    <Post data={postData} />
  </>;
}

// @Post


const Post = (post) => {
  return <>
    <Author id={post.data.authorId} />
    <h1>{post.data.title}</h1>
    <p>{post.data.content}</p>
    <Comments id={post.data.postId} />
  <>;
}

Author and Comments has its own useQuery calls. Moreover, every comment can have its own useQuery call, if you need. In that case we will see the post before author and comments queries are ready. And no any problems with types)
If you need to render title with author name, we can render just a title, while author query is in a loading state.

In your idea with SequentialQueries, we have to wait for all of the queries just to see the post — the main thing a user needs.

[Newbie012]

The returned value from the hook is not a single query response, but rather an object of keys which each key indicates a query. In other words, we don't have to wait for all of the queries, you have full control and how you manipulate your data:

// ignore the syntax for now (see @TkDodo comment)
const { author, post } = useSequentialQueries(
    ["post", () => postQueries.byId({ api, postId: props.postId })],
    ["author", ({ post }) => authorQueries.byId({ api, authorId: post.authorId })]
);

post;
// ^? UseQueryResult<...>
console.log(post.isLoading) // logs: true, false, false

author;
// ^? UseQueryResult<...>
console.log(author.isLoading) // logs: true, true, false

The whole idea of useSequentialQueries is to allow you to write dependent queries inside the component without any "hacky" solutions such as { enabled: post.data !== undefined, queryKey: ["author", post.data?.authorId] }.

While I understand your point of separating each logic into its own component, I'm not a fan of invoking network requests inside child components, for the following reasons:

1. Potentially, it can cause unnecessary network waterfalls (in this specific case it's not relevant since the queries are dependent).
2. In the future, you may want to render a list of <Author />, but you don't want to create an X amount of network requests (you could simply query a single endpoint that returns authors instead).

I'm aware that these reasons sound like premature optimizations or that my approach comes with some drawbacks (like any other approach), but this is the only approach that worked for me that didn't require any refactors for the past years that I'm using React.

Hopefully I made my point clearer 🙂

[artem-malko]

Yeah, I understand you. I do not agree with you, but I understand =)

Let's see, what maintainers will decide)