x-http-client

HttpClient.js

An http client to simplify sending requests (Http & JSONP) in the browser.

点击此处查看中文说明文档

Features

• Promise-style and callback-style API.
• Send Http & JSONP requests.
• Compile url and query string.
• Cancel request and set timeout.
• Headers, cache control and CORS.
• Configurable http request body processor.
• Configurable function to check whether the response is ok.
• Configurable functions to transform the responses and the errors.
• Configurable mixins to the responses and the errors.
• Other flexible and useful configuration.

Install

If you are using npm, just install x-http-client as a dependency.

npm i x-http-client

Otherwise you can import the bundle file with script tag directly.

<script src="/path/to/HttpClient.min.js"></script>

Note that the bundle file also can be used as an AMD module, which means it can be loaded by require.js.

Example

1. An exmaple of GET request

import HttpClient from 'x-http-client';
 
/**
 * Tip: You'd better save the configured instance of `HttpClient` in
 * a individual module and reuse it in other place of your project.
 */
const client = new HttpClient({
    baseURL: 'https://example.com'
});
 
/**
 * GET https://example.com/posts/1
 */
client.fetch({
    url: '/posts/1'
}).then(response => {
    return response.json();
}).then(data => {
    console.log(data);
}).catch(error => {
    console.error(error);
});

2. An exmaple of PUT request

import HttpClient from 'x-http-client';
 
/**
 * Tip: You'd better save the configured instance of `HttpClient` in
 * a individual module and reuse it in other place of your project.
 */
const client = new HttpClient({
    baseURL: 'https://example.com'
});
 
/**
 * PUT https://example.com/posts/1?category=2
 */
client.fetch({
    // The http request method, default is `GET`. Here we use `PUT`.
    method: 'PUT',
    // The url to request. It will be compiled before sending request.
    url: '/posts/{ postId }',
    // The data used to compile the url above.
    model: {
        postId: 1
    },
    // The data to be compiled to query string.
    query: {
        category: 2
    },
    // The request headers to set.
    headers: {
        'X-My-Custom-Header': 'value'
    },
    // The body of the http request.
    body: {
        // Send JSON data to the server. The request content type will
        // be set to `application/json; charset=UTF-8` and the data
        // will be converted to a JSON string automaticly.
        // For more details, please read the descriptions of the
        // option called `body` and `httpRequestBodyProcessor`.
        json: {
            title: 'Using HttpClient.js',
            content: '...'
        }
    }
}).then(response => {
    return response.json();
}).then(data => {
    console.log(data);
}).catch(error => {
    console.error(error);
});

Default request options

{
    /**
     * The http request method.
     */
    method: 'GET',
 
    /**
     * The base url.
     */
    baseURL: '',
 
    /**
     * The url to request. If the url is a relative url and the base url is not empty,
     * the `baseURL` will be prepended to the `url`. The `url` and `baseURL` can contain
     * placeholders like `{ post.id }`, which will be replaced by the corresponding value
     * in the option called `model`.
     */
    url: '',
 
    /**
     * The data used to compile the request url.
     */
    model: null,
 
    /**
     * The data used to compile to query string.
     */
    query: null,
 
    /**
     * The http request headers to set.
     */
    headers: null,
 
    /**
     * The body of the http request. `body` is a simple plain object that contains only
     * one property, like `json` or `form`. The property name is used to find a http
     * request body processor in the option called `httpRequestBodyProcessor`.
     * The processor we found will be used to process the value of the property,
     * and add smome extra headers to the request if needed.
     * We provide three default http request body processors.
     * json - convert the data to JSON string (application/json; charset=UTF-8).
     * form - convert the data to form-urlencoded (application/x-www-form-urlencoded; charset=UTF-8).
     * raw - the data will not be processed and no extra headers will be added.
     * For more details, please read the description of `httpRequestBodyProcessor`.
     */
    body: null,
 
    /**
     * The maximum time (in millisecond) to wait for the response. If the request not
     * finished in the given time, an error (`ERR_TIMEOUT`) will be thrown. If the timeout
     * is less than or equal to zero, no timeout will be set.
     */
    timeout: 0,
 
    /**
     * The default timeout when sending JSONP requests. If the `timeout` is less than or equal to
     * zero this value will be used as `timeout`. So, if you want to disable timeout when sending
     * JSONP requests (NOT recommended), you should set `timeout` and `jsonpDefaultTimeout` to zero.
     */
    jsonpDefaultTimeout: 60000,
 
    /**
     * If `cors` is set to `true`, the `withCredentials` property of the `XMLHttpRequest` instance
     * will be set to `true` when sending http requests.
     */
    cors: false,
 
    /**
     * Whether to disable cache. If this value is set to `true`, the headers defined in
     * `noCacheHeaders` will be added to the request headers.
     */
    noCache: false,
 
    /**
     * The headers to be added to the request headers when `noCache` is set to `true`.
     */
    noCacheHeaders: {
        'Pragma': 'no-cache',
        'Cache-Control': 'no-cache, no-store, must-revalidate'
    },
 
    /**
     * The url search param name that used to hold the callback name when sending JSONP requests.
     */
    jsonp: 'callback',
 
    /**
     * The namespace reserved for the users who want extend the library. The library itself will
     * not use this field.
     */
    settings: {},
 
    /**
     * The cancel controller that be used to cancel requests when using promise API. If you are
     * using callback API, this property is ignored and will be set to `null` forcely.
     */
    controller: null,
 
    /**
     * The name of the function that you are using to send requests. The value is set internally,
     * which can be `send`, `fetch`, `getJSONP` or `fetchJSONP`.
     */
    requestFunctionName: null,
 
    /**
     * The type of the request, can be `HTTP_REQUEST` or `JSONP_REQUEST`. The value is set
     * internally.
     */
    requestType: null,
 
    /**
     * The object contains the properties that will be set to the `XMLHttpRequest` instance.
     */
    xhrProps: null,
 
    /**
     * The username to use when call `XMLHttpRequest#open()`.
     */
    username: null,
 
    /**
     * The password to use when call `XMLHttpRequest#open()`.
     */
    password: null,
 
    /**
     * The object to hold http request body processors.
     */
    httpRequestBodyProcessor: {
        /**
         * The built-in processor `raw`. This processor process the request body by not
         * processing it. You can use this processor when you want to send `FormData`,
         * `ArrayBuffer`, `Blob` or anything that do not need to be processed.
         */
        raw: {
            /**
             * The higher the number, the higher the priority.
             */
            priority: 0,
            /**
             * No extra headers will be added when using `raw` processor.
             */
            headers: null,
            /**
             * The data will not be transformed when using `raw` processor.
             */
            processor: null
        },
        /**
         * The built-in processor `form`. This processor will transform the request body
         * (an object) to the `form-urlencoded` string and set the request header
         * `Content-Type` to `application/x-www-form-urlencoded; charset=UTF-8`.
         * You can change the charset by overwrite the headers of this processor.
         */
        form: {
            /**
             * The higher the number, the higher the priority.
             */
            priority: 1,
            /**
             * The extra headers to be added when using `form` processor.
             */
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8'
            },
            /**
             * The function used to process the request body.
             *
             * @param {Object.<string, *>} data The data to be processed.
             * @param {RequestOptions} options The request options.
             * @returns {string} Returns the processed data that will send to the server.
             */
            processor: function (data, options) {
                // encodeQueryString = require('x-query-string/encode')
                return encodeQueryString(data);
            }
        },
        /**
         * The built-in processor `json`. This processor will transform the request body
         * (an object) to a JSON string and set the header `Content-Type` to
         * `application/json; charset=UTF-8`. You can change the charset by overwrite the
         * headers of this processor.
         */
        json: {
            /**
             * The higher the number, the higher the priority.
             */
            priority: 2,
            /**
             * The extra headers to be added when using `json` processor.
             */
            headers: {
                'Content-Type': 'application/json; charset=UTF-8'
            },
            /**
             * The function used to process the request body.
             *
             * @param {Object.<string, *>} data The data to be processed.
             * @param {RequestOptions} options The request options.
             * @returns {string} Returns the processed data that will send to the server.
             */
            processor: function (data, options) {
                return JSON.stringify(data);
            }
        }
    },
 
    /**
     * The object to hold the mixins of the http response.
     */
    httpResponseMixin: {
        /**
         * The mixin function to parse the http response body as JSON string.
         *
         * @throws {SyntaxError} Throws error on parsing failed.
         * @returns {any} Returns the parsed data.
         */
        json: function () {
            var responseText = this.request.xhr.responseText;
            return responseText ? JSON.parse(responseText) : null;
        },
        /**
         * The mixin function to retrive the text of the response body.
         *
         * @returns {string} Returns the response text.
         */
        text: function () {
            return this.request.xhr.responseText;
        },
        /**
         * The mixin function to retrive the response status.
         *
         * @returns {number} Returns the response status.
         */
        status: function () {
            return this.request.xhr.status;
        }
    },
 
    /**
     * The object to hold the mixins of the jsonp response.
     */
    jsonpResponseMixin: {
        /**
         * The function to retrive the response JSON of JSONP request.
         *
         * @returns {any} Returns the response JSON.
         */
        json: function () {
            return this.request.responseJSON;
        }
    },
 
    /**
     * The object to hold the mixins of the http response error.
     */
    httpResponseErrorMixin: null,
 
    /**
     * The object to hold the mixins of the JSONP response error.
     */
    jsonpResponseErrorMixin: null,
 
    /**
     * The function to handle the request options. If this function is set,
     * it will be called before we using the request options.
     *
     * @param {RequestOptions} options The request options
     * @returns {void} The return value is ignored.
     */
    handleOptions: null,
 
    /**
     * The function to create an instance of `XMLHttpRequest`.
     *
     * @param {RequestOptions} options The request options.
     * @returns {XMLHttpRequest} Returns an instance of `XMLHttpRequest`.
     */
    createXHR: function (options) {
        return new XMLHttpRequest();
    },
 
    /**
     * The function to create the script element when sending JSONP request.
     *
     * @param {RequestOptions} options The request options.
     * @returns {HTMLScriptElement} Returns a script element.
     */
    createScript: function (options) {
        var script = document.createElement('script');
 
        script.setAttribute('type', 'text/javascript');
        script.setAttribute('charset', 'utf-8');
 
        return script;
    },
 
    /**
     * The function get the element that will be used to inject the script
     * element when sending JSONP request.
     *
     * @param {RequestOptions} options The request options.
     * @returns {HTMLElement} Returns an HTML element.
     */
    jsonpContainerNode: function (options) {
        return document.head || document.getElementsByName('head')[0];
    },
 
    /**
     * The function to create a unique callback name when sending JSONP request.
     *
     * @param {RequestOptions} options The request options.
     * @returns {string} Returns a string that will be used as JSONP callback name.
     */
    jsonpCallbackName: function (options) {
        return 'jsonp_' + uuid() + '_' + (new Date().getTime());
    },
 
    /**
     * The function to compile the URL.
     *
     * @param {string} url The url string to be compiled (with baseURL prepended if needed).
     * @param {Object.<string, *>} model The data used to compile the url.
     * @param {RequestOptions} options The request options.
     * @returns {string} Returns the compiled url.
     */
    compileURL: function (url, model, options) {
        return template(url, model);
    },
 
    /**
     * The function to encode the query string.
     *
     * @param {Object.<string, *>} query The data to be compiled to query string.
     * @param {RequestOptions} options The request options.
     * @returns {string} Returns the compiled query string.
     */
    encodeQueryString: function (query, options) {
        // encodeQueryString = require('x-query-string/encode')
        return encodeQueryString(query);
    },
 
    /**
     * The callback on `XMLHttpRequest` instance created.
     *
     * @param {XMLHttpRequest} xhr The created `XMLHttpRequest` instance.
     * @param {RequestOptions} options The request options.
     * @returns {void} The reutrn value is ignored.
     */
    onXhrCreated: null,
 
    /**
     * The callback on `XMLHttpRequest` opened.
     *
     * @param {XMLHttpRequest} xhr The `XMLHttpRequest` instance.
     * @param {RequestOptions} options The request options.
     * @returns {void} The reutrn value is ignored.
     */
    onXhrOpened: null,
 
    /**
     * The callback on `XMLHttpRequest` sent.
     *
     * @param {XMLHttpRequest} xhr The `XMLHttpRequest` instance.
     * @param {RequestOptions} options The request options.
     * @returns {void} The reutrn value is ignored.
     */
    onXhrSent: null,
 
    /**
     * The callback on request created.
     *
     * @param {HttpRequest|JSONPRequest} request The current request.
     * @returns {void} The reutrn value is ignored.
     */
    onRequestCreated: null,
 
    /**
     * The function to check whether the repsonse is ok.
     *
     * @param {string} requestType The request type, can be `HTTP_REQUEST` or `JSONP_REQUEST`.
     * @param {HttpResponse|JSONPResponse} response The response object.
     * @returns {boolean} Returns `truthy` on response is ok, otherwise returns `falsy`.
     */
    isResponseOk: function (requestType, response) {
        var isOk;
        var status;
 
        // Http request.
        if (requestType === HTTP_REQUEST) {
            status = +response.request.xhr.status;
            isOk = (status >= 200 && status < 300) || status === 304;
        // JSONP request.
        } else {
            isOk = true;
        }
 
        return isOk;
    },
 
    /**
     * The function to transform the response error. If it is `null` or not a function,
     * the response error will not be transformed.
     *
     * @param {string} requestType The request type, can be `HTTP_REQUEST` or `JSONP_REQUEST`.
     * @param {HttpResponseError|JSONPResponseError} error The response error object.
     * @returns {any} The return value of this function will be used as response error.
     */
    transformError: null,
 
    /**
     * The function to transform the response. If it is `null` or not a function, the
     * response will not be transformed.
     *
     * @param {string} requestType The request type, can be `HTTP_REQUEST` or `JSONP_REQUEST`.
     * @param {HttpResponse|JSONPResponse} response The response object.
     * @returns {any} The return value of this function will be used as response.
     */
    transformResponse: null,
 
    /**
     * The function to check whether to call the error callback on an error happend. If it is
     * `null` or not a function, the error callback will be called. If it is a function and
     * the function returns a `falsy` value the error callback will not be called. Otherwise
     * the error callback will be called.
     *
     * @param {string} requestType The request type, can be `HTTP_REQUEST` or `JSONP_REQUEST`.
     * @param {any} transformedError The transformed error (by `transformError`).
     * @param {HttpResponseError|JSONPResponseError} error The original response error.
     * @returns {boolean} Returns `truthy` to call the error callback.
     */
    shouldCallErrorCallback: null,
 
    /**
     * The function to check whether to call the success callback on request success. If it is
     * `null` or not a function, the success callback will be called. If it is a function and
     * the function returns a `falsy` value the success callback will not be called. Otherwise
     * the success callback will be called.
     *
     * @param {string} requestType The request type, can be `HTTP_REQUEST` or `JSONP_REQUEST`.
     * @param {any} transformedResponse The transformed response (by `transformResponse`).
     * @param {HttpResponse|JSONPResponse} response The original response.
     * @returns {boolean} Returns `truthy` to call the success callback.
     */
    shouldCallSuccessCallback: null
}