React hooks for the fetch API with support for client-side caching
Usage:
import { useCachedQuery, isHTTPError } from '@emdgroup/react-query';
const { status, response, revalidate, error } = useCachedQuery<{ email: string }>('http://example.com/userinfo');
function Profile() {
if (status === 'loading') return 'Loading';
if (isHTTPError(error, 404)) return 'Not found';
if (error) return 'Unknown error';
return `Hello ${response?.email}`;
}To enable a query at a later time (for example if the query depends on a previous query),
the method can be set to null which will effectively defer the query until the query
method is defined.
function ToDos() {
const [filter, setFilter] = useState(false);
const { response } = useQuery('/todos', { method: filter ? 'GET' : null });
// ...
}Ƭ QueryStatus: "success" | "loading" | "error" | "idle"
Status of the request. Starts out with idle, then transitions from loading
to either success or error.
• Const querystring: Object = qs
Implementation of the NodeJS querystring module for the browser.
| Name | Type |
|---|---|
decode |
(str?: string, sep: string, eq: string, options: ParseOptions) => ParsedUrlQuery |
encode |
(obj?: ParsedUrlQueryInput, sep: string, eq: string) => string |
parse |
(str?: string, sep: string, eq: string, options: ParseOptions) => ParsedUrlQuery |
stringify |
(obj?: ParsedUrlQueryInput, sep: string, eq: string) => string |
▸ isHTTPError(error, status?): error is HTTPError
Type guard for the error response returned by the useQuery and useCachedQuery hooks.
The function returns true if the server returns an HTTP error with an error code. A Network error
is not an HTTP error and will not return true when passed to this function.
| Name | Type |
|---|---|
error |
unknown |
status? |
number |
error is HTTPError
▸ sleep(ms, signal?): Promise<void>
Sleep function that supports an optional AbortSignal. If the signal is aborted
the returned Promise will immediately reject with a DOMException and name AbortError.
| Name | Type |
|---|---|
ms |
number |
signal? |
null | AbortSignal |
Promise<void>
▸ useCachedQuery<T>(path, request): QueryResponse<T>
useCachedQuery accepts the same parameters as useQuery. It will
immediately return the cached result if it exists for GET requests and set the
status to success. The request will still be performed and the response is
updated once the request is complete. Any failed request will clear the cache.
The response is cached in the browser's localStorage (if available).
| Name |
|---|
T |
| Name | Type |
|---|---|
path |
string |
request |
RequestOptions |
▸ useOnlineStatus(): boolean
useOnlineStatus will return a boolean that indicates if the user is currently online. This useful
if you want to prevent the browser to make requests or redirects that will fail. Note that this
is not a reliable way to determine if the user is online. See
navigator.onLine for more details.
This hook will listen to changes to the online status and will update accordingly.
const online = useOnlineStatus();boolean
▸ useQuery<T>(path, request): QueryResponse<T>
useQuery<T> is a generic hook for making fetch requests. The type T is the type of the response body.
const { status, response, revalidate, error } = useQuery<{ email: string }>('http://example.com/userinfo');
useEffect(() => {
if (status === 'success') {
// do something with response
} if (status === 'error') {
// do something with error
}
}, [status, response, error]);
return status === 'success' ? (<p>Email: {response.email}</p>) : (<p>Loading</p>);For authenticated requests that require a custom header, consider creating a custom hook that passes the
header using a useMemo hook:
function useApi<T>(...[method, path, body]: Parameters<typeof useQuery>) {
const { token } = useUser();
const header = useMemo(() => ({ Authorization: `Bearer ${token}` }), [token]);
return useQuery<T>(method, path, body, header);
}| Name |
|---|
T |
| Name | Type |
|---|---|
path |
string |
request |
RequestOptions |
The request options extends the options from the fetch API with retry, retryMs and queryParameters.
• Optional body: Body
A BodyInit object or null to set request's body. If the body is a plain object it will be serialized as JSON.
• Optional cache: RequestCache
A string indicating how the request will interact with the browser's cache to set request's cache.
• Optional credentials: RequestCredentials
A string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL. Sets request's credentials.
• Optional headers: HeadersInit
A Headers object, an object literal, or an array of two-item arrays to set request's headers.
• Optional integrity: string
A cryptographic hash of the resource to be fetched by request. Sets request's integrity.
• Optional keepalive: boolean
A boolean to set request's keepalive.
• Optional method: null | string
A string to set request's method.
• Optional mode: RequestMode
A string to indicate whether the request will use CORS, or will be restricted to same-origin URLs. Sets request's mode.
• Optional parseBody: boolean
Make an attempt to parse the body. If the content type of the response is application/json, body is a JSON object, text otherwise. Set to false if you need to read the response yourself. Defaults to true.
• Optional queryParameters: URLSearchParams | Record<string, string>
Optional query parameters that will be encoded and appended to the URL.
• Optional redirect: RequestRedirect
A string indicating whether request follows redirects, results in an error upon encountering a redirect, or returns the redirect (in an opaque fashion). Sets request's redirect.
• Optional referrer: string
A string whose value is a same-origin URL, "about:client", or the empty string, to set request's referrer.
• Optional referrerPolicy: ReferrerPolicy
A referrer policy to set request's referrerPolicy.
• Optional retry: number
Number of times a request with a 429 status code us retried. Defaults to 3.
• Optional retryMs: number
Milliseconds to wait before the next request is retried. Subsequent requests will be multiplied by Math.LOG2E. A random jitter of 50% of the retryMs value is applied.
• Optional signal: null | AbortSignal
An AbortSignal to set request's signal.
• Optional window: null
Can only be null. Used to disassociate request from any Window.
Response object returned from useQuery and useCachedQuery.
| Name |
|---|
T |
• Optional error: Error
Error object, available when status is error.
• Optional response: T
Response object from the server.
• revalidate: () => void
▸ (): void
Function to call to request a refresh of the query.
void
• Optional status: QueryStatus
Status of the request.
If the server responds with an HTTP error (status code > 399) then a HTTPError exception is thrown.
-
Error↳
HTTPError
• response: any
The response body if available.
• status: number
HTTP status code of the error response.
▪ Static Optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any
▸ (err, stackTraces): any
Optional override for formatting stack traces
See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
| Name | Type |
|---|---|
err |
Error |
stackTraces |
CallSite[] |
any
Error.prepareStackTrace
▸ Static captureStackTrace(targetObject, constructorOpt?): void
Create .stack property on a target object
| Name | Type |
|---|---|
targetObject |
object |
constructorOpt? |
Function |
void
Error.captureStackTrace