0
# is-stream
1
2
is-stream is a Node.js utility library that provides comprehensive stream type detection and validation capabilities. It offers runtime type checking functions that determine whether an object is a stream and what specific stream operations it supports, with configurable options for checking stream state.
3
4
## Package Information
5
6
- **Package Name**: is-stream
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules with TypeScript definitions)
9
- **Node.js Version**: >=18
10
- **Installation**: `npm install is-stream`
11
12
## Core Imports
13
14
```javascript
15
import { isStream, isWritableStream, isReadableStream, isDuplexStream, isTransformStream } from "is-stream";
16
```
17
18
Dynamic import (for CommonJS or conditional loading):
19
20
```javascript
21
const { isStream, isWritableStream, isReadableStream, isDuplexStream, isTransformStream } = await import("is-stream");
22
```
23
24
With TypeScript (including types):
25
26
```typescript
27
import { isStream, isWritableStream, isReadableStream, isDuplexStream, isTransformStream, type Options } from "is-stream";
28
```
29
30
## Basic Usage
31
32
```javascript
33
import fs from 'node:fs';
34
import { isStream, isWritableStream, isReadableStream } from 'is-stream';
35
36
// Check if something is any type of stream
37
const readStream = fs.createReadStream('file.txt');
38
console.log(isStream(readStream)); // true
39
40
// Check for specific stream types
41
const writeStream = fs.createWriteStream('output.txt');
42
console.log(isWritableStream(writeStream)); // true
43
console.log(isReadableStream(writeStream)); // false
44
45
// Configure stream state checking
46
console.log(isStream(closedStream, { checkOpen: false })); // true (ignores closed state)
47
console.log(isStream(closedStream, { checkOpen: true })); // false (default: checks if open)
48
```
49
50
## Capabilities
51
52
### Stream Detection
53
54
Detects if an object is any type of Node.js stream.
55
56
```javascript { .api }
57
/**
58
* Check if something is a Node.js Stream
59
* @param stream - The object to check
60
* @param options - Optional configuration
61
* @returns Whether the object is a stream
62
*/
63
function isStream(stream: unknown, options?: Options): stream is Stream;
64
```
65
66
### Writable Stream Detection
67
68
Detects if an object is a writable stream (stream.Writable, http.OutgoingMessage, http.ServerResponse, or http.ClientRequest).
69
70
```javascript { .api }
71
/**
72
* Check if something is a writable stream
73
* @param stream - The object to check
74
* @param options - Optional configuration
75
* @returns Whether the object is a writable stream
76
*/
77
function isWritableStream(stream: unknown, options?: Options): stream is WritableStream;
78
```
79
80
**Usage Example:**
81
82
```javascript
83
import fs from 'node:fs';
84
import http from 'node:http';
85
import { isWritableStream } from 'is-stream';
86
87
// File streams
88
console.log(isWritableStream(fs.createWriteStream('output.txt'))); // true
89
console.log(isWritableStream(fs.createReadStream('input.txt'))); // false
90
91
// HTTP streams
92
const server = http.createServer((req, res) => {
93
console.log(isWritableStream(res)); // true (ServerResponse)
94
console.log(isWritableStream(req)); // false (IncomingMessage)
95
});
96
97
// Network streams
98
import net from 'node:net';
99
const socket = new net.Socket();
100
console.log(isWritableStream(socket)); // true (Socket is duplex)
101
```
102
103
### Readable Stream Detection
104
105
Detects if an object is a readable stream (stream.Readable or http.IncomingMessage).
106
107
```javascript { .api }
108
/**
109
* Check if something is a readable stream
110
* @param stream - The object to check
111
* @param options - Optional configuration
112
* @returns Whether the object is a readable stream
113
*/
114
function isReadableStream(stream: unknown, options?: Options): stream is ReadableStream;
115
```
116
117
**Usage Example:**
118
119
```javascript
120
import fs from 'node:fs';
121
import http from 'node:http';
122
import { isReadableStream } from 'is-stream';
123
124
// File streams
125
console.log(isReadableStream(fs.createReadStream('input.txt'))); // true
126
console.log(isReadableStream(fs.createWriteStream('output.txt'))); // false
127
128
// HTTP streams
129
const server = http.createServer((req, res) => {
130
console.log(isReadableStream(req)); // true (IncomingMessage)
131
console.log(isReadableStream(res)); // false (ServerResponse)
132
});
133
```
134
135
### Duplex Stream Detection
136
137
Detects if an object is a duplex stream (stream.Duplex) that supports both reading and writing.
138
139
```javascript { .api }
140
/**
141
* Check if something is a duplex stream
142
* @param stream - The object to check
143
* @param options - Optional configuration
144
* @returns Whether the object is a duplex stream
145
*/
146
function isDuplexStream(stream: unknown, options?: Options): stream is DuplexStream;
147
```
148
149
**Usage Example:**
150
151
```javascript
152
import { Duplex } from 'node:stream';
153
import net from 'node:net';
154
import { isDuplexStream } from 'is-stream';
155
156
// Native duplex streams
157
const duplex = new Duplex({
158
write(chunk, encoding, callback) { callback(); },
159
read() { this.push(null); }
160
});
161
console.log(isDuplexStream(duplex)); // true
162
163
// Network streams (inherently duplex)
164
const socket = new net.Socket();
165
console.log(isDuplexStream(socket)); // true
166
```
167
168
### Transform Stream Detection
169
170
Detects if an object is a transform stream (stream.Transform) that can modify data as it passes through.
171
172
```javascript { .api }
173
/**
174
* Check if something is a transform stream
175
* @param stream - The object to check
176
* @param options - Optional configuration
177
* @returns Whether the object is a transform stream
178
*/
179
function isTransformStream(stream: unknown, options?: Options): stream is TransformStream;
180
```
181
182
**Usage Example:**
183
184
```javascript
185
import { Transform, PassThrough } from 'node:stream';
186
import { isTransformStream } from 'is-stream';
187
188
// Transform stream that uppercases text
189
const uppercaseTransform = new Transform({
190
transform(chunk, encoding, callback) {
191
callback(null, chunk.toString().toUpperCase());
192
}
193
});
194
console.log(isTransformStream(uppercaseTransform)); // true
195
196
// PassThrough is also a transform stream
197
const passthrough = new PassThrough();
198
console.log(isTransformStream(passthrough)); // true
199
```
200
201
## Types
202
203
```typescript { .api }
204
/**
205
* Configuration options for stream checking functions
206
*/
207
interface Options {
208
/**
209
* When this option is true, the method returns false if the stream has already been closed.
210
* @default true
211
*/
212
checkOpen?: boolean;
213
}
214
215
/**
216
* Stream types (from Node.js 'node:stream' module)
217
* These are the base types that is-stream can detect
218
*/
219
type Stream = import('node:stream').Stream;
220
type WritableStream = import('node:stream').Writable;
221
type ReadableStream = import('node:stream').Readable;
222
type DuplexStream = import('node:stream').Duplex;
223
type TransformStream = import('node:stream').Transform;
224
```
225
226
## Supported Stream Types
227
228
The library correctly identifies these Node.js stream types:
229
230
- **Core streams**: `Stream.Readable`, `Stream.Writable`, `Stream.Duplex`, `Stream.Transform`, `Stream.PassThrough`
231
- **File streams**: `fs.createReadStream()`, `fs.createWriteStream()`
232
- **HTTP streams**: `http.IncomingMessage`, `http.OutgoingMessage`, `http.ServerResponse`, `http.ClientRequest`
233
- **Network streams**: `net.Socket`
234
- **Custom streams**: Any object implementing the Node.js stream interface
235
236
## Error Handling
237
238
All functions return `false` for:
239
- `null` or `undefined` values
240
- Non-object types (strings, numbers, booleans)
241
- Objects that don't implement the stream interface
242
- Closed streams (when `checkOpen: true`, which is the default)