xhr

What is xhr?

The xhr npm package is a simple and lightweight library for making XMLHttpRequests in a browser environment. It provides a straightforward API for performing HTTP requests, handling responses, and managing errors.

What are xhr's main functionalities?

Basic GET Request

This feature allows you to perform a basic GET request to a specified URL. The callback function handles the response or any errors that occur.

const xhr = require('xhr');
xhr({ url: 'https://api.example.com/data' }, function (err, resp, body) {
  if (err) {
    console.error(err);
  } else {
    console.log(body);
  }
});

POST Request with Data

This feature allows you to perform a POST request with a JSON payload. The request includes headers to specify the content type, and the callback function handles the response or any errors.

const xhr = require('xhr');
xhr({
  url: 'https://api.example.com/data',
  method: 'POST',
  body: JSON.stringify({ key: 'value' }),
  headers: { 'Content-Type': 'application/json' }
}, function (err, resp, body) {
  if (err) {
    console.error(err);
  } else {
    console.log(body);
  }
});

Handling Response Status Codes

This feature demonstrates how to handle different HTTP response status codes. The callback function checks the status code and logs the appropriate message.

const xhr = require('xhr');
xhr({ url: 'https://api.example.com/data' }, function (err, resp, body) {
  if (err) {
    console.error(err);
  } else if (resp.statusCode === 200) {
    console.log('Success:', body);
  } else {
    console.log('Error:', resp.statusCode);
  }
});

Other packages similar to xhr

axios

Axios is a promise-based HTTP client for the browser and Node.js. It provides a more powerful and flexible API compared to xhr, including support for interceptors, automatic JSON transformation, and request cancellation.

fetch

Fetch is a built-in web API for making HTTP requests in the browser. It is a modern alternative to XMLHttpRequest and provides a more powerful and flexible API. Unlike xhr, fetch is built into modern browsers and does not require an external library.

superagent

Superagent is a small, progressive client-side HTTP request library. It provides a more feature-rich API compared to xhr, including support for promises, request retries, and plugins.

README

xhr

A small XMLHttpRequest wrapper. Designed for use with browserify, webpack etc.

API is a subset of request so that the same code can be used in the browser and Node.js.

Browser support: IE8+ and everything else.

Example

var xhr = require("xhr")

xhr({
    body: someJSONString,
    uri: "/foo",
    headers: {
        "Content-Type": "application/json"
    }
}, function (err, resp, body) {
    // check resp.statusCode
})

var req = xhr(options, callback)

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 - XMLHttpRequest.response, XMLHttpRequest.responseText or XMLHttpRequest.responseXML depending on the request type.
• rawRequest: Original XMLHttpRequest instance or XDomainRequest instance (if on IE8/IE9 && options.useXDR is set to true)
• 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.

Other signatures

• 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.

Convience methods

• 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);
})

Options

options.method

Specify the method the XMLHttpRequest should be opened with. Passed to XMLHttpRequest.open. Defaults to "GET"

options.useXDR

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.

options.sync

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!

options.body

Pass in body to be send across the XMLHttpRequest. Generally should be a string. But anything that's valid as a parameter to XMLHttpRequest.send should work (Buffer for file, etc.).

options.uri or options.url

The uri to send a request to. Passed to XMLHttpRequest.open. options.url and options.uri are aliases for each other.

options.headers

An object of headers that should be set on the request. The key, value pair is passed to XMLHttpRequest.setRequestHeader

options.timeout

Number of miliseconds to wait for response. Defaults to 0 (no timeout). Ignored when options.sync is true.

options.json

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

options.withCredentials

Specify whether user credentials are to be included in a cross-origin request. Sets XMLHttpRequest.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.

options.responseType

Determines the data type of the response. Sets XMLHttpRequest.responseType. For example, a responseType of document will return a parsed Document object as the response.body for an XML resource.

options.beforeSend

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.

options.xhr

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.

FAQ

• Why is my server's JSON response not parsed? I returned the right content-type.
  • See options.json - you can set it to true on a GET request to tell xhr to parse the response body.
  • 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)
• How do I send an object or array as POST body?
  • options.body should be a string. You need to serialize your object before passing to xhr for sending.
  • To serialize to JSON you can use options.json instead of options.body for convenience - then xhr will do the serialization and set content-type accordingly.
• Where's stream API? .pipe() etc.
  • Not implemented. You can't reasonably have that in the browser.

Mocking Requests

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

MIT Licenced