0
# Pump
1

2
Pump is a small Node.js module that pipes streams together and destroys all of them if one of them closes. It addresses critical issues with Node.js's standard `pipe()` method by automatically destroying all connected streams when any stream in the pipeline closes or errors, and provides a callback mechanism to handle completion or error events.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const pump = require("pump");
15
```
16

17
Note: This package uses CommonJS format and does not provide native ESM exports.
18

19
## Basic Usage
20

21
```javascript
22
const pump = require("pump");
23
const fs = require("fs");
24

25
const source = fs.createReadStream("/dev/random");
26
const dest = fs.createWriteStream("/dev/null");
27

28
pump(source, dest, function(err) {
29
  console.log("pipe finished", err);
30
});
31
```
32

33
## Architecture
34

35
Pump is built around a single core function that:
36

37
- **Stream Pipeline Management**: Creates and manages multi-stream pipelines with proper resource cleanup
38
- **Error Propagation**: Ensures errors from any stream in the pipeline are properly propagated to the callback
39
- **Resource Management**: Automatically destroys all streams when any stream closes, preventing resource leaks
40
- **Special Stream Handling**: Provides optimized cleanup for filesystem streams and HTTP requests
41
- **Callback Interface**: Offers a completion callback that standard `pipe()` lacks
42

43
## Capabilities
44

45
### Stream Piping with Cleanup
46

47
The core functionality that pipes multiple streams together and ensures proper cleanup when any stream closes or errors.
48

49
```javascript { .api }
50
/**
51
 * Pipes streams together and destroys all when one closes
52
 * @param {...(Stream|Function)} streams - Streams to pipe together, with optional callback as last argument
53
 * @returns {Stream} The last stream in the pipeline
54
 * @throws {Error} If fewer than 2 streams are provided
55
 */
56
function pump(...streams): Stream;
57

58
/**
59
 * Alternative signature with array of streams
60
 * @param {Stream[]} streams - Array of streams to pipe together
61
 * @param {Function} [callback] - Optional completion callback
62
 * @returns {Stream} The last stream in the pipeline
63
 */
64
function pump(streams: Stream[], callback?: (err?: Error) => void): Stream;
65

66
/**
67
 * Two-stream signature with callback
68
 * @param {Stream} source - Source stream
69
 * @param {Stream} destination - Destination stream  
70
 * @param {Function} [callback] - Optional completion callback
71
 * @returns {Stream} The destination stream
72
 */
73
function pump(source: Stream, destination: Stream, callback?: (err?: Error) => void): Stream;
74

75
/**
76
 * Multi-stream signature with callback
77
 * @param {Stream} stream1 - First stream
78
 * @param {Stream} stream2 - Second stream
79
 * @param {...Stream} additionalStreams - Additional streams
80
 * @param {Function} [callback] - Optional completion callback
81
 * @returns {Stream} The last stream in the pipeline
82
 */
83
function pump(stream1: Stream, stream2: Stream, ...additionalStreams: (Stream | ((err?: Error) => void))[]): Stream;
84
```
85

86
**Usage Examples:**
87

88
```javascript
89
const pump = require("pump");
90
const fs = require("fs");
91

92
// Basic two-stream piping
93
pump(
94
  fs.createReadStream("input.txt"),
95
  fs.createWriteStream("output.txt"),
96
  function(err) {
97
    if (err) console.error("Pipeline failed:", err);
98
    else console.log("Pipeline succeeded");
99
  }
100
);
101

102
// Multi-stream transformation pipeline
103
const { Transform } = require("stream");
104

105
const upperCase = new Transform({
106
  transform(chunk, encoding, callback) {
107
    callback(null, chunk.toString().toUpperCase());
108
  }
109
});
110

111
const addPrefix = new Transform({
112
  transform(chunk, encoding, callback) {
113
    callback(null, "PREFIX: " + chunk);
114
  }
115
});
116

117
pump(
118
  fs.createReadStream("input.txt"),
119
  upperCase,
120
  addPrefix,
121
  fs.createWriteStream("output.txt"),
122
  function(err) {
123
    console.log("Transformation pipeline finished", err);
124
  }
125
);
126

127
// Using array syntax
128
const streams = [
129
  fs.createReadStream("input.txt"),
130
  upperCase,
131
  fs.createWriteStream("output.txt")
132
];
133

134
const result = pump(streams, function(err) {
135
  console.log("Array pipeline finished", err);
136
});
137

138
// Return value can be used for further chaining
139
console.log(result === streams[streams.length - 1]); // true
140
```
141

142
## Error Handling
143

144
Pump provides comprehensive error handling:
145

146
- **Automatic Cleanup**: When any stream in the pipeline emits an error or closes, all other streams are automatically destroyed
147
- **Callback Errors**: The callback receives the first error that occurred in the pipeline
148
- **Uncaught Exception Prevention**: Pump handles stream errors internally to prevent uncaught exceptions
149
- **Special Stream Support**: 
150
  - Filesystem streams use `.close()` to prevent file descriptor leaks
151
  - HTTP request streams use `.abort()` for proper cleanup
152
  - Standard streams use `.destroy()` for cleanup
153

154
```javascript
155
pump(source, dest, function(err) {
156
  if (err) {
157
    // Error occurred - could be from any stream in the pipeline
158
    console.error("Pipeline failed:", err.message);
159
  } else {
160
    // All streams completed successfully
161
    console.log("Pipeline completed successfully");
162
  }
163
});
164
```
165

166
## Stream Requirements
167

168
Pump works with any Node.js stream that follows the standard stream interface:
169

170
- **Readable streams**: Must emit `'data'`, `'end'`, and `'error'` events
171
- **Writable streams**: Must implement `.write()` and emit `'finish'` and `'error'` events  
172
- **Transform streams**: Must implement both readable and writable interfaces
173
- **Duplex streams**: Must implement both readable and writable interfaces
174

175
## Browser Compatibility
176

177
Pump is browser-compatible when used with browserify or webpack. The filesystem (`fs`) module is automatically stubbed out in browser environments, so filesystem-specific optimizations are disabled but core functionality remains intact.
178

179
## Dependencies
180

181
Pump relies on two external modules:
182

183
- **end-of-stream**: Detects when streams have ended or errored
184
- **once**: Ensures callback functions are called only once