@thi.ng/transducers 9.2.26 → 9.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-04-16T11:11:14Z
+- **Last updated**: 2025-04-30T12:52:32Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,12 @@ 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.
 
+## [9.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/transducers@9.3.0) (2025-04-30)
+
+#### 🚀 Features
+
+- add `binned()` transducer & example ([6e8d9cd](https://github.com/thi-ng/umbrella/commit/6e8d9cd))
+
 ### [9.2.13](https://github.com/thi-ng/umbrella/tree/@thi.ng/transducers@9.2.13) (2025-01-14)
 
 #### ♻️ Refactoring

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 205 standalone projects, maintained as part
+> This is one of 206 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -150,7 +150,7 @@ For Node.js REPL:
 const tx = await import("@thi.ng/transducers");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 9.12 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 9.16 KB
 
 ## Dependencies
 
@@ -935,6 +935,7 @@ transduce(map((x) => x*10), push(), range(4))
 ```
 
 - [benchmark](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/benchmark.ts)
+- [binned](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/binned.ts)
 - [cat](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/cat.ts)
 - [converge](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/converge.ts)
 - [convolve2d](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/convolve.ts)

package/binned.d.ts

@@ -0,0 +1,70 @@
+import type { Transducer } from "./api.js";
+/**
+ * Config options for {@link binned} transducer
+ */
+export interface BinnedOpts {
+    /**
+     * Rounding precision. Values inside the closed `[min,max]` interval will be
+     * rounded to multiples of given `precision.
+     *
+     * @defaultValue 1
+     */
+    prec: number;
+    /**
+     * Lower bounds of interval.
+     *
+     * @defaultValue -♾️
+     */
+    min: number;
+    /**
+     * Upper bounds of interval.
+     *
+     * @defaultValue +♾️
+     */
+    max: number;
+}
+/**
+ * Transducer to apply binning and interval clipping for numeric values based on
+ * provided options. Values in the closed `[min,max]` interval will be rounded
+ * to multiples of given `prec`ision (e.g. as a preparation for
+ * {@link frequencies} et al). Values outside the interval will be ignored.
+ *
+ * @example
+ * ```ts tangle:../export/binned.ts
+ * import { binned, frequencies, pluck, repeatedly, transduce } from "@thi.ng/transducers";
+ * import { normal } from "@thi.ng/random";
+ * import { barChartVStr } from "@thi.ng/text-canvas";
+ *
+ * // compute histogram of 1 million gaussian random samples (aka normal distribution)
+ * // use binned values and discard those outside configured interval
+ * const hist = transduce(
+ *   binned({ prec: 0.1, min: -3, max: 3 }),
+ *   frequencies(),
+ *   repeatedly(normal(), 1e6)
+ * );
+ * // Map(61) { -3 => 223, ... 0 => 40212, ... 3 => 245 }
+ *
+ * // sort by key (position)
+ * const sorted = [...hist].sort((a,b) => a[0] - b[0]);
+ *
+ * // draw as ANSI art diagram
+ * console.log(barChartVStr(10, pluck(1, sorted)));
+ *
+ * //                          ▁▄▇▇█▆▆▄
+ * //                        ▂▇█████████▆▂
+ * //                      ▁▆█████████████▆▁
+ * //                     ▅█████████████████▅
+ * //                   ▄█████████████████████▃
+ * //                 ▂▇███████████████████████▇▂
+ * //               ▁▆███████████████████████████▆▁
+ * //             ▂▆███████████████████████████████▇▃
+ * //         ▁▂▅█████████████████████████████████████▅▃
+ * // ▁▁▂▃▄▅▆▇███████████████████████████████████████████▇▆▅▃▃▂▁▁
+ * ```
+ *
+ * @param opts
+ */
+export declare function binned(opts?: Partial<BinnedOpts>): Transducer<number, number>;
+export declare function binned(src: Iterable<number>): IterableIterator<number>;
+export declare function binned(opts: Partial<BinnedOpts>, src: Iterable<number>): IterableIterator<number>;
+//# sourceMappingURL=binned.d.ts.map

package/binned.js

@@ -0,0 +1,20 @@
+import { roundTo } from "@thi.ng/math/prec";
+import { compR } from "./compr.js";
+import { __iter } from "./iterator.js";
+function binned(...args) {
+  return __iter(binned, args) || ((rfn) => {
+    const r = rfn[2];
+    const {
+      prec = 1,
+      min = -Infinity,
+      max = Infinity
+    } = args[0] || {};
+    return compR(
+      rfn,
+      (acc, x) => x < min || x > max ? acc : r(acc, roundTo(x, prec))
+    );
+  });
+}
+export {
+  binned
+};

package/index.d.ts

@@ -50,6 +50,7 @@ export * from "./sorted-frequencies.js";
 export * from "./str.js";
 export * from "./sub.js";
 export * from "./benchmark.js";
+export * from "./binned.js";
 export * from "./cat.js";
 export * from "./converge.js";
 export * from "./convolve.js";

package/index.js

@@ -50,6 +50,7 @@ export * from "./sorted-frequencies.js";
 export * from "./str.js";
 export * from "./sub.js";
 export * from "./benchmark.js";
+export * from "./binned.js";
 export * from "./cat.js";
 export * from "./converge.js";
 export * from "./convolve.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/transducers",
-  "version": "9.2.26",
+  "version": "9.3.0",
   "description": "Collection of ~170 lightweight, composable transducers, reducers, generators, iterators for functional data transformations",
   "type": "module",
   "module": "./index.js",
@@ -43,19 +43,19 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.26",
-    "@thi.ng/arrays": "^2.10.23",
-    "@thi.ng/checks": "^3.7.6",
-    "@thi.ng/compare": "^2.4.18",
-    "@thi.ng/compose": "^3.0.29",
-    "@thi.ng/errors": "^2.5.32",
-    "@thi.ng/math": "^5.11.26",
-    "@thi.ng/random": "^4.1.17",
-    "@thi.ng/timestamp": "^1.1.11"
+    "@thi.ng/api": "^8.11.27",
+    "@thi.ng/arrays": "^2.11.0",
+    "@thi.ng/checks": "^3.7.7",
+    "@thi.ng/compare": "^2.4.19",
+    "@thi.ng/compose": "^3.0.30",
+    "@thi.ng/errors": "^2.5.33",
+    "@thi.ng/math": "^5.11.27",
+    "@thi.ng/random": "^4.1.18",
+    "@thi.ng/timestamp": "^1.1.12"
   },
   "devDependencies": {
-    "esbuild": "^0.25.2",
-    "typedoc": "^0.28.2",
+    "esbuild": "^0.25.3",
+    "typedoc": "^0.28.3",
     "typescript": "^5.8.3"
   },
   "keywords": [
@@ -135,6 +135,9 @@
     "./benchmark": {
       "default": "./benchmark.js"
     },
+    "./binned": {
+      "default": "./binned.js"
+    },
     "./cat": {
       "default": "./cat.js"
     },
@@ -603,5 +606,5 @@
     ],
     "year": 2016
   },
-  "gitHead": "c464b6948f92cba90c2ea75b59203dad894fb450\n"
+  "gitHead": "4354686a6fb1f82c09ea48f92f87786191b231a0\n"
 }