@thi.ng/csp 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-04-25T19:44:55Z
+- **Last updated**: 2024-04-28T14:28:17Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,27 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [3.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/csp@3.2.0) (2024-04-28)
+
+#### 🚀 Features
+
+- update Mult/PubSub unsub handling, add docs ([32ad70e](https://github.com/thi-ng/umbrella/commit/32ad70e))
+  - add optional auto-closing for Mult.unsubscribe(), PubSub.unsubscribeTopic()
+  - add docs
+
+#### 🩹 Bug fixes
+
+- update select() ([5e87c8d](https://github.com/thi-ng/umbrella/commit/5e87c8d))
+  - update select(), ensure write queue of selected channel is being updated
+  - mark Channel.updateQueue() as internal
+
+## [3.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/csp@3.1.0) (2024-04-26)
+
+#### 🚀 Features
+
+- add opt. generics for PubSub.subscribe()/unsubscribe() ([b4e9d20](https://github.com/thi-ng/umbrella/commit/b4e9d20))
+- add into() to feed (async) iterables into a channel ([c7c1f6d](https://github.com/thi-ng/umbrella/commit/c7c1f6d))
+
 # [3.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/csp@3.0.0) (2024-04-25)
 
 #### 🛑 Breaking changes

package/README.md

@@ -15,11 +15,18 @@
 > GitHub](https://github.com/sponsors/postspectacular). Thank you! ❤️
 
 - [About](#about)
+  - [What is CSP?](#what-is-csp)
+  - [Buffering behaviors](#buffering-behaviors)
+  - [Channels](#channels)
+  - [Other channel types](#other-channel-types)
+  - [Channel operators](#channel-operators)
 - [Status](#status)
 - [Related packages](#related-packages)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
+- [Usage examples](#usage-examples)
 - [API](#api)
+  - [Ping pong](#ping-pong)
   - [PubSub](#pubsub)
 - [Authors](#authors)
 - [License](#license)
@@ -29,25 +36,88 @@
 Primitives & operators for Communicating Sequential Processes based on async/await and async iterables.
 
 This package was temporarily deprecated (throughout most of 2023), but meanwhile
-has been reanimated in the form of a **complete rewrite**, using a new, more
+has been **reanimated in the form of a complete rewrite**, using a new, more
 simple and more modern approach afforded by contemporary ES language features
 (and widespread support for them).
 
 **This new/current implementation is in most cases NOT compatible with earlier
 versions**.
 
-Provided are:
+### What is CSP?
+
+References:
+
+- [Wikipedia](https://en.wikipedia.org/wiki/Communicating_sequential_processes)
+- [Communicating Sequential Processes, C.A.R.
+Hoare](https://dl.acm.org/doi/pdf/10.1145/359576.359585)
+
+The key construct of this package is a read/write channel primitive which can be
+customized with different buffer implementations to control blocking behaviors
+and backpressure handling (aka attempting to write faster to a channel than
+values are being read, essentially a memory management issue). Unbuffered CSP
+channels are blocking on both the reader and writer side.
+
+### Buffering behaviors
+
+The following channel buffer types/behaviors are included (from the
+[thi.ng/buffers](https://github.com/thi-ng/umbrella/tree/develop/packages/buffers)
+package), all accepting a max. capacity and all implementing the
+[IReadWriteBuffer](https://docs.thi.ng/umbrella/buffers/interfaces/IReadWriteBuffer.html)
+interface required by the channel:
+
+- [`fifo`](https://docs.thi.ng/umbrella/buffers/functions/fifo.html): First in,
+  first out ring buffer. Writes to the channel will start blocking once the
+  buffer's capacity is reached, otherwise complete immediately. Likewise,
+  channel reads are non-blocking whilst there're more buffered values available.
+  Reads will only block if the buffer is empty.
+- [`lifo`](https://docs.thi.ng/umbrella/buffers/functions/lifo.html): Last in,
+  first out. Write behavior is the same as with `fifo`, reads are in reverse
+  order (as the name indicates), i.e. the last value written will be the first
+  value read (i.e. stack behavior).
+- [`sliding`](https://docs.thi.ng/umbrella/buffers/functions/sliding.html):
+  Sliding window ring buffer. Writes to the channel are **never** blocking!
+  Whilst the buffer is at full capacity, new writes will first expunge the
+  oldest buffered value (similar to [LRU
+  cache](https://github.com/thi-ng/umbrella/blob/develop/packages/cache/README.md#lru)
+  behavior). Read behavior is the same as for `fifo`.
+- [`dropping`](https://docs.thi.ng/umbrella/buffers/functions/dropping.html):
+  Dropping value ring buffer. Writes to the channel are **never** blocking!
+  Whilst the buffer is at full capacity, new writes will be silently ignored.
+  Read behavior is the same as for `fifo`.
+
+### Channels
+
+As mentioned previously,
+[channels](https://docs.thi.ng/umbrella/csp/functions/channel.html) and their
+[read](https://docs.thi.ng/umbrella/csp/classes/Channel.html#read),
+[write](https://docs.thi.ng/umbrella/csp/classes/Channel.html#write) and
+[close](https://docs.thi.ng/umbrella/csp/classes/Channel.html#close) operations
+are the key building blocks for CSP.
+
+### Other channel types
 
-- [CSP `Channel`
-  primitive](https://docs.thi.ng/umbrella/csp/classes/Channel.html) supporting a
-  choice of buffer behaviors (fifo, sliding, dropping, see
-  [thi.ng/buffers](https://github.com/thi-ng/umbrella/blob/develop/packages/buffers)
-  for options)
-- Composable channel operators (see list below)
 - [`Mult`](https://docs.thi.ng/umbrella/csp/classes/Mult.html) for channel
-  multiplexing (one-to-many splitting) and dynamic add/removal of subscribers
+  multiplexing (aka one-to-many splitting) and dynamic add/removal of
+  subscribers
 - [`PubSub`](https://docs.thi.ng/umbrella/csp/classes/PubSub.html) for
-  topic-based subscriptions, each topic implemented as `Mult`
+  topic-based subscriptions, each topic implemented as a `Mult`
+
+### Channel operators
+
+- [`broadcast()`](https://docs.thi.ng/umbrella/csp/functions/broadcast.html)
+- [`channel()`](https://docs.thi.ng/umbrella/csp/functions/channel.html)
+- [`concat()`](https://docs.thi.ng/umbrella/csp/functions/concat.html)
+- [`consume()`](https://docs.thi.ng/umbrella/csp/functions/consume.html)
+- [`consumeWith()`](https://docs.thi.ng/umbrella/csp/functions/consumeWith.html)
+- [`drain()`](https://docs.thi.ng/umbrella/csp/functions/drain.html)
+- [`fromAsyncIterable()`](https://docs.thi.ng/umbrella/csp/functions/fromAsyncIterable.html)
+- [`into()`](https://docs.thi.ng/umbrella/csp/functions/into.html)
+- [`merge()`](https://docs.thi.ng/umbrella/csp/functions/merge.html)
+- [`mult()`](https://docs.thi.ng/umbrella/csp/functions/mult.html)
+- [`pipe()`](https://docs.thi.ng/umbrella/csp/functions/pipe.html)
+- [`pubsub()`](https://docs.thi.ng/umbrella/csp/functions/pubsub.html)
+- [`select()`](https://docs.thi.ng/umbrella/csp/functions/select.html)
+- [`timeout()`](https://docs.thi.ng/umbrella/csp/functions/timeout.html)
 
 ## Status
 
@@ -87,7 +157,7 @@ For Node.js REPL:
 const csp = await import("@thi.ng/csp");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.77 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.79 KB
 
 ## Dependencies
 
@@ -96,14 +166,80 @@ Package sizes (brotli'd, pre-treeshake): ESM: 1.77 KB
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
 
+## Usage examples
+
+One project in this repo's
+[/examples](https://github.com/thi-ng/umbrella/tree/develop/examples)
+directory is using this package:
+
+| Screenshot                                                                                                     | Description                                                                  | Live demo                                     | Source                                                                     |
+|:---------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------|:----------------------------------------------|:---------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/csp-bus.png" width="240"/> | CSP channel-based event handling, async transducers & reactive UI components | [Demo](https://demo.thi.ng/umbrella/csp-bus/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/csp-bus) |
+
 ## API
 
 [Generated API docs](https://docs.thi.ng/umbrella/csp/)
 
+### Ping pong
+
+```ts tangle:export/readme-pingpong.ts
+import { channel } from "@thi.ng/csp";
+
+// create CSP channel for bi-directional communication
+const chan = channel<number>();
+
+// create first async process (ping)
+(async () => {
+    while (true) {
+        // this op will block until a value becomes available in the channel
+        const x = await chan.read();
+        // if the channel was closed meanwhile, read() will deliver `undefined`
+        if (x === undefined || x > 5) {
+            console.log("stopping...");
+            // calling close() is idempotent
+            // any in-flight writes will still be readable
+            chan.close();
+            break;
+        }
+        console.log("ping", x);
+        // this op will also block until the other side is reading the value
+        await chan.write(x + 1);
+    }
+    console.log("ping done");
+})();
+
+// create second async process (pong, almost identical to ping)
+(async () => {
+    while (true) {
+        // wait until value can be read (or channel closed)
+        const x = await chan.read();
+        // exit loop if channel closed
+        if (x === undefined) break;
+        console.log("pong", x);
+        // write next value & wait until other side read it
+        await chan.write(x + 1);
+    }
+    console.log("pong done");
+})();
+
+// kickoff
+chan.write(0);
+
+// ping 0
+// pong 1
+// ping 2
+// pong 3
+// ping 4
+// pong 5
+// stopping...
+// ping done
+// pong done
+```
+
 ### PubSub
 
 ```ts tangle:export/readme-pubsub.ts
-import { channel, consumeWith, pubsub } from "@thi.ng/csp";
+import { channel, consumeWith, into, pubsub } from "@thi.ng/csp";
 
 // input channel (optional)
 const src = channel<string>({ id: "users" });
@@ -120,10 +256,9 @@ for (let i of "abc") {
     consumeWith(pub.subscribeTopic(i), (x, ch) => console.log(ch.id, x));
 }
 
-// start processing
-for (let x of ["alice", "bert", "bella", "charlie", "arthur"]) {
-    await src.write(x);
-}
+// start processing by feeding an iterable of names
+await into(src, ["alice", "bert", "bella", "charlie", "arthur"]);
+
 // users-a-tap0 alice
 // users-b-tap1 bert
 // users-b-tap1 bella

package/channel.d.ts

@@ -1,10 +1,17 @@
 import type { Fn, Maybe } from "@thi.ng/api";
 import type { ChannelBuffer, ChannelValue, IChannel } from "./api.js";
 export declare const MAX_READS = 1024;
-export declare const MAX_QUEUE = 1024;
+export declare const MAX_WRITES = 1024;
 export interface ChannelOpts {
     id: string;
 }
+/**
+ * Syntax sugar for creating a new CSP {@link Channel}. By default, the channel
+ * has a buffer capacity of 1 value, but supports custom buffer sizes and/or
+ * implementations (described in readme).
+ *
+ * @param opts
+ */
 export declare function channel<T>(opts?: Partial<ChannelOpts>): Channel<T>;
 export declare function channel<T>(buf: ChannelBuffer<T> | number, opts?: Partial<ChannelOpts>): Channel<T>;
 export declare class Channel<T> implements IChannel<T> {
@@ -14,14 +21,119 @@ export declare class Channel<T> implements IChannel<T> {
     reads: Fn<Maybe<T>, void>[];
     races: Fn<Channel<T>, void>[];
     protected state: number;
+    /**
+     * See {@link channel} for reference.
+     *
+     * @param opts
+     */
     constructor(opts?: Partial<ChannelOpts>);
     constructor(buf: ChannelBuffer<T> | number, opts?: Partial<ChannelOpts>);
+    /**
+     * Returns an async iterator of this channel, acting as adapter between the
+     * CSP world and the more generic ES async iterables. The iterator stops
+     * once the channel has been closed and no further values can be read.
+     *
+     * @remarks
+     * Multiple iterators will compete for new values. To ensure an iterator
+     * receives all of the channel's values, you must either ensure there's only
+     * a single iterator per channel or feed the channel into a {@link mult}
+     * first and create an iterator of a channel obtained via
+     * {@link Mult.subscribe}.
+     *
+     * @example
+     * ```ts tangle:../export/channel-iterator.ts
+     * import { channel } from "@thi.ng/csp";
+     *
+     * const chan = channel<number>();
+     *
+     * (async () => {
+     *   // implicit iterator conversion of the channel
+     *   for await(let x of chan) console.log("received", x);
+     *   console.log("channel closed");
+     * })()
+     *
+     * chan.write(1);
+     * chan.write(2);
+     * chan.write(3);
+     * chan.close();
+     * ```
+     */
     [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+    /**
+     * Attempts to read a value from the channel. The returned promise will
+     * block until such value becomes available or if the channel has been
+     * closed in the meantime. In that latter case, the promise will resolve to
+     * `undefined`.
+     *
+     * @remarks
+     * If a value is already available at the time of the function call, the
+     * promise resolves immediately.
+     *
+     * Note: There's a limit of in-flight {@link MAX_READS} allowed per channel.
+     * The promise will reject if that number is exceeded.
+     *
+     * Also see {@link Channel.poll}.
+     */
     read(): Promise<Maybe<T>>;
+    /**
+     * Similar to {@link Channel.read}, but not async and non-blocking. Will
+     * only succeed if the channel is readable (i.e. not yet closed) and if a
+     * value can be read immediately (without waiting). Returns the value or
+     * `undefined` if unsuccessful.
+     *
+     * @remarks
+     * Use {@link Channel.closed} to check if the channel is already closed.
+     */
     poll(): Maybe<T>;
+    /**
+     * Attempts to write a new value to the channel and returns a promise
+     * indicating success or failure. Depending on buffer capacity & behavior,
+     * the returned promise will block until the channel accept new values (i.e.
+     * until the next {@link Channel.read}) or if it has been closed in the
+     * meantime. In that latter case, the promise will resolve to false.
+     *
+     * @remarks
+     * If the channel's buffer accepts new writes or if a read op is already
+     * waiting at the time of the function call, the promise resolves
+     * immediately.
+     *
+     * If the buffer is already full, the write will be queued and only resolve
+     * when delivered. Note: As a fail-safe, there's a limit of queued
+     * {@link MAX_WRITES} allowed per channel. The promise will reject if that
+     * number is exceeded.
+     *
+     * Also see {@link Channel.offer}.
+     */
     write(msg: T): Promise<boolean>;
+    /**
+     * Similar to {@link Channel.write}, but not async and non-blocking. Will
+     * only succeed if the channel is writable (i.e. not yet closed/closing) and
+     * if a write is immediately possible (without queuing). Returns true, if
+     * successful.
+     *
+     * @param msg
+     */
     offer(msg: T): boolean;
+    /**
+     * Queues a "race" operation & returns a promise which resolves with the
+     * channel itself when the channel becomes readable, but no other queued
+     * read operations are waiting (which always have priority). If the channel
+     * is already closed, the promise resolves immediately.
+     *
+     * @remarks
+     * This op is used internally by {@link select} to choose a channel to read
+     * from next.
+     */
     race(): Promise<Channel<T>>;
+    /**
+     * Triggers closing of the channel (idempotent). Any queued writes remain
+     * readable, but new writes will be ignored.
+     *
+     * @remarks
+     * Whilst there're still values available for reading,
+     * {@link Channel.closed} will still return false since the channel state is
+     * still "closing", not yet fully "closed".
+     */
     close(): void;
     /**
      * Returns true if the channel is principally readable (i.e. not yet
@@ -38,9 +150,15 @@ export declare class Channel<T> implements IChannel<T> {
     /**
      * Returns true if the channel is fully closed and no further reads or
      * writes are possible.
+     *
+     * @remarks
+     * Whilst there're still values available for reading, this will still
+     * return false since the channel state is still "closing", not yet fully
+     * "closed".
      */
     closed(): boolean;
+    /** @internal */
+    updateQueue(): void;
     protected deliver(): void;
-    protected updateQueue(): void;
 }
 //# sourceMappingURL=channel.d.ts.map

package/channel.js

@@ -4,7 +4,7 @@ import { isPlainObject } from "@thi.ng/checks/is-plain-object";
 import { illegalState } from "@thi.ng/errors/illegal-state";
 import { __nextID } from "./idgen.js";
 const MAX_READS = 1024;
-const MAX_QUEUE = 1024;
+const MAX_WRITES = 1024;
 const STATE_OPEN = 0;
 const STATE_CLOSING = 1;
 const STATE_CLOSED = 2;
@@ -35,6 +35,36 @@ class Channel {
     this.writes = isNumber(buf) ? fifo(buf) : buf;
     this.id = opts?.id ?? `chan-${__nextID()}`;
   }
+  /**
+   * Returns an async iterator of this channel, acting as adapter between the
+   * CSP world and the more generic ES async iterables. The iterator stops
+   * once the channel has been closed and no further values can be read.
+   *
+   * @remarks
+   * Multiple iterators will compete for new values. To ensure an iterator
+   * receives all of the channel's values, you must either ensure there's only
+   * a single iterator per channel or feed the channel into a {@link mult}
+   * first and create an iterator of a channel obtained via
+   * {@link Mult.subscribe}.
+   *
+   * @example
+   * ```ts tangle:../export/channel-iterator.ts
+   * import { channel } from "@thi.ng/csp";
+   *
+   * const chan = channel<number>();
+   *
+   * (async () => {
+   *   // implicit iterator conversion of the channel
+   *   for await(let x of chan) console.log("received", x);
+   *   console.log("channel closed");
+   * })()
+   *
+   * chan.write(1);
+   * chan.write(2);
+   * chan.write(3);
+   * chan.close();
+   * ```
+   */
   async *[Symbol.asyncIterator]() {
     while (this.state < STATE_CLOSED) {
       const x = await this.read();
@@ -42,6 +72,21 @@ class Channel {
         yield x;
     }
   }
+  /**
+   * Attempts to read a value from the channel. The returned promise will
+   * block until such value becomes available or if the channel has been
+   * closed in the meantime. In that latter case, the promise will resolve to
+   * `undefined`.
+   *
+   * @remarks
+   * If a value is already available at the time of the function call, the
+   * promise resolves immediately.
+   *
+   * Note: There's a limit of in-flight {@link MAX_READS} allowed per channel.
+   * The promise will reject if that number is exceeded.
+   *
+   * Also see {@link Channel.poll}.
+   */
   read() {
     return new Promise((resolve) => {
       if (!this.readable()) {
@@ -59,6 +104,15 @@ class Channel {
         this.deliver();
     });
   }
+  /**
+   * Similar to {@link Channel.read}, but not async and non-blocking. Will
+   * only succeed if the channel is readable (i.e. not yet closed) and if a
+   * value can be read immediately (without waiting). Returns the value or
+   * `undefined` if unsuccessful.
+   *
+   * @remarks
+   * Use {@link Channel.closed} to check if the channel is already closed.
+   */
   poll() {
     const { reads, writes } = this;
     if (this.readable() && !reads.length && writes.readable()) {
@@ -68,6 +122,25 @@ class Channel {
       return msg;
     }
   }
+  /**
+   * Attempts to write a new value to the channel and returns a promise
+   * indicating success or failure. Depending on buffer capacity & behavior,
+   * the returned promise will block until the channel accept new values (i.e.
+   * until the next {@link Channel.read}) or if it has been closed in the
+   * meantime. In that latter case, the promise will resolve to false.
+   *
+   * @remarks
+   * If the channel's buffer accepts new writes or if a read op is already
+   * waiting at the time of the function call, the promise resolves
+   * immediately.
+   *
+   * If the buffer is already full, the write will be queued and only resolve
+   * when delivered. Note: As a fail-safe, there's a limit of queued
+   * {@link MAX_WRITES} allowed per channel. The promise will reject if that
+   * number is exceeded.
+   *
+   * Also see {@link Channel.offer}.
+   */
   write(msg) {
     return new Promise((resolve) => {
       if (!this.writable()) {
@@ -77,7 +150,7 @@ class Channel {
       const { reads, writes, races, queue } = this;
       const val = [msg, resolve];
       if (!(writes.writable() && writes.write(val))) {
-        queue.length < MAX_QUEUE ? queue.push(val) : illegalState(
+        queue.length < MAX_WRITES ? queue.push(val) : illegalState(
           "max. queue capacity reached, reduce back pressure!"
         );
       }
@@ -88,6 +161,14 @@ class Channel {
       }
     });
   }
+  /**
+   * Similar to {@link Channel.write}, but not async and non-blocking. Will
+   * only succeed if the channel is writable (i.e. not yet closed/closing) and
+   * if a write is immediately possible (without queuing). Returns true, if
+   * successful.
+   *
+   * @param msg
+   */
   offer(msg) {
     if (this.writable() && this.writes.writable()) {
       this.write(msg);
@@ -95,6 +176,16 @@ class Channel {
     }
     return false;
   }
+  /**
+   * Queues a "race" operation & returns a promise which resolves with the
+   * channel itself when the channel becomes readable, but no other queued
+   * read operations are waiting (which always have priority). If the channel
+   * is already closed, the promise resolves immediately.
+   *
+   * @remarks
+   * This op is used internally by {@link select} to choose a channel to read
+   * from next.
+   */
   race() {
     return new Promise((resolve) => {
       if (!this.readable()) {
@@ -107,6 +198,15 @@ class Channel {
       }
     });
   }
+  /**
+   * Triggers closing of the channel (idempotent). Any queued writes remain
+   * readable, but new writes will be ignored.
+   *
+   * @remarks
+   * Whilst there're still values available for reading,
+   * {@link Channel.closed} will still return false since the channel state is
+   * still "closing", not yet fully "closed".
+   */
   close() {
     if (this.state >= STATE_CLOSING)
       return;
@@ -141,17 +241,16 @@ class Channel {
   /**
    * Returns true if the channel is fully closed and no further reads or
    * writes are possible.
+   *
+   * @remarks
+   * Whilst there're still values available for reading, this will still
+   * return false since the channel state is still "closing", not yet fully
+   * "closed".
    */
   closed() {
     return this.state === STATE_CLOSED;
   }
-  deliver() {
-    const { reads, writes } = this;
-    const [msg, write] = writes.read();
-    write(true);
-    reads.shift()(msg);
-    this.updateQueue();
-  }
+  /** @internal */
   updateQueue() {
     const { queue, writes } = this;
     if (queue.length && writes.writable()) {
@@ -161,10 +260,17 @@ class Channel {
       this.state = STATE_CLOSED;
     }
   }
+  deliver() {
+    const { reads, writes } = this;
+    const [msg, write] = writes.read();
+    write(true);
+    reads.shift()(msg);
+    this.updateQueue();
+  }
 }
 export {
   Channel,
-  MAX_QUEUE,
   MAX_READS,
+  MAX_WRITES,
   channel
 };

package/mult.d.ts

@@ -1,16 +1,63 @@
 import type { IClosable, IWriteable } from "./api.js";
 import { Channel } from "./channel.js";
+/**
+ * Syntax sugar for {@link Mult} ctor. Creates a new `Mult` which allows
+ * multiple child subscriptions, each receiving the same values written to (or
+ * received by) the Mult itself, i.e. it acts as a channel splitter, supporting
+ * dynamic subscriptions and unsubscriptions.
+ *
+ * @remarks
+ * If `src` is a channel, it will be used as input. If given a string, a new
+ * channel with the given ID will be created (for receiving values).
+ *
+ * @param arg
+ */
 export declare const mult: <T>(arg?: string | Channel<T>) => Mult<T>;
 export declare class Mult<T> implements IWriteable<T>, IClosable {
     protected src: Channel<any>;
     protected taps: Channel<any>[];
+    /**
+     * See {@link mult} for reference.
+     *
+     * @param arg
+     */
     constructor(arg?: string | Channel<T>);
     writable(): boolean;
     write(val: T): Promise<boolean>;
     close(): void;
     closed(): boolean;
+    /**
+     * Attaches (and possibly creates) a new subscription channel to receive any
+     * values received by the `Mult` itself. Returns it.
+     *
+     * @remarks
+     * The channel can later be detached again via {@link Mult.unsubscribe}.
+     *
+     * @param ch
+     */
     subscribe(ch?: Channel<T>): Channel<T>;
-    unsubscribe(ch: Channel<T>): boolean;
+    /**
+     * Attempts to remove given subscription channel. Returns true if
+     * successful. If `close` is true (default), the given channel will also be
+     * closed (only if unsubscription was successful).
+     *
+     * @remarks
+     * See {@link Mult.subscribe} for reverse op.
+     *
+     * @param ch
+     * @param close
+     */
+    unsubscribe(ch: Channel<T>, close?: boolean): boolean;
+    /**
+     * Removes all child subscription channels and if `close` is true (default)
+     * also closes them.
+     *
+     * @remarks
+     * The `Mult` itself will remain active and will continue to accept new
+     * subscriptions.
+     *
+     * @param close
+     */
     unsubscribeAll(close?: boolean): void;
     protected process(): Promise<void>;
 }

package/mult.js

@@ -4,6 +4,11 @@ const mult = (arg) => new Mult(arg);
 class Mult {
   src;
   taps = [];
+  /**
+   * See {@link mult} for reference.
+   *
+   * @param arg
+   */
   constructor(arg) {
     let id, src;
     if (typeof arg === "string") {
@@ -26,6 +31,15 @@ class Mult {
   closed() {
     return this.src.closed();
   }
+  /**
+   * Attaches (and possibly creates) a new subscription channel to receive any
+   * values received by the `Mult` itself. Returns it.
+   *
+   * @remarks
+   * The channel can later be detached again via {@link Mult.unsubscribe}.
+   *
+   * @param ch
+   */
   subscribe(ch) {
     if (!ch) {
       ch = new Channel({
@@ -37,14 +51,36 @@ class Mult {
     this.taps.push(ch);
     return ch;
   }
-  unsubscribe(ch) {
+  /**
+   * Attempts to remove given subscription channel. Returns true if
+   * successful. If `close` is true (default), the given channel will also be
+   * closed (only if unsubscription was successful).
+   *
+   * @remarks
+   * See {@link Mult.subscribe} for reverse op.
+   *
+   * @param ch
+   * @param close
+   */
+  unsubscribe(ch, close = true) {
     const idx = this.taps.indexOf(ch);
     if (idx >= 0) {
       this.taps.splice(idx, 1);
+      close && ch.close();
       return true;
     }
     return false;
   }
+  /**
+   * Removes all child subscription channels and if `close` is true (default)
+   * also closes them.
+   *
+   * @remarks
+   * The `Mult` itself will remain active and will continue to accept new
+   * subscriptions.
+   *
+   * @param close
+   */
   unsubscribeAll(close = true) {
     if (close) {
       for (let t of this.taps)

package/ops.d.ts

@@ -4,8 +4,8 @@ import { Channel } from "./channel.js";
 export declare const broadcast: <T>(src: Channel<T>, dest: Channel<T>[], close?: boolean) => Promise<void>;
 export declare const concat: <T>(dest: IWriteable<T> & IClosable, chans: Iterable<Channel<T>>, close?: boolean) => Promise<void>;
 /**
- * Consumes & collects all future values written to channel `chan` until
- * closed or the max. number of values has been collected (whatever comes
+ * Consumes & collects all queued and future values written to channel `chan`
+ * until closed or the max. number of values has been collected (whatever comes
  * first). Returns a promise of the result array.
  *
  * @param chan
@@ -13,11 +13,55 @@ export declare const concat: <T>(dest: IWriteable<T> & IClosable, chans: Iterabl
  * @param num
  */
 export declare const consume: <T>(chan: Channel<T>, res?: T[], num?: number) => Promise<T[]>;
+/**
+ * Consumes all queued and future values written to channel `chan` until closed
+ * or the max. number of values has been reached (whatever comes first). Calls
+ * `fn` with each value read (presumably for side effects). Returns a void
+ * promise which resolves when the consumer is done.
+ *
+ * @param chan
+ * @param fn
+ * @param num
+ */
 export declare const consumeWith: <T>(chan: Channel<T>, fn: Fn2<T, Channel<T>, void>, num?: number) => Promise<void>;
+/**
+ * Similar to {@link consume}, but only processes any current in-flight writes
+ * and returns a promise with an array of their values.
+ *
+ * @param chan
+ */
 export declare const drain: <T>(chan: Channel<T>) => Promise<Awaited<T>[]>;
+/**
+ * Takes an async iterable and returns a new CSP {@link Channel}, which receives
+ * all values from `src`. If `close` is true (default), the channel will be
+ * automatically closed once the iterable is exhausted.
+ *
+ * @param src
+ * @param close
+ */
 export declare const fromAsyncIterable: <T>(src: AsyncIterable<T>, close?: boolean) => Channel<T>;
 export declare const merge: <T>(src: Channel<T>[], dest?: Channel<T>, close?: boolean) => Channel<T>;
+export declare const into: <T, DEST extends IWriteable<T> & IClosable>(chan: DEST, src: Iterable<T> | AsyncIterable<T>, close?: boolean) => Promise<void>;
 export declare const pipe: <T, DEST extends IWriteable<T> & IClosable>(src: Channel<T>, dest: DEST, close?: boolean) => DEST;
+/**
+ * Takes one or more input channels and attempts to read from all of them at
+ * once (via {@link Channel.race}, a blocking op). Returns a promise which
+ * resolves once one of the inputs becomes available or was closed, selects that
+ * channel to read from it and returns tuple of `[value, channel]`.
+ *
+ * @param input
+ * @param xs
+ */
 export declare const select: <T>(input: Channel<T>, ...xs: Channel<T>[]) => Promise<[Maybe<T>, Channel<T>]>;
+/**
+ * Returns a new {@link Channel} which will automatically close after `delay`
+ * milliseconds.
+ *
+ * @remarks
+ * Intended as utility for enforcing a timeout for {@link select}-style
+ * operations.
+ *
+ * @param delay
+ */
 export declare const timeout: (delay: number) => Channel<any>;
 //# sourceMappingURL=ops.d.ts.map

package/ops.js

@@ -73,6 +73,14 @@ const merge = (src, dest, close = true) => {
   })();
   return dest;
 };
+const into = async (chan, src, close = false) => {
+  for await (let x of src) {
+    if (!chan.writable())
+      break;
+    await chan.write(x);
+  }
+  close && chan.close();
+};
 const pipe = (src, dest, close = true) => {
   (async () => {
     for await (let x of src) {
@@ -94,6 +102,7 @@ const select = async (input, ...xs) => {
   if (sel.writes.readable()) {
     const [msg, write] = sel.writes.read();
     write(true);
+    sel.updateQueue();
     return [msg, sel];
   }
   return [void 0, sel];
@@ -110,6 +119,7 @@ export {
   consumeWith,
   drain,
   fromAsyncIterable,
+  into,
   merge,
   pipe,
   select,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/csp",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Primitives & operators for Communicating Sequential Processes based on async/await and async iterables",
   "type": "module",
   "module": "./index.js",
@@ -106,5 +106,5 @@
     "status": "beta",
     "year": 2016
   },
-  "gitHead": "aed3421c21044c005fbcb7cc37965ccf85a870d2\n"
+  "gitHead": "85861eb5760fd5c145dbd2d032b6f03400d6653e\n"
 }

package/pubsub.d.ts

@@ -2,12 +2,31 @@ import type { IObjectOf } from "@thi.ng/api";
 import type { IClosable, IWriteable, TopicFn } from "./api.js";
 import { Channel } from "./channel.js";
 import { Mult } from "./mult.js";
+/**
+ * Syntax sugar for {@link PubSub} ctor. Creates a new `PubSub` which allows
+ * multiple child subscriptions, based on given topic function.
+ *
+ * @remarks
+ * The topic function will be called for each received value and its result is
+ * used to determine which child subscription should receive the value. New
+ * topic (un)subscriptions can be created dynamically via
+ * {@link PubSub.subscribeTopic} and {@link PubSub.unsubscribeTopic} or
+ * {@link PubSub.unsubscribeAll}. Each topic subscription is a {@link Mult},
+ * which itself allows for multiple child subscriptions.
+ *
+ * @param fn
+ */
 export declare function pubsub<T>(fn: TopicFn<T>): PubSub<T>;
 export declare function pubsub<T>(src: Channel<T>, fn: TopicFn<T>): PubSub<T>;
 export declare class PubSub<T> implements IWriteable<T>, IClosable {
     protected src: Channel<T>;
     protected fn: TopicFn<T>;
-    protected topics: IObjectOf<Mult<T>>;
+    protected topics: IObjectOf<Mult<any>>;
+    /**
+     * See {@link pubsub} for reference.
+     *
+     * @param fn
+     */
     constructor(fn: TopicFn<T>);
     constructor(src: Channel<T>, fn: TopicFn<T>);
     writable(): boolean;
@@ -21,8 +40,26 @@ export declare class PubSub<T> implements IWriteable<T>, IClosable {
      *
      * @param id - topic id
      */
-    subscribeTopic(id: string): Channel<T>;
-    unsubscribeTopic(id: string, ch: Channel<T>): boolean;
+    subscribeTopic<S extends T = T>(id: string): Channel<S>;
+    /**
+     * Attempts to remove a subscription channel for given topic `id`. Returns
+     * true if successful. If `close` is true (default), the given channel will
+     * also be closed (only if unsubscription was successful).
+     *
+     * @remarks
+     * See {@link Mult.subscribe} for reverse op.
+     *
+     * @param id
+     * @param ch
+     * @param close
+     */
+    unsubscribeTopic<S extends T = T>(id: string, ch: Channel<S>, close?: boolean): boolean;
+    /**
+     * Removes all child subscription channels for given topic `id` and if
+     * `close` is true (default) also closes them.
+     *
+     * @param close
+     */
     unsubscribeAll(id: string, close?: boolean): void;
     protected process(): Promise<void>;
 }

package/pubsub.js

@@ -50,10 +50,28 @@ class PubSub {
     }
     return topic.subscribe();
   }
-  unsubscribeTopic(id, ch) {
+  /**
+   * Attempts to remove a subscription channel for given topic `id`. Returns
+   * true if successful. If `close` is true (default), the given channel will
+   * also be closed (only if unsubscription was successful).
+   *
+   * @remarks
+   * See {@link Mult.subscribe} for reverse op.
+   *
+   * @param id
+   * @param ch
+   * @param close
+   */
+  unsubscribeTopic(id, ch, close = true) {
     const topic = this.topics[id];
-    return topic?.unsubscribe(ch) ?? false;
+    return topic?.unsubscribe(ch, close) ?? false;
   }
+  /**
+   * Removes all child subscription channels for given topic `id` and if
+   * `close` is true (default) also closes them.
+   *
+   * @param close
+   */
   unsubscribeAll(id, close = true) {
     const topic = this.topics[id];
     topic?.unsubscribeAll(close);