browser-http

Simple (but advanced) HTTP for browser

npm install browser-http
1 downloads in the last week
66 downloads in the last month

NPM version Dependency Status Build Status

Donate

http-browser

Simple (but advanced) library for working with http in browser (like for example jQuery.ajax).

http-browser uses q promise pattern and is instance of EventEmitter.

You can use it for example with simq as you are used to from node environment or use standalone build with expanded package into window:

Installation

$ npm install browser-http

or for standalone version just choose desired version and include it.

Usage

var http = require('browser-http');

// or standalone version:
var http = window.http;        // you can of course just call http directly without window at the beginning

http.request('http://www.google.com', {type: 'GET'}).then(function(response) {
    console.log(response.text);
}, function(e) {
    throw e;        // some error occurred
});

In then function, you will get response object with data from server.

Shorthands

var http = require('browser-http');

http.get('http://www.google.com');
http.post('http://www.google.com');
http.put('http://www.google.com');
http.delete('http://www.google.com');

Options

In every http function, you can set other options. Now it is just type and data.

  • type: GET, POST, PUT or DELETE
  • data: literal object of data which needs to be send to server

Response object

Basically it is just wrapper for some data from XMLHttpRequest.

  • state
  • status
  • statusText
  • rawData: same like responseText
  • data: same like responseText or literal object (json)
  • xml: same like responseXML

Load JSON

If content-type in response header is application/json then your data will be automatically transformed into js object.

If you can not set this header on your server, than you can use *Json methods.

http.getJson('http://www.google.com/some.json').then(function(response) {
    console.log(response.data);        // output will be object
});

http.postJson('http://www.google.com/some.json');

Requests queue

By default all your requests are called from queue one by one, so there is always just one request running (or zero). Inspiration from this article http://blog.alexmaccaw.com/queuing-ajax-requests.

You can of course disable this behavior:

http.useQueue = false;

JSONP

It is very easy to work with jsonp requests.

http.jsonp('http://some.url.com').then(function(response) {
    console.log(response.data);
});

Json hijacking

First, please read this discussion on stackoverflow.

Now if you want to use same technique just like Google or eg. Facebook do, you only need to set your own prefix in requests.

http.get('http://some.url.com', {
    jsonPrefix: 'while(1);'
}).then(function(response) {
    console.log(response.data);
});

String while(1); will be removed from the beginning of received data before parsing into json object.

Events

You can listen for all http events with your own functions.

http.on('send', function(response, request) {
    console.log('In any moment, new http request will be send to server');
});

http.on('complete', function(response, request) {
    console.log('I just finished some request, but there may be some errors');
});

http.on('success', function(response, request) {
    console.log('I have got response from server without any error :-)');
});

http.on('error', function(err, response, request) {
    console.log('Sorry, there was some error with this response');
});

Extensions

Sometimes it will be better to register whole group of events and this group is called extension.

http.addExtension('nameOfMyExtension', {
    send: function(response, request) {},
    complete: function(response, request) {},
    success: function(response, request) {},
    error: function(err, response, request) {},
});

You can also remove other extensions.

http.removeExtension('nameOfMyExtension');

Build in extensions

browser-http already comes with few extensions. Originally they were created for projects build on Nette framework, but can be used on any other project.

Loading cursor

new (require('browser-http/Extensions/Loading'));

standalone version:

new http.Extensions.Loading;

Every time new request is send, your cursor is changed into progress cursor. After receiving response from server, cursor is changed into auto.

Redirect

new (require('browser-http/Extensions/Redirect'));

standalone version:

new http.Extensions.Redirect;

If your server sends json data with redirect variable, then you will be redirected to address in this variable.

Snippets

var Snippets = require('browser-http/Extensions/Snippets');
new Snippets(window.jQuery);

standalone version:

new http.Extensions.Snippets(window.jQuery);

If in response data is snippets object with html id and content pairs, then browser-http will iterate throw this object, find element in page with given id and change content of this element into the one from given data.

This extension depends on jquery.

var Links = require('browser-http/Extensions/Links');
new Links(window.jQuery);

standalone version:

new http.Extensions.Links(window.jQuery);

This is not true extension for browser-http. It listen for all click events on a links with class ajax but not with class not-ajax and after this click, it creates ajax request.

Depends on jquery.

Ajax forms

This is the same like the previous one, but apply for all forms with ajax class. This extension can not handle forms with file uploads. Depends on jquery.

var Forms = require('browser-http/Extensions/Forms');
new Forms(window.jQuery);

standalone version:

new http.Extensions.Forms(window.jQuery);

Tests

$ npm test

Own tests

var http = require('browser-http/Mocks/Http');

// standalone version:
var http = http.Mocks.Http;

afterEach(function() {
    http.restore();
});

it('should load some data', function(done) {
    http.receive('some data', {'content-type': 'text/plain'}, 200);

    http.get('localhost').then(function(response) {
        expect(response.data).to.be.equal('some data');
        done();
    });
});

// text/plain in headers list is default content-type, so you don't have to set it. Also status 200 is default.

it('should load some data and check received data', function(done) {
    http.receive('some data', {'content-type': 'application/json'});

    http.once('send', function(response, request) {
        expect(request.xhr.url).to.be.equal('localhost?greeting=hello')            // now we can test eg. url with parsed data
    });

    http.get('localhost', {data: {greeting: 'hello'}}).then(function(response) {
        expect(response.data).to.be.eql({greeting: 'hello'});
        done()
    });
});

Changelog

  • 2.2.0

    • Added support for environments without require (like with simq)
    • Tests uses minified standalone version of browser-http
  • 2.1.1

    • Removed forgotten tests building
  • 2.1.0

  • 2.0.0

    • jQuery must be passed in constructor into extensions which depends on it
    • Updated dependencies
    • Test frameworks are in devDependencies (not globally installed)
    • Large refactoring (better for testing)
    • Tests does not need real server (using mock from philikon/MockHttpRequest)
    • Many optimizations
    • Added some badges + travis
  • 1.8.0

    • Requests are added into queue
    • Added support for jsonp
  • 1.7.1

    • Added some tests
    • Bug with responses without content-type header
  • 1.7.0

    • Refactoring
    • buildQuery and urlencode moved to browser-http/Helpers
    • Instance of EventEmitter
  • 1.6.4

    • Optimizations + bug with sending data
  • 1.6.3

    • Bug with buildQuery - replaced with the real one from jQuery
  • 1.6.2

    • Just removed some useless code
  • 1.6.1

    • Forgot to add Extensions/Links shortcut
  • 1.6.0

    • buildQuery should got the same output like jQuery.param
    • Added some extensions
  • 1.5.2

    • Bug with sending data via POST method
  • 1.5.1

    • Bug with X-Requested-With header
  • 1.5.0

    • Added method isHistoryApiSupported
  • 1.4.0

    • Sending X-Requested-With header
  • 1.3.1 - 1.3.5

    • Bugs
  • 1.3.0

    • Added urlencode and buildQuery methods
    • Prepared changelog
    • Added some tests
    • Some bugs and optimizations
    • Transforming response data into json if mime type is application/json
npm loves you