www.aleph1.co.uk Git - yaffs-website/blob - node_modules/xhr/README.md

   1 # xhr
   2
   3 A small XMLHttpRequest wrapper. Designed for use with [browserify](http://browserify.org/), [webpack](https://webpack.github.io/) etc.
   4
   5 API is a subset of [request](https://github.com/request/request) so that the same code can be used in the browser and Node.js.
   6
   7 Browser support: IE8+ and everything else.
   8
   9 ## Example
  10
  11 ```js
  12 var xhr = require("xhr")
  13
  14 xhr({
  15     body: someJSONString,
  16     uri: "/foo",
  17     headers: {
  18         "Content-Type": "application/json"
  19     }
  20 }, function (err, resp, body) {
  21     // check resp.statusCode
  22 })
  23 ```
  24
  25 ## `var req = xhr(options, callback)`
  26
  27 ```js
  28 type XhrOptions = String | {
  29     useXDR: Boolean?,
  30     sync: Boolean?,
  31     uri: String,
  32     url: String,
  33     method: String?,
  34     timeout: Number?,
  35     headers: Object?,
  36     body: String?,
  37     json: Object?,
  38     username: String?,
  39     password: String?,
  40     withCredentials: Boolean?,
  41     responseType: String?,
  42     beforeSend: Function?
  43 }
  44 xhr := (XhrOptions, Callback<Response>) => Request
  45 ```
  46 the returned object is either an [`XMLHttpRequest`][3] instance
  47     or an [`XDomainRequest`][4] instance (if on IE8/IE9 &&
  48     `options.useXDR` is set to `true`)
  49
  50 Your callback will be called once with the arguments
  51     ( [`Error`][5], `response` , `body` ) where the response is an object:
  52 ```js
  53 {
  54     body: Object||String,
  55     statusCode: Number,
  56     method: String,
  57     headers: {},
  58     url: String,
  59     rawRequest: xhr
  60 }
  61 ```
  62  - `body`: HTTP response body - [`XMLHttpRequest.response`][6], [`XMLHttpRequest.responseText`][7] or
  63     [`XMLHttpRequest.responseXML`][8] depending on the request type.
  64  - `rawRequest`: Original  [`XMLHttpRequest`][3] instance
  65     or [`XDomainRequest`][4] instance (if on IE8/IE9 &&
  66     `options.useXDR` is set to `true`)
  67  - `headers`: A collection of headers where keys are header names converted to lowercase
  68
  69
  70 Your callback will be called with an [`Error`][5] if there is an error in the browser that prevents sending the request.
  71 A HTTP 500 response is not going to cause an error to be returned.
  72
  73 ## Other signatures
  74
  75 * `var req = xhr(url, callback)` -
  76 a simple string instead of the options. In this case, a GET request will be made to that url.
  77
  78 * `var req = xhr(url, options, callback)` -
  79 the above may also be called with the standard set of options.
  80
  81 ### Convience methods
  82 * `var req = xhr.{post, put, patch, del, head, get}(url, callback)`
  83 * `var req = xhr.{post, put, patch, del, head, get}(options, callback)`
  84 * `var req = xhr.{post, put, patch, del, head, get}(url, options, callback)`
  85
  86 The `xhr` module has convience functions attached that will make requests with the given method.
  87 Each function is named after its method, with the exception of `DELETE` which is called `xhr.del` for compatibility.
  88
  89 The method shorthands may be combined with the url-first form of `xhr` for succinct and descriptive requests. For example,
  90
  91 ```js
  92 xhr.post('/post-to-me', function(err, resp) {
  93   console.log(resp.body)
  94 })
  95 ```
  96
  97 or
  98
  99 ```js
 100 xhr.del('/delete-me', { headers: { my: 'auth' } }, function (err, resp) {
 101   console.log(resp.statusCode);
 102 })
 103 ```
 104
 105 ## Options
 106
 107 ### `options.method`
 108
 109 Specify the method the [`XMLHttpRequest`][3] should be opened
 110     with. Passed to [`XMLHttpRequest.open`][2]. Defaults to "GET"
 111
 112 ### `options.useXDR`
 113
 114 Specify whether this is a cross origin (CORS) request for IE<10.
 115     Switches IE to use [`XDomainRequest`][4] instead of `XMLHttpRequest`.
 116     Ignored in other browsers.
 117
 118 Note that headers cannot be set on an XDomainRequest instance.
 119
 120 ### `options.sync`
 121
 122 Specify whether this is a synchrounous request. Note that when
 123     this is true the callback will be called synchronously. In
 124     most cases this option should not be used. Only use if you
 125     know what you are doing!
 126
 127 ### `options.body`
 128
 129 Pass in body to be send across the [`XMLHttpRequest`][3].
 130     Generally should be a string. But anything that's valid as
 131     a parameter to [`XMLHttpRequest.send`][1] should work  (Buffer for file, etc.).
 132
 133 ### `options.uri` or `options.url`
 134
 135 The uri to send a request to. Passed to [`XMLHttpRequest.open`][2]. `options.url` and `options.uri` are aliases for each other.
 136
 137 ### `options.headers`
 138
 139 An object of headers that should be set on the request. The
 140     key, value pair is passed to [`XMLHttpRequest.setRequestHeader`][9]
 141
 142 ### `options.timeout`
 143
 144 Number of miliseconds to wait for response. Defaults to 0 (no timeout). Ignored when `options.sync` is true.
 145
 146 ### `options.json`
 147
 148 A valid JSON serializable value to be send to the server. If this
 149     is set then we serialize the value and use that as the body.
 150     We also set the Content-Type to `"application/json"`.
 151
 152 Additionally the response body is parsed as JSON
 153
 154 ### `options.withCredentials`
 155
 156 Specify whether user credentials are to be included in a cross-origin
 157     request. Sets [`XMLHttpRequest.withCredentials`][10]. Defaults to false.
 158
 159 A wildcard `*` cannot be used in the `Access-Control-Allow-Origin` header when `withCredentials` is true.
 160     The header needs to specify your origin explicitly or browser will abort the request.
 161
 162 ### `options.responseType`
 163
 164 Determines the data type of the `response`. Sets [`XMLHttpRequest.responseType`][11]. For example, a `responseType` of `document` will return a parsed `Document` object as the `response.body` for an XML resource.
 165
 166 ### `options.beforeSend`
 167
 168 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.
 169
 170 ### `options.xhr`
 171
 172 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.
 173
 174 ## FAQ
 175
 176 - Why is my server's JSON response not parsed? I returned the right content-type.
 177   - See `options.json` - you can set it to `true` on a GET request to tell `xhr` to parse the response body.
 178   - Without `options.json` body is returned as-is (a string or when `responseType` is set and the browser supports it - a result of parsing JSON or XML)
 179 - How do I send an object or array as POST body?
 180   - `options.body` should be a string. You need to serialize your object before passing to `xhr` for sending.
 181   - To serialize to JSON you can use
 182    `options.json` instead of `options.body` for convenience - then `xhr` will do the serialization and set content-type accordingly.
 183 - Where's stream API? `.pipe()` etc.
 184   - Not implemented. You can't reasonably have that in the browser.
 185
 186
 187 ## Mocking Requests
 188 You can override the constructor used to create new requests for testing. When you're making a new request:
 189
 190 ```js
 191 xhr({ xhr: new MockXMLHttpRequest() })
 192 ```
 193
 194 or you can override the constructors used to create requests at the module level:
 195
 196 ```js
 197 xhr.XMLHttpRequest = MockXMLHttpRequest
 198 xhr.XDomainRequest = MockXDomainRequest
 199 ```
 200
 201 ## MIT Licenced
 202
 203   [1]: http://xhr.spec.whatwg.org/#the-send()-method
 204   [2]: http://xhr.spec.whatwg.org/#the-open()-method
 205   [3]: http://xhr.spec.whatwg.org/#interface-xmlhttprequest
 206   [4]: http://msdn.microsoft.com/en-us/library/ie/cc288060(v=vs.85).aspx
 207   [5]: http://es5.github.com/#x15.11
 208   [6]: http://xhr.spec.whatwg.org/#the-response-attribute
 209   [7]: http://xhr.spec.whatwg.org/#the-responsetext-attribute
 210   [8]: http://xhr.spec.whatwg.org/#the-responsexml-attribute
 211   [9]: http://xhr.spec.whatwg.org/#the-setrequestheader()-method
 212   [10]: http://xhr.spec.whatwg.org/#the-withcredentials-attribute
 213   [11]: https://xhr.spec.whatwg.org/#the-responsetype-attribute