@thi.ng/rstream 9.1.0 → 9.2.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-12-04T15:08:17Z
+- **Last updated**: 2024-12-12T10:11:58Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,14 @@ 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.
 
+## [9.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/rstream@9.2.0) (2024-12-05)
+
+#### 🚀 Features
+
+- add fromTuple(), update StreamObj impl ([ef691cc](https://github.com/thi-ng/umbrella/commit/ef691cc))
+  - update docs
+  - add tests
+
 ## [9.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/rstream@9.1.0) (2024-12-04)
 
 #### 🚀 Features

package/README.md

@@ -215,7 +215,7 @@ For Node.js REPL:
 const rs = await import("@thi.ng/rstream");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 6.28 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 6.34 KB
 
 ## Dependencies
 
@@ -451,6 +451,7 @@ s.next(42);
 - [fromPromise()](https://docs.thi.ng/umbrella/rstream/functions/fromPromise.html) - single value stream from promise
 - [fromPromises()](https://docs.thi.ng/umbrella/rstream/functions/fromPromises.html) - results from multiple promise
 - [fromRAF()](https://docs.thi.ng/umbrella/rstream/functions/fromRAF.html) - requestAnimationFrame() counter (w/ node fallback)
+- [fromTuple()](https://docs.thi.ng/umbrella/rstream/functions/fromTuple.html) - tuple/vector per-component streams
 - [fromView()](https://docs.thi.ng/umbrella/rstream/functions/fromView.html) - derived view value changes (see [@thi.ng/atom](https://github.com/thi-ng/umbrella/tree/develop/packages/atom))
 - [fromWorker()](https://docs.thi.ng/umbrella/rstream/functions/fromWorker.html) - messages received from worker
 - [toggle()](https://docs.thi.ng/umbrella/rstream/functions/toggle.html) - on/off switch-like stream

package/object.d.ts

@@ -38,36 +38,26 @@ export interface StreamObjOpts<T, K extends Keys<T>> extends CommonOpts {
 }
 /**
  * Takes an arbitrary object `src` and object of options (see
- * {@link StreamObjOpts}). Creates a new object and for each selected
- * key creates a new stream, optionally seeded with the key's value in
- * `src`. Returns new object of streams.
+ * {@link StreamObjOpts}). Creates a new object and for each selected key
+ * creates a new subscription, optionally seeded with the key's value in `src`.
+ * Returns new {@link StreamObj}.
  *
  * @remarks
- * The structure of the returned object is
- * {@link StreamObj | as follows}:
- *
- * ```text
- * {
- *   streams: { ... },
- *   next(x): void;
- *   done(): void;
- * }
- * ```
- *
- * All streams will be stored under `streams`. The `next()` and `done()`
- * functions/methods allow the object itself to be used as subscriber
- * for an upstream subscribable (see 2nd example below):
- *
- * - `next()` - takes a object of same type as `src` and feeds each
- *   key's new value into its respective stream. If the `defaults`
- *   option is given, `undefined` key values are replaced with their
- *   specified default. If `dedupe` is enabled (default) only changed
- *   values (as per `equiv` predicate option) will be propagated
- *   downstream.
- * - `done()` - calls {@link ISubscriber.done} on all streams
- *
- * The optional `opts` arg is used to customize overall behavior of
- * `fromObject` and specify shared options for *all* created streams.
+ * The options arg is used to customize overall behavior of `fromObject` and
+ * specify shared options for *all* created streams.
+ *
+ * A {@link StreamObj} is a full {@link Subscription}, in which additionally all
+ * configured key streams are exposed under `streams`. The
+ * {@link StreamObj.next} and {@link StreamObj.done} methods allow the
+ * {@link StreamObj} itself to be used as subscriber for an upstream
+ * subscribable (see 2nd example below):
+ *
+ * {@link StreamObj.next} receives an object of same type as `src` and feeds
+ * each key's new value into its respective {@link StreamObj.streams}. If the
+ * {@link StreamObjOpts.defaults} option is given, `undefined` key values are
+ * replaced with their specified default. If {@link StreamObjOpts.dedupe} is
+ * enabled (default) only changed values (as per {@link StreamObjOpts.equiv}
+ * predicate option) will be propagated downstream.
  *
  * @example
  * ```ts tangle:../export/from-object.ts
@@ -99,7 +89,7 @@ export interface StreamObjOpts<T, K extends Keys<T>> extends CommonOpts {
  * obj.streams.b.subscribe(trace("b"));
  *
  * const src = subscription<Foo, Foo>();
- * // use as subscriber
+ * // use `obj` as subscriber itself
  * src.subscribe(obj);
  *
  * src.next({ a: 1, b: "foo" });
@@ -111,6 +101,44 @@ export interface StreamObjOpts<T, K extends Keys<T>> extends CommonOpts {
  * @param opts -
  */
 export declare const fromObject: <T extends object, K extends Keys<T>>(src: T, opts?: Partial<StreamObjOpts<T, K>>) => StreamObj<T, K>;
+/**
+ * Syntax sugar for {@link fromObject} for tuple/arrays. Returns a
+ * {@link StreamObj} which provides individual subscriptions for each tuple
+ * element, i.e. for 1:N fanout.
+ *
+ * @remarks
+ * This construct is very useful for UI purposes, helping to provide both
+ * finegrained and tuple-based reactive state for UI components used to edit
+ * tuple/vector values (e.g. via individual per-tuple-element input
+ * fields/controls).
+ *
+ * @example
+ * ```ts tangle:../export/from-tuple.ts
+ * import { fromTuple, subscription, trace } from "@thi.ng/rstream";
+ *
+ * const tup = fromTuple([10, 20, 30]);
+ *
+ * tup.streams[0].subscribe(trace("[0]:"));
+ * tup.streams[1].subscribe(trace("[1]:"));
+ * tup.streams[2].subscribe(trace("[2]:"));
+ *
+ * // [0]: 10
+ * // [1]: 20
+ * // [2]: 30
+ *
+ * tup.next([100,20,30]);
+ *
+ * // [0]: 100
+ * // (the two other streams didn't update since their values haven't changed)
+ * ```
+ *
+ * @param src
+ * @param opts
+ */
+export declare const fromTuple: <T>(src: T[], opts?: Partial<StreamObjOpts<T[], number>>) => StreamObj<T[], number>;
+/**
+ * See {@link fromObject} for details.
+ */
 export declare class StreamObj<T extends object, K extends Keys<T>> extends Subscription<T, T> {
     /**
      * Object of managed & typed streams for registered keys.
@@ -120,16 +148,18 @@ export declare class StreamObj<T extends object, K extends Keys<T>> extends Subs
     defaults?: Partial<T>;
     constructor(src: T, opts?: Partial<StreamObjOpts<T, K>>);
     /**
-     * Feeds new values from `x` to each registered key's stream.
-     * Satifies {@link ISubscriber.next} interface.
+     * Receives an object of configured type and feeds each key's new value into
+     * its respective {@link StreamObj.streams}. If the
+     * {@link StreamObjOpts.defaults} option is given, `undefined` key values
+     * are replaced with their specified default. If
+     * {@link StreamObjOpts.dedupe} is enabled (default) only changed values (as
+     * per {@link StreamObjOpts.equiv} predicate option) will be propagated
+     * downstream.
      *
      * @param x -
      */
     next(x: T): void;
-    /**
-     * Calls {@link ISubscriber.done} for all streams created. Satifies
-     * {@link ISubscriber.done} interface.
-     */
     done(): void;
+    unsubscribe(sub?: ISubscription<T, any> | undefined): boolean;
 }
 //# sourceMappingURL=object.d.ts.map

package/object.js

@@ -1,7 +1,9 @@
 import { dedupe } from "@thi.ng/transducers/dedupe";
+import { range } from "@thi.ng/transducers/range";
 import { __optsWithID } from "./idgen.js";
 import { Subscription, subscription } from "./subscription.js";
 const fromObject = (src, opts = {}) => new StreamObj(src, opts);
+const fromTuple = (src, opts) => new StreamObj(src, { keys: [...range(src.length)], ...opts });
 class StreamObj extends Subscription {
   /**
    * Object of managed & typed streams for registered keys.
@@ -26,8 +28,13 @@ class StreamObj extends Subscription {
     opts.initial !== false && this.next(src);
   }
   /**
-   * Feeds new values from `x` to each registered key's stream.
-   * Satifies {@link ISubscriber.next} interface.
+   * Receives an object of configured type and feeds each key's new value into
+   * its respective {@link StreamObj.streams}. If the
+   * {@link StreamObjOpts.defaults} option is given, `undefined` key values
+   * are replaced with their specified default. If
+   * {@link StreamObjOpts.dedupe} is enabled (default) only changed values (as
+   * per {@link StreamObjOpts.equiv} predicate option) will be propagated
+   * downstream.
    *
    * @param x -
    */
@@ -39,18 +46,25 @@ class StreamObj extends Subscription {
         this.defaults && val === void 0 ? this.defaults[k] : val
       );
     }
+    super.next(x);
   }
-  /**
-   * Calls {@link ISubscriber.done} for all streams created. Satifies
-   * {@link ISubscriber.done} interface.
-   */
   done() {
     for (let k of this.keys) {
       this.streams[k].done();
     }
+    super.done();
+  }
+  unsubscribe(sub) {
+    if (!sub) {
+      for (let k of this.keys) {
+        this.streams[k].unsubscribe();
+      }
+    }
+    return super.unsubscribe(sub);
   }
 }
 export {
   StreamObj,
-  fromObject
+  fromObject,
+  fromTuple
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/rstream",
-  "version": "9.1.0",
+  "version": "9.2.1",
   "description": "Reactive streams & subscription primitives for constructing dataflow graphs / pipelines",
   "type": "module",
   "module": "./index.js",
@@ -40,19 +40,19 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.13",
-    "@thi.ng/arrays": "^2.10.6",
-    "@thi.ng/associative": "^7.0.15",
-    "@thi.ng/atom": "^5.3.13",
-    "@thi.ng/checks": "^3.6.15",
-    "@thi.ng/errors": "^2.5.19",
-    "@thi.ng/logger": "^3.0.23",
-    "@thi.ng/transducers": "^9.2.9"
+    "@thi.ng/api": "^8.11.14",
+    "@thi.ng/arrays": "^2.10.7",
+    "@thi.ng/associative": "^7.0.16",
+    "@thi.ng/atom": "^5.3.14",
+    "@thi.ng/checks": "^3.6.16",
+    "@thi.ng/errors": "^2.5.20",
+    "@thi.ng/logger": "^3.0.24",
+    "@thi.ng/transducers": "^9.2.10"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.48.0",
     "esbuild": "^0.24.0",
-    "typedoc": "^0.26.11",
+    "typedoc": "^0.27.4",
     "typescript": "^5.7.2"
   },
   "keywords": [
@@ -219,5 +219,5 @@
     ],
     "year": 2017
   },
-  "gitHead": "7f97d3a454bb605afabf785af1736cb155ecced4\n"
+  "gitHead": "34ac95538d96f046090fef5fd3a1dc36d54663d5\n"
 }