useAsync

import { useAsync } from "@prestojs/util";

useAsync(fn,options)

Hook to deal with triggering async function calls and handling result / errors and loading states.

This can be used in two distinct modes:

manual (useAsync.MANUAL) - the function is only triggered explicitly
automatic (useAsync.DEEP or useAsync.SHALLOW) - the function is triggered initially and then automatically when argument values change (using a shallow or deep comparison).

For mutations you usually want manual as it is triggered in response to some user action like pressing a button.

For data fetching you usually want automatic mode as you retrieve some data initially and then refetch it when some arguments change (eg. the id for a single record or the filters for a list).

Examples

Fetch and render a specified github profile

function FollowerCount() {
  const [user, setUser] = React.useState("octocat");
  const {
    result,
    isLoading,
    error,
    run,
    reset
  } = useAsync(() => getGithubUser(user));
  return (
    <div>
      <input
        value={user}
        onChange={e => setUser(e.target.value)}
      />
      <div className="my-2 justify-between flex">
        <button
          onClick={run}
          disabled={isLoading}
          className="btn-blue"
        >
          Query follower count
        </button>
        <button className="btn" onClick={reset}>
          Clear
        </button>
      </div>
      {result && (
        <p>
          <img src={result.avatar_url} />
          <br />
          {result.name} has {result.followers} followers
        </p>
      )}
      {error && (
        <p>
          Failed with status: {error.status}{" "}
          {error.statusText}
        </p>
      )}
    </div>
  );
}
function getGithubUser(user) {
  return fetch(
    `https://api.github.com/users/${user}`
  ).then(r => {
    if (r.ok) {
      return r.json();
    }
    throw r;
  });
}function FollowerCount() {
  const [user, setUser] = React.useState("octocat");
  const {
    result,
    isLoading,
    error,
    run,
    reset
  } = useAsync(() => getGithubUser(user));
  return (
    <div>
      <input
        value={user}
        onChange={e => setUser(e.target.value)}
      />
      <div className="my-2 justify-between flex">
        <button
          onClick={run}
          disabled={isLoading}
          className="btn-blue"
        >
          Query follower count
        </button>
        <button className="btn" onClick={reset}>
          Clear
        </button>
      </div>
      {result && (
        <p>
          <img src={result.avatar_url} />
          <br />
          {result.name} has {result.followers} followers
        </p>
      )}
      {error && (
        <p>
          Failed with status: {error.status}{" "}
          {error.statusText}
        </p>
      )}
    </div>
  );
}
function getGithubUser(user) {
  return fetch(
    `https://api.github.com/users/${user}`
  ).then(r => {
    if (r.ok) {
      return r.json();
    }
    throw r;
  });
}

	Parameter	Type	Description
*	fn	Function	A function that returns a promise. When `trigger` is `MANUAL` this is only called when you manually call the returned `run` function, otherwise it's called initially and then whenever an equality comparison fails between previous arguments and new arguments. Note that when `trigger` is `SHALLOW` or `DEEP` changes to this function will cause it to be called again so you must memoize it (eg. with `useCallback`) if it's defined in your component or hook. To help detect runaway effects caused by this automatically consider using stop-runaway-react-effects.
	options.args	Array	Arguments to be passed to asyncFn when it is called. Can be empty. If you are using `trigger` of `MANUAL` then it's usually simpler to just pass the arguments in `fn` manually (eg. by defining an arrow function inline). When using other values of `trigger` the value of `args` is compared and will trigger a call to `fn` when a change is detected according to the comparison logic of the selected `trigger`.
	options.onError	Function	Called when action errors. Passed the error returned from async action. See note above on `onSuccess` for behaviour when component has unmounted.
	options.onSuccess	Function	Called when action resolves successfully. Is passed a single parameter which is the result from the async action. NOTE: If your component unmounts before the promise resolves this function will NOT be called. This is to avoid the general case of calling React state transition functions on an unmounted component. If you want the method to be called regardless then attach your own callbacks to the promise when you call `run` or in the async function definition itself.
	options.trigger	"MANUAL"\|"SHALLOW"\|"DEEP"	Determines when the function is called. Defaults to `MANUAL`. NOTE: If changing from MANUAL then the function will be called immediately regardless useAsync.MANUAL (default) - only called when you explicitly call `run` useAsync.SHALLOW - called whenever a shallow equality check fails. Compares previous async function, and `option.args`. Passing an inline function (eg. `useAsync(() => ...)`) or an inline object to args (eg. `useAsync(fn, { args: { filter: 1 } })`) with this option will result in an infinite loop because each render dynamically creates a new object and only object identity is checked; use `useMemo` or `useCallback` in these cases. useAsync.DEEP - called whenever a deep equality check fails. Compares previous async function and `option.args`. Slower than `shallow` but works with objects that may change every render. Passing an inline function (eg. `useAsync(() => ...)`) with this option will result in an infinite loop as a new function is created each render and a deep equality check on this will always fail; use `useCallback` in those cases.

Returns

UseAsyncReturnObject

Key	Type	Description
error	ErrorT\|null	Set to the rejected value of the promise. Only one of `error` and `result` can be set. If `isLoading` is true consider this stale (ie. based on previous props). This can be useful when you want the UI to show the previous value until the next value is ready.
isLoading	boolean	True when action is in progress.
reset	Function	When called will set both result or error to null. Will not immediately trigger a call to the action but subsequent changes to `fn` or `options.args` will according to the value of `trigger`.
response	ResultT\|null	Deprecated: Use `result` instead
result	ResultT\|null	Set to the resolved value of promise. Only one of `error` and `result` can be set. If `isLoading` is true consider this stale (ie. based on previous props). This can be useful when you want the UI to show the previous value until the next value is ready (for example showing the previous page of a paginated table with a loading indicator while next page is loading).
run	Function	A function to manually trigger the action. If `options.trigger` is `useAsync.MANUAL` calling this function is the only way to trigger the action. You can pass arguments to `run` which will override the defaults. If no arguments are passed then `options.args` will be passed by default (if supplied). This function will return a promise that resolves/rejects to same value resolved/rejected from the async action.