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)