Wise-fetch NPM

wise-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 = 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

Use npm.

npm install wise-fetch

API

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:

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.

(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;
    }
  }
})();