@thi.ng/bench 3.4.33 → 3.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-09T09:18:17Z
+- **Last updated**: 2024-03-13T14:04:31Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,16 @@ 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.
 
+## [3.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/bench@3.5.0) (2024-03-13)
+
+#### 🚀 Features
+
+- add frequency stat (i.e. ops/sec) ([0e6576a](https://github.com/thi-ng/umbrella/commit/0e6576a))
+  - add `BenchmarkOpts.extSize`
+  - update `benchmark()`
+  - update all formatters
+  - add `setPrecision()` to adjust float formatter
+
 ### [3.4.28](https://github.com/thi-ng/umbrella/tree/@thi.ng/bench@3.4.28) (2024-02-22)
 
 #### ♻️ Refactoring

package/README.md

@@ -78,7 +78,7 @@ For Node.js REPL:
 const bench = await import("@thi.ng/bench");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.07 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.13 KB
 
 ## Dependencies
 
@@ -107,35 +107,45 @@ directory are using this package:
 
 ### Basic usage
 
-```ts
-import { timed, bench, benchmark } from "@thi.ng/bench";
-
-// test functions
-const fib = (n) => n > 2 ? fib(n - 1) + fib(n - 2) : n > 0 ? 1 : 0;
+```ts id:test-functions
+// functions to benchmark...
+const fib = (n: number) =>
+    n > 2
+        ? fib(n - 1) + fib(n - 2)
+        : n > 0
+            ? 1
+            : 0;
 
-const fib2 = (n) => {
+const fib2 = (n: number) => {
     const res = [0, 1];
     for(let i = 2; i <= n; i++) {
         res[i] = res[i - 1] + res[i - 2];
     }
     return res[n];
 };
+```
+
+```ts tangle:export/readme1.ts
+import { timed, bench } from "@thi.ng/bench";
+
+<<test-functions>>
 
 // measure single execution time
-timed(() => fib(40));
-// 714ms
+console.log(timed(() => fib(40)));
+// 318.86ms
 // 102334155
-timed(() => fib2(40));
-// 0ms
+
+console.log(timed(() => fib2(40)));
+// 0.05ms
 // 102334155
 
 // measure 1mil iterations (default)
-bench(() => fib(10), 1e6);
-// 395ms
+console.log(bench(() => fib(10), 1e6));
+// 157.41ms
 // 55
 
-bench(() => fib2(10), 1e6);
-// 53ms
+console.log(bench(() => fib2(10), 1e6));
+// 95.97ms
 // 55
 ```
 
@@ -153,32 +163,34 @@ for configuration options.
 Also see the [formatting](#output-formatting) section below for other output
 options. This example uses the default format...
 
-```ts
+```ts tangle:export/readme2.ts
 import { benchmark } from "@thi.ng/bench";
 
-// fib() function is from previous example above...
+<<test-functions>>
 
 benchmark(() => fib(40), { title: "fib", iter: 10, warmup: 5 });
 // benchmarking: fib
-//         warmup... 3707.17ms (5 runs)
-//         executing...
-//         total: 7333.72ms, runs: 10
-//         mean: 733.37ms, median: 733.79ms, range: [728.58..743.43]
-//         q1: 730.98ms, q3: 735.03ms
-//         sd: 0.54%
+//         warmup... 1480.79ms (5 runs)
+//         total: 2917.41ms, runs: 10 (@ 1 calls/iter)
+//         freq: 3.43 ops/sec
+//         mean: 291.74ms, median: 291.67ms, range: [291.51..292.58]
+//         q1: 291.55ms, q3: 291.79ms
+//         sd: 0.10%
 
 // also returns results:
 // {
 //   title: "fib",
 //   iter: 10,
-//   total: 7333.72402,
-//   mean: 733.372402,
-//   median: 733.794194,
-//   min: 728.5808,
-//   max: 743.432538,
-//   q1: 730.980115,
-//   q3: 735.025314,
-//   sd: 0.542200865574415
+//   size: 1,
+//   total: 2917.4060010000003,
+//   freq: 3.4277025537660157,
+//   mean: 291.74060010000005,
+//   median: 291.668125,
+//   min: 291.50624999999997,
+//   max: 292.581834,
+//   q1: 291.55116699999996,
+//   q3: 291.788417,
+//   sd: 0.10295312107365955,
 // }
 ```
 
@@ -187,10 +199,10 @@ benchmark(() => fib(40), { title: "fib", iter: 10, warmup: 5 });
 Multiple benchmarks can be run sequentially as suite (also returns an array of
 all results):
 
-```ts
+```ts tangle:export/readme3.ts
 import { suite, FORMAT_MD } from "@thi.ng/bench";
 
-// fib2() function defined in earlier example above...
+<<test-functions>>
 
 suite(
     [
@@ -202,22 +214,22 @@ suite(
     { iter: 10, size: 100000, warmup: 5, format: FORMAT_MD }
 )
 
-// |                   Title|    Iter|    Size|       Total|    Mean|  Median|     Min|     Max|      Q1|      Q3|     SD%|
-// |------------------------|-------:|-------:|-----------:|-------:|-------:|-------:|-------:|-------:|-------:|-------:|
-// |                fib2(10)|      10|  100000|       54.34|    5.43|    5.15|    4.40|    8.14|    4.84|    6.67|   20.32|
-// |                fib2(20)|      10|  100000|      121.24|   12.12|   12.13|   11.73|   12.91|   11.93|   12.35|    2.61|
-// |                fib2(30)|      10|  100000|      152.98|   15.30|   14.51|   13.93|   20.77|   14.35|   16.35|   12.65|
-// |                fib2(40)|      10|  100000|      164.79|   16.48|   15.60|   15.01|   19.27|   15.42|   18.80|    9.34|
+// |                   Title|    Iter|    Size|       Total|   Frequency|    Mean|  Median|     Min|     Max|      Q1|      Q3|     SD%|
+// |------------------------|-------:|-------:|-----------:|-----------:|-------:|-------:|-------:|-------:|-------:|-------:|-------:|
+// |                fib2(10)|      10|  100000|       93.25| 10723774.45|    9.33|    9.25|    8.94|   10.27|    9.03|    9.46|    4.15|
+// |                fib2(20)|      10|  100000|      110.73|  9030823.33|   11.07|   11.02|   10.91|   11.56|   10.92|   11.10|    1.76|
+// |                fib2(30)|      10|  100000|      175.10|  5711056.26|   17.51|   17.58|   17.03|   17.65|   17.50|   17.60|    0.96|
+// |                fib2(40)|      10|  100000|      200.01|  4999765.64|   20.00|   19.71|   19.34|   21.78|   19.55|   19.91|    3.90|
 ```
 
 Same table as actual Markdown:
 
-|                   Title|    Iter|    Size|       Total|    Mean|  Median|     Min|     Max|      Q1|      Q3|     SD%|
-|------------------------|-------:|-------:|-----------:|-------:|-------:|-------:|-------:|-------:|-------:|-------:|
-|                fib2(10)|      10|  100000|       54.34|    5.43|    5.15|    4.40|    8.14|    4.84|    6.67|   20.32|
-|                fib2(20)|      10|  100000|      121.24|   12.12|   12.13|   11.73|   12.91|   11.93|   12.35|    2.61|
-|                fib2(30)|      10|  100000|      152.98|   15.30|   14.51|   13.93|   20.77|   14.35|   16.35|   12.65|
-|                fib2(40)|      10|  100000|      164.79|   16.48|   15.60|   15.01|   19.27|   15.42|   18.80|    9.34|
+|                   Title|    Iter|    Size|       Total|   Frequency|    Mean|  Median|     Min|     Max|      Q1|      Q3|     SD%|
+|------------------------|-------:|-------:|-----------:|-----------:|-------:|-------:|-------:|-------:|-------:|-------:|-------:|
+|                fib2(10)|      10|  100000|       93.25| 10723774.45|    9.33|    9.25|    8.94|   10.27|    9.03|    9.46|    4.15|
+|                fib2(20)|      10|  100000|      110.73|  9030823.33|   11.07|   11.02|   10.91|   11.56|   10.92|   11.10|    1.76|
+|                fib2(30)|      10|  100000|      175.10|  5711056.26|   17.51|   17.58|   17.03|   17.65|   17.50|   17.60|    0.96|
+|                fib2(40)|      10|  100000|      200.01|  4999765.64|   20.00|   19.71|   19.34|   21.78|   19.55|   19.91|    3.90|
 
 ### Output formatting
 

package/api.d.ts

@@ -19,6 +19,18 @@ export interface BenchmarkOpts {
      * @defaultValue 1
      */
     size: number;
+    /**
+     * Externally defined batch size, similar to {@link BenchmarkOpts.size},
+     * i.e. calls per iteration. However, this option is ONLY used for computing
+     * {@link BenchmarkResult.freq} and has no impact on actual benchmark
+     * execution.
+     *
+     * @remarks
+     * This option is only to be used if the benchmarked function uses internal
+     * looping to execute multiple iterations. E.g. if internally executing N
+     * iterations, `extSize` should be set to that number.
+     */
+    extSize: number;
     /**
      * Number of warmup iterations (not included in results).
      *
@@ -56,28 +68,38 @@ export interface BenchmarkResult {
      */
     total: number;
     /**
-     * Mean execution time (in ms)
+     * Frequency aka number of ops per second
+     */
+    freq: number;
+    /**
+     * Mean execution time (in ms) per iteration (batch of
+     * {@link BenchmarkResult.size} calls)
      */
     mean: number;
     /**
-     * Median execution time (in ms)
+     * Median execution time (in ms) per iteration (batch of
+     * {@link BenchmarkResult.size} calls)
      */
     median: number;
     /**
-     * Min execution time (in ms)
+     * Min execution time (in ms) per iteration (batch of
+     * {@link BenchmarkResult.size} calls)
      */
     min: number;
     /**
-     * Max execution time (in ms)
+     * Max execution time (in ms) per iteration (batch of
+     * {@link BenchmarkResult.size} calls)
      */
     max: number;
     /**
-     * First quartile execution time (in ms). I.e. 25% of all runs were
+     * First quartile execution time (in ms) per iteration (batch of
+     * {@link BenchmarkResult.size} calls). I.e. 25% of all runs were
      * faster/equal to this measurement.
      */
     q1: number;
     /**
-     * Third quartile execution time (in ms). I.e. 25% of all runs were
+     * Third quartile execution time (in ms) per iteration (batch of
+     * {@link BenchmarkResult.size} calls). I.e. 25% of all runs were
      * equal/slower than this measurement.
      */
     q3: number;
@@ -131,6 +153,7 @@ export interface Benchmark {
      */
     opts?: Partial<OptsWithoutTitle>;
 }
+export declare const setPrecision: (prec: number) => number;
 export declare const FLOAT: (x: number) => string;
 export declare const EMPTY: () => string;
 //# sourceMappingURL=api.d.ts.map

package/api.js

@@ -1,6 +1,9 @@
-const FLOAT = (x) => x.toFixed(2);
+let PRECISION = 2;
+const setPrecision = (prec) => PRECISION = prec;
+const FLOAT = (x) => x.toFixed(PRECISION);
 const EMPTY = () => "";
 export {
   EMPTY,
-  FLOAT
+  FLOAT,
+  setPrecision
 };

package/benchmark.js

@@ -4,13 +4,14 @@ const DEFAULT_OPTS = {
   title: "benchmark",
   iter: 1e3,
   size: 1,
+  extSize: 1,
   warmup: 10,
   output: true,
   format: FORMAT_DEFAULT
 };
 const benchmark = (fn, opts) => {
   const _opts = { ...DEFAULT_OPTS, ...opts };
-  const { iter, size, warmup, output, format } = _opts;
+  let { iter, size, extSize, warmup, output, format } = _opts;
   output && outputString(format.start(_opts));
   const t = benchResult(fn, warmup * size)[1];
   output && outputString(format.warmup(t, _opts));
@@ -20,12 +21,13 @@ const benchmark = (fn, opts) => {
   }
   samples.sort((a, b) => a - b);
   const total = samples.reduce((acc, x) => acc + x, 0);
+  const freq = iter * size * extSize * 1e3 / total;
   const mean = total / iter;
   const median = samples[iter >> 1];
   const min = samples[0];
   const max = samples[iter - 1];
-  const q1 = samples[Math.ceil(iter * 0.25)];
-  const q3 = samples[Math.ceil(iter * 0.75)];
+  const q1 = samples[Math.floor(iter * 0.25)];
+  const q3 = samples[Math.floor(iter * 0.75)];
   const sd = Math.sqrt(
     samples.reduce((acc, x) => acc + (mean - x) ** 2, 0) / iter
   ) / mean * 100;
@@ -34,6 +36,7 @@ const benchmark = (fn, opts) => {
     iter,
     size,
     total,
+    freq,
     mean,
     median,
     min,

package/format/csv.js

@@ -1,10 +1,11 @@
 import { EMPTY, FLOAT } from "../api.js";
 const FORMAT_CSV = {
-  prefix: () => `Title,Iterations,Size,Total,Mean,Median,Min,Max,Q1,Q3,SD%`,
+  prefix: () => `Title,Iterations,Size,Total,Frequency,Mean,Median,Min,Max,Q1,Q3,SD%`,
   start: EMPTY,
   warmup: EMPTY,
   result: (res) => `"${res.title}",${res.iter},${res.size},${[
     res.total,
+    res.freq,
     res.mean,
     res.median,
     res.min,

package/format/default.js

@@ -3,9 +3,10 @@ const FORMAT_DEFAULT = {
   prefix: EMPTY,
   start: ({ title }) => `benchmarking: ${title}`,
   warmup: (t, { warmup }) => `	warmup... ${FLOAT(t)}ms (${warmup} runs)`,
-  result: ({ iter, size, total, mean, median, min, max, q1, q3, sd }) => (
+  result: ({ iter, size, total, freq, mean, median, min, max, q1, q3, sd }) => (
     // prettier-ignore
     `	total: ${FLOAT(total)}ms, runs: ${iter} (@ ${size} calls/iter)
+	freq: ${FLOAT(freq)} ops/sec
 	mean: ${FLOAT(mean)}ms, median: ${FLOAT(median)}ms, range: [${FLOAT(min)}..${FLOAT(max)}]
 	q1: ${FLOAT(q1)}ms, q3: ${FLOAT(q3)}ms
 	sd: ${FLOAT(sd)}%`

package/format/markdown.js

@@ -4,7 +4,7 @@ const pad = (w) => {
   const column = $n(w, " ");
   return (x) => {
     const s = typeof x === "number" ? FLOAT(x) : x;
-    return s.length < w ? column.substr(0, w - s.length) + s : s.substr(0, w);
+    return s.length < w ? column.substring(0, w - s.length) + s : s.substring(0, w);
   };
 };
 const c24 = pad(24);
@@ -13,8 +13,8 @@ const c8 = pad(8);
 const d24 = $n(24);
 const d12 = $n(11) + ":";
 const d8 = $n(7) + ":";
-const COLUMNS = [c24, c8, c8, c12, c8, c8, c8, c8, c8, c8, c8];
-const DASHES = [d24, d8, d8, d12, d8, d8, d8, d8, d8, d8, d8];
+const COLUMNS = [c24, c8, c8, c12, c12, c8, c8, c8, c8, c8, c8, c8];
+const DASHES = [d24, d8, d8, d12, d12, d8, d8, d8, d8, d8, d8, d8];
 const row = (cols) => `|${cols.map((x, i) => COLUMNS[i](x)).join("|")}|`;
 const FORMAT_MD = {
   prefix: () => row([
@@ -22,6 +22,7 @@ const FORMAT_MD = {
     "Iter",
     "Size",
     "Total",
+    "Frequency",
     "Mean",
     "Median",
     "Min",
@@ -38,6 +39,7 @@ const FORMAT_MD = {
     "" + res.iter,
     "" + res.size,
     res.total,
+    res.freq,
     res.mean,
     res.median,
     res.min,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/bench",
-  "version": "3.4.33",
+  "version": "3.5.0",
   "description": "Benchmarking & profiling utilities w/ various statistics & formatters (CSV, JSON, Markdown etc.)",
   "type": "module",
   "module": "./index.js",
@@ -36,17 +36,17 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.29"
+    "@thi.ng/api": "^8.9.30"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.40.1",
-    "@thi.ng/testament": "^0.4.22",
-    "@types/node": "^20.11.17",
-    "esbuild": "^0.20.0",
+    "@microsoft/api-extractor": "^7.42.3",
+    "@thi.ng/testament": "^0.4.23",
+    "@types/node": "^20.11.26",
+    "esbuild": "^0.20.1",
     "rimraf": "^5.0.5",
     "tools": "^0.0.1",
-    "typedoc": "^0.25.7",
-    "typescript": "^5.3.3"
+    "typedoc": "^0.25.12",
+    "typescript": "^5.4.2"
   },
   "keywords": [
     "benchmark",
@@ -120,5 +120,5 @@
     ],
     "year": 2018
   },
-  "gitHead": "69100942474942f7446ac645d59d91e7dfc352f9\n"
+  "gitHead": "7f3fcbd6c0462b0ce45afa141fe163d1f297fd51\n"
 }

package/profiler.d.ts

@@ -1,6 +1,6 @@
 import type { FnAny, IDeref, IEnable, IObjectOf, IReset } from "@thi.ng/api";
 import type { Timestamp } from "./api.js";
-interface Profile {
+export interface Profile {
     t0: Timestamp[];
     total: Timestamp;
     calls: number;
@@ -103,26 +103,26 @@ export declare class Profiler implements IDeref<IObjectOf<ProfileResult>>, IEnab
      * no-op.
      *
      * * @example
-     * ```ts
+     * ```ts tangle:../export/profiler.ts
      * import { Profiler } from "@thi.ng/bench";
      *
      * const profiler = new Profiler();
      *
      * // recursive function
-     * const countdown = (n, acc = []) => {
+     * const countdown = (n: number, acc: number[] = []) => {
      *   profiler.start("countdown");
      *   if (n > 0) countdown(n - 1, (acc.push(n),acc));
      *   profiler.end("countdown");
      *   return acc;
      * }
      *
-     * countdown(10);
+     * console.log(countdown(10));
      * // [ 10, 9, 8, 7, 6, 5, 4, 3, 2, 1 ]
      *
-     * countdown(5);
+     * console.log(countdown(5));
      * // [ 5, 4, 3, 2, 1 ]
      *
-     * profiler.deref()
+     * console.log(profiler.deref());
      * // {
      * //   countdown: {
      * //     id: 'countdown',
@@ -171,7 +171,7 @@ export declare class Profiler implements IDeref<IObjectOf<ProfileResult>>, IEnab
      * `fn`.
      *
      * @example
-     * ```ts
+     * ```ts tangle:../export/profiler-wrap.ts
      * import { Profiler } from "@thi.ng/bench";
      *
      * const profiler = new Profiler();
@@ -181,10 +181,10 @@ export declare class Profiler implements IDeref<IObjectOf<ProfileResult>>, IEnab
      *   (vec: number[]) => vec.reduce((acc, x) => acc + x, 0)
      * );
      *
-     * sum([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+     * console.log(sum([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]));
      * // 55
      *
-     * profiler.deref()
+     * console.log(profiler.deref());
      * // {
      * //   sum: {
      * //     id: 'sum',
@@ -230,5 +230,4 @@ export declare class Profiler implements IDeref<IObjectOf<ProfileResult>>, IEnab
         maxDepth: number;
     };
 }
-export {};
 //# sourceMappingURL=profiler.d.ts.map

package/profiler.js

@@ -94,26 +94,26 @@ class Profiler {
    * no-op.
    *
    * * @example
-   * ```ts
+   * ```ts tangle:../export/profiler.ts
    * import { Profiler } from "@thi.ng/bench";
    *
    * const profiler = new Profiler();
    *
    * // recursive function
-   * const countdown = (n, acc = []) => {
+   * const countdown = (n: number, acc: number[] = []) => {
    *   profiler.start("countdown");
    *   if (n > 0) countdown(n - 1, (acc.push(n),acc));
    *   profiler.end("countdown");
    *   return acc;
    * }
    *
-   * countdown(10);
+   * console.log(countdown(10));
    * // [ 10, 9, 8, 7, 6, 5, 4, 3, 2, 1 ]
    *
-   * countdown(5);
+   * console.log(countdown(5));
    * // [ 5, 4, 3, 2, 1 ]
    *
-   * profiler.deref()
+   * console.log(profiler.deref());
    * // {
    * //   countdown: {
    * //     id: 'countdown',
@@ -197,7 +197,7 @@ class Profiler {
    * `fn`.
    *
    * @example
-   * ```ts
+   * ```ts tangle:../export/profiler-wrap.ts
    * import { Profiler } from "@thi.ng/bench";
    *
    * const profiler = new Profiler();
@@ -207,10 +207,10 @@ class Profiler {
    *   (vec: number[]) => vec.reduce((acc, x) => acc + x, 0)
    * );
    *
-   * sum([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+   * console.log(sum([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]));
    * // 55
    *
-   * profiler.deref()
+   * console.log(profiler.deref());
    * // {
    * //   sum: {
    * //     id: 'sum',