@thi.ng/csp 3.2.0 → 3.2.2

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-04-28T14:28:17Z
+- **Last updated**: 2024-06-21T19:34:38Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,15 @@ 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.2](https://github.com/thi-ng/umbrella/tree/@thi.ng/csp@3.2.2) (2024-06-21)
+
+#### ♻️ Refactoring
+
+- rename various rest args to be more semantically meaningful ([8088a56](https://github.com/thi-ng/umbrella/commit/8088a56))
+- dedupe pipe() logic, deprecate into() ([5979527](https://github.com/thi-ng/umbrella/commit/5979527))
+  - update fromAsyncIterable()
+  - add docstrings
+
 ## [3.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/csp@3.2.0) (2024-04-28)
 
 #### 🚀 Features

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 192 standalone projects, maintained as part
+> This is one of 193 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -35,13 +35,14 @@
 
 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
-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**.
+> [!IMPORTANT]
+> 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 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**.
 
 ### What is CSP?
 
@@ -157,7 +158,7 @@ For Node.js REPL:
 const csp = await import("@thi.ng/csp");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.79 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.80 KB
 
 ## Dependencies
 

package/channel.js

@@ -23,10 +23,8 @@ class Channel {
     let opts;
     switch (args.length) {
       case 1:
-        if (isPlainObject(args[0]))
-          opts = args[0];
-        else
-          buf = args[0];
+        if (isPlainObject(args[0])) opts = args[0];
+        else buf = args[0];
         break;
       case 2:
         [buf, opts] = args;
@@ -68,8 +66,7 @@ class Channel {
   async *[Symbol.asyncIterator]() {
     while (this.state < STATE_CLOSED) {
       const x = await this.read();
-      if (x !== void 0)
-        yield x;
+      if (x !== void 0) yield x;
     }
   }
   /**
@@ -100,8 +97,7 @@ class Channel {
           resolve(void 0);
         }
       }
-      if (this.writes.readable())
-        this.deliver();
+      if (this.writes.readable()) this.deliver();
     });
   }
   /**
@@ -208,19 +204,15 @@ class Channel {
    * still "closing", not yet fully "closed".
    */
   close() {
-    if (this.state >= STATE_CLOSING)
-      return;
+    if (this.state >= STATE_CLOSING) return;
     const { reads, writes, races } = this;
     this.state = reads.length || writes.readable() ? STATE_CLOSING : STATE_CLOSED;
-    while (reads.length && writes.readable())
-      this.deliver();
+    while (reads.length && writes.readable()) this.deliver();
     if (!writes.readable()) {
-      while (reads.length)
-        reads.shift()(void 0);
+      while (reads.length) reads.shift()(void 0);
     }
     this.state = writes.readable() ? STATE_CLOSING : STATE_CLOSED;
-    while (races.length)
-      races.shift()(this);
+    while (races.length) races.shift()(this);
   }
   /**
    * Returns true if the channel is principally readable (i.e. not yet

package/mult.js

@@ -83,8 +83,7 @@ class Mult {
    */
   unsubscribeAll(close = true) {
     if (close) {
-      for (let t of this.taps)
-        t.close();
+      for (let t of this.taps) t.close();
     }
     this.taps.length = 0;
   }

package/ops.d.ts

@@ -33,26 +33,40 @@ export declare const consumeWith: <T>(chan: Channel<T>, fn: Fn2<T, Channel<T>, v
 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.
+ * all values from `src` (via {@link pipe}). If `close` is true (default), the
+ * channel will be automatically closed once the iterable is exhausted. Returns
+ * the new channel.
  *
  * @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>;
+/**
+ * @deprecated use {@link pipe} instead.
+ */
 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;
+/**
+ * Receives values from `src` and writes them to `dest` for as long as it's
+ * accepting new writes (i.e. isn't closed from elsewhere). If `close` is true
+ * (default), the `dest` channel will be automatically closed once the `src` is
+ * exhausted. Returns `dest` channel.
+ *
+ * @param src
+ * @param dest
+ * @param close
+ */
+export declare const pipe: <T, DEST extends IWriteable<T> & IClosable>(src: AsyncIterable<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
+ * @param input - first input
+ * @param rest - other inputs
  */
-export declare const select: <T>(input: Channel<T>, ...xs: Channel<T>[]) => Promise<[Maybe<T>, Channel<T>]>;
+export declare const select: <T>(input: Channel<T>, ...rest: Channel<T>[]) => Promise<[Maybe<T>, Channel<T>]>;
 /**
  * Returns a new {@link Channel} which will automatically close after `delay`
  * milliseconds.

package/ops.js

@@ -2,12 +2,10 @@ import { assert } from "@thi.ng/errors/assert";
 import { Channel } from "./channel.js";
 const broadcast = async (src, dest, close = true) => {
   for await (let x of src) {
-    for (let chan of dest)
-      chan.write(x);
+    for (let chan of dest) chan.write(x);
   }
   if (close) {
-    for (let chan of dest)
-      chan.close();
+    for (let chan of dest) chan.close();
   }
 };
 const concat = async (dest, chans, close = true) => {
@@ -21,8 +19,7 @@ const concat = async (dest, chans, close = true) => {
 const consume = async (chan, res = [], num = Infinity) => {
   for (let n = 0; !chan.closed() && n < num; n++) {
     const x = await chan.read();
-    if (x == void 0)
-      break;
+    if (x == void 0) break;
     res.push(x);
   }
   return res;
@@ -30,8 +27,7 @@ const consume = async (chan, res = [], num = Infinity) => {
 const consumeWith = async (chan, fn, num = Infinity) => {
   for (let n = 0; !chan.closed() && n < num; n++) {
     const x = await chan.read();
-    if (x == void 0)
-      break;
+    if (x == void 0) break;
     fn(x, chan);
   }
 };
@@ -42,18 +38,7 @@ const drain = async (chan) => await (async () => {
   }
   return Promise.all(ops);
 })();
-const fromAsyncIterable = (src, close = true) => {
-  const chan = new Channel();
-  (async () => {
-    for await (let x of src) {
-      await chan.write(x);
-      if (!chan.writable())
-        break;
-    }
-    close && chan.close();
-  })();
-  return chan;
-};
+const fromAsyncIterable = (src, close = true) => pipe(src, new Channel(), close);
 const merge = (src, dest, close = true) => {
   assert(src.length > 0, "no inputs given");
   dest = dest || new Channel();
@@ -75,8 +60,7 @@ const merge = (src, dest, close = true) => {
 };
 const into = async (chan, src, close = false) => {
   for await (let x of src) {
-    if (!chan.writable())
-      break;
+    if (!chan.writable()) break;
     await chan.write(x);
   }
   close && chan.close();
@@ -85,19 +69,17 @@ const pipe = (src, dest, close = true) => {
   (async () => {
     for await (let x of src) {
       await dest.write(x);
-      if (!dest.writable())
-        break;
+      if (!dest.writable()) break;
     }
     close && dest.close();
   })();
   return dest;
 };
-const select = async (input, ...xs) => {
-  const inputs = [input, ...xs];
+const select = async (input, ...rest) => {
+  const inputs = [input, ...rest];
   const sel = await Promise.race(inputs.map((x) => x.race()));
   for (let chan of inputs) {
-    if (chan !== sel)
-      chan.races.shift();
+    if (chan !== sel) chan.races.shift();
   }
   if (sel.writes.readable()) {
     const [msg, write] = sel.writes.read();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/csp",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "description": "Primitives & operators for Communicating Sequential Processes based on async/await and async iterables",
   "type": "module",
   "module": "./index.js",
@@ -10,7 +10,7 @@
     "type": "git",
     "url": "https://github.com/thi-ng/umbrella.git"
   },
-  "homepage": "https://github.com/thi-ng/umbrella/tree/develop/packages/csp#readme",
+  "homepage": "https://thi.ng/csp",
   "funding": [
     {
       "type": "github",
@@ -40,16 +40,16 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.1",
-    "@thi.ng/buffers": "^0.1.2",
-    "@thi.ng/checks": "^3.6.3",
-    "@thi.ng/errors": "^2.5.6"
+    "@thi.ng/api": "^8.11.3",
+    "@thi.ng/buffers": "^0.1.4",
+    "@thi.ng/checks": "^3.6.5",
+    "@thi.ng/errors": "^2.5.8"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.43.0",
-    "esbuild": "^0.20.2",
-    "typedoc": "^0.25.12",
-    "typescript": "^5.4.3"
+    "@microsoft/api-extractor": "^7.47.0",
+    "esbuild": "^0.21.5",
+    "typedoc": "^0.25.13",
+    "typescript": "^5.5.2"
   },
   "keywords": [
     "async",
@@ -106,5 +106,5 @@
     "status": "beta",
     "year": 2016
   },
-  "gitHead": "85861eb5760fd5c145dbd2d032b6f03400d6653e\n"
+  "gitHead": "154c95cf9d6bab32174498ec3b5b5d87e42be7f9\n"
 }