/http-request-plus

Small wrapper around {http,https}.request()

Primary LanguageJavaScript

http-request-plus

Package Version Build Status PackagePhobia Latest Commit

Small package that provides a promise-based, stream-oriented wrapper around the http and https modules.

Features:

  • HTTP & HTTPs
  • promise oriented
  • stream oriented
  • request body can be either a buffer/string or a stream
  • content length header automatically set if available
  • handle redirects
  • response emits error on timeout

Install

Installation of the npm package:

> npm install --save http-request-plus

Usage

Example

Easy use case: just downloads and prints a page with error handling.

ES2015 - ES2016:

import httpRequestPlus from "http-request-plus";

async function main() {
  // this is a standard Node's IncomingMessage augmented with the following method:
  //
  // - buffer(): returns a promise to the content of the response in a Buffer
  // - json(): returns a promise to the content of the response parsed as JSON
  // - text(): returns a promise to the content of the response parsed as a UTF-8 string
  const response = await httpRequestPlus("http://example.org", {
    // A request body can provided, either as a buffer/string or a stream
    body: "foo bar",

    // By default, http-request-plus throws if the reponse's status Code is not 2xx
    //
    // This option can be used to bypass this
    bypassStatusCheck: true,

    // Maximum number of redirects that should be handled by http-request-plus
    //
    // Defaults to 5
    maxRedirects: 0,

    // all other options are forwarded to native {http,https}.request()
    //
    // including `timeout` and `signal` which will properly trigger errors
  });

  // any error occuring after the response has been received, including abortion,
  // timeout, or body error (if body is a stream) will be emitted as an `error`
  // event on the response object

  console.log(await response.text());
}

main().catch((error) => console.error("FATAL:", error));

Contributions

Contributions are very welcomed, either on the documentation or on the code.

You may:

  • report any issue you've encountered;
  • fork and create a pull request.

Related Resources

License

ISC © Julien Fontanet