Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/honzabrecka/composable-fetch
A library that brings composition to http requests & solves most common tasks
https://github.com/honzabrecka/composable-fetch
composable fetch functional http javascript request typescript
Last synced: 19 days ago
JSON representation
A library that brings composition to http requests & solves most common tasks
- Host: GitHub
- URL: https://github.com/honzabrecka/composable-fetch
- Owner: honzabrecka
- License: mit
- Created: 2017-08-07T13:33:50.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T02:03:48.000Z (almost 2 years ago)
- Last Synced: 2024-10-15T09:32:17.169Z (about 1 month ago)
- Topics: composable, fetch, functional, http, javascript, request, typescript
- Language: TypeScript
- Homepage:
- Size: 1.96 MB
- Stars: 24
- Watchers: 3
- Forks: 1
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# composable-fetch [](https://circleci.com/gh/honzabrecka/composable-fetch/tree/master)
- Composable and extensible
- Just javascript and promises
- Brings solutions for most common cases such as status code checking, body encoding/decoding, retries & retries strategies, ...
- Provides functional API
- Dependency free
- First class support for both TypeScript and Flow
## Installation
```
npm install composable-fetch
```
## Example
```js
const composableFetch = require('composable-fetch')
const log = console.log.bind(console)
const fetchJSON = composableFetch.pipeP(
composableFetch.withBaseUrl('https://example.com/api'),
composableFetch.withHeader('Content-Type', 'application/json'),
composableFetch.withHeader('Accept', 'application/json'),
composableFetch.withEncodedBody(JSON.stringify),
composableFetch.retryable(composableFetch.fetch1(window.fetch)),
composableFetch.withRetry(),
composableFetch.withSafe204(),
composableFetch.decodeJSONResponse,
composableFetch.checkStatus
)
fetchJSON({ url: '/foo' }).then(log).catch(log)
fetchJSON({ url: '/bar', method: 'POST', body: [1, 2, 3] }).then(log).catch(log)
```
For better overview of how composability may help take a look at `examples/composable.js` example.
## Overview
The main concept of composable-fetch is [piping (left-to-right composition)](#pipep) - passing data through pipe of unary functions. Pipe typically has three blocks, subpipes ([see API](#api) for more details about applicable functions):
```
pipe = enhance request -> fetch (with retries) -> enhance response
```
## fetch
For better composability, composable-fetch requires unary `fetch`. However original `fetch` function or its polyfills is of binary arity. Don't worry, composable-fetch comes with `fetch1` wrapper that transforms unary interface to its binary counterpart.
## Retries
```js
withRetry({ max: 3, delay: delays.constant() })
// retries after 1 sec, then again after 1 sec, then again after 1 sec
withRetry({ max: 3, delay: delays.linear() })
// retries after 1 sec, then after 2 secs, then after 3 secs
withRetry({ max: 3, delay: delays.exponential() })
// retries after 1 sec, then after 4 secs, then after 9 secs
withRetry({ max: 6, delay: delays.limited(3, delays.linear()) })
// retries after 1 sec, then 2 secs, 3 secs, then 1 sec, 2 secs, 3 secs
```
When using `withRetry`, make sure that you wrapped `fetch` with `retryable`.
## Error handling & logging
To pretty print failed request (any reason):
```js
const fetchJSON: tryCatchP(
pipeP(/* ... */),
logError(), // to console.error by default
)
```
In case you are interested in details of all requests made by your application, you can add simple `tap` function which performs desired side effect:
```js
const tap = (f) => (v) => {
f(v)
return v
}
const fetchJSON = pipeP(
// ...
withHeader('Accept', 'application/json'),
withEncodedBody(JSON.stringify),
tap(console.log.bind(console, 'request:')),
fetch1(window.fetch),
// ...
)
```
The `fetch` API has one major "limitation" - body of the response can be read just once. For example you deal with an API that returns HTML encoded reponse even though you asked for JSON encoded one - fetch fails on DecodeResponseError. You cannot just catch this error and decode that HTML encoded response, because you already read it. In browser it typically does not matter, you have network tab with all the details, however in non-browser environment it's not that easy, therefore composable-fetch comes with `withClone` function that gives you second chance to read the response:
```js
const fetchJSON = tryCatchP(
pipeP(
// ...
withRetry(),
withClone,
decodeJSONResponse, // this will fail for any non application/json response
// ...
),
logError
)
```
## API
### pipeP
Performs left-to-right function composition. Each function in composition must be unary. If function returns promise, than `pipeP` waits to its resolution before it calls next function in chain.
### tryCatchP
`tryCatchP` takes two functions, an async trier and an async catcher. The returned function evaluates the trier; if it does not throw, it simply returns the result. If it does throw, the catcher function is evaluated and result is returned.
### Enhance request phase
```js
withBaseUrl: (baseUrl: string) => (req: Request) => Request
withEncodedBody: (encoder: Encoder) => (req: Request) => Request
withJSONEncodedBody: (req: Request) => Request
withHeader: (header: string, value: string) => (req: Request) => Request
withCredentials: (value: 'omit' | 'same-origin' | 'include') => (req: Request) => Request
withTimeout: (timeout: number) => (fetch: RetryableFetch) => RetryableFetch
```
### Fetch phase
```js
fetch1: (fetch: BinaryFetch) => UnaryFetch
retryable: (fetch: UnaryFetch) => (req: Request) => RetryableFetch
withRetry: (options?: RetryOptions) => (fetch: RetryableFetch) => Promise
```
### Enhance response phase
```js
checkStatus: (res: Response) => Response
decodeArrayBufferResponse: (res: Response) => DecodedResponse
decodeBlobResponse: (res: Response) => DecodedResponse
decodeFormDataResponse: (res: Response) => DecodedResponse
decodeJSONResponse: (res: Response) => DecodedResponse
decodeResponse: (res: Response) => DecodedResponse
decodeTextResponse: (res: Response) => DecodedResponse
withSafe204: (text?: string, json?: any) => (res: Response) => Response
withClone: (res: Response) => Response
```
### Predefined pipes
```js
json: (fetch: BinaryFetch, options?: RetryOptions) => Promise
text: (fetch: BinaryFetch, options?: RetryOptions) => Promise
```
### Abort
For better understanding how to abort fetch request, go to `examples/abort.js` example.
```js
abortable: () => { signal: AbortSignal, abort: () => void }
ignoreAbortError: (handler: (error: Error) => T) => (error: Error) => T
```