https://github.com/kuzn-ilya/react-async-call

Declarative promise handling in React
https://github.com/kuzn-ilya/react-async-call

async declarative fetch promise props react render render-props

Last synced: 5 months ago
JSON representation

Declarative promise handling in React

• Host: GitHub
• URL: https://github.com/kuzn-ilya/react-async-call
• Owner: kuzn-ilya
• License: mit
• Created: 2018-03-11T13:21:32.000Z (over 8 years ago)
• Default Branch: master
• Last Pushed: 2018-11-03T12:38:15.000Z (over 7 years ago)
• Last Synced: 2025-10-11T12:14:02.292Z (8 months ago)
• Topics: async, declarative, fetch, promise, props, react, render, render-props
• Language: JavaScript
• Size: 613 KB
• Stars: 10
• Watchers: 1
• Forks: 2
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# React Async Call

[![npm version][npm-badge]][npm]

[![Build Status][build-badge]][build]

[![Code Coverage][coverage-badge]][coverage]

[![MIT License][license-badge]][license]

[![size][size-badge]][unpkg-dist]

[![gzip size][gzip-badge]][unpkg-dist]

[![module formats: umd, cjs, and es][module-formats-badge]][unpkg-dist]

Declarative promise handling in React.

## Table of Content

  * [Motivation](#motivation)

  * [Install](#install)

  * [Usage](#usage)

    * [Basic Usage](#basic-usage)

    * [Data Fetching](#data-fetching)

    * [Incremental Data Fetching](#incremental-data-fetching)

  * [API Reference](#api-reference)

  * [Change Log](#change-log)

  * [Credits](#credits)

## Motivation

Handling promise-returning functions (for example, [`fetch`][fetch-api]) is not hard to do in React application. There are several packages like [holen][holen] or [React Request][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][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.

## Install

### Using npm

`npm i react-async-call --save`

Then, use it as usual:

```JS

// using ES6 modules

import createAsyncCallComponent from 'react-async-call'

// using CommonJS modules

var createAsyncCallComponent = require('react-async-call').createAsyncCallComponent

```

### UMD build

The UMD build is also available on [unpkg][unpkg]:

```HTML

```

The package is avalable on `window.ReactAsyncCall`

## Usage

### Basic Usage

* [JavaScript Example](https://codesandbox.io/s/y7349vl4oj)

* [TypeScript Example](https://codesandbox.io/s/w76rq8jjx8)

```jsx

import createAsyncCallComponent from 'react-async-call'

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

const Example = () => (

  

    

      
Loading...

    

    {({ result }) => 
The result of function call is {result}
}

    {({ rejectReason }) => 
Error: {rejectReason}
}

  

)

```


### Data Fetching

* [JavaScript Example](https://codesandbox.io/s/vn8qmr43yy)

* [TypeScript Example](https://codesandbox.io/s/ryxwnkl34)

### Incremental Data Fetching

* [JavaScript Example](https://codesandbox.io/s/mzzvlmj65y)

* [TypeScript Example](https://codesandbox.io/s/5y3m6mrx9p)

# API Reference

## Exported Members



### `createAsyncCallComponent(fn, [displayName])` ⇒ [AsyncCall](#AsyncCall)

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

```jsx

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:

```jsx

// Start executing async operation on Fetcher mount

  

    Renders only if async operation is executing

  

  

    {({ result }) => (

      


        Renders if async operation has been executed successfully

        
{JSON.stringify(result)}>

      

    )}}

  


  

    Renders only if async operation failed

  

```

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

**Kind**: global function  

**Params**

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| fn | [AsyncFunction](#AsyncFunction) |  | See [`AsyncFunction` signature](#AsyncFunction) for details. |

| [displayName] | String | "AsyncCall" | Component name (visible, for example, in React extension of Chrome Dev Tools). |

**Returns**: [AsyncCall](#AsyncCall) - Returns React [component class `AsyncCall`](#AsyncCall) for the further usage.

This class contains extra component classes [`Running`](#AsyncCall.Running),

[`Rejected`](#AsyncCall.Rejected), [`Resolved`](#AsyncCall.Resolved),

[`Completed`](#AsyncCall.Completed), [`ResultStore`](#AsyncCall.ResultStore),

[`Executor`](#AsyncCall.Executor) and [`State`](#AsyncCall.State) which can be used as children

(direct or indirect) of `AsyncCall`.  

* * *

## React Components



### AsyncCall ⇐ React.Component

React Component. This class is returned by call of [createAsyncCallComponent](#createAsyncCallComponent) and this is the only way to get it.

**Kind**: global class  

**Extends**: React.Component  

**Properties**

| Name | Type | Default | Description |

| --- | --- | --- | --- |

| children | ReactNode \| [AsyncCallChildrenFunction](#AsyncCallChildrenFunction) |  | Property `children` can be either a ReactNode or a function that receives an object as its only argument and return ReactNode. `AsyncCall` component **always** renders its children. We recommend to use [the first form of using `children` property](https://github.com/kuzn-ilya/react-async-call/blob/master/README.md#basic-usage) and respond to async operation execution results using *static sub-components* (like [`Running`](#AsyncCall.Running), [`Rejected`](#AsyncCall.Rejected), [`Resolved`](#AsyncCall.Resolved), [`Completed`](#AsyncCall.Completed), [`ResultStore`](#AsyncCall.ResultStore), [`Executor`](#AsyncCall.Executor) and [`State`](#AsyncCall.State)). |

| params | any |  | A value that will be passed as a single argument into async function. Every time when change of this property occurs, asyncronous operation restarts. |

| [lazy] | Boolean | false | If `true`, component will not start execution of asynchronous operation during component mount phase and on `params` property change. You should start async operation manualy by calling [`execute` method](#AsyncCall+execute) or via [`Executor`](#AsyncCall.Executor). |

* [AsyncCall](#AsyncCall) ⇐ React.Component

    * _instance_

        * [`.execute()`](#AsyncCall+execute)

    * _static_

        * [.ResultStore](#AsyncCall.ResultStore) ⇐ React.Component

            * _instance_

                * [`.reset([execute])`](#AsyncCall.ResultStore+reset)

            * _static_

                * [.HasResult](#AsyncCall.ResultStore.HasResult) ⇐ React.StatelessComponent

                * [.Resetter](#AsyncCall.ResultStore.Resetter) ⇐ React.StatelessComponent

        * [.Running](#AsyncCall.Running) ⇐ React.StatelessComponent

        * [.Resolved](#AsyncCall.Resolved) ⇐ React.StatelessComponent

        * [.Rejected](#AsyncCall.Rejected) ⇐ React.StatelessComponent

        * [.Executor](#AsyncCall.Executor) ⇐ React.StatelessComponent

        * [.State](#AsyncCall.State) ⇐ React.StatelessComponent

        * [.Completed](#AsyncCall.Completed) ⇐ React.StatelessComponent

* * *



#### `asyncCall.execute()`

Method for executing async operation manually.

It is recommended to use [`` component](#AsyncCall.Executor) instead.

**Kind**: instance method of [AsyncCall](#AsyncCall)  

* * *



#### AsyncCall.ResultStore ⇐ React.Component

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](#AsyncCall)  

**Extends**: React.Component  

**Properties**

| Name | Type | Default | Description |

| --- | --- | --- | --- |

| children | [ResultStoreChildrenFunction](#ResultStoreChildrenFunction) \| ReactNode |  | React children or function that returns rendered result depending on `hasResult` flag and `result`. |

| reduce | [ReduceFunction](#ReduceFunction) |  | Function from previousResult and currentResult to a new result. Useful, for example, when you need to accumulate sequential async calls (e.g. for fetching data for infinte page scroll). |

| [initialValue] | any |  | Optional initial value for the result store. If value is provided, result store will have result always. |

| [reset] | boolean | false | @deprecated If `true`, clears the store (**Deprecated, will be removed in version 1.0.0. Use [Resetter](#AsyncCall.ResultStore.Resetter) instead**). |

* [.ResultStore](#AsyncCall.ResultStore) ⇐ React.Component

    * _instance_

        * [`.reset([execute])`](#AsyncCall.ResultStore+reset)

    * _static_

        * [.HasResult](#AsyncCall.ResultStore.HasResult) ⇐ React.StatelessComponent

        * [.Resetter](#AsyncCall.ResultStore.Resetter) ⇐ React.StatelessComponent

* * *



##### `resultStore.reset([execute])`

Resets result store to its initial state.

**Kind**: instance method of [ResultStore](#AsyncCall.ResultStore)  

**Params**

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [execute] | bool | true | Wether execute promise-returning function after resetting or not. |

* * *



##### ResultStore.HasResult ⇐ React.StatelessComponent

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](#AsyncCall.ResultStore)  

**Extends**: React.StatelessComponent  

**Properties**

| Name | Type |

| --- | --- |

| children | [HasResultChildrenFunction](#HasResultChildrenFunction) | 

* * *



##### ResultStore.Resetter ⇐ React.StatelessComponent

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](#AsyncCall.ResultStore).

**Kind**: static class of [ResultStore](#AsyncCall.ResultStore)  

**Extends**: React.StatelessComponent  

**Properties**

| Name | Type |

| --- | --- |

| children | [ResetterChildrenFunction](#ResetterChildrenFunction) | 

* * *



#### AsyncCall.Running ⇐ React.StatelessComponent

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

**Kind**: static class of [AsyncCall](#AsyncCall)  

**Extends**: React.StatelessComponent  

**Properties**

| Name | Type |

| --- | --- |

| children | ReactNode | 

* * *



#### AsyncCall.Resolved ⇐ React.StatelessComponent

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](#AsyncCall)  

**Extends**: React.StatelessComponent  

**Properties**

| Name | Type |

| --- | --- |

| children | ReactNode \| [ResolvedChildrenFunction](#ResolvedChildrenFunction) | 

* * *



#### AsyncCall.Rejected ⇐ React.StatelessComponent

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](#AsyncCall)  

**Extends**: React.StatelessComponent  

**Properties**

| Name | Type |

| --- | --- |

| children | ReactNode \| [RejectedChildrenFunction](#RejectedChildrenFunction) | 

* * *



#### AsyncCall.Executor ⇐ React.StatelessComponent

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](#AsyncCall)  

**Extends**: React.StatelessComponent  

**Properties**

| Name | Type |

| --- | --- |

| children | [ExecutorChildrenFunction](#ExecutorChildrenFunction) | 

* * *



#### AsyncCall.State ⇐ React.StatelessComponent

React Component. Renders its children always. Property `children` must be a function

with the only argument receiving an object ([see description of `StateChildrenFunction`](#StateChildrenFunction))

with the state of async operation. `State` component is handy for complicated UI cases when none of static components of [AsyncCall](#AsyncCall) suits you.

**Kind**: static class of [AsyncCall](#AsyncCall)  

**Extends**: React.StatelessComponent  

**Properties**

| Name | Type |

| --- | --- |

| children | [StateChildrenFunction](#StateChildrenFunction) | 

* * *



#### AsyncCall.Completed ⇐ React.StatelessComponent

React Component. Renders its children whenever async operation has been completed (successfully or not),

but is still not started again. Otherwise renders nothing.

```jsx

  Async operation completed

```

**Kind**: static class of [AsyncCall](#AsyncCall)  

**Extends**: React.StatelessComponent  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| [children] | ReactNode | React children to be rendered whenever async operation is completed. |

* * *

## Function Signatures



### `ResultStoreChildrenFunction(params)` ⇒ ReactNode

Type of `children` function of a [ResultStore](#AsyncCall.ResultStore) component.

**Params**

| Param | Type | Description |

| --- | --- | --- |

| params | object |  |

| params.hasResult | boolean |  |

| [params.result] | any |  |

| params.reset | [ResetFunction](#ResetFunction) | Function for manual store cleaning. |

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

* * *



### `ReduceFunction(previousResult, currentResult)` ⇒ any

Type of `reduce` property of a [ResultStore](#AsyncCall.ResultStore) component.

**Params**

| Param | Type |

| --- | --- |

| previousResult | any | 

| currentResult | any | 

* * *



### `HasResultChildrenFunction(params)` ⇒ ReactNode

Type of children function for [HasResult](#AsyncCall.ResultStore.HasResult)

**Params**

| Param | Type |

| --- | --- |

| params | object | 

| params.result | any | 

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

* * *



### `ResetFunction([execute])`

Reset function

**Params**

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [execute] | bool | false | Wether execute promise-returning function after resetting or not. |

* * *



### `ResetterChildrenFunction(params)` ⇒ ReactNode

Type of children function for [Resetter](#AsyncCall.ResultStore.Resetter)

**Params**

| Param | Type | Description |

| --- | --- | --- |

| params | object |  |

| params.reset | [ResetFunction](#ResetFunction) | Function for manual clearing of [ResultStore](#AsyncCall.ResultStore). |

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

* * *



### `AsyncFunction(params)` ⇒ Promise

Asynchronous function (aka asynchronous operation or promise-returning function)

which returns promise based on supplied parameter.

**Params**

| Param | Type | Description |

| --- | --- | --- |

| params | any | Parameters, based on which function should return promise. |

**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())

```

* * *



### `ExecuteFunction()` ⇒ void

Execute function

* * *



### `AsyncCallChildrenFunction(params)` ⇒ ReactNode

Type of children function for [AsyncCall](#AsyncCall)

**Params**

| Param | Type | Description |

| --- | --- | --- |

| params | object | Represents current status of asynchronous operation. |

| params.running | boolean | Indicates whether asynchronous operation is executing or not. |

| params.rejected | boolean | Indicates whether asynchronous operation was failed when it was called last time. If `true`, result of promise rejection (error) can be found in the `params.rejectReason`. |

| params.resolved | boolean | Indicates whether asynchronous operation was succeeded when it was called last time. If `true`, result of promise resolving can be found in the `params.result`. |

| [params.result] | any | Contains result of promise (returned by async function) resolving if function call was successful. `undefined` if asynchronous operation is running or promise was rejected. |

| [params.rejectReason] | any | Contains result of promise (returned by async function) rejection if function call was unsuccessful. `undefined` if asynchronous operation is running or promise was resolved. |

| params.execute | [ExecuteFunction](#ExecuteFunction) | Function for manual execution of asynchronous operation. |

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

* * *



### `ResolvedChildrenFunction()` ⇒ ReactNode

Type of children function for [Resolved](#AsyncCall.Resolved)

**Params**

| Param | Type |

| --- | --- |

|  | object | 

| params.result | any | 

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

* * *



### `RejectedChildrenFunction(params)` ⇒ ReactNode

Type of children function for [Rejected](#AsyncCall.Rejected)

**Params**

| Param | Type |

| --- | --- |

| params | object | 

| params.rejectReason | any | 

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

* * *



### `ExecutorChildrenFunction(params)` ⇒ ReactNode

Type of children function for [Executor](#AsyncCall.Executor)

**Params**

| Param | Type | Description |

| --- | --- | --- |

| params | object |  |

| params.execute | [ExecuteFunction](#ExecuteFunction) | Function for manual execution of asynchronous operation. |

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

* * *



### `StateChildrenFunction(params)` ⇒ ReactNode

Type of children function for [State](#AsyncCall.State)

**Params**

| Param | Type | Description |

| --- | --- | --- |

| params | object |  |

| params.running | boolean | Whether async opertation is executing or not. If you only need to process `running`, use either [Running](#AsyncCall.Running) or [Completed](#AsyncCall.Completed) component instead. |

| params.resolved | boolean | Whether async opertation was completed successfully last time or not. If you only need to process `resolved` and `result`, [Resolved](#AsyncCall.Resolved) component instead. |

| params.rejected | boolean | Whether async opertation failed last time or not. If you only need to process `rejected` and `rejectedStatus`, use [Rejected](#AsyncCall.Rejected) component instead. |

| [params.rejectReason] | any | Contains reject reason if async opertation failed last time. If you only need to process `rejected` and `rejectedReason`, use [Rejected](#AsyncCall.Rejected) component instead. |

| [params.result] | any | Contains result of last successful async operation call. If you only need to process `resolved` and `result`, use [Resolved](#AsyncCall.Resolved) component instead. If you need to accumulate result, consider [ResultStore](#AsyncCall.ResultStore) usage. |

| params.execute | [ExecuteFunction](#ExecuteFunction) | Callback for manual execution of async operation. If you only need to execute async operation manualy, use [Executor](#AsyncCall.Executor) component instead.                               | |

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

* * *

## Change Log

[You can find change log here][changelog]

## Credits

Great thanks to [@kitos](https://github.com/kitos) and [@ventrz](https://github.com/ventrz) for their invaluable help, support and bright ideas!

[npm-badge]: https://badge.fury.io/js/react-async-call.svg

[npm]: https://www.npmjs.com/package/react-async-call

[build-badge]: https://travis-ci.org/kuzn-ilya/react-async-call.svg?branch=master

[build]: https://travis-ci.org/kuzn-ilya/react-async-call

[coverage-badge]: https://codecov.io/gh/kuzn-ilya/react-async-call/branch/master/graph/badge.svg

[coverage]: https://codecov.io/gh/kuzn-ilya/react-async-call

[license-badge]: https://img.shields.io/npm/l/react-async-call.svg

[license]: https://github.com/kuzn-ilya/react-async-call/blob/master/LICENSE

[size-badge]: http://img.badgesize.io/https://unpkg.com/react-async-call/umd/react-async-call.production.min.js?label=size

[gzip-badge]: http://img.badgesize.io/https://unpkg.com/react-async-call/umd/react-async-call.production.min.js?compression=gzip&label=gzip%20size

[module-formats-badge]: https://img.shields.io/badge/module%20formats-umd%2C%20cjs-green.svg

[unpkg-dist]: https://unpkg.com/react-async-call/

[unpkg]: https:/unpkg.com

[changelog]: https://github.com/kuzn-ilya/react-async-call/blob/master/docs/CHANGELOG.md

[fetch-api]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API

[holen]: https://github.com/tkh44/holen

[react-request]: https://github.com/jamesplease/react-request