Skip to content

Latest commit

 

History

History
121 lines (87 loc) · 3.67 KB

README.md

File metadata and controls

121 lines (87 loc) · 3.67 KB
Raw

xhr-request

stable

An extremely tiny HTTP/HTTPS request client for Node and the browser. Uses xhr in the browser and simple-get in Node.

Supported response types: JSON, ArrayBuffer, and text (default).

For streaming requests, you can just use simple-get directly. It works in Node/browser and supports true streaming in new versions of Chrome/FireFox.

Install

npm install xhr-request --save

Example

A simple example, loading JSON:

var request = require('xhr-request')

request('http://foo.com/some/api', {
  json: true
}, function (err, data) {
  if (err) throw err
  
  // the JSON result
  console.log(data.foo.bar)
})

Another example, sending a JSON body with a query parameter. Receives binary data as the response.

var request = require('xhr-request')

request('http://foo.com/some/api', {
  method: 'PUT',
  json: true,
  body: { foo: 'bar' },
  responseType: 'arraybuffer',
  query: {
    sort: 'name'
  }
}, function (err, data) {
  if (err) throw err
  console.log('got ArrayBuffer result: ', data)
})

Motivation

There are a lot of HTTP clients, but most of them are Node-centric and lead to large browser bundles with builtins like url, buffer, http, zlib, streams, etc.

With browserify, this bundles to 7kb minified. Compare to 742kb for request, 153kb for got, 74kb for simple-get, and 25kb for nets.

Usage

req = xhrRequest(url, [opt], [callback])

Sends a request to the given url with optional opt settings, triggering callback on complete.

Options:

  • query (String|Object)
    • the query parameters to use for the URL
  • headers (Object)
    • the headers for the request
  • json (Boolean)
    • if true, responseType defaults to 'json' and body will be sent as JSON
  • responseType (String)
    • can be 'text', 'arraybuffer' or 'json'
    • defaults to 'text' unless json is true
  • body (String|JSON)
    • an optional body to send with request
    • sent as text unless json is true
  • method (String)
    • an optional method to use, defaults to 'GET'
  • timeout (Number)
    • milliseconds to use as a timeout, defaults to 0 (no timeout)

The callback is called with the arguments (error, data, response)

  • error on success will be null/undefined
  • data the result of the request, either a JSON object, string, or ArrayBuffer
  • response the request response, see below

The response object has the following form:

{
  statusCode: Number,
  method: String,
  headers: {},
  url: String,
  rawRequest: {}
}

The rawRequest is the XMLHttpRequest in the browser, and the http response in Node.

Since opt is optional, you can specify callback as the second argument.

req.abort()

The returned req (the ClientRequest or XMLHttpRequest) has an abort() method which can be used to cancel the request and send an Error to the callback.

See Also

License

MIT, see LICENSE.md for details.