source: trip-planner-front/node_modules/combined-stream/Readme.md@ 571e0df

Last change on this file since 571e0df was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 4.4 KB
Line 
1# combined-stream
2
3A 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
14npm install combined-stream
15```
16
17## Usage
18
19Here is a simple example that shows how you can use combined-stream to combine
20two files into one:
21
22``` javascript
23var CombinedStream = require('combined-stream');
24var fs = require('fs');
25
26var combinedStream = CombinedStream.create();
27combinedStream.append(fs.createReadStream('file1.txt'));
28combinedStream.append(fs.createReadStream('file2.txt'));
29
30combinedStream.pipe(fs.createWriteStream('combined.txt'));
31```
32
33While the example above works great, it will pause all source streams until
34they are needed. If you don't want that to happen, you can set `pauseStreams`
35to `false`:
36
37``` javascript
38var CombinedStream = require('combined-stream');
39var fs = require('fs');
40
41var combinedStream = CombinedStream.create({pauseStreams: false});
42combinedStream.append(fs.createReadStream('file1.txt'));
43combinedStream.append(fs.createReadStream('file2.txt'));
44
45combinedStream.pipe(fs.createWriteStream('combined.txt'));
46```
47
48However, what if you don't have all the source streams yet, or you don't want
49to allocate the resources (file descriptors, memory, etc.) for them right away?
50Well, in that case you can simply provide a callback that supplies the stream
51by calling a `next()` function:
52
53``` javascript
54var CombinedStream = require('combined-stream');
55var fs = require('fs');
56
57var combinedStream = CombinedStream.create();
58combinedStream.append(function(next) {
59 next(fs.createReadStream('file1.txt'));
60});
61combinedStream.append(function(next) {
62 next(fs.createReadStream('file2.txt'));
63});
64
65combinedStream.pipe(fs.createWriteStream('combined.txt'));
66```
67
68## API
69
70### CombinedStream.create([options])
71
72Returns a new combined stream object. Available options are:
73
74* `maxDataSize`
75* `pauseStreams`
76
77The effect of those options is described below.
78
79### combinedStream.pauseStreams = `true`
80
81Whether to apply back pressure to the underlaying streams. If set to `false`,
82the underlaying streams will never be paused. If set to `true`, the
83underlaying 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
88The maximum amount of bytes (or characters) to buffer for all source streams.
89If this value is exceeded, `combinedStream` emits an `'error'` event.
90
91### combinedStream.dataSize = `0`
92
93The amount of bytes (or characters) currently buffered by `combinedStream`.
94
95### combinedStream.append(stream)
96
97Appends the given `stream` to the combinedStream object. If `pauseStreams` is
98set 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`
101is a function that must be invoked in order to provide the `next` stream, see
102example above.
103
104Regardless 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
107Special case: `stream` can also be a String or Buffer.
108
109### combinedStream.write(data)
110
111You should not call this, `combinedStream` takes care of piping the appended
112streams into itself for you.
113
114### combinedStream.resume()
115
116Causes `combinedStream` to start drain the streams it manages. The function is
117idempotent, and also emits a `'resume'` event each time which usually goes to
118the stream that is currently being drained.
119
120### combinedStream.pause();
121
122If `combinedStream.pauseStreams` is set to `false`, this does nothing.
123Otherwise a `'pause'` event is emitted, this goes to the stream that is
124currently being drained, so you can use it to apply back pressure.
125
126### combinedStream.end();
127
128Sets `combinedStream.writable` to false, emits an `'end'` event, and removes
129all streams from the queue.
130
131### combinedStream.destroy();
132
133Same as `combinedStream.end()`, except it emits a `'close'` event instead of
134`'end'`.
135
136## License
137
138combined-stream is licensed under the MIT license.
Note: See TracBrowser for help on using the repository browser.