httpplease v0.16.4

HTTP, Please

There are a lot of JS libraries for making HTTP requests in JavaScript. Why use this one? Because it's awesome, that's why. And this is why it's awesome:

• Designed for "isomorphic" JavaScript (supporting both client and server with the same codebase)
• …but with a browser-driven focus that keeps in mind the limitations of that environment (filesize, old IE)
• Extensible via a simple but powerful plugin system (which it dogfoods)
  • Supports cross-domain requests in IE9 transparently with the oldiexdomain plugin
  • Supports promises (thenable/catchable request objects) with the promises plugin

browserify and webpack users can simply npm install httpplease.

Bower users can bower install httpplease.

<script> tag fans can grab the standalone build from the "browser-builds" directory.

Minified and gzipped, the standalone browser build is <2K.

API

Making a request

httpplease.get('http://example.com', function (err, res) {
    // Do something with the result.
});

Alternatively, you can pass a request options object as the first parameter:

httpplease.get({url: 'http://example.com'}, function (err, res) {
    // Do something with the result.
});

If you'd rather include the method in the object, that's okay too:

httpplease({method: 'GET', url: 'http://example.com'}, function (err, res) {
    // Do something with the result.
});

You can create a new http function with default request object values:

var http = httpplease.defaults({method: 'GET', errorOn404: false});
http('http://example.com', function (err, res) {
    // This request was made using the defaults specified above.
});

The request object

When you call one of the http functions (http, http.get, etc.), the result is a Request object. This object can also be processed by plugins. It has the same properties as the request options object you pass to the http function (though properties that you didn't pass will be filled by defaults). Those properties are:

The error object

In the event of an error, an error object will be passed as the first argument to your callback. If the error is an HTTP error, it will have all of the properties that a response object has (listed below), but will be a JS Error object (which can be useful if relying on instanceof checks). It also has one additional property—message—which contains a description of the error.

The response object

The response object passed to your callback in the event of a successful request has the following properties:

Plugins

httpplease supports plugins for changing how requests are made. Some plugins are built in:

Plugins are enabled with the use method:

var json = require('httpplease/plugins/json');
httpplease = httpplease.use(json);

Or, if you're using the standalone build:

<script src="httpplease.js" type="text/javascript"></script>
<script src="httppleaseplugins.js" type="text/javascript"></script>

var json = httppleaseplugins.json;
httpplease = httpplease.use(json);

Notice that use returns a new httpplease instance. This is so that you can create multiple instances, each with their own plugins:

var http = httpplease.use(json);

http
  .use(oldiexdomain)
  .get('http://example.com', function (err, res) { ... }); // Uses "json" plugin and "oldiexdomain".
http.get('http://example.com', function (err, res) { ... }); // Only uses "json" plugin.
httpplease.get('http://example.com', function (err, res) { ... }); // No extra plugins are used.

You can use as many plugins as you want—either by passing multiple plugins to use or chaining calls:

var http = httpplease
  .use(json, oldiexdomain, myPlugin)
  .use(anotherPlugin);

In order to keep your builds as small as possible, most plugins aren't enabled by default. (See the table above.) However, some small plugins are. If you want to disable all plugins, use the bare() method:

var http = httpplease.bare();

Like use(), this method also returns a new httpplease instance so you can continue to use the old object with the original plugins intact.

Custom Plugins

In addition to the bundled plugins, you can create your own. Plugins are simply objects that implement one or more of the following methods:

Similar Projects

• xhr (browser only)
• request (node only)
• httpify (wraps xhr and request)

Thanks

This project is mostly just a small wrapper around XMLHttpRequest and an (I hope) sensible structure for extending functionality. The reason it works on the server is because of driverdan's awesome node-XMLHttpRequest library—it's the secret sauce that makes the browser-focused design of httpplease possible!

Changelog

I try to write good commit messages so the commit log should be very readable, but here's a summary of some notable changes.

• v0.16.0
  • Use onload on onerror where available since onreadystatechange can't differentiate between 0 status code errors and successes (matthewwithanm/react-inlinesvg#10)
• v0.15.0
  • Rename "jsonparser" to "jsonresponse"
  • Set Accept header in "jsonresponse" instead of "jsonrequest"
  • Add "json" plugin that combines "jsonrequest" and "jsonresponse"
• v0.14.0
  • Move plugins from httpplease/lib/plugins to httpplease/plugins
• v0.13.1
  • Don't add Content-Type header if request has no body in jsonrequest plugin. (This avoids an unneeded preflight request.)
• v0.13.0
  • Add support for timeouts
• v0.12.0
  • Add abort to request object
• v0.11.0
  • Add setprotocol plugin
• v0.9.0
  • Ignore request headers when using oldiexdomain
  • Change when plugin methods are called
• v0.8.1
  • Add Accept header if not present for jsonrequest
• v0.8.0
  • Add onload and onerror
• v0.7.0
  • Goodbye CoffeeScript
• v0.6.0
  • Add jsonrequest plugin
  • Add header() to Request and Response objects
  • More tests
• v0.5.3
  • Improve content-type matching
• v0.5.1
  • Fix bug with non-404s being suppressed by errorOn404
• v0.5.0
  • Return request object from http methods
• v0.4.0
  • Added errorOn404 option
  • Make defaults a method
  • Make plugins a method
• v0.3.0
  • Response-like errors
  • More tests
• v0.2.0
  • Initial release as "httpplease"