feat: export formatNumber, add documentation for converting the result for console.table (#444)

* feat: export formatNumber, add documentation for converting the results for console.table

* fix

Author: Uzlopak

README.md

@@ -100,58 +100,6 @@ task.addEventListener('cycle', (evt) => {
 
 ### [`BenchEvent`](https://tinylibs.github.io/tinybench/types/BenchEvent.html)
 
-## Timestamp Providers
-
-Tinybench can utilize different timestamp providers for measuring time intervals.
-By default it uses `performance.now()`.
-
-The `timestampProvider` option can be set when creating a `Bench` instance. It
-accepts either a `TimestampProvider` object or shorthands for the common
-providers `hrtimeNow` and `performanceNow`.
-
-If you use `bun` runtime, you can also use `bunNanoseconds` shorthand.
-
-You can set the `timestampProvider` to `auto` to let Tinybench choose the most
-precise available timestamp provider based on the runtime.
-
-```ts
-import { Bench } from 'tinybench'
-
-const bench = new Bench({
-  timestampProvider: 'hrtimeNow' // or 'performanceNow', 'bunNanoseconds', 'auto'
-})
-```
-
-If you want to provide a custom timestamp provider, you can create an object that implements
-the `TimestampProvider` interface:
-
-```ts
-import { Bench, TimestampProvider } from 'tinybench'
-
-// Custom timestamp provider using Date.now()
-const dateNowTimestampProvider: TimestampProvider = {
-  name: 'dateNow', // name of the provider
-  fn: Date.now, // function that returns the current timestamp
-  toMs: ts => ts, // convert the timestamp to milliseconds
-  fromMs: ts => ts // convert milliseconds to the format used by fn()
-}
-
-const bench = new Bench({
-  timestampProvider: dateNowTimestampProvider
-})
-```
-
-You can also set the `now` option to a function that returns the current timestamp.
-It will be converted to a `TimestampProvider` internally.
-
-```ts
-import { Bench } from 'tinybench'
-
-const bench = new Bench({
-  now: Date.now
-})
-```
-
 ## Async Detection
 
 Tinybench automatically detects if a task function is asynchronous by
@@ -198,6 +146,64 @@ bench.concurrency = 'task' // The concurrency mode to determine how tasks are ru
 await bench.run()
 ```
 
+## Convert task results for `console.table()`
+
+You can convert the benchmark results to a table format suitable for
+`console.table()` using the `bench.table()` method.
+
+```ts
+const table = bench.table()
+console.table(table)
+```
+
+You can also customize the table output by providing a convert-function to the `table` method.
+
+```ts
+import { Bench, type ConsoleTableConverter, formatNumber, mToNs, type Task } from 'tinybench'
+
+/**
+ * The default converter function for console.table output.
+ * Modify it as needed to customize the table format.
+ */
+const defaultConverter: ConsoleTableConverter = (
+  task: Task
+): Record<string, number | string> => {
+  const state = task.result.state
+  return {
+    'Task name': task.name,
+    ...(state === 'aborted-with-statistics' || state === 'completed'
+      ? {
+          'Latency avg (ns)': `${formatNumber(mToNs(task.result.latency.mean))} \xb1 ${task.result.latency.rme.toFixed(2)}%`,
+          'Latency med (ns)': `${formatNumber(mToNs(task.result.latency.p50))} \xb1 ${formatNumber(mToNs(task.result.latency.mad))}`,
+          'Throughput avg (ops/s)': `${Math.round(task.result.throughput.mean).toString()} \xb1 ${task.result.throughput.rme.toFixed(2)}%`,
+          'Throughput med (ops/s)': `${Math.round(task.result.throughput.p50).toString()} \xb1 ${Math.round(task.result.throughput.mad).toString()}`,
+          Samples: task.result.latency.samplesCount,
+        }
+      : state !== 'errored'
+        ? {
+            'Latency avg (ns)': 'N/A',
+            'Latency med (ns)': 'N/A',
+            'Throughput avg (ops/s)': 'N/A',
+            'Throughput med (ops/s)': 'N/A',
+            Samples: 'N/A',
+            Remarks: state,
+          }
+        : {
+            Error: task.result.error.message,
+            Stack: task.result.error.stack ?? 'N/A',
+          }),
+    ...(state === 'aborted-with-statistics' && {
+      Remarks: state,
+    }),
+  }
+}
+
+const bench = new Bench({ name: 'custom table benchmark', time: 100 })
+// add tasks...
+
+console.table(bench.table(defaultConverter))
+```
+
 ## Retaining Samples
 
 By default Tinybench does not keep the samples for `latency` and `throughput` to
@@ -220,6 +226,58 @@ bench.add('task with samples', () => {
 }, { retainSamples: true })
 ```
 
+## Timestamp Providers
+
+Tinybench can utilize different timestamp providers for measuring time intervals.
+By default it uses `performance.now()`.
+
+The `timestampProvider` option can be set when creating a `Bench` instance. It
+accepts either a `TimestampProvider` object or shorthands for the common
+providers `hrtimeNow` and `performanceNow`.
+
+If you use `bun` runtime, you can also use `bunNanoseconds` shorthand.
+
+You can set the `timestampProvider` to `auto` to let Tinybench choose the most
+precise available timestamp provider based on the runtime.
+
+```ts
+import { Bench } from 'tinybench'
+
+const bench = new Bench({
+  timestampProvider: 'hrtimeNow' // or 'performanceNow', 'bunNanoseconds', 'auto'
+})
+```
+
+If you want to provide a custom timestamp provider, you can create an object that implements
+the `TimestampProvider` interface:
+
+```ts
+import { Bench, TimestampProvider } from 'tinybench'
+
+// Custom timestamp provider using Date.now()
+const dateNowTimestampProvider: TimestampProvider = {
+  name: 'dateNow', // name of the provider
+  fn: Date.now, // function that returns the current timestamp
+  toMs: ts => ts, // convert the timestamp to milliseconds
+  fromMs: ts => ts // convert milliseconds to the format used by fn()
+}
+
+const bench = new Bench({
+  timestampProvider: dateNowTimestampProvider
+})
+```
+
+You can also set the `now` option to a function that returns the current timestamp.
+It will be converted to a `TimestampProvider` internally.
+
+```ts
+import { Bench } from 'tinybench'
+
+const bench = new Bench({
+  now: Date.now
+})
+```
+
 ## Aborting Benchmarks
 
 Tinybench supports aborting benchmarks using `AbortSignal` at both the bench and task levels:

src/index.ts

@@ -37,4 +37,4 @@ export type {
   TimestampProvider,
   TimestampValue,
 } from './types'
-export { hrtimeNow, performanceNow as now, nToMs } from './utils'
+export { formatNumber, hrtimeNow, performanceNow as now, nToMs } from './utils'