react-chained-query

Features

useChainedQuery

useChainedQuery hook consit of a wrapper on top of react-query useQuery. This useChainedQuery hook allow chaining queries instead of runnning them concurently, it aims to solve problems that may occurs when hitting a slow backend with too many requests.

By managing a queue and executing the request one after another, it could give the capability for an application to display the information sequentially.

useChainedMutations

useChainedMutations hook chains mutations sequentially with retry support. It supports both static (pre-created) and dynamic (hook-based) mutations. Each step receives results from previous mutations to compute its variables.

Install

npm install @scality/react-chained-query

Quickstart

useChainedQuery

import { QueryClient, QueryClientProvider } from 'react-query';
import { ChainedQueryProvider, useChainedQuery } from '@scality/react-chained-query';

const queryClient = new QueryClient();

function Component1() {
  const { data } = useChainedQuery({
    queryKey: ['key', 'arg'],
    queryFn: async () => {
      await new Promise((resolve) => setTimeout(resolve, 2_000));
      return '1';
    },
  });
  return <>{data}</>;
}

function Component2() {
  const { data } = useChainedQuery({
    queryKey: ['key', 'arg1'],
    queryFn: async () => {
      await new Promise((resolve) => setTimeout(resolve, 1_000));
      return '2';
    },
  });
  return <>{data}</>;
}

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <ChainedQueryProvider>
        <div className="App">
          <h2>Hello, useChainedQuery! </h2>
          <Component1 />
          <Component2 />
        </div>
      </ChainedQueryProvider>
    </QueryClientProvider>
  );
}

A complete example here

useChainedMutations

Basic Usage (Static Mutations)

import { useMutation } from 'react-query';
import { useChainedMutations } from '@scality/react-chained-query';

const useUpdatePost = () => {
  return useMutation({
    mutationFn: async (id: string) => {
      const res = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`, {
        method: 'PUT',
        headers: { 'Content-type': 'application/json' },
        body: JSON.stringify({ id, title: 'foo', body: 'bar', userId: id }),
      });
      if (!res.ok) throw res.statusText;
      return res.json();
    },
  });
};

export default function App() {
  const updateUser1 = useUpdatePost();
  const updateUser2 = useUpdatePost();

  const { steps, isComplete, hasError, start } = useChainedMutations({
    mutations: [
      { id: 'user1', label: 'Update User 1', mutation: updateUser1 },
      { id: 'user2', label: 'Update User 2', mutation: updateUser2 },
    ],
    variables: {
      user1: () => '1',
      user2: (prev) => prev.user1.data.userId, // Access by key (recommended)
      // Or: (prev) => prev[0].data.userId    // Access by index (still supported)
    },
    autoStart: false,
  });

  return (
    <div>
      <button onClick={start}>Start</button>
      <ul>
        {steps.map((step) => (
          <li key={step.id}>
            {step.label}: {step.status}
            {step.status === 'error' && <button onClick={step.retry}>Retry</button>}
          </li>
        ))}
      </ul>
      {isComplete && <p>Done!</p>}
      {hasError && <p>Error occurred</p>}
    </div>
  );
}

Dynamic Mutations (for dynamic lists)

When you need to create mutations from a dynamic array (e.g., user-selected items), use hook instead of mutation:

const userIds = ['1', '2', '3']; // Could come from props or state

const { Slots, steps, start } = useChainedMutations({
  mutations: userIds.map((id) => ({
    id: `user-${id}`,
    label: `Update User ${id}`,
    hook: useUpdatePost, // Hook will be called internally for each mutation
  })),
  variables: Object.fromEntries(
    userIds.map((id, i) => [`user-${id}`, (prev) => (i === 0 ? id : prev[i - 1].data.userId)])
  ),
});

return (
  <>
    {Slots} {/* Required: renders hidden components that call hooks for dynamic mutations */}
    <button onClick={start}>Start</button>
  </>
);

API

| Config | Type | Description | |--------|------|-------------| | mutations | MutationConfig[] | Array with id, label, and either mutation (static) or hook (dynamic) | | variables | Record<string, (prev) => unknown> | Functions to compute variables. Access results via prev.mutationId.data (recommended) or prev[i].data. Note: Mutation ids should not be numeric strings ("0", "1") or array method names ("length", "push", "map", etc.) as they conflict with array properties. | | autoStart | boolean | Auto-start when ready. Default: true |

| Return | Type | Description | |--------|------|-------------| | Slots | ReactNode | Render this for dynamic mutations | | steps | StepStatus[] | { id, label, step, status, retry } | | isReady | boolean | All mutations registered | | isComplete | boolean | All succeeded | | hasError | boolean | Any failed | | start | () => void | Manual start | | reset | () => void | Reset chain state, allows start() again | | getResult | <T>(id: string) => T | Get mutation result |

Advanced Documentation

In order to use useChainedQuery in your component, it has be below QueryClientProvider and ChainedQueryProvider.

It's possibile to have several ChainedQueryProvider each of them would then holds it's own queue of queries.

<QueryClientProvider>
  <ChainedQueryProvider>
    <YourComponent />
  </ChainedQueryProvider>
</QueryClientProvider>

Made with ❤️ by Pod-UI at Scality