buddy

node MVC discord bot
Log | Files | Refs | README

Readme.md (4551B)


      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.