x-http-client
Version:
An http client to simplify sending requests (HTTP & JSONP) in the browser.
575 lines (508 loc) • 19 kB
Markdown
# HttpClient.js
[](https://www.npmjs.com/package/x-http-client)
[](https://travis-ci.org/john-yuan/HttpClient.js)
[](https://packagephobia.now.sh/result?p=x-http-client)
[](http://npm-stat.com/charts.html?package=x-http-client)
An http client to simplify sending requests (Http & JSONP) in the browser.
[点击此处查看中文说明文档](./README.zh_CN.md)
## 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.
```bash
npm i x-http-client
```
Otherwise you can import the bundle file with script tag directly.
```html
<script src="/path/to/HttpClient.min.js"></script>
```
Note that the bundle file also can be used as an [AMD module](https://github.com/amdjs/amdjs-api), which means it can be loaded by [require.js](https://requirejs.org/).
## Example
### 1. An exmaple of GET request
```js
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
```js
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
```js
{
/**
* 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
}
```