@thi.ng/transducers 8.4.7 → 8.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-06-14T07:58:51Z
+- **Last updated**: 2023-08-04T10:58:19Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,20 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [8.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/transducers@8.5.0) (2023-08-04)
+
+#### 🚀 Features
+
+- fix [#401](https://github.com/thi-ng/umbrella/issues/401), update multiplex(), step() ([834b076](https://github.com/thi-ng/umbrella/commit/834b076))
+  - add optional support to override single-result unwrapping behavior
+  - update docstrings/examples
+  - add tests
+
+#### ♻️ Refactoring
+
+- update `identity` usage in various pkgs ([b6db053](https://github.com/thi-ng/umbrella/commit/b6db053))
+- minor internal updates ([5ffdcbb](https://github.com/thi-ng/umbrella/commit/5ffdcbb))
+
 ## [8.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/transducers@8.4.0) (2023-03-19)
 
 #### 🚀 Features

package/README.md

@@ -173,7 +173,7 @@ For Node.js REPL:
 const transducers = await import("@thi.ng/transducers");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 8.64 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 8.70 KB
 
 ## Dependencies
 
@@ -206,6 +206,7 @@ A selection:
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/dominant-colors.png" width="240"/>               | Color palette generation via dominant color extraction from uploaded images      | [Demo](https://demo.thi.ng/umbrella/dominant-colors/)      | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/dominant-colors)     |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/ellipse-proximity.png" width="240"/>             | Interactive visualization of closest points on ellipses                          | [Demo](https://demo.thi.ng/umbrella/ellipse-proximity/)    | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/ellipse-proximity)   |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/fft-synth.png" width="240"/>                     | Interactive inverse FFT toy synth                                                | [Demo](https://demo.thi.ng/umbrella/fft-synth/)            | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/fft-synth)           |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/fiber-basics.png" width="240"/>                  | Fiber-based cooperative multitasking basics                                      | [Demo](https://demo.thi.ng/umbrella/fiber-basics/)         | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/fiber-basics)        |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/grid-iterators.png" width="240"/>                | Visualization of different grid iterator strategies                              | [Demo](https://demo.thi.ng/umbrella/grid-iterators/)       | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/grid-iterators)      |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/hdom-benchmark2.png" width="240"/>               | hdom update performance benchmark w/ config options                              | [Demo](https://demo.thi.ng/umbrella/hdom-benchmark2/)      | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/hdom-benchmark2)     |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/hdom-canvas-clock.png" width="240"/>             | Realtime analog clock demo                                                       | [Demo](https://demo.thi.ng/umbrella/hdom-canvas-clock/)    | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/hdom-canvas-clock)   |

package/api.d.ts

@@ -1,11 +1,19 @@
-import type { Comparator, Fn, IObjectOf } from "@thi.ng/api";
+import type { Comparator, Fn, Fn0, IObjectOf } from "@thi.ng/api";
 import type { Reduced } from "./reduced.js";
 export type Transducer<A, B> = (rfn: Reducer<any, B>) => Reducer<any, A>;
+/**
+ * A transducer or a custom type with a {@link IXform} implementation.
+ */
 export type TxLike<A, B> = Transducer<A, B> | IXform<A, B>;
+/**
+ * Custom version of {@link TxLike} for use with {@link multiplex} and
+ * {@link multiplexObj}.
+ */
+export type MultiplexTxLike<T, A> = TxLike<T, A> | [TxLike<T, A>, boolean];
 export type ReductionFn<A, B> = (acc: A, x: B) => A | Reduced<A>;
 export interface Reducer<A, B> extends Array<any> {
-    [0]: () => A;
-    [1]: (acc: A) => A;
+    [0]: Fn0<A>;
+    [1]: Fn<A, A>;
     [2]: ReductionFn<A, B>;
 }
 /**
@@ -15,7 +23,7 @@ export interface Reducer<A, B> extends Array<any> {
  * functions in this package where a `Transducer` arg is expected.
  *
  * @example
- * ```
+ * ```ts
  * class Mul implements IXform<number, number> {
  *   constructor(public factor = 10) {}
  *

package/flatten1.js

@@ -1,4 +1,5 @@
+import { identity } from "@thi.ng/api/fn";
 import { mapcat } from "./mapcat.js";
 export function flatten1(src) {
-    return mapcat((x) => x, src);
+    return mapcat((identity), src);
 }

package/labeled.d.ts

@@ -1,5 +1,6 @@
+import type { Fn } from "@thi.ng/api";
 import type { Transducer } from "./api.js";
-export type LabelFn<L, T> = L | ((x: T) => L);
+export type LabelFn<L, T> = L | Fn<T, L>;
 export declare function labeled<L, T>(id: LabelFn<L, T>): Transducer<T, [L, T]>;
 export declare function labeled<L, T>(id: LabelFn<L, T>, src: Iterable<T>): IterableIterator<[L, T]>;
 //# sourceMappingURL=labeled.d.ts.map

package/multiplex-obj.d.ts

@@ -1,5 +1,5 @@
 import type { IObjectOf } from "@thi.ng/api";
-import type { Reducer, Transducer, TxLike } from "./api.js";
+import type { MultiplexTxLike, Reducer, Transducer } from "./api.js";
 /**
  * Transducer. Similar to (and building on) {@link multiplex}, but takes an
  * object of transducers and produces a result object for each input.
@@ -12,19 +12,18 @@ import type { Reducer, Transducer, TxLike } from "./api.js";
  *     upper:   map(x => x.toUpperCase()),
  *     length:  map(x => x.length)
  *   },
- *   ["Alice", "Bob", "Charlie", "Andy"]
+ *   ["Alice", "Bob", "Charlie"]
  * )]
  * // [ { length: 5, upper: 'ALICE', initial: 'A' },
  * //   { length: 3, upper: 'BOB', initial: 'B' },
- * //   { length: 7, upper: 'CHARLIE', initial: 'C' },
- * //   { length: 4, upper: 'ANDY', initial: 'A' } ]
+ * //   { length: 7, upper: 'CHARLIE', initial: 'C' } ]
  * ```
  *
  * @param xforms - object of transducers
  * @param rfn -
  * @param src -
  */
-export declare function multiplexObj<A, B>(xforms: IObjectOf<TxLike<A, any>>, rfn?: Reducer<B, [PropertyKey, any]>): Transducer<A, B>;
-export declare function multiplexObj<A, B>(xforms: IObjectOf<TxLike<A, any>>, src: Iterable<A>): IterableIterator<B>;
-export declare function multiplexObj<A, B>(xforms: IObjectOf<TxLike<A, any>>, rfn: Reducer<B, [PropertyKey, any]>, src: Iterable<A>): IterableIterator<B>;
+export declare function multiplexObj<A, B>(xforms: IObjectOf<MultiplexTxLike<A, any>>, rfn?: Reducer<B, [PropertyKey, any]>): Transducer<A, B>;
+export declare function multiplexObj<A, B>(xforms: IObjectOf<MultiplexTxLike<A, any>>, src: Iterable<A>): IterableIterator<B>;
+export declare function multiplexObj<A, B>(xforms: IObjectOf<MultiplexTxLike<A, any>>, rfn: Reducer<B, [PropertyKey, any]>, src: Iterable<A>): IterableIterator<B>;
 //# sourceMappingURL=multiplex-obj.d.ts.map

package/multiplex.d.ts

@@ -1,4 +1,4 @@
-import type { Transducer, TxLike } from "./api.js";
+import type { MultiplexTxLike, Transducer } from "./api.js";
 /**
  * Yields a new transducer which applies given transducers in parallel (using
  * [`juxt()`](https://docs.thi.ng/umbrella/compose/functions/juxt.html) &
@@ -8,6 +8,12 @@ import type { Transducer, TxLike } from "./api.js";
  * Use the {@link noop} transducer for processing lanes which should retain the
  * original input values.
  *
+ * **Important note for transducers which are producing multiple (possibly
+ * varying number of) outputs for each received input:** If only a single output
+ * is produced per step, the default behavior of {@link step} is to unwrap it,
+ * i.e. `[42]` => `42`. To override this behavior, individual transducers given
+ * to `multiplex()` can be given as tuple `[xform, false]` (see 2nd example below).
+ *
  * @example
  * ```ts
  * [...iterator(
@@ -16,19 +22,41 @@ import type { Transducer, TxLike } from "./api.js";
  *     map(x => x.toUpperCase()),
  *     map(x => x.length)
  *   ),
- *   ["Alice", "Bob", "Charlie", "Andy"]
+ *   ["Alice", "Bob", "Charlie"]
  * )]
+ *
  * // [ [ "A", "ALICE", 5 ], [ "B", "BOB", 3 ], [ "C", "CHARLIE", 7 ] ]
  * ```
  *
+ * @example
+ * ```ts
+ * [...iterator(
+ *   multiplex(
+ *     // override default unwrap behavior for this transducer
+ *     // (i.e. here to ensure results are always arrays)
+ *     [mapcat((x) => x), false],
+ *     // use default behavior for this
+ *     map((x) => x),
+ *   ),
+ *   [[1, 2], [3]]
+ * )]
+ *
+ * // [ [ [ 1, 2 ], [ 1, 2 ] ], [ [ 3 ], [ 3 ] ] ]
+ *
+ * // to compare: using the default behavior would produce this instead
+ * // (note the difference in the last result):
+ *
+ * // [ [ [ 1, 2 ], [ 1, 2 ] ], [ 3, [ 3 ] ] ]
+ * ```
+ *
  * @param a -
  */
-export declare function multiplex<T, A>(a: TxLike<T, A>): Transducer<T, [A]>;
-export declare function multiplex<T, A, B>(a: TxLike<T, A>, b: TxLike<T, B>): Transducer<T, [A, B]>;
-export declare function multiplex<T, A, B, C>(a: TxLike<T, A>, b: TxLike<T, B>, c: TxLike<T, C>): Transducer<T, [A, B, C]>;
-export declare function multiplex<T, A, B, C, D>(a: TxLike<T, A>, b: TxLike<T, B>, c: TxLike<T, C>, d: TxLike<T, D>): Transducer<T, [A, B, C, D]>;
-export declare function multiplex<T, A, B, C, D, E>(a: TxLike<T, A>, b: TxLike<T, B>, c: TxLike<T, C>, d: TxLike<T, D>, e: TxLike<T, E>): Transducer<T, [A, B, C, D, E]>;
-export declare function multiplex<T, A, B, C, D, E, F>(a: TxLike<T, A>, b: TxLike<T, B>, c: TxLike<T, C>, d: TxLike<T, D>, e: TxLike<T, E>, f: TxLike<T, F>): Transducer<T, [A, B, C, D, E, F]>;
-export declare function multiplex<T, A, B, C, D, E, F, G>(a: TxLike<T, A>, b: TxLike<T, B>, c: TxLike<T, C>, d: TxLike<T, D>, e: TxLike<T, E>, f: TxLike<T, F>, g: TxLike<T, G>): Transducer<T, [A, B, C, D, E, F, G]>;
-export declare function multiplex<T, A, B, C, D, E, F, G, H>(a: TxLike<T, A>, b: TxLike<T, B>, c: TxLike<T, C>, d: TxLike<T, D>, e: TxLike<T, E>, f: TxLike<T, F>, g: TxLike<T, G>, h: TxLike<T, H>): Transducer<T, [A, B, C, D, E, F, G, H]>;
+export declare function multiplex<T, A>(a: MultiplexTxLike<T, A>): Transducer<T, [A]>;
+export declare function multiplex<T, A, B>(a: MultiplexTxLike<T, A>, b: MultiplexTxLike<T, B>): Transducer<T, [A, B]>;
+export declare function multiplex<T, A, B, C>(a: MultiplexTxLike<T, A>, b: MultiplexTxLike<T, B>, c: MultiplexTxLike<T, C>): Transducer<T, [A, B, C]>;
+export declare function multiplex<T, A, B, C, D>(a: MultiplexTxLike<T, A>, b: MultiplexTxLike<T, B>, c: MultiplexTxLike<T, C>, d: MultiplexTxLike<T, D>): Transducer<T, [A, B, C, D]>;
+export declare function multiplex<T, A, B, C, D, E>(a: MultiplexTxLike<T, A>, b: MultiplexTxLike<T, B>, c: MultiplexTxLike<T, C>, d: MultiplexTxLike<T, D>, e: MultiplexTxLike<T, E>): Transducer<T, [A, B, C, D, E]>;
+export declare function multiplex<T, A, B, C, D, E, F>(a: MultiplexTxLike<T, A>, b: MultiplexTxLike<T, B>, c: MultiplexTxLike<T, C>, d: MultiplexTxLike<T, D>, e: MultiplexTxLike<T, E>, f: MultiplexTxLike<T, F>): Transducer<T, [A, B, C, D, E, F]>;
+export declare function multiplex<T, A, B, C, D, E, F, G>(a: MultiplexTxLike<T, A>, b: MultiplexTxLike<T, B>, c: MultiplexTxLike<T, C>, d: MultiplexTxLike<T, D>, e: MultiplexTxLike<T, E>, f: MultiplexTxLike<T, F>, g: MultiplexTxLike<T, G>): Transducer<T, [A, B, C, D, E, F, G]>;
+export declare function multiplex<T, A, B, C, D, E, F, G, H>(a: MultiplexTxLike<T, A>, b: MultiplexTxLike<T, B>, c: MultiplexTxLike<T, C>, d: MultiplexTxLike<T, D>, e: MultiplexTxLike<T, E>, f: MultiplexTxLike<T, F>, g: MultiplexTxLike<T, G>, h: MultiplexTxLike<T, H>): Transducer<T, [A, B, C, D, E, F, G, H]>;
 //# sourceMappingURL=multiplex.d.ts.map

package/multiplex.js

@@ -2,5 +2,5 @@ import { juxt } from "@thi.ng/compose/juxt";
 import { map } from "./map.js";
 import { step } from "./step.js";
 export function multiplex(...args) {
-    return map(juxt.apply(null, args.map(step)));
+    return map(juxt.apply(null, (args.map((xf) => Array.isArray(xf) ? step(xf[0], xf[1]) : step(xf)))));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/transducers",
-  "version": "8.4.7",
+  "version": "8.5.0",
   "description": "Lightweight transducer implementations for ES6 / TypeScript",
   "type": "module",
   "module": "./index.js",
@@ -38,22 +38,22 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.8.2",
-    "@thi.ng/arrays": "^2.5.14",
-    "@thi.ng/checks": "^3.3.14",
-    "@thi.ng/compare": "^2.1.32",
-    "@thi.ng/compose": "^2.1.34",
-    "@thi.ng/errors": "^2.2.17",
-    "@thi.ng/math": "^5.5.0",
-    "@thi.ng/random": "^3.5.0"
+    "@thi.ng/api": "^8.9.0",
+    "@thi.ng/arrays": "^2.5.15",
+    "@thi.ng/checks": "^3.4.0",
+    "@thi.ng/compare": "^2.1.33",
+    "@thi.ng/compose": "^2.1.35",
+    "@thi.ng/errors": "^2.3.0",
+    "@thi.ng/math": "^5.5.1",
+    "@thi.ng/random": "^3.5.1"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.35.3",
-    "@thi.ng/testament": "^0.3.17",
+    "@microsoft/api-extractor": "^7.36.3",
+    "@thi.ng/testament": "^0.3.18",
     "rimraf": "^5.0.1",
     "tools": "^0.0.1",
     "typedoc": "^0.24.8",
-    "typescript": "^5.1.3"
+    "typescript": "^5.1.6"
   },
   "keywords": [
     "2d",
@@ -574,5 +574,5 @@
     ],
     "year": 2016
   },
-  "gitHead": "88cfe77770f3b07c788301dccefcb9547cd4aff6\n"
+  "gitHead": "9fa3f7f8169efa30e3c71b43c82f77393581c3b5\n"
 }

package/repeatedly.d.ts

@@ -9,6 +9,7 @@ import type { Fn } from "@thi.ng/api";
  * [...repeatedly(() => Math.floor(Math.random() * 10), 5)]
  * // [7, 0, 9, 3, 1]
  *
+ * // same result as range(5)
  * [...repeatedly((i) => i, 5)]
  * // [0, 1, 2, 3, 4]
  * ```

package/repeatedly.js

@@ -8,6 +8,7 @@
  * [...repeatedly(() => Math.floor(Math.random() * 10), 5)]
  * // [7, 0, 9, 3, 1]
  *
+ * // same result as range(5)
  * [...repeatedly((i) => i, 5)]
  * // [0, 1, 2, 3, 4]
  * ```

package/step.d.ts

@@ -1,25 +1,38 @@
+import type { Fn } from "@thi.ng/api";
 import type { TxLike } from "./api.js";
 /**
- * Single-step transducer execution wrapper.
- * Returns array if transducer produces multiple results
- * and undefined if there was no output. Else returns single
- * result value.
+ * Single-step transducer execution wrapper. Returns array if the given
+ * transducer produces multiple results and undefined if there was no output. If
+ * the transducer only produces a single result (per step) and if `unwrap`
+ * is true (default), the function returns that single result value itself.
  *
  * @remarks
- * Likewise, once a transducer has produced a final / reduced
- * value, all further invocations of the stepper function will
- * return undefined.
+ * Likewise, once a transducer has produced a final / reduced value, all further
+ * invocations of the stepper function will return undefined.
  *
  * @example
  * ```ts
- * // single result
+ * // single result (unwrapped, default)
  * step(map(x => x * 10))(1);
  * // 10
  *
+ * // single result (no unwrapping)
+ * step(map(x => x * 10), false)(1);
+ * // [10]
+ *
  * // multiple results
  * step(mapcat(x => [x, x + 1, x + 2]))(1)
  * // [ 1, 2, 3 ]
  *
+ * // multiple results (default behavior)
+ * step(mapcat(x => x))([1, 2])
+ * // [1, 2]
+ * step(mapcat(x => x))([3])
+ * // 3
+ * // ...once more without unwrapping
+ * step(mapcat(x => x), false)([3])
+ * // [3]
+ *
  * // no result
  * f = step(filter((x) => !(x & 1)))
  * f(1); // undefined
@@ -34,6 +47,7 @@ import type { TxLike } from "./api.js";
  * ```
  *
  * @param tx -
+ * @param unwrap -
  */
-export declare const step: <A, B>(tx: TxLike<A, B>) => (x: A) => B | B[];
+export declare const step: <A, B>(tx: TxLike<A, B>, unwrap?: boolean) => Fn<A, B | B[]>;
 //# sourceMappingURL=step.d.ts.map

package/step.js

@@ -2,26 +2,38 @@ import { ensureTransducer } from "./ensure.js";
 import { push } from "./push.js";
 import { isReduced } from "./reduced.js";
 /**
- * Single-step transducer execution wrapper.
- * Returns array if transducer produces multiple results
- * and undefined if there was no output. Else returns single
- * result value.
+ * Single-step transducer execution wrapper. Returns array if the given
+ * transducer produces multiple results and undefined if there was no output. If
+ * the transducer only produces a single result (per step) and if `unwrap`
+ * is true (default), the function returns that single result value itself.
  *
  * @remarks
- * Likewise, once a transducer has produced a final / reduced
- * value, all further invocations of the stepper function will
- * return undefined.
+ * Likewise, once a transducer has produced a final / reduced value, all further
+ * invocations of the stepper function will return undefined.
  *
  * @example
  * ```ts
- * // single result
+ * // single result (unwrapped, default)
  * step(map(x => x * 10))(1);
  * // 10
  *
+ * // single result (no unwrapping)
+ * step(map(x => x * 10), false)(1);
+ * // [10]
+ *
  * // multiple results
  * step(mapcat(x => [x, x + 1, x + 2]))(1)
  * // [ 1, 2, 3 ]
  *
+ * // multiple results (default behavior)
+ * step(mapcat(x => x))([1, 2])
+ * // [1, 2]
+ * step(mapcat(x => x))([3])
+ * // 3
+ * // ...once more without unwrapping
+ * step(mapcat(x => x), false)([3])
+ * // [3]
+ *
  * // no result
  * f = step(filter((x) => !(x & 1)))
  * f(1); // undefined
@@ -36,8 +48,9 @@ import { isReduced } from "./reduced.js";
  * ```
  *
  * @param tx -
+ * @param unwrap -
  */
-export const step = (tx) => {
+export const step = (tx, unwrap = true) => {
     const { 1: complete, 2: reduce } = ensureTransducer(tx)(push());
     let done = false;
     return (x) => {
@@ -47,7 +60,11 @@ export const step = (tx) => {
             if (done) {
                 acc = complete(acc.deref());
             }
-            return acc.length === 1 ? acc[0] : acc.length > 0 ? acc : undefined;
+            return acc.length === 1 && unwrap
+                ? acc[0]
+                : acc.length > 0
+                    ? acc
+                    : undefined;
         }
     };
 };