collect/README.md

# @promistream/collect

<!-- 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.__ -->

This is a sink stream that's used to collect the results of a pipeline into a single array.

When its `read` method is called, this stream returns a Promise and then just endlessly reads from its source stream until it receives an `EndOfStream`. Once the source stream ends, the Promise is resolved with an array containing every value that the `collect` stream has received.

## Example

```js
"use strict";

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

return Promise.try(() => {
	return pipe([
		rangeNumbers(0, 20),
		collect()
	]).read();
}).then((result) => {
	console.log(result);
	// [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19 ]
});
```

## API

### collect()

Returns a new collect stream. Takes no arguments.

Stream behaviour:

- __Reads from source:__ Infinitely, until the end of the source stream is reached.
- __Consumes:__ Values of any kind.
- __Produces:__ Returns a Promise when `.read()` is called, that will resolve with accumulated values received from the source stream when its end is reached, or reject when an error of any kind (including an `Aborted` marker) is received from the source stream.
- __Throws:__ Only when an error is received from upstream.
- __Aborts:__ Never.