rafa/docs/Stream-zip.md

Rafa.js is a Javascript framework for building concurrent applications.

Zip will merge two or more streams and produce a single array containing values
from all streams. Unlike `merge`, which will produce a value for each stream,
`zip` waits until it has a single value from all streams before producing a 
single array of values.

<aside>
```js
var values = [];
var outer = Rafa.stream();
var inner = Rafa.stream();

outer.zip(inner).each(v => values.push(v));

outer.write(1);
// values.length = 0

inner.write(2);
// values[0] = [1, 2]
```
</aside>

Error messages will pass through immediately but still count as a value. Once
all other streams produce a value, the array of values will be pushed with the
index representing the error stream set to undefined.

<aside>
```js
var error, value;
var outer = Rafa.stream();
var inner = Rafa.stream();

outer.zip(inner).each(v => value = v);

outer.write(new Error(1));
// error = Error(1)
// value = undefined

inner.write(2);
// value = [undefined, 2]
```
</aside>

Done messages from streams are converted to normal messages until all streams
produce a done message. Once a stream produces a done message, all future
messages from the other streams will set the done stream's value to null.
Since streams will not typically produce done messages at the same time, 
the final done message produced will be an array with null values set for
streams that have already completed.

<aside>
```js
var values = [], last;
var outer = Rafa.stream();
var inner = Rafa.stream();
outer.zip(inner).each(v => values.push(v)).done(v => last = v);

outer.write(1, true); // done
// values: undefined
// last: undefined

inner.write(2); // not done
// values: [[1, 2]]
// last: undefined

inner.write(3, true); // done
// values: [[1, 2], [null, 3]]
// last: [null, 3]
```
</aside>