Cispy

The value returned from a take on a channel when that channel is closed and has no more values available.

This is a special value that is returned under a certain circumstance, namely when a take is performed on a closed channel. Because of that, it cannot be returned from a take on an open channel. For that reason, CLOSED is the only value that cannot be put onto a channel — it would be impossible to distinguish between a legitimate value of CLOSED and an actual closed channel.

The name of the channel returned from await alts or sent to the callback in altsAsync when the default is returned as its value.

This only happens when an alts call is performed, all operations are initially blocking, and a default option is sent. The immediate response in that situation is { value: options.default, channel: DEFAULT }.

The value returned from a buffer when it has no values in it.

This is used instead of null because null is a value that can actually be put onto a channel (and therefore into a buffer backing that channel). That means that, despite the assertion that only CLOSED cannot be put onto a channel, it's probably not a great idea to put EMPTY onto an unbuffered channel. While it won't cause an error to be thrown, and while it will be removed from the buffer to allow the next value to be removed, it's likely to cause some odd behavior.

The dispatch method option indicating that a MessageChannel should be used to dispatch tasks.

For environments that don't support MessageChannels, this falls back to SET\_TIMEOUT.

The dispatch method option indicating that setImmediate should be used to dispatch tasks.

This is the default option. For environments that don't support setImmediate, this falls back to MESSAGE\_CHANNEL.

The dispatch method option indicating that setTimeout should be used to dispatch tasks.

This method is always available, but it's also always less efficient than any other method, so it should be used as a last resort.

A set of utility functions for working with channels.

This is a small 'standard library' of promise-based operations that are useful when working with channels.

Completes the first operation among the provided operations that comes available, blocking the process until then.

operations is an array whose elements must be channels or two-element sub-arrays of channels and values, in any combination. An operation that is a channel is a take operation on that channel. An operation that is a two-element array is a put operation on that channel using that value. Exactly one of these operations will complete, and it will be the first operation that unblocks.

This function must be called from within an async function and as part of an await expression.

When alts is completed and its process unblocks, its await expression evaluates to an object of two properties. The value property becomes exactly what would have been returned by the equivalent await put or await take operation: a boolean in the case of a put, or the taken value in the case of a take. The channel property is set to the channel where the operation actually took place. This will be equivalent to the channel in the operations array which completed first, allowing the process to unblock.

If there is more than one operation already available to complete when the call to alts is made, the operation with the highest priority will be the one to complete. Regularly, priority is non-deterministic (i.e., it's set randomly). However, if the options object has a priority value set to true, priority will be assigned in the order of the operations in the supplied array.

If all of the operations must block (i.e., there are no pending puts for take operations, or takes for put operations), a default value may be returned. This is only done if there is a default property in the options object, and the value of that property becomes the value returned by await alts. The channel is set to the special value DEFAULT.

Completes the first operation among the provided operations that comes available, without blocking.

This means that a call to altsAsync does not go into an await expression, and it is not necessary to use it inside a process. Rather than blocking until an operation completes, this one returns immediately and then invokes the callback (if provided) as soon as one of the supplied operations completes. It can be regarded as a non-blocking version of alts.

This function uses an operations list that's identical to the one used by alts. It's an array of values; if a value is a channel, then that operation is a take on that channel, while if it's a two-element array of channel and value, then that operation is a put of that value onto that channel. All options that are available to alts are also available here.

The callback is a function of one parameter, which in this case is an object with value and channel properties.

Creates and returns a new channel.

By default this channel will be a simple unbuffered, untransformed channel, but that can be changed through options. A channel does not have any externally useful functions. It exists largely to be passed into put, take, and alts invocations, along with their non-blocking variations (putAsync, takeAsync, and altsAsync).

If a buffer value is provided, it defines what buffer should back the channel. If this is null, 0, or completely missing, the channel will be unbuffered. If it's a positive number, the channel will be buffered by a FixedBuffer of that size. If it's a Buffer object, that object will be used as the channel's buffer.

chan supports transducers by allowing a transducer function to be associated with it. This is passed as the transducer option and can only be used if the channel is buffered (otherwise an error is thrown). This transducer function must take another transducer as a parameter (allowing transformers to be chained), and it must return an object conforming to the transducer protocol. The transducer functions provided by several libraries meet these requirements.

Errors in the transformation process can be handled by passing an error handler. This is a function that expects to receive an error object as a parameter and can return a value that is then put onto the channel. If this value is CLOSED, then no value will be put onto the channel upon handler completion.

Closes a channel.

Marks a particular channel as closed. A closed channel cannot accept any new puts (put will return false if an attempt is made, and no new value will be on the channel). If it's buffered, it will still provide the values that are already on the channel until all of them are taken, after which any take will return CLOSED.

If there are pending takes on a channel when it's closed, then all takes will immediately return with CLOSED.

Sets one of the dispatcher configuration options.

This is advanced setting for the dispatcher that is responsible for queueing up channel operations and processes. It is likely that this function will never need to be called in normal operation.

If any recognized options are specified in the options object passed to config, then the option is set to the value sent in. Properties that aren't any of these four options are ignored, and any of these options that do not appear in the passed object are left with their current values.

Creates a dropping buffer of the specified capacity.

A dropping buffer silently drops the item being added if the buffer is already at capacity. Since adding a new item will always 'succeed' (even if it succeeds by just ignoring the add), it is never considered full and therefore a put to a channel buffered by a dropping buffer never blocks.

This buffer is able to be passed to chan to create a buffered channel.

Creates a fixed buffer of the specified capacity.

A fixed buffer is a 'normal' buffer, one that stores and returns items on demand. While it is capable of being over-filled, that ability is not used in Cispy. A buffer that is full will cause the next put to its channel to block until at least one item is removed from the buffer.

This buffer is able to be passed to chan to create a buffered channel.

Invokes an async function acting as a process.

This is purely a convenience function, driven by the fact that it's necessary to use an IIFE to invoke an inline async function, and that's not very aesthetically pleasing. It does no more than invoke the passed function, but that at least releases us from the need to put the empty parentheses after the function definition.

Puts a value onto a channel, blocking the process until that value is taken from the channel by a different process (or until the channel closes).

A value is always put onto the channel, but if that value isn't specified by the second parameter, it is undefined. Any value may be put on a channel, with the sole exception of the special value CLOSED.

This function must be called from within an async function and as part of an await expression.

When put is completed and its process unblocks, its await expression evaluates to a status boolean that indicates what caused the process to unblock. That value is true if the put value was successfully taken by another process, or false if the unblocking happened because the target channel closed.

Puts a value onto a channel without blocking.

This means that a call to putAsync does not go into an await expression, and it is not necessary to use it inside a process. Rather than blocking until the put value is taken by another process, this one returns immediately and then invokes the callback (if provided) when the put value is taken. It can be seen as a non-blocking version of put.

While the primary use of this function is to put values onto channels in contexts where being inside a process is impossible (for example, in a DOM element's event handler), it can still be used inside processes at times when it's important to make sure that the process doesn't block from the put.

The callback is a function of one parameter. The parameter that's supplied to the callback is the same as what is supplied to await put: true if the value was taken, or false if the channel was closed. If the callback isn't present, nothing will happen after the value is taken.

Blocks the process for the specified time (in milliseconds) and then unblocks it.

This implements a delay, but one that's superior to other kinds of delays (setTimeout, etc.) because it blocks the process and allows the dispatcher to allow other processes to run while this one waits. The default delay is 0, which will release the process to allow others to run and then immediately re-queue it.

This function must be called from within an async function and as part of an await expression.

When this function completes and its process unblocks, the await expression doesn't take on any meaningful value. The purpose of this function is simply to delay, not to communicate any data.

Creates a sliding buffer of the specified capacity.

A sliding buffer drops the first-added (oldest) item already in the buffer if a new item is added when the buffer is already at capacity. Since it's always capable of having items added to it, it's never considered full, and therefore a put to a channel buffered by a sliding buffer never blocks.

This buffer is able to be passed to chan to create a buffered channel.

Takes a value from a channel, blocking the process until a value becomes available to be taken (or until the channel closes with no more values on it to be taken).

This function must be called from within an async function and as part of an await expression.

When take is completed and its process unblocks, its await expression evaluates to the actual value that was taken. If the target channel closed, then all of the values already placed onto it are resolved by take as normal, and once no more values are available, the special value CLOSED is returned.

Takes a value from a channel, blocking the process until a value becomes available to be taken (or until the channel closes with no more values on it to be taken). If the taken value is an error object, that error is thrown at that point.

This function must be called from within an async function and as part of an await expression.

It functions in every way like take except in the case that the value on the channel is an object that has Error.prototype in its prototype chain (any built-in error, any properly-constructed custom error). If that happens, the error is thrown, which will cause the returned promise to be rejected with the error. It can then be handled up the promise chain like any other rejected promise.

takeOrThrow is roughly equivalent to:

const value = await take(ch);
if (Error.prototype.isPrototypeOf(value)) {
  throw value;
}

Creates a new unbuffered channel that closes after some amount of time.

This channel is able to be used for putting and taking as normal, but it will close after the number of milliseconds in its delay parameter has passed. For that reason it's not really intended to be used for putting and taking. Its primary purpose is to be a channel passed to alts to place a time limit on how long its process will block.