# 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.