@thi.ng/rstream 9.2.9 → 9.2.11

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-01-29T16:25:48Z
+- **Last updated**: 2025-02-19T20:59:58Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.

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 201 standalone projects, maintained as part
+> This is one of 202 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >

package/api.d.ts

@@ -139,7 +139,7 @@ export interface ISubscribable<A> extends IDeref<Maybe<A>>, IID<string> {
      * attached to the returned wrapped sub will also only receive those
      * transformed values.
      *
-     * @see {@link ITransformable}
+     * See {@link ITransformable}
      *
      * @param sub -
      * @param opts -

package/forkjoin.d.ts

@@ -7,97 +7,92 @@ export interface ForkJoinOpts<IN, MSG, RES, OUT> extends Partial<CommonOpts> {
      */
     src: ITransformable<IN>;
     /**
-     * Transformation function prepare (e.g. chunk) work for a single
-     * worker. Receives worker `id` [0 .. numWorkers), `numWorkers` and
-     * current input value to be processed. Only the results of this
-     * function are sent to the worker and therefore the function must
-     * return a type compatible with the configured worker instance.
+     * Transformation function prepare (e.g. chunk) work for a single worker.
+     * Receives worker `id` `[0,numWorkers)`, `numWorkers` and current input
+     * value to be processed. Only the results of this function are sent to the
+     * worker and therefore the function must return a type compatible with the
+     * configured worker instance.
      *
-     * For example, such a function might extract slices from a large
-     * input array, one per worker. The given worker ID and worker count
-     * can be used to create non-overlapping chunks to evenly spread the
-     * workload...
+     * For example, such a function might extract slices from a large input
+     * array, one per worker. The given worker ID and worker count can be used
+     * to create non-overlapping chunks to evenly spread the workload...
      *
      * Also see: {@link forkBuffer}
      */
     fork: Fn3<number, number, IN, MSG>;
     /**
-     * Join function. Receives array of worker results (in worker ID
-     * order) and is responsible to transform these into the final
-     * result / output type.
+     * Join function. Receives array of worker results (in worker ID order) and
+     * is responsible to transform these into the final result / output type.
      */
     join: Fn<RES[], OUT>;
     /**
-     * Optional function to extract transferables from `fork` result
-     * values (i.e. payloads sent to each worker), e.g. ArrayBuffers. See:
+     * Optional function to extract transferables from `fork` result values
+     * (i.e. payloads sent to each worker), e.g. ArrayBuffers. See:
      * https://developer.mozilla.org/en-US/docs/Web/API/Worker/postMessage
      */
     transferables?: Fn<MSG, any[]>;
     /**
-     * An existing `Worker` instance, a JS source code `Blob` or an URL
-     * string. In the latter two cases, a worker is created
-     * automatically using `makeWorker()`.
+     * An existing `Worker` instance, a JS source code `Blob` or an URL string.
+     * In the latter two cases, a worker is created automatically using
+     * `makeWorker()`.
      */
     worker: WorkerSource;
     /**
      * Optional max number of workers to use. Defaults to
-     * `navigator.hardwareConcurrency` (or if unavailable, then 4 as
-     * fallback). If setting this higher, be aware of browser limits and
-     * potential resulting crashes!
+     * `navigator.hardwareConcurrency` (or if unavailable, then 4 as fallback).
+     * If setting this higher, be aware of browser limits and potential
+     * resulting crashes!
      *
      * If using multiple `forkJoin`s concurrently, it's the user's
-     * responsibility to ensure that the total number of workers won't
-     * exceed the browser limit (Chome/FF ~20).
+     * responsibility to ensure that the total number of workers won't exceed
+     * the browser limit (Chome/FF ~20).
      */
     numWorkers?: number;
     /**
-     * If true, the workers will be terminated and restarted for each
-     * new input stream value. This is useful to avoid executing
-     * extraneous work and ensures only the most rececent stream value
-     * is being processed.
+     * If true, the workers will be terminated and restarted for each new input
+     * stream value. This is useful to avoid executing extraneous work and
+     * ensures only the most rececent stream value is being processed.
      *
-     * IMPORTANT: Please note that `forkJoin` does NOT handle
-     * backpressure at all. If `interrupt` is false, it's the user's
-     * responsibility to ensure that the input stream does NOT operate
-     * on a higher frequency than workers can produce results or else
-     * undefined behavior WILL occur!
+     * IMPORTANT: Please note that `forkJoin` does NOT handle backpressure at
+     * all. If `interrupt` is false, it's the user's responsibility to ensure
+     * that the input stream does NOT operate on a higher frequency than workers
+     * can produce results or else undefined behavior WILL occur!
      *
      * Default: false
      */
     interrupt?: boolean;
     /**
-     * If given and greater than zero, all workers will be terminated
-     * after given period (in millis) after the parent stream is done.
-     * If used, this value MUST be higher than the expected processing
-     * time of the worker jobs, in order to guarantee that the last
-     * values are processed fully.
+     * If given and greater than zero, all workers will be terminated after
+     * given period (in millis) after the parent stream is done. If used, this
+     * value MUST be higher than the expected processing time of the worker
+     * jobs, in order to guarantee that the last values are processed fully.
      *
      * Default: 1000
      */
     terminate?: number;
     /**
-     * If greater than 0, then each labeled input will cache upto the
-     * stated number of input values, even if other inputs have not yet
-     * produced new values. Once the limit is reached, `partitionSync()`
-     * will throw an `IllegalState` error.
+     * If greater than 0, then each labeled input will cache upto the stated
+     * number of input values, even if other inputs have not yet produced new
+     * values. Once the limit is reached, `partitionSync()` will throw an
+     * `IllegalState` error.
      *
-     * Enabling this option will cause the same behavior as if `reset`
-     * is enabled (regardless of the actual configured `reset` setting).
-     * I.e. new results are only produced when ALL required inputs have
-     * available values...
+     * Enabling this option will cause the same behavior as if `reset` is
+     * enabled (regardless of the actual configured `reset` setting). I.e. new
+     * results are only produced when ALL required inputs have available
+     * values...
      */
     backPressure?: number;
 }
 /**
- * Returns a {@link StreamSync} instance which creates & attaches
- * multiple subscriptions to given `src` input stream, processes each
- * received value in parallel via web workers, then recombines partial
- * results and passes the resulting transformed value downstream.
+ * Returns a {@link StreamSync} instance which creates & attaches multiple
+ * subscriptions to given `src` input stream, processes each received value in
+ * parallel via web workers, then recombines partial results and passes the
+ * resulting transformed value downstream.
  *
  * @remarks
- * See {@link ForkJoinOpts} for further details & behavior options and
- * the {@link forkBuffer} and {@link joinBuffer} helpers for array-based
- * value processing (most likely use case).
+ * See {@link ForkJoinOpts} for further details & behavior options and the
+ * {@link forkBuffer} and {@link joinBuffer} helpers for array-based value
+ * processing (most likely use case).
  *
  * @param src - input stream
  * @param opts -
@@ -112,21 +107,20 @@ export type Sliceable<T> = ArrayLike<T> & {
  *
  * @remarks
  * The returned function is meant to be used as `fork` function in a
- * {@link ForkJoinOpts} config and extracts a workload slice of the
- * original buffer for a single worker. The HOF itself takes a minimum
- * chunk size as optional parameter (default: 1).
+ * {@link ForkJoinOpts} config and extracts a workload slice of the original
+ * buffer for a single worker. The HOF itself takes a minimum chunk size as
+ * optional parameter (default: 1).
  *
- * **Note:** Depending on the configured `minChunkSize` and the size of
- * the input buffer to be partitioned, the returned fork function might
- * produce empty sub-arrays for some workers, iff the configured number
- * of workers exceeds the resulting number of chunks / input values.
- * E.g. If the number of workers = 8, buffer size = 10 and min chunk
- * size = 2, then the last 3 (i.e. 8 - 10 / 2) workers will only receive
- * empty workloads.
+ * **Note:** Depending on the configured `minChunkSize` and the size of the
+ * input buffer to be partitioned, the returned fork function might produce
+ * empty sub-arrays for some workers, iff the configured number of workers
+ * exceeds the resulting number of chunks / input values. E.g. If the number of
+ * workers = 8, buffer size = 10 and min chunk size = 2, then the last 3 (i.e. 8
+ * - 10 / 2) workers will only receive empty workloads.
  *
- * More generally, if the input buffer size is not equally distributable
- * over the given number of workers, the last worker(s) might receive a
- * larger, smaller or empty chunk.
+ * More generally, if the input buffer size is not equally distributable over
+ * the given number of workers, the last worker(s) might receive a larger,
+ * smaller or empty chunk.
  *
  * Also see {@link forkJoin} and {@link joinBuffer}.
  *
@@ -153,15 +147,15 @@ export declare const forkBuffer: (minChunkSize?: number) => <T extends Sliceable
  *
  * @remarks
  * The returned function is meant to be used as `join` function in a
- * {@link ForkJoinOpts} config, receives the processed result chunks
- * from all workers (ordered by worker ID) and concatenates them back
- * into a single result array.
+ * {@link ForkJoinOpts} config, receives the processed result chunks from all
+ * workers (ordered by worker ID) and concatenates them back into a single
+ * result array.
  *
- * The optional `fn` arg can be used to pick the actual result chunk
- * from each worker result. This is useful if the worker result type is
- * not an array and includes other data points (e.g. execution metrics
- * etc.). If `fn` is not given, it defaults to the identity function
- * (i.e. each worker's result is assumed to be an array).
+ * The optional `fn` arg can be used to pick the actual result chunk from each
+ * worker result. This is useful if the worker result type is not an array and
+ * includes other data points (e.g. execution metrics etc.). If `fn` is not
+ * given, it defaults to the identity function (i.e. each worker's result is
+ * assumed to be an array).
  *
  * Also see {@link forkJoin} and {@link forkBuffer}.
  *

package/merge.d.ts

@@ -42,7 +42,7 @@ export interface StreamMergeOpts<A, B> extends TransformableOpts<A, B> {
  *
  * @example
  * Use the
- * [`labeled()`](https://docs.thi.ng/umbrella/transducers/functions/labeled.html)
+ * [`labeled`](https://docs.thi.ng/umbrella/transducers/functions/labeled.html)
  * transducer for each input to create a stream of labeled values and
  * track their provenance:
  *
@@ -70,7 +70,7 @@ export interface StreamMergeOpts<A, B> extends TransformableOpts<A, B> {
  */
 export declare const merge: <A, B>(opts?: Partial<StreamMergeOpts<A, B>>) => StreamMerge<A, B>;
 /**
- * @see {@link merge} for reference & examples.
+ * See {@link merge} for reference & examples.
  */
 export declare class StreamMerge<A, B> extends Subscription<A, B> {
     sources: Map<ISubscribable<A>, ISubscription<A, any>>;

package/metastream.d.ts

@@ -108,7 +108,7 @@ export interface MetaStreamOpts extends CommonOpts {
  */
 export declare const metaStream: <A, B>(factory: Fn<A, Nullable<ISubscription<B, B>>>, opts?: Partial<MetaStreamOpts>) => MetaStream<A, B>;
 /**
- * @see {@link metaStream} for reference & examples.
+ * See {@link metaStream} for reference & examples.
  */
 export declare class MetaStream<A, B> extends Subscription<A, B> {
     factory: Fn<A, Nullable<ISubscription<B, B>>>;

package/object.d.ts

@@ -6,13 +6,13 @@ export type KeyStreams<T, K extends Keys<T>> = {
 };
 export interface StreamObjOpts<T, K extends Keys<T>> extends CommonOpts {
     /**
-     * Array of selected `keys` (else selects all by default) for which
-     * to create streams.
+     * Array of selected `keys` (else selects all by default) for which to
+     * create streams.
      */
     keys: K[];
     /**
-     * If true (default), all created streams will be seeded with key
-     * values from the source object.
+     * If true (default), all created streams will be seeded with key values
+     * from the source object.
      *
      * @defaultValue true
      */
@@ -23,7 +23,7 @@ export interface StreamObjOpts<T, K extends Keys<T>> extends CommonOpts {
     defaults: Partial<T>;
     /**
      * If true, attaches
-     * [`dedupe()`](https://docs.thi.ng/umbrella/transducers/functions/dedupe.html)
+     * [`dedupe`](https://docs.thi.ng/umbrella/transducers/functions/dedupe.html)
      * transducer to each key's value stream to avoid obsolete downstream
      * propagation when a key's value hasn't actually changed.
      *
@@ -31,8 +31,8 @@ export interface StreamObjOpts<T, K extends Keys<T>> extends CommonOpts {
      */
     dedupe: boolean;
     /**
-     * Generic equality predicate to be used for `dedupe` (`===` by
-     * default). Ignored if `dedupe` option is false.
+     * Generic equality predicate to be used for `dedupe` (`===` by default).
+     * Ignored if `dedupe` option is false.
      */
     equiv: Predicate2<any>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/rstream",
-  "version": "9.2.9",
+  "version": "9.2.11",
   "description": "Reactive streams & subscription primitives for constructing dataflow graphs / pipelines",
   "type": "module",
   "module": "./index.js",
@@ -43,18 +43,18 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.19",
-    "@thi.ng/arrays": "^2.10.14",
-    "@thi.ng/associative": "^7.0.23",
-    "@thi.ng/atom": "^5.3.20",
-    "@thi.ng/checks": "^3.6.22",
-    "@thi.ng/errors": "^2.5.25",
-    "@thi.ng/logger": "^3.1.0",
-    "@thi.ng/transducers": "^9.2.17"
+    "@thi.ng/api": "^8.11.21",
+    "@thi.ng/arrays": "^2.10.16",
+    "@thi.ng/associative": "^7.0.25",
+    "@thi.ng/atom": "^5.3.22",
+    "@thi.ng/checks": "^3.6.24",
+    "@thi.ng/errors": "^2.5.27",
+    "@thi.ng/logger": "^3.1.2",
+    "@thi.ng/transducers": "^9.2.19"
   },
   "devDependencies": {
-    "esbuild": "^0.24.2",
-    "typedoc": "^0.27.6",
+    "esbuild": "^0.25.0",
+    "typedoc": "^0.27.7",
     "typescript": "^5.7.3"
   },
   "keywords": [
@@ -221,5 +221,5 @@
     ],
     "year": 2017
   },
-  "gitHead": "dcc1dbfa6eae31ac65e12843987b94d4a7edc144\n"
+  "gitHead": "bee617702ac61d093465b967f8f973dc566faa6b\n"
 }

package/pubsub.d.ts

@@ -5,19 +5,18 @@ import type { ISubscriber, ISubscription, TransformableOpts, WithErrorHandlerOpt
 import { Subscription } from "./subscription.js";
 export interface PubSubOpts<A, B, T> {
     /**
-     * Topic function. Incoming values will be routed to topic
-     * subscriptions using this function's return value.
+     * Topic function. Incoming values will be routed to topic subscriptions
+     * using this function's return value.
      */
     topic: Fn<B, T>;
     /**
-     * Optional transformer for incoming values. If given, `xform` will
-     * be applied first and the transformed value passed to the
-     * `topic` fn.
+     * Optional transformer for incoming values. If given, `xform` will be
+     * applied first and the transformed value passed to the `topic` fn.
      */
     xform?: Transducer<A, B>;
     /**
-     * Equivalence check for topic values. Should return truthy result
-     * if given topics are considered equal.
+     * Equivalence check for topic values. Should return truthy result if given
+     * topics are considered equal.
      */
     equiv?: Predicate2<T>;
     /**
@@ -34,9 +33,9 @@ export interface PubSubOpts<A, B, T> {
  * `undefined`. If the latter is returned, the incoming value will not be
  * processed further. Complex topics (e.g objects / arrays) are allowed and
  * they're matched against registered topics using
- * [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) by
- * default (but customizable via `equiv` option). Each topic can have any number
- * of subscribers.
+ * [`equiv`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) by default
+ * (but customizable via `equiv` option). Each topic can have any number of
+ * subscribers.
  *
  * If a `xform` transducer is given, it is always applied prior to passing the
  * input to the topic function. I.e. in this case the topic function will
@@ -54,7 +53,7 @@ export interface PubSubOpts<A, B, T> {
  */
 export declare const pubsub: <A, B = A, T = any>(opts: PubSubOpts<A, B, T>) => PubSub<A, B, T>;
 /**
- * @see {@link pubsub} for reference & examples.
+ * See {@link pubsub} for reference & examples.
  */
 export declare class PubSub<A, B = A, T = any> extends Subscription<A, B> {
     topicfn: Fn<B, T>;

package/raf.d.ts

@@ -3,7 +3,7 @@ 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.
+     * counter `[0,∞)` will be emitted.
      *
      * @defaultValue false
      */

package/stream.d.ts

@@ -68,7 +68,7 @@ export declare function stream<T>(src: StreamSource<T>, opts?: Partial<WithError
  */
 export declare const reactive: <T>(val: T, opts?: Partial<CommonOpts>) => Stream<T>;
 /**
- * @see {@link stream} & {@link reactive} for reference & examples.
+ * See {@link stream} & {@link reactive} for reference & examples.
  */
 export declare class Stream<T> extends Subscription<T, T> implements IStream<T> {
     src?: StreamSource<T>;

package/subscription.d.ts

@@ -83,7 +83,7 @@ export declare class Subscription<A, B> implements ISubscription<A, B> {
      * Creates a new child subscription using given transducers and optional
      * subscription ID. Supports up to 4 transducers and if more than one
      * transducer is given, composes them in left-to-right order using
-     * [`comp()`](https://docs.thi.ng/umbrella/transducers/functions/comp.html).
+     * [`comp`](https://docs.thi.ng/umbrella/transducers/functions/comp.html).
      *
      * Shorthand for `subscribe(comp(xf1, xf2,...), id)`
      */
@@ -94,7 +94,7 @@ export declare class Subscription<A, B> implements ISubscription<A, B> {
     transform<C>(opts: WithTransform<B, C> & Partial<WithErrorHandlerOpts>): ISubscription<B, C>;
     /**
      * Syntax sugar for {@link Subscription.transform} when using a single
-     * [`map()`](https://docs.thi.ng/umbrella/transducers/functions/map.html)
+     * [`map`](https://docs.thi.ng/umbrella/transducers/functions/map.html)
      * transducer only. The given function `fn` is used as `map`'s
      * transformation fn.
      *

package/subscription.js

@@ -87,7 +87,7 @@ class Subscription {
   }
   /**
    * Syntax sugar for {@link Subscription.transform} when using a single
-   * [`map()`](https://docs.thi.ng/umbrella/transducers/functions/map.html)
+   * [`map`](https://docs.thi.ng/umbrella/transducers/functions/map.html)
    * transducer only. The given function `fn` is used as `map`'s
    * transformation fn.
    *

package/sync.d.ts

@@ -87,7 +87,7 @@ export interface StreamSyncOpts<A extends IObjectOf<ISubscribable<any>>, B = Syn
  * option to `false`.
  *
  * The synchronization is done via the
- * [`partitionSync()`](https://docs.thi.ng/umbrella/transducers/functions/partitionSync-1.html)
+ * [`partitionSync`](https://docs.thi.ng/umbrella/transducers/functions/partitionSync-1.html)
  * transducer from the [`thi.ng/transducers`](https://thi.ng/transducers)
  * package. See this function's docs for further details.
  *
@@ -119,7 +119,7 @@ export interface StreamSyncOpts<A extends IObjectOf<ISubscribable<any>>, B = Syn
  */
 export declare const sync: <A extends IObjectOf<ISubscribable<any>>, B = SyncTuple<A>>(opts: Partial<StreamSyncOpts<A, B>>) => StreamSync<A, B>;
 /**
- * @see {@link sync} for reference & examples.
+ * See {@link sync} for reference & examples.
  */
 export declare class StreamSync<A extends IObjectOf<ISubscribable<any>>, B = SyncTuple<A>> extends Subscription<any, B> {
     /**

package/tunnel.d.ts

@@ -58,7 +58,7 @@ export interface TunnelOpts<A> {
  */
 export declare const tunnel: <A, B>(opts: TunnelOpts<A>) => Tunnel<A, B>;
 /**
- * @see {@link tunnel} for reference & examples.
+ * See {@link tunnel} for reference & examples.
  */
 export declare class Tunnel<A, B> extends Subscription<A, B> {
     workers: Worker[];

package/view.d.ts

@@ -53,7 +53,7 @@ export declare const fromViewUnsafe: <T>(atom: ReadonlyAtom<any>, opts: FromView
  * Views are readonly and more lightweight versions of [thi.ng/atom
  * cursors](https://docs.thi.ng/umbrella/atom/classes/Cursor.html). The view
  * checks for value changes with given `equiv` predicate (default:
- * [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html)). If the
+ * [`equiv`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html)). If the
  * predicate returns a falsy result (i.e. there's a new value), the new value is
  * emitted on the stream. The first value emitted is always the (possibly
  * transformed) current value at the stream's start time (i.e. when the first
@@ -65,8 +65,8 @@ export declare const fromViewUnsafe: <T>(atom: ReadonlyAtom<any>, opts: FromView
  * When the stream is cancelled the view is destroyed as well.
  *
  * Also see
- * [`defView()`](https://docs.thi.ng/umbrella/atom/functions/defView.html),
- * [`defViewUnsafe()`](https://docs.thi.ng/umbrella/atom/functions/defViewUnsafe.html)
+ * [`defView`](https://docs.thi.ng/umbrella/atom/functions/defView.html),
+ * [`defViewUnsafe`](https://docs.thi.ng/umbrella/atom/functions/defViewUnsafe.html)
  *
  * @example
  * ```ts tangle:../export/from-view.ts