0
# StreamX
1

2
StreamX is an improved iteration of Node.js core streams with enhanced lifecycle support, proper error handling, simplified API design, and a significantly smaller browser footprint. It provides better stream lifecycle management, integrated error handling with automatic cleanup, pipe operations with built-in error handling and callbacks, unified binary and object mode streams, backwards compatibility with Node.js streams, and AbortSignal support for async/await integration.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const { 
15
  Readable, 
16
  Writable, 
17
  Duplex, 
18
  Transform, 
19
  PassThrough, 
20
  Stream,
21
  pipeline,
22
  pipelinePromise
23
} = require('streamx');
24
```
25

26
For utility functions:
27

28
```javascript
29
const { 
30
  isStream, 
31
  isStreamx, 
32
  isEnded, 
33
  isFinished, 
34
  isDisturbed, 
35
  getStreamError 
36
} = require('streamx');
37
```
38

39
## Basic Usage
40

41
```javascript
42
const { Readable, Writable, pipeline } = require('streamx');
43

44
// Create a readable stream
45
const readable = new Readable({
46
  read(cb) {
47
    this.push('Hello StreamX!');
48
    this.push(null); // End the stream
49
    cb();
50
  }
51
});
52

53
// Create a writable stream
54
const writable = new Writable({
55
  write(data, cb) {
56
    console.log('Received:', data.toString());
57
    cb();
58
  }
59
});
60

61
// Pipe streams together
62
readable.pipe(writable, (err) => {
63
  if (err) console.error('Pipeline failed:', err);
64
  else console.log('Pipeline completed successfully');
65
});
66
```
67

68
## Architecture
69

70
StreamX is built around several key improvements over Node.js core streams:
71

72
- **Enhanced Lifecycle**: Proper `_open` and `_destroy` hooks for resource management
73
- **Integrated Error Handling**: Unified error handling with automatic cleanup and destroy logic
74
- **Unified Stream Mode**: Single stream type handles both binary and object modes through `map` and `byteLength` functions
75
- **Pipeline Integration**: Built-in pipeline functions with error handling and callback support
76
- **AbortSignal Support**: Integration with AbortController for cancellation
77
- **Smaller Footprint**: 8x smaller gzipped size compared to Node.js core streams
78

79
## Capabilities
80

81
### Readable Streams
82

83
Core readable stream functionality with enhanced lifecycle management and backpressure handling. Supports both flowing and non-flowing modes with proper pause/resume behavior.
84

85
```javascript { .api }
86
class Readable extends Stream {
87
  constructor(options?: ReadableOptions);
88
  _read(cb: () => void): void;
89
  _open(cb: (err?: Error) => void): void;
90
  _destroy(cb: (err?: Error) => void): void;
91
  push(data: any): boolean;
92
  read(): any;
93
  pipe(destination: Writable, callback?: (err?: Error) => void): Writable;
94
}
95

96
interface ReadableOptions {
97
  highWaterMark?: number;
98
  map?: (data: any) => any;
99
  byteLength?: (data: any) => number;
100
  signal?: AbortSignal;
101
  eagerOpen?: boolean;
102
  read?: (cb: () => void) => void;
103
  open?: (cb: (err?: Error) => void) => void;
104
  destroy?: (cb: (err?: Error) => void) => void;
105
  predestroy?: () => void;
106
}
107
```
108

109
[Readable Streams](./readable.md)
110

111
### Writable Streams
112

113
Core writable stream functionality with enhanced drain handling and batch writing support. Includes proper finish/close lifecycle management.
114

115
```javascript { .api }
116
class Writable extends Stream {
117
  constructor(options?: WritableOptions);
118
  _write(data: any, cb: (err?: Error) => void): void;
119
  _writev(batch: any[], cb: (err?: Error) => void): void;
120
  _open(cb: (err?: Error) => void): void;
121
  _destroy(cb: (err?: Error) => void): void;
122
  write(data: any): boolean;
123
  end(): void;
124
}
125

126
interface WritableOptions {
127
  highWaterMark?: number;
128
  map?: (data: any) => any;
129
  byteLength?: (data: any) => number;
130
  signal?: AbortSignal;
131
  write?: (data: any, cb: (err?: Error) => void) => void;
132
  writev?: (batch: any[], cb: (err?: Error) => void) => void;
133
  final?: (cb: (err?: Error) => void) => void;
134
  open?: (cb: (err?: Error) => void) => void;
135
  destroy?: (cb: (err?: Error) => void) => void;
136
  predestroy?: () => void;
137
}
138
```
139

140
[Writable Streams](./writable.md)
141

142
### Duplex and Transform Streams
143

144
Duplex streams that are both readable and writable, and Transform streams that provide data transformation capabilities.
145

146
```javascript { .api }
147
class Duplex extends Readable {
148
  constructor(options?: DuplexOptions);
149
  // Includes all Readable methods plus Writable methods
150
  write(data: any): boolean;
151
  end(): void;
152
}
153

154
class Transform extends Duplex {
155
  constructor(options?: TransformOptions);
156
  _transform(data: any, cb: (err?: Error, data?: any) => void): void;
157
}
158

159
class PassThrough extends Transform {
160
  constructor(options?: TransformOptions);
161
  // Pass-through implementation (no transformation)
162
}
163
```
164

165
[Duplex and Transform Streams](./duplex-transform.md)
166

167
### Pipeline Functions
168

169
Pipeline utilities for connecting multiple streams with proper error handling and cleanup.
170

171
```javascript { .api }
172
function pipeline(...streams: Stream[], callback?: (err?: Error) => void): Stream;
173
function pipelinePromise(...streams: Stream[]): Promise<void>;
174
```
175

176
[Pipeline Functions](./pipeline.md)
177

178
### Utility Functions
179

180
Helper functions for stream inspection and compatibility checking.
181

182
```javascript { .api }
183
function isStream(obj: any): boolean;
184
function isStreamx(obj: any): boolean;
185
function isEnded(stream: Readable): boolean;
186
function isFinished(stream: Writable): boolean;
187
function isDisturbed(stream: Readable): boolean;
188
function getStreamError(stream: Stream, opts?: object): Error | null;
189
```
190

191
## Types
192

193
```javascript { .api }
194
class Stream extends EventEmitter {
195
  destroyed: boolean;
196
  destroy(err?: Error): void;
197
}
198

199
interface CommonOptions {
200
  highWaterMark?: number;      // Buffer size in bytes (default: 16384)
201
  map?: (data: any) => any;    // Transform input data
202
  byteLength?: (data: any) => number;  // Calculate data size
203
  signal?: AbortSignal;        // AbortSignal for destruction
204
}
205
```