@draftup/react-use-promise v1.0.2

React use promise

Custom React hook to manage promises.

Install

npm i -S @draftup/react-use-promise

Highlights

• Automatic promise cancellation:
  • when componet has been unmounted,
  • when another promise has been injected.
• React way error handling.
• Typescript and Flow type definitions included.

Usage

Basic example

usePromise is a custom React hook:

const [promiseState, promiseInjector] = usePromise();

Upon it's initialization promiseState is null. Once you inject a promise using promiseInjector first time promiseState becomes an object with a following signature:

type PromiseState<ValueType> = {
  pending: boolean;
  resolved: boolean;
  rejected: boolean;
  value: null | ValueType;
  error: null | Error;
};

Here's a simple example of how to use usePromise hook in your React component:

import { usePromise } from "@draftup/react-use-promise";

const submitService = async () => {
  // Some kind of asynchronous operation goes here.
};

const Component = () => {
  const [promiseState, injectPromise] = usePromise();

  const handleClick = React.useCallback(() => {
    injectPromise(submitService());
  }, [injectPromise]);

  if (promiseState && promiseState.pending) {
    return <span>processing...</span>;
  }

  if (promiseState && promiseState.resolved) {
    return <span>succeeded</span>;
  }

  if (promiseState && promiseState.rejected) {
    return <span>failed</span>;
  }

  return <button onClick={handleClick}>submit</button>;
};

Error handling

By default usePromise will throw away any instance of Error constructor that was either throwed or returned by injected promise. You should take care of this errors by using error boundaries:

const submitService = async () => {
  throw new Error("Error message");
};

const Root = () => (
  <ErrorBoundary>
    <Component />
  </ErrorBoundary>
);

const Component = () => {
  const [promiseState, injectPromise] = usePromise();

  const handleClick = React.useCallback(() => {
    injectPromise(submitService());
  }, [injectPromise]);

  // Error instance will be throwed away and will bubble up
  // to the closest error boundary you set.

But there are cases when you want to handle some errors locally. To make it possible there are an errorsToKeep option you can pass on hook initialization. It takes an array of error constructors whose instances you want to handle locally:

const [promiseState, injectPromise] = usePromise({
  errorsToKeep: [MyError]
});

With above configuration any instance of MyError throwed or returned by promise will end up in a promiseState.error property so you can handle it locally:

const submitService = async () => {
  throw new MyError("My error message");
};

const Component = () => {
  const [promiseState, injectPromise] = usePromise({
      errorsToKeep: [MyError]
  });

  const handleClick = React.useCallback(() => {
    injectPromise(submitService());
  }, [injectPromise]);

  if (promiseState && promiseState.error) {
    return(
        <span>{promiseState.error.message}</span>
    )
  }

  // ...

Take a note that your custom error constructors must be inherited from native Error constructor if you are going to throw them from inside you promise:

// This will end up with a custom TypeError throwed away:
// class MyError {}

class MyError extends Error {}

const submitService = async () => {
  throw new MyError("My error message");
};

License

This project is MIT licensed.