A small xhr wrapper. Designed for use with browserify and node.js (by akralj)
Browser support: IE8+ and everything else.
var xhr = require("xhr")
xhr({
body: someJSONString,
uri: "/foo",
headers: {
"Content-Type": "application/json"
}
}, function (err, resp, body) {
// check resp.statusCode
})
type XhrOptions = String | {
useXDR: Boolean?,
sync: Boolean?,
uri: String,
url: String,
method: String?,
timeout: Number?,
headers: Object?,
body: String?,
json: Object?,
username: String?,
password: String?,
withCredentials: Boolean?,
responseType: String?,
beforeSend: Function?
}
xhr := (XhrOptions, Callback<Response>) => Request
the returned object is either an XMLHttpRequest
instance
or an XDomainRequest
instance (if on IE8/IE9 &&
options.useXDR
is set to true
)
Your callback will be called once with the arguments
( Error
, response
, body
) where the response is an object:
{
body: Object||String,
statusCode: Number,
method: String,
headers: {},
url: String,
rawRequest: xhr
}
body
: HTTP response body -xhr.response
,xhr.responseText
orxhr.responseXML
depending on the request type.rawRequest
: OriginalXMLHttpRequest
instance orXDomainRequest
instance (if on IE8/IE9 &&options.useXDR
is set totrue
)headers
: A collection of headers where keys are header names converted to lowercase
Your callback will be called with an Error
if there is an error in the browser that prevents sending the request.
A HTTP 500 response is not going to cause an error to be returned.
-
var req = xhr(url, callback)
- a simple string instead of the options. In this case, a GET request will be made to that url. -
var req = xhr(url, options, callback)
- the above may also be called with the standard set of options.
var req = xhr.{post, put, patch, del, head, get}(url, callback)
var req = xhr.{post, put, patch, del, head, get}(options, callback)
var req = xhr.{post, put, patch, del, head, get}(url, options, callback)
The xhr
module has convience functions attached that will make requests with the given method.
Each function is named after its method, with the exception of DELETE
which is called xhr.del
for compatibility.
The method shorthands may be combined with the url-first form of xhr
for succinct and descriptive requests. For example,
xhr.post('/post-to-me', function(err, resp) {
console.log(resp.body)
})
or
xhr.del('/delete-me', { headers: { my: 'auth' } }, function (err, resp) {
console.log(resp.statusCode);
})
Specify the method the XMLHttpRequest
should be opened
with. Passed to xhr.open
. Defaults to "GET"
Specify whether this is a cross origin (CORS) request for IE<10.
Switches IE to use XDomainRequest
instead of XMLHttpRequest
.
Ignored in other browsers.
Note that headers cannot be set on an XDomainRequest instance.
Specify whether this is a synchrounous request. Note that when this is true the callback will be called synchronously. In most cases this option should not be used. Only use if you know what you are doing!
Pass in body to be send across the XMLHttpRequest
.
Generally should be a string. But anything that's valid as
a parameter to xhr.send
should work
The uri to send a request to. Passed to xhr.open
. options.url
and options.uri
are aliases for each other.
An object of headers that should be set on the request. The
key, value pair is passed to xhr.setRequestHeader
Number of miliseconds to wait for response. Defaults to 0 (no timeout). Ignored when options.sync
is true.
A valid JSON serializable value to be send to the server. If this
is set then we serialize the value and use that as the body.
We also set the Content-Type to "application/json"
.
Additionally the response body is parsed as JSON
Specify whether user credentials are to be included in a cross-origin
request. Sets xhr.withCredentials
. Defaults to false.
A wildcard *
cannot be used in the Access-Control-Allow-Origin
header when withCredentials
is true.
The header needs to specify your origin explicitly or browser will abort the request.
Determines the data type of the response
. Sets xhr.responseType
. For example, a responseType
of document
will return a parsed Document
object as the response.body
for an XML resource.
A function being called right before the send
method of the XMLHttpRequest
or XDomainRequest
instance is called. The XMLHttpRequest
or XDomainRequest
instance is passed as an argument.
Pass an XMLHttpRequest
object (or something that acts like one) to use instead of constructing a new one using the XMLHttpRequest
or XDomainRequest
constructors. Useful for testing.
You can override the constructor used to create new requests for testing. When you're making a new request:
xhr({ xhr: new MockXMLHttpRequest() })
or you can override the constructors used to create requests at the module level:
xhr.XMLHttpRequest = MockXMLHttpRequest
xhr.XDomainRequest = MockXDomainRequest