@thi.ng/rstream 7.2.46 → 8.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-03-27T19:05:48Z
+- **Last updated**: 2023-04-08T11:09:50Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,39 @@ 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.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/rstream@8.0.0) (2023-04-08)
+
+#### 🛑 Breaking changes
+
+- simplify/unify sidechain API ([5e90431](https://github.com/thi-ng/umbrella/commit/5e90431))
+- BREAKING CHANGE: simplify/unify sidechain subscription API
+  - update sidechainPartition/Toggle/Trigger() to take src sub as 1st arg
+    - old: `src.subscribe(sidechainXXX(side))`...
+    - new: `sidechainXXX(src, side)`
+  - update docs
+  - update tests
+
+#### 🚀 Features
+
+- add syncRAF() ([3c17520](https://github.com/thi-ng/umbrella/commit/3c17520))
+  - add SyncRAF class and syncRAF() factory
+  - deprecate sidechainPartitionRAF()
+  - add tests
+- add sidechainTrigger() ([3d2b56d](https://github.com/thi-ng/umbrella/commit/3d2b56d))
+- add timestamp support for fromRAF() ([a2b8629](https://github.com/thi-ng/umbrella/commit/a2b8629))
+  - add FromRAFOpts
+  - update docs
+
+#### 🩹 Bug fixes
+
+- fix opts handling in syncRAF() & fromView() ([baa8878](https://github.com/thi-ng/umbrella/commit/baa8878))
+
+#### ♻️ Refactoring
+
+- update KeyStreams type ([1dd60e9](https://github.com/thi-ng/umbrella/commit/1dd60e9))
+  - switch value types Subscription => ISubscription
+- minor update sidechainPartition/Toggle() ([c3ffd38](https://github.com/thi-ng/umbrella/commit/c3ffd38))
+
 ### [7.2.46](https://github.com/thi-ng/umbrella/tree/@thi.ng/rstream@7.2.46) (2023-03-27)
 
 #### ♻️ Refactoring

package/README.md

@@ -35,6 +35,7 @@ This project is part of the
   - [Side-chaining](#side-chaining)
     - [Input chunking / buffering, controlled by sidechain](#input-chunking--buffering-controlled-by-sidechain)
     - [Input toggling, controlled by sidechain](#input-toggling-controlled-by-sidechain)
+    - [Input passthrough, controlled by sidechain](#input-passthrough-controlled-by-sidechain)
   - [Worker support](#worker-support)
     - [Parallel stream processing via workers](#parallel-stream-processing-via-workers)
     - [Stream processing via workers](#stream-processing-via-workers)
@@ -196,7 +197,7 @@ For Node.js REPL:
 const rstream = await import("@thi.ng/rstream");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 5.63 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 5.80 KB
 
 ## Dependencies
 
@@ -237,6 +238,7 @@ A selection:
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/parse-playground.png" width="240"/>              | Parser grammar livecoding editor/playground & codegen                            | [Demo](https://demo.thi.ng/umbrella/parse-playground/)     | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/parse-playground)    |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/pixel-sorting.png" width="240"/>                 | Interactive pixel sorting tool using thi.ng/color & thi.ng/pixel                 | [Demo](https://demo.thi.ng/umbrella/pixel-sorting/)        | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/pixel-sorting)       |
 |                                                                                                                                      | Demonstates various rdom usage patterns                                          | [Demo](https://demo.thi.ng/umbrella/rdom-basics/)          | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rdom-basics)         |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rdom-canvas-basics.png" width="240"/>            | Minimal rdom-canvas animation                                                    | [Demo](https://demo.thi.ng/umbrella/rdom-canvas-basics/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rdom-canvas-basics)  |
 | <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-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)    |
@@ -246,9 +248,11 @@ A selection:
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rstream-grid.jpg" width="240"/>                  | Interactive grid generator, SVG generation & export, undo/redo support           | [Demo](https://demo.thi.ng/umbrella/rstream-grid/)         | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rstream-grid)        |
 |                                                                                                                                      | rstream based UI updates & state handling                                        | [Demo](https://demo.thi.ng/umbrella/rstream-hdom/)         | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rstream-hdom)        |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rstream-spreadsheet.png" width="240"/>           | rstream based spreadsheet w/ S-expression formula DSL                            | [Demo](https://demo.thi.ng/umbrella/rstream-spreadsheet/)  | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rstream-spreadsheet) |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rstream-sync.png" width="240"/>                  | Minimal rstream sync() example using rdom                                        | [Demo](https://demo.thi.ng/umbrella/rstream-sync/)         | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rstream-sync)        |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/shader-ast-workers.jpg" width="240"/>            | Fork-join worker-based raymarch renderer (JS/CPU only)                           | [Demo](https://demo.thi.ng/umbrella/shader-ast-workers/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/shader-ast-workers)  |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/svg-resample.png" width="240"/>                  | SVG path parsing & dynamic resampling                                            | [Demo](https://demo.thi.ng/umbrella/svg-resample/)         | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/svg-resample)        |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/talk-slides.png" width="240"/>                   | hdom based slide deck viewer & slides from my ClojureX 2018 keynote              | [Demo](http://media.thi.ng/2018/talks/clojurex/index.html) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/talk-slides)         |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/trace-bitmap.jpg" width="240"/>                  | Multi-layer vectorization & dithering of bitmap images                           | [Demo](https://demo.thi.ng/umbrella/trace-bitmap/)         | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/trace-bitmap)        |
 |                                                                                                                                      | Transducer & rstream based hdom UI updates                                       | [Demo](https://demo.thi.ng/umbrella/transducers-hdom/)     | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/transducers-hdom)    |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/webgl-channel-mixer.jpg" width="240"/>           | rdom & WebGL-based image channel editor                                          | [Demo](https://demo.thi.ng/umbrella/webgl-channel-mixer/)  | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/webgl-channel-mixer) |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/webgl-cubemap.jpg" width="240"/>                 | WebGL cube maps with async texture loading                                       | [Demo](https://demo.thi.ng/umbrella/webgl-cubemap/)        | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/webgl-cubemap)       |
@@ -304,7 +308,7 @@ interface CommonOpts {
 
 #### Stream
 
-Source: [stream()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/stream.ts)
+Docs: [stream()](https://docs.thi.ng/umbrella/rstream/functions/stream-1.html)
 
 Creates a new `Stream` instance, optionally with given `StreamSource`
 function and / or ID. If a `src` function is provided, the function
@@ -361,7 +365,7 @@ will always return `undefined`.
 
 #### Subscription
 
-Source: [subscription()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/subscription.ts)
+Docs: [subscription()](https://docs.thi.ng/umbrella/rstream/functions/subscription-1.html)
 
 Creates a new `Subscription` instance, the fundamental datatype &
 building block provided by this package (`Stream`s are `Subscription`s
@@ -393,25 +397,26 @@ s.next(42);
 
 #### Other stream creation helpers
 
-- [reactive()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/stream.ts) - syntax sugar for `stream()` with initial value
-- [fromAtom()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/atom.ts) - streams from value changes in atoms/cursors
+- [reactive()](https://docs.thi.ng/umbrella/rstream/functions/reactive.html) - syntax sugar for `stream()` with initial value
+- [fromAtom()](https://docs.thi.ng/umbrella/rstream/functions/fromAtom.html) - streams from value changes in atoms/cursors
 - [fromChannel()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream-csp) - CSP channel to stream conversion
-- [fromEvent()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/event.ts) - events
-- [fromDOMEvent()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/event.ts#L25) - DOM events
-- [fromInterval()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/interval.ts) - interval based counters
-- [fromIterable()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/iterable.ts) - arrays, iterators / generators (async & sync)
-- [fromNodeJS() / linesFromNodeJS()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/nodejs.ts) - NodeJS streams adapters
-- [fromObject()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/object.ts) - object property streams
-- [fromPromise()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/promise.ts) - single value stream from promise
-- [fromPromises()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/promises.ts) - results from multiple promise
-- [fromRAF()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/raf.ts) - requestAnimationFrame() counter (w/ node fallback)
-- [fromView()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/view.ts) - derived view changes (see [@thi.ng/atom](https://github.com/thi-ng/umbrella/tree/develop/packages/atom))
-- [fromWorker()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/worker.ts) - messages received from worker
-- [trigger()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/trigger.ts) - one-off events
+- [fromEvent()](https://docs.thi.ng/umbrella/rstream/functions/fromEvent.html) - events
+- [fromDOMEvent()](https://docs.thi.ng/umbrella/rstream/functions/fromDOMEvent.html) - DOM events
+- [fromInterval()](https://docs.thi.ng/umbrella/rstream/functions/fromInterval.html) - interval based counters
+- [fromIterable()](https://docs.thi.ng/umbrella/rstream/functions/fromIterable.html) - arrays, iterators / generators (async & sync)
+- [fromNodeJS()](https://docs.thi.ng/umbrella/rstream/functions/fromNodeJS.html) - NodeJS stream adapter
+- [linesFromNodeJS()](https://docs.thi.ng/umbrella/rstream/functions/linesFromNodeJS.html) - NodeJS stream adapter
+- [fromObject()](https://docs.thi.ng/umbrella/rstream/functions/fromObject.html) - object property streams
+- [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)
+- [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
+- [trigger()](https://docs.thi.ng/umbrella/rstream/functions/trigger.html) - one-off events
 
 ### Meta streams
 
-Source: [metaStream()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/metastream.ts)
+Docs: [metaStream()](https://docs.thi.ng/umbrella/rstream/functions/metaStream-1.html)
 
 `MetaStream`s are streams of streams. A `MetaStream` is a subscription
 type which transforms each incoming value into a new stream, subscribes
@@ -496,7 +501,7 @@ m.next(true);
 
 #### Unordered merge from multiple inputs (dynamic add/remove)
 
-Source: [merge()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/stream-merge.ts)
+Docs: [merge()](https://docs.thi.ng/umbrella/rstream/functions/merge.html)
 
 ![diagram](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/rstream/rstream-merge.png)
 
@@ -528,9 +533,8 @@ merge({
 ```
 
 Use the [`labeled()`
-transducer](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/xform/labeled.ts)
-for each input to create a stream of labeled values and track their
-provenance:
+transducer](https://docs.thi.ng/umbrella/transducers/functions/labeled.html) for
+each input to create a stream of labeled values and track their provenance:
 
 ```ts
 merge({
@@ -548,7 +552,7 @@ merge({
 ```
 
 See
-[StreamMergeOpts](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/stream-merge.ts#L7)
+[StreamMergeOpts](https://docs.thi.ng/umbrella/rstream/interfaces/StreamMergeOpts.html)
 for further reference of the various behavior options.
 
 ##### Adding inputs automatically
@@ -559,8 +563,10 @@ as new input to the merge and then automatically remove once that stream
 is exhausted.
 
 ```ts
+import { repeat } from "@thi.ng/transducers";
+
 // stream source w/ transducer mapping values to new streams
-a = stream().transform(tx.map((x) => fromIterable(tx.repeat(x, 3))));
+a = stream().map((x) => fromIterable(repeat(x, 3)));
 // simple 1Hz counter
 b = fromInterval(1000);
 
@@ -571,17 +577,17 @@ merge({ src: [a, b] }).subscribe(trace());
 
 // sent "a" will be transformed into stream via above transducer
 // and then auto-added as new input to the StreamMerge
-a.next("a");
-// a
-// a
-// a
+a.next("abc");
+// abc
+// abc
+// abc
 // 3
 // 4
 ```
 
 #### Synchronized merge and labeled tuple objects
 
-Source: [sync()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/stream-sync.ts)
+Docs: [sync()](https://docs.thi.ng/umbrella/rstream/functions/sync.html)
 
 ![diagram](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/rstream/rstream-sync.png)
 
@@ -622,19 +628,20 @@ be incomplete, by default. To only allow complete tuples, also set the
 `all` option to `false`.
 
 The synchronization is done via the
-[`partitionSync()`](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/xform/partition-sync.ts)
-transducer from the @thi.ng/transducers package. See this function's
-docs for further details.
+[`partitionSync()`](https://docs.thi.ng/umbrella/transducers/functions/partitionSync-1.html)
+transducer from the
+[@thi.ng/transducers](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers)
+package. See this function's docs for further details.
 
 See
-[StreamSyncOpts](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/stream-sync.ts#L12)
+[StreamSyncOpts](https://docs.thi.ng/umbrella/rstream/interfaces/StreamSyncOpts.html)
 for further reference of the various behavior options.
 
 ### Stream splitting
 
 #### Topic based splitting
 
-Source: [pubsub()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/pubsub.ts)
+Docs: [pubsub()](https://docs.thi.ng/umbrella/rstream/functions/pubsub-1.html)
 
 ![diagram](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/rstream/rstream-pubsub.png)
 
@@ -659,7 +666,7 @@ called WITHOUT argument to unsubscribe the entire `PubSub` instance
 
 #### Splitting via predicate
 
-Source: [bisect()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/bisect.ts)
+Docs: [bisect()](https://docs.thi.ng/umbrella/rstream/functions/bisect.html)
 
 Returns a new `PubSub` instance using given predicate `pred` as boolean
 topic function and `a` & `b` as subscribers for truthy (`a`) and falsy
@@ -704,7 +711,7 @@ fromIterable([1, 2, 3, 4]).subscribe(bisect((x) => !!(x & 1), odd, even));
 
 #### Input chunking / buffering, controlled by sidechain
 
-Source: [sidechainPartition()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/sidechain-partition.ts)
+Docs: [sidechainPartition()](https://docs.thi.ng/umbrella/rstream/functions/sidechainPartition-1.html)
 
 ![diagram](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/rstream/rstream-sidechain-partition.png)
 
@@ -715,21 +722,25 @@ optional predicate can be used to only trigger for specific values /
 conditions.
 
 ```ts
-// merge various event streams
-merge([
-    fromEvent(document, "mousemove"),
-    fromEvent(document, "mousedown"),
-    fromEvent(document, "mouseup")
-])
-    // queue event processing to only execute during the
-    // requestAnimationFrame cycle (RAF)
-    .subscribe(sidechainPartition(fromRAF()))
-    .subscribe(trace());
+// queue event processing to only execute during the
+// requestAnimationFrame cycle (RAF)
+sidechainPartition(
+    // merge various event streams
+    merge([
+        fromEvent(document, "mousemove"),
+        fromEvent(document, "mousedown"),
+        fromEvent(document, "mouseup")
+    ]),
+    // sidechain control stream
+    fromRAF()
+).subscribe(trace());
 ```
 
+Since v8.0.0 there's [`syncRAF()`](https://docs.thi.ng/umbrella/rstream/functions/syncRAF-1.html)
+
 #### Input toggling, controlled by sidechain
 
-Source: [sidechainToggle()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/sidechain-toggle.ts)
+Docs: [sidechainToggle()](https://docs.thi.ng/umbrella/rstream/functions/sidechainToggle-1.html)
 
 ![diagram](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/rstream/rstream-sidechain-toggle.png)
 
@@ -741,10 +752,8 @@ will be toggled on/off. Whilst switched off, no input values will be
 forwarded.
 
 ```ts
-// use slower interval stream to toggle main stream on/off
-fromInterval(500)
-  .subscribe(sidechainToggle(fromInterval(1000)))
-  .subscribe(trace());
+// use slower interval stream to toggle faster main stream on/off
+sidechainToggle(fromInterval(500), fromInterval(1000)).subscribe(trace());
 // 0
 // 3
 // 4
@@ -753,11 +762,41 @@ fromInterval(500)
 ...
 ```
 
+#### Input passthrough, controlled by sidechain
+
+Docs: [sidechainTrigger()](https://docs.thi.ng/umbrella/rstream/functions/sidechainTrigger-1.html)
+
+Buffers the most recent value received and only forwards it downstream whenever
+a new control value is received from the sidechain.
+
+```ts
+const src = reactive("payload");
+
+const side = stream();
+
+sidechainTrigger(src, side).subscribe(trace("data:"));
+
+side.next(1);
+// data: payload
+
+// every time sidechain triggers
+side.next(1);
+// data: payload
+
+// only newest value will be buffered
+src.next("update #1");
+src.next("update #2");
+
+// ...until side chain triggers again
+side.next(1);
+// data: update #2
+```
+
 ### Worker support
 
 #### Parallel stream processing via workers
 
-Source: [forkJoin()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/forkjoin.ts)
+Docs: [forkJoin()](https://docs.thi.ng/umbrella/rstream/functions/forkJoin.html)
 
 ![diagram](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/rstream/rstream-forkjoin.png)
 
@@ -806,27 +845,27 @@ src.next(new Array(16).fill(1));
 
 #### Stream processing via workers
 
-Source: [tunnel()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/tunnel.ts)
+Docs: [tunnel()](https://docs.thi.ng/umbrella/rstream/functions/tunnel-1.html)
 
 Delegate stream value processing to workers and pass on their responses
 to downstream subscriptions. Supports multiple worker instances and
 worker termination / restart for each new stream value received.
 
-Source: [postWorker()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/post-worker.ts)
+Docs: [postWorker()](https://docs.thi.ng/umbrella/rstream/functions/postWorker.html)
 
 Send values to workers (incl. optional (inline) worker instantiation)
 
-Source: [fromWorker()](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/worker.ts)
+Docs: [fromWorker()](https://docs.thi.ng/umbrella/rstream/functions/fromWorker.html)
 
 Create value stream from worker messages.
 
 ### Other subscription ops
 
-- [debounce](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/debounce.ts) - ignore high frequency interim values
-- [resolve](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/resolve.ts) - resolve on-stream promises
-- [trace](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/trace.ts) - debug helper
-- [transduce](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/transduce.ts) - transduce or just reduce an entire stream into a promise
-- [tween](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream/src/tween.ts) - stream interpolation
+- [debounce](https://docs.thi.ng/umbrella/rstream/functions/debounce.html): ignore high frequency interim values
+- [resolve](https://docs.thi.ng/umbrella/rstream/functions/resolve.html): resolve on-stream promises
+- [trace](https://docs.thi.ng/umbrella/rstream/functions/trace.html): debug helper
+- [transduce](https://docs.thi.ng/umbrella/rstream/functions/transduce.html): transduce or just reduce an entire stream into a promise
+- [tween](https://docs.thi.ng/umbrella/rstream/functions/tween.html): stream interpolation
 
 ### Error handling
 

package/index.d.ts

@@ -23,9 +23,11 @@ export * from "./raf.js";
 export * from "./resolve.js";
 export * from "./sidechain-partition.js";
 export * from "./sidechain-toggle.js";
+export * from "./sidechain-trigger.js";
 export * from "./stream.js";
 export * from "./subscription.js";
 export * from "./sync.js";
+export * from "./sync-raf.js";
 export * from "./timeout.js";
 export * from "./trace.js";
 export * from "./transduce.js";

package/index.js

@@ -23,9 +23,11 @@ export * from "./raf.js";
 export * from "./resolve.js";
 export * from "./sidechain-partition.js";
 export * from "./sidechain-toggle.js";
+export * from "./sidechain-trigger.js";
 export * from "./stream.js";
 export * from "./subscription.js";
 export * from "./sync.js";
+export * from "./sync-raf.js";
 export * from "./timeout.js";
 export * from "./trace.js";
 export * from "./transduce.js";

package/iterable.d.ts

@@ -26,10 +26,10 @@ export interface FromIterableOpts extends CommonOpts {
 export declare const fromIterable: <T>(src: Iterable<T>, opts?: Partial<FromIterableOpts>) => import("./stream.js").Stream<T>;
 /**
  * Creates a new {@link Stream} of given iterable which synchronously calls
- * `.next()` for each item of the iterable when the first (and in this
- * case the only one) subscriber becomes available. Once the iterable is
- * exhausted (MUST be finite!), then calls `.done()` by default, but can
- * be avoided by passing `false` as last argument.
+ * {@link ISubscriber.next} for each item of the iterable when the first (and in
+ * this case the only one) subscriber becomes available. Once the iterable is
+ * exhausted (MUST be finite!), then calls {@link ISubscriber.done} by default,
+ * but can be avoided by passing `false` as last argument.
  *
  * @param src -
  * @param opts -

package/iterable.js

@@ -32,10 +32,10 @@ export const fromIterable = (src, opts = {}) => stream((stream) => {
 }, __optsWithID("iterable", opts));
 /**
  * Creates a new {@link Stream} of given iterable which synchronously calls
- * `.next()` for each item of the iterable when the first (and in this
- * case the only one) subscriber becomes available. Once the iterable is
- * exhausted (MUST be finite!), then calls `.done()` by default, but can
- * be avoided by passing `false` as last argument.
+ * {@link ISubscriber.next} for each item of the iterable when the first (and in
+ * this case the only one) subscriber becomes available. Once the iterable is
+ * exhausted (MUST be finite!), then calls {@link ISubscriber.done} by default,
+ * but can be avoided by passing `false` as last argument.
  *
  * @param src -
  * @param opts -

package/object.d.ts

@@ -1,8 +1,7 @@
 import type { Keys, Predicate2 } from "@thi.ng/api";
-import type { CommonOpts } from "./api.js";
-import { type Subscription } from "./subscription.js";
+import type { CommonOpts, ISubscription } from "./api.js";
 export type KeyStreams<T, K extends Keys<T>> = {
-    [id in K]-?: Subscription<T[id], T[id]>;
+    [id in K]-?: ISubscription<T[id], T[id]>;
 };
 /**
  * Result object type for {@link fromObject}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/rstream",
-  "version": "7.2.46",
+  "version": "8.0.0",
   "description": "Reactive streams & subscription primitives for constructing dataflow graphs / pipelines",
   "type": "module",
   "module": "./index.js",
@@ -38,22 +38,22 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.7.5",
-    "@thi.ng/arrays": "^2.5.9",
-    "@thi.ng/associative": "^6.2.33",
-    "@thi.ng/atom": "^5.1.34",
-    "@thi.ng/checks": "^3.3.11",
-    "@thi.ng/errors": "^2.2.14",
-    "@thi.ng/logger": "^1.4.12",
-    "@thi.ng/transducers": "^8.4.1"
+    "@thi.ng/api": "^8.7.6",
+    "@thi.ng/arrays": "^2.5.10",
+    "@thi.ng/associative": "^6.2.34",
+    "@thi.ng/atom": "^5.2.0",
+    "@thi.ng/checks": "^3.3.12",
+    "@thi.ng/errors": "^2.2.15",
+    "@thi.ng/logger": "^1.4.13",
+    "@thi.ng/transducers": "^8.4.2"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.34.4",
-    "@thi.ng/testament": "^0.3.14",
+    "@thi.ng/testament": "^0.3.15",
     "rimraf": "^4.4.1",
     "tools": "^0.0.1",
     "typedoc": "^0.23.28",
-    "typescript": "^5.0.2"
+    "typescript": "^5.0.4"
   },
   "keywords": [
     "async",
@@ -162,12 +162,18 @@
     "./sidechain-toggle": {
       "default": "./sidechain-toggle.js"
     },
+    "./sidechain-trigger": {
+      "default": "./sidechain-trigger.js"
+    },
     "./stream": {
       "default": "./stream.js"
     },
     "./subscription": {
       "default": "./subscription.js"
     },
+    "./sync-raf": {
+      "default": "./sync-raf.js"
+    },
     "./sync": {
       "default": "./sync.js"
     },
@@ -205,5 +211,5 @@
     ],
     "year": 2017
   },
-  "gitHead": "83b15b34326d480cbca0472b20390d4d3bbb792a\n"
+  "gitHead": "abcedd9e4e06a4b631f363610eec572f79b571c1\n"
 }

package/raf.d.ts

@@ -1,15 +1,26 @@
 import type { CommonOpts } from "./api.js";
+export interface FromRAFOpts extends CommonOpts {
+    /**
+     * Browser only. If true (default: false), passes the timestamps received
+     * via `requestAnimationFrame()` as stream values. If false, a simple
+     * counter [0..∞) will be emitted.
+     *
+     * @defaultValue false
+     */
+    timestamp: boolean;
+}
 /**
- * Yields {@link Stream} of a monotonically increasing counter,
- * triggered by a `requestAnimationFrame()` loop (only available in
- * browser environments).
+ * Yields {@link Stream} of a monotonically increasing counter (or timestamps),
+ * triggered by a `requestAnimationFrame()` loop (only available in browser
+ * environments).
  *
  * @remarks
- * In NodeJS, this function falls back to {@link fromInterval}, yielding
- * a similar (approx. 60Hz) stream.
+ * In NodeJS, this function falls back to {@link fromInterval}, yielding a
+ * similar (approx. 60Hz) stream (the {@link FromRAFOpts.timestamp} option will
+ * be ignored).
  *
- * All subscribers to this stream will be processed during that same
- * loop iteration.
+ * All subscribers to this stream will be processed during that same RAF loop
+ * iteration.
  */
-export declare const fromRAF: (opts?: Partial<CommonOpts>) => import("./stream.js").Stream<number>;
+export declare const fromRAF: (opts?: Partial<FromRAFOpts>) => import("./stream.js").Stream<number>;
 //# sourceMappingURL=raf.d.ts.map

package/raf.js

@@ -3,24 +3,25 @@ import { __optsWithID } from "./idgen.js";
 import { fromInterval } from "./interval.js";
 import { stream } from "./stream.js";
 /**
- * Yields {@link Stream} of a monotonically increasing counter,
- * triggered by a `requestAnimationFrame()` loop (only available in
- * browser environments).
+ * Yields {@link Stream} of a monotonically increasing counter (or timestamps),
+ * triggered by a `requestAnimationFrame()` loop (only available in browser
+ * environments).
  *
  * @remarks
- * In NodeJS, this function falls back to {@link fromInterval}, yielding
- * a similar (approx. 60Hz) stream.
+ * In NodeJS, this function falls back to {@link fromInterval}, yielding a
+ * similar (approx. 60Hz) stream (the {@link FromRAFOpts.timestamp} option will
+ * be ignored).
  *
- * All subscribers to this stream will be processed during that same
- * loop iteration.
+ * All subscribers to this stream will be processed during that same RAF loop
+ * iteration.
  */
-export const fromRAF = (opts) => isNode()
+export const fromRAF = (opts = {}) => isNode()
     ? fromInterval(16, opts)
     : stream((stream) => {
         let i = 0;
         let isActive = true;
-        const loop = () => {
-            isActive && stream.next(i++);
+        const loop = (time) => {
+            isActive && stream.next(opts.timestamp ? time : i++);
             isActive && (id = requestAnimationFrame(loop));
         };
         let id = requestAnimationFrame(loop);

package/sidechain-partition.d.ts

@@ -1,19 +1,20 @@
 import type { Predicate } from "@thi.ng/api";
-import { type CommonOpts, type ISubscribable } from "./api.js";
+import { type CommonOpts, type ISubscribable, type ISubscription } from "./api.js";
 import { ASidechain } from "./asidechain.js";
-import type { Subscription } from "./subscription.js";
 export interface SidechainPartitionOpts<T> extends CommonOpts {
     pred: Predicate<T>;
 }
 /**
- * Returns a {@link Subscription} which buffers values from `src` until
- * side chain fires, then emits buffer (unless empty) and repeats
- * process until either input is done.
+ * Returns a subscription which buffers values from `src` until side chain
+ * delivers its next value, then emits buffer (unless empty) and repeats process
+ * until either input is done.
  *
  * @remarks
- * By default, the values read from the side chain are ignored (i.e.
- * only their timing is used), however the `pred`icate option can be
- * used to only trigger for specific values / conditions.
+ * By default, the values read from the side chain are ignored (i.e. only their
+ * timing is used), however the `pred`icate option can be used to only trigger
+ * for specific values / conditions.
+ *
+ * Also see: {@link sidechainToggle}, {@link sidechainTrigger}, {@link syncRAF}.
  *
  * @example
  * ```t
@@ -26,23 +27,45 @@ export interface SidechainPartitionOpts<T> extends CommonOpts {
  *
  * // queue event processing to only execute during the
  * // requestAnimationFrame cycle (RAF)
- * events.subscribe(sidechainPartition(fromRAF())).subscribe(trace())
+ * sidechainPartition(events, fromRAF()).subscribe(trace())
  * ```
  *
+ * @param src -
  * @param side -
  * @param opts -
  */
-export declare const sidechainPartition: <A, B>(side: ISubscribable<B>, opts?: Partial<SidechainPartitionOpts<B>> | undefined) => Subscription<A, A[]>;
+export declare const sidechainPartition: <T, S>(src: ISubscribable<T>, side: ISubscribable<S>, opts?: Partial<SidechainPartitionOpts<S>> | undefined) => ISubscription<T, T[]>;
 /**
- * Syntax sugar for one of most common {@link sidechainPartition} use cases, to
- * synchronize downstream processing w/ `requestAnimationFrame()`. The returned
- * subscription debounces any high frequency intra-frame input values and (if
- * any present), passes only most recent one downstream *during* next RAF event
- * processing.
+ * **Deprecated** syntax sugar for one of most common {@link sidechainPartition}
+ * use cases, to synchronize downstream processing w/ `requestAnimationFrame()`.
+ * Please use {@link syncRAF} instead.
+ *
+ * @remarks
+ * The returned subscription debounces any high frequency intra-frame input
+ * values and (if any present), passes only most recent one downstream during
+ * next RAF event processing.
+ *
+ * This example uses thi.ng/atom as state container. Also see {@link fromAtom}
+ * and {@link syncRAF}.
+ *
+ * @example
+ * ```ts
+ * 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; }
+ * });
+ *
+ * // trigger update
+ * atom.reset("bob");
+ * ```
  *
  * @param src -
+ *
+ * @deprecated
  */
-export declare const sidechainPartitionRAF: <T>(src: ISubscribable<T>) => import("./api.js").ISubscription<T[], T>;
+export declare const sidechainPartitionRAF: <T>(src: ISubscribable<T>) => ISubscription<T[], T>;
 export declare class SidechainPartition<T, S> extends ASidechain<T, S, T[]> {
     buf: T[];
     constructor(side: ISubscribable<S>, opts?: Partial<SidechainPartitionOpts<S>>);

package/sidechain-partition.js

@@ -1,18 +1,20 @@
 import { peek } from "@thi.ng/arrays/peek";
 import { map } from "@thi.ng/transducers/map";
-import { State } from "./api.js";
+import { State, } from "./api.js";
 import { ASidechain } from "./asidechain.js";
 import { __optsWithID } from "./idgen.js";
 import { fromRAF } from "./raf.js";
 /**
- * Returns a {@link Subscription} which buffers values from `src` until
- * side chain fires, then emits buffer (unless empty) and repeats
- * process until either input is done.
+ * Returns a subscription which buffers values from `src` until side chain
+ * delivers its next value, then emits buffer (unless empty) and repeats process
+ * until either input is done.
  *
  * @remarks
- * By default, the values read from the side chain are ignored (i.e.
- * only their timing is used), however the `pred`icate option can be
- * used to only trigger for specific values / conditions.
+ * By default, the values read from the side chain are ignored (i.e. only their
+ * timing is used), however the `pred`icate option can be used to only trigger
+ * for specific values / conditions.
+ *
+ * Also see: {@link sidechainToggle}, {@link sidechainTrigger}, {@link syncRAF}.
  *
  * @example
  * ```t
@@ -25,45 +27,64 @@ import { fromRAF } from "./raf.js";
  *
  * // queue event processing to only execute during the
  * // requestAnimationFrame cycle (RAF)
- * events.subscribe(sidechainPartition(fromRAF())).subscribe(trace())
+ * sidechainPartition(events, fromRAF()).subscribe(trace())
  * ```
  *
+ * @param src -
  * @param side -
  * @param opts -
  */
-export const sidechainPartition = (side, opts) => new SidechainPartition(side, opts);
+export const sidechainPartition = (src, side, opts) => src.subscribe(new SidechainPartition(side, opts));
 /**
- * Syntax sugar for one of most common {@link sidechainPartition} use cases, to
- * synchronize downstream processing w/ `requestAnimationFrame()`. The returned
- * subscription debounces any high frequency intra-frame input values and (if
- * any present), passes only most recent one downstream *during* next RAF event
- * processing.
+ * **Deprecated** syntax sugar for one of most common {@link sidechainPartition}
+ * use cases, to synchronize downstream processing w/ `requestAnimationFrame()`.
+ * Please use {@link syncRAF} instead.
+ *
+ * @remarks
+ * The returned subscription debounces any high frequency intra-frame input
+ * values and (if any present), passes only most recent one downstream during
+ * next RAF event processing.
+ *
+ * This example uses thi.ng/atom as state container. Also see {@link fromAtom}
+ * and {@link syncRAF}.
+ *
+ * @example
+ * ```ts
+ * 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; }
+ * });
+ *
+ * // trigger update
+ * atom.reset("bob");
+ * ```
  *
  * @param src -
+ *
+ * @deprecated
  */
-export const sidechainPartitionRAF = (src) => src
-    .subscribe(sidechainPartition(fromRAF()))
-    .transform(map(peek));
+export const sidechainPartitionRAF = (src) => sidechainPartition(src, fromRAF()).transform(map(peek));
 export class SidechainPartition extends ASidechain {
     constructor(side, opts) {
         opts = __optsWithID("sidepart", opts);
         super(opts);
-        this.buf = [];
         const pred = opts.pred || (() => true);
-        const $this = this;
+        this.buf = [];
         this.sideSub = side.subscribe({
-            next(x) {
-                if ($this.buf.length && pred(x)) {
-                    $this.dispatch($this.buf);
-                    $this.buf = [];
+            next: (x) => {
+                if (this.buf.length && pred(x)) {
+                    this.dispatch(this.buf);
+                    this.buf = [];
                 }
             },
-            done() {
-                if ($this.buf.length) {
-                    $this.dispatch($this.buf);
+            done: () => {
+                if (this.buf.length) {
+                    this.dispatch(this.buf);
                 }
-                $this.done();
-                delete $this.buf;
+                this.done();
+                delete this.buf;
             },
         });
     }

package/sidechain-toggle.d.ts

@@ -1,28 +1,25 @@
 import type { Predicate } from "@thi.ng/api";
-import { type CommonOpts, type ISubscribable } from "./api.js";
+import { type CommonOpts, type ISubscribable, type ISubscription } from "./api.js";
 import { ASidechain } from "./asidechain.js";
-import type { Subscription } from "./subscription.js";
 export interface SidechainToggleOpts<T> extends CommonOpts {
     pred: Predicate<T>;
     initial: boolean;
 }
 /**
- * Returns {@link Subscription} which filters values from input based on
- * values received from side chain.
+ * Returns a subscription which filters values from `src` based on control
+ * values received from `side` chain.
  *
  * @remarks
- * By default, the value read from the side chain is ignored (i.e. only
- * their timing is used), however the `pred`icate option can be used to
- * only trigger for specific values/conditions. Every time the predicate
- * fn returns true, the filter will be toggled on/off. Whilst switched
- * off, no input values will be forwarded.
+ * By default, the values read from the side chain are ignored (i.e. only their
+ * timing is used), however the `pred`icate option can be used to only trigger
+ * for specific values/conditions. Every time the predicate fn returns true, the
+ * filter will be toggled on/off. Whilst switched off, no input values will be
+ * forwarded downstream.
  *
  * @example
  * ```ts
- * // use slower interval stream to toggle main stream on/off
- * fromInterval(500)
- *   .subscribe(sidechainToggle(fromInterval(1000)))
- *   .subscribe(trace());
+ * // use slower interval stream to toggle faster main stream on/off
+ * sidechainToggle(fromInterval(500), fromInterval(1000)).subscribe(trace());
  * // 0
  * // 3
  * // 4
@@ -31,10 +28,11 @@ export interface SidechainToggleOpts<T> extends CommonOpts {
  * ...
  * ```
  *
+ * @param src -
  * @param side -
  * @param opts -
  */
-export declare const sidechainToggle: <A, B>(side: ISubscribable<B>, opts?: Partial<SidechainToggleOpts<B>> | undefined) => Subscription<A, A>;
+export declare const sidechainToggle: <T, S>(src: ISubscribable<T>, side: ISubscribable<S>, opts?: Partial<SidechainToggleOpts<S>> | undefined) => ISubscription<T, T>;
 export declare class SidechainToggle<T, S> extends ASidechain<T, S, T> {
     isActive: boolean;
     constructor(side: ISubscribable<S>, opts?: Partial<SidechainToggleOpts<S>>);

package/sidechain-toggle.js

@@ -1,23 +1,21 @@
-import { State } from "./api.js";
+import { State, } from "./api.js";
 import { ASidechain } from "./asidechain.js";
 import { __optsWithID } from "./idgen.js";
 /**
- * Returns {@link Subscription} which filters values from input based on
- * values received from side chain.
+ * Returns a subscription which filters values from `src` based on control
+ * values received from `side` chain.
  *
  * @remarks
- * By default, the value read from the side chain is ignored (i.e. only
- * their timing is used), however the `pred`icate option can be used to
- * only trigger for specific values/conditions. Every time the predicate
- * fn returns true, the filter will be toggled on/off. Whilst switched
- * off, no input values will be forwarded.
+ * By default, the values read from the side chain are ignored (i.e. only their
+ * timing is used), however the `pred`icate option can be used to only trigger
+ * for specific values/conditions. Every time the predicate fn returns true, the
+ * filter will be toggled on/off. Whilst switched off, no input values will be
+ * forwarded downstream.
  *
  * @example
  * ```ts
- * // use slower interval stream to toggle main stream on/off
- * fromInterval(500)
- *   .subscribe(sidechainToggle(fromInterval(1000)))
- *   .subscribe(trace());
+ * // use slower interval stream to toggle faster main stream on/off
+ * sidechainToggle(fromInterval(500), fromInterval(1000)).subscribe(trace());
  * // 0
  * // 3
  * // 4
@@ -26,26 +24,24 @@ import { __optsWithID } from "./idgen.js";
  * ...
  * ```
  *
+ * @param src -
  * @param side -
  * @param opts -
  */
-export const sidechainToggle = (side, opts) => new SidechainToggle(side, opts);
+export const sidechainToggle = (src, side, opts) => src.subscribe(new SidechainToggle(side, opts));
 export class SidechainToggle extends ASidechain {
     constructor(side, opts) {
         opts = __optsWithID("sidetoggle", opts);
         super(opts);
         this.isActive = !!opts.initial;
         const pred = opts.pred || (() => true);
-        const $this = this;
         this.sideSub = side.subscribe({
-            next(x) {
+            next: (x) => {
                 if (pred(x)) {
-                    $this.isActive = !$this.isActive;
+                    this.isActive = !this.isActive;
                 }
             },
-            done() {
-                $this.done();
-            },
+            done: () => this.done(),
         });
     }
     next(x) {

package/sidechain-trigger.d.ts

@@ -0,0 +1,54 @@
+import type { Predicate } from "@thi.ng/api";
+import { SEMAPHORE } from "@thi.ng/api/api";
+import { type CommonOpts, type ISubscribable, type ISubscription } from "./api.js";
+import { ASidechain } from "./asidechain.js";
+export interface SidechainTriggerOpts<T> extends CommonOpts {
+    pred: Predicate<T>;
+}
+/**
+ * Returns a subscription which buffers the most recent value received from
+ * `src` and only forwards it downstream whenever a new control value is
+ * received from the `side` chain.
+ *
+ * @remarks
+ * By default, the values read from the side chain are ignored (i.e. only their
+ * timing is used), however the `pred`icate option can be used to only trigger
+ * for specific values/conditions. Every time the predicate fn returns true AND
+ * if `src` already has delivered at least one value, it will be forwarded
+ * downstream.
+ *
+ * @example
+ * ```ts
+ * const src = reactive("payload");
+ *
+ * const side = stream();
+ *
+ * sidechainTrigger(src, side).subscribe(trace("data:"));
+ *
+ * side.next(1);
+ * // data: payload
+ *
+ * side.next(1);
+ * // data: payload
+ *
+ * // only newest value will be buffered
+ * src.next("update #1");
+ * src.next("update #2");
+ *
+ * // ...until side chain triggers again
+ * side.next(1);
+ * // data: update #2
+ * ...
+ * ```
+ *
+ * @param src
+ * @param side
+ * @param opts
+ */
+export declare const sidechainTrigger: <T, S>(src: ISubscribable<T>, side: ISubscribable<S>, opts?: Partial<SidechainTriggerOpts<S>> | undefined) => ISubscription<T, T>;
+export declare class SidechainTrigger<T, S> extends ASidechain<T, S, T> {
+    buf: T | typeof SEMAPHORE;
+    constructor(side: ISubscribable<S>, opts?: Partial<SidechainTriggerOpts<S>>);
+    next(x: T): void;
+}
+//# sourceMappingURL=sidechain-trigger.d.ts.map

package/sidechain-trigger.js

@@ -0,0 +1,66 @@
+import { SEMAPHORE } from "@thi.ng/api/api";
+import { State, } from "./api.js";
+import { ASidechain } from "./asidechain.js";
+import { __optsWithID } from "./idgen.js";
+/**
+ * Returns a subscription which buffers the most recent value received from
+ * `src` and only forwards it downstream whenever a new control value is
+ * received from the `side` chain.
+ *
+ * @remarks
+ * By default, the values read from the side chain are ignored (i.e. only their
+ * timing is used), however the `pred`icate option can be used to only trigger
+ * for specific values/conditions. Every time the predicate fn returns true AND
+ * if `src` already has delivered at least one value, it will be forwarded
+ * downstream.
+ *
+ * @example
+ * ```ts
+ * const src = reactive("payload");
+ *
+ * const side = stream();
+ *
+ * sidechainTrigger(src, side).subscribe(trace("data:"));
+ *
+ * side.next(1);
+ * // data: payload
+ *
+ * side.next(1);
+ * // data: payload
+ *
+ * // only newest value will be buffered
+ * src.next("update #1");
+ * src.next("update #2");
+ *
+ * // ...until side chain triggers again
+ * side.next(1);
+ * // data: update #2
+ * ...
+ * ```
+ *
+ * @param src
+ * @param side
+ * @param opts
+ */
+export const sidechainTrigger = (src, side, opts) => src.subscribe(new SidechainTrigger(side, opts));
+export class SidechainTrigger extends ASidechain {
+    constructor(side, opts) {
+        opts = __optsWithID("sidetrigger", opts);
+        super(opts);
+        this.buf = SEMAPHORE;
+        const pred = opts.pred || (() => true);
+        this.sideSub = side.subscribe({
+            next: (x) => {
+                if (this.buf !== SEMAPHORE && pred(x)) {
+                    this.dispatch(this.buf);
+                }
+            },
+            done: () => this.done(),
+        });
+    }
+    next(x) {
+        if (this.state < State.DONE) {
+            this.buf = x;
+        }
+    }
+}

package/sync-raf.d.ts

@@ -0,0 +1,45 @@
+/// <reference types="node" />
+import { type CommonOpts, type ISubscribable } from "./api.js";
+import { Subscription } from "./subscription.js";
+/**
+ * Similar to (in in effect the same as the **now deprecated**)
+ * {@link sidechainPartitionRAF}, however more performant & lightweight.
+ * Synchronizes downstream processing w/ `requestAnimationFrame()`. The returned
+ * subscription delays & debounces any high frequency intra-frame input values
+ * and passes only most recent one downstream during next RAF event processing.
+ *
+ * This example uses thi.ng/atom as state container. Also see {@link fromAtom}.
+ *
+ * See {@link sidechainTrigger} from a similar & more general construct.
+ *
+ * @example
+ * ```ts
+ * const atom = defAtom("alice");
+ *
+ * // any changes to the atom will only be received by this subscription
+ * // during next RAF update cycle
+ * syncRAF(fromAtom(atom)).subscribe({
+ *   next({ name }) { document.body.innerText = name; }
+ * });
+ *
+ * // trigger update
+ * atom.reset("bob");
+ * ```
+ *
+ * @param src -
+ * @param opts -
+ */
+export declare const syncRAF: <T>(src: ISubscribable<T>, opts?: Partial<CommonOpts>) => import("./api.js").ISubscription<T, T>;
+/**
+ * See {@link syncRAF} for details.
+ */
+export declare class SyncRAF<T> extends Subscription<T, T> {
+    queued?: T;
+    raf?: number | NodeJS.Timeout;
+    constructor(opts?: Partial<CommonOpts>);
+    next(x: T): void;
+    done(): void;
+    error(e: any): boolean;
+    protected _clean(): void;
+}
+//# sourceMappingURL=sync-raf.d.ts.map

package/sync-raf.js

@@ -0,0 +1,72 @@
+import { isNode } from "@thi.ng/checks/is-node";
+import { State } from "./api.js";
+import { __optsWithID } from "./idgen.js";
+import { Subscription } from "./subscription.js";
+/**
+ * Similar to (in in effect the same as the **now deprecated**)
+ * {@link sidechainPartitionRAF}, however more performant & lightweight.
+ * Synchronizes downstream processing w/ `requestAnimationFrame()`. The returned
+ * subscription delays & debounces any high frequency intra-frame input values
+ * and passes only most recent one downstream during next RAF event processing.
+ *
+ * This example uses thi.ng/atom as state container. Also see {@link fromAtom}.
+ *
+ * See {@link sidechainTrigger} from a similar & more general construct.
+ *
+ * @example
+ * ```ts
+ * const atom = defAtom("alice");
+ *
+ * // any changes to the atom will only be received by this subscription
+ * // during next RAF update cycle
+ * syncRAF(fromAtom(atom)).subscribe({
+ *   next({ name }) { document.body.innerText = name; }
+ * });
+ *
+ * // trigger update
+ * atom.reset("bob");
+ * ```
+ *
+ * @param src -
+ * @param opts -
+ */
+export const syncRAF = (src, opts) => src.subscribe(new SyncRAF(__optsWithID(`syncraf-${src.id}`, opts)));
+/**
+ * See {@link syncRAF} for details.
+ */
+export class SyncRAF extends Subscription {
+    constructor(opts) {
+        super(undefined, opts);
+    }
+    next(x) {
+        if (this.state >= State.DONE)
+            return;
+        this.queued = x;
+        if (!this.raf) {
+            const update = () => {
+                if (this.state < State.DONE)
+                    super.next(this.queued);
+                this._clean();
+            };
+            this.raf = isNode()
+                ? setTimeout(update, 16)
+                : requestAnimationFrame(update);
+        }
+    }
+    done() {
+        this._clean();
+        super.done();
+    }
+    error(e) {
+        this._clean();
+        return super.error(e);
+    }
+    _clean() {
+        if (this.raf) {
+            isNode()
+                ? clearTimeout(this.raf)
+                : cancelAnimationFrame(this.raf);
+        }
+        this.raf = this.queued = undefined;
+    }
+}

package/view.d.ts

@@ -41,7 +41,7 @@ export declare const fromViewUnsafe: <T>(atom: ReadonlyAtom<any>, opts: FromView
 /**
  * Similar to {@link fromAtom}, but creates a type checked, eager derived view
  * for a nested value in an Atom-like state container and yields stream of its
- * value changes.
+ * value changes. See {@link fromViewUnsafe} for unchecked version.
  *
  * @remarks
  * Stream value type is inferred from target path or (if given), the result type

package/view.js

@@ -43,5 +43,5 @@ export function fromView(atom, opts) {
             isActive = false;
             view.release();
         };
-    });
+    }, opts);
 }