Package Exports

x-http-client

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (x-http-client) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

HttpClient.js

HttpClient.js is a library that aims to make it easier to send data to the server and to parse the data returned by the server in the browsers. It provides both Promise-style and Callback-style API and can be used to send http requests or JSONP requests. It is highly configurable which make it very easy to extend the functionality of this library.

Features

Path variables compilation.
Query string compilation.
Request body processing (JSON, Form, Raw).
Response content processing.
Http requests and JSONP requests.
Timeout and request cancellation.
Promise-style and Callback-style API.

Installation

npm i x-http-client

HttpClient.js

Getting Started

1. Creating HttpClient instance

Sending requests with HttpClient.js is really easy. The first thing we should do is to create an instance of HttpClient. When using HttpClient.js, the best practice is to save the configured HttpClient instance in a single module, and reuse that instance many times.

var HttpClient = require('x-http-client');
var client = new HttpClient({
    baseURL: 'https://api.example.com',
});

The signature of this HttpClient constructor is:

/**
 * @class
 * @param {RequestOptions} [defaultOptions] The default request options.
 * @param {HandleOptionsFunction} [handleOptions] The function to handle the mereged default options.
 */
HttpClient([defaultOptions, [handleOptions]]);

2. Sending HTTP requests

After creating the HttpClient instance, now we can use that instance to send http requests. In the following example, we are going to send an HTTP PUT request to the server.

/**
 * @type {HttpRequest} The return value of `send(...)` is an instance of `HttpRequest`.
 */
var request = client.send({
    // PUT https://api.example.com/posts/1?category=javascript
    method: 'PUT',
    url: '/posts/{postId}',
    param: {
        postId: 1
    },
    query: {
        category: 'javascript'
    },
    headers: {
        'X-My-Custom-Header': 'header-value'
    },
    body: {
        // The property name `json` here tells the library that the type
        // of the data we are going to send to the server is JSON.
        // That means we should use `JSON.stringify(data)` to encode the
        // data before sending it to the server, and set the request
        // header `Content-Type` to `application/json; charset=UTF-8`.
        // The library will use the name `json` to find a request content
        // processor in the `options.httpRequestBodyProcessor` and use
        // that processor to process the data and set request headers.
        // The library provides three processor. They are `json`, `form`
        // and `raw`. You can rewrite them, delete them or add a new one
        // by merge your options to the default options.
        json: {
            title: 'Introducing HttpClient.js',
            content: 'The content of the post...'
        }
    }
}, function (response) {
    var data = response.json();
    console.log(data);
}, function (error) {
    console.log(error.message);
});

3. Sending JSONP requests

You can also use HttpClient instance to send a JSONP request.

/**
 * @type {JSONPRequest} The return value of `getJSONP(...)` is an instance of `JSONPRequest`.
 */
var request = client.getJSONP({
    url: '/dictionary/search',
    query: {
        word: 'javascript'
    },
    timeout: 6000
}, function (response) {
    var data = response.json();
    console.log(data);
}, function (error) {
    console.log(error.message);
});

4. Using Promise

If you prefer the Promise-style API, just change the method name from send to fetch, getJSONP to fetchJSONP.

// Sending HTTP request with Promise-style API:
client.fetch({
    // PUT https://api.example.com/posts/1?category=javascript
    method: 'PUT',
    url: '/posts/{postId}',
    param: {
        postId: 1
    },
    query: {
        category: 'javascript'
    },
    headers: {
        'X-My-Custom-Header': 'header-value'
    },
    body: {
        json: {
            title: 'Introducing HttpClient.js',
            content: 'The content of the post...'
        }
    }
}).then(function (response) {
    var data = response.json();
    console.log(data);
}).catch(function (error) {
    console.log(error.message);
});

// Sending JSONP request with Promise-style API:
client.fetchJSONP({
    url: '/dictionary/search',
    query: {
        word: 'javascript'
    },
    timeout: 6000
}).then(function (response) {
    var data = response.json();
    console.log(data);
}).catch(function (error) {
    console.log(error.message);
});

Default Request Options

{
    // The http request method. The default method is `GET`.
    method: 'GET',

    // The request base url. If the `url` is relative url, and the `baseURL` is not `null`,
    // the `baseURL` will be prepend to the `url`.
    baseURL: null,

    // The request url that can contain any number of placeholders, and will be compiled with
    // the data that passed in with `options.param`.
    url: null,

    // The data used to compile the request url.
    param: null,

    // The data that will be compiled to query string.
    query: null,

    // The object that contains the headers to set when sending the request.
    // Only the non-undefined and non-null headers are set.
    headers: null,

    // The object that contains the content which will be send to the server. This object
    // has only one property. The name of the property is the content type of the content,
    // which will be used to find a processor in `options.httpRequestBodyProcessor`.
    // The processor is used to process the value of the property. The processed value
    // which the processor returns will be send to the server as the request body.
    body: null,

    // The object to keep the extra information that the user passed in. The library itself
    // will not touch this property. You can use this property to hold any information that
    // you want, when you extend the functionality of your own instance of `HttpClient`.
    // The default value of this property is an empty object.
    extra: {},

    // The `CancelController` used to cancel the request. It only works when using `fetch`
    // or `fetchJSONP` to send request. If the you send request using `send` or `getJSONP`,
    // the `options.controller` will be set to `null`.
    controller: null,

    // The name of the function that send the request. Can be `send`, `fetch`, `getJSONP`,
    // `fetchJSONP`. This value is set by the library, don't change it.
    requestFunctionName: null,

    // The request type of this request. The value of it is set by the library itself,
    // can be `HTTP_REQUEST` or `JSONP_REQUEST`. Any other value the user passed in is
    // ignored. You can use this property to get the type of the current request.
    requestType: null,

    // Whether to set `withCredentials` property of the `XMLHttpRequest` to `true`.
    // The default value is `false`.
    cors: false,

    // The object that contains the properties to set on the instance of the `XMLHttpRequest`.
    xhrProps: null,

    // The user name to use for authentication purposes. The defualt value is `null`.
    username: null,

    // The password to use for authentication purposes. The defualt value is `null`.
    password: null,

    // The number of milliseconds the request can take before it finished. If the timeout
    // value is `0`, no timer will be set. If the request does not finsihed within the given
    // time, a timeout error will be thrown. The default value is `0`.
    timeout: 0,

    // Whether to disable the cache. If the value is `true`, the headers in
    // `options.noCacheHeaders` will be set. The default value is `false`.
    noCache: false,

    // The headers to set when `options.noCache` is set to `true`.
    noCacheHeaders: {
        'Pragma': 'no-cache',
        'Cache-Control': 'no-cache, no-store, must-revalidate'
    },

    // The query string key to hold the value of the callback name when sending JSONP request.
    // The default values is `callback`.
    jsonp: 'callback',

    // The object to config the error messages. The keys in the object are error code
    // such as `ERR_NETWORK`.
    errorMessages: {
        ERR_ABORTED: 'Request aborted',
        ERR_CANCELLED: 'Request cancelled',
        ERR_NETWORK: 'Network error',
        ERR_RESPONSE: 'Response error',
        ERR_TIMEOUT: 'Request timeout'
    },

    // The object that contains the http request body processors.
    httpRequestBodyProcessor: {
        raw: {
            priority: 0,
            headers: null,
            processor: null,
        },
        form: {
            priority: 1,
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8'
            },
            processor: function (data, options) {
                return QS.encode(data);
            }
        },
        json: {
            priority: 2,
            headers: {
                'Content-Type': 'application/json; charset=UTF-8'
            },
            processor: function (data, options) {
                return JSON.stringify(data);
            }
        }
    },

    // The object that contains the http response parsers.
    httpResponseParser: {
        json: function () {
            // `this` is point to the current instance of `HttpResponse`.
            var responseText = this.request.xhr.responseText;
            return responseText ? JSON.parse(responseText) : null;
        },
        text: function () {
            return this.request.xhr.responseText;
        },
        status: function () {
            return this.request.xhr.status;
        }
    },

    // The object that contains the jsonp response parsers.
    jsonpResponseParser: {
        json: function () {
            return this.request.jsonpResponseJSON;
        }
    },

    // The object that contains the http response error parsers.
    httpResponseErrorParser: null,

    // The object that contains the jsonp response error parsers.
    jsonpResponseErrorParser: null,

    // The function to handle the options.
    handleOptions: null,

    // The function to create the `XMLHttpRequest` instance.
    createXHR: function (options) {
        return new XMLHttpRequest();
    },

    // The function to create the `HTMLScriptElement` instance.
    createScript: function (options) {
        var script = document.createElement('script');

        script.setAttribute('type', 'text/javascript');
        script.setAttribute('charset', 'utf-8');

        return script;
    },

    // The function that returns the container node, which will be used to append the
    // script element when sending jsonp request.
    jsonpContainerNode: function (options) {
        return document.head || document.getElementsByName('head')[0];
    },

    // The function to generate the unique callback name when sending jsonp request.
    jsonpCallbackName: function (options) {
        return 'jsonp_' + uuid() + '_' + (new Date().getTime());
    },

    // The function to compile url.
    compileURL: function (url, param, options) {
        return template(url, param);
    },

    // The function to encode the query string.
    encodeQueryString: function (data, options) {
        return QS.encode(data);
    },

    // The function to call on xhr created.
    onXhrCreated: null,

    // The functon to call on xhr opened.
    onXhrOpened: null,

    // The function to call on xhr sent.
    onXhrSent: null,

    // The function to call on request created.
    onRequestCreated: null,

    // The function to check whether the response is ok.
    isResponseOk: function (requestType, response) {
        var status;

        // Http reqest
        if (requestType === HTTP_REQUEST) {
            status = response.request.xhr.status;
            return (status >= 200 && status < 300) || status === 304;
        }

        // JSONP request
        return true;
    },

    // The function to transfrom the response error.
    // The return value of this function will be passed to the `onerror` callback.
    transformError: null,

    // The function to transfrom the response.
    // The return value of this function will be passed to the `onsuccess` callback.
    transformResponse: null,

    // The function to check whether to call the error callback.
    shouldCallErrorCallback: null,

    // The function to check whether to call the success callback.
    shouldCallSuccessCallback: null
}

x-http-client