httpinvoke

A 4.8kb 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

npm install httpinvoke
1 downloads in the last day
4 downloads in the last week
89 downloads in the last month

httpinvoke

httpinvoke is a 4.8kb 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.

Build Status

Overview

  • Gracefully upgrades to latest platform-specific features:
  • 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 560 unit 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 1.5 and later;
    • Chrome 1 and later;
    • Safari 4.0 and later;
    • Opera 10.50 and later;
    • Mobile Safari 7.0.0;
    • Kindle 3.0.0;
    • Android 2.3.7.

Installation

manually

Adding to your HTML file:

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

with npm

npm install --save httpinvoke

with Bower

bower install --save httpinvoke

with Component

component install jakutis/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 this argument), "chunked" (the received value will be the latest chunk), "joined" (the received value will be the entire partial body).
  • timeout must be either one of:
    • undefined (default), means that finished must never be called with any of the timeout errors,
    • a number (greater than 0 and less than 1073741824) for maximum duration in milliseconds between the httpinvoke call and finished call, if it timeouts - finished must be called with "timeout" error,
    • an instance of Array (if corsFineGrainedTimeouts feature is not supported and url is cross-origin then timeout is assigned to the sum of this array) with elements:
      1. a number (greater than 0 and less than 1073741824) for maximum duration in milliseconds between the httpinvoke call and gotStatus call, if it timeouts - finished must be called with "upload timeout" error;
      2. a number (greater than 0 and less than 1073741824) for maximum duration in milliseconds between gotStatus call and finished call, if it timeouts - finished must be called with "download timeout" error.
  • uploading is a function that is called when HTTP request upload progress event happens. It is called with these arguments:
    1. current is a number for the number of bytes currently sent;
    2. total is a number for the total number of bytes to be sent.
  • downloading is a function that is called when HTTP response download progress event happens. It is called with these arguments:
    1. current is a number for the number of bytes currently received;
    2. total is a number for the total number of bytes to be received, or undefined if not known.
    3. partial is a string (or bytearray, if either outputType is "bytearray" or a custom outputType will be converted from bytearray), or undefined if partialOutputMode option is set to "disabled".
  • gotStatus is a function that is called when HTTP response headers are received. It is called with these arguments:
    1. status is a number for an HTTP response status code, either undefined, or a correct value.
    2. headers is an object for HTTP response headers. Keys are lower-cased header names, values are strings.
  • finished is a function that is called when HTTP response is fully downloaded, or any error happens. It is called with these arguments:
    1. err is null or an object that is an instance of Error, please read error conditions section below;
    2. output is:
      • undefined, if err is not null or no response entity has been received (e.g. when method is "HEAD"),
      • a string, if outputType is "text",
      • a bytearray - instance of Uint8Array or instance of Buffer or instance of Array that has elements of type "number" with values ranging from 0 to 255 - if outputType is "bytearray",
      • any value - if outputType is neither "bytearray", nor "text", i.e. a converter has been called.
    3. status is:
      • undefined, if err is not null or no correct value is available,
      • otherwise, a number for an HTTP response status code, correct value.
    4. headers is:
      • undefined, if err is not null,
      • otherwise, an object for HTTP response headers. Keys are lower-cased header names, values are strings.
  • outputType is a string for the type of the output argument of the finished option, one of "text" (default), "bytearray" or a custom value that has corresponding converters.
  • inputType is a string for the type of the input option, one of "auto"(default), "bytearray", "text", "formdata" or a custom value that has corresponding converters. If not "auto", input must be not be undefined.
  • input must be either one of:
    • undefined (default), if inputType is "auto" and request headers does not have Content-Type,
    • a string, if inputType is "text" or "auto",
    • a bytearray - instance of ArrayBuffer or instance of ArrayBufferView or instance of Blob or instance of File or instance of Buffer or instance of Array that has elements of type "number" with values ranging from 0 to 255 - if inputType is "bytearray" or "auto".
    • an instance of FormData - if inputType is "formdata" or "auto",
  • headers is an object for HTTP request headers. Keys are header names, values are strings.
  • converters is an object to convert custom inputType and outputType values to "bytearray" or "text". Example: {"json text": JSON.stringify, "text json": JSON.parse}. If you use custom inputType, then there must be at least one converter from that type to "text" or "bytearray", and the other way around for outputType.
  • corsExposedHeaders is an array of HTTP response headers to be extracted in gotStatus call. Default simple headers like "Content-Type" are always extracted. Applicable only for cross-origin requests.
  • corsCredentials is a boolean for requesting to send credentials. Applicable only for a cross-origin request. See Feature Flags section. Defaults to false.
  • corsOriginHeader is a string for the request header name for browsers with buggy CORS implementations (e.g. Android Browser 2.3.7) - which do not send the Origin request header in actual request. By default corsOriginHeader is not set, as it needs a proper Access-Control-Allow-Headers server-side header, see dummyserver.js for an example of server-side part of the workaround implementation.

Callback Sequence

The callbacks are called in this strict sequence:

  1. uploading (two or more times);
  2. gotStatus (one time);
  3. downloading (two or more times);
  4. finished (one time), except the case that finished can be called with Error any time, and then no callbacks will be called.

Feature Flags

There are feature flags to be queried for platform-specific features.

if(httpinvoke.cors) {
    console.log('Cross-Origin Resource Sharing support is available!');
}

Error Conditions

The finished callback will be called with an instance of Error only when strictly either one of these things happen:

  • abort function was called (error message "abort");
  • number of received bytes does not equal the Content-Type value or native XMLHttpRequest called .onerror without a .status or .statusText (error message "network error") - this can happen due to various network errors, server response sending or request receiving errors, or simply an unsupported status code - e.g. Firefox 3.0 ends up here after a status 408 response;
  • sending request timed out (error message "upload timeout");
  • receiving response timed out (error message "download timeout");
  • sending request and receiving response timed out (error message "timeout");
  • converter from converters option threw an error (the thrown error message is passed);
  • request did not even start (error message "Error code #%. See https://github.com/jakutis/httpinvoke#error-codes") - calling options validation failed or a feature that is not supported by the platform was used (various error messages are passed, e.g. "Unsupported method TRACE"). See error codes.

So generally, finishing with an error means that a response has not been received. Please note that a request can finish successfully, with an err set to null, but also with an undefined status, undefined output and an empty headers object - generally status is defined at all times, but some older browsers provide status code only for 2XX responses - e.g. Opera 11.50.

Error Codes

  • 001 Option % is less than zero
  • 002 Option % is not a number
  • 003 Option "partialOutputMode" is neither "disabled", nor "chunked", nor "joined"
  • 004 Unsupported method %
  • 005 Unsupported outputType %
  • 006 "inputType" is undefined or auto and input is neither string, nor FormData, nor an instance of Buffer, nor Blob, nor File, nor ArrayBuffer, nor ArrayBufferView, nor Int8Array, nor Uint8Array, nor Uint8ClampedArray, nor Int16Array, nor Uint16Array, nor Int32Array, nor Uint32Array, nor Float32Array, nor Float64Array, nor Array
  • 007 "inputType" is text, but input is not a string
  • 008 "inputType" is formdata, but input is not an instance of FormData
  • 009 "inputType" is bytearray, but input is neither an instance of Buffer, nor Blob, nor File, nor ArrayBuffer, nor ArrayBufferView, nor Int8Array, nor Uint8Array, nor Uint8ClampedArray, nor Int16Array, nor Uint16Array, nor Int32Array, nor Uint32Array, nor Float32Array, nor Float64Array, nor Array
  • 010 There is no converter for specified "inputType" %
  • 011 "input" is undefined, but "inputType" is defined
  • 012 "input" is undefined, but "Content-Type" input header is defined
  • 013 "timeout" value is not valid
  • 014 Input header % is forbidden to be set programmatically
  • 015 Input header % (to be precise, all Proxy-*) is forbidden to be set programmatically
  • 016 Input header % (to be precise, all Sec-*) is forbidden to be set programmatically
  • 017 bytearray inputType is not supported on this platform, please always test using requestTextOnly feature flag - hint - you may want to try sending FormData (formdata type)
  • 018 Cross-origin requests are not supported in this browser
  • 019 % method cross-origin requests are not supported in this browser
  • 020 PATCH method requests are not supported in this browser
  • 021 Unable to construct XMLHttpRequest object
  • 022 Unable to open uri %
  • 023 Unable to set input header %
  • 024 Unable to send

Development

To test for NodeJS functionality run npm run test-node.

To test for web browser functionality run npm run test-browser, copy the URL link that is displayed in console and open it in any web browser.

Checklist before releasing

  • package.json, bower.json and component.json version number bumped
  • file size, number of tests in readme.markdown updated
  • httpinvoke-* files regenerated

License

The MIT License (MIT)

Copyright (c) 2013 Vytautas Jakutis <vytautas@jakut.is>

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
npm loves you