useQueue
This hook controls the dispatcher queues. It uses the Dispatcher to read the actual value
of the queue, which is based on the queryKey retrieved from the request passed as the first argument.
A prepared Request is the minimum requirement for useQueue.
- Queue control for requests: Manage and observe the queue of requests for a given
Requestinstance. - Fine-grained request lifecycle: Start, stop, and pause entire queues or individual requests.
- Real-time updates: Reactively track the state of all requests in the queue.
- Integration with Dispatcher: Leverages the
Dispatcherfor queue management and event updates. - Advanced queue strategies: Works best with
one-by-onedispatching and thequeuedoption enabled.
Quick Start
To use useQueue, provide a prepared Request instance. The hook returns the current queue state
and control methods.
import { useQueue } from "@hyper-fetch/react";
import { getUsers } from "./api/users";
function App() {
const { requests } = useQueue(getUsers);
return (
<div>
<ul>
{/* List of currently running requests */}
{requests.map((req) => (
<li key={req.requestId}>{req.requestOptions.endpoint}</li>
))}
</ul>
</div>
);
}
How it works
useQueue uses the request's queryKey to read and control the Dispatcher queue. It subscribes to Dispatcher
events to keep the queue state up to date. This hook is ideal for advanced scenarios where you need to:
- Control the execution order of requests
- Pause, stop, or resume queued requests
- Monitor the status of all requests in a queue
- Integrate with custom queueing strategies
It works best with the one-by-one dispatching mode and when the queued option is set to true on the request.
Remember to ensure your request's queryKey is static when using this hook. If your request uses dynamic params or
query params, auto-generated keys may cause incorrect queue tracking. Provide a custom queryKey when creating the
request to avoid this issue.
Controlling the Queue
The hook returns methods to control the queue and individual requests:
const { requests, stopped, stop, start, pause } = useQueue(getUsers);
// Control all requests in the queue
top(); // Stops the queue
pause(); // Pauses the queue
start(); // Starts the queue
// Control individual requests
requests.forEach((req) => {
req.stopRequest();
req.startRequest();
});
Read more about the differences between stop, pause, and start in the Dispatcher
documentation.
Options
Customize the behavior of useQueue by passing an options object as the second argument.
const { ... } = useQueue(request, options);
| Name | Type | Description |
|---|---|---|
| dispatcherType | | |
| keepFinishedRequests | |
Returns
useQueue returns an object with the current queue state, control methods, and request helpers.
const values = useQueue(request);
| Name | Type | Description |
|---|---|---|
| dispatcher | | Request dispatcher instance |
| requests | | List of requests for provided request |
| stopped | | Queue status for provided request |
| pause | | Callback which allow to pause queue. It will allow ongoing requests to be finished, but will stop next from being send. |
| start | | Callback which allow to start queue. |
| stop | | Callback which allow to stop queue, it will cancel ongoing requests. |
Request interface
| Name | Type | Description |
|---|---|---|
| request | | |
| requestId | | |
| resolved | | Resolved when we receive response |
| retries | | |
| stopped | | |
| timestamp | | |
| canceled | | |
| downloading | | Downloading progress for given request |
| failed | | |
| removed | | |
| success | | |
| uploading | | Uploading progress for given request |
| deleteRequest | | Removes request from the queue |
| startRequest | | Callback which allow to start previously stopped request. |
| stopRequest | | Callback which allow to stop request and cancel it if it's ongoing. |