@emdgroup/react-query

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}`;
}

Lazy Queries

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 });

  // ...
}

Hooks

• useCachedQuery
• useQuery
• useOnlineStatus

Functions

• isHTTPError

Classes

• HTTPError

Interfaces

• QueryResponse
• RequestOptions

Type Aliases

QueryStatus

Ƭ QueryStatus: "success" | "loading" | "error" | "idle"

Status of the request. Starts out with idle, then transitions from loading to either success or error.

Variables

querystring

• Const querystring: Object = qs

Implementation of the NodeJS querystring module for the browser.

Type declaration

| 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 |

Functions

isHTTPError

▸ 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.

Parameters

| Name | Type | | :------ | :------ | | error | unknown | | status? | number |

Returns

error is HTTPError

sleep

▸ 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.

Parameters

| Name | Type | | :------ | :------ | | ms | number | | signal? | null | AbortSignal |

Returns

Promise<void>

useCachedQuery

▸ 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).

Type parameters

| Name | | :------ | | T |

Parameters

| Name | Type | | :------ | :------ | | path | string | | request | RequestOptions |

Returns

QueryResponse<T>

useOnlineStatus

▸ 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();

Returns

boolean

useQuery

▸ 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);
}

Type parameters

| Name | | :------ | | T |

Parameters

| Name | Type | | :------ | :------ | | path | string | | request | RequestOptions |

Returns

QueryResponse<T>

RequestOptions

The request options extends the options from the fetch API with retry, retryMs and queryParameters.

Properties

body

• 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.

cache

• Optional cache: RequestCache

A string indicating how the request will interact with the browser's cache to set request's cache.

credentials

• 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.

headers

• Optional headers: HeadersInit

A Headers object, an object literal, or an array of two-item arrays to set request's headers.

integrity

• Optional integrity: string

A cryptographic hash of the resource to be fetched by request. Sets request's integrity.

keepalive

• Optional keepalive: boolean

A boolean to set request's keepalive.

method

• Optional method: null | string

A string to set request's method.

mode

• 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.

parseBody

• 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.

queryParameters

• Optional queryParameters: URLSearchParams | Record<string, string>

Optional query parameters that will be encoded and appended to the URL.

redirect

• 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.

referrer

• Optional referrer: string

A string whose value is a same-origin URL, "about:client", or the empty string, to set request's referrer.

referrerPolicy

• Optional referrerPolicy: ReferrerPolicy

A referrer policy to set request's referrerPolicy.

retry

• Optional retry: number

Number of times a request with a 429 status code us retried. Defaults to 3.

retryMs

• 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.

signal

• Optional signal: null | AbortSignal

An AbortSignal to set request's signal.

window

• Optional window: null

Can only be null. Used to disassociate request from any Window.

QueryResponse

Response object returned from useQuery and useCachedQuery.

Type parameters

| Name | | :------ | | T |

Properties

error

• Optional error: Error

Error object, available when status is error.

response

• Optional response: T

Response object from the server.

revalidate

• revalidate: () => void

Type declaration

▸ (): void

Function to call to request a refresh of the query.

Returns

void

status

• Optional status: QueryStatus

Status of the request.

HTTPError

If the server responds with an HTTP error (status code > 399) then a HTTPError exception is thrown.

Hierarchy

• Error

  ↳ HTTPError

Properties

response

• response: any

The response body if available.

status

• status: number

HTTP status code of the error response.

prepareStackTrace

▪ Static Optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any

Type declaration

▸ (err, stackTraces): any

Optional override for formatting stack traces

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Parameters

| Name | Type | | :------ | :------ | | err | Error | | stackTraces | CallSite[] |

Returns

any

Inherited from

Error.prepareStackTrace

Methods

captureStackTrace

▸ Static captureStackTrace(targetObject, constructorOpt?): void

Create .stack property on a target object

Parameters

| Name | Type | | :------ | :------ | | targetObject | object | | constructorOpt? | Function |

Returns

void

Inherited from

Error.captureStackTrace