You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

138 lines
4.4 KiB

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