@thi.ng/rstream 9.0.9 → 9.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-11-24T18:15:49Z
+- **Last updated**: 2024-12-05T12:02:40Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,20 @@ 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
+
+- update fromObject(), re-implement as full subscription ([6903507](https://github.com/thi-ng/umbrella/commit/6903507))
+
 # [9.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/rstream@9.0.0) (2024-08-20)
 
 #### 🛑 Breaking changes

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

@@ -1,29 +1,9 @@
-import type { Keys, Predicate2 } from "@thi.ng/api";
+import type { IObjectOf, Keys, NumOrString, Predicate2 } from "@thi.ng/api";
 import type { CommonOpts, ISubscription } from "./api.js";
+import { Subscription } from "./subscription.js";
 export type KeyStreams<T, K extends Keys<T>> = {
     [id in K]-?: ISubscription<T[id], T[id]>;
 };
-/**
- * Result object type for {@link fromObject}.
- */
-export interface StreamObj<T, K extends Keys<T>> {
-    /**
-     * Object of managed & typed streams for registered keys.
-     */
-    streams: KeyStreams<T, K>;
-    /**
-     * Feeds new values from `x` to each registered key's stream.
-     * Satifies {@link ISubscriber.next} interface.
-     *
-     * @param x -
-     */
-    next(x: T): void;
-    /**
-     * Calls {@link ISubscriber.done} for all streams created. Satifies
-     * {@link ISubscriber.done} interface.
-     */
-    done(): void;
-}
 export interface StreamObjOpts<T, K extends Keys<T>> extends CommonOpts {
     /**
      * Array of selected `keys` (else selects all by default) for which
@@ -58,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 optional `opts` 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
@@ -119,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 subscription itself
  * src.subscribe(obj);
  *
  * src.next({ a: 1, b: "foo" });
@@ -131,4 +101,48 @@ 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. 1:N fanout.
+ *
+ * ```ts tangle:../export/from-tuple.ts
+ * import { fromTuple, subscription, trace } from "@thi.ng/rstream";
+ *
+ * const tup = fromTuple([1, 2, 3]);
+ *
+ * tup.streams[0].subscribe(trace("[0]:"));
+ * tup.streams[1].subscribe(trace("[1]:"));
+ * tup.streams[2].subscribe(trace("[2]:"));
+ * ```
+ * @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.
+     */
+    keys: NumOrString[];
+    streams: IObjectOf<Subscription<any, any>>;
+    defaults?: Partial<T>;
+    constructor(src: T, opts?: Partial<StreamObjOpts<T, K>>);
+    /**
+     * 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;
+    done(): void;
+    unsubscribe(sub?: ISubscription<T, any> | undefined): boolean;
+}
 //# sourceMappingURL=object.d.ts.map

package/object.js

@@ -1,39 +1,70 @@
 import { dedupe } from "@thi.ng/transducers/dedupe";
-import { __nextID } from "./idgen.js";
-import { subscription } from "./subscription.js";
-const fromObject = (src, opts = {}) => {
-  const id = opts.id || `obj${__nextID()}`;
-  const keys = opts.keys || Object.keys(src);
-  const _opts = opts.dedupe !== false ? {
-    xform: dedupe(opts.equiv || ((a, b) => a === b)),
-    ...opts
-  } : opts;
-  const streams = {};
-  for (let k of keys) {
-    streams[k] = subscription(void 0, {
-      ..._opts,
-      id: `${id}-${String(k)}`
-    });
+import { __optsWithID } from "./idgen.js";
+import { Subscription, subscription } from "./subscription.js";
+import { range } from "@thi.ng/transducers";
+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.
+   */
+  keys;
+  streams = {};
+  defaults;
+  constructor(src, opts = {}) {
+    super(void 0, __optsWithID("obj", opts));
+    this.keys = opts.keys || Object.keys(src);
+    this.defaults = opts.defaults;
+    const _opts = opts.dedupe !== false ? {
+      xform: dedupe(opts.equiv || ((a, b) => a === b)),
+      ...opts
+    } : opts;
+    for (let k of this.keys) {
+      this.streams[k] = subscription(void 0, {
+        ..._opts,
+        id: `${this.id}-${k}`
+      });
+    }
+    opts.initial !== false && this.next(src);
   }
-  const res = {
-    streams,
-    next(state) {
-      for (let k of keys) {
-        const val = state[k];
-        streams[k].next(
-          opts.defaults && val === void 0 ? opts.defaults[k] : val
-        );
-      }
-    },
-    done() {
-      for (let k of keys) {
-        streams[k].done();
+  /**
+   * 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) {
+    this.cacheLast && (this.last = x);
+    for (let k of this.keys) {
+      const val = x[k];
+      this.streams[k].next(
+        this.defaults && val === void 0 ? this.defaults[k] : val
+      );
+    }
+    super.next(x);
+  }
+  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();
       }
     }
-  };
-  opts.initial !== false && res.next(src);
-  return res;
-};
+    return super.unsubscribe(sub);
+  }
+}
 export {
-  fromObject
+  StreamObj,
+  fromObject,
+  fromTuple
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/rstream",
-  "version": "9.0.9",
+  "version": "9.2.0",
   "description": "Reactive streams & subscription primitives for constructing dataflow graphs / pipelines",
   "type": "module",
   "module": "./index.js",
@@ -219,5 +219,5 @@
     ],
     "year": 2017
   },
-  "gitHead": "85e2f0935b58bde5d165fbe754fafec5da0b731e\n"
+  "gitHead": "b3cc41cd55dd21cf672c2567b748b0a632b01d76\n"
 }