Nanotechnology Promises Much

    @react-hook/async
    TypeScript icon, indicating that this package has built-in type declarations

    3.1.1 • Public • Published

    useAsync()

    Bundlephobia Types Build status NPM Version MIT License

    npm i @react-hook/async

    A React hook for gracefully resolving, cancelling, and handling errors for async functions and promises. These hooks also clean up any lingering promises when your component unmounts by cancelling them.

    Quick Start

    Check out the example on CodeSandbox

    import {useAsync, useAsyncEffect} from '@react-hook/async'
    
    // Example using a manual invocation
    const CallbackResolver = () => {
      const [{status, cancel, error, value}, call] = useAsync(() => {
        return new Promise((resolve) => setTimeout(() => resolve('Loaded'), 3000))
      })
    
      switch (status) {
        case 'loading':
          return (
            <div>
              <button onClick={cancel}>Cancel</button>
              Loading...
            </div>
          )
        case 'cancelled':
          return (
            <div>
              Cancelled.
              <button onClick={call}>Try again</button>
            </div>
          )
        case 'error':
          return `Error: ${error}`
        case 'success':
          return value || 'Success!'
        default:
          return <button onClick={call}>Load me</button>
      }
    }
    
    // Example using a useEffect invocation
    const EffectResolver = () => {
      const [curr, setCurr] = useState(0)
      // Will load each time counter changes
      const {status, cancel, error, value} = useAsyncEffect(() => {
        return new Promise((resolve) =>
          setTimeout(() => resolve(`Loaded ${curr}`), 3000)
        )
      }, [curr])
    
      switch (status) {
        case 'loading':
          return (
            <div>
              <button onClick={cancel}>Cancel</button>
              Loading...
            </div>
          )
        case 'cancelled':
          return (
            <div>
              Cancelled.
              <button onClick={() => setCurr((curr) => ++curr)}>Try again</button>
            </div>
          )
        case 'error':
          return `Error: ${error}`
        case 'success':
          return (
            <div>
              {value}
              <button onClick={() => setCurr((curr) => ++curr)}>Load again</button>
            </div>
          )
        default:
          return null
      }
    }

    API

    useAsync(asyncCallback)

    export const useAsync = <
      ValueType extends any = any,
      ErrorType extends any = Error,
      Args extends any[] = any[]
    >(
      asyncCallback: (...args: Args) => Promise<ValueType>
    ): [AsyncState<ValueType, ErrorType, Args>, AsyncCallback<Args>]

    Arguments

    Argument Type Default Required? Description
    asyncCallback (...args: Args) => Promise<ValueType> undefined Yes An async function or function that returns a promise.

    Returns [AsyncState<ValueType, ErrorType>, AsyncCallback]


    AsyncState

    export interface AsyncState<ValueType, ErrorType> {
      // 'idle' | 'loading' | 'success' | 'error' | 'cancelled'
      status: AsyncStatus
      // The return value of your async callback or promise. This value is persisted until there
      // is another successful promise resolution. That means you when you're in an 'error', 'loading',
      // or 'cancelled' state, you'll still have the most recent successful value here. This is useful
      // because the status property should be dictating what you're doing in your UI and there are
      // cases where you won't want to lose the current value.
      value?: ValueType
      // The error object from any exceptions encountered inside the async function
      // or the value of the promise rejection.
      error?: ErrorType
      // Cancels the promise
      cancel: () => void
    }

    AsyncCallback

    export interface AsyncCallback<Args extends any[] = any[]> {
      (...args: Args): void
      cancel: () => void
    }

    useAsyncEffect(asyncCallback, dependencies)

    export const useAsyncEffect = <
      ValueType extends any = any,
      ErrorType extends any = Error
    >(
      asyncCallback: () => Promise<ValueType>,
      dependencies?: React.DependencyList
    ): AsyncState<ValueType, ErrorType, []>

    This hook will invoke a callback each time its dependencies array changes.

    Arguments

    Argument Type Default Required? Description
    asyncCallback () => Promise<ValueType> undefined Yes An async function or function that returns a promise.
    dependencies any[] undefined No Values or state that your callback depends on. This works the same as the dependencies array of useEffect, useCallback, etc.

    Returns AsyncState<ValueType, ErrorType>

    LICENSE

    MIT

    Install

    npm i @react-hook/async

    DownloadsWeekly Downloads

    932

    Version

    3.1.1

    License

    MIT

    Unpacked Size

    63.1 kB

    Total Files

    24

    Last publish

    Collaborators

    • jaredlunde