@rg-3/http-client.js NPM

http-client.js

Introduction
Features
Examples
Install
License

Introduction

A light promise-based abstraction around XMLHttpRequest.

Features

Supports making requests with the HEAD, GET, POST, PUT, and PATCH verbs.
Supports adding HTTP header(s) to a request.
Supports adding a request body.
Supports request time outs.
Supports providing query parameters as an object literal.
light: dist/http-client.min.js is transpiled ES5 - it is minified and weighs 1.2kb.

Examples

This example makes a GET request to /blog.json?id=10 with the Accept header set to application/json.

import httpclient from 'http-client.js';
new httpclient()
    .get('/blog.json', {params: {id: 10}, headers: {'Accept': 'application/json'}})
    .then((xhr) => JSON.parse(xhr.responseText))
    .catch((xhr) => console.log(xhr));

The cause of request failure can be found at xhr.httpclient.cause and it returns one of the following strings: abort, timeout, error, status:

new httpclient().get('/index.html').catch((xhr) => {
  switch(xhr.httpclient.cause) {
  case 'abort':
    return console.log('request aborted')
  case 'timeout':
    return console.log('request timed out')
  case 'error':
    return console.log('network error (including cross-origin errors)')
  case 'status':
    return console.log(`response status code is ${xhr.status}, not 2XX`)
  default:
    throw new Error("Shouldn't happen");
  }
});

A httpclient object can operate under a timeout (measured in ms) by providing a timeout option as this example shows:

import httpclient from 'http-client.js';
const client = new httpclient({timeout: 1000});
client.get('/index.html').then(..).catch(..);
client.get('/projects.html').then(..).catch(..);

The timeout can be overridden on a per-request basis by passing a timeout option to a verb method such as get:

import httpclient from 'http-client.js';
const client = new httpclient({timeout: 500});
client.get('/index.html').then(..).catch(..);
client.get('/projects.html', {timeout: 5000}).then(..).catch(..);

In environments where you can make cross-origin requests you can set the baseURI when creating a new client:

import httpclient from 'http-client.js';
const client = new httpclient({baseURI: 'https://www.twitter.com'});
client.get(...);

Install

NPM environment

If you're in a NPM environment, there's an NPM package to use.
The package should be required or imported as @rg-3/http-client.js.
http-client.js is implemented as an ES6 module, you might need to
use babel in order to use it in a node environment.

# npm users
$ npm i --save @rg-3/http-client.js

# yarn users
$ yarn add @rg-3/http-client.js

Old school method

If you're in a browser environment without NPM, you can save dist/http-client.min.js to your project and link to it from a <script> tag. It has been transpiled to ES5, and adds window.httpclient.