Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including funtch with all npm packages installed. Try it out:

var funtch = require("funtch")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

funtch v2.1.1

FUNctional feTCH isomorphic

funtch - Functional Fetch

CI Status Doc Status codecov npm version Quality Gate Status

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 nameParamsDescription
geturl: StringPerform a GET
posturl: String
body: Any
Perform a POST with given body and Content-type guessed from param
puturl: String
body: Any
Perform a PUT with given body and Content-type guessed from param
patchurl: String
body: Any
Perform a PATCH with given body and Content-type guessed from param
deleteurl: StringPerform 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:

Methode nameParamsDescription
headerkey: String
value: String
Add HTTP header
authvalue: StringAdd Authorization Header with given value
contentJsonAdd Content-type: application/json header
contentTextAdd Content-type: text/plain header
guessContentTypebody: AnyGuess content type by checking if body is a JSON. If true, content is set to JSON, otherwise to text
acceptJsonAdd Accept: application/json header
acceptTextAdd Accept: text/plain header
contentSee content handler
errorSee error handler
bodybody: Any
guess: Boolean default true
Set body content of request, and guessing content on the fly
getSet method to GET and send request
postbody: AnySet method to POST, add body if provided with content guess and send request
putbody: AnySet method to PUT, add body if provided with content guess and send request
patchbody: AnySet method to PATCH, add body if provided with content guess and send request
deleteSet method to DELETE and send request
methodmethod: StringSet HTTP method to given value
sendSend request as it

All these method are chainable and once send, 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));

You can create a pre-configured builder, in order to avoid repeating yourself, by passing an object to the withDefault method. content and error are named contentHandler and errorHandler respectively, all others properties have the same name as above.

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

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

Error Handling

By default, funtch will reject promise with an object describing error if HTTP status is greater or equal than 400. This object contains HTTP status, response headers and content (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'
  },
  content: '404 page not found',
}

Customization

Custom content handler

By default, fetch expose 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 accept 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 return 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 error() on the builder. The error handler method accept a response 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')
  .error(errorWithToString)
  .get()
  .catch(err => console.log(String(err)));
RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free