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

  // ...
}

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`

Name
`T`

HTTPError

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

Hierarchy

Error

↳ HTTPError

See

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

Parameters

Name	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Name	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns

void

Inherited from

Error.captureStackTrace

@emdgroup/react-query

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads