@fuzdev/fuz_util 0.52.0 → 0.53.0

package/dist/zod.js

@@ -0,0 +1,198 @@
+/**
+ * Zod schema introspection utilities.
+ *
+ * Generic helpers for extracting metadata from Zod schemas.
+ * Designed for CLI argument parsing but applicable elsewhere.
+ *
+ * @module
+ */
+//
+// Schema Introspection
+//
+/**
+ * Unwrap nested schema types (optional, default, nullable, etc).
+ *
+ * @param def - Zod type definition to unwrap.
+ * @returns Inner schema if wrapped, undefined otherwise.
+ */
+export const zod_to_subschema = (def) => {
+    if ('innerType' in def) {
+        return def.innerType;
+    }
+    else if ('in' in def) {
+        return def.in;
+    }
+    else if ('schema' in def) {
+        return def.schema;
+    }
+    return undefined;
+};
+/**
+ * Get the description from a schema's metadata, unwrapping if needed.
+ *
+ * @param schema - Zod schema to extract description from.
+ * @returns Description string or null if not found.
+ */
+export const zod_to_schema_description = (schema) => {
+    const meta = schema.meta();
+    if (meta?.description) {
+        return meta.description;
+    }
+    const subschema = zod_to_subschema(schema.def);
+    if (subschema) {
+        return zod_to_schema_description(subschema);
+    }
+    return null;
+};
+/**
+ * Get the default value from a schema, unwrapping if needed.
+ *
+ * @param schema - Zod schema to extract default from.
+ * @returns Default value or undefined.
+ */
+export const zod_to_schema_default = (schema) => {
+    const { def } = schema._zod;
+    if ('defaultValue' in def) {
+        return def.defaultValue;
+    }
+    const subschema = zod_to_subschema(def);
+    if (subschema) {
+        return zod_to_schema_default(subschema);
+    }
+    return undefined;
+};
+/**
+ * Get aliases from a schema's metadata, unwrapping if needed.
+ *
+ * @param schema - Zod schema to extract aliases from.
+ * @returns Array of alias strings.
+ */
+export const zod_to_schema_aliases = (schema) => {
+    const meta = schema.meta();
+    if (meta?.aliases) {
+        return meta.aliases;
+    }
+    const subschema = zod_to_subschema(schema.def);
+    if (subschema) {
+        return zod_to_schema_aliases(subschema);
+    }
+    return [];
+};
+/**
+ * Get the type string for a schema, suitable for display.
+ *
+ * @param schema - Zod schema to get type string for.
+ * @returns Human-readable type string.
+ */
+export const zod_to_schema_type_string = (schema) => {
+    const { def } = schema._zod;
+    switch (def.type) {
+        case 'string':
+            return 'string';
+        case 'number':
+            return 'number';
+        case 'int':
+            return 'int';
+        case 'boolean':
+            return 'boolean';
+        case 'bigint':
+            return 'bigint';
+        case 'null':
+            return 'null';
+        case 'undefined':
+            return 'undefined';
+        case 'any':
+            return 'any';
+        case 'unknown':
+            return 'unknown';
+        case 'array':
+            return 'Array<string>';
+        case 'enum':
+            return schema.options
+                .map((v) => `'${v}'`)
+                .join(' | ');
+        case 'literal':
+            return def.values
+                .map((v) => zod_format_value(v))
+                .join(' | ');
+        case 'nullable': {
+            const subschema = zod_to_subschema(def);
+            return subschema ? zod_to_schema_type_string(subschema) + ' | null' : 'nullable';
+        }
+        case 'optional': {
+            const subschema = zod_to_subschema(def);
+            return subschema ? zod_to_schema_type_string(subschema) + ' | undefined' : 'optional';
+        }
+        default: {
+            const subschema = zod_to_subschema(def);
+            return subschema ? zod_to_schema_type_string(subschema) : def.type;
+        }
+    }
+};
+/**
+ * Format a value for display in help text.
+ *
+ * @param value - Value to format.
+ * @returns Formatted string representation.
+ */
+export const zod_format_value = (value) => {
+    if (value === undefined)
+        return '';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return `'${value}'`;
+    if (Array.isArray(value))
+        return '[]';
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    if (typeof value === 'boolean' || typeof value === 'number')
+        return String(value);
+    return '';
+};
+/**
+ * Extract properties from a Zod object schema.
+ *
+ * @param schema - Zod object schema to extract from.
+ * @returns Array of property definitions.
+ */
+export const zod_to_schema_properties = (schema) => {
+    const { def } = schema;
+    if (!('shape' in def)) {
+        return [];
+    }
+    const shape = def.shape;
+    const properties = [];
+    for (const name in shape) {
+        // Skip no- prefixed fields (used for boolean negation)
+        if ('no-' + name in shape)
+            continue;
+        const field = shape[name];
+        properties.push({
+            name,
+            type: zod_to_schema_type_string(field),
+            description: zod_to_schema_description(field) ?? '',
+            default: zod_to_schema_default(field),
+            aliases: zod_to_schema_aliases(field),
+        });
+    }
+    return properties;
+};
+/**
+ * Get all property names and their aliases from an object schema.
+ *
+ * @param schema - Zod object schema.
+ * @returns Set of all names and aliases.
+ */
+export const zod_to_schema_names_with_aliases = (schema) => {
+    const names = new Set();
+    for (const prop of zod_to_schema_properties(schema)) {
+        if (prop.name !== '_') {
+            names.add(prop.name);
+            for (const alias of prop.aliases) {
+                names.add(alias);
+            }
+        }
+    }
+    return names;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_util",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "utility belt for JS",
   "glyph": "🦕",
   "logo": "logo.svg",
@@ -31,7 +31,9 @@
     "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"
+    "benchmark_deep_equal_comparison": "gro run src/benchmarks/deep_equal_comparison.benchmark.ts",
+    "benchmark_random": "gro run src/benchmarks/random.benchmark.ts",
+    "benchmark_random_quality": "gro run src/benchmarks/random_quality.ts"
   },
   "type": "module",
   "engines": {
@@ -44,6 +46,7 @@
     "web"
   ],
   "peerDependencies": {
+    "@fuzdev/blake3_wasm": "^0.1.0",
     "@types/estree": "^1",
     "@types/node": "^24",
     "esm-env": "^1.2.2",
@@ -51,13 +54,16 @@
     "zod": "^4.0.14"
   },
   "peerDependenciesMeta": {
-    "@types/node": {
+    "@fuzdev/blake3_wasm": {
       "optional": true
     },
-    "esm-env": {
+    "@types/estree": {
       "optional": true
     },
-    "@types/estree": {
+    "@types/node": {
+      "optional": true
+    },
+    "esm-env": {
       "optional": true
     },
     "svelte": {
@@ -69,10 +75,11 @@
   },
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
+    "@fuzdev/blake3_wasm": "^0.1.0",
     "@fuzdev/fuz_code": "^0.45.1",
-    "@fuzdev/fuz_css": "^0.52.0",
-    "@fuzdev/fuz_ui": "^0.184.0",
-    "@fuzdev/gro": "^0.194.0",
+    "@fuzdev/fuz_css": "^0.54.0",
+    "@fuzdev/fuz_ui": "^0.185.2",
+    "@fuzdev/gro": "^0.196.0",
     "@jridgewell/trace-mapping": "^0.3.31",
     "@ryanatkn/eslint-config": "^0.9.0",
     "@sveltejs/adapter-static": "^3.0.10",

package/src/lib/bytes.ts

@@ -0,0 +1,21 @@
+/**
+ * Binary data conversion helpers.
+ *
+ * @module
+ */
+
+const encoder = new TextEncoder();
+
+/**
+ * Converts string or binary data to a `Uint8Array`.
+ * Strings are UTF-8 encoded. `Uint8Array` inputs are returned as-is.
+ *
+ * @param data - String or `BufferSource` to convert.
+ * @returns `Uint8Array` view of the data.
+ */
+export const to_bytes = (data: BufferSource | string): Uint8Array => {
+	if (typeof data === 'string') return encoder.encode(data);
+	if (data instanceof Uint8Array) return data;
+	if (data instanceof ArrayBuffer) return new Uint8Array(data);
+	return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+};

package/src/lib/hash.ts

@@ -1,45 +1,26 @@
 /**
  * Hash utilities for content comparison and cache invalidation.
  *
- * Provides both secure (cryptographic) and insecure (fast) hash functions.
+ * Provides `hash_sha256` (Web Crypto, async) and `hash_insecure` (DJB2, fast non-cryptographic).
+ * For BLAKE3, see `hash_blake3` in `hash_blake3.ts`.
  *
  * @module
  */
 
-const encoder = new TextEncoder();
+import {to_hex} from './hex.js';
 
-// Lazily computed lookup table for byte to hex conversion
-let byte_to_hex: Array<string> | undefined;
-const get_byte_to_hex = (): Array<string> => {
-	if (byte_to_hex === undefined) {
-		byte_to_hex = new Array(256); // 256 possible byte values (0x00-0xff)
-		for (let i = 0; i < 256; i++) {
-			byte_to_hex[i] = i.toString(16).padStart(2, '0');
-		}
-	}
-	return byte_to_hex;
-};
+const encoder = new TextEncoder();
 
 /**
- * Computes a cryptographic hash using Web Crypto API.
+ * Computes a SHA-256 hash using Web Crypto API.
  *
  * @param data - String or binary data to hash. Strings are UTF-8 encoded.
- * @param algorithm - Hash algorithm. Defaults to SHA-256.
- * @returns Hexadecimal hash string.
+ * @returns 64-character hexadecimal hash string.
  */
-export const hash_secure = async (
-	data: BufferSource | string,
-	algorithm: 'SHA-256' | 'SHA-384' | 'SHA-512' = 'SHA-256',
-): Promise<string> => {
+export const hash_sha256 = async (data: BufferSource | string): Promise<string> => {
 	const buffer = typeof data === 'string' ? encoder.encode(data) : data;
-	const digested = await crypto.subtle.digest(algorithm, buffer);
-	const bytes = new Uint8Array(digested);
-	const lookup = get_byte_to_hex();
-	let hex = '';
-	for (const byte of bytes) {
-		hex += lookup[byte];
-	}
-	return hex;
+	const digested = await crypto.subtle.digest('SHA-256', buffer);
+	return to_hex(new Uint8Array(digested));
 };
 
 /**

package/src/lib/hash_blake3.ts

@@ -0,0 +1,20 @@
+/**
+ * BLAKE3 cryptographic hashing via `@fuzdev/blake3_wasm`.
+ *
+ * Synchronous and fast. Returns hex-encoded 256-bit (32-byte) digests.
+ *
+ * @module
+ */
+
+import {hash} from '@fuzdev/blake3_wasm';
+
+import {to_hex} from './hex.js';
+import {to_bytes} from './bytes.js';
+
+/**
+ * Computes a BLAKE3 hash synchronously.
+ *
+ * @param data - String or binary data to hash. Strings are UTF-8 encoded.
+ * @returns 64-character hexadecimal hash string (32 bytes).
+ */
+export const hash_blake3 = (data: BufferSource | string): string => to_hex(hash(to_bytes(data)));

package/src/lib/hex.ts

@@ -0,0 +1,32 @@
+/**
+ * Hex encoding helpers.
+ *
+ * @module
+ */
+
+/**
+ * Converts a `Uint8Array` to a lowercase hex string.
+ *
+ * @param bytes - Binary data to encode.
+ * @returns Hex string with two characters per byte.
+ */
+export const to_hex = (bytes: Uint8Array): string => {
+	const lookup = get_byte_to_hex();
+	let hex = '';
+	for (const byte of bytes) {
+		hex += lookup[byte];
+	}
+	return hex;
+};
+
+// Lazily computed lookup table for byte to hex conversion
+let byte_to_hex: Array<string> | undefined;
+const get_byte_to_hex = (): Array<string> => {
+	if (byte_to_hex === undefined) {
+		byte_to_hex = new Array(256); // 256 possible byte values (0x00-0xff)
+		for (let i = 0; i < 256; i++) {
+			byte_to_hex[i] = i.toString(16).padStart(2, '0');
+		}
+	}
+	return byte_to_hex;
+};

package/src/lib/log.ts

@@ -415,7 +415,12 @@ export class Logger {
 	 */
 	info(...args: Array<unknown>): void {
 		if (this.#get_cached_level() < LOG_LEVEL_VALUES.info) return;
-		this.console.log(this.#get_info_prefix(), ...args);
+		const prefix = this.#get_info_prefix();
+		if (prefix) {
+			this.console.log(prefix, ...args);
+		} else {
+			this.console.log(...args);
+		}
 	}
 
 	/**

package/src/lib/random.ts

@@ -1,3 +1,13 @@
+/**
+ * Random helpers that accept an optional `random` parameter,
+ * defaulting to `Math.random`. Pass a seeded PRNG for reproducible results:
+ *
+ * - {@link create_random_xoshiro} — fast, high-quality numeric seeding (recommended)
+ * - {@link create_random_alea} — supports string and variadic seeds
+ *
+ * @module
+ */
+
 import type {ArrayElement} from './types.js';
 
 /**

package/src/lib/random_alea.ts

@@ -1,10 +1,36 @@
-/*
-
-DO NOT USE when security matters, use webcrypto APIs instead.
-This is the Alea pseudo-random number generator by Johannes Baagøe.
+/**
+ * Alea: a seedable pseudo-random number generator by Johannes Baagøe.
+ * Supports variadic and string seeds (`create_random_alea('my', 3, 'seeds')`).
+ * For numeric seeds, prefer `create_random_xoshiro` which is faster with equal quality.
+ *
+ * DO NOT USE when security matters — use the Web Crypto API (`crypto.getRandomValues`) instead.
+ *
+ * Alea passes all 11 distribution quality tests at 10M samples,
+ * performing on par with `Math.random` (V8's xorshift128+):
+ *
+ * - mean, variance, chi-squared uniformity, Kolmogorov-Smirnov
+ * - lag-1 through lag-8 autocorrelation
+ * - runs test, gap test, permutation test (triples)
+ * - bit-level frequency (bits 0-7)
+ * - 2D serial pairs (25x25 through 200x200 grids)
+ * - birthday spacings (Marsaglia parameters)
+ *
+ * Speed is ~19% slower than `Math.random` (~12.2M ops/sec vs ~15.0M ops/sec).
+ *
+ * To reproduce:
+ *
+ * ```bash
+ * npm run benchmark_random_quality          # distribution tests (N=1M)
+ * npm run benchmark_random_quality -- --deep # thorough (N=10M, multi-trial)
+ * npm run benchmark_random                  # speed comparison
+ * ```
+ *
+ * @see https://github.com/nquinlan/better-random-numbers-for-javascript-mirror
+ *
+ * @module
+ */
 
-From http://baagoe.com/en/RandomMusings/javascript/
-via https://github.com/nquinlan/better-random-numbers-for-javascript-mirror
+/*
 
 Copyright (C) 2010 by Johannes Baagøe <baagoe@baagoe.org>
 
@@ -28,7 +54,7 @@ THE SOFTWARE.
 
 */
 
-export interface Alea {
+export interface RandomAlea {
 	(): number;
 	uint32: () => number;
 	fract53: () => number;
@@ -40,10 +66,9 @@ export interface Alea {
  * Seeded pseudo-random number generator.
  * DO NOT USE when security matters, use webcrypto APIs instead.
  *
- * @see http://baagoe.com/en/RandomMusings/javascript/
  * @see https://github.com/nquinlan/better-random-numbers-for-javascript-mirror
  */
-export const create_random_alea = (...seed: Array<unknown>): Alea => {
+export const create_random_alea = (...seed: Array<unknown>): RandomAlea => {
 	let s0 = 0;
 	let s1 = 0;
 	let s2 = 0;
@@ -65,7 +90,7 @@ export const create_random_alea = (...seed: Array<unknown>): Alea => {
 	}
 	mash = null;
 
-	const random: Alea = (): number => {
+	const random: RandomAlea = (): number => {
 		const t = 2091639 * s0 + c * 2.3283064365386963e-10; // 2^-32
 		s0 = s1;
 		s1 = s2;
@@ -85,10 +110,10 @@ export const create_random_alea = (...seed: Array<unknown>): Alea => {
 type Mash = (data: any) => number;
 
 /**
- * @source http://baagoe.com/en/RandomMusings/javascript/
+ * @source https://github.com/nquinlan/better-random-numbers-for-javascript-mirror
  * @copyright Johannes Baagøe <baagoe@baagoe.com>, 2010
  */
-export const masher = (): Mash => {
+const masher = (): Mash => {
 	let n = 0xefc8249d;
 	return (data) => {
 		const d = data + '';

package/src/lib/random_xoshiro.ts

@@ -0,0 +1,124 @@
+/**
+ * Xoshiro128**: a seedable pseudo-random number generator by Blackman & Vigna (2018).
+ * Recommended for reproducible randomness (testing, simulations, procedural generation).
+ *
+ * DO NOT USE when security matters — use the Web Crypto API (`crypto.getRandomValues`) instead.
+ *
+ * Xoshiro128** has a 2^128-1 period and passes BigCrush.
+ * It uses pure 32-bit arithmetic (shifts, rotates, XOR, multiply)
+ * making it very fast in JavaScript via `Math.imul`.
+ *
+ * Xoshiro128** passes all 11 distribution quality tests at 10M samples,
+ * performing on par with `Math.random` (V8's xorshift128+):
+ *
+ * - mean, variance, chi-squared uniformity, Kolmogorov-Smirnov
+ * - lag-1 through lag-8 autocorrelation
+ * - runs test, gap test, permutation test (triples)
+ * - bit-level frequency (bits 0-7)
+ * - 2D serial pairs (25x25 through 200x200 grids)
+ * - birthday spacings (Marsaglia parameters)
+ *
+ * Speed is near-native (~4% slower than `Math.random`) and ~18% faster than Alea
+ * (~14.4M ops/sec vs ~15.0M and ~12.2M respectively).
+ *
+ * To reproduce:
+ *
+ * ```bash
+ * npm run benchmark_random_quality          # distribution tests (N=1M)
+ * npm run benchmark_random_quality -- --deep # thorough (N=10M, multi-trial)
+ * npm run benchmark_random                  # speed comparison
+ * ```
+ *
+ * @see https://prng.di.unimi.it/
+ * @see https://vigna.di.unimi.it/ftp/papers/ScrambledLinear.pdf
+ *
+ * @module
+ */
+
+/*
+
+Written in 2018 by David Blackman and Sebastiano Vigna (vigna@acm.org)
+
+To the extent possible under law, the author has dedicated all copyright
+and related and neighboring rights to this software to the public domain
+worldwide. This software is distributed without any warranty.
+
+See <https://creativecommons.org/publicdomain/zero/1.0/>.
+
+*/
+
+export interface RandomXoshiro {
+	(): number;
+	uint32: () => number;
+	fract53: () => number;
+	version: string;
+	seed: number;
+}
+
+/**
+ * Seeded pseudo-random number generator using the Xoshiro128** algorithm.
+ * DO NOT USE when security matters, use webcrypto APIs instead.
+ *
+ * @see https://prng.di.unimi.it/
+ */
+export const create_random_xoshiro = (seed?: number): RandomXoshiro => {
+	const actual_seed = seed ?? Date.now();
+	let sm_state = actual_seed | 0;
+
+	// expand single seed into 4 state words via SplitMix32
+	let r = splitmix32_next(sm_state);
+	let s0 = r.value;
+	sm_state = r.state;
+	r = splitmix32_next(sm_state);
+	let s1 = r.value;
+	sm_state = r.state;
+	r = splitmix32_next(sm_state);
+	let s2 = r.value;
+	sm_state = r.state;
+	r = splitmix32_next(sm_state);
+	let s3 = r.value;
+
+	// guard against all-zero state (absorbing fixed point)
+	if ((s0 | s1 | s2 | s3) === 0) s0 = 1;
+
+	const next_uint32 = (): number => {
+		const result = Math.imul(rotl(Math.imul(s1, 5), 7), 9);
+		const t = s1 << 9;
+
+		s2 ^= s0;
+		s3 ^= s1;
+		s1 ^= s2;
+		s0 ^= s3;
+		s2 ^= t;
+		s3 = rotl(s3, 11);
+
+		return result >>> 0;
+	};
+
+	const random: RandomXoshiro = (): number => next_uint32() / 0x100000000; // 2^32
+
+	random.uint32 = next_uint32;
+
+	random.fract53 = (): number => {
+		return random() + ((random() * 0x200000) | 0) * 1.1102230246251565e-16; // 2^-53
+	};
+
+	random.version = 'Xoshiro128** 1.0';
+	random.seed = actual_seed;
+
+	return random;
+};
+
+/**
+ * Expands a 32-bit state by one step using the SplitMix32 algorithm,
+ * producing the four state words needed by Xoshiro128**.
+ */
+const splitmix32_next = (prev_state: number): {value: number; state: number} => {
+	const next_state = (prev_state + 0x9e3779b9) | 0;
+	let z = next_state;
+	z = Math.imul(z ^ (z >>> 16), 0x85ebca6b);
+	z = Math.imul(z ^ (z >>> 13), 0xc2b2ae35);
+	return {value: (z ^ (z >>> 16)) >>> 0, state: next_state};
+};
+
+const rotl = (x: number, k: number): number => (x << k) | (x >>> (32 - k));