WARNING: instead of this project, you should use https://github.com/bitinn/node-fetch or https://github.com/github/fetch

httpinvoke

A no-dependencies HTTP client library for browsers and Node.js with a promise-based or Node.js-style callback-based API to progress events, text and binary file upload and download, partial response body, request and response headers, status code.

Overview
Installation
Examples
API
Development

Overview

Gracefully upgrades to latest platform-specific features:
- cross-origin resource sharing - do cross-domain requests with confidence;
- streaming - currently only streaming downloads, see description of option partialOutputMode below.
- progress events - get current and total bytes downloaded or uploaded;
- binary file uploads and downloads - easily use Blob, FormData, ArrayBuffer, Uint8Array or a simple array of bytes;
Supports both NodeJS style callbacks and Promises/A+ (with progress events, see an example).
Supports transparent gzip/deflate content decoding.
Handles HTTP responses The Right Way™:
- Tries hard to get the HTTP response status code in all cases.
- Emits the HTTP response status code and headers as soon as they are available.
- Gives you HTTP status code instead of an error, that is for example HTTP 404 would just return success, with status 404.
- Throws an error only when the HTTP request did not actually completely finished.
Well tested - over 600 acceptance tests.
Detects the presence of CommonJS and AMD script loaders.
Supports npm, Bower and Component package managers.
Tested on these web browsers:
- Internet Explorer 6 and later;
- Firefox 3.0 and later;
- Chrome 1 and later;
- Safari 4.0 and later;
- Opera 10.60 and later;
- Android 2.3.3 and later;
- Firefox OS 1.3 and later;
- Kindle 3.0 (Version/4.0);
- Samsung Smart-TV 4.5 (Webkit/537.42 Chromium/25.0).
Tested on these Node versions:
- 0.8;
- 0.10;
- 0.11;
- 0.12.

Installation

Install manually by adding to your HTML file:

<script src="/path/to/httpinvoke/httpinvoke-browser.js"></script>

Install with npm:

$ npm install --save httpinvoke

Install with component:

$ component install jakutis/httpinvoke

Install with bower:

$ bower install --save httpinvoke

Examples

Basic

var httpinvoke = require('httpinvoke');

httpinvoke('http://example.org', 'GET', function(err, body, statusCode, headers) {
    if(err) {
        return console.log('Failure', err);
    }
    console.log('Success', body, statusCode, headers);
});

Basic with Promises

var httpinvoke = require('httpinvoke');

httpinvoke('http://example.org', 'GET').then(function(res) {
    console.log('Success', res.body, res.statusCode, res.headers);
}, function(err) {
    console.log('Failure', err);
});

Promises and partial progress

httpinvoke('http://example.org', {
    partialOutputMode: 'chunked',
    outputType: 'bytearray'
}).then(function(res) {
    console.log('Success', res.body, res.statusCode, res.headers);
}, function(err) {
    console.log('Error occurred', err);
}, function(progress) {
    if(progress.type === 'upload') {
        // total and current are always defined
        console.log('progress: ' + (progress.total - progress.current) + ' bytes left to upload');
    } else if(progress.type === 'download') {
        var partialinfo = ' (received chunk of ' + progress.partial.length + ' bytes)';
        if(typeof progress.total === 'undefined') {
            console.log('progress: ' + progress.current + ' bytes downloaded' + partialinfo);
        } else {
            console.log('progress: ' + (progress.total - progress.current) + ' bytes left to download' + partialinfo);
        }
    } else if(progress.type === 'headers') {
        console.log('progress: received response with status code ' + progress.statusCode + ' and headers: ', progress.headers);
    }
});

Uploading an HTML form

var httpinvoke = require('httpinvoke');

var book = {
    content: 'Hello World',
    comment: 'initial version'
};
// convert the json object to application/x-www-form-urlencoded format string
var encodedBook = Object.keys(book).map(function(key) {
    return encodeURIComponent(key) + '=' + encodeURIComponent(book[key]);
}).join('&');
// upload to server
httpinvoke('http://example.org', 'POST', {
    headers: {
        // remove this header if doing a cross-domain request
        // or add a 'Content-Type' to 'Access-Control-Allow-Headers' server-side response header
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    input: encodedBook
}, function(err) {
    if(err) {
        return console.log('Failure', err);
    }
    console.log('Success');
});

Downloading and uploading a file

var httpinvoke = require('httpinvoke');

var converters = {
    'text json': JSON.parse,
    'json text': JSON.stringify
};
httpinvoke('https://bower-component-list.herokuapp.com/', 'GET', {
    outputType: 'json',
    converters: converters
}).then(function(response) {
    console.log('There are ' + response.body.length + ' bower packages.');
    return httpinvoke('http://server.cors-api.appspot.com/server?id=9285649&enable=true&status=200&credentials=false&methods=POST', 'POST', {
        input: response.body,
        inputType: 'json',
        converters: converters
    });
}, function(err) {
    console.log('Error receiving package list', err);
}, function(progress) {
    console.log('Receiving package list progress', progress);
}).then(function(response) {
    console.log('Uploading finished', response);
}, function(err) {
    console.log('Error sending package list', err);
}, function(progress) {
    console.log('Sending package list progress', progress);
});

Streaming JSON

var clarinet = require('clarinet');
var httpinvoke = require('httpinvoke');

var parser = clarinet.parser();
var lastKey = null;
parser.onvalue = function(v) {
    if(lastKey === 'name') {
        console.log('component', v);
    }
};
parser.onopenobject = function(key) {
    lastKey = key;
};
parser.onkey = function(key) {
    lastKey = key;
};
// try with slow internet connection
httpinvoke('https://bower-component-list.herokuapp.com/', {
    partialOutputMode: 'chunked'
}).then(function(res) {
    parser.close();
    console.log('OK, in total there are ' + JSON.parse(res.body).length + ' bower components');
}, function(err) {
    console.log('Error occurred', err);
}, function(progress) {
    if(progress.type === 'download') {
        console.log('received chunk of length=' + progress.partial.length);
        parser.write(progress.partial);
    }
});

API

var abort = httpinvoke(url, method, options, cb)

Any one, two or three arguments can be skipped, except the url.

abort is a function for aborting the HTTP request. It is also a Promise/A+-compliant promise (has the then() method) that receives all the same events as the callbacks - uploading, downloading, gotStatus and finished - see an example. When invoked as a function, it immediately calls the "finished" callback with an Error. If "finished" callback is already called before the "abort", nothing happens.
url is a string for URL, e.g. "http://example.org/".
method is a string for HTTP method, one of "HEAD", "GET", "PATCH", "POST", "PUT", "DELETE".
options is an object for various options (see the Options section below) or a function, which is used as a "finished" option (see the first example).
cb is a function that is used as an option finished (read below).

Options

See the Examples section for all the options being used. All options are optional.

partialOutputMode is a string for the type of the partial argument of the downloading option, one of "disabled" (default, downloading will not receive the partial argument), "chunked" (the received value will be the latest chunk), "joined" (the received value will be the entire partial body).
anonymous - is a boolean - if true, then user credentials are not sent, if false - sent. Applicable only when anonymousOption feature flag is true. Defaults to the value of anonymousByDefault feature flag. See corsCredentials feature flag, if you are making a cross-origin request with system option being false.
system - is a boolean - if true, then [same origin

Httpinvoke

Install / Use

README