@thi.ng/bench 3.6.53 → 3.7.0

package/README.md

@@ -34,7 +34,7 @@
 
 ## About
 
-Benchmarking & profiling utilities w/ various statistics & formatters (CSV, JSON, Markdown etc.).
+Async/sync benchmarking & profiling utilities with various statistics & formatters (CSV, JSON, Markdown etc.).
 
 > [!IMPORTANT]
 > As of 2024-12-27, all timestamp-related functions have been extracted/migrated
@@ -78,7 +78,7 @@ For Node.js REPL:
 const bench = await import("@thi.ng/bench");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.06 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.22 KB
 
 ## Dependencies
 
@@ -114,14 +114,14 @@ directory are using this package:
 
 ```ts id:test-functions
 // functions to benchmark...
-const fib = (n: number) =>
+const fib = (n: number): number =>
     n > 2
         ? fib(n - 1) + fib(n - 2)
         : n > 0
             ? 1
             : 0;
 
-const fib2 = (n: number) => {
+const fib2 = (n: number): number => {
     const res = [0, 1];
     for(let i = 2; i <= n; i++) {
         res[i] = res[i - 1] + res[i - 2];

package/api.d.ts

@@ -146,13 +146,16 @@ export interface Benchmark {
      * Benchmark function. Will be called `size` times per `iter`ation (see
      * {@link BenchmarkOpts}).
      */
-    fn: Fn0<void>;
+    fn: Fn0<any>;
     /**
      * Optional & partial benchmark specific option overrides (merged with opts
      * given to suite)
      */
     opts?: Partial<OptsWithoutTitle>;
 }
+export interface AsyncBenchmark extends Omit<Benchmark, "fn"> {
+    fn: Fn0<Promise<any>>;
+}
 export declare const setPrecision: (prec: number) => number;
 export declare const FLOAT: (x: number) => string;
 export declare const EMPTY: () => string;

package/bench.d.ts

@@ -8,6 +8,14 @@ import type { TimingResult } from "./api.js";
  * @param n - number of iterations
  */
 export declare const bench: <T>(fn: () => T, n?: number, prefix?: string) => T;
+/**
+ * Async version of {@link bench}.
+ *
+ * @param fn
+ * @param n
+ * @param prefix
+ */
+export declare const benchAsync: <T>(fn: () => Promise<T>, n?: number, prefix?: string) => Promise<T>;
 /**
  * Similar to {@link bench}, but produces no output and instead returns
  * tuple of `fn`'s last result and the grand total time measurement.
@@ -16,4 +24,11 @@ export declare const bench: <T>(fn: () => T, n?: number, prefix?: string) => T;
  * @param n - number of iterations
  */
 export declare const benchResult: <T>(fn: () => T, n?: number) => TimingResult<T>;
+/**
+ * Async version of {@link benchResult}.
+ *
+ * @param fn
+ * @param n
+ */
+export declare const benchResultAsync: <T>(fn: () => Promise<T>, n?: number) => Promise<TimingResult<T>>;
 //# sourceMappingURL=bench.d.ts.map

package/bench.js

@@ -1,4 +1,4 @@
-import { timed, timedResult } from "./timed.js";
+import { timed, timedAsync, timedResult, timedResultAsync } from "./timed.js";
 const bench = (fn, n = 1e6, prefix = "") => {
   let res;
   return timed(() => {
@@ -8,6 +8,15 @@ const bench = (fn, n = 1e6, prefix = "") => {
     return res;
   }, prefix);
 };
+const benchAsync = (fn, n = 1e6, prefix = "") => {
+  let res;
+  return timedAsync(async () => {
+    while (n-- > 0) {
+      res = await fn();
+    }
+    return res;
+  }, prefix);
+};
 const benchResult = (fn, n = 1e6) => {
   let res;
   return timedResult(() => {
@@ -17,7 +26,18 @@ const benchResult = (fn, n = 1e6) => {
     return res;
   });
 };
+const benchResultAsync = (fn, n = 1e6) => {
+  let res;
+  return timedResultAsync(async () => {
+    while (n-- > 0) {
+      res = await fn();
+    }
+    return res;
+  });
+};
 export {
   bench,
-  benchResult
+  benchAsync,
+  benchResult,
+  benchResultAsync
 };

package/benchmark.d.ts

@@ -1,6 +1,22 @@
 import type { BenchmarkOpts, BenchmarkResult } from "./api.js";
 export declare const DEFAULT_OPTS: BenchmarkOpts;
-export declare const benchmark: (fn: () => void, opts?: Partial<BenchmarkOpts>) => BenchmarkResult;
+export declare const benchmark: (fn: () => any, opts?: Partial<BenchmarkOpts>) => BenchmarkResult;
+/**
+ * Async version of {@link benchmark}.
+ *
+ * @param fn
+ * @param opts
+ */
+export declare const benchmarkAsync: (fn: () => Promise<any>, opts?: Partial<BenchmarkOpts>) => Promise<BenchmarkResult>;
+/**
+ * Helper for {@link benchmark}, {@link benchmarkAsync}. Takes an array of
+ * benchmark samples and computes result statistics using provided options. If
+ * `opts.output` is true, also outputs formatted result.
+ *
+ * @param samples
+ * @param opts
+ */
+export declare const benchmarkResult: (samples: number[], { iter, size, extSize, format, output, title }: BenchmarkOpts) => BenchmarkResult;
 /**
  * Only outputs non-empty strings to console.
  *

package/benchmark.js

@@ -1,4 +1,4 @@
-import { benchResult } from "./bench.js";
+import { benchResult, benchResultAsync } from "./bench.js";
 import { FORMAT_DEFAULT } from "./format/default.js";
 const DEFAULT_OPTS = {
   title: "benchmark",
@@ -10,15 +10,30 @@ const DEFAULT_OPTS = {
   format: FORMAT_DEFAULT
 };
 const benchmark = (fn, opts) => {
-  const _opts = { ...DEFAULT_OPTS, ...opts };
-  let { iter, size, extSize, warmup, output, format } = _opts;
-  output && outputString(format.start(_opts));
+  const $opts = { ...DEFAULT_OPTS, ...opts };
+  let { iter, size, warmup, output, format } = $opts;
+  output && outputString(format.start($opts));
   const t = benchResult(fn, warmup * size)[1];
-  output && outputString(format.warmup(t, _opts));
+  output && outputString(format.warmup(t, $opts));
   const samples = [];
   for (let i = iter; i-- > 0; ) {
     samples.push(benchResult(fn, size)[1]);
   }
+  return benchmarkResult(samples, $opts);
+};
+const benchmarkAsync = async (fn, opts) => {
+  const $opts = { ...DEFAULT_OPTS, ...opts };
+  let { iter, size, warmup, output, format } = $opts;
+  output && outputString(format.start($opts));
+  const t = (await benchResultAsync(fn, warmup * size))[1];
+  output && outputString(format.warmup(t, $opts));
+  const samples = [];
+  for (let i = iter; i-- > 0; ) {
+    samples.push((await benchResultAsync(fn, size))[1]);
+  }
+  return benchmarkResult(samples, $opts);
+};
+const benchmarkResult = (samples, { iter, size, extSize, format, output, title }) => {
   samples.sort((a, b) => a - b);
   const total = samples.reduce((acc, x) => acc + x, 0);
   const freq = iter * size * extSize * 1e3 / total;
@@ -32,7 +47,7 @@ const benchmark = (fn, opts) => {
     samples.reduce((acc, x) => acc + (mean - x) ** 2, 0) / iter
   ) / mean * 100;
   const res = {
-    title: _opts.title,
+    title,
     iter,
     size,
     total,
@@ -52,5 +67,7 @@ const outputString = (str) => str !== "" && console.log(str);
 export {
   DEFAULT_OPTS,
   benchmark,
+  benchmarkAsync,
+  benchmarkResult,
   outputString
 };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@thi.ng/bench",
-	"version": "3.6.53",
-	"description": "Benchmarking & profiling utilities w/ various statistics & formatters (CSV, JSON, Markdown etc.)",
+	"version": "3.7.0",
+	"description": "Async/sync benchmarking & profiling utilities with various statistics & formatters (CSV, JSON, Markdown etc.)",
 	"type": "module",
 	"module": "./index.js",
 	"typings": "./index.d.ts",
@@ -41,17 +41,18 @@
 		"tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
 	},
 	"dependencies": {
-		"@thi.ng/api": "^8.12.26",
-		"@thi.ng/timestamp": "^1.1.45"
+		"@thi.ng/api": "^8.12.27",
+		"@thi.ng/timestamp": "^1.1.46"
 	},
 	"devDependencies": {
-		"@types/node": "^25.6.2",
-		"esbuild": "^0.28.0",
+		"@types/node": "^25.9.4",
+		"esbuild": "^0.28.1",
 		"tools": "workspace:^",
 		"typedoc": "^0.28.19",
 		"typescript": "^6.0.3"
 	},
 	"keywords": [
+		"async",
 		"benchmark",
 		"bigint",
 		"csv",
@@ -123,5 +124,5 @@
 		"tag": "benchmark",
 		"year": 2018
 	},
-	"gitHead": "c47c56420bcae2e0477d252a497be44f08ca185a"
+	"gitHead": "4fc0df9a97bec92742f288aa059c04e9ff24cf41"
 }

package/profiler.d.ts

@@ -164,6 +164,14 @@ export declare class Profiler implements IDeref<IObjectOf<ProfileResult>>, IEnab
      * @param fn
      */
     profile<T>(id: string, fn: FnAny<T>, ...args: any[]): T;
+    /**
+     * Async version of {@link Profiler.profile}.
+     *
+     * @param id
+     * @param fn
+     * @param args
+     */
+    profileAsync<T>(id: string, fn: FnAny<Promise<T>>, ...args: any[]): Promise<T>;
     /**
      * Higher-order version of {@link Profiler.profile}. Takes a profile `id`
      * and vararg function `fn`. Returns new function which when called, calls
@@ -202,6 +210,13 @@ export declare class Profiler implements IDeref<IObjectOf<ProfileResult>>, IEnab
      * @param fn
      */
     wrap<T>(id: string, fn: FnAny<T>): (...args: any[]) => T;
+    /**
+     * Async version of {@link Profiler.wrap}.
+     *
+     * @param id
+     * @param fn
+     */
+    wrapAsync<T>(id: string, fn: FnAny<Promise<T>>): (...args: any[]) => Promise<T>;
     /**
      * Estimates the internal overhead of the {@link Profiler.start} and
      * {@link Profiler.end} methods by performing given number of `iter`ations

package/profiler.js

@@ -185,6 +185,19 @@ class Profiler {
     this.end(id);
     return res;
   }
+  /**
+   * Async version of {@link Profiler.profile}.
+   *
+   * @param id
+   * @param fn
+   * @param args
+   */
+  async profileAsync(id, fn, ...args) {
+    this.start(id);
+    const res = await fn.apply(null, args);
+    this.end(id);
+    return res;
+  }
   /**
    * Higher-order version of {@link Profiler.profile}. Takes a profile `id`
    * and vararg function `fn`. Returns new function which when called, calls
@@ -230,6 +243,20 @@ class Profiler {
       return res;
     };
   }
+  /**
+   * Async version of {@link Profiler.wrap}.
+   *
+   * @param id
+   * @param fn
+   */
+  wrapAsync(id, fn) {
+    return async (...args) => {
+      this.start(id);
+      const res = await fn.apply(null, args);
+      this.end(id);
+      return res;
+    };
+  }
   /**
    * Estimates the internal overhead of the {@link Profiler.start} and
    * {@link Profiler.end} methods by performing given number of `iter`ations
@@ -246,10 +273,13 @@ class Profiler {
     let total = 0;
     for (let i = 0; i < 10; i++) {
       const id = `prof-${i}`;
-      const [_, taken] = benchResult(() => {
-        this.start(id);
-        this.end(id);
-      }, ~~(iter / 10));
+      const [_, taken] = benchResult(
+        () => {
+          this.start(id);
+          this.end(id);
+        },
+        ~~(iter / 10)
+      );
       total += taken;
     }
     this._overhead = total / iter;

package/suite.d.ts

@@ -1,3 +1,10 @@
-import type { Benchmark, BenchmarkResult, BenchmarkSuiteOpts } from "./api.js";
+import type { AsyncBenchmark, Benchmark, BenchmarkResult, BenchmarkSuiteOpts } from "./api.js";
 export declare const suite: (cases: Benchmark[], opts?: Partial<BenchmarkSuiteOpts>) => BenchmarkResult[];
+/**
+ * Async version of {@link suite}.
+ *
+ * @param cases
+ * @param opts
+ */
+export declare const suiteAsync: (cases: AsyncBenchmark[], opts?: Partial<BenchmarkSuiteOpts>) => Promise<BenchmarkResult[]>;
 //# sourceMappingURL=suite.d.ts.map

package/suite.js

@@ -1,4 +1,9 @@
-import { benchmark, DEFAULT_OPTS, outputString } from "./benchmark.js";
+import {
+  benchmark,
+  benchmarkAsync,
+  DEFAULT_OPTS,
+  outputString
+} from "./benchmark.js";
 const suite = (cases, opts) => {
   const _opts = {
     ...DEFAULT_OPTS,
@@ -13,6 +18,23 @@ const suite = (cases, opts) => {
   _opts.output && outputString(_opts.format.suffix());
   return results;
 };
+const suiteAsync = async (cases, opts) => {
+  const _opts = {
+    ...DEFAULT_OPTS,
+    ...opts
+  };
+  _opts.output && outputString(_opts.format.prefix());
+  const results = [];
+  for (const c of cases) {
+    results.push(
+      await benchmarkAsync(c.fn, { ..._opts, ...c.opts, title: c.title })
+    );
+  }
+  _opts.output && outputString(_opts.format.total(results));
+  _opts.output && outputString(_opts.format.suffix());
+  return results;
+};
 export {
-  suite
+  suite,
+  suiteAsync
 };

package/timed.d.ts

@@ -8,6 +8,13 @@ import type { TimingResult } from "./api.js";
  * @param prefix - log prefix
  */
 export declare const timed: <T>(fn: () => T, prefix?: string) => T;
+/**
+ * Async version of {@link timed}.
+ *
+ * @param fn
+ * @param prefix
+ */
+export declare const timedAsync: <T>(fn: () => Promise<T>, prefix?: string) => Promise<T>;
 /**
  * Similar to {@link timed}, but produces no output and instead returns
  * tuple of `fn`'s result and the time measurement (in milliseconds).
@@ -15,4 +22,10 @@ export declare const timed: <T>(fn: () => T, prefix?: string) => T;
  * @param fn - function to time
  */
 export declare const timedResult: <T>(fn: () => T) => TimingResult<T>;
+/**
+ * Async version of {@link timedResult}.
+ *
+ * @param fn
+ */
+export declare const timedResultAsync: <T>(fn: () => Promise<T>) => Promise<TimingResult<T>>;
 //# sourceMappingURL=timed.d.ts.map

package/timed.js

@@ -4,13 +4,26 @@ const timed = (fn, prefix = "") => {
   console.log(`${prefix} ${t.toFixed(2)}ms`);
   return res;
 };
+const timedAsync = async (fn, prefix = "") => {
+  const [res, t] = await timedResultAsync(fn);
+  console.log(`${prefix} ${t.toFixed(2)}ms`);
+  return res;
+};
 const timedResult = (fn) => {
   const t0 = now();
   const res = fn();
   const t1 = now();
   return [res, timeDiff(t0, t1)];
 };
+const timedResultAsync = async (fn) => {
+  const t0 = now();
+  const res = await fn();
+  const t1 = now();
+  return [res, timeDiff(t0, t1)];
+};
 export {
   timed,
-  timedResult
+  timedAsync,
+  timedResult,
+  timedResultAsync
 };