@thi.ng/rstream 8.4.3 → 8.5.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-04-23T07:02:18Z
+- **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,13 @@ 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.
 
+## [8.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/rstream@8.5.0) (2024-05-08)
+
+#### 🚀 Features
+
+- add rdom-klist example project, update readmes ([cd458ac](https://github.com/thi-ng/umbrella/commit/cd458ac))
+- add rdom-klist example project, update readmes ([531437f](https://github.com/thi-ng/umbrella/commit/531437f))
+
 ### [8.4.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/rstream@8.4.1) (2024-04-20)
 
 #### ♻️ Refactoring

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.
 >
@@ -214,7 +214,7 @@ For Node.js REPL:
 const rs = await import("@thi.ng/rstream");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 6.32 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 6.33 KB
 
 ## Dependencies
 
@@ -265,6 +265,7 @@ directory are using this package:
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rdom-delayed-update.jpg" width="240"/>           | Dynamically loaded images w/ preloader state                                                            | [Demo](https://demo.thi.ng/umbrella/rdom-delayed-update/)  | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rdom-delayed-update) |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rdom-formgen.jpg" width="240"/>                  | Basic usage of the declarative rdom-forms generator                                                     | [Demo](https://demo.thi.ng/umbrella/rdom-formgen/)         | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rdom-formgen)        |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rdom-key-sequences.jpg" width="240"/>            | rstream & transducer-based FSM for converting key event sequences into high-level commands              | [Demo](https://demo.thi.ng/umbrella/rdom-key-sequences/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rdom-key-sequences)  |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rdom-klist.png" width="240"/>                    | Basic usage of thi.ng/rdom keyed list component wrapper                                                 | [Demo](https://demo.thi.ng/umbrella/rdom-klist/)           | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rdom-klist)          |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rdom-lissajous.png" width="240"/>                | rdom & hiccup-canvas interop test                                                                       | [Demo](https://demo.thi.ng/umbrella/rdom-lissajous/)       | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rdom-lissajous)      |
 |                                                                                                                                      | Full umbrella repo doc string search w/ paginated results                                               | [Demo](https://demo.thi.ng/umbrella/rdom-search-docs/)     | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rdom-search-docs)    |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rdom-svg-nodes.png" width="240"/>                | rdom powered SVG graph with draggable nodes                                                             | [Demo](https://demo.thi.ng/umbrella/rdom-svg-nodes/)       | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rdom-svg-nodes)      |

package/async.js

@@ -6,8 +6,7 @@ const fromAsync = (src, opts) => stream(($stream) => {
   (async () => {
     try {
       for await (let x of src) {
-        if (!active)
-          return;
+        if (!active) return;
         $stream.next(x);
       }
       $stream.done();
@@ -31,23 +30,19 @@ async function* asAsync(src) {
       if (initial) {
         resolve(x);
         initial = void 0;
-      } else
-        promises.push(Promise.resolve(x));
+      } else promises.push(Promise.resolve(x));
     },
     done() {
       if (initial) {
         resolve(SEMAPHORE);
         initial = void 0;
-      } else
-        promises.push(Promise.resolve(SEMAPHORE));
+      } else promises.push(Promise.resolve(SEMAPHORE));
     }
   });
   while (promises.length && src.getState() < State.ERROR) {
     const res = await promises.shift();
-    if (res === SEMAPHORE)
-      break;
-    if (!promises.length)
-      promises[0] = $newInitial();
+    if (res === SEMAPHORE) break;
+    if (!promises.length) promises[0] = $newInitial();
     yield res;
   }
 }

package/atom.d.ts

@@ -32,14 +32,16 @@ export interface FromAtomOpts<T> extends CommonOpts {
  * Also see {@link fromView}, {@link fromViewUnsafe}
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/from-atom.ts
  * import { defAtom, defCursor } from "@thi.ng/atom";
- * import { fromCursor } from "@thi.ng/rstream";
+ * import { fromAtom, trace } from "@thi.ng/rstream";
  *
- * db = defAtom({ a: 23, b: 88 });
- * cursor = defCursor(db, "a")
+ * type DB = { a: number; b?: number };
  *
- * rs.fromAtom(cursor).subscribe(rs.trace("cursor val:"))
+ * const db = defAtom<DB>({ a: 23, b: 88 });
+ * const cursor = defCursor(db, ["a"])
+ *
+ * fromAtom(cursor).subscribe(trace("cursor val:"))
  * // cursor val: 23
  *
  * cursor.reset(42);

package/bisect.d.ts

@@ -12,7 +12,7 @@ import { PubSub } from "./pubsub.js";
  * kept prior to calling `bisect()`.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/bisect.ts
  * import { bisect, fromIterable, trace } from "@thi.ng/rstream";
  *
  * fromIterable([1, 2, 3, 4]).subscribe(
@@ -31,19 +31,28 @@ import { PubSub } from "./pubsub.js";
  * ```
  *
  * @example
- * ```ts
- * import { bisect, subscription, trace } from "@thi.ng/rstream";
+ * ```ts tangle:../export/bisect-2.ts
+ * import { bisect, fromIterable, subscription, trace } from "@thi.ng/rstream";
  * import { map } from "@thi.ng/transducers";
  *
- * const odd = subscription();
- * const even = subscription();
+ * const odd = subscription<number, number>();
+ * const even = subscription<number, number>();
  * odd.subscribe(trace("odd"));
- * odd.subscribe(trace("odd x10"), { xform: map((x) => x * 10) });
+ * odd.subscribe(trace("odd x10"), { xform: map((x: number) => x * 10) });
  * even.subscribe(trace("even"));
  *
  * fromIterable([1, 2, 3, 4]).subscribe(
  *     bisect((x) => !!(x & 1), odd, even)
  * );
+ * // odd x10 10
+ * // odd 1
+ * // even 2
+ * // odd x10 30
+ * // odd 3
+ * // even 4
+ * // odd x10 done
+ * // odd done
+ * // even done
  * ```
  *
  * @param pred - predicate function

package/debounce.d.ts

@@ -5,12 +5,13 @@ import { type MetaStreamOpts } from "./metastream.js";
  * milliseconds.
  *
  * @example
- * ```ts
- * import { debounce, fromIterable } from "@thi.ng/rstream";
+ * ```ts tangle:../export/debounce.ts
+ * import { debounce, fromIterable, trace } from "@thi.ng/rstream";
  *
  * const src = fromIterable([1, 2, 3], { delay: 10 })
- * src.subscribe(debounce(20)).subscribe({ next: console.log });
+ * src.subscribe(debounce(20)).subscribe(trace());
  * // 3
+ * // done
  * ```
  *
  * @param delay -

package/event.d.ts

@@ -32,8 +32,6 @@ export declare const fromEvent: (src: EventTarget, name: string, listenerOpts?:
  * fromEvent(document.body, "mousemove"); // Stream<Event>
  * ```
  *
- * Also see: {@link fromEvent}
- *
  * @param src -
  * @param name -
  * @param listenerOpts -

package/merge.d.ts

@@ -17,7 +17,7 @@ export interface StreamMergeOpts<A, B> extends TransformableOpts<A, B> {
  * {@link StreamMergeOpts | options}.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/merge.ts
  * import { fromIterable, merge, trace } from "@thi.ng/rstream";
  *
  * merge({
@@ -37,6 +37,7 @@ export interface StreamMergeOpts<A, B> extends TransformableOpts<A, B> {
  * // 3
  * // 20
  * // 30
+ * // done
  * ```
  *
  * @example
@@ -46,13 +47,14 @@ export interface StreamMergeOpts<A, B> extends TransformableOpts<A, B> {
  * track their provenance:
  *
  * @example
- * ```ts
- * import { fromIterable, merge } from "@thi.ng/rstream";
+ * ```ts tangle:../export/merge-2.ts
+ * import { fromIterable, merge, trace } from "@thi.ng/rstream";
+ * import { labeled } from "@thi.ng/transducers";
  *
  * merge({
  *     src: [
- *         fromIterable([1, 2, 3]).transform(tx.labeled("a")),
- *         fromIterable([10, 20, 30]).transform(tx.labeled("b")),
+ *         fromIterable([1, 2, 3]).transform(labeled("a")),
+ *         fromIterable([10, 20, 30]).transform(labeled("b")),
  *     ]
  * }).subscribe(trace());
  * // ["a", 1]
@@ -61,6 +63,7 @@ export interface StreamMergeOpts<A, B> extends TransformableOpts<A, B> {
  * // ["b", 20]
  * // ["a", 3]
  * // ["b", 30]
+ * // done
  * ```
  *
  * @param opts -

package/metastream.d.ts

@@ -36,14 +36,14 @@ export interface MetaStreamOpts extends CommonOpts {
  * dynamic switching between them.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/metastream.ts
  * import { fromIterable, metaStream, trace } from "@thi.ng/rstream";
  * import { repeat } from "@thi.ng/transducers";
  *
  * // transform each received odd number into a stream
  * // producing 3 copies of that number in the metastream
  * // even numbers are ignored
- * a = metaStream(
+ * const a = metaStream<number, number>(
  *   (x) => (x & 1)
  *     ? fromIterable(repeat(x, 3), { delay: 100 })
  *     : null
@@ -56,41 +56,51 @@ export interface MetaStreamOpts extends CommonOpts {
  * // 23
  * // 23
  *
- * a.next(42) // ignored by factory fn
+ * setTimeout(() => a.next(42), 500); // value 42 ignored by metastream
  *
- * a.next(43)
+ * setTimeout(() => a.next(43), 1000);
  * // 43
  * // 43
  * // 43
  * ```
  *
  * @example
- * ```ts
- * import { fromIterable, metaStream, trace, CloseMode } from "@thi.ng/rstream";
- * import { repeat } from "@thi.ng/transducers";
+ * ```ts tangle:../export/metastream-2.ts
+ * import { CloseMode, fromIterable, metaStream, trace } from "@thi.ng/rstream";
+ * import { cycle, repeat } from "@thi.ng/transducers";
  *
- * // infinite inputs
- * a = fromIterable(
+ * // infinite inputs (important: closeOut mode = never!)
+ * const a = fromIterable(
  *   repeat("a"),
- *   { delay: 1000, closeOut: CloseMode.NEVER }
+ *   { delay: 100, closeOut: CloseMode.NEVER }
  * );
- * b = fromIterable(
+ * const b = fromIterable(
  *   repeat("b"),
- *   { delay: 1000, closeOut: CloseMode.NEVER }
+ *   { delay: 100, closeOut: CloseMode.NEVER }
  * );
  *
  * // stream selector / switch
- * m = metaStream((x) => x ? a : b);
+ * const m = metaStream<boolean, string>((x) => (x ? a : b));
  * m.subscribe(trace("meta from: "));
  *
- * m.next(true);
- * // meta from: a
- *
- * m.next(false);
- * // meta from: b
- *
- * m.next(true);
- * // meta from: a
+ * // create infinite stream of true/false and pipe into
+ * // the metastream and switch which source to use
+ * fromIterable(cycle([true, false]), { delay: 500 })
+ *   .subscribe({ next(x) { m.next(x); } });
+ *
+ * // a
+ * // a
+ * // a
+ * // a
+ * // a
+ * // b
+ * // b
+ * // b
+ * // b
+ * // b
+ * // a
+ * // a
+ * // ...
  * ```
  *
  * @param factory -

package/nodejs.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import type { Readable } from "node:stream";
 import { type Stream } from "./stream.js";
 import type { Subscription } from "./subscription.js";
@@ -23,9 +22,9 @@ export declare const fromNodeJS: <T>(stdout: Readable, stderr?: Readable, close?
  * to rechunk input.
  *
  * @example
- * ```ts
- * import { spawn } from "node:child_process"
+ * ```ts tangle:../export/lines-from-nodejs.ts
  * import { linesFromNodeJS, trace } from "@thi.ng/rstream";
+ * import { spawn } from "node:child_process"
  *
  * const cmd = spawn("ls", ["-la"]);
  *

package/object.d.ts

@@ -90,28 +90,31 @@ export interface StreamObjOpts<T, K extends Keys<T>> extends CommonOpts {
  * `fromObject` and specify shared options for *all* created streams.
  *
  * @example
- * ```ts
- * import { fromObject } from "@thi.ng/rstream";
+ * ```ts tangle:../export/from-object.ts
+ * import { fromObject, trace } from "@thi.ng/rstream";
  *
  * type Foo = { a?: number; b: string; };
  *
- * const obj = fromObject(<Foo>{ a: 1, b: "foo" })
+ * const obj = fromObject(<Foo>{ a: 1, b: "foo" });
  *
- * obj.streams.a.subscribe(trace("a"))
+ * obj.streams.a.subscribe(trace("a"));
  * // a 1
- * obj.streams.b.subscribe(trace("b"))
+ *
+ * obj.streams.b.subscribe(trace("b"));
  * // b foo
  *
- * obj.next({ b: "bar" })
+ * obj.next({ b: "bar" });
  * // a undefined
  * // b bar
  * ```
  *
  * @example
- * ```ts
- * import { fromObject, trace } from "@thi.ng/rstream";
+ * ```ts tangle:../export/from-object-2.ts
+ * import { fromObject, subscription, trace } from "@thi.ng/rstream";
+ *
+ * type Foo = { a?: number; b: string; };
  *
- * const obj = fromObject(<Foo>{}, ["a", "b"], { initial: false });
+ * const obj = fromObject(<Foo>{}, { keys: ["a", "b"], initial: false });
  * obj.streams.a.subscribe(trace("a"));
  * obj.streams.b.subscribe(trace("b"));
  *
@@ -127,5 +130,5 @@ export interface StreamObjOpts<T, K extends Keys<T>> extends CommonOpts {
  * @param src -
  * @param opts -
  */
-export declare const fromObject: <T extends object, K extends keyof T>(src: T, opts?: Partial<StreamObjOpts<T, K>>) => StreamObj<T, K>;
+export declare const fromObject: <T extends object, K extends Keys<T>>(src: T, opts?: Partial<StreamObjOpts<T, K>>) => StreamObj<T, K>;
 //# sourceMappingURL=object.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/rstream",
-  "version": "8.4.3",
+  "version": "8.5.1",
   "description": "Reactive streams & subscription primitives for constructing dataflow graphs / pipelines",
   "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/rstream#readme",
+  "homepage": "https://thi.ng/rstream",
   "funding": [
     {
       "type": "github",
@@ -40,20 +40,20 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.1",
-    "@thi.ng/arrays": "^2.9.5",
-    "@thi.ng/associative": "^6.3.59",
-    "@thi.ng/atom": "^5.2.45",
-    "@thi.ng/checks": "^3.6.3",
-    "@thi.ng/errors": "^2.5.6",
-    "@thi.ng/logger": "^3.0.11",
-    "@thi.ng/transducers": "^9.0.4"
+    "@thi.ng/api": "^8.11.3",
+    "@thi.ng/arrays": "^2.9.7",
+    "@thi.ng/associative": "^6.3.61",
+    "@thi.ng/atom": "^5.3.1",
+    "@thi.ng/checks": "^3.6.5",
+    "@thi.ng/errors": "^2.5.8",
+    "@thi.ng/logger": "^3.0.13",
+    "@thi.ng/transducers": "^9.0.6"
   },
   "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",
@@ -218,5 +218,5 @@
     ],
     "year": 2017
   },
-  "gitHead": "aed3421c21044c005fbcb7cc37965ccf85a870d2\n"
+  "gitHead": "154c95cf9d6bab32174498ec3b5b5d87e42be7f9\n"
 }

package/post-worker.d.ts

@@ -16,15 +16,15 @@ import type { ISubscriber } from "./api.js";
  * since the parent subscription is {@link ISubscriber.done}.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/post-worker.ts
  * import { postWorker, stream } from "@thi.ng/rstream";
  *
  * // worker source code
- * src = `self.onmessage = (e) => console.log("worker", e.data);`;
+ * const src = `self.onmessage = (e) => console.log("worker", e.data);`;
  *
- * a = stream();
+ * const a = stream<any>();
  * a.subscribe(
- *   postWorker(src, { type: "application/javascript" }))
+ *   postWorker(new Blob([src], { type: "application/javascript" }))
  * );
  *
  * a.next(42)

package/promises.d.ts

@@ -10,8 +10,8 @@ import type { ISubscription, WithErrorHandlerOpts } from "./api.js";
  * Also see {@link fromPromise}, {@link resolve}.
  *
  * @example
- * ```ts
- * import { fromPromises } from "@thi.ng/rstream";
+ * ```ts tangle:../export/from-promises.ts
+ * import { fromPromises, trace } from "@thi.ng/rstream";
  *
  * fromPromises([
  *     Promise.resolve(1),
@@ -24,20 +24,6 @@ import type { ISubscription, WithErrorHandlerOpts } from "./api.js";
  * // done
  * ```
  *
- * @example
- * If individual error handling is required, an alternative is below
- * (however this approach provides no ordering guarantees):
- *
- * ```ts
- * import { fromIterable, resolve, trace } from "@thi.ng/rstream";
- *
- * fromIterable([
- *     Promise.resolve(1),
- *     new Promise(() => setTimeout(() => { throw new Error("eeek"); }, 10)),
- *     Promise.resolve(3)
- * ]).subscribe(resolve()).subscribe(trace())
- * ```
- *
  * @param promises -
  * @param opts -
  */

package/raf.js

@@ -9,8 +9,7 @@ const fromRAF = (opts = {}) => isNode() ? fromInterval(16, opts) : stream((strea
   let t0 = isNumber(opts.t0) ? opts.t0 : void 0;
   const loop = (time) => {
     if (opts.timestamp && opts.t0) {
-      if (t0 === void 0)
-        t0 = time;
+      if (t0 === void 0) t0 = time;
       time -= t0;
     }
     isActive && stream2.next(opts.timestamp ? time : i++);

package/resolve.d.ts

@@ -17,14 +17,14 @@ export interface ResolverOpts extends IID<string> {
  * from receiving further values.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/resolve.ts
  * import { fromIterable, resolve, trace } from "@thi.ng/rstream";
  * import { delayed } from "@thi.ng/transducers";
  *
- * fromIterable([1, 2, 3], 100)
+ * fromIterable([1, 2, 3], 500)
  *   .transform(delayed(1000))
  *   .subscribe(resolve())
- *   .subscribe(trace("result"))
+ *   .subscribe(trace("result"));
  * // result 1
  * // result 2
  * // result 3

package/sidechain-partition.d.ts

@@ -17,15 +17,17 @@ export interface SidechainPartitionOpts<T> extends CommonOpts {
  * Also see: {@link sidechainToggle}, {@link sidechainTrigger}, {@link syncRAF}.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/sidechain-partition.ts
  * import { fromEvent, fromRAF, merge, sidechainPartition, trace } from "@thi.ng/rstream";
  *
  * // merge various event streams
- * events = merge([
+ * const events = merge({
+ *   src: [
  *     fromEvent(document,"mousemove"),
  *     fromEvent(document,"mousedown"),
  *     fromEvent(document,"mouseup")
- * ]);
+ *   ]
+ * });
  *
  * // queue event processing to only execute during the
  * // requestAnimationFrame cycle (RAF)
@@ -51,15 +53,15 @@ export declare const sidechainPartition: <T, S>(src: ISubscribable<T>, side: ISu
  * and {@link syncRAF}.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/sidechain-partition-raf.ts
  * import { defAtom } from "@thi.ng/atom";
- * import { sideChainPartitionRAF } from "@thi.ng/rstream";
+ * import { fromAtom, sidechainPartitionRAF } from "@thi.ng/rstream";
  *
  * const atom = defAtom("alice");
  *
  * // any change to the atom will only be applied during next RAF update
- * sideChainPartitionRAF(fromAtom(atom)).subscribe({
- *   next({ name }) { document.body.innerText = name; }
+ * sidechainPartitionRAF(fromAtom(atom)).subscribe({
+ *   next(name) { document.body.innerText = name; }
  * });
  *
  * // trigger update

package/sidechain-toggle.d.ts

@@ -17,17 +17,23 @@ export interface SidechainToggleOpts<T> extends CommonOpts {
  * forwarded downstream.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/sidechain-toggle.ts
  * import { fromInterval, sidechainToggle, trace } from "@thi.ng/rstream";
  *
+ * const src = fromInterval(500);
+ *
+ * // close stream after 5 secs
+ * setTimeout(() => src.done(), 5000);
+ *
  * // use slower interval stream to toggle faster main stream on/off
- * sidechainToggle(fromInterval(500), fromInterval(1000)).subscribe(trace());
+ * sidechainToggle(src, fromInterval(1000)).subscribe(trace());
  * // 0
- * // 3
+ * // 1
  * // 4
- * // 7
+ * // 5
  * // 8
- * ...
+ * // 9
+ * // done
  * ```
  *
  * @param src -

package/sidechain-trigger.d.ts

@@ -18,7 +18,7 @@ export interface SidechainTriggerOpts<T> extends CommonOpts {
  * downstream.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/sidechain-trigger.ts
  * import { reactive, stream, sidechainTrigger, trace } from "@thi.ng/rstream";
  *
  * const src = reactive("payload");
@@ -40,7 +40,6 @@ export interface SidechainTriggerOpts<T> extends CommonOpts {
  * // ...until side chain triggers again
  * side.next(1);
  * // data: update #2
- * ...
  * ```
  *
  * @param src

package/stream.d.ts

@@ -27,10 +27,10 @@ import { Subscription } from "./subscription.js";
  * disabled or if the stream is done, it will deref to `undefined`.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/stream.ts
  * import { stream, subscription, trace } from "@thi.ng/rstream";
  *
- * a = stream((s) => {
+ * const a = stream((s) => {
  *     s.next(1);
  *     s.next(2);
  *     s.done()
@@ -41,7 +41,7 @@ import { Subscription } from "./subscription.js";
  * // a done
  *
  * // as reactive value mechanism
- * b = stream();
+ * const b = stream();
  * // or alternatively
  * // b = subscription();
  *

package/stream.js

@@ -57,8 +57,7 @@ class Stream extends Subscription {
     delete this._cancel;
   }
   error(e) {
-    if (super.error(e))
-      return true;
+    if (super.error(e)) return true;
     this.cancel();
     return false;
   }

package/subscription.d.ts

@@ -32,14 +32,17 @@ import { CloseMode, State, type CommonOpts, type ISubscriber, type ISubscription
  * arg. See {@link CommonOpts} and {@link SubscriptionOpts} for further details.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/subscription.ts
  * import { subscription, trace } from "@thi.ng/rstream";
  * import { filter } from "@thi.ng/transducers";
  *
  * // as reactive value mechanism (same as with stream() above)
- * s = subscription();
+ * const s = subscription<number, number>();
+ *
+ * // attach child subscriptions
  * s.subscribe(trace("s1"));
- * s.subscribe(trace("s2"), { xform: filter((x) => x > 25) });
+ * // this child sub will receive filtered values only
+ * s.subscribe(trace("s2"), { xform: filter((x: number) => x > 25) });
  *
  * // external trigger
  * s.next(23);

package/subscription.js

@@ -121,17 +121,14 @@ class Subscription {
     return false;
   }
   next(x) {
-    if (this.state >= State.DONE)
-      return;
+    if (this.state >= State.DONE) return;
     this.xform ? this.dispatchXform(x) : this.dispatch(x);
   }
   done() {
     LOGGER.debug(this.id, "entering done()");
-    if (this.state >= State.DONE)
-      return;
+    if (this.state >= State.DONE) return;
     if (this.xform) {
-      if (!this.dispatchXformDone())
-        return;
+      if (!this.dispatchXformDone()) return;
     }
     this.state = State.DONE;
     if (this.dispatchTo("done")) {
@@ -161,8 +158,7 @@ class Subscription {
       try {
         s[type] && s[type](x);
       } catch (e) {
-        if (!this.error(e))
-          return false;
+        if (!this.error(e)) return false;
       }
     }
     const subs = type === "next" ? this.subs : [...this.subs];

package/sync-raf.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import { type CommonOpts, type ISubscribable } from "./api.js";
 import { Subscription } from "./subscription.js";
 /**
@@ -13,7 +12,7 @@ import { Subscription } from "./subscription.js";
  * See {@link sidechainTrigger} from a similar & more general construct.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/sync-raf.ts
  * import { defAtom } from "@thi.ng/atom";
  * import { fromAtom, syncRAF } from "@thi.ng/rstream";
  *

package/sync-raf.js

@@ -10,13 +10,11 @@ class SyncRAF extends Subscription {
     super(void 0, opts);
   }
   next(x) {
-    if (this.state >= State.DONE)
-      return;
+    if (this.state >= State.DONE) return;
     this.queued = x;
     if (!this.raf) {
       const update = () => {
-        if (this.state < State.DONE)
-          super.next(this.queued);
+        if (this.state < State.DONE) super.next(this.queued);
         this._clean();
       };
       this.raf = isNode() ? setTimeout(update, 16) : requestAnimationFrame(update);

package/sync.d.ts

@@ -92,15 +92,25 @@ export interface StreamSyncOpts<A extends IObjectOf<ISubscribable<any>>, B = Syn
  * package. See this function's docs for further details.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/sync.ts
  * import { stream, sync, trace } from "@thi.ng/rstream";
  *
- * const a = stream();
- * const b = stream();
- * s = sync({ src: { a, b } }).subscribe(trace("result: "));
+ * const a = stream<number>();
+ * const b = stream<number>();
+ *
+ * const main = sync({ src: { a, b } }).subscribe(trace("result: "));
+ *
  * a.next(1);
+ * // main received value, but does not yet emit...
+ *
  * b.next(2);
+ * // now that `b` has delivered a value, `main` will produce its 1st result tuple
  * // result: { a: 1, b: 2 }
+ *
+ * // any further input changes will trigger new results
+ * // (with cached values from other inputs)
+ * b.next(3);
+ * // result: { a: 1, b: 3 }
  * ```
  *
  * Also see: {@link StreamSyncOpts}

package/toggle.d.ts

@@ -6,7 +6,7 @@ import { Subscription } from "./subscription.js";
  * `initial` value.
  *
  * @examples
- * ```ts
+ * ```ts tangle:../export/toggle.ts
  * import { toggle, trace } from "@thi.ng/rstream";
  *
  * const mute = toggle(false);

package/transduce.d.ts

@@ -9,7 +9,7 @@ import type { Subscription } from "./subscription.js";
  * the final reduced result (or fail with error).
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/transduce.ts
  * import { fromIterable, transduce } from "@thi.ng/rstream";
  * import { add, map, range } from "@thi.ng/transducers";
  *

package/tween.d.ts

@@ -21,10 +21,10 @@ import { type ISubscribable } from "./api.js";
  * `clock` are exhausted.
  *
  * @example
- * ```ts
- * import { stream, tween } from "@thi.ng/rstream";
+ * ```ts tangle:../export/tween.ts
+ * import { stream, tween, trace } from "@thi.ng/rstream";
  *
- * val = stream();
+ * const val = stream<number>();
  *
  * tween(
  *   // consume from `val` stream
@@ -37,17 +37,20 @@ import { type ISubscribable } from "./api.js";
  *   (a, b) => Math.abs(a - b) < 0.01
  * ).subscribe(trace("tweened"))
  *
- * a.next(10)
+ * val.next(10)
  * // 5
  * // 7.5
  * // ...
  * // 9.98046875
  *
- * a.next(100)
+ * val.next(100)
  * // 55
  * // 77.5
  * // ...
  * // 99.989013671875
+ *
+ * // terminate after 1sec
+ * setTimeout(() => val.done(), 1000);
  * ```
  *
  * @param src -

package/view.d.ts

@@ -13,7 +13,7 @@ export type FromViewUnsafeOpts<T> = FromViewOpts<Path, any, T>;
  * or tuple.
 
  * @example
- * ```ts
+ * ```ts tangle:../export/from-view-unsafe.ts
  * import { defAtom } from "@thi.ng/atom";
  * import { fromViewUnsafe, trace } from "@thi.ng/rstream";
  *
@@ -69,22 +69,27 @@ export declare const fromViewUnsafe: <T>(atom: ReadonlyAtom<any>, opts: FromView
  * [`defViewUnsafe()`](https://docs.thi.ng/umbrella/atom/functions/defViewUnsafe.html)
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/from-view.ts
  * import { defAtom } from "@thi.ng/atom";
  * import { fromView, trace } from "@thi.ng/rstream";
  *
- * const db = defAtom<any>({ a: 1, b: { c: 2 }});
+ * interface DB {
+ *   a: number;
+ *   b?: { c: number; }
+ * }
+ *
+ * const db = defAtom<DB>({ a: 1, b: { c: 2 }});
  *
  * fromView(
  *   db,
  *   {
- *     path: ["b,"c"],
+ *     path: ["b", "c"],
  *     tx: (x) => x != null ? String(x) : "n/a"
  *   }
  * ).subscribe(trace("view:"))
  * // view: 2
  *
- * db.swapIn(["b","c"], (x) => x + 1);
+ * db.swapIn(["b","c"], (x) => x! + 1);
  * // view: 3
  *
  * db.reset({ a: 10 });

package/worker.d.ts

@@ -23,11 +23,6 @@ export interface FromWorkerOpts extends WithErrorHandlerOpts {
  * instance, a JS source code `Blob` or an URL string. In the latter two
  * cases, a worker is created automatically.
  *
- * @example
- * ```ts
- *
- * ```
- *
  * @param worker -
  * @param opts -
  */