0
# Stream HTTP
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: stream-http
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install stream-http`
10

11
## Core Imports
12

13
```javascript
14
const http = require('stream-http');
15
```
16

17
For ES modules:
18

19
```javascript
20
import * as http from 'stream-http';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const http = require('stream-http');
27

28
// Simple GET request
29
http.get('/api/data', function (res) {
30
  console.log('Status:', res.statusCode);
31
  
32
  res.on('data', function (chunk) {
33
    console.log('Received:', chunk.toString());
34
  });
35
  
36
  res.on('end', function () {
37
    console.log('Request completed');
38
  });
39
});
40

41
// POST request with data
42
const req = http.request({
43
  method: 'POST',
44
  path: '/api/users',
45
  headers: {
46
    'Content-Type': 'application/json'
47
  }
48
}, function (res) {
49
  console.log('Response:', res.statusCode);
50
});
51

52
req.write(JSON.stringify({ name: 'Alice', age: 30 }));
53
req.end();
54
```
55

56
## Architecture
57

58
Stream HTTP is built around several key components:
59

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

66
The library automatically detects browser capabilities and selects the best implementation:
67
- **Fetch API**: For modern browsers with true streaming support
68
- **XHR with chunked responses**: For browsers supporting progressive data access
69
- **Standard XHR**: Fallback for maximum compatibility
70

71
## Capabilities
72

73
### HTTP Request Creation
74

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

77
```javascript { .api }
78
/**
79
 * Creates a new HTTP request
80
 * @param opts - URL string or options object
81
 * @param cb - Optional callback for 'response' event
82
 * @returns ClientRequest instance
83
 */
84
function request(opts, cb);
85

86
/**
87
 * Convenience method for GET requests
88
 * @param opts - URL string or options object  
89
 * @param cb - Optional callback for 'response' event
90
 * @returns ClientRequest instance
91
 */
92
function get(opts, cb);
93
```
94

95
[HTTP Requests](./http-requests.md)
96

97
### Request and Response Streaming
98

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

101
```javascript { .api }
102
class ClientRequest extends stream.Writable {
103
  /**
104
   * Sets an HTTP request header
105
   * @param name - Header name
106
   * @param value - Header value
107
   */
108
  setHeader(name, value);
109
  
110
  /**
111
   * Gets an HTTP request header value
112
   * @param name - Header name
113
   * @returns Header value or null
114
   */
115
  getHeader(name);
116
  
117
  /**
118
   * Sets request timeout
119
   * @param timeout - Timeout in milliseconds
120
   * @param cb - Optional timeout callback
121
   */
122
  setTimeout(timeout, cb);
123
  
124
  /**
125
   * Aborts the request
126
   * @param err - Optional error
127
   */
128
  abort(err);
129
}
130

131
class IncomingMessage extends stream.Readable {
132
  /** Response headers (lowercase keys) */
133
  headers;
134
  /** Raw response headers array */
135
  rawHeaders;
136
  /** HTTP status code */
137
  statusCode;
138
  /** HTTP status message */
139
  statusMessage;
140
  /** Final URL after redirects */
141
  url;
142
}
143
```
144

145
[Request and Response Streaming](./streaming.md)
146

147
### Browser-Specific Features
148

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

151
```javascript { .api }
152
interface RequestOptions {
153
  /** Standard Node.js options */
154
  protocol?: string;
155
  hostname?: string;
156
  host?: string;
157
  port?: number;
158
  path?: string;
159
  method?: string;
160
  headers?: object;
161
  auth?: string;
162
  
163
  /** Browser-specific options */
164
  withCredentials?: boolean;
165
  mode?: 'default' | 'allow-wrong-content-type' | 'prefer-streaming' | 'disable-fetch' | 'prefer-fast';
166
  requestTimeout?: number;
167
  timeout?: number;
168
}
169
```
170

171
[Browser Features](./browser-features.md)
172

173
## Types
174

175
```javascript { .api }
176
/**
177
 * Agent class - Compatibility stub for Node.js http.Agent
178
 * No actual connection pooling in browser environment
179
 */
180
const Agent = function () {};
181
Agent.defaultMaxSockets = 4;
182

183
const globalAgent = new Agent();
184

185
const STATUS_CODES = {
186
  // HTTP status code mappings from builtin-status-codes
187
};
188

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

196
/**
197
 * XMLHttpRequest ready states for internal response handling
198
 */
199
const readyStates = {
200
  UNSENT: 0,
201
  OPENED: 1,
202
  HEADERS_RECEIVED: 2,
203
  LOADING: 3,
204
  DONE: 4
205
};
206
```