Skip to content

Latest commit

 

History

History
191 lines (147 loc) · 9.16 KB

README.md

File metadata and controls

191 lines (147 loc) · 9.16 KB
Raw

rext

gzip size license

A lightweight (< 5kb gzipped) and Promise-supported HTTP request library, for all browsers (i.e. even cross-domain requests in IE 6 are possible).

IE / Edge IE / Edge Chrome Chrome Firefox Firefox Safari Safari
6+ ✔ All ✔ All ✔ All ✔

Quick Import

$ npm install --save rexter
var rext = require('rexter');

IE 9- Support

If IE9- browsers are required to send cross-domain requests with user credentials, define the invoker-hostname whitelist in dist/iframe-agent.html and put it at the root path of the target origin.

For example:

Define the invoker-hostname whitelist in iframe-agent.html:

Replace

[/* Define a whitelist of host names here, e.g. '.invoker.com'. */]

with

['.my-domain.com', '.my-domain1.com']

Additianally, before rext is imported, the JSON polyfill (e.g. JSON-js) shall be executed.

⚠️ rext does not include full polyfills in itself.

API

As simple as rext(options).

Besides, the format of jQuery ajax's option object is also allowed:

{
    type: 'post',
    url: '/path/to/api',
    data: {},
    contentType: 'application/json',
    dataType: 'json',
    xhrFields: {
        withCredentials: true
    },
    success: function () { /**/ },
    error: function () { /**/ },
    complete: function () { /**/ }
}

XMLHttpRequest

The success, error, always callbacks are allowed both a chain call and defined in the option object.

rext({
    url: '/path/to/resource',
    data: { /**/ },
    promise: false
}).success((data, response) => {
    /**/
}).error((data, response) => {
    /**/
}).always((data, response) => {
    /**/
});

JSONP

The callback function is allowed either as the second parameter behind the option object or defined in the option object.

rext({
    jsonp: true,
    url: '/path/to/resource',
    data: { /**/ }
}, data => {
    /**/
});

Promise Object Returned

A Promise object is returned by default. Set property promise value false if you do not want to get a Promise object or you prefer to use success and error methods actually.

rext({
    url: '/path/to/resource',
    data: { /**/ }
}).then(data => {
    /**/
}).catch(err => {
    /**/
});

👏 shenfe/promises-aplus is used as a polyfill when the browser does not support Promise.

Options

Instructions of the option object:

Property Type Value
type {Undefined|String} 'get' (default), 'post'.
url {String} The resource url string.
data {Undefined|Object} The data to send. Object recommended.
withCredentials {Undefined|Boolean} undefined (false, as default), true. The withCredentials property of the request. Whether to send user credentials with the request to another origin or not. An xhrFields object with withCredentials property of value true is accepted as well.
agent {Undefined|Boolean} undefined (false, as default), true. Whether to fall back to the iframe agent directly when the request is cross-domain and the browser is IE 9-.
agentPageUrl {Undefined|String} undefined (`${targetOrigin}/iframe-agent.html`, as default), a url string. Specify the url of the iframe agent page if it's not in the root path of the target origin.
responseType (or dataType) {Undefined|String} 'text' (default), 'json', .etc. Similar to the dataType option in jQuery ajax. A simple trial of JSON parsing would be conducted upon the response data besides the MIME type. See below for more.
headers {Undefined|Object} The request headers object. Usually used to define the Content-Type property (similar to the contentType option in jQuery ajax), of which 'application/x-www-form-urlencoded' is the default value. See below for more.
contentType {Undefined|String} The same as headers['Content-Type'].
jsonp {Undefined|Boolean} undefined (false, as default), true. The same as setting responseType (or dataType) jsonp.
promise {Undefined|Boolean|Function} undefined, false, true, or a Promise object constructor. Whether to return a Promise object. Set it false if not for a Promise object.
simple {Undefined|Boolean} undefined (false, as default), true. Whether not to force an X-Requested-With header in an XHR.

Case Matrix

All the cases of browser requests.

Cross-Domain With-Credentials Web Browser Approach Restriction Security
no - IE 6- ActiveXObject Almost the same API as the XMLHttpRequest Object. -
no - IE 7-9 XMLHttpRequest The XMLHttpRequest Object. -
yes no IE 8-9 XDomainRequest XDomainRequest - Restrictions, Limitations and Workarounds -
no - IE 10-11, non-IE XMLHttpRequest (Level 2) XMLHttpRequest Level 2. IE 10-11 do not support value json as XHR's responseType, but it doesn't matter. -
yes - IE 10-11, non-IE XMLHttpRequest (Level 2) Server responses should include the Access-Control-Allow-Origin HTTP response header with value *, or the exact origin of the calling page. -
yes yes IE 10-11, non-IE XMLHttpRequest (Level 2) Server responses should include the Access-Control-Allow-Origin HTTP response header with the exact origin of the calling page, and the Access-Control-Allow-Credentials HTTP response header with value true. -
- - - JSONP - Security concerns
- - - iframe agent Be put in a specific place of the target origin. A whitelist of visitor origins is required.

Take a Look at headers['Content-Type']

The MIME type of data to send, like the contentType in jQuery ajax.

Value Effect
application/x-www-form-urlencoded The default, recommended. Almost the same as the url query string.
multipart/form-data HTML 4 specification. This allows entire files to be included in the data. Use this when the form includes any <input type="file"> element. In this case, Content-Type would be ignored because the browser set this header with a boundary generated by itself.
text/plain HTML 5 specification. Not recommended. Do not use it unless for debugging.
application/json Personally not recommended for common POST requests. Make sure you really need to post complex data with user credentials. Additionally, for CORS requests, setting the content type to anything other than application/x-www-form-urlencoded, multipart/form-data, or text/plain will trigger the browser to send a preflight OPTIONS request to the server.

Take a Look at responseType

The alias of the expected MIME type of data to receive, similar to the dataType in jQuery ajax. This option should affect the request header Accept and how to treat the response data, relating the response header Content-Type. However, a simple trial of JSON parsing would be conducted then regardless of the type of response data.

According to the specification of responseType, the value can be:

Value Description
text Default.
json -
blob If to receive files.
arraybuffer If to receive files.
document Seldom.

License

MIT

Copyright © 2017-present, shenfe