@fuzdev/fuz_util 0.42.0 → 0.44.0

package/dist/time.js

@@ -0,0 +1,264 @@
+/**
+ * Time utilities.
+ * Provides cross-platform high-resolution timing and measurement helpers.
+ */
+/**
+ * Node.js high-resolution timer using process.hrtime.bigint().
+ * Provides true nanosecond precision.
+ */
+export const timer_node = {
+    now: () => {
+        const ns = process.hrtime.bigint();
+        return Number(ns); // Native nanoseconds
+    },
+};
+/**
+ * Browser high-resolution timer using performance.now().
+ * Converts milliseconds to nanoseconds for consistent API.
+ *
+ * **Precision varies by browser due to Spectre/Meltdown mitigations:**
+ * - Chrome: ~100μs (coarsened)
+ * - Firefox: ~1ms (rounded)
+ * - Safari: ~100μs
+ * - Node.js: ~1μs
+ *
+ * For nanosecond-precision benchmarks, use Node.js with `timer_node`.
+ */
+export const timer_browser = {
+    now: () => {
+        return performance.now() * 1_000_000; // Convert ms to ns
+    },
+};
+/**
+ * Detect the best available timer function for the current environment.
+ * Called once and cached for performance.
+ */
+const detect_timer_fn = () => {
+    // Check if we're in Node.js with hrtime.bigint support
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (typeof process !== 'undefined' && process.hrtime) {
+        try {
+            if (typeof process.hrtime.bigint !== 'undefined') {
+                return timer_node.now;
+            }
+        }
+        catch {
+            // Ignore and fall through
+        }
+    }
+    // Fallback to performance.now() (works in browsers and modern Node.js)
+    if (typeof performance !== 'undefined' && typeof performance.now === 'function') {
+        return timer_browser.now;
+    }
+    // Last resort: Date.now() (millisecond precision only)
+    return () => Date.now() * 1_000_000;
+};
+// Cache the detected timer function
+let _cached_timer_fn = null;
+const get_timer_fn = () => {
+    if (_cached_timer_fn === null) {
+        _cached_timer_fn = detect_timer_fn();
+    }
+    return _cached_timer_fn;
+};
+/**
+ * Auto-detected timer based on environment.
+ * Uses process.hrtime in Node.js, performance.now() in browsers.
+ * The timer function is detected once and cached for performance.
+ */
+export const timer_default = {
+    now: () => get_timer_fn()(),
+};
+/**
+ * Time units and conversions.
+ */
+export const TIME_NS_PER_US = 1_000;
+export const TIME_NS_PER_MS = 1_000_000;
+export const TIME_NS_PER_SEC = 1_000_000_000;
+/**
+ * Convert nanoseconds to microseconds.
+ */
+export const time_ns_to_us = (ns) => ns / TIME_NS_PER_US;
+/**
+ * Convert nanoseconds to milliseconds.
+ */
+export const time_ns_to_ms = (ns) => ns / TIME_NS_PER_MS;
+/**
+ * Convert nanoseconds to seconds.
+ */
+export const time_ns_to_sec = (ns) => ns / TIME_NS_PER_SEC;
+/**
+ * Display labels for time units (uses proper Unicode μ for microseconds).
+ */
+export const TIME_UNIT_DISPLAY = { ns: 'ns', us: 'μs', ms: 'ms', s: 's' };
+/**
+ * Detect the best time unit for a set of nanosecond values.
+ * Chooses the unit where most values fall in the range 1-9999.
+ * @param values_ns - Array of times in nanoseconds
+ * @returns Best unit to use for all values
+ */
+export const time_unit_detect_best = (values_ns) => {
+    if (values_ns.length === 0)
+        return 'ms';
+    // Filter out invalid values
+    const valid = values_ns.filter((v) => isFinite(v) && v > 0);
+    if (valid.length === 0)
+        return 'ms';
+    // Find the median value (more stable than mean for outliers)
+    const sorted = [...valid].sort((a, b) => a - b);
+    const median = sorted[Math.floor(sorted.length / 2)];
+    // Choose unit based on median magnitude
+    if (median < 1_000) {
+        return 'ns'; // < 1μs
+    }
+    else if (median < 1_000_000) {
+        return 'us'; // < 1ms
+    }
+    else if (median < 1_000_000_000) {
+        return 'ms'; // < 1s
+    }
+    else {
+        return 's'; // >= 1s
+    }
+};
+/**
+ * Format time with a specific unit.
+ * @param ns - Time in nanoseconds
+ * @param unit - Unit to use ('ns', 'us', 'ms', 's')
+ * @param decimals - Number of decimal places (default: 2)
+ * @returns Formatted string like "3.87μs"
+ */
+export const time_format = (ns, unit, decimals = 2) => {
+    if (!isFinite(ns))
+        return String(ns);
+    switch (unit) {
+        case 'ns':
+            return `${ns.toFixed(decimals)}ns`;
+        case 'us':
+            return `${time_ns_to_us(ns).toFixed(decimals)}μs`;
+        case 'ms':
+            return `${time_ns_to_ms(ns).toFixed(decimals)}ms`;
+        case 's':
+            return `${time_ns_to_sec(ns).toFixed(decimals)}s`;
+    }
+};
+/**
+ * Format time with adaptive units (ns/μs/ms/s) based on magnitude.
+ * @param ns - Time in nanoseconds
+ * @param decimals - Number of decimal places (default: 2)
+ * @returns Formatted string like "3.87μs" or "1.23ms"
+ *
+ * @example
+ * ```ts
+ * time_format_adaptive(1500) // "1.50μs"
+ * time_format_adaptive(3870) // "3.87μs"
+ * time_format_adaptive(1500000) // "1.50ms"
+ * time_format_adaptive(1500000000) // "1.50s"
+ * ```
+ */
+export const time_format_adaptive = (ns, decimals = 2) => {
+    if (!isFinite(ns))
+        return String(ns);
+    // Choose unit based on magnitude
+    if (ns < 1_000) {
+        return time_format(ns, 'ns', decimals);
+    }
+    else if (ns < 1_000_000) {
+        return time_format(ns, 'us', decimals);
+    }
+    else if (ns < 1_000_000_000) {
+        return time_format(ns, 'ms', decimals);
+    }
+    else {
+        return time_format(ns, 's', decimals);
+    }
+};
+/**
+ * Time an asynchronous function execution.
+ * @param fn - Async function to time
+ * @param timer - Timer to use (defaults to timer_default)
+ * @returns Object containing the function result and timing information
+ *
+ * @example
+ * ```ts
+ * const {result, timing} = await time_async(async () => {
+ *   await fetch('https://api.example.com/data');
+ *   return 42;
+ * });
+ * console.log(`Result: ${result}, took ${time_format_adaptive(timing.elapsed_ns)}`);
+ * ```
+ */
+export const time_async = async (fn, timer = timer_default) => {
+    const started_at_ns = timer.now();
+    const result = await fn();
+    const ended_at_ns = timer.now();
+    const elapsed_ns = ended_at_ns - started_at_ns;
+    return {
+        result,
+        timing: {
+            elapsed_ns,
+            elapsed_us: time_ns_to_us(elapsed_ns),
+            elapsed_ms: time_ns_to_ms(elapsed_ns),
+            started_at_ns,
+            ended_at_ns,
+        },
+    };
+};
+/**
+ * Time a synchronous function execution.
+ * @param fn - Sync function to time
+ * @param timer - Timer to use (defaults to timer_default)
+ * @returns Object containing the function result and timing information
+ *
+ * @example
+ * ```ts
+ * const {result, timing} = time_sync(() => {
+ *   return expensive_computation();
+ * });
+ * console.log(`Result: ${result}, took ${time_format_adaptive(timing.elapsed_ns)}`);
+ * ```
+ */
+export const time_sync = (fn, timer = timer_default) => {
+    const started_at_ns = timer.now();
+    const result = fn();
+    const ended_at_ns = timer.now();
+    const elapsed_ns = ended_at_ns - started_at_ns;
+    return {
+        result,
+        timing: {
+            elapsed_ns,
+            elapsed_us: time_ns_to_us(elapsed_ns),
+            elapsed_ms: time_ns_to_ms(elapsed_ns),
+            started_at_ns,
+            ended_at_ns,
+        },
+    };
+};
+/**
+ * Measure multiple executions of a function and return all timings.
+ * @param fn - Function to measure (sync or async)
+ * @param iterations - Number of times to execute
+ * @param timer - Timer to use (defaults to timer_default)
+ * @returns Array of elapsed times in nanoseconds
+ *
+ * @example
+ * ```ts
+ * const timings_ns = await time_measure(async () => {
+ *   await process_data();
+ * }, 100);
+ *
+ * import {BenchmarkStats} from './benchmark_stats.js';
+ * const stats = new BenchmarkStats(timings_ns);
+ * console.log(`Mean: ${time_format_adaptive(stats.mean_ns)}`);
+ * ```
+ */
+export const time_measure = async (fn, iterations, timer = timer_default) => {
+    const timings = [];
+    for (let i = 0; i < iterations; i++) {
+        const started_at_ns = timer.now();
+        await fn(); // eslint-disable-line no-await-in-loop
+        const ended_at_ns = timer.now();
+        timings.push(ended_at_ns - started_at_ns);
+    }
+    return timings;
+};

package/dist/timings.d.ts

@@ -9,19 +9,13 @@ export type TimingsKey = string | number;
  * Allows starting, stopping, and retrieving timings with optional precision.
  */
 export declare class Timings {
+    #private;
     readonly decimals: number | undefined;
-    private readonly timings;
-    private readonly stopwatches;
     constructor(decimals?: number);
     /**
      * Starts a timing operation for the given key.
      */
     start(key: TimingsKey, decimals?: number | undefined): () => number;
-    private next_key;
-    /**
-     * Stops a timing operation and records the elapsed time.
-     */
-    private stop;
     get(key: TimingsKey): number;
     entries(): IterableIterator<[TimingsKey, number | undefined]>;
     /**

package/dist/timings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timings.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/timings.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,MAAM,CAAC;AAEpD;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,iBAAY,KAAG,SAQ/C,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC;;;GAGG;AACH,qBAAa,OAAO;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAEtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkD;IAC1E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyC;gBAEzD,QAAQ,CAAC,EAAE,MAAM;IAI7B;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,qBAAgB,GAAG,MAAM,MAAM;IAO9D,OAAO,CAAC,QAAQ;IAShB;;OAEG;IACH,OAAO,CAAC,IAAI;IASZ,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM;IAM5B,OAAO,IAAI,gBAAgB,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAI7D;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;CAc7B"}
+{"version":3,"file":"timings.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/timings.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,MAAM,CAAC;AAEpD;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,iBAAY,KAAG,SAQ/C,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC;;;GAGG;AACH,qBAAa,OAAO;;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;gBAK1B,QAAQ,CAAC,EAAE,MAAM;IAI7B;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,qBAAgB,GAAG,MAAM,MAAM;IA4B9D,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM;IAM5B,OAAO,IAAI,gBAAgB,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAI7D;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;CAc7B"}

package/dist/timings.js

@@ -18,8 +18,8 @@ export const create_stopwatch = (decimals = 2) => {
  */
 export class Timings {
     decimals;
-    timings = new Map();
-    stopwatches = new Map();
+    #timings = new Map();
+    #stopwatches = new Map();
     constructor(decimals) {
         this.decimals = decimals;
     }
@@ -27,41 +27,41 @@ export class Timings {
      * Starts a timing operation for the given key.
      */
     start(key, decimals = this.decimals) {
-        const final_key = this.next_key(key);
-        this.stopwatches.set(final_key, create_stopwatch(decimals));
-        this.timings.set(final_key, undefined); // initializing to preserve order
-        return () => this.stop(final_key);
+        const final_key = this.#next_key(key);
+        this.#stopwatches.set(final_key, create_stopwatch(decimals));
+        this.#timings.set(final_key, undefined); // initializing to preserve order
+        return () => this.#stop(final_key);
     }
-    next_key(key) {
-        if (!this.stopwatches.has(key))
+    #next_key(key) {
+        if (!this.#stopwatches.has(key))
             return key;
         let i = 2;
         while (true) {
             const next = key + '_' + i++;
-            if (!this.stopwatches.has(next))
+            if (!this.#stopwatches.has(next))
                 return next;
         }
     }
     /**
      * Stops a timing operation and records the elapsed time.
      */
-    stop(key) {
-        const stopwatch = this.stopwatches.get(key);
+    #stop(key) {
+        const stopwatch = this.#stopwatches.get(key);
         if (!stopwatch)
             return 0; // TODO maybe warn?
-        this.stopwatches.delete(key);
+        this.#stopwatches.delete(key);
         const timing = stopwatch();
-        this.timings.set(key, timing);
+        this.#timings.set(key, timing);
         return timing;
     }
     get(key) {
-        const timing = this.timings.get(key);
+        const timing = this.#timings.get(key);
         if (timing === undefined)
             return 0; // TODO maybe warn?
         return timing;
     }
     entries() {
-        return this.timings.entries();
+        return this.#timings.entries();
     }
     /**
      * Merges other timings into this one,
@@ -69,7 +69,7 @@ export class Timings {
      */
     merge(timings) {
         for (const [key, timing] of timings.entries()) {
-            this.timings.set(key, timing === undefined ? undefined : (this.timings.get(key) ?? 0) + timing);
+            this.#timings.set(key, timing === undefined ? undefined : (this.#timings.get(key) ?? 0) + timing);
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_util",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "utility belt for JS",
   "glyph": "🦕",
   "logo": "logo.svg",
@@ -8,7 +8,7 @@
   "motto": "ancient not extinct",
   "public": true,
   "license": "MIT",
-  "homepage": "https://belt.ryanatkn.com/",
+  "homepage": "https://util.fuz.dev/",
   "author": {
     "name": "Ryan Atkinson",
     "email": "mail@ryanatkn.com",
@@ -16,9 +16,9 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ryanatkn/belt.git"
+    "url": "git+https://github.com/fuzdev/fuz_util.git"
   },
-  "bugs": "https://github.com/ryanatkn/belt/issues",
+  "bugs": "https://github.com/fuzdev/fuz_util/issues",
   "funding": "https://www.ryanatkn.com/funding",
   "scripts": {
     "start": "gro dev",
@@ -28,9 +28,11 @@
     "test": "gro test",
     "preview": "vite preview",
     "deploy": "gro deploy",
-    "benchmark": "gro run src/benchmarks/slugify_benchmark.ts",
-    "benchmark-deep-equal": "node --max-old-space-size=8192 --expose-gc --import @ryanatkn/gro/register.js src/lib/deep_equal.bench_comparison.ts",
-    "benchmark-deep-equal-deno": "deno run --allow-read --allow-env --v8-flags=--expose-gc src/lib/deep_equal.bench_comparison.ts"
+    "benchmark": "gro run src/benchmarks/run.ts",
+    "benchmark:save": "gro run src/benchmarks/run.ts --save",
+    "benchmark_slugify": "gro run src/benchmarks/slugify.benchmark.ts",
+    "benchmark_deep_equal": "gro run src/benchmarks/deep_equal.benchmark.ts",
+    "benchmark_deep_equal_comparison": "gro run src/benchmarks/deep_equal_comparison.benchmark.ts"
   },
   "type": "module",
   "engines": {
@@ -60,29 +62,29 @@
   },
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
+    "@fuzdev/fuz_code": "^0.38.0",
+    "@fuzdev/fuz_css": "^0.42.1",
+    "@fuzdev/fuz_ui": "^0.172.0",
     "@ryanatkn/eslint-config": "^0.9.0",
-    "@ryanatkn/fuz": "^0.167.0",
-    "@ryanatkn/fuz_code": "^0.36.0",
-    "@ryanatkn/gro": "^0.179.0",
-    "@ryanatkn/moss": "^0.39.0",
+    "@ryanatkn/gro": "^0.181.0",
     "@sveltejs/adapter-static": "^3.0.10",
-    "@sveltejs/kit": "^2.49.0",
-    "@sveltejs/package": "^2.5.6",
+    "@sveltejs/kit": "^2.49.1",
+    "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.1",
     "@types/node": "^24.10.1",
     "dequal": "^2.0.3",
     "eslint": "^9.39.1",
-    "eslint-plugin-svelte": "^3.13.0",
+    "eslint-plugin-svelte": "^3.13.1",
     "esm-env": "^1.2.2",
-    "prettier": "^3.6.2",
+    "fast-deep-equal": "^3.1.3",
+    "prettier": "^3.7.4",
     "prettier-plugin-svelte": "^3.4.0",
-    "svelte": "^5.44.1",
+    "svelte": "^5.45.6",
     "svelte-check": "^4.3.4",
-    "tinybench": "^5.1.0",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.48.0",
-    "vitest": "^4.0.14",
+    "typescript-eslint": "^8.48.1",
+    "vitest": "^4.0.15",
     "zod": "^4.1.13"
   },
   "prettier": {

package/src/lib/async.ts

@@ -7,10 +7,10 @@ export const wait = (duration = 0): Promise<void> =>
 	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: any): value is Promise<any> =>
-	value && typeof value.then === 'function';
+export const is_promise = (value: unknown): value is Promise<unknown> =>
+	value != null && typeof (value as Promise<unknown>).then === 'function';
 
 /**
  * Creates a deferred object with a promise and its resolve/reject handlers.