327 lines
10 KiB
Markdown
327 lines
10 KiB
Markdown
<!-- TOC -->
|
|
|
|
- [New Properties](#new-properties)
|
|
- [close() -> async](#close---async)
|
|
- [readOnly() -> Channel](#readonly---channel)
|
|
- [writeOnly() -> Channel](#writeonly---channel)
|
|
- [Channel.select(promises) -> async channel](#channelselectpromises---async-channel)
|
|
- [Examples](#examples)
|
|
- [value](#value)
|
|
- [Array-like Properties](#array-like-properties)
|
|
- [Channel](#channel)
|
|
- [Channel([bufferLength = 0]) -> Channel](#channelbufferlength--0---channel)
|
|
- [Channel.isChannel(value) -> Boolean](#channelischannelvalue---boolean)
|
|
- [Channel.of(...values) -> Channel](#channelofvalues---channel)
|
|
- [Channel.from(iterable | stream.Readable) -> Channel](#channelfromiterable--streamreadable---channel)
|
|
- [Channel Object](#channel-object)
|
|
- [every (callbackfn[, thisArg]) -> async Boolean](#every-callbackfn-thisarg---async-boolean)
|
|
- [filter(callbackfn[, thisArg]) -> Channel](#filtercallbackfn-thisarg---channel)
|
|
- [forEach(callbackfn[, thisArg]) -> async](#foreachcallbackfn-thisarg---async)
|
|
- [join(separator) -> async String](#joinseparator---async-string)
|
|
- [map(callbackfn[, thisArg]) -> Channel](#mapcallbackfn-thisarg---channel)
|
|
- [push(value) -> async bufferLength](#pushvalue---async-bufferlength)
|
|
- [reduce(callbackfn[, initialValue])](#reducecallbackfn-initialvalue)
|
|
- [shift() -> async](#shift---async)
|
|
- [slice(start[, end]) -> Channel](#slicestart-end---channel)
|
|
- [some(callbackfn[, thisArg])](#somecallbackfn-thisarg)
|
|
- [Functional API](#functional-api)
|
|
|
|
<!-- /TOC -->
|
|
|
|
# New Properties
|
|
|
|
The following properties don't have equivalents in `Array`.
|
|
|
|
## close() -> async
|
|
|
|
Close the channel so that no more values can be pushed to it. Return a promise
|
|
that resolves when any remaining pushes in flight complete.
|
|
|
|
Attempting to push to a closed channel will throw an exception and shifting from
|
|
a closed channel will immediately return `undefined`.
|
|
|
|
## readOnly() -> Channel
|
|
|
|
Return a version of the channel that provides only read methods.
|
|
|
|
## writeOnly() -> Channel
|
|
|
|
Return a version of the channel that provides only write methods.
|
|
|
|
## Channel.select(promises) -> async channel
|
|
|
|
Wait for the first channel method promise to succeed and then cancel the rest.
|
|
Return the channel of the winning promise.
|
|
|
|
All of the promises can be cancelled before completion by calling `cancel` on
|
|
the promise returned by `select`.
|
|
|
|
### Examples
|
|
|
|
Imagine you're at a party and your next conversation depends on whom you run
|
|
into first: Alice, Bob, or Charlie.
|
|
|
|
```JavaScript
|
|
switch (await Channel.select([
|
|
alice.shift(),
|
|
bob.shift(),
|
|
charlie.push(`Hi!`)
|
|
])) {
|
|
case alice:
|
|
console.log(`Alice said ${alice.value}.`);
|
|
break;
|
|
|
|
case bob:
|
|
console.log(`Bob said ${bob.value}.`);
|
|
break;
|
|
|
|
case charlie:
|
|
console.log(`I said "hi" to Charlie.`);
|
|
break;
|
|
}
|
|
```
|
|
|
|
Be careful of unintended side effects, however. Even though only one value is
|
|
pushed in the following example, the counter is incremented twice.
|
|
|
|
```JavaScript
|
|
let counter = 0;
|
|
|
|
const increment = () => {
|
|
counter++;
|
|
return counter;
|
|
};
|
|
|
|
await Channel.select([alice.push(increment()), bob.push(increment())]);
|
|
assert.equal(counter, 2);
|
|
```
|
|
|
|
Sometimes you don't want to wait until a method completes. You can use a closed
|
|
channel to return immediately even if no other channels are ready:
|
|
|
|
```JavaScript
|
|
const closed = Channel();
|
|
closed.close();
|
|
|
|
switch (await Channel.select([alice.shift(), bob.shift(), closed.shift())]) {
|
|
case alice:
|
|
console.log(`Alice said ${alice.value}.`);
|
|
break;
|
|
|
|
case bob:
|
|
console.log(`Bob said ${bob.value}.`);
|
|
break;
|
|
|
|
default:
|
|
console.log(`No one has anything to say yet.`);
|
|
}
|
|
```
|
|
|
|
You can also arrange it so that the `select` completes within a timeout:
|
|
|
|
```JavaScript
|
|
const timeout = Channel();
|
|
setTimeout(timeout.close, 1000);
|
|
|
|
switch (await Channel.select([alice.shift(), bob.shift(), timeout.shift())]) {
|
|
case alice:
|
|
console.log(`Alice said ${alice.value}.`);
|
|
break;
|
|
|
|
case bob:
|
|
console.log(`Bob said ${bob.value}.`);
|
|
break;
|
|
|
|
default:
|
|
console.log(`I stopped listening after one second.`);
|
|
}
|
|
```
|
|
|
|
## value
|
|
|
|
Set to the most recently `shift`ed value. This is useful when used in
|
|
combination with `select`.
|
|
|
|
# Array-like Properties
|
|
|
|
These methods are similar to the equivalently named methods of `Array`.
|
|
|
|
## Channel
|
|
|
|
### Channel([bufferLength = 0]) -> Channel
|
|
|
|
Create a new `Channel` with an optional buffer. This allows an async function
|
|
to push up to `bufferLength` values before blocking.
|
|
|
|
### Channel.isChannel(value) -> Boolean
|
|
|
|
Return `true` if `value` is a channel, `false` otherwise.
|
|
|
|
### Channel.of(...values) -> Channel
|
|
|
|
Push `values` into a new channel and then close it.
|
|
|
|
### Channel.from(iterable | stream.Readable) -> Channel
|
|
|
|
Create a new `Channel` from an iterable or a [Node.js readable stream](https://nodejs.org/api/stream.html#stream_readable_streams).
|
|
|
|
## Channel Object
|
|
|
|
### every (callbackfn[, thisArg]) -> async Boolean
|
|
|
|
`callbackfn` should be a function that accepts one argument and returns a value
|
|
that is coercible to the Boolean values `true` or `false`. `every` calls
|
|
`callbackfn` once for each value present in the channel until it finds one where
|
|
`callbackfn` returns `false`. If such a value is found, every immediately
|
|
returns `false`. Otherwise, if `callbackfn` returned `true` for all elements,
|
|
`every` will return `true`.
|
|
|
|
If a `thisArg` parameter is provided, it will be used as the `this` value for
|
|
each invocation of `callbackfn`. If it is not provided, `undefined` is used
|
|
instead.
|
|
|
|
Unlike in the Array version of `every`, `callbackfn` is called with only one
|
|
argument.
|
|
|
|
### filter(callbackfn[, thisArg]) -> Channel
|
|
|
|
`callbackfn` should be a function that accepts an argument and returns a value
|
|
that is coercible to the Boolean values `true` or `false`. `filter` calls
|
|
`callbackfn` once for each value in the channel and constructs a new channel of
|
|
all the values for which `callbackfn` returns true.
|
|
|
|
If a `thisArg` parameter is provided, it will be used as the `this` value for
|
|
each invocation of `callbackfn`. If it is not provided, `undefined` is used
|
|
instead.
|
|
|
|
Unlike in the Array version of `filter`, `callbackfn` is called with only one
|
|
argument.
|
|
|
|
### forEach(callbackfn[, thisArg]) -> async
|
|
|
|
The promise returned by `forEach` resolves when the channel is closed:
|
|
|
|
```JavaScript
|
|
const toArray = async channel => {
|
|
const array = [];
|
|
|
|
await channel.forEach(value => {
|
|
array.push(value);
|
|
});
|
|
|
|
return array;
|
|
};
|
|
```
|
|
|
|
If `callbackfn` is async then `forEach` will wait for it before iterating to the
|
|
next value:
|
|
|
|
```JavaScript
|
|
const pipe = async (source, sink) => {
|
|
await source.forEach(sink.push);
|
|
sink.close();
|
|
};
|
|
```
|
|
|
|
### join(separator) -> async String
|
|
|
|
The values of the channel are converted to Strings, and these Strings are then
|
|
concatenated, separated by occurrences of the separator. If no separator is
|
|
provided, a single comma is used as the separator.
|
|
|
|
### map(callbackfn[, thisArg]) -> Channel
|
|
|
|
`callbackfn` should be a function that accepts one argument. `map` calls
|
|
`callbackfn` once for each value in the channel and constructs a new Channel
|
|
from the results.
|
|
|
|
If a `thisArg` parameter is provided, it will be used as the `this` value for
|
|
each invocation of `callbackfn`. If it is not provided, `undefined` is used
|
|
instead.
|
|
|
|
Unlike `Array`'s method, `callbackfn` is called with only one argument.
|
|
|
|
### push(value) -> async bufferLength
|
|
|
|
Send the value into the channel and return a promise that resolves when the
|
|
value has been shifted or placed in the buffer.
|
|
|
|
* Throw a `TypeError` when attempting to push to a closed channel.
|
|
* Throw a `TypeError` when attempting to push `undefined` because it's a
|
|
reserved value used to indicate a closed channel.
|
|
|
|
The push can be cancelled before completion by calling `cancel` on the
|
|
returned promise.
|
|
|
|
Unlike `Array`'s method, accept only one `value` at a time.
|
|
|
|
### reduce(callbackfn[, initialValue])
|
|
|
|
`callbackfn` should be a function that takes two arguments (unlike `Array`'s
|
|
version which takes four). `reduce` calls the callback, as a function, once for
|
|
each value after the first value present in the channel.
|
|
|
|
`callbackfn` is called with two arguments: the `previousValue` (value from the
|
|
previous call to `callbackfn`) and the `currentValue`. The first time that
|
|
callback is called, the `previousValue` and `currentValue` can be one of two
|
|
values. If an `initialValue` was provided in the call to `reduce`, then
|
|
`previousValue` will be equal to `initialValue` and `currentValue` will be equal
|
|
to the first value in the channel. If no `initialValue` was provided, then
|
|
`previousValue` will be equal to the first value in the channel and
|
|
`currentValue` will be equal to the second. It is a `TypeError` if the channel
|
|
contains no values and `initialValue` is not provided.
|
|
|
|
### shift() -> async
|
|
|
|
Return a promise that resolves when an value is received from the channel.
|
|
Closed channels always return `undefined` immediately.
|
|
|
|
The shift can be cancelled before completion by calling `cancel` on the
|
|
returned promise.
|
|
|
|
### slice(start[, end]) -> Channel
|
|
|
|
Return a new channel generated by skipping `start` number of values. If `end`
|
|
is provided then close the new channel after `end` - `start` values have been
|
|
pushed.
|
|
|
|
Unlike in `Array`'s method, `start` and `end` cannot be negative.
|
|
|
|
### some(callbackfn[, thisArg])
|
|
|
|
`callbackfn` should be a function that accepts one argument and returns a value
|
|
that is coercible to the Boolean values `true` or `false`. `some` calls
|
|
`callbackfn` once for each value in the channel until it finds one where
|
|
`callbackfn` returns `true`. If such a value is found, `some` immediately
|
|
returns `true`. Otherwise, `some` returns `false`.
|
|
|
|
If a `thisArg` parameter is provided, it will be used as the `this` value for
|
|
each invocation of `callbackfn`. If it is not provided, `undefined` is used
|
|
instead.
|
|
|
|
Unlike in `Array`'s method, `callbackfn` is called with only one argument.
|
|
|
|
`some` acts like the "exists" quantifier in mathematics. In particular, for an
|
|
empty channel, it returns `false`.
|
|
|
|
# Functional API
|
|
|
|
There is a parallel API to support functional-style programming. Every channel
|
|
method is also available as an independent function in the `Channel` namespace
|
|
that takes a channel as the final argument. For example, `slice` can be called
|
|
in either of the following two ways:
|
|
|
|
```JavaScript
|
|
// method
|
|
channel.slice(10);
|
|
|
|
// function
|
|
Channel.slice(10, Infinity, channel);
|
|
```
|
|
|
|
You can also use partial application:
|
|
|
|
```JavaScript
|
|
Channel.slice(10, Infinity)(channel);
|
|
Channel.slice(10)(Infinity)(channel);
|
|
```
|