@thi.ng/transducers 9.0.5 → 9.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/transducers",
-  "version": "9.0.5",
+  "version": "9.0.6",
   "description": "Lightweight transducer implementations for ES6 / TypeScript",
   "type": "module",
   "module": "./index.js",
@@ -10,7 +10,7 @@
     "type": "git",
     "url": "https://github.com/thi-ng/umbrella.git"
   },
-  "homepage": "https://github.com/thi-ng/umbrella/tree/develop/packages/transducers#readme",
+  "homepage": "https://thi.ng/transducers",
   "funding": [
     {
       "type": "github",
@@ -40,20 +40,20 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.2",
-    "@thi.ng/arrays": "^2.9.6",
-    "@thi.ng/checks": "^3.6.4",
-    "@thi.ng/compare": "^2.3.5",
-    "@thi.ng/compose": "^3.0.4",
-    "@thi.ng/errors": "^2.5.7",
-    "@thi.ng/math": "^5.10.13",
-    "@thi.ng/random": "^3.8.0"
+    "@thi.ng/api": "^8.11.3",
+    "@thi.ng/arrays": "^2.9.7",
+    "@thi.ng/checks": "^3.6.5",
+    "@thi.ng/compare": "^2.3.6",
+    "@thi.ng/compose": "^3.0.5",
+    "@thi.ng/errors": "^2.5.8",
+    "@thi.ng/math": "^5.11.0",
+    "@thi.ng/random": "^3.8.1"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.43.2",
-    "esbuild": "^0.21.1",
+    "@microsoft/api-extractor": "^7.47.0",
+    "esbuild": "^0.21.5",
     "typedoc": "^0.25.13",
-    "typescript": "^5.4.5"
+    "typescript": "^5.5.2"
   },
   "keywords": [
     "2d",
@@ -589,5 +589,5 @@
     ],
     "year": 2016
   },
-  "gitHead": "df34b4a9e650cc7323575356de207d78933bdcf3\n"
+  "gitHead": "154c95cf9d6bab32174498ec3b5b5d87e42be7f9\n"
 }

package/pad-last.d.ts

@@ -1,33 +1,42 @@
 import type { Transducer } from "./api.js";
 /**
- * Ensures the total number of transformed values will be multiples of
- * `n`.
+ * Ensures the total number of transformed values will be multiples of `n`.
  *
  * @remarks
- * Only makes sense for finite streams / reductions. Does nothing if the
- * to be transformed data source has exactly multiple of `n` values, but
- * if not pads / supplies additional `fill` values at the end until the
- * next multiple is reached. No padding takes place if input is empty,
- * since length 0 is always a multiple.
+ * Only makes sense for finite streams / reductions. Does nothing if the to be
+ * transformed data source has exactly multiple of `n` values, but if not pads /
+ * supplies additional `fill` values at the end until the next multiple is
+ * reached. No padding takes place if input is empty, since length 0 is always a
+ * multiple.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/pad-last.ts
  * import { padLast } from "@thi.ng/transducers";
  *
- * [...padLast(8, 0, [1, 2, 3, 4, 5])]
+ * console.log(
+ *   [...padLast(8, 0, [1, 2, 3, 4, 5])]
+ * );
  * // [ 1, 2, 3, 4, 5, 0, 0, 0 ]
  *
- * [...padLast(8, 0, [1])]
+ * console.log(
+ *   [...padLast(8, 0, [1])]
+ * );
  * // [ 1, 0, 0, 0, 0, 0, 0, 0 ]
  *
- * [...padLast(8, 0, [])]
+ * console.log(
+ *   [...padLast(8, 0, [])]
+ * );
  * // []
  *
- * [...padLast(2, 0, [1, 2, 3])]
- * // [ 1, 2, 3, 0 ]
+ * console.log(
+ *   [...padLast(4, 0, [1, 2])]
+ * );
+ * // [ 1, 2, 0, 0 ]
  *
- * [...padLast(2, 0, [1, 2, 3, 4])]
- * // [ 1, 2, 3, 4 ]
+ * console.log(
+ *   [...padLast(4, 0, [1, 2, 3, 4, 5])]
+ * );
+ * // [ 1, 2, 3, 4, 5, 0, 0, 0 ]
  * ```
  *
  * @param n -

package/pad-sides.d.ts

@@ -9,17 +9,39 @@
  * {@link wrapSides}.
  *
  * @example
- * ```ts
- * import { concat, repeat } from "@thi.ng/transducers";
+ * ```ts tangle:../export/pad-sides.ts
+ * import { padSides, range } from "@thi.ng/transducers";
+ *
+ * // pad both sides with 10
+ * console.log(
+ *   [...padSides(range(3), 10)]
+ * );
+ *
+ * // pad both sides 3x
+ * console.log(
+ *   [...padSides(range(3), 10, 3)]
+ * );
+ *
+ * // left/start only
+ * console.log(
+ *   [...padSides(range(3), 10, 3, 0)]
+ * );
+ *
+ * // right/end only
+ * console.log(
+ *   [...padSides(range(3), 10, 0, 3)]
+ * );
+ *
+ * // padSides() is syntax sugar for:
  *
  * // default
- * concat(repeat(x, numLeft), src, repeat(x, numRight))
+ * // concat(repeat(x, numLeft), src, repeat(x, numRight))
  *
  * // left only
- * concat(repeat(x, numLeft), src)
+ * // concat(repeat(x, numLeft), src)
  *
  * // right only
- * concat(src, repeat(x, numRight))
+ * // concat(src, repeat(x, numRight))
  * ```
  *
  * @param src -

package/page.d.ts

@@ -8,19 +8,27 @@ import type { Transducer } from "./api.js";
  * is used as early as possible / prior to any heavy processing steps.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/page.ts
  * import { page, range } from "@thi.ng/transducers";
  *
- * [...page(0, 5, range(12))]
+ * console.log(
+ *   [...page(0, 5, range(12))]
+ * );
  * // [ 0, 1, 2, 3, 4 ]
  *
- * [...page(1, 5, range(12))]
+ * console.log(
+ *   [...page(1, 5, range(12))]
+ * );
  * // [ 5, 6, 7, 8, 9 ]
  *
- * [...page(2, 5, range(12))]
+ * console.log(
+ *   [...page(2, 5, range(12))]
+ * );
  * // [ 10, 11 ]
  *
- * [...page(3, 5, range(12))]
+ * console.log(
+ *   [...page(3, 5, range(12))]
+ * );
  * // []
  * ```
  *

package/pairs.d.ts

@@ -1,17 +1,20 @@
 import type { IObjectOf } from "@thi.ng/api";
 /**
  * Iterator yielding key-value pairs of given object's own properties and their
- * values. Same as `zip(keys(x), vals(x))`.
+ * values. Same as `zip(keys(x), vals(x))` or iterator version of
+ * `Object.entries(x)`.
  *
  * @remarks
  * - {@link vals}
  * - {@link zip}
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/pairs.ts
  * import { pairs } from "@thi.ng/transducers";
  *
- * [...pairs({ a: 1, b: 2 })]
+ * console.log(
+ *   [...pairs({ a: 1, b: 2 })]
+ * );
  * // [['a', 1], ['b', 2]]
  * ```
  *

package/palindrome.d.ts

@@ -4,15 +4,28 @@
  *
  * @remarks
  * In the general case, this is similar to `concat(x, reverse(x))`,
- * though keeps input type intact.
+ * though this function keeps input type intact.
+ *
+ * Uses {@link symmetric}.for all inputs other than arrays or strings.
  *
  * @example
- * ```ts
- * import { palindrome } from "@thi.ng/transducers";
+ * ```ts tangle:../export/palindrome.ts
+ * import { palindrome, range } from "@thi.ng/transducers";
+ *
+ * console.log(
+ *   palindrome("hello")
+ * );
+ * // "helloolleh"
+ *
+ * console.log(
+ *   palindrome([1, 2, 3])
+ * );
+ * // [1, 2, 3, 3, 2, 1]
  *
- * palindrome("hello"); // "helloolleh"
- * palindrome([1, 2, 3]); // [1, 2, 3, 3, 2, 1]
- * palindrome(range(3)); // IterableIterator<number>
+ * console.log(
+ *   [...palindrome(range(3))]
+ * );
+ * // [ 0, 1, 2, 2, 1, 0 ]
  * ```
  *
  * @param x -

package/palindrome.js

@@ -1,11 +1,11 @@
-import { ensureArray } from "@thi.ng/arrays/ensure-array";
 import { isArray } from "@thi.ng/checks/is-array";
 import { isString } from "@thi.ng/checks/is-string";
 import { concat } from "./concat.js";
 import { reverse } from "./reverse.js";
 import { str } from "./str.js";
+import { symmetric } from "./symmetric.js";
 function palindrome(x) {
-  return isString(x) ? str("", concat([x], reverse(x))) : isArray(x) ? x.concat(x.slice().reverse()) : (x = ensureArray(x), concat(x, reverse(x)));
+  return isString(x) ? str("", concat([x], reverse(x))) : isArray(x) ? x.concat(x.slice().reverse()) : symmetric(x);
 }
 export {
   palindrome

package/partition-by.d.ts

@@ -6,10 +6,12 @@ import type { Transducer } from "./api.js";
  * happens yields chunk of buffered values.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/partition-by.ts
  * import { partitionBy } from "@thi.ng/transducers";
  *
- * [...partitionBy((x) => x & 1, [1, 2, 4, 6, 3, 5, 8, 4])]
+ * console.log(
+ *   [...partitionBy((x) => x & 1, [1, 2, 4, 6, 3, 5, 8, 4])]
+ * );
  * // [ [ 1 ], [ 2, 4, 6 ], [ 3, 5 ], [ 8, 4 ] ]
  * ```
  *

package/partition-of.d.ts

@@ -4,10 +4,12 @@ import type { Transducer } from "./api.js";
  * chunks. The last partition emitted is allowed to be incomplete.
  *
  * @example
- * ```ts
- * import { partitionOf } from "@thi.ng/transducers";
+ * ```ts tangle:../export/partition-of.ts
+ * import { partitionOf, range } from "@thi.ng/transducers";
  *
- * [...partitionOf([3,2,4], range(20))]
+ * console.log(
+ *   [...partitionOf([3, 2, 4], range(20))]
+ * );
  * // [ [ 0, 1, 2 ],
  * //   [ 3, 4 ],
  * //   [ 5, 6, 7, 8 ],

package/partition-sort.d.ts

@@ -10,20 +10,26 @@ import type { SortOpts, Transducer } from "./api.js";
  * compute a sortable value and change sorting behavior.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/partition-sort.ts
  * import { partitionSort } from "@thi.ng/transducers";
  *
- * [...partitionSort(4, [5,9,2,6,4,1,3,8,7,0])]
+ * console.log(
+ *   [...partitionSort(4, [5, 9, 2, 6, 4, 1, 3, 8, 7, 0])]
+ * );
  * // [ 2, 5, 6, 9, 1, 3, 4, 8, 0, 7 ]
  *
  * // with key fn and custom comparator
- * [...partitionSort(3, (x) => x.val, (a, b) => b - a,
+ * const res = [...partitionSort(
+ *   3,
+ *   { key: (x) => x.val, compare: (a, b) => b - a },
  *   [
  *     { id: "a", val: 5 },
  *     { id: "b", val: 7 },
  *     { id: "c", val: 8 }
  *   ]
- * )]
+ * )];
+ *
+ * console.log(res);
  * // [ { id: 'c', val: 8 }, { id: 'b', val: 7 }, { id: 'a', val: 5 } ]
  * ```
  *

package/partition-sync.d.ts

@@ -68,17 +68,19 @@ export interface PartitionSyncOpts<T> {
  * via `.add(id)` or `.delete(id)` on the returned transducer.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/partition-sync.ts
  * import { partitionSync } from "@thi.ng/transducers";
  *
- * src = [
+ * const src = [
  *   ["a", 1], ["a", 2], ["d", 100], ["b", 10],
  *   ["b", 11], ["c", 0], ["a", 3]
  * ];
  *
  * // form tuples for values only from sources "a" & "b"
  * // here the label is the first element of each input item
- * [...partitionSync(["a", "b"], { key: (x) => x[0] }, src)]
+ * console.log(
+ *   [...partitionSync(["a", "b"], { key: (x) => x[0] }, src)]
+ * );
  * // [ { a: ["a", 2], b: ["b", 10] },
  * //   { b: ["b", 11], a: ["a", 3] } ]
  * ```
@@ -91,18 +93,25 @@ export interface PartitionSyncOpts<T> {
  * above example:
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/partition-sync-2.ts
  * import { partitionSync } from "@thi.ng/transducers";
  *
+ * const src = [
+ *   ["a", 1], ["a", 2], ["d", 100], ["b", 10],
+ *   ["b", 11], ["c", 0], ["a", 3]
+ * ];
+ *
  * // passing `false` to disable tuple reset
- * [...partitionSync(
+ * const res = [...partitionSync(
  *   ["a", "b"],
  *   {
  *     key: (x) => x[0],
  *     reset: false
  *   },
  *   src
- * )]
+ * )];
+ *
+ * console.log(res);
  * // [ { a: ["a", 2], b: ["b", 10] },
  * //   { a: ["a", 2], b: ["b", 11] },
  * //   { a: ["a", 3], b: ["b", 11] } ]

package/partition-sync.js

@@ -36,7 +36,7 @@ function partitionSync(...args) {
           if (requiredKeys.has(k)) {
             curr[k] = x;
             currKeys.add(k);
-            if (mergeOnly || requiredInputs(requiredKeys, currKeys)) {
+            if (mergeOnly || __requiredInputs(requiredKeys, currKeys)) {
               acc = reduce(acc, curr);
               first = false;
               if (reset) {
@@ -55,7 +55,7 @@ function partitionSync(...args) {
         init,
         (acc) => {
           if (all && currKeys.size > 0) {
-            acc = reduce(acc, collect(cache, currKeys));
+            acc = reduce(acc, __collect(cache, currKeys));
             cache.clear();
             currKeys.clear();
           }
@@ -73,8 +73,8 @@ function partitionSync(...args) {
             );
             slot.push(x);
             currKeys.add(k);
-            while (requiredInputs(requiredKeys, currKeys)) {
-              acc = reduce(acc, collect(cache, currKeys));
+            while (__requiredInputs(requiredKeys, currKeys)) {
+              acc = reduce(acc, __collect(cache, currKeys));
               first = false;
               if (isReduced(acc)) break;
             }
@@ -104,14 +104,14 @@ function partitionSync(...args) {
   };
   return xform;
 }
-const requiredInputs = (required, curr) => {
+const __requiredInputs = (required, curr) => {
   if (curr.size < required.size) return false;
   for (let id of required) {
     if (!curr.has(id)) return false;
   }
   return true;
 };
-const collect = (cache, currKeys) => {
+const __collect = (cache, currKeys) => {
   const curr = {};
   for (let id of currKeys) {
     const slot = cache.get(id);

package/partition-time.d.ts

@@ -8,14 +8,16 @@ import type { Transducer } from "./api.js";
  * Only to be used in async contexts, NOT with {@link transduce} directly.
  *
  * Also see:
+ * - [`thi.ng/transducers-async`](https://thi.ng/transducers-async).
  * - [`thi.ng/rstream`](https://thi.ng/rstream)
- * - [`thi.ng/csp`](https://thi.ng/csp).
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/partition-time.ts
  * import { fromInterval, trace } from "@thi.ng/rstream";
+ * import { partitionTime } from "@thi.ng/transducers";
  *
- * // stream emits
+ * // stream emits counter value every 250ms
+ * // callect & partition into tuples every 1000ms
  * fromInterval(250)
  *   .transform(partitionTime(1000))
  *   .subscribe(trace())

package/partition-when.d.ts

@@ -6,10 +6,12 @@ import type { Transducer } from "./api.js";
  * happens yields chunk of buffered values.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/partition-when.ts
  * import { partitionWhen } from "@thi.ng/transducers";
  *
- * [...partitionWhen((x) => !!x, [0, 1, 0, 0, 1, 1, 0, 1])]
+ * console.log(
+ *   [...partitionWhen((x) => !!x, [0, 1, 0, 0, 1, 1, 0, 1])]
+ * );
  * // [ [ 0 ], [ 1, 0, 0 ], [ 1 ], [ 1, 0 ], [ 1 ] ]
  * ```
  *

package/partition.d.ts

@@ -7,16 +7,22 @@ import type { Transducer } from "./api.js";
  * be incomplete / partially filled only.
  *
  * @example
- * ```ts
- * import { partition } from "@thi.ng/transducers";
+ * ```ts tangle:../export/partition.ts
+ * import { partition, range } from "@thi.ng/transducers";
  *
- * [...partition(3, range(10))]
+ * console.log(
+ *   [...partition(3, range(10))]
+ * );
  * // [ [ 0, 1, 2 ], [ 3, 4, 5 ], [ 6, 7, 8 ] ]
  *
- * [...partition(3, true, range(10))]
+ * console.log(
+ *   [...partition(3, true, range(10))]
+ * );
  * // [ [ 0, 1, 2 ], [ 3, 4, 5 ], [ 6, 7, 8 ], [ 9 ] ]
  *
- * [...partition(3, 1, range(10))]
+ * console.log(
+ *   [...partition(3, 1, range(10))]
+ * );
  * // [ [ 0, 1, 2 ],
  * //   [ 1, 2, 3 ],
  * //   [ 2, 3, 4 ],

package/peek.d.ts

@@ -1,14 +1,16 @@
 import type { Transducer } from "./api.js";
 /**
  * Transducer version of
- * [`peek()`](https://docs.thi.ng/umbrella/api/functions/peek.html), i.e.
+ * [`peek()`](https://docs.thi.ng/umbrella/arrays/functions/peek.html), i.e.
  * extracts the last item of an array.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/peek.ts
  * import { peek } from "@thi.ng/transducers";
  *
- * [...peek([ [1, 2, 3], [4, 5] ])]
+ * console.log(
+ *   [...peek([ [1, 2, 3], [4, 5] ])]
+ * );
  * // [ 3, 5 ]
  * ```
  */

package/permutations.d.ts

@@ -6,17 +6,23 @@
  * empty the iterator yields no values.
  *
  * @example
- * ```ts
- * import { permutations } from "@thi.ng/transducers";
+ * ```ts tangle:../export/permutations.ts
+ * import { map, permutations, range } from "@thi.ng/transducers";
  *
- * [...permutations("ab", range(3))]
+ * console.log(
+ *   [...permutations("ab", range(3))]
+ * );
  * // [ ['a', 0], ['a', 1], ['a', 2],
  * //   ['b', 0], ['b', 1], ['b', 2] ]
  *
- * [...map((x: any[]) => x.join(""), permutations("ab", "-", range(3)))]
+ * console.log(
+ *   [...map((x: any[]) => x.join(""), permutations("ab", "-", range(3)))]
+ * );
  * // ['a-0', 'a-1', 'a-2', 'b-0', 'b-1', 'b-2']
  *
- * [...permutations([], "", range(0))]
+ * console.log(
+ *   [...permutations([], "", range(0))]
+ * );
  * // []
  * ```
  *
@@ -37,18 +43,24 @@ export declare function permutations(...src: Iterable<any>[]): IterableIterator<
  * values for each dimension.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/permutations-n.ts
  * import { permutationsN } from "@thi.ng/transducers";
  *
- * [...permutationsN(2)]
+ * console.log(
+ *   [...permutationsN(2)]
+ * );
  * // [ [0, 0], [0, 1], [1, 0], [1, 1] ]
  *
- * [...permutationsN(2, 3)]
+ * console.log(
+ *   [...permutationsN(2, 3)]
+ * );
  * // [ [0, 0], [0, 1], [0, 2],
  * //   [1, 0], [1, 1], [1, 2],
  * //   [2, 0], [2, 1], [2, 2] ]
  *
- * [...permutationsN(2, 2, [10, 20])]
+ * console.log(
+ *   [...permutationsN(2, 2, [10, 20])]
+ * );
  * // [ [ 10, 20 ], [ 10, 21 ], [ 11, 20 ], [ 11, 21 ] ]
  * ```
  *

package/pluck.d.ts

@@ -4,10 +4,12 @@ import type { Transducer } from "./api.js";
  * sequence of these values.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/pluck.ts
  * import { pluck } from "@thi.ng/transducers";
  *
- * [...pluck("id", [{id: 1}, {id: 2}, {}])]
+ * console.log(
+ *   [...pluck("id", [{id: 1}, {id: 2}, {}])]
+ * );
  * // [ 1, 2, undefined ]
  * ```
  *

package/push-sort.d.ts

@@ -8,5 +8,5 @@ import type { Reducer } from "./api.js";
  * @param cmp -
  */
 export declare function pushSort<T>(cmp?: Comparator<T>): Reducer<T, T[]>;
-export declare function pushSort<T>(cmp: Maybe<Comparator<T>>, xs: Iterable<T>): T[];
+export declare function pushSort<T>(cmp: Maybe<Comparator<T>>, src: Iterable<T>): T[];
 //# sourceMappingURL=push-sort.d.ts.map

package/push-sort.js

@@ -1,6 +1,6 @@
 import { compare } from "@thi.ng/compare/compare";
-function pushSort(cmp = compare, xs) {
-  return xs ? [...xs].sort(cmp) : [
+function pushSort(cmp = compare, src) {
+  return src ? [...src].sort(cmp) : [
     () => [],
     (acc) => acc.sort(cmp),
     (acc, x) => (acc.push(x), acc)

package/push.d.ts

@@ -1,4 +1,7 @@
 import type { Reducer } from "./api.js";
+/**
+ * Reducer which collects inputs into a new array.
+ */
 export declare function push<T>(): Reducer<T, T[]>;
-export declare function push<T>(xs: Iterable<T>): T[];
+export declare function push<T>(src: Iterable<T>): T[];
 //# sourceMappingURL=push.d.ts.map

package/push.js

@@ -1,6 +1,6 @@
 import { reducer } from "./reduce.js";
-function push(xs) {
-  return xs ? [...xs] : reducer(
+function push(src) {
+  return src ? [...src] : reducer(
     () => [],
     (acc, x) => (acc.push(x), acc)
   );

package/range-nd.d.ts

@@ -7,19 +7,27 @@ import type { ArrayLikeIterable } from "@thi.ng/api";
  * negative values.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/range-nd.ts
  * import { rangeNd } from "@thi.ng/transducers";
  *
- * [...rangeNd([2])]
+ * console.log(
+ *   [...rangeNd([2])]
+ * );
  * // [ [ 0 ], [ 1 ] ]
  *
- * [...rangeNd([2, -2])]
+ * console.log(
+ *   [...rangeNd([2, -2])]
+ * );
  * // [ [ 0, 0 ], [ 0, -1 ], [ 1, 0 ], [ 1, -1 ] ]
  *
- * [...rangeNd([-1,2], [1,3])]
+ * console.log(
+ *   [...rangeNd([-1,2], [1,3])]
+ * );
  * // [ [ -1, 2 ], [ -1, 3 ], [ 0, 2 ], [ 0, 3 ] ]
  *
- * [...rangeNd([2, 2, 2])]
+ * console.log(
+ *   [...rangeNd([2, 2, 2])]
+ * );
  * // [
  * //   [ 0, 0, 0 ],
  * //   [ 0, 0, 1 ],