You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
53 lines
2.8 KiB
Markdown
53 lines
2.8 KiB
Markdown
# through2-buffer
|
|
|
|
A simple `through2` stream that buffers up a certain amount of data before passing anything through.
|
|
|
|
This module generates a simple Transform stream that you can use in any (non-object-mode) pipeline, and that will only do a single thing: buffer up a stream to a certain amount. It's useful for eg. audio/video streams, where you want to have a 'headstart' to prevent underruns if your encoding process stalls for a moment.
|
|
|
|
The `through2-buffer` will start out in __buffering mode__, and keep collecting incoming chunks of data until it hits the configured buffer size. At that moment, it switches to __flowing mode__, outputs the chunks it has collected, and pass through everything that comes afterwards.
|
|
|
|
Once the stream is in flowing mode, it will *never* go back to buffering mode; this is to prevent hiccups in the source stream from causing delayed hiccups in the output. You should make sure that your initial buffer is large enough to cover *all* the hiccups that you will encounter throughout the life of the stream.
|
|
|
|
## License
|
|
|
|
[WTFPL](http://www.wtfpl.net/txt/copying/) or [CC0](https://creativecommons.org/publicdomain/zero/1.0/), whichever you prefer. A donation and/or attribution are appreciated, but not required.
|
|
|
|
## Donate
|
|
|
|
My income consists largely of donations for my projects. If this module is useful to you, consider [making a donation](http://cryto.net/~joepie91/donate.html)!
|
|
|
|
You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else.
|
|
|
|
## Contributing
|
|
|
|
Pull requests welcome. Please make sure your modifications are in line with the overall code style, and ensure that you're editing the files in `src/`, not those in `lib/`.
|
|
|
|
Build tool of choice is `gulp`; simply run `gulp` while developing, and it will watch for changes.
|
|
|
|
Be aware that by making a pull request, you agree to release your modifications under the licenses stated above.
|
|
|
|
## Usage
|
|
|
|
__Please be careful not to require the module as `Buffer` or `buffer`! That would cause confusion with the built-in `Buffer` type in Node.js.__
|
|
|
|
The following example would keep reading data from `/dev/urandom` (and converting it to hexadecimal representation), and buffer 5 MiB of it. After that it will switch into flowing mode and pass everything through to the terminal, *including* the originally buffered data.
|
|
|
|
```javascript
|
|
'use strict';
|
|
|
|
const through2Buffer = require("through2-buffer");
|
|
const fs = require("fs");
|
|
|
|
fs.createReadStream("/dev/urandom", "hex")
|
|
.pipe(streamBuffer(5 * 1024 * 1024)) /* 5 MiB buffer size */
|
|
.pipe(process.stdout);
|
|
```
|
|
|
|
## API
|
|
|
|
### through2Buffer(bufferSize)
|
|
|
|
Creates and returns a new `through2-buffer` stream. Like all Node.js streams, this stream is __single-use__.
|
|
|
|
* __bufferSize__: The amount of bytes to buffer before switching into flowing mode.
|