funtch - Functional Fetch

Fetch based on isomorphic-fetch with functional and customizable behavior.

Getting started

Add dependency to your project

npm i -S funtch

Usage

Full documentation is available here.

Full usage example in example folder

ES6

import funtch from 'funtch';

funtch.get('https://api.github.com').then((data) => doSomething(data));

CommonJS

const funtch = require('funtch').default;

funtch.get('https://api.github.com').then((data) => doSomething(data));

API

You can send HTTP requests from common verbs by invoking the following methods from funtch:

Methode name	Params	Description
get	url: String query: Object/Map	Perform a GET with optional query params
post	url: String body: Any	Perform a POST with given body and Content-type guessed from param
put	url: String body: Any	Perform a PUT with given body and Content-type guessed from param
patch	url: String body: Any	Perform a PATCH with given body and Content-type guessed from param
delete	url: String	Perform a DELETE

If default pattern doesn't match your needs, you can build a step by step request by invoking funtch.url(url: String) and applying following methods:

Method name	Params	Description
query	query: Object/Map	Append query params when requesting
header	key: String value: String	Add HTTP header
auth	value: String	Add Authorization Header with given value
contentJson		Add Content-type: application/json header
contentText		Add Content-type: text/plain header
guessContentType	body: Any	Guess content type by checking if body is a JSON. If true, content is set to JSON, otherwise to text
acceptJson		Add Accept: application/json header
acceptText		Add Accept: text/plain header
contentHandler	callback: func(response)	See content handler
errorHandler	callback: func(response, contentHandler)	See error handler
abortHandler	callback: func(error)	Callback method when request is aborted
fullResponse		Return complete response with {status, headers, data}, instead of just raw data by default
body	body: Any guess: Boolean default true	Set body content of request, and guessing content on the fly
get		Set method to GET and send request
post	body: Any	Set method to POST, add body if provided with content guess and send request
put	body: Any	Set method to PUT, add body if provided with content guess and send request
patch	body: Any	Set method to PATCH, add body if provided with content guess and send request
delete		Set method to DELETE and send request
method	method: String	Set HTTP method to given value
send		Send request as it
abort		Abort request

All these methods, except abort, are chainable and once send is called, the result is a Promise.

const fetchPromise = funtch
  .url('https://api.github.com')
  .auth('Basic SECRET')
  .contentJson()
  .acceptJson()
  .post({ star: true });

fetchPromise
  .then((data) => console.log(data))
  .catch((err) => console.error(data));

Cancelable request can be done this way.

const fetchRequest = funtch
  .url('https://api.vibioh.fr/delay/10') // 10 seconds delay
  .abortHandler((e) => console.warn(`Request was aborted: ${e.name}`));

fetchRequest.get();
fetchRequest.abort();

You can create a pre-configured builder, in order to avoid repeating yourself, by passing an object to the withDefault method with keys as the config function name.

const funtcher = funtch.withDefault({
  baseURL: 'https://api.github.com',
  auth: 'github SecretToken',
  fullResponse: true,
  contentJson: true,
});

funtcher.get('/user/keys').then((response) => doSomething(response.data));
funtcher
  .post('/user/keys', 'my-ssh-key')
  .then((response) => doSomething(response.data));

Error Handling

By default, funtch will rejects promise with a full response describing error if HTTP status is greater or equal than 400. This object contains HTTP status, response headers and data (in plain text or JSON, according to content handler).

{
  status: 404,
  headers: {
    'content-length': '19',
    'content-type': 'text/plain; charset=utf-8',
    date: 'Sat, 06 May 2017 11:58:38 GMT',
    'x-content-type-options': 'nosniff',
    connection: 'close'
  },
  data: '404 page not found',
}

Customization

Custom content handler

By default, fetch exposes only two methods for reading content : text() and json(). Instead of juggling with these methods, funtch return content by examining Content-Type header and call one of the two methods.

You can easily override default content handler by calling content() on the build. The content handler method accepts a reponse and return a Promise. Method is also passed to error handler method, in order to read content while identifying error.

Below an example that parse XML response.

import funtch { MEDIA_TYPE_JSON, CONTENT_TYPE_HEADER } from 'funtch';

const contentTypeJsonRegex = new RegExp(MEDIA_TYPE_JSON, 'i');
const contentTypeXmlRegex = /application\/xml/i;

function xmlContent(response) {
  if (contentTypeJsonRegex.test(response.headers.get(CONTENT_TYPE_HEADER))) {
    return response.json();
  }

  return new Promise(resolve => {
    response.text().then(data => {
      if (contentTypeXmlRegex.test(response.headers.get(CONTENT_TYPE_HEADER))) {
        resolve(new DOMParser().parseFromString(data, 'text/xml'));
      }
      resolve(data);
    });
  });
}

funtch
  .url('https://api.github.com')
  .content(xmlContent)
  .get();

Custom error handler

By default, fetch returns a valid Promise without considering http status. Funtch error handler is called first, in this way, you can identify an error response and reject the Promise. By default, if HTTP status is greather or equal than 400, it's considered as error.

You can easyly override default error handler by calling errorHandler() on the builder. The error handler method accepts a response and a content handler, and return a Promise. You can reimplement it completely or adding behavior of the default one.

Below an example that add a toString() behavior.

import funtch, { errorHandler } from 'funtch';

function errorWithToString(response) {
  return new Promise((resolve, reject) =>
    errorHandler(response)
      .then(resolve)
      .catch((err) =>
        reject({
          ...err,
          toString: () => {
            if (typeof err.content === 'string') {
              return err.content;
            }
            return JSON.stringify(err.content);
          },
        }),
      ),
  );
}

funtch
  .url('https://api.github.com')
  .errorHandler(errorWithToString)
  .get()
  .catch((err) => console.log(String(err)));