0
# streamx
1

2
streamx is an iteration of the Node.js core streams with a series of improvements including proper lifecycle support, easy error handling, pipe error handling, simplified API without object mode, and backwards compatibility with Node.js streams.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const { Readable, Writable, Duplex, Transform, Stream, isStream, isStreamx } = require("@mafintosh/streamx");
15
```
16

17
For ES modules:
18

19
```javascript
20
import { Readable, Writable, Duplex, Transform, Stream, isStream, isStreamx } from "@mafintosh/streamx";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const { Readable, Writable } = require("@mafintosh/streamx");
27

28
// Create a readable stream
29
const readable = new Readable({
30
  read(cb) {
31
    this.push("Hello World");
32
    this.push(null); // End stream
33
    cb(null);
34
  }
35
});
36

37
// Create a writable stream
38
const writable = new Writable({
39
  write(data, cb) {
40
    console.log("Received:", data.toString());
41
    cb(null);
42
  }
43
});
44

45
// Pipe streams together
46
readable.pipe(writable, (err) => {
47
  if (err) console.error("Pipeline failed:", err);
48
  else console.log("Pipeline completed");
49
});
50
```
51

52
## Architecture
53

54
streamx is built around several key improvements over Node.js core streams:
55

56
- **Lifecycle Management**: `_open()` and `_destroy()` methods provide proper initialization and cleanup
57
- **Integrated Error Handling**: `.destroy()` method with automatic cleanup and error propagation
58
- **Enhanced Pipe Operations**: `pipe()` accepts callbacks and handles errors automatically
59
- **Simplified Data Handling**: Uses `map()` and `byteLength()` functions instead of object mode
60
- **Single File Implementation**: Complete rewrite contained in one file for simplicity
61
- **Backwards Compatibility**: Compatible with Node.js streams where reasonable
62

63
## Capabilities
64

65
### Stream Base Class
66

67
Base class providing core stream functionality with lifecycle management and error handling.
68

69
```javascript { .api }
70
class Stream extends EventEmitter {
71
  constructor(opts?: StreamOptions);
72
  destroy(error?: Error): void;
73
  get destroyed(): boolean;
74
  get destroying(): boolean;
75
  on(name: string, fn: Function): this;
76
  _open(cb: (error?: Error) => void): void;
77
  _destroy(cb: (error?: Error) => void): void;
78
}
79

80
interface StreamOptions {
81
  open?: (cb: (error?: Error) => void) => void;
82
  destroy?: (cb: (error?: Error) => void) => void;
83
}
84
```
85

86
[Stream Base Class](./stream.md)
87

88
### Readable Streams
89

90
Readable stream implementation with buffer management and data flow control.
91

92
```javascript { .api }
93
class Readable extends Stream {
94
  constructor(opts?: ReadableOptions);
95
  push(data: any): boolean;
96
  read(): any;
97
  unshift(data: any): void;
98
  pause(): void;
99
  resume(): void;
100
  pipe(destination: Writable, cb?: (error?: Error) => void): Writable;
101
  _read(cb: (error?: Error) => void): void;
102
}
103

104
interface ReadableOptions extends StreamOptions {
105
  highWaterMark?: number;
106
  map?: (data: any) => any;
107
  byteLength?: (data: any) => number;
108
  read?: (cb: (error?: Error) => void) => void;
109
}
110
```
111

112
[Readable Streams](./readable.md)
113

114
### Writable Streams
115

116
Writable stream implementation with buffering and backpressure management.
117

118
```javascript { .api }
119
class Writable extends Stream {
120
  constructor(opts?: WritableOptions);
121
  write(data: any): boolean;
122
  end(data?: any): void;
123
  _write(data: any, cb: (error?: Error) => void): void;
124
  _final(cb: (error?: Error) => void): void;
125
}
126

127
interface WritableOptions extends StreamOptions {
128
  highWaterMark?: number;
129
  map?: (data: any) => any;
130
  byteLength?: (data: any) => number;
131
  write?: (data: any, cb: (error?: Error) => void) => void;
132
  final?: (cb: (error?: Error) => void) => void;
133
}
134
```
135

136
[Writable Streams](./writable.md)
137

138
### Duplex Streams
139

140
Duplex streams that are both readable and writable, inheriting from Readable with Writable functionality.
141

142
```javascript { .api }
143
class Duplex extends Readable {
144
  constructor(opts?: DuplexOptions);
145
  write(data: any): boolean;
146
  end(data?: any): void;
147
  _write(data: any, cb: (error?: Error) => void): void;
148
  _final(cb: (error?: Error) => void): void;
149
}
150

151
interface DuplexOptions extends ReadableOptions {
152
  mapReadable?: (data: any) => any;
153
  byteLengthReadable?: (data: any) => number;
154
  mapWritable?: (data: any) => any;
155
  byteLengthWritable?: (data: any) => number;
156
  write?: (data: any, cb: (error?: Error) => void) => void;
157
  final?: (cb: (error?: Error) => void) => void;
158
}
159
```
160

161
[Duplex Streams](./duplex.md)
162

163
### Transform Streams
164

165
Transform streams for data transformation, extending Duplex with transformation capabilities.
166

167
```javascript { .api }
168
class Transform extends Duplex {
169
  constructor(opts?: TransformOptions);
170
  _transform(data: any, cb: (error?: Error, result?: any) => void): void;
171
}
172

173
interface TransformOptions extends DuplexOptions {
174
  transform?: (data: any, cb: (error?: Error, result?: any) => void) => void;
175
  flush?: (cb: (error?: Error, result?: any) => void) => void;
176
}
177
```
178

179
[Transform Streams](./transform.md)
180

181
### Utility Functions
182

183
Stream detection utilities for identifying stream types.
184

185
```javascript { .api }
186
/**
187
 * Check if an object is a Node.js stream
188
 * @param stream - Object to test
189
 * @returns True if object is a stream
190
 */
191
function isStream(stream: any): boolean;
192

193
/**
194
 * Check if an object is a streamx stream
195
 * @param stream - Object to test  
196
 * @returns True if object is a streamx stream
197
 */
198
function isStreamx(stream: any): boolean;
199
```
200

201
## Types
202

203
```javascript { .api }
204
interface StreamOptions {
205
  open?: (cb: (error?: Error) => void) => void;
206
  destroy?: (cb: (error?: Error) => void) => void;
207
}
208

209
interface ReadableOptions extends StreamOptions {
210
  highWaterMark?: number;
211
  map?: (data: any) => any;
212
  byteLength?: (data: any) => number;
213
  read?: (cb: (error?: Error) => void) => void;
214
}
215

216
interface WritableOptions extends StreamOptions {
217
  highWaterMark?: number;
218
  map?: (data: any) => any;
219
  byteLength?: (data: any) => number;
220
  write?: (data: any, cb: (error?: Error) => void) => void;
221
  final?: (cb: (error?: Error) => void) => void;
222
}
223

224
interface DuplexOptions extends ReadableOptions {
225
  mapReadable?: (data: any) => any;
226
  byteLengthReadable?: (data: any) => number;
227
  mapWritable?: (data: any) => any;
228
  byteLengthWritable?: (data: any) => number;
229
  write?: (data: any, cb: (error?: Error) => void) => void;
230
  final?: (cb: (error?: Error) => void) => void;
231
}
232

233
interface TransformOptions extends DuplexOptions {
234
  transform?: (data: any, cb: (error?: Error, result?: any) => void) => void;
235
  flush?: (cb: (error?: Error, result?: any) => void) => void;
236
}
237
```