Declarative promise handling in React.

• Motivation
• Install
• Usage
  • Basic Usage
  • Data Fetching
  • Incremental Data Fetching
• API Reference
• Change Log
• Credits

Handling promise-returning functions (for example, fetch) is not hard to do in React application. There are several packages like holen or React Request for simplifying such kind of tasks but theirs authors try to impose their own vision on various aspects of data fetching. For instance, React Request has a cache for HTTP requests but what will happen if you decide to change caching strategy? React Async Call tries to sharpen the edges. This is minimalistic package that can be used not only for data fetching but also for handling any promise-returning functions.

npm i react-async-call --save

Then, use it as usual:

// using ES6 modules
import createAsyncCallComponent from 'react-async-call'

// using CommonJS modules
var createAsyncCallComponent = require('react-async-call').createAsyncCallComponent

The UMD build is also available on unpkg:

<script src="https://unpkg.com/react-async-call"></script>

The package is avalable on window.ReactAsyncCall

• JavaScript Example
• TypeScript Example

import createAsyncCallComponent from 'react-async-call'

const AsyncCall = createAsyncCallComponent(value => Promise.resolve(42))

const Example = () => (
  <AsyncCall>
    <AsyncCall.Running>
      <div>Loading...</div>
    </AsyncCall.Running>
    <AsyncCall.Resolved>{({ result }) => <div>The result of function call is {result}</div>}</AsyncCall.Resolved>
    <AsyncCall.Rejected>{({ rejectReason }) => <div>Error: {rejectReason}</div>}</AsyncCall.Rejected>
  </AsyncCall>
)

• JavaScript Example
• TypeScript Example

• JavaScript Example
• TypeScript Example

A factory function that creates React component class and binds async operation to it:

const Fetcher = createAsyncCallComponent(() => fetch('https://api.github.com/repositories').then(data => data.json()))

After calling of this function you can use returned component and its static sub-components to hook async operation lifecycle:

// Start executing async operation on Fetcher mount
<Fetcher>
  <Fetcher.Running>
    Renders only if async operation is executing
  </Fetcher.Running>

  <Fetcher.Resolved>
    {({ result }) => (
      <div>
        Renders if async operation has been executed successfully
        <pre>{JSON.stringify(result)}></pre>
      </div>
    )}}
  </Fetcher.Resolved>

  <Fetcher.Rejected>
    Renders only if async operation failed
  </Fetcher.Rejected>
</Fetcher>

createAsyncCallComponent is the only member exported by react-async-call package.

Kind: global function
Params

Returns: AsyncCall - Returns React component class AsyncCall for the further usage. This class contains extra component classes Running, Rejected, Resolved, Completed, ResultStore, Executor and State which can be used as children (direct or indirect) of AsyncCall.

React Component. This class is returned by call of createAsyncCallComponent and this is the only way to get it.

Kind: global class
Extends: React.Component
Properties

• AsyncCall ⇐ React.Component
  • instance
    • .execute()
  • static
    • .ResultStore ⇐ React.Component
      • instance
        • .reset([execute])
      • static
        • .HasResult ⇐ React.StatelessComponent
        • .Resetter ⇐ React.StatelessComponent
    • .Running ⇐ React.StatelessComponent
    • .Resolved ⇐ React.StatelessComponent
    • .Rejected ⇐ React.StatelessComponent
    • .Executor ⇐ React.StatelessComponent
    • .State ⇐ React.StatelessComponent
    • .Completed ⇐ React.StatelessComponent

Method for executing async operation manually. It is recommended to use <Executor> component instead.

Kind: instance method of AsyncCall

React Component. Implements store of results of sequential async calls. Useful when you need to accumulate results of async calls (e.g., to glue together sequential calls of server API).

Kind: static class of AsyncCall
Extends: React.Component
Properties

• .ResultStore ⇐ React.Component
  • instance
    • .reset([execute])
  • static
    • .HasResult ⇐ React.StatelessComponent
    • .Resetter ⇐ React.StatelessComponent

Resets result store to its initial state.

Kind: instance method of ResultStore
Params

React Component. Renders its children whenever result store is not empty (has result). Property children must be a function with the only argument receiving object with the only field result.

Kind: static class of ResultStore
Extends: React.StatelessComponent
Properties

React Component. Renders its children always. Property children must be a function with the only argument receiving an object with a function for manual reset of ResultStore.

Kind: static class of ResultStore
Extends: React.StatelessComponent
Properties

React Component. Renders its children whenever async operation was started but is still executing. Otherwise renders nothing.

Kind: static class of AsyncCall
Extends: React.StatelessComponent
Properties

React Component. Renders its children whenever async operation has been completed successfully (promise was resolved), but is still not started again. Otherwise renders nothing. Property children can be either React node(s) or children function with the only argument receiving object with the only field result.

Kind: static class of AsyncCall
Extends: React.StatelessComponent
Properties

React Component. Renders its children whenever async operation has been completed with failure (promise was rejected), but is still not started again. Otherwise renders nothing. Property children can be either React node(s) or children function with the only argument receiving object with the only field rejectReason (promise reject reason).

Kind: static class of AsyncCall
Extends: React.StatelessComponent
Properties

React Component. Renders its children always. Property children must be a function with the only argument receiving an object with a function for manual execution of async operation.

Kind: static class of AsyncCall
Extends: React.StatelessComponent
Properties

React Component. Renders its children always. Property children must be a function with the only argument receiving an object (see description of StateChildrenFunction) with the state of async operation. State component is handy for complicated UI cases when none of static components of AsyncCall suits you.

Kind: static class of AsyncCall
Extends: React.StatelessComponent
Properties

React Component. Renders its children whenever async operation has been completed (successfully or not), but is still not started again. Otherwise renders nothing.

<AsyncCall.Completed>
  Async operation completed
</AsyncCall.Completed>

Kind: static class of AsyncCall
Extends: React.StatelessComponent
Properties

Type of children function of a ResultStore component.

Params

Returns: ReactNode - Should return rendered React component(s) depending on supplied params.

Type of reduce property of a ResultStore component.

Params

Type of children function for HasResult

Params

Returns: ReactNode - Should return rendered React component(s) depending on supplied params.

Reset function

Params

Type of children function for Resetter

Params

Returns: ReactNode - Should return rendered React component(s) depending on supplied params.

Asynchronous function (aka asynchronous operation or promise-returning function) which returns promise based on supplied parameter.

Params

Returns: Promise - Promise object that represents asynchronous operation result.
Example
The function below returns result (Promise object) of getting user data from GitHub API by his/her GitHub login:

const getGitHubUserData = userName => fetch(`https://api.github.com/users/${userName}`).then(data => data.json())

Execute function

Type of children function for AsyncCall

Params

Returns: ReactNode - Should return rendered React component(s) depending on supplied params.

Type of children function for Resolved

Params

Returns: ReactNode - Should return rendered React component(s) depending on supplied params.

Type of children function for Rejected

Params

Returns: ReactNode - Should return rendered React component(s) depending on supplied params.

Type of children function for Executor

Params

Returns: ReactNode - Should return rendered React component(s) depending on supplied params.

Type of children function for State

Params

Returns: ReactNode - Should return rendered React component(s) depending on supplied params.

You can find change log here

Great thanks to @kitos and @ventrz for their invaluable help, support and bright ideas!