Higher-order functions for WHATWG Fetch. Also includes an opinionated default.
npm install fetch-composeHigher-order functions for WHATWG Fetch. Also includes an opinionated default.
Re-exports the great vercel/fetch-retry library as withRetry and TypeScript support.
Re-exports the also great cross-fetch as fetch.
Re-exports the also also great abortcontroller-polyfill as AbortController only if a system implementation (globalThis.AbortController) is not provided. Otherwise,
the AbortController export will equal globalThis.AbortController, making it safe it use.
yarn add fetch-compose
Using yarn is highly recommended but not required.
When compared to axios or request, the Fetch API is a standard that is
supported across browsers. By using the cross-fetch package (which fetch-compose does),
React Native and Node.js become supported platforms as well.
However, compared to those other options, the Fetch API has less out-of-the-box functionality.
Using JSON data requires constantly setting HTTP headers, additional boilerplate to check if a
request was actually successful, etc.
fetch-compose expands on the concept of higher-order functions
to transform the Fetch API into being extensible and approachable.
fetch-compose also includes an opinionated default that covers most use-cases.
Most users will want to use the "batteries-included" default. An example is below.
./src/fetch.js:
``js
import createFetch from 'fetch-compose'
// Includes JSON, 'query' parameter, throwing an exception on non-ok, and a timeout with default of 10s.
const fetch = createFetch()
export default fetch
`
./src/App.js:
`js
import fetch from './fetch'
// ...
// Use Fetch API like normal, just with sugar!
fetch('/api/createUser', {
method: 'POST',
body: {
name: 'Michael',
},
query: {
apikey: 'abc'
}
})
// ...
`
./src/fetch.js:
`js
import createFetch, { withRetry } from 'fetch-compose'
const fetch = withRetry(createFetch())
export default fetch
`
./src/fetch.js:
`js
import { fetch, withJSON, withQuery, withThrowNonOk, withTimeout } from 'fetch-compose'
// Same as Default in README.md.
const fetch = withJSON(withQuery(withThrowNonOk(withTimeout(fetch))))
export default fetch
`
./src/fetch.js:
`js
import createFetch, { withJWTToken } from 'fetch-compose'
// Information for our login system.
const provider = {
baseHostname: 'dji.com',
getToken() {
return 'token'
},
async refreshToken() {
await doAsyncRefreshAction()
// We now have a new token! fetch-compose is able to retry the request.
}
}
const fetch = withJWTToken(createFetch(), provider)
export default fetch
`
./src/fetch.js:
`js
import compose from '@f/compose'
import { fetch, withJSON, withQuery, withThrowNonOk, withTimeout } from 'fetch-compose'
const fetch = compose(withJSON, withQuery, withThrowNonOk, withTimeout)(fetch)
export default fetch
`
Copyright 2020 DJI Technology LLC.
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
- Fetch
- withThrowNonOk
- Parameters
- withQuery
- Parameters
- withJSON
- Parameters
- CredentialProvider
- Properties
- baseHostname
- getToken
- refreshToken
- withTimeout
- Parameters
- createFetch
- Parameters
- withJWTToken
- Parameters
packages/fetch-compose/lib/types.ts:4-7
Generic type for WHATWG Fetch API.
Type: function (req: RequestInfo, opts: Partial<T>): Promise<Response>
packages/fetch-compose/lib/withThrowNonOk.ts:6-17
Throws a generic Error if HTTP response is not "ok".
- fetch Fetch<T>
Returns Fetch<T>
packages/fetch-compose/lib/withQuery.ts:13-32
If Fetch options include an object 'query', this will be converted
into the search params of the URL.
- fetch Fetch<T>
Returns Fetch<any>
packages/fetch-compose/lib/withJSON.ts:14-38
If Fetch options include a plain-object 'body', this will be converted
into JSON with the Content-Type properly set to 'application/json' if not in 'headers'.
- fetch Fetch<T>
Returns Fetch<any>
packages/fetch-compose/lib/withJWTToken.ts:15-31
Provider that is passed to 'withJWTToken'.
Type: {baseHostname: string, getToken: function (): Promise<string>, refreshToken: function (): Promise<void>}
- baseHostname string getToken
- function (): Promise<string> refreshToken
- function (): Promise<void>
packages/fetch-compose/lib/withJWTToken.ts:19-19
Base hostname for what credentials should be offered.
Type: string
packages/fetch-compose/lib/withJWTToken.ts:23-23
Gets the current JWT token.
Type: function (): Promise<string>
packages/fetch-compose/lib/withJWTToken.ts:30-30
Refresh the JWT token using the refresh token.
MUST throw an error on unsuccessful refresh for the higher-order function
to work properly.
Type: function (): Promise<void>
packages/fetch-compose/lib/withTimeout.ts:33-63
Based on this:
Will cancel request after timeout, with a default timeout of 10s.
Allows an optional field named 'timeout'.
- fetch Fetch<T> defaultTimeout
- number (optional, default DEFAULT_TIMEOUT)
Returns Fetch<any>
packages/fetch-compose/lib/index.ts:34-36
Creates an opinionated default for fetch.
- Automatically transforms a 'body' object into JSON request.
- Automatically appends a 'query' option into the search params of the request.
- Throws an error on non-2xx HTTP responses.
- Allows request to specify a timeout, with default of 10s.
- fetchVal Fetch<RequestInit>?
packages/fetch-compose/lib/withJWTToken.ts:48-128
Handles adding the bearer token for authorized routes, otherwise
attempting to refresh the JWT token from backend.
Requires an implementation of {@type CredentialProvider}
Allows an optional field named 'skipRefresh'.
- fetch Fetch<T> credentialProvider` CredentialProvider
-
Returns Fetch<any>