iso-http v0.0.5
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="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.