or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

browser-features.mdhttp-requests.mdindex.mdstreaming.md
tile.json

tessl/npm-stream-http

Streaming HTTP implementation for browsers with Node.js API compatibility

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/stream-http@3.2.x

To install, run

npx @tessl/cli install tessl/npm-stream-http@3.2.0

index.mddocs/

Stream HTTP

Stream HTTP is a browser implementation of Node.js's native HTTP module that enables streaming HTTP requests in web browsers. It provides API compatibility as close as possible to Node.js while supporting true streaming in modern browsers and pseudo-streaming in older browsers.

Package Information

  • Package Name: stream-http
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install stream-http

Core Imports

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

For ES modules:

import * as http from 'stream-http';

Basic Usage

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

// Simple GET request
http.get('/api/data', function (res) {
  console.log('Status:', res.statusCode);
  
  res.on('data', function (chunk) {
    console.log('Received:', chunk.toString());
  });
  
  res.on('end', function () {
    console.log('Request completed');
  });
});

// POST request with data
const req = http.request({
  method: 'POST',
  path: '/api/users',
  headers: {
    'Content-Type': 'application/json'
  }
}, function (res) {
  console.log('Response:', res.statusCode);
});

req.write(JSON.stringify({ name: 'Alice', age: 30 }));
req.end();

Architecture

Stream HTTP is built around several key components:

  • Main HTTP Module: Provides request() and get() functions with Node.js API compatibility
  • ClientRequest Class: Writable stream for handling outgoing HTTP requests
  • IncomingMessage Class: Readable stream for handling incoming HTTP responses
  • Capability Detection: Browser feature detection to choose optimal implementation strategy
  • Streaming Strategies: Multiple approaches (fetch, XHR variants) based on browser capabilities

The library automatically detects browser capabilities and selects the best implementation:

  • Fetch API: For modern browsers with true streaming support
  • XHR with chunked responses: For browsers supporting progressive data access
  • Standard XHR: Fallback for maximum compatibility

Capabilities

HTTP Request Creation

Core functionality for creating HTTP requests with Node.js API compatibility. Supports both simple string URLs and comprehensive options objects.

/**
 * Creates a new HTTP request
 * @param opts - URL string or options object
 * @param cb - Optional callback for 'response' event
 * @returns ClientRequest instance
 */
function request(opts, cb);

/**
 * Convenience method for GET requests
 * @param opts - URL string or options object  
 * @param cb - Optional callback for 'response' event
 * @returns ClientRequest instance
 */
function get(opts, cb);

HTTP Requests

Request and Response Streaming

Comprehensive streaming capabilities for both outgoing request data and incoming response data. Provides true streaming in supported browsers and pseudo-streaming fallback.

class ClientRequest extends stream.Writable {
  /**
   * Sets an HTTP request header
   * @param name - Header name
   * @param value - Header value
   */
  setHeader(name, value);
  
  /**
   * Gets an HTTP request header value
   * @param name - Header name
   * @returns Header value or null
   */
  getHeader(name);
  
  /**
   * Sets request timeout
   * @param timeout - Timeout in milliseconds
   * @param cb - Optional timeout callback
   */
  setTimeout(timeout, cb);
  
  /**
   * Aborts the request
   * @param err - Optional error
   */
  abort(err);
}

class IncomingMessage extends stream.Readable {
  /** Response headers (lowercase keys) */
  headers;
  /** Raw response headers array */
  rawHeaders;
  /** HTTP status code */
  statusCode;
  /** HTTP status message */
  statusMessage;
  /** Final URL after redirects */
  url;
}

Request and Response Streaming

Browser-Specific Features

Enhanced browser functionality beyond standard Node.js HTTP module, including CORS credentials, request modes, and timeout handling.

interface RequestOptions {
  /** Standard Node.js options */
  protocol?: string;
  hostname?: string;
  host?: string;
  port?: number;
  path?: string;
  method?: string;
  headers?: object;
  auth?: string;
  
  /** Browser-specific options */
  withCredentials?: boolean;
  mode?: 'default' | 'allow-wrong-content-type' | 'prefer-streaming' | 'disable-fetch' | 'prefer-fast';
  requestTimeout?: number;
  timeout?: number;
}

Browser Features

Types

/**
 * Agent class - Compatibility stub for Node.js http.Agent
 * No actual connection pooling in browser environment
 */
const Agent = function () {};
Agent.defaultMaxSockets = 4;

const globalAgent = new Agent();

const STATUS_CODES = {
  // HTTP status code mappings from builtin-status-codes
};

const METHODS = [
  'CHECKOUT', 'CONNECT', 'COPY', 'DELETE', 'GET', 'HEAD', 'LOCK',
  'M-SEARCH', 'MERGE', 'MKACTIVITY', 'MKCOL', 'MOVE', 'NOTIFY',
  'OPTIONS', 'PATCH', 'POST', 'PROPFIND', 'PROPPATCH', 'PURGE',
  'PUT', 'REPORT', 'SEARCH', 'SUBSCRIBE', 'TRACE', 'UNLOCK', 'UNSUBSCRIBE'
];

/**
 * XMLHttpRequest ready states for internal response handling
 */
const readyStates = {
  UNSENT: 0,
  OPENED: 1,
  HEADERS_RECEIVED: 2,
  LOADING: 3,
  DONE: 4
};