@thi.ng/transducers-async 0.1.2 → 0.2.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-04-13T16:05:36Z
+- **Last updated**: 2024-04-22T09:56:21Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,27 @@ 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.
 
+## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/transducers-async@0.2.0) (2024-04-20)
+
+#### 🚀 Features
+
+- add delayed() & wait() helpers ([d2f0738](https://github.com/thi-ng/umbrella/commit/d2f0738))
+- add mult() for 1:N splitting (multiple subscribers) ([ad1b63b](https://github.com/thi-ng/umbrella/commit/ad1b63b))
+- add asAsyncIterable() helper ([8e40424](https://github.com/thi-ng/umbrella/commit/8e40424))
+- add source(), refactor events() ([b94d150](https://github.com/thi-ng/umbrella/commit/b94d150))
+- add syncRAF(), update sidechain() args ([54ded8b](https://github.com/thi-ng/umbrella/commit/54ded8b))
+- add pubsub() ([1f406d0](https://github.com/thi-ng/umbrella/commit/1f406d0))
+- update/extend Source interface/impl ([a95819b](https://github.com/thi-ng/umbrella/commit/a95819b))
+- add [@thi.ng/buffers](https://github.com/thi-ng/umbrella/tree/main/packages/buffers) support for source() ([c46d862](https://github.com/thi-ng/umbrella/commit/c46d862))
+- update Source API, add docs ([7a7b5ab](https://github.com/thi-ng/umbrella/commit/7a7b5ab))
+
+#### ♻️ Refactoring
+
+- add ClosableAsyncGenerator type, update events() & source() ([929d860](https://github.com/thi-ng/umbrella/commit/929d860))
+- simplify raf() impl ([38c36b9](https://github.com/thi-ng/umbrella/commit/38c36b9))
+  - rewrite to use source()
+- update type usage ([bec044c](https://github.com/thi-ng/umbrella/commit/bec044c))
+
 ### [0.1.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/transducers-async@0.1.1) (2024-04-11)
 
 #### ♻️ Refactoring

package/README.md

@@ -16,12 +16,14 @@
 
 - [About](#about)
   - [Evaluators](#evaluators)
-  - [Iterators](#iterators)
+  - [Generators & iterators](#generators--iterators)
+  - [Combinators](#combinators)
   - [Transducers](#transducers)
   - [Reducers](#reducers)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
+- [Usage examples](#usage-examples)
 - [API](#api)
 - [Authors](#authors)
 - [License](#license)
@@ -38,18 +40,26 @@ Async versions of various highly composable transducers, reducers and iterators.
 - [`step()`](https://docs.thi.ng/umbrella/transducers-async/functions/step.html)
 - [`transduce()`](https://docs.thi.ng/umbrella/transducers-async/functions/transduce.html)
 
-### Iterators
+### Generators & iterators
 
+- [`asAsyncIterable()`](https://docs.thi.ng/umbrella/transducers-async/functions/asAsyncIterable.html)
 - [`concat()`](https://docs.thi.ng/umbrella/transducers-async/functions/concat.html)
 - [`events()`](https://docs.thi.ng/umbrella/transducers-async/functions/events.html)
-- [`merge()`](https://docs.thi.ng/umbrella/transducers-async/functions/merge.html)
 - [`raf()`](https://docs.thi.ng/umbrella/transducers-async/functions/raf.html)
 - [`range()`](https://docs.thi.ng/umbrella/transducers-async/functions/range.html)
 - [`repeatedly()`](https://docs.thi.ng/umbrella/transducers-async/functions/repeatedly.html)
 - [`sidechain()`](https://docs.thi.ng/umbrella/transducers-async/functions/sidechain.html)
-- [`sync()`](https://docs.thi.ng/umbrella/transducers-async/functions/sync.html)
+- [`source()`](https://docs.thi.ng/umbrella/transducers-async/functions/source.html)
 - [`zip()`](https://docs.thi.ng/umbrella/transducers-async/functions/zip.html)
 
+### Combinators
+
+- [`merge()`](https://docs.thi.ng/umbrella/transducers-async/functions/merge.html)
+- [`mult()`](https://docs.thi.ng/umbrella/transducers-async/functions/mult.html)
+- [`pubsub()`](https://docs.thi.ng/umbrella/transducers-async/functions/pubsub.html)
+- [`sync()`](https://docs.thi.ng/umbrella/transducers-async/functions/sync.html)
+- [`syncRAF()`](https://docs.thi.ng/umbrella/transducers-async/functions/syncRAF.html)
+
 ### Transducers
 
 - [`comp()`](https://docs.thi.ng/umbrella/transducers-async/functions/comp.html)
@@ -58,6 +68,7 @@ Async versions of various highly composable transducers, reducers and iterators.
 - [`mapcat()`](https://docs.thi.ng/umbrella/transducers-async/functions/mapcat.html)
 - [`multiplex()`](https://docs.thi.ng/umbrella/transducers-async/functions/multiplex.html)
 - [`multiplexObj()`](https://docs.thi.ng/umbrella/transducers-async/functions/multiplexObj.html)
+- [`partition()`](https://docs.thi.ng/umbrella/transducers-async/functions/partition.html)
 - [`take()`](https://docs.thi.ng/umbrella/transducers-async/functions/take.html)
 - [`throttle()`](https://docs.thi.ng/umbrella/transducers-async/functions/throttle.html)
 - [`throttleTime()`](https://docs.thi.ng/umbrella/transducers-async/functions/throttleTime.html)
@@ -87,10 +98,10 @@ import * as txa from "@thi.ng/transducers-async";
 Browser ESM import:
 
 ```html
-<script type="module" src="https://cdn.skypack.dev/@thi.ng/transducers-async"></script>
+<script type="module" src="https://esm.run/@thi.ng/transducers-async"></script>
 ```
 
-[Skypack documentation](https://docs.skypack.dev/)
+[JSDelivr documentation](https://www.jsdelivr.com/)
 
 For Node.js REPL:
 
@@ -98,20 +109,33 @@ For Node.js REPL:
 const txa = await import("@thi.ng/transducers-async");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.23 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.10 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
+- [@thi.ng/buffers](https://github.com/thi-ng/umbrella/tree/develop/packages/buffers)
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 - [@thi.ng/compose](https://github.com/thi-ng/umbrella/tree/develop/packages/compose)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
 - [@thi.ng/transducers](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers)
 
+## Usage examples
+
+One project in this repo's
+[/examples](https://github.com/thi-ng/umbrella/tree/develop/examples)
+directory is using this package:
+
+| Description                                               | Live demo                                        | Source                                                                        |
+|:----------------------------------------------------------|:-------------------------------------------------|:------------------------------------------------------------------------------|
+| Basic & barebones usage of async iterables in thi.ng/rdom | [Demo](https://demo.thi.ng/umbrella/rdom-async/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rdom-async) |
+
 ## API
 
 [Generated API docs](https://docs.thi.ng/umbrella/transducers-async/)
 
+TODO
+
 ## Authors
 
 - [Karsten Schmidt](https://thi.ng)

package/api.d.ts

@@ -20,4 +20,10 @@ export type AsyncMultiplexTxLike<A, B> = AsyncTxLike<A, B> | [AsyncTxLike<A, B>,
 export interface IXformAsync<A, B> {
     xformAsync(): AsyncTransducer<A, B>;
 }
+export interface ClosableAsyncGenerator<T> extends AsyncGenerator<T> {
+    /**
+     * Terminates the iterable at the next opportunity.
+     */
+    close(): void;
+}
 //# sourceMappingURL=api.d.ts.map

package/as-async.d.ts

@@ -0,0 +1,2 @@
+export declare function asAsyncIterable<T>(src: Iterable<T>, delay?: number): AsyncGenerator<Awaited<T>, void, unknown>;
+//# sourceMappingURL=as-async.d.ts.map

package/as-async.js

@@ -0,0 +1,11 @@
+import { wait } from "./delayed.js";
+async function* asAsyncIterable(src, delay = 0) {
+  for (let x of src) {
+    yield x;
+    if (delay > 0)
+      await wait(delay);
+  }
+}
+export {
+  asAsyncIterable
+};

package/delayed.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Same as [thi.ng/compose `delayed()`](). Re-exported for convenience. Yields
+ * `x` as promise which only resolves after `delay` milliseconds.
+ *
+ * @remarks
+ * Also see {@link wait}.
+ *
+ * @param x
+ * @param delay
+ */
+export declare const delayed: <T>(x: T, t: number) => Promise<T>;
+/**
+ * Syntax sugar for {@link delayed}, yields a void promise which resolves after
+ * `delay` milliseconds.
+ *
+ * @remarks
+ * Also see {@link delayed}.
+ *
+ * @param delay
+ */
+export declare const wait: (delay: number) => Promise<void>;
+//# sourceMappingURL=delayed.d.ts.map

package/delayed.js

@@ -0,0 +1,7 @@
+import { delayed as $ } from "@thi.ng/compose/delayed";
+const delayed = $;
+const wait = (delay) => delayed(void 0, delay);
+export {
+  delayed,
+  wait
+};

package/events.d.ts

@@ -1,14 +1,35 @@
+import type { IDeref, Maybe } from "@thi.ng/api";
+import type { ClosableAsyncGenerator } from "./api.js";
 /**
  * Attaches an event listener to given `target` and yields an async iterator of
  * events.
  *
  * @remarks
- * The event listener can be removed (and the iterator stopped) by sending
- * `yield iter.next(true)`.
+ * The event listener can be removed (and the iterator stopped) by calling
+ * `.close()`.
+ *
+ * @example
+ * ```ts tangle:../export/events.ts
+ * import { events, map, run } from "@thi.ng/transducers-async";
+ *
+ * const resize = events(window, "resize");
+ *
+ * const sizes = map(
+ *   (e) => [window.innerWidth, window.innerHeight],
+ *   resize
+ * );
+ *
+ * for await (let [w, h] of sizes) {
+ *   console.log(w, h)
+ * }
+ *
+ * // to stop listening and stop iterator
+ * resize.close();
+ * ```
  *
  * @param target
  * @param id
  * @param opts
  */
-export declare function events<T extends Event = Event>(target: EventTarget, id: string, opts?: EventListenerOptions): AsyncGenerator<T>;
+export declare const events: <T extends Event = Event>(target: EventTarget, id: string, opts?: EventListenerOptions) => ClosableAsyncGenerator<T> & IDeref<Maybe<T>>;
 //# sourceMappingURL=events.d.ts.map

package/events.js

@@ -1,17 +1,14 @@
-async function* events(target, id, opts) {
-  let resolve;
-  const listener = (e) => resolve(e);
+import { source } from "./source.js";
+const events = (target, id, opts) => {
+  const listener = (e) => gen.write(e);
   target.addEventListener(id, listener, opts);
-  while (true) {
-    const promise = new Promise(($resolve) => {
-      resolve = $resolve;
-    });
-    const cancel = yield await promise;
-    if (cancel === true)
-      break;
-  }
-  target.removeEventListener(id, listener, opts);
-}
+  const gen = source();
+  gen.close = () => {
+    target.removeEventListener(id, listener, opts);
+    gen.write(void 0);
+  };
+  return gen;
+};
 export {
   events
 };

package/index.d.ts

@@ -1,8 +1,10 @@
 export * from "./api.js";
+export * from "./as-async.js";
 export * from "./cat.js";
 export * from "./comp.js";
 export * from "./compr.js";
 export * from "./concat.js";
+export * from "./delayed.js";
 export * from "./ensure.js";
 export * from "./events.js";
 export * from "./filter.js";
@@ -10,9 +12,11 @@ export * from "./iterator.js";
 export * from "./map.js";
 export * from "./mapcat.js";
 export * from "./merge.js";
+export * from "./mult.js";
 export * from "./multiplex-obj.js";
 export * from "./multiplex.js";
 export * from "./partition.js";
+export * from "./pubsub.js";
 export * from "./push.js";
 export * from "./raf.js";
 export * from "./range.js";
@@ -20,8 +24,10 @@ export * from "./reduce.js";
 export * from "./repeatedly.js";
 export * from "./run.js";
 export * from "./sidechain.js";
+export * from "./source.js";
 export * from "./step.js";
 export * from "./sync.js";
+export * from "./sync-raf.js";
 export * from "./take.js";
 export * from "./throttle-time.js";
 export * from "./throttle.js";

package/index.js

@@ -1,8 +1,10 @@
 export * from "./api.js";
+export * from "./as-async.js";
 export * from "./cat.js";
 export * from "./comp.js";
 export * from "./compr.js";
 export * from "./concat.js";
+export * from "./delayed.js";
 export * from "./ensure.js";
 export * from "./events.js";
 export * from "./filter.js";
@@ -10,9 +12,11 @@ export * from "./iterator.js";
 export * from "./map.js";
 export * from "./mapcat.js";
 export * from "./merge.js";
+export * from "./mult.js";
 export * from "./multiplex-obj.js";
 export * from "./multiplex.js";
 export * from "./partition.js";
+export * from "./pubsub.js";
 export * from "./push.js";
 export * from "./raf.js";
 export * from "./range.js";
@@ -20,8 +24,10 @@ export * from "./reduce.js";
 export * from "./repeatedly.js";
 export * from "./run.js";
 export * from "./sidechain.js";
+export * from "./source.js";
 export * from "./step.js";
 export * from "./sync.js";
+export * from "./sync-raf.js";
 export * from "./take.js";
 export * from "./throttle-time.js";
 export * from "./throttle.js";

package/mult.d.ts

@@ -0,0 +1,83 @@
+import type { Fn, Fn0, Maybe } from "@thi.ng/api";
+/**
+ * Creates a new {@link Mult} instance which allows splitting a single `src`
+ * async iterable into multiple parallel subscribers. Iteration only starts when
+ * the first subscriber is attached (via {@link Mult.subscribe}) and back
+ * pressure is handled by waiting for **all** child subscribers to deliver their
+ * values before the next value from `src` is consumed. `Mult` allows dynamic
+ * subscriptions and unsubscriptions and will stop consuming from `src` when no
+ * further subscribers are attached.
+ *
+ * @example
+ * ```ts tangle:../export/mult.ts
+ * import { map, mult, run, wait } from "@thi.ng/transducers-async";
+ *
+ * const root = mult(
+ *   (async function* () {
+ *     yield "hello";
+ *     await wait(1000);
+ *     yield "world";
+ *     await wait(1000);
+ *     yield "good bye";
+ *   })()
+ * );
+ *
+ * // 1st subscriber (vanilla JS)
+ * (async () => {
+ *   for await (let x of root.subscribe()) console.log("vanilla:", x);
+ * })();
+ *
+ * // 2nd subscriber (transducer), attached with delay
+ * setTimeout(
+ *   () =>
+ *     run(
+ *       map(async (x) => {
+ *         console.log("tx", x);
+ *         await wait(1500);
+ *       }),
+ *       root.subscribe()
+ *     ),
+ *   900
+ * );
+ *
+ * // vanilla: hello
+ * // vanilla: world
+ * // tx world
+ * // vanilla: good bye
+ * // tx good bye
+ * ```
+ *
+ * @param src
+ */
+export declare const mult: <T>(src: AsyncIterable<T>) => Mult<T>;
+export declare class Mult<T> {
+    src: AsyncIterable<T>;
+    protected subs: MSub<T>[];
+    protected isActive: boolean;
+    constructor(src: AsyncIterable<T>);
+    /**
+     * Creates a new subscription (aka custom `AsyncIterable`) which will
+     * receive any future values from `src`. The returned subscription can be
+     * removed again via {@link Mult.unsubscribe}.
+     */
+    subscribe(): AsyncIterable<T>;
+    /**
+     * Attempts to remove given child subscription (presumably created via
+     * {@link Mult.subscribe}). Returns true if removal was successful.
+     *
+     * @param sub
+     */
+    unsubscribe(sub: AsyncIterable<T>): boolean;
+}
+/** @internal */
+export declare class MSub<T> {
+    valueP: Promise<Maybe<T>>;
+    notifyP: Promise<void>;
+    resolve: Fn<Maybe<T>, void>;
+    notify: Fn0<void>;
+    active: boolean;
+    constructor();
+    [Symbol.asyncIterator](): AsyncGenerator<Awaited<Awaited<T> & null> | Awaited<Awaited<T> & {}>, void, unknown>;
+    protected $await(): void;
+}
+//# sourceMappingURL=mult.d.ts.map

package/mult.js

@@ -0,0 +1,85 @@
+import { illegalState } from "@thi.ng/errors/illegal-state";
+const mult = (src) => new Mult(src);
+class Mult {
+  constructor(src) {
+    this.src = src;
+  }
+  subs = [];
+  isActive = false;
+  /**
+   * Creates a new subscription (aka custom `AsyncIterable`) which will
+   * receive any future values from `src`. The returned subscription can be
+   * removed again via {@link Mult.unsubscribe}.
+   */
+  subscribe() {
+    const sub = new MSub();
+    this.subs.push(sub);
+    if (!this.isActive) {
+      this.isActive = true;
+      (async () => {
+        for await (let val of this.src) {
+          for (let s of this.subs)
+            s.resolve(val);
+          if (val === void 0)
+            this.subs.length = 0;
+          if (!this.subs.length)
+            break;
+          await Promise.all(this.subs.map((x) => x.notifyP));
+        }
+        for (let s of this.subs)
+          s.resolve(void 0);
+        this.subs.length = 0;
+        this.isActive = false;
+      })();
+    }
+    return sub;
+  }
+  /**
+   * Attempts to remove given child subscription (presumably created via
+   * {@link Mult.subscribe}). Returns true if removal was successful.
+   *
+   * @param sub
+   */
+  unsubscribe(sub) {
+    const idx = this.subs.findIndex((x) => x === sub);
+    if (idx >= 0) {
+      this.subs.splice(idx, 1);
+      sub.resolve(void 0);
+      return true;
+    }
+    return false;
+  }
+}
+class MSub {
+  valueP;
+  notifyP;
+  resolve;
+  notify;
+  active = false;
+  constructor() {
+    this.$await();
+  }
+  async *[Symbol.asyncIterator]() {
+    if (this.active)
+      illegalState("multiple consumers unsupported");
+    this.active = true;
+    while (true) {
+      const res = await this.valueP;
+      if (res === void 0)
+        break;
+      yield res;
+      this.notify();
+      this.$await();
+    }
+    this.active = false;
+  }
+  $await() {
+    this.notifyP = new Promise((res) => this.notify = res);
+    this.valueP = new Promise((res) => this.resolve = res);
+  }
+}
+export {
+  MSub,
+  Mult,
+  mult
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/transducers-async",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Async versions of various highly composable transducers, reducers and iterators",
   "type": "module",
   "module": "./index.js",
@@ -36,11 +36,12 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.10.1",
-    "@thi.ng/checks": "^3.6.1",
-    "@thi.ng/compose": "^3.0.1",
-    "@thi.ng/errors": "^2.5.4",
-    "@thi.ng/transducers": "^9.0.1"
+    "@thi.ng/api": "^8.11.0",
+    "@thi.ng/buffers": "^0.1.1",
+    "@thi.ng/checks": "^3.6.2",
+    "@thi.ng/compose": "^3.0.2",
+    "@thi.ng/errors": "^2.5.5",
+    "@thi.ng/transducers": "^9.0.2"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.43.0",
@@ -89,6 +90,9 @@
     "./api": {
       "default": "./api.js"
     },
+    "./as-async": {
+      "default": "./as-async.js"
+    },
     "./cat": {
       "default": "./cat.js"
     },
@@ -101,6 +105,9 @@
     "./concat": {
       "default": "./concat.js"
     },
+    "./delayed": {
+      "default": "./delayed.js"
+    },
     "./ensure": {
       "default": "./ensure.js"
     },
@@ -122,6 +129,9 @@
     "./merge": {
       "default": "./merge.js"
     },
+    "./mult": {
+      "default": "./mult.js"
+    },
     "./multiplex-obj": {
       "default": "./multiplex-obj.js"
     },
@@ -131,6 +141,9 @@
     "./partition": {
       "default": "./partition.js"
     },
+    "./pubsub": {
+      "default": "./pubsub.js"
+    },
     "./push": {
       "default": "./push.js"
     },
@@ -152,9 +165,15 @@
     "./sidechain": {
       "default": "./sidechain.js"
     },
+    "./source": {
+      "default": "./source.js"
+    },
     "./step": {
       "default": "./step.js"
     },
+    "./sync-raf": {
+      "default": "./sync-raf.js"
+    },
     "./sync": {
       "default": "./sync.js"
     },
@@ -180,5 +199,5 @@
     "status": "alpha",
     "year": 2018
   },
-  "gitHead": "fd7ab12d565809a2300783881c62b883dbd25c23\n"
+  "gitHead": "4e2bf6b12e35192e678b525fa699429370e357d3\n"
 }

package/pubsub.d.ts

@@ -0,0 +1,26 @@
+import type { Fn } from "@thi.ng/api";
+import { MSub } from "./mult.js";
+export declare const pubsub: <K, V>(src: AsyncIterable<V>, topicFn: Fn<V, K>) => PubSub<K, V>;
+export declare class PubSub<K, V> {
+    src: AsyncIterable<V>;
+    topicFn: Fn<V, K>;
+    protected topics: Map<K, MSub<V>[]>;
+    protected isActive: boolean;
+    constructor(src: AsyncIterable<V>, topicFn: Fn<V, K>);
+    /**
+     * Creates a new subscription (aka custom `AsyncIterable`) which will
+     * receive any future values from `src` matching given topic `id`. The
+     * returned subscription can be removed again via
+     * {@link PubSub.unsubscribeTopic}.
+     */
+    subscribeTopic(id: K): AsyncIterable<V>;
+    /**
+     * Attempts to remove given child subscription (presumably created via
+     * {@link PubSub.subscribeTopic}). Returns true if removal was successful.
+     *
+     * @param sub
+     */
+    unsubscribeTopic(id: K, sub: AsyncIterable<V>): boolean;
+    protected process(): Promise<void>;
+}
+//# sourceMappingURL=pubsub.d.ts.map

package/pubsub.js

@@ -0,0 +1,68 @@
+import { MSub } from "./mult.js";
+const pubsub = (src, topicFn) => new PubSub(src, topicFn);
+class PubSub {
+  constructor(src, topicFn) {
+    this.src = src;
+    this.topicFn = topicFn;
+  }
+  topics = /* @__PURE__ */ new Map();
+  isActive = false;
+  /**
+   * Creates a new subscription (aka custom `AsyncIterable`) which will
+   * receive any future values from `src` matching given topic `id`. The
+   * returned subscription can be removed again via
+   * {@link PubSub.unsubscribeTopic}.
+   */
+  subscribeTopic(id) {
+    const sub = new MSub();
+    let subs = this.topics.get(id);
+    if (!subs) {
+      this.topics.set(id, subs = []);
+    }
+    subs.push(sub);
+    if (!this.isActive) {
+      this.isActive = true;
+      this.process();
+    }
+    return sub;
+  }
+  /**
+   * Attempts to remove given child subscription (presumably created via
+   * {@link PubSub.subscribeTopic}). Returns true if removal was successful.
+   *
+   * @param sub
+   */
+  unsubscribeTopic(id, sub) {
+    const subs = this.topics.get(id);
+    if (!subs)
+      return false;
+    const idx = subs.findIndex((x) => x === sub) ?? -1;
+    if (idx >= 0) {
+      subs.splice(idx, 1);
+      sub.resolve(void 0);
+      return true;
+    }
+    return false;
+  }
+  async process() {
+    for await (let val of this.src) {
+      const topic = this.topicFn(val);
+      const subs = this.topics.get(topic);
+      if (!(subs && subs.length))
+        continue;
+      for (let s of subs)
+        s.resolve(val);
+      await Promise.all(subs.map((x) => x.notifyP));
+    }
+    for (let subs of this.topics.values()) {
+      for (let s of subs)
+        s.resolve(void 0);
+    }
+    this.topics.clear();
+    this.isActive = false;
+  }
+}
+export {
+  PubSub,
+  pubsub
+};

package/raf.d.ts

@@ -1,3 +1,5 @@
+import type { IDeref, Maybe } from "@thi.ng/api";
+import type { ClosableAsyncGenerator } from "./api.js";
 export interface RAFOpts {
     /**
      * If true (default: false), passes the timestamps received
@@ -16,5 +18,5 @@ export interface RAFOpts {
      */
     t0: number | boolean;
 }
-export declare function raf(opts?: Partial<RAFOpts>): AsyncGenerator<number>;
+export declare const raf: (opts?: Partial<RAFOpts>) => ClosableAsyncGenerator<number> & IDeref<Maybe<number>>;
 //# sourceMappingURL=raf.d.ts.map

package/raf.js

@@ -1,11 +1,16 @@
-async function* raf(opts) {
+import { source } from "./source.js";
+const raf = (opts) => {
   let frame = 0;
   let t0 = opts?.t0 || 0;
-  while (true) {
-    let resolve;
-    const promise = new Promise(($resolve) => resolve = $resolve);
-    requestAnimationFrame(resolve);
-    let t = await promise;
+  let isClosed = false;
+  const gen = source();
+  gen.close = () => {
+    isClosed = true;
+    gen.write(void 0);
+  };
+  const update = (t) => {
+    if (isClosed)
+      return;
     if (opts?.timestamp) {
       if (t0 === true)
         t0 = t;
@@ -14,11 +19,12 @@ async function* raf(opts) {
     } else {
       t = frame++;
     }
-    const cancel = yield t;
-    if (cancel === true)
-      break;
-  }
-}
+    gen.write(t);
+    requestAnimationFrame(update);
+  };
+  requestAnimationFrame(update);
+  return gen;
+};
 export {
   raf
 };

package/range.js

@@ -1,10 +1,10 @@
-import { delayed } from "@thi.ng/compose/delayed";
 import { Range } from "@thi.ng/transducers/range";
+import { wait } from "./delayed.js";
 async function* range(...args) {
   const delay = args.pop();
   for (let x of new Range(...args)) {
     yield x;
-    await delayed(null, delay);
+    await wait(delay);
   }
 }
 export {

package/repeatedly.js

@@ -1,9 +1,9 @@
-import { delayed } from "@thi.ng/compose/delayed";
+import { wait } from "./delayed.js";
 async function* repeatedly(fn, n = Infinity, delay = 0) {
   for (let i = 0; i < n; i++) {
     yield await fn(i);
     if (delay > 0) {
-      await delayed(null, delay);
+      await wait(delay);
     }
   }
 }

package/sidechain.d.ts

@@ -1,15 +1,15 @@
 export interface SidechainOpts {
     /**
      * If true (default), only emits the last received value when the sidechain
-     * triggers. Otherwise buffers and emits *all* received values since the
-     * last time the sidechain triggered.
+     * delivers a truthy value. Otherwise buffers and emits *all* received
+     * values since the last time the sidechain triggered.
      *
      * @defaultValue true
      */
     lastOnly: boolean;
 }
-export declare function sidechain<T>(src: AsyncIterable<T>, side: AsyncIterable<boolean>, opts: Partial<SidechainOpts> & {
+export declare function sidechain<T>(src: AsyncIterable<T>, side: AsyncIterable<any>, opts: Partial<SidechainOpts> & {
     lastOnly: false;
 }): AsyncIterableIterator<T[]>;
-export declare function sidechain<T>(src: AsyncIterable<T>, side: AsyncIterable<boolean>, opts?: Partial<SidechainOpts>): AsyncIterableIterator<T>;
+export declare function sidechain<T>(src: AsyncIterable<T>, side: AsyncIterable<any>, opts?: Partial<SidechainOpts>): AsyncIterableIterator<T>;
 //# sourceMappingURL=sidechain.d.ts.map

package/source.d.ts

@@ -0,0 +1,93 @@
+import type { FnO, IDeref, Maybe } from "@thi.ng/api";
+import type { IReadWriteBuffer } from "@thi.ng/buffers";
+import type { ClosableAsyncGenerator } from "./api.js";
+export interface Source<T> extends ClosableAsyncGenerator<T>, IDeref<Maybe<T>> {
+    /**
+     * Writes or queues given value `x` to be asynchronously passed down to the
+     * source's consumer. If no other values are queued yet, the source
+     * processes it immediately, otherwise the value will be first added to the
+     * source's configured buffer.
+     *
+     * @remarks
+     * Once {@link Source.close} has been called, all future write attempts will
+     * be silently ignored.
+     *
+     * @param x
+     */
+    write(x?: T): void;
+    /**
+     * Returns the most recently produced/yielded value (if any). If there's
+     * back pressure (i.e. queued values caused by more frequent writes and than
+     * reads, the returned value is **not** necessarily the last value written
+     * via {@link Source.write}). Returns `undefined`, if no value has yet been
+     * written or the source has already been fully closed (via
+     * {@link Source.close}).
+     */
+    deref(): Maybe<T>;
+    /**
+     * Takes a function which will be called with the most recent emitted value
+     * of the source (plus any optionally given args) and queues the result of
+     * that function as new value to be asynchronously passed down by the source
+     * to its consumer.
+     *
+     * @remarks
+     * Only use this function in situations where there's no back pressure (i.e.
+     * no queued up values).
+     *
+     * @param fn
+     * @param args
+     */
+    update(fn: FnO<Maybe<T>, Maybe<T>>, ...args: any[]): void;
+}
+/**
+ * Creates an async iterable acting as data source with an extended API to
+ * externally feed/write new values, which are then passed downstream to any
+ * attached processors/transducers. The source can use an optional buffer
+ * implementation to control back pressure behavior and value ordering.
+ *
+ * @remarks
+ * See [thi.ng/buffers](https://thi.ng/buffers) for available buffer
+ * implementations. By default a
+ * [`fifo()`](https://docs.thi.ng/umbrella/buffers/functions/fifo.html) buffer
+ * with capacity=1 is used.
+ *
+ * If `initial` is given, the source will immediately deliver this value once a
+ * consumer is attached.
+ *
+ * The `source()` stores the last produced/yielded value (not necessarily the
+ * last value written via {@link Source.write}), which can be read via
+ * {@link Source.deref} or updated via {@link Source.update}.
+ *
+ * @example
+ * ```ts tangle:../export/source.ts
+ * import { source, map, run } from "@thi.ng/transducers-async";
+ *
+ * // create empty source
+ * const src = source();
+ *
+ * // create an async consumer
+ * // (consumer stops when we close the source)
+ * run(
+ *   map(async (x) => x * 10),
+ *   (x) => console.log("result:", x),
+ *   src
+ * )
+ *
+ * // set new value
+ * src.write(23);
+ * // result: 230
+ *
+ * // update last value
+ * // (delayed invocation here to avoid buffer overflow)
+ * setTimeout(() => src.update((x) => x + 1), 0);
+ * // result: 240
+ *
+ * // close/terminate source
+ * setTimeout(() => src.close(), 0);
+ * ```
+ *
+ * @param initial
+ * @param buffer
+ */
+export declare const source: <T>(initial?: T, buffer?: IReadWriteBuffer<Maybe<T>> | number) => Source<T>;
+//# sourceMappingURL=source.d.ts.map

package/source.js

@@ -0,0 +1,51 @@
+import { fifo } from "@thi.ng/buffers/fifo";
+import { isNumber } from "@thi.ng/checks/is-number";
+import { illegalState } from "@thi.ng/errors/illegal-state";
+const source = (initial, buffer = 1) => {
+  const queue = isNumber(buffer) ? fifo(buffer) : buffer;
+  let last = initial;
+  let state = 0;
+  let promise;
+  let resolve;
+  const newPromise = () => {
+    promise = new Promise(($resolve) => {
+      resolve = $resolve;
+    });
+  };
+  newPromise();
+  const gen = async function* () {
+    while (true) {
+      const val = await promise;
+      last = val;
+      if (val === void 0)
+        break;
+      yield val;
+      newPromise();
+      if (queue.readable())
+        resolve(queue.read());
+    }
+    state = 2;
+  }();
+  gen.write = (x) => {
+    if (state > 0)
+      return;
+    if (resolve) {
+      resolve(x);
+      resolve = void 0;
+    } else if (queue.writable()) {
+      queue.write(x);
+      if (x === void 0)
+        state = 1;
+    } else
+      illegalState("buffer overflow");
+  };
+  gen.update = (fn, ...args) => gen.write(fn(last, ...args));
+  gen.close = () => gen.write(void 0);
+  gen.deref = () => last;
+  if (initial !== void 0)
+    gen.write(initial);
+  return gen;
+};
+export {
+  source
+};

package/step.d.ts

@@ -1,4 +1,4 @@
-import type { Fn } from "@thi.ng/api";
+import type { Fn, Maybe } from "@thi.ng/api";
 import type { AsyncTxLike } from "./api.js";
-export declare const step: <A, B>(tx: AsyncTxLike<A, B>, unwrap?: boolean) => Fn<A, Promise<B | B[] | undefined>>;
+export declare const step: <A, B>(tx: AsyncTxLike<A, B>, unwrap?: boolean) => Fn<A, Promise<Maybe<B | B[]>>>;
 //# sourceMappingURL=step.d.ts.map

package/step.js

@@ -1,6 +1,6 @@
+import { isReduced } from "@thi.ng/transducers/reduced";
 import { ensureAsyncTransducer } from "./ensure.js";
 import { push } from "./push.js";
-import { isReduced } from "@thi.ng/transducers/reduced";
 const step = (tx, unwrap = true) => {
   const [_, complete, reduce] = ensureAsyncTransducer(tx)(push());
   let done = false;

package/sync-raf.d.ts

@@ -0,0 +1,2 @@
+export declare const syncRAF: <T>(src: AsyncIterable<T>) => AsyncIterableIterator<T>;
+//# sourceMappingURL=sync-raf.d.ts.map

package/sync-raf.js

@@ -0,0 +1,6 @@
+import { raf } from "./raf.js";
+import { sidechain } from "./sidechain.js";
+const syncRAF = (src) => sidechain(src, raf({ timestamp: true }));
+export {
+  syncRAF
+};