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.