0
# Readable Stream
1

2
Readable Stream is a userland implementation of Node.js core streams, providing a stable and consistent streaming API across different Node.js versions. It serves as a mirror of the streams implementations from Node.js 18.19.0, allowing developers to guarantee a stable streams base regardless of the Node.js version being used.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const {
15
  Readable,
16
  Writable,
17
  Transform,
18
  Duplex,
19
  PassThrough,
20
  pipeline,
21
  finished
22
} = require('readable-stream');
23
```
24

25
For ESM:
26

27
```javascript
28
import {
29
  Readable,
30
  Writable,
31
  Transform,
32
  Duplex,
33
  PassThrough,
34
  pipeline,
35
  finished
36
} from 'readable-stream';
37
```
38

39
## Basic Usage
40

41
You can swap your `require('stream')` with `require('readable-stream')` without any changes, if you are just using one of the main classes and functions.
42

43
```javascript
44
const { Readable, Transform, pipeline } = require('readable-stream');
45

46
// Create a readable stream
47
const readableStream = new Readable({
48
  read() {
49
    this.push('hello ');
50
    this.push('world');
51
    this.push(null); // End the stream
52
  }
53
});
54

55
// Create a transform stream
56
const upperCaseTransform = new Transform({
57
  transform(chunk, encoding, callback) {
58
    this.push(chunk.toString().toUpperCase());
59
    callback();
60
  }
61
});
62

63
// Pipe streams together using pipeline
64
pipeline(
65
  readableStream,
66
  upperCaseTransform,
67
  process.stdout,
68
  (err) => {
69
    if (err) {
70
      console.error('Pipeline failed:', err);
71
    } else {
72
      console.log('Pipeline succeeded');
73
    }
74
  }
75
);
76
```
77

78
## Architecture
79

80
Readable Stream is built around several key components:
81

82
- **Core Stream Classes**: `Readable`, `Writable`, `Duplex`, `Transform`, and `PassThrough` providing the foundation for all streaming operations
83
- **Utility Functions**: `pipeline`, `finished`, `compose` for stream composition and lifecycle management
84
- **Stream Operators**: Functional programming methods like `map`, `filter`, `reduce` for data transformation
85
- **Promise API**: Promise-based versions of utility functions for modern async/await patterns
86
- **Cross-Platform Support**: Works in both Node.js and browser environments with appropriate polyfills
87

88
## Capabilities
89

90
### Stream Classes
91

92
Core stream classes that form the foundation of the streaming system. These provide the base functionality for creating readable, writable, and transform streams.
93

94
```javascript { .api }
95
class Readable extends Stream {
96
  constructor(options?: ReadableOptions);
97
  read(size?: number): any;
98
  push(chunk: any, encoding?: BufferEncoding): boolean;
99
}
100

101
class Writable extends Stream {
102
  constructor(options?: WritableOptions);
103
  write(chunk: any, encoding?: BufferEncoding, cb?: (error: Error | null | undefined) => void): boolean;
104
  end(chunk?: any, encoding?: BufferEncoding, cb?: () => void): this;
105
}
106

107
class Duplex extends Readable {
108
  constructor(options?: DuplexOptions);
109
  // Implements both Readable and Writable interfaces
110
}
111

112
class Transform extends Duplex {
113
  constructor(options?: TransformOptions);
114
  _transform(chunk: any, encoding: BufferEncoding, callback: TransformCallback): void;
115
}
116

117
class PassThrough extends Transform {
118
  constructor(options?: PassThroughOptions);
119
}
120
```
121

122
[Stream Classes](./stream-classes.md)
123

124
### Utility Functions
125

126
Essential utilities for stream composition, error handling, and lifecycle management. These functions provide robust patterns for working with multiple streams.
127

128
```javascript { .api }
129
function pipeline(...streams: Array<NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream>, callback: (err: NodeJS.ErrnoException | null) => void): NodeJS.ReadableStream;
130

131
function finished(stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, options: FinishedOptions, callback: (err?: NodeJS.ErrnoException | null) => void): () => void;
132

133
function compose(...streams: Array<NodeJS.ReadWriteStream>): NodeJS.ReadWriteStream;
134

135
// Stream state utilities
136
function isDisturbed(stream: NodeJS.ReadableStream): boolean;
137
function isErrored(stream: NodeJS.ReadableStream | NodeJS.WritableStream): boolean;
138

139
// Internal utilities (exported for compatibility)
140
function _uint8ArrayToBuffer(chunk: Uint8Array): Buffer;
141
function _isUint8Array(value: any): boolean;
142

143
// Backwards compatibility
144
const Stream: typeof import('readable-stream');
145
```
146

147
[Utility Functions](./utility-functions.md)
148

149
### Stream Operators
150

151
Functional programming methods available on Readable streams for data transformation and processing. These operators provide a chainable API for stream manipulation.
152

153
```javascript { .api }
154
// Stream-returning operators (return streams)
155
map(fn: (chunk: any, options?: any) => any, options?: any): Readable;
156
filter(fn: (chunk: any, options?: any) => boolean, options?: any): Readable;
157
drop(number: number, options?: any): Readable;
158
take(number: number, options?: any): Readable;
159

160
// Promise-returning operators (return promises)
161
reduce(fn: (previous: any, current: any, options?: any) => any, initial?: any, options?: any): Promise<any>;
162
toArray(options?: any): Promise<any[]>;
163
forEach(fn: (chunk: any, options?: any) => void, options?: any): Promise<void>;
164
```
165

166
[Stream Operators](./stream-operators.md)
167

168
### Promise API
169

170
Promise-based versions of utility functions that integrate seamlessly with modern async/await patterns.
171

172
```javascript { .api }
173
const promises = {
174
  pipeline: (...streams: Array<NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream>) => Promise<void>;
175
  finished: (stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, options?: FinishedOptions) => Promise<void>;
176
};
177
```
178

179
[Promise API](./promise-api.md)
180

181
## Types
182

183
```javascript { .api }
184
interface ReadableOptions {
185
  highWaterMark?: number;
186
  encoding?: BufferEncoding;
187
  objectMode?: boolean;
188
  emitClose?: boolean;
189
  read?(this: Readable, size: number): void;
190
  destroy?(this: Readable, error: Error | null, callback: (error: Error | null) => void): void;
191
  construct?(this: Readable, callback: (error?: Error | null) => void): void;
192
  autoDestroy?: boolean;
193
  signal?: AbortSignal;
194
}
195

196
interface WritableOptions {
197
  highWaterMark?: number;
198
  decodeStrings?: boolean;
199
  defaultEncoding?: BufferEncoding;
200
  objectMode?: boolean;
201
  emitClose?: boolean;
202
  write?(this: Writable, chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
203
  writev?(this: Writable, chunks: Array<{ chunk: any, encoding: BufferEncoding }>, callback: (error?: Error | null) => void): void;
204
  destroy?(this: Writable, error: Error | null, callback: (error: Error | null) => void): void;
205
  final?(this: Writable, callback: (error?: Error | null) => void): void;
206
  construct?(this: Writable, callback: (error?: Error | null) => void): void;
207
  autoDestroy?: boolean;
208
  signal?: AbortSignal;
209
}
210

211
interface DuplexOptions extends ReadableOptions, WritableOptions {
212
  allowHalfOpen?: boolean;
213
  readableObjectMode?: boolean;
214
  writableObjectMode?: boolean;
215
  readableHighWaterMark?: number;
216
  writableHighWaterMark?: number;
217
}
218

219
interface TransformOptions extends DuplexOptions {
220
  transform?(this: Transform, chunk: any, encoding: BufferEncoding, callback: TransformCallback): void;
221
  flush?(this: Transform, callback: TransformCallback): void;
222
}
223

224
interface PassThroughOptions extends TransformOptions {}
225

226
interface FinishedOptions {
227
  error?: boolean;
228
  readable?: boolean;
229
  writable?: boolean;
230
  signal?: AbortSignal;
231
}
232

233
type TransformCallback = (error?: Error | null, data?: any) => void;
234
```