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

``javascript
const wiseFetch = require('wise-fetch');

(async () => {
const response = await wiseFetch('https://example.org');

response.status; //=> 200
response.headers.get('content-length'); //=> '606'

const text = await response.text();
//=> '\n\n\n ...'
})();
`

Installation

Use npm.

`
npm install wise-fetch
`

API

`javascript
const wiseFetch = require('wise-fetch');
`

$3

url: string | URL (HTTP or HTTPS URL)
options: Object
Return: Promise

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.

`javascript
(async () => {
try {
await wiseFetch('https://github.com/shinnn/it_does_not_exist');
} catch (err) {
err.message; //=> '404 (Not Found) responded by a GET request to https://github.com/shinnn/it_does_not_exist.'
err.reponse.status; //=> 404
await err.reponse.arrayBuffer(); //=> 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 of https-proxy or proxy npm config depending on the request protocol.
* noProxy option defaults to no-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.

`javascript
(async () => {
const response = await wiseFetch('~shinnn', {baseUrl: 'https://www.npmjs.com'});
response.url; //=> 'https://www.npmjs.com/~shinnn'
})();
`

##### options.resolveUnsuccessfulResponse

Type: boolean
Default: false

Return a resolved Promise even if the response is unsuccessful.

`javascript
(async () => {
const response = await wiseFetch('https://github.com/shinnn/this_does_not_exist', {
resolveUnsuccessfulResponse: true
});

response.statusText; //=> '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.

`javascript
const AbortController = require('abort-controller');

const abortController = new AbortController();

(async () => {
try {
await wiseFetch('https://loclahost:5000/very_large_contents', {signal: abortController.signal});
} catch (err) {
err.message; //=> '... The GET request to https://loclahost:5000/very_large_contents was aborted'
}
})();

setTimeout(() => abortController.abort(), 1000);
`

##### options.userAgent

Type: string

A shorthand for setting user-agent property of headers option.

$3

baseOptions: Object
Return: Function

Create a new wiseFetch with the given defaults.

`javascript
const getGithubUserData = wiseFetch.create({
baseUrl: 'https://api.github.com/users/',
headers: {
accept: 'application/vnd.github.v3+json',
'user-agent': 'your app name'
}
});

(async () => {
await (await getGithubUserData('shinnn')).json();
//=> {login: 'shinnn', id: 1131567, created_at: '2011-10-16T16:36:43Z', ...}
})();
`

headers of each function call will be merged to the base headers.

`javascript
const newWiseFetch = wiseFetch.create({
headers: {
'header-A': 'old value'
'header-B': 'value'
}
});

newWiseFetch('https://example.org', {
headers: {
'header-A': 'updated value',
'header-C': 'new value'
}
});
/* The final header is {
'header-A': 'updated value',
'header-B': 'value'
'header-C': 'new value'
}. */
`

##### baseOptions.frozenOptions

Type: Set

Make given options unconfigurable in each function call.

`javascript
const alwaysPost = wiseFetch.create({
method: 'post',
frozenOptions: new Set(['method'])
});

(async () => {
try {
await alwaysPost('https://example.org/api', {method: 'patch'});
} catch (err) {
err.toString();
//=> 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.

`javascript
(async () => {
const response = await wiseFetch('https://example.org/', {urlModifier: url => ${url}?x=1});
response.url; //=> 'https://example.org/?x=1'
})();
`

##### baseOptions.additionalOptionValidators

Type: Array

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.

`javascript
const {username} = require('os').userInfo();

const forceYourUA = wiseFetch.create({
additionalOptionValidators: [
options => {
if (options.userAgent && !options.userAgent.includes(username)) {
throw new Error('user agent must include your name!');
}
}
]
});

forceYourUA('https://example.org', {userAgent: 'nothing'});
// rejected with an Error: 'user agent must include your name!'
`

$3

Type: integer

An error code that wiseFetch adds to the error when the request is aborted.

`javascript
(async () => {
try {
await wiseFetch('https://example.org/', {signal: someSignal});
} catch (err) {
if (err.code === wiseFetch.ABORT_ERROR_CODE) {
console.log('Canceled');
} else {
throw err;
}
}
})();
`

$3

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