async-error-boundary

A React error boundary component library for handling asynchronous errors. It allows easy management of HTTP errors and displays custom error fallbacks.

Installation

You can install the package using npm:

npm install async-error-boundary

Or if you're using yarn:

yarn add async-error-boundary

Usage

ErrorBoundary Component

Use the ErrorBoundary component to catch and handle errors occurring in its child components.

import { ErrorBoundary } from 'async-error-boundary';
import ErrorFallback from './ErrorFallback';

function App() {
  return (
    <ErrorBoundary
      fallback={ErrorFallback}
      onReset={() => { navigate('/') }}
    >
      <ApiComponent />
    </ErrorBoundary>
  );
}

ErrorBoundary Properties

Name	Type	Required	Description
fallbackComponent	React.ComponentType<ErrorProps>	Yes	Fallback component to display when an error occurs
onReset	() => void	Yes	Function to reset the error state
children	React.ReactNode	Yes	Child components to be wrapped

HTTPError Class

Use the HTTPError class to create and handle HTTP errors.

import { HTTPError } from 'async-error-boundary';

try {
  const response = await fetch("api/endpoint");
  if (!response.ok) {
    const errorData = await response.json();
    throw new HTTPError(response.status, errorData.message);
  }
} catch (error) {
  if (error instanceof Error) {
    throw error;
  } else {
    throw new HTTPError(400);
  }
}

HTTPError Constructor

constructor(statusCode: number, message?: string)

Name	Type	Required	Description
statusCode	number	Yes	HTTP status code
message	string	No	Error message (uses default error message if not provided)

Custom Error Fallback Component

Create a custom error fallback component using the ErrorProps type. It's important to set a default value for statusCode as it may be undefined if the error is not an instance of HTTPError.

import { ErrorProps } from "async-error-boundary";

const HTTP_ERROR_MESSAGE = {
  404: {
    HEADING: "404",
    BODY: "The page you requested could not be found.",
    BUTTON: "Go to Home",
  },
  500: {
    HEADING: "Server Error",
    BODY: "An error occurred on the server. Please try again later.",
    BUTTON: "Refresh",
  },
  400: {
    HEADING: "Bad Request",
    BODY: "The request was invalid. Please check and try again.",
    BUTTON: "Go to Home",
  },
};

const ErrorFallback = ({ statusCode = 404, resetError, message }: ErrorProps) => {
  // Set a default value of 404 for statusCode.
  // This handles cases where the error is not an HTTPError and statusCode is undefined.
  const currentStatusCode = statusCode as keyof typeof HTTP_ERROR_MESSAGE;
  const { HEADING, BODY, BUTTON } = HTTP_ERROR_MESSAGE[currentStatusCode];
  
  return (
    <div>
      <h1>{HEADING}</h1>
      <p>{BODY}</p>
      <button onClick={resetError}>{BUTTON}</button>
      {message && <div>{message}</div>}
    </div>
  );
};

export default ErrorFallback;

API

<ErrorBoundary>

A React component that catches and handles errors.

Props

Name	Type	Required	Description
fallbackComponent	React.ComponentType<ErrorProps>	Yes	Fallback component to display when an error occurs
onReset	() => void	Yes	Function to reset the error state
children	React.ReactNode	Yes	Child components to be wrapped

HTTPError

A class representing HTTP errors.

Properties

Name	Type	Description
name	string	Always set to "HTTPError"
statusCode	number	HTTP status code
message	string	Error message

Methods

Name	Return Type	Description
constructor	HTTPError	Creates an instance of HTTPError with a status code and an optional error message.

ErrorProps

The type of properties passed to the error fallback component.

interface ErrorProps {
  statusCode?: number;
  resetError?: () => void;
  message?: string;
}

Name	Type	Required	Description
statusCode	number	No	HTTP status code. Undefined if not provided.
resetError	() => void	No	Function to reset the error state. Provided by ErrorBoundary.
message	string	No	Error message. Undefined if not provided.

Example

Using HTTPError in an API Component

import { useEffect } from "react";
import { HTTPError } from "async-error-boundary";

const DEFAULT_STATUS_CODE = 400;

const ApiComponent = () => {
  useEffect(() => {
    const fetchData = async () => {
      try {
        const response = await fetch("api/endpoint");
        if (!response.ok) {
          const errorData = await response.json();
          throw new HTTPError(response.status, errorData.message);
        }
      } catch (error) {
        if (error instanceof Error) {
          throw error;
        } else {
          throw new HTTPError(DEFAULT_STATUS_CODE);
        }
      }
    };

    fetchData();
  }, []);

  return <div>ApiComponent</div>;
};

export default ApiComponent;

In this example, errors occurring during the API call are handled using HTTPError. The ErrorBoundary will catch this error and display the appropriate error fallback.

Note

• ErrorBoundary catches all JavaScript errors in its child components. However, it doesn't automatically catch asynchronous errors (e.g., errors in fetch requests). In such cases, you need to explicitly throw an HTTPError.
• If the error is not an instance of HTTPError, statusCode will be undefined. Therefore, it's crucial to set a default value for statusCode in your fallback component (e.g., 404). This ensures appropriate fallback display for all types of errors.
• While message is optional, it can be useful for providing more detailed error information to the user.
• The resetError function is provided by ErrorBoundary and is used to reset the error state. Calling this function will execute the function passed to the onReset prop of ErrorBoundary.

Best Practices

1. Always set a default value for statusCode in your fallback component:

const ErrorFallback = ({ statusCode = 404, resetError, message }: ErrorProps) => {
  // ...
}

2. Whenever possible, use HTTPError to throw errors. This provides more specific error information:

throw new HTTPError(response.status, errorData.message);

3. For unknown errors, consider throwing an HTTPError with a default status code:

throw new HTTPError(DEFAULT_STATUS_CODE);

These practices ensure consistent error handling for all types of errors.