0
# Stream Base Class
1

2
Base class for all streamx streams providing core functionality including lifecycle management, error handling, and event integration.
3

4
## Capabilities
5

6
### Stream Constructor
7

8
Creates a new Stream instance with optional lifecycle hooks.
9

10
```javascript { .api }
11
/**
12
 * Creates a new Stream instance
13
 * @param opts - Configuration options including lifecycle hooks
14
 */
15
class Stream extends EventEmitter {
16
  constructor(opts?: StreamOptions);
17
}
18

19
interface StreamOptions {
20
  /** Function called before first stream operation */
21
  open?: (cb: (error?: Error) => void) => void;
22
  /** Function called during stream destruction */
23
  destroy?: (cb: (error?: Error) => void) => void;
24
}
25
```
26

27
**Usage Example:**
28

29
```javascript
30
const { Stream } = require("@mafintosh/streamx");
31

32
const stream = new Stream({
33
  open(cb) {
34
    console.log("Stream opening");
35
    // Perform initialization
36
    cb(null);
37
  },
38
  destroy(cb) {
39
    console.log("Stream destroying");
40
    // Perform cleanup
41
    cb(null);
42
  }
43
});
44
```
45

46
### Lifecycle Methods
47

48
#### _open Method
49

50
Called once before the first stream operation. Override to implement initialization logic.
51

52
```javascript { .api }
53
/**
54
 * Called before first stream operation for initialization
55
 * @param cb - Callback to call when open is complete
56
 */
57
_open(cb: (error?: Error) => void): void;
58
```
59

60
**Usage Example:**
61

62
```javascript
63
class CustomStream extends Stream {
64
  _open(cb) {
65
    // Initialize resources
66
    this.resource = acquireResource();
67
    cb(null);
68
  }
69
}
70
```
71

72
#### _destroy Method
73

74
Called during stream destruction. Override to implement cleanup logic.
75

76
```javascript { .api }
77
/**
78
 * Called during stream destruction for cleanup
79
 * @param cb - Callback to call when destroy is complete
80
 */
81
_destroy(cb: (error?: Error) => void): void;
82
```
83

84
**Usage Example:**
85

86
```javascript
87
class CustomStream extends Stream {
88
  _destroy(cb) {
89
    // Clean up resources
90
    if (this.resource) {
91
      this.resource.close();
92
    }
93
    cb(null);
94
  }
95
}
96
```
97

98
### Stream Control
99

100
#### destroy Method
101

102
Forcefully destroys the stream, calling _destroy after pending operations complete.
103

104
```javascript { .api }
105
/**
106
 * Forcefully destroy the stream
107
 * @param error - Optional error indicating reason for destruction
108
 */
109
destroy(error?: Error): void;
110
```
111

112
**Usage Example:**
113

114
```javascript
115
const stream = new Stream();
116

117
// Destroy with error
118
stream.destroy(new Error("Something went wrong"));
119

120
// Destroy without error
121
stream.destroy();
122
```
123

124
### Stream State
125

126
#### destroyed Property
127

128
Boolean indicating whether the stream has been destroyed.
129

130
```javascript { .api }
131
/**
132
 * Whether the stream has been destroyed
133
 */
134
get destroyed(): boolean;
135
```
136

137
#### destroying Property
138

139
Boolean indicating whether the stream is currently being destroyed.
140

141
```javascript { .api }
142
/**
143
 * Whether the stream is currently being destroyed
144
 */
145
get destroying(): boolean;
146
```
147

148
**Usage Example:**
149

150
```javascript
151
const stream = new Stream();
152

153
console.log(stream.destroyed);  // false
154
console.log(stream.destroying); // false
155

156
stream.destroy();
157

158
console.log(stream.destroying); // true
159
// Eventually destroyed becomes true
160
```
161

162
#### on Method
163

164
Override of EventEmitter's on method with special stream event handling.
165

166
```javascript { .api }
167
/**
168
 * Add event listener with special stream-specific behavior
169
 * @param name - Event name
170
 * @param fn - Event listener function
171
 * @returns This stream instance
172
 */
173
on(name: string, fn: Function): this;
174
```
175

176
**Special Event Behaviors:**
177
- **`data`** events automatically resume readable streams
178
- **`readable`** events enable readable event emission
179
- **`drain`** events enable drain event emission for writable streams
180

181
### Event Handling
182

183
The Stream class extends EventEmitter and provides special handling for stream-specific events.
184

185
#### Common Events
186

187
- **`close`** - Emitted when the stream is fully closed
188
- **`error`** - Emitted when an error occurs
189

190
**Usage Example:**
191

192
```javascript
193
const stream = new Stream();
194

195
stream.on('close', () => {
196
  console.log('Stream closed');
197
});
198

199
stream.on('error', (err) => {
200
  console.error('Stream error:', err);
201
});
202

203
stream.destroy();
204
```