wise-fetch
Feature-rich node-fetch:
- Built-in RFC compliant response cache
- Proxy support
- Abortable
- Base URL support
- Automatic
Promise
rejection of unsuccessful responses by default - Strict URL validation
const wiseFetch = ; async { const response = await ; responsestatus; //=> 200 responseheaders; //=> '606' const text = await responsetext; //=> '<!doctype html>\n<html>\n<head>\n <title>Example Domain</title> ...'};
Installation
npm install wise-fetch
API
const wiseFetch = ;
wiseFetch(url [, options])
url: string | URL
(HTTP or HTTPS URL)
options: Object
Return: Promise<Response>
The API is very similar to the browser fetch
API. It makes an HTTP or HTTPS request and returns a Promise
of a node-fetch-npm Response
object that works as if DOM Response
but has additional methods.
Unlike the fetch
API, when the response is unsuccessful, that is, its status code is neither 2xx
, 304
, it will be rejected with an Error
with a response
property.
async { try await ; catch err errmessage; //=> '404 (Not Found) responded by a GET request to https://github.com/shinnn/it_does_not_exist.' errreponsestatus; //=> 404 await errreponse; //=> ArrayBuffer { ... } (the response body) };
The response is cached to the OS's default directory for temporary files in the RFC 7234 compliant way.
options
It supports the all options that make-fetch-happen can receives, except for counter
and cacheManager
.
When the program is running as an npm script, note that:
proxy
option defaults to the value ofhttps-proxy
orproxy
npm config depending on the request protocol.noProxy
option defaults tono-proxy
npm config.
Additionally, the following wise-fetch specific options are available.
options.baseUrl
Type: string | URL
Set the base URL to resolve against if the request URL is not absolute.
async { const response = await ; responseurl; //=> 'https://www.npmjs.com/~shinnn'};
options.resolveUnsuccessfulResponse
Type: boolean
Default: false
Return a resolved Promise
even if the response is unsuccessful.
async { const response = await ; responsestatusText; //=> 'Not Found'};
options.signal
Type: AbortSignal
Allow a user to abort the request via the corresponding AbortController
. Read the article about abortable fetch for more details.
Currently Node.js doesn't support AbortController
, so that users need to substitute the userland implementation for it.
const AbortController = ; const abortController = ; async { try await ; catch err errmessage; //=> '... The GET request to https://loclahost:5000/very_large_contents was aborted' }; ;
options.userAgent
Type: string
A shorthand for setting user-agent
property of headers
option.
wiseFetch.create(baseOptions)
baseOptions: Object
Return: Function
Create a new wiseFetch
with the given defaults.
const getGithubUserData = wiseFetch; async { await await ; //=> {login: 'shinnn', id: 1131567, created_at: '2011-10-16T16:36:43Z', ...}};
headers
of each function call will be merged to the base headers.
const newWiseFetch = wiseFetch; ;/* The final `header` is { 'header-A': 'updated value', 'header-B': 'value' 'header-C': 'new value'}. */
baseOptions.frozenOptions
Type: Set<string>
Make given options unconfigurable in each function call.
const alwaysPost = wiseFetch; async { try await ; catch err err; //=> TypeError: 'method' option is not configurable, but it was tried to be configured. };
baseOptions.urlModifier
Type: Function
Update a request URL to the value this function returns, before applying baseUrl
option to it.
This function receives the original URL and is expected to return a string
or URL
.
async { const response = await ; responseurl; //=> 'https://example.org/?x=1'};
baseOptions.additionalOptionValidators
Type: Array<Function>
An array of functions that performs additional option validation. Each functions receive an options Object
and if at least one of then throws an error, wiseFetch
will be rejected.
const username = ; const forceYourUA = wiseFetch; ;// rejected with an Error: 'user agent must include your name!'
wiseFetch.ABORT_ERROR_CODE
Type: integer
An error code
that wiseFetch adds to the error when the request is aborted.
async { try await ; catch err if errcode === wiseFetchABORT_ERROR_CODE console; else throw err; };
wiseFetch.CACHE_DIR
Type: string
A path of the directory where wise-fetch saves response cache.
Users can clear cache by deleting this directory.
License
ISC License © 2018 - 2019 Shinnosuke Watanabe