wise-fetch
v0.4.0-1
Published
Feature-rich node-fetch
Downloads
28
Maintainers
shinnnReadme
wise-fetch
Feature-rich node-fetch:
- Built-in RFC compliant response cache
- Proxy support
- Abortable
- Base URL support
- Automatic
Promiserejection of unsuccessful responses by default - Strict URL validation
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();
//=> '<!doctype html>\n<html>\n<head>\n <title>Example Domain</title> ...'
})();Installation
npm install wise-fetchAPI
const wiseFetch = require('wise-fetch');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 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:
proxyoption defaults to the value ofhttps-proxyorproxynpm config depending on the request protocol.noProxyoption defaults tono-proxynpm 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 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.
(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.
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.
wiseFetch.create(baseOptions)
baseOptions: Object
Return: Function
Create a new wiseFetch with the given defaults.
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.
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<string>
Make given options unconfigurable in each function call.
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.
(async () => {
const response = await wiseFetch('https://example.org/', {urlModifier: url => `${url}?x=1`});
response.url; //=> '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} = 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!'wiseFetch.ABORT_ERROR_CODE
Type: integer
An error code that wiseFetch adds to the error when the request is aborted.
(async () => {
try {
await wiseFetch('https://example.org/', {signal: someSignal});
} catch (err) {
if (err.code === wiseFetch.ABORT_ERROR_CODE) {
console.log('Canceled');
} 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