Isomorphic HTTP Stream

0.1.2 · active · verified Wed Apr 22

iso-stream-http is a JavaScript module that provides an isomorphic (browser and Node.js compatible) implementation of Node.js's native `http` module. Currently at version 0.1.2, it aims to replicate the Node.js HTTP client API as closely as possible within browser environments, offering pseudo-streaming capabilities where the entire response is held in memory, and in some modern browsers, true streaming. It is heavily inspired by and intended to replace `stream-http`. The project appears to have a slow release cadence, with the latest update being minor bug fixes. Key differentiators include its isomorphic nature, aiming for Node.js API parity in the browser, and its focus on providing data before the request completes, which is a significant feature for handling larger responses efficiently in both client and server contexts.

Common errors

```
https does not exist
```
cause An issue with the internal resolution of the `https` module, particularly in certain environments or configurations.

fix Update `iso-stream-http` to version 0.1.2 or later, as this specific error was addressed in that release.
```
TypeError: Cannot read properties of undefined (reading 'on') when trying to attach socket event listener
```
cause Attempting to attach event listeners like 'socket' or 'connect' to the `ClientRequest` object, which are not supported as `http.Agent` is a stub and direct socket access is not available in the browser implementation.

fix Remove any code attempting to interact with the underlying socket or listen for socket-specific events. The library does not expose this level of control. Focus on `data`, `end`, and `error` events for the response stream.

Warnings

gotcha The `http.Agent` in `iso-stream-http` is only a stub and does not provide actual agent functionality as it would in Node.js. Users expecting connection pooling or proxying via `http.Agent` will find it non-functional.
Fix: Avoid relying on `http.Agent` for browser-based requests. For advanced network control in the browser, consider `fetch` API options or browser-specific network configurations, which are outside the scope of this library.
gotcha Many socket-level events and operations available in Node.js's `http.ClientRequest` are not implemented. This includes 'socket', 'connect', 'upgrade', 'continue' events, and `request.setTimeout`. The browser's security model restricts direct socket access.
Fix: Do not attempt to use socket-specific events or methods. For request timeouts, use `options.requestTimeout` which is a library-specific alternative, but note it behaves differently than Node's `setTimeout`.
gotcha Certain HTTP headers cannot be set or retrieved due to browser security restrictions (e.g., 'referer', 'cookie', 'host'). Additionally, `message.rawHeaders` might not exactly match what the server sends, and `message.trailers` and `message.rawTrailers` will always be empty. `message.httpVersion` is also missing.
Fix: Be aware of browser-enforced header limitations. For debugging, inspect `message.headers` (which is processed by the browser) rather than expecting raw headers. Do not rely on `trailers` for critical response data.
gotcha HTTP redirects (301/302) are followed silently by the browser. This means `iso-stream-http` will not expose the intermediate redirect responses, only the final destination. This differs from Node.js where redirects are often observable.
Fix: Assume redirects are handled transparently. If redirect URLs or statuses are required, a server-side proxy or a different browser-native API (like `fetch` with `redirect: 'manual'`) would be necessary.

Install

npm install iso-stream-http npm
yarn add iso-stream-http yarn
pnpm add iso-stream-http pnpm

Imports

http
wrong:
```
const http = require('iso-stream-http').http;
```
correct:
```
import { http } from 'iso-stream-http';
```
Primary HTTP client for making requests. The README examples primarily use CommonJS `require`, but named ESM imports are the modern standard.
https
wrong:
```
const https = require('iso-stream-http').https;
```
correct:
```
import { https } from 'iso-stream-http';
```
Secure HTTP client for making HTTPS requests. Functions identically to `http` but for secure connections.
getRequest
wrong:
```
const getRequest = require('iso-stream-http').getRequest;
```
correct:
```
import { getRequest } from 'iso-stream-http';
```
A helper function that detects the URL protocol (http/https) and returns the appropriate client (`http` or `https`) in Node.js.

Quickstart

Demonstrates how to make an HTTP GET request, handle streaming data chunks, and detect the end of the response using `iso-stream-http`'s Node.js-like API.

const { http } = require('iso-stream-http');

console.log('Fetching /bundle.js...');

http.get('http://localhost:8080/bundle.js', function (res) {
  console.log(`Status: ${res.statusCode}`);
  console.log('Headers:', res.headers);

  let data = '';
  res.on('data', function (buf) {
    data += buf.toString();
    process.stdout.write('Received chunk: ' + buf.length + ' bytes\n');
  });

  res.on('end', function () {
    console.log('\n__END__');
    // In a browser, you might update the DOM here:
    // document.getElementById('result').innerHTML += '<br>__END__';
    console.log('Full response data length:', data.length);
  });

  res.on('error', function(err) {
    console.error('Response error:', err);
  });
}).on('error', function(err) {
  console.error('Request error:', err);
});

// To make this runnable, you would need a simple HTTP server
// serving a 'bundle.js' file on http://localhost:8080
// Example server (Node.js):
/*
const server = require('http').createServer((req, res) => {
  if (req.url === '/bundle.js') {
    res.writeHead(200, { 'Content-Type': 'application/javascript' });
    res.end('console.log("hello from bundle.js");');
  } else {
    res.writeHead(404); res.end('Not Found');
  }
});
server.listen(8080, () => console.log('Server listening on port 8080'));
*/

view raw JSON →