1 | # combined-stream
|
2 |
|
3 | A stream that emits multiple other streams one after another.
|
4 |
|
5 | **NB** Currently `combined-stream` works with streams version 1 only. There is ongoing effort to switch this library to streams version 2. Any help is welcome. :) Meanwhile you can explore other libraries that provide streams2 support with more or less compatibility with `combined-stream`.
|
6 |
|
7 | - [combined-stream2](https://www.npmjs.com/package/combined-stream2): A drop-in streams2-compatible replacement for the combined-stream module.
|
8 |
|
9 | - [multistream](https://www.npmjs.com/package/multistream): A stream that emits multiple other streams one after another.
|
10 |
|
11 | ## Installation
|
12 |
|
13 | ``` bash
|
14 | npm install combined-stream
|
15 | ```
|
16 |
|
17 | ## Usage
|
18 |
|
19 | Here is a simple example that shows how you can use combined-stream to combine
|
20 | two files into one:
|
21 |
|
22 | ``` javascript
|
23 | var CombinedStream = require('combined-stream');
|
24 | var fs = require('fs');
|
25 |
|
26 | var combinedStream = CombinedStream.create();
|
27 | combinedStream.append(fs.createReadStream('file1.txt'));
|
28 | combinedStream.append(fs.createReadStream('file2.txt'));
|
29 |
|
30 | combinedStream.pipe(fs.createWriteStream('combined.txt'));
|
31 | ```
|
32 |
|
33 | While the example above works great, it will pause all source streams until
|
34 | they are needed. If you don't want that to happen, you can set `pauseStreams`
|
35 | to `false`:
|
36 |
|
37 | ``` javascript
|
38 | var CombinedStream = require('combined-stream');
|
39 | var fs = require('fs');
|
40 |
|
41 | var combinedStream = CombinedStream.create({pauseStreams: false});
|
42 | combinedStream.append(fs.createReadStream('file1.txt'));
|
43 | combinedStream.append(fs.createReadStream('file2.txt'));
|
44 |
|
45 | combinedStream.pipe(fs.createWriteStream('combined.txt'));
|
46 | ```
|
47 |
|
48 | However, what if you don't have all the source streams yet, or you don't want
|
49 | to allocate the resources (file descriptors, memory, etc.) for them right away?
|
50 | Well, in that case you can simply provide a callback that supplies the stream
|
51 | by calling a `next()` function:
|
52 |
|
53 | ``` javascript
|
54 | var CombinedStream = require('combined-stream');
|
55 | var fs = require('fs');
|
56 |
|
57 | var combinedStream = CombinedStream.create();
|
58 | combinedStream.append(function(next) {
|
59 | next(fs.createReadStream('file1.txt'));
|
60 | });
|
61 | combinedStream.append(function(next) {
|
62 | next(fs.createReadStream('file2.txt'));
|
63 | });
|
64 |
|
65 | combinedStream.pipe(fs.createWriteStream('combined.txt'));
|
66 | ```
|
67 |
|
68 | ## API
|
69 |
|
70 | ### CombinedStream.create([options])
|
71 |
|
72 | Returns a new combined stream object. Available options are:
|
73 |
|
74 | * `maxDataSize`
|
75 | * `pauseStreams`
|
76 |
|
77 | The effect of those options is described below.
|
78 |
|
79 | ### combinedStream.pauseStreams = `true`
|
80 |
|
81 | Whether to apply back pressure to the underlaying streams. If set to `false`,
|
82 | the underlaying streams will never be paused. If set to `true`, the
|
83 | underlaying streams will be paused right after being appended, as well as when
|
84 | `delayedStream.pipe()` wants to throttle.
|
85 |
|
86 | ### combinedStream.maxDataSize = `2 * 1024 * 1024`
|
87 |
|
88 | The maximum amount of bytes (or characters) to buffer for all source streams.
|
89 | If this value is exceeded, `combinedStream` emits an `'error'` event.
|
90 |
|
91 | ### combinedStream.dataSize = `0`
|
92 |
|
93 | The amount of bytes (or characters) currently buffered by `combinedStream`.
|
94 |
|
95 | ### combinedStream.append(stream)
|
96 |
|
97 | Appends the given `stream` to the combinedStream object. If `pauseStreams` is
|
98 | set to `true, this stream will also be paused right away.
|
99 |
|
100 | `streams` can also be a function that takes one parameter called `next`. `next`
|
101 | is a function that must be invoked in order to provide the `next` stream, see
|
102 | example above.
|
103 |
|
104 | Regardless of how the `stream` is appended, combined-stream always attaches an
|
105 | `'error'` listener to it, so you don't have to do that manually.
|
106 |
|
107 | Special case: `stream` can also be a String or Buffer.
|
108 |
|
109 | ### combinedStream.write(data)
|
110 |
|
111 | You should not call this, `combinedStream` takes care of piping the appended
|
112 | streams into itself for you.
|
113 |
|
114 | ### combinedStream.resume()
|
115 |
|
116 | Causes `combinedStream` to start drain the streams it manages. The function is
|
117 | idempotent, and also emits a `'resume'` event each time which usually goes to
|
118 | the stream that is currently being drained.
|
119 |
|
120 | ### combinedStream.pause();
|
121 |
|
122 | If `combinedStream.pauseStreams` is set to `false`, this does nothing.
|
123 | Otherwise a `'pause'` event is emitted, this goes to the stream that is
|
124 | currently being drained, so you can use it to apply back pressure.
|
125 |
|
126 | ### combinedStream.end();
|
127 |
|
128 | Sets `combinedStream.writable` to false, emits an `'end'` event, and removes
|
129 | all streams from the queue.
|
130 |
|
131 | ### combinedStream.destroy();
|
132 |
|
133 | Same as `combinedStream.end()`, except it emits a `'close'` event instead of
|
134 | `'end'`.
|
135 |
|
136 | ## License
|
137 |
|
138 | combined-stream is licensed under the MIT license.
|