@fuzdev/fuz_util 0.42.0 → 0.43.0

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) Ryan Atkinson <mail@ryanatkn.com> <https://ryanatkn.com/>
+Copyright (c) fuz.dev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,10 +1,10 @@
-# @ryanatkn/belt
+# @fuzdev/fuz_util
 
-[<img src="static/logo.svg" alt="a green sauropod wearing a brown utility belt" align="right" width="256" height="256">](https://belt.ryanatkn.com/)
+[<img src="static/logo.svg" alt="a green sauropod wearing a brown utility belt" align="right" width="256" height="256">](https://util.fuz.dev/)
 
 > utility belt for JS 🦕 ancient not extinct
 
-**[belt.ryanatkn.com](https://belt.ryanatkn.com)**
+**[util.fuz.dev](https://util.fuz.dev)**
 
 design:
 
@@ -15,32 +15,39 @@ design:
 - mix of JS module environments - browser-only, Node-only, universal
 - mostly small pure functions
 - all TypeScript, for styles and Svelte and SvelteKit
-  see <a href="https://github.com/fuz-dev/fuz">@ryanatkn/fuz</a>
+  see <a href="https://github.com/fuz-dev/fuz">@fuzdev/fuz_ui</a>
 - complements the modern web platform, drops legacy quickly
 - kinda minimal in many ways but also not, treeshakes well
+- includes a benchmarking library with rich statistical analysis
 
 ## usage
 
-Install from [npm](https://www.npmjs.com/package/@ryanatkn/belt):
+Install from [npm](https://www.npmjs.com/package/@fuzdev/fuz_util):
 
 ```bash
-npm i -D @ryanatkn/belt
+npm i -D @fuzdev/fuz_util
 ```
 
 Import modules at their full paths:
 
 ```ts
-import {type Result, unwrap} from '@ryanatkn/belt/result.js';
-import {random_int} from '@ryanatkn/belt/random.js';
+import {type Result, unwrap} from '@fuzdev/fuz_util/result.js';
+import {random_int} from '@fuzdev/fuz_util/random.js';
 ```
 
 `.ts` imports also work:
 
 ```ts
-import {deep_equal} from '@ryanatkn/belt/deep_equal.ts';
+import {deep_equal} from '@fuzdev/fuz_util/deep_equal.ts';
 ```
 
-Docs at [belt.ryanatkn.com/docs](https://belt.ryanatkn.com/docs).
+Docs at [util.fuz.dev/docs](https://util.fuz.dev/docs).
+
+## features
+
+### Benchmarking
+
+See [`docs/benchmark.md`](docs/benchmark.md).
 
 ## build
 
@@ -52,13 +59,13 @@ gro build
 
 ## test
 
-For more see [`uvu`](https://github.com/lukeed/uvu)
+For more see [Vitest](https://github.com/vitest-dev/vitest)
 and [Gro's test docs](https://github.com/feltjs/gro/blob/main/src/docs/test.md).
 
 ```bash
 gro test
 gro test filepattern1 filepatternB
-gro test -- uvu --forwarded_args 'to uvu'
+gro test -- --forwarded-args 'to vitest'
 ```
 
 ## deploy

package/dist/async.d.ts

@@ -4,9 +4,9 @@ export type AsyncStatus = 'initial' | 'pending' | 'success' | 'failure';
  */
 export declare const wait: (duration?: number) => Promise<void>;
 /**
- * Checks if `value` is a `Promise`.
+ * Checks if `value` is a `Promise` (or thenable).
  */
-export declare const is_promise: (value: any) => value is Promise<any>;
+export declare const is_promise: (value: unknown) => value is Promise<unknown>;
 /**
  * Creates a deferred object with a promise and its resolve/reject handlers.
  */

package/dist/async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/async.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,IAAI,GAAI,iBAAY,KAAG,OAAO,CAAC,IAAI,CACQ,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,GAAG,KAAG,KAAK,IAAI,OAAO,CAAC,GAAG,CAClB,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,MAAM,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,OAAK,QAAQ,CAAC,CAAC,CAQ/C,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,GAAU,CAAC,EAAE,CAAC,EACxC,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,aAAa,MAAM,KACjB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAoDlB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,sBAAsB,GAAU,CAAC,EAAE,CAAC,EAChD,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,aAAa,MAAM,KACjB,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CA6CxC,CAAC"}
+{"version":3,"file":"async.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/async.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,IAAI,GAAI,iBAAY,KAAG,OAAO,CAAC,IAAI,CACQ,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,OAAO,CAAC,OAAO,CACI,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,MAAM,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,OAAK,QAAQ,CAAC,CAAC,CAQ/C,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,GAAU,CAAC,EAAE,CAAC,EACxC,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,aAAa,MAAM,KACjB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAoDlB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,sBAAsB,GAAU,CAAC,EAAE,CAAC,EAChD,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,aAAa,MAAM,KACjB,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CA6CxC,CAAC"}

package/dist/async.js

@@ -3,9 +3,9 @@
  */
 export const wait = (duration = 0) => new Promise((resolve) => setTimeout(resolve, duration));
 /**
- * Checks if `value` is a `Promise`.
+ * Checks if `value` is a `Promise` (or thenable).
  */
-export const is_promise = (value) => value && typeof value.then === 'function';
+export const is_promise = (value) => value != null && typeof value.then === 'function';
 /**
  * Creates a object with a `promise` and its `resolve`/`reject` handlers.
  */

package/dist/benchmark.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Benchmarking library.
+ *
+ * @example
+ * ```ts
+ * import {Benchmark} from './benchmark.js';
+ *
+ * const bench = new Benchmark({
+ *   duration_ms: 5000,
+ *   warmup_iterations: 5,
+ * });
+ *
+ * bench
+ *   .add('slugify', () => slugify(title))
+ *   .add('slugify_slower', () => slugify_slower(title));
+ *
+ * const results = await bench.run();
+ * console.log(bench.table());
+ * ```
+ */
+import { type BenchmarkFormatJsonOptions } from './benchmark_format.js';
+import type { BenchmarkConfig, BenchmarkTask, BenchmarkResult, BenchmarkFormatTableOptions } from './benchmark_types.js';
+/**
+ * Warmup function by running it multiple times.
+ * Detects whether the function is async based on return value.
+ *
+ * @param fn - Function to warmup (sync or async)
+ * @param iterations - Number of warmup iterations
+ * @param async_hint - If provided, use this instead of detecting
+ * @returns Whether the function is async
+ *
+ * @example
+ * ```ts
+ * const is_async = await benchmark_warmup(() => expensive_operation(), 10);
+ * ```
+ */
+export declare const benchmark_warmup: (fn: () => unknown, iterations: number, async_hint?: boolean) => Promise<boolean>;
+/**
+ * Benchmark class for measuring and comparing function performance.
+ */
+export declare class Benchmark {
+    #private;
+    constructor(config?: BenchmarkConfig);
+    /**
+     * Add a benchmark task.
+     * @param name - Task name or full task object
+     * @param fn - Function to benchmark (if name is string). Return values are ignored.
+     * @returns This Benchmark instance for chaining
+     *
+     * @example
+     * ```ts
+     * bench.add('simple', () => fn());
+     *
+     * // Or with setup/teardown:
+     * bench.add({
+     *   name: 'with setup',
+     *   fn: () => process(data),
+     *   setup: () => { data = load() },
+     *   teardown: () => { cleanup() },
+     * });
+     * ```
+     */
+    add(name: string, fn: () => unknown): this;
+    add(task: BenchmarkTask): this;
+    /**
+     * Remove a benchmark task by name.
+     * @param name - Name of the task to remove
+     * @returns This Benchmark instance for chaining
+     * @throws Error if task with given name doesn't exist
+     *
+     * @example
+     * ```ts
+     * bench.add('task1', () => fn1());
+     * bench.add('task2', () => fn2());
+     * bench.remove('task1');
+     * // Only task2 remains
+     * ```
+     */
+    remove(name: string): this;
+    /**
+     * Mark a task to be skipped during benchmark runs.
+     * @param name - Name of the task to skip
+     * @returns This Benchmark instance for chaining
+     * @throws Error if task with given name doesn't exist
+     *
+     * @example
+     * ```ts
+     * bench.add('task1', () => fn1());
+     * bench.add('task2', () => fn2());
+     * bench.skip('task1');
+     * // Only task2 will run
+     * ```
+     */
+    skip(name: string): this;
+    /**
+     * Mark a task to run exclusively (along with other `only` tasks).
+     * @param name - Name of the task to run exclusively
+     * @returns This Benchmark instance for chaining
+     * @throws Error if task with given name doesn't exist
+     *
+     * @example
+     * ```ts
+     * bench.add('task1', () => fn1());
+     * bench.add('task2', () => fn2());
+     * bench.add('task3', () => fn3());
+     * bench.only('task2');
+     * // Only task2 will run
+     * ```
+     */
+    only(name: string): this;
+    /**
+     * Run all benchmark tasks.
+     * @returns Array of benchmark results
+     */
+    run(): Promise<Array<BenchmarkResult>>;
+    /**
+     * Format results as an ASCII table with percentiles, min/max, and relative performance.
+     * @param options - Formatting options
+     * @returns Formatted table string
+     *
+     * @example
+     * ```ts
+     * // Standard table
+     * console.log(bench.table());
+     *
+     * // Grouped by category
+     * console.log(bench.table({
+     *   groups: [
+     *     { name: 'FAST PATHS', filter: (r) => r.name.includes('fast') },
+     *     { name: 'SLOW PATHS', filter: (r) => r.name.includes('slow') },
+     *   ]
+     * }));
+     * ```
+     */
+    table(options?: BenchmarkFormatTableOptions): string;
+    /**
+     * Format results as a Markdown table.
+     * @returns Formatted markdown string
+     */
+    markdown(): string;
+    /**
+     * Format results as JSON.
+     * @param options - Formatting options (pretty, include_timings)
+     * @returns JSON string
+     */
+    json(options?: BenchmarkFormatJsonOptions): string;
+    /**
+     * Get the benchmark results.
+     * Returns a shallow copy to prevent external mutation.
+     * @returns Array of benchmark results
+     */
+    results(): Array<BenchmarkResult>;
+    /**
+     * Reset the benchmark results.
+     * Keeps tasks intact so benchmarks can be rerun.
+     * @returns This Benchmark instance for chaining
+     */
+    reset(): this;
+    /**
+     * Clear everything (results and tasks).
+     * Use this to start fresh with a new set of benchmarks.
+     * @returns This Benchmark instance for chaining
+     */
+    clear(): this;
+    /**
+     * Get a quick text summary of the fastest task.
+     * @returns Human-readable summary string
+     *
+     * @example
+     * ```ts
+     * console.log(bench.summary());
+     * // "Fastest: slugify_v2 (1,285,515.00 ops/sec, 786.52ns per op)"
+     * // "Slowest: slugify (252,955.00 ops/sec, 3.95μs per op)"
+     * // "Speed difference: 5.08x"
+     * ```
+     */
+    summary(): string;
+}
+//# sourceMappingURL=benchmark.d.ts.map

package/dist/benchmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/benchmark.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,EAMN,KAAK,0BAA0B,EAC/B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACX,eAAe,EACf,aAAa,EACb,eAAe,EACf,2BAA2B,EAC3B,MAAM,sBAAsB,CAAC;AAgD9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,GAC5B,IAAI,MAAM,OAAO,EACjB,YAAY,MAAM,EAClB,aAAa,OAAO,KAClB,OAAO,CAAC,OAAO,CAyBjB,CAAC;AAEF;;GAEG;AACH,qBAAa,SAAS;;gBAMT,MAAM,GAAE,eAAoB;IAcxC;;;;;;;;;;;;;;;;;;OAkBG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,GAAG,IAAI;IAC1C,GAAG,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAkB9B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAS1B;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IASxB;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IASxB;;;OAGG;IACG,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAqH5C;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,2BAA2B,GAAG,MAAM;IAMpD;;;OAGG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;OAIG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,0BAA0B,GAAG,MAAM;IAIlD;;;;OAIG;IACH,OAAO,IAAI,KAAK,CAAC,eAAe,CAAC;IAIjC;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAKb;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAMb;;;;;;;;;;;OAWG;IACH,OAAO,IAAI,MAAM;CA+BjB"}