stream-http

What is stream-http?

The stream-http npm package is designed to provide a streaming HTTP client for browser-based applications that mimics node's native http module, allowing for code that uses http to be more easily ported to the browser.

What are stream-http's main functionalities?

HTTP GET request

This feature allows you to perform an HTTP GET request and stream the response data as it is received.

const http = require('stream-http');

http.get('http://example.com', function (response) {
  response.on('data', function (chunk) {
    console.log('BODY: ' + chunk);
  });
});

HTTP request with options

This feature allows you to perform an HTTP request with custom options such as method, path, and headers, and to send data in the body of the request.

const http = require('stream-http');

const options = {
  method: 'POST',
  path: '/submit',
  headers: {'Content-Type': 'application/json'}
};

const req = http.request(options, function (response) {
  console.log('STATUS: ' + response.statusCode);
  response.on('data', function (chunk) {
    console.log('BODY: ' + chunk);
  });
});

req.write(JSON.stringify({ key: 'value' }));
req.end();

Handling request errors

This feature demonstrates how to handle errors that may occur during an HTTP request.

const http = require('stream-http');

http.get('http://example.com', function (response) {
  response.on('data', function (chunk) {
    console.log('BODY: ' + chunk);
  });
}).on('error', function (e) {
  console.error('Request failed: ' + e.message);
});

Other packages similar to stream-http

axios

Axios is a promise-based HTTP client for the browser and node.js. It provides a simple API for performing HTTP requests and is often preferred for its ease of use and promise support compared to stream-http.

fetch

The Fetch API provides a JavaScript interface for accessing and manipulating parts of the HTTP pipeline, such as requests and responses. It is built into modern browsers and offers a more modern, promise-based approach to asynchronous HTTP requests compared to stream-http.

superagent

Superagent is a small progressive client-side HTTP request library that offers a simple, fluent API. It is often used for its chaining syntax and built-in support for JSON, which can make it more convenient than stream-http for certain use cases.

got

Got is a human-friendly and powerful HTTP request library for Node.js. It is designed to be a simpler and more robust alternative to the built-in http module, with features like retries and streams, which can make it a more feature-rich alternative to stream-http.

README

stream-http

This module is an implementation of node's native http module for the browser. It tries to match node's api and behavior as closely as possible, but some features aren't available, since browsers don't give nearly as much control over requests.

This is heavily inspired by, and intended to replace, http-browserify

What does it do?

In accordance with its name, stream-http tries to provide data to its caller before the request has completed whenever possible.

The following browsers support true streaming, where only a small amount of the request has to be held in memory at once:

• Chrome >= 43 (using the fetch api)
• Firefox >= 9 (using moz-chunked-arraybuffer responseType with xhr)

The following browsers support pseudo-streaming, where the data is available before the request finishes, but the entire response must be held in memory:

• Chrome
• Safari >= 5, and maybe older
• IE >= 10
• Most other Webkit-based browsers, including the default Android browser

All browsers newer than IE8 support binary responses. All of the above browsers that support true streaming or pseudo-streaming support that for binary data as well except for IE10. Old (presto-based) Opera also does not support binary streaming either.

How do you use it?

The intent is to have the same api as the client part of the node HTTP module. The interfaces are the same wherever practical, although limitations in browsers make an exact clone of the node api impossible.

This module implements http.request, http.get, and most of http.ClientRequest and http.IncomingMessage in addition to http.METHODS and http.STATUS_CODES. See the node docs for how these work.

Extra features compared to node

• The options.withCredentials boolean flag, used to indicate if the browser should send cookies or authentication information with a CORS request. Default true.

This module has to make some tradeoffs to support binary data and/or streaming. Generally, the module can make a fairly good decision about which underlying browser features to use, but sometimes it helps to get a little input from the user.

• The options.mode field passed into http.request or http.get can take on one of the following values:
  • 'default' (or any falsy value, including undefined): Try to provide partial data before the equest completes, but not at the cost of correctness for binary data. In some cases the implementation may be a bit slow.
  • 'prefer-stream': Provide data before the request completes even if binary data (anything that isn't a single-byte ASCII or utf8 character) will be corrupted. Of course, this option is only safe for text data.
  • 'prefer-fast': Use an implementation that does less processing even if it means that partial data isn't available. This is particularly useful when making large requests in a browser like Safari that has a weaker javascript engine.

Features missing compared to node

• http.Agent is only a stub
• The 'socket', 'connect', 'upgrade', and 'continue' events on http.ClientRequest.
• Any operations, including request.setTimeout, that operate directly on the underlying socket.
• Any options that are disallowed for security reasons. This includes setting or getting certian headers.
• message.httpVersion
• message.rawHeaders is modified by the browser, and may not quite match what is sent by the server.
• message.trailers and message.rawTrailers will remain empty.

Example

http.get('/bundle.js', function (res) {
	var div = document.getElementById('result');
	div.innerHTML += 'GET /beep<br>';
	
	res.on('data', function (buf) {
		div.innerHTML += buf;
	});
	
	res.on('end', function () {
		div.innerHTML += '<br>__END__';
	});
})

License

MIT. Copyright (C) John Hiesey and other contributors.