buffer/README.md

# @promistream/buffer

<!-- FIXME: Uncomment below at 1.0.0 release -->
<!-- __This module is compatible with the [Promistream](https://promistream.cryto.net/) standard, version 1.0.0 - the latest at the time of writing.__ -->

Normally, a Promistream can only return exactly one value. A buffer stream changes this, and allows a stream to return zero-or-more values instead.

You'll probably only need this module if you're implementing a custom (transform) stream of some sort.

How it works: simply place a buffer stream *after* the stream whose results you want to buffer, in the pipeline. It will accept arrays of values from the previous stream, store them internally, and dispense the values *in* those arrays one at a time, whenever the next stream in the pipeline asks for a value.

If the previous stream returns an empty array, the buffer stream will keep requesting new values from the previous stream until it gets either a non-empty array or an `EndOfStream`. This is what allows streams to return zero values.

## Example

In the following example, the `duplicateEven` stream always returns exactly one value at a time, even though the internal `buffer` stream *receives* arrays with two or zero values from the `map` stream before it.

This example also demonstrates how you can create custom streams by piping together existing stream modules.

```js
"use strict";

const Promise = require("bluebird");
const pipe = require("@promistream/pipe");
const rangeNumbers = require("@promistream/range-numbers");
const map = require("@promistream/map");
const buffer = require("@promistream/buffer");
const collect = require("@promistream/collect");

function duplicateEven() {
	return pipe([
		map((value) => {
			if (value % 2 === 0) {
				return [value, value];
			} else {
				return [];
			}
		}),
		buffer()
	]);
}

return Promise.try(() => {
	return pipe([
		rangeNumbers(0, 20),
		duplicateEven(),
		collect()
	]).read();
}).then((result) => {
	console.log(result);
	// [ 0, 0, 2, 2, 4, 4, 6, 6, 8, 8, 10, 10, 12, 12, 14, 14, 16, 16, 18, 18 ]
});
```

## API

### buffer()

Returns a new buffer stream. Takes no arguments.

Stream behaviour:

- __Reads from source:__ Zero or more times, depending on the internal buffer.
- __Consumes:__ An array of zero or more values. This stream will *only* accept arrays; any other values will result in an error.
- __Produces:__ Exactly one value, error, EndOfStream marker, or Aborted marker.
- __Throws:__ When a non-array value is consumed from the previous stream. Upstream errors are rethrown without changes.
- __Aborts:__ Never.