iso-http

An isomorphic HTTP request library.

Features

Isomorphic – runs on Node and in-browser with the same interface!
100% test coverage with 4.0 Code Climate GPA
Zero dependencies
Small footprint – 4KB (minified) / 2KB (gzipped)
FakeHttp module for testing
TypeScript source – definitions are free!

Isomorphic

With iso-http, the only thing different between Node and in-browser is the installation. This means you can use iso-http in your isomorphic applications in the most consistent way. In Node, the built-in http module is utilized. In the browser, the XMLHttpRequest is used without any reference to Node libraries. This keeps the footprint light.

Node installation

$ npm install iso-http

Remember the --save or --save-dev flag, depending on your situation.

Browser installation

$ bower install --save iso-http

Usage

Now, you're ready to require iso-http. The Bower package uses Browserify to expose iso-http so you can require it in the CommonJS way, same as Node.

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

Now, you can make an http request:

var requestOptions = {
  url: 'http://domain.com/foo'
};
var request = http.request(requestOptions, function(response) {
  // handle response
});

Your request options must follow the following interface. Note that ? indicates an optional field and any represents an Object literal or hash.

interface RequestOptions {
    url: string;
    method?: string; // default: 'GET'
    contentType?: string;
    headers?: any;
    withCredentials?: boolean; // default: false
    data?: any;
}

The callback function will be called with a response object that uses the following interface:

interface Response {
    headers: Types.HashTable<string>;
    status: number;
    text: string;
}

Browser Usage

You can require the browser package like so:

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

Full test coverage

Tests are written in Jasmine to cover all library source code. Code coverage reports are generated with Istanbul and sent to Code Climate for further code quality analysis. Browser tests are run with Karma.

All tests are run locally in Node, Chrome, Chrome Canary, Firefox, Safari and Internet Explorer. In Travis-CI, tests are run in Node, Chrome and Firefox.

For Internet Explorer, only versions 9 and above are supported. Please submit any issues on the GitHub Issue Tracker.

FakeHttp module for testing

A FakeHttp module is available for testing. Here's how you require it:

var fakeHttp = require('iso-http/fake');

NOTE: If you're doing browser tests, you'll need to first reference the iso-http--fake.js file in the head section of your test runner's HTML file:

<script src="https://github.com/jednano/iso-http/raw/master/bower_components/iso-http--fake.js"></script>

Unlike the real iso-http module, the fake one returns a request object (an instance of FakeHttp.Agent), upon which you can run two methods. The first method is respondWith and it accepts a fake response object:

it('responds with a fake response', function(done) {
    var options = { /* your options here */ };
    var fakeResponse = {
        status: 123,
        headers: { foo: 'bar' },
        text: 'baz'
    };
    var req = fakeHttp.request(options, function(response) {
        expect(response).toEqual(fakeResponse);
        done();
    });
    req.respondWith(fakeResponse);
});

The second method, rejectWith, accepts an error object:

it('rejects with an error', function(done) {
    var options = { /* your options here */ };
    var noop = function() {};
    var req = fakeHttp.request(options, noop, function(err) {
        expect(err instanceof Error).toBe(true);
        expect(err.message).toEqual('No dice');
        done();
    });
    req.rejectWith(new Error('No dice'));
});

Typescript source

Since all the source code is written in TypeScript, the definition files are always in sync with the code. To gain access to these definitions, install the iso-http node module with npm and import the module like so:

/// <reference path="node_modules/iso-http/iso-http.d.ts" />
import http = require('iso-http');

You'll now gain all the benefits of intelligent code completion aka Intellisense within Microsoft Visual Studio.

jednano / iso-http

readme