## Contents
Just follow links below to get an overview of library features.
- [Contents](#contents)
- [Getting started](#getting-started)
- [Provider](#provider)
- [Http client](#http-client)
- [Public API](#public-api)
- [Request params](#request-params)
- [Request return](#request-return)
- [Abortable request return](#abortable-request-return)
- [Example – Abortable request](#example--abortable-request)
- [Example – Get request](#example--get-request)
- [Example – Http context](#example--http-context)
- [Request hooks](#request-hooks)
- [Http request hook params](#http-request-hook-params)
- [Http request hook return](#http-request-hook-return)
- [Http request state](#http-request-state)
- [Example – Http request hook triggered automatically on component mount](#example--http-request-hook-triggered-automatically-on-component-mount)
- [Example – Http request hook triggered manually on component mount](#example--http-request-hook-triggered-manually-on-component-mount)
- [Example – Non-abortable http request hook](#example--non-abortable-http-request-hook)
- [Example – Aborting http request triggered by the hook](#example--aborting-http-request-triggered-by-the-hook)
- [Example – Http post request hook](#example--http-post-request-hook)
- [Events](#events)
- [Caching](#caching)
- [Browser support](#browser-support)
## Getting started
Install the package by using npm
```
npm install react-http-fetch
```
or yarn
```
yarn add react-http-fetch
```
## Provider
You can override the default configuration used by the http client to perform any request by using the `HttpClientConfigProvider`:
```js
import React from 'react';
import { defaultHttpReqConfig, HttpClientConfigProvider } from 'react-http-fetch';
function Child() {
return (
Child component
);
};
function httpResponseParser(res) {
return res.json();
}
function App() {
/**
* Provided configs are automatically merged to the default one.
*/
const httpReqConfig = {
// ...defaultHttpReqConfig,
baseUrl: process.env.BACKEND_URL,
responseParser: httpResponseParser,
reqOptions: {
headers: {
'Content-Type': 'text/html; charset=UTF-8',
},
},
};
return (
);
}
export default App;
```
Below the complete set of options you can provide to the `HttpClientConfigProvider`:
| Option | Description | Default |
| --------------------- | --------------------------------------------------------------------------|------------- |
|baseUrl|The base url used by the client to perform any http request (e.g. http://localhost:8000)|```''```
|responseParser|A function that maps the native fetch response. The default parser transform the fetch response stream into a json (https://developer.mozilla.org/en-US/docs/Web/API/Response/json)|[httpResponseParser](src/config/response-parser.ts)
|requestBodySerializer|A function used to serialize request body. The default serializer take into account a wide range of data types to figure out which type of serialization to perform|[serializeRequestBody](src/config/request-body-serializer.ts)
|reqOptions|The default request option that will be carried by any request dispatched by the client. See [HttpRequestOptions](src/client/types.ts)|```{ headers: { 'Content-Type': 'application/json' } }```
|cacheStore|The store for cached http responses. By default an in-memory cache store is used.|[HttpInMemoryCacheStore](src/cache/http-in-memory-cache-store.ts)
|cacheStorePrefix|The prefix concatenated to any cached entry.|`rfh`
|cacheStoreSeparator|Separates the store prefix and the cached entry identifier|`__`
## Http client
The `useHttpClient` hook return a set of methods to perform http requests. The `request` function is the lowest level one, all other exposed functions are just decorators around it. Below a basic example using `request`:
```js
import React from 'react';
import { useHttpClient } from 'react-http-fetch';
function App() {
const { request } = useHttpClient();
const [todo, setTodo] = useState();
useEffect(
() => {
const fetchTodo = async () => {
const res = await request({
baseUrlOverride: 'https://jsonplaceholder.typicode.com',
relativeUrl: 'todos/1',
requestOptions: {
method: 'GET',
},
});
setTodo(res);
};
fetchTodo();
},
[request]
);
return (
{`Todo name: ${todo && todo.title}`}
);
}
export default App;
```
### Public API
The complete *public API* exposed by the hook:
| Method | Description | Params | Return |
| --------------------- | --------------------------------------------------------------------------| --------------------- | --------------------- |
|request | The lowest level method to perform a http request | [Request params](#request-params) | [Request return](#request-return)
|
get
post
put
patch
delete
| Make use of lower level method `request` by just overriding the http method ([example](#example--abortable-request)) | [Request params](#request-params) | [Request return](#request-return)
| abortableRequest | The lowest level method to perform an abortable http request ([example](#example--abortable-request)) | [Request params](#request-params) | [Abortable request return](#abortable-request-return)
|
abortableGet
abortablePost
abortablePut
abortablePatch
abortableDelete
| Make use of lower level method `abortableRequest` by just overriding the http method | [Request params](#request-params) | [Abortable request return](#abortable-request-return)
### Request params
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| baseUrlOverride | string | The base url of the request. If provided, it would override the [provider](#provider) base url.
| relativeUrl | string | The url relative to the base one (e.g. posts/1).
| parser | [HttpResponseParser](src/client/types.ts) | An optional response parser that would override the [provider](#provider) global one. |
| context | [HttpContext](src/client/http-context.ts) | An optional context that carries arbitrary user defined data. See examples.|
| requestOptions | [HttpRequestOptions](./src/client/types.ts) | The options carried by the fetch request. |
### Request return
The jsonified return value of native JS fetch. If a custom response parser (see [Provider](#provider)) is provided then the return value corresponds to the parsed one.
### Abortable request return
| Value | Type |
| ----- | ---- |
|[request, abortController]|[[RequestReturn](#request-return), [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController)]|
### Example – Abortable request
```js
import React, { useState, useRef } from 'react';
import { useHttpClient } from 'react-http-fetch';
function App() {
const { abortableRequest } = useHttpClient();
const abortCtrlRef = useRef();
const [todo, setTodo] = useState();
const fetchTodo = async () => {
const [reqPromise, abortController] = abortableRequest({
baseUrlOverride: 'https://jsonplaceholder.typicode.com',
relativeUrl: 'todos/1',
});
abortCtrlRef.current = abortController;
try {
const res = await reqPromise;
setTodo(res);
} catch (error) {
// Abort the request will cause the request promise to be rejected with the following error:
// "DOMException: The user aborted a request."
console.error(error);
} finally {
abortCtrlRef.current = undefined;
}
};
const abortPendingRequest = () => {
if (abortCtrlRef.current) {
abortCtrlRef.current.abort();
}
};
return (
{`Todo name: ${todo && todo.title}`}
);
}
export default App;
```
### Example – Get request
```js
import React, { useState, useEffect } from 'react';
import { useHttpClient } from 'react-http-fetch';
function App() {
const { get } = useHttpClient();
const [todo, setTodo] = useState();
useEffect(
() => {
const fetchTodo = async () => {
const res = await get({
baseUrlOverride: 'https://jsonplaceholder.typicode.com',
relativeUrl: 'todos/1',
});
setTodo(res);
};
fetchTodo();
},
[get]
);
return (
);
}
export default App;
```
## Request hooks
The library provides a hook `useHttpRequest` managing the state of the http request. Such state is returned by the hook along with a function to trigger the request. See [params](#http-request-hook-params) and [return](#http-request-hook-return) for more info. A dedicated hook is provided for every http method: `useHttpGet`, `useHttpPost`, `useHttpPatch`, `useHttpPut`, `useHttpDelete`.
### Http request hook params
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| baseUrlOverride | string | The base url of the request. If provided, it would override the [provider](#provider) base url.
| relativeUrl | string | The url relative to the base one (e.g. posts/1).
| parser | [HttpResponseParser](src/client/types.ts) | An optional response parser that would override the [provider](#provider) global one. |
| context | [HttpContext](src/client/http-context.ts) | An optional context that carries arbitrary user defined data. See examples.|
| requestOptions | [HttpRequestOptions](./src/client/types.ts) | The options carried by the fetch request. |
| initialData | any | The value that the state assumes initially before the request is send. |
| fetchOnBootstrap | boolean | Tell if the fetch must be triggered automatically when mounting the component or not. In the second case we would like to have a manual fetch, this is optained by a request function returned by the hook. |
### Http request hook return
Returns an array of three elements:
- The first one embeds the state of the http request.
- The second is a function that can be used to perform an abortable http request.
- The third is a function that can be used to perform a non-abortable http request.
See examples for further details. The table below describes the shape (i.e. properties) of http request state.
### Http request state
| Property | Type | Description |
| --------- | ---- | ----------- |
| pristine | boolean | Tells if the request has been dispatched. |
| errored | boolean | Tells if the request has returned an error. |
| isLoading | boolean | Tells if the request is pending. |
| error | unknown | property evaluated by the error generated by the backend api. |
| data | any | The response provided by the backend api. |
### Example – Http request hook triggered automatically on component mount
```js
import React from 'react';
import { useHttpRequest } from 'react-http-fetch';
function App() {
const [state] = useHttpRequest({
baseUrlOverride: 'https://jsonplaceholder.typicode.com',
relativeUrl: 'todos/1',
requestOptions: {},
initialData: {},
fetchOnBootstrap: true,
});
return (
](http://gotbahn.github.io/browsers-support-badges/)Edge | [
](http://gotbahn.github.io/browsers-support-badges/)Firefox | [
](http://gotbahn.github.io/browsers-support-badges/)Chrome | [
](http://gotbahn.github.io/browsers-support-badges/)Safari |
| --------- | --------- | --------- | --------- |
| last 2 versions| last 2 versions| last 2 versions| last 2 versions