@fuzdev/fuz_util 0.42.0

package/src/lib/random_alea.ts

@@ -0,0 +1,107 @@
+/*
+
+DO NOT USE when security matters, use webcrypto APIs instead.
+This is the Alea pseudo-random number generator by Johannes Baagøe.
+
+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>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+*/
+
+export interface Alea {
+	(): number;
+	uint32: () => number;
+	fract53: () => number;
+	version: string;
+	seeds: Array<unknown>;
+}
+
+/**
+ * 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 => {
+	let s0 = 0;
+	let s1 = 0;
+	let s2 = 0;
+	let c = 1;
+
+	const seeds = seed.length ? seed : [Date.now()];
+	let mash: Mash | null = masher();
+	s0 = mash(' ');
+	s1 = mash(' ');
+	s2 = mash(' ');
+
+	for (const s of seeds) {
+		s0 -= mash(s);
+		if (s0 < 0) s0 += 1;
+		s1 -= mash(s);
+		if (s1 < 0) s1 += 1;
+		s2 -= mash(s);
+		if (s2 < 0) s2 += 1;
+	}
+	mash = null;
+
+	const random: Alea = (): number => {
+		const t = 2091639 * s0 + c * 2.3283064365386963e-10; // 2^-32
+		s0 = s1;
+		s1 = s2;
+		return (s2 = t - (c = t | 0));
+	};
+	random.uint32 = (): number => {
+		return random() * 0x100000000; // 2^32
+	};
+	random.fract53 = (): number => {
+		return random() + ((random() * 0x200000) | 0) * 1.1102230246251565e-16; // 2^-53
+	};
+	random.version = 'Alea 0.9';
+	random.seeds = seeds;
+	return random;
+};
+
+type Mash = (data: any) => number;
+
+/**
+ * @source http://baagoe.com/en/RandomMusings/javascript/
+ * @copyright Johannes Baagøe <baagoe@baagoe.com>, 2010
+ */
+export const masher = (): Mash => {
+	let n = 0xefc8249d;
+	return (data) => {
+		const d = data + '';
+		for (let i = 0; i < d.length; i++) {
+			n += d.charCodeAt(i);
+			let h = 0.02519603282416938 * n;
+			n = h >>> 0;
+			h -= n;
+			h *= n;
+			n = h >>> 0;
+			h -= n;
+			n += h * 0x100000000; // 2^32
+		}
+		return (n >>> 0) * 2.3283064365386963e-10; // 2^-32
+	};
+};

package/src/lib/regexp.ts

@@ -0,0 +1,17 @@
+/**
+ * Escapes a string for literal matching in a RegExp.
+ * @source https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/RegularExpressions
+ */
+export const escape_regexp = (str: string): string => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Reset a RegExp's lastIndex to 0 for global and sticky patterns.
+ * Ensures consistent behavior by clearing state that affects subsequent matches.
+ * @mutates regexp sets lastIndex to 0 if regexp is global or sticky
+ */
+export const reset_regexp = <T extends RegExp>(regexp: T): T => {
+	if (regexp.global || regexp.sticky) {
+		regexp.lastIndex = 0;
+	}
+	return regexp;
+};

package/src/lib/result.ts

@@ -0,0 +1,67 @@
+/**
+ * An alternative pattern to throwing and catching errors.
+ * Uses the type system to strongly type error return values when desired.
+ * Catching errors is then reserved for unexpected situations.
+ */
+export type Result<TValue = object, TError = object> =
+	| ({ok: true} & TValue)
+	| ({ok: false} & TError);
+
+/**
+ * Frozen object representing a successful result.
+ */
+export const OK = Object.freeze({ok: true} as const);
+
+/**
+ * Frozen object representing a failed result.
+ */
+export const NOT_OK = Object.freeze({ok: false} as const);
+
+/**
+ * A helper that says,
+ * "hey I know this is wrapped in a `Result`, but I expect it to be `ok`,
+ * so if it's not, I understand it will throw an error that wraps the result".
+ * @param result Some `Result` object.
+ * @param message Optional custom error message.
+ * @returns The wrapped value.
+ */
+export const unwrap = <TValue extends {value?: unknown}, TError extends {message?: string}>(
+	result: Result<TValue, TError>,
+	message?: string,
+): TValue['value'] => {
+	if (!result.ok) throw new ResultError(result, message);
+	return result.value;
+};
+
+/**
+ * A custom error class that's thrown by `unwrap`.
+ * Wraps a failed `Result` with an optional message,
+ * and also accepts an optional message that overrides the result's.
+ * Useful for generic handling of unwrapped results
+ * to forward custom messages and other failed result data.
+ */
+export class ResultError extends Error {
+	static DEFAULT_MESSAGE = 'unknown error';
+
+	readonly result: {ok: false; message?: string};
+
+	constructor(result: {ok: false; message?: string}, message?: string, options?: ErrorOptions) {
+		super(message ?? result.message ?? ResultError.DEFAULT_MESSAGE, options);
+		this.result = result;
+	}
+}
+
+/**
+ * A helper that does the opposite of `unwrap`, throwing if the `Result` is ok.
+ * Note that while `unwrap` returns the wrapped `value`, `unwrap_error` returns the entire result.
+ * @param result Some `Result` object.
+ * @param message Optional custom error message.
+ * @returns The type-narrowed result.
+ */
+export const unwrap_error = <TError extends object>(
+	result: Result<object, TError>,
+	message = 'Failed to unwrap result error',
+): {ok: false} & TError => {
+	if (result.ok) throw Error(message);
+	return result;
+};

package/src/lib/source_json.ts

@@ -0,0 +1,209 @@
+/**
+ * Metadata types for library source code analysis.
+ *
+ * These types represent the structure of `src/lib/` exports,
+ * extracted at build time via TypeScript compiler analysis.
+ * Used for generating API documentation and enabling code search.
+ *
+ * Hierarchy: SourceJson → ModuleJson → DeclarationJson
+ */
+
+import {z} from 'zod';
+
+/**
+ * The kind of exported declaration.
+ */
+export const DeclarationKind = z.enum([
+	'type',
+	'function',
+	'variable',
+	'class',
+	'constructor',
+	'component',
+	'json',
+	'css',
+]);
+export type DeclarationKind = z.infer<typeof DeclarationKind>;
+
+/**
+ * Generic type parameter information.
+ */
+export const GenericParamInfo = z.looseObject({
+	/** Parameter name like `T`. */
+	name: z.string(),
+	/** Constraint like `string` from `T extends string`. */
+	constraint: z.string().optional(),
+	/** Default type like `unknown` from `T = unknown`. */
+	default_type: z.string().optional(),
+});
+export type GenericParamInfo = z.infer<typeof GenericParamInfo>;
+
+/**
+ * Parameter information for functions and methods.
+ *
+ * Kept distinct from ComponentPropInfo despite structural similarity.
+ * Function parameters form a tuple with positional semantics:
+ * calling order matters (`fn(a, b)` vs `fn(b, a)`),
+ * may include rest parameters and destructuring patterns.
+ */
+export const ParameterInfo = z.looseObject({
+	name: z.string(),
+	type: z.string(),
+	optional: z.boolean().optional(),
+	description: z.string().optional(),
+	default_value: z.string().optional(),
+});
+export type ParameterInfo = z.infer<typeof ParameterInfo>;
+
+/**
+ * Component prop information for Svelte components.
+ *
+ * Kept distinct from ParameterInfo despite structural similarity.
+ * Component props are named attributes with different semantics:
+ * no positional order when passing (`<Foo {a} {b} />` = `<Foo {b} {a} />`),
+ * support two-way binding via `$bindable` rune.
+ */
+export const ComponentPropInfo = z.looseObject({
+	name: z.string(),
+	type: z.string(),
+	optional: z.boolean().optional(),
+	description: z.string().optional(),
+	default_value: z.string().optional(),
+	bindable: z.boolean().optional(),
+});
+export type ComponentPropInfo = z.infer<typeof ComponentPropInfo>;
+
+/**
+ * Metadata for an exported declaration (function, type, class, component, etc.).
+ *
+ * Extracted from TypeScript source and JSDoc/TSDoc comments at build time.
+ */
+export const DeclarationJson = z.looseObject({
+	/** The exported name. */
+	name: z.string(),
+	kind: DeclarationKind,
+	/** JSDoc/TSDoc comment in mdz format. */
+	doc_comment: z.string().optional(),
+	/** Full TypeScript type signature. */
+	type_signature: z.string().optional(),
+	/** TypeScript modifiers like `readonly`, `private`, or `static`. */
+	modifiers: z.array(z.string()).optional(),
+	/** 1-indexed line number in source file. */
+	source_line: z.number().optional(),
+	/** Function/method parameters. */
+	parameters: z.array(ParameterInfo).optional(),
+	/** Function/method return type. */
+	return_type: z.string().optional(),
+	/** Return value description from `@returns` tag. */
+	return_description: z.string().optional(),
+	/** Generic type parameters like `<T, U>`. */
+	generic_params: z.array(GenericParamInfo).optional(),
+	/** Code examples from `@example` tags. */
+	examples: z.array(z.string()).optional(),
+	/** Deprecation message from `@deprecated` tag. */
+	deprecated_message: z.string().optional(),
+	/** Related items from `@see` tags, in mdz format. */
+	see_also: z.array(z.string()).optional(),
+	/** Exceptions from `@throws` tags. */
+	throws: z.array(z.looseObject({type: z.string().optional(), description: z.string()})).optional(),
+	/** Version introduced, from `@since` tag. */
+	since: z.string().optional(),
+	/** Extended classes/interfaces. */
+	extends: z.array(z.string()).optional(),
+	/** Implemented interfaces. */
+	implements: z.array(z.string()).optional(),
+	/** Class or interface members (recursive). */
+	get members() {
+		return z.array(DeclarationJson).optional();
+	},
+	/** Type/interface properties (recursive). */
+	get properties() {
+		return z.array(DeclarationJson).optional();
+	},
+	/** Svelte component props. */
+	props: z.array(ComponentPropInfo).optional(),
+	/**
+	 * Module paths (relative to src/lib) that re-export this declaration.
+	 * The canonical location is this module's `declarations` array.
+	 */
+	also_exported_from: z.array(z.string()).optional(),
+	/**
+	 * For renamed re-exports (`export {foo as bar}`), the original declaration.
+	 */
+	alias_of: z
+		.object({
+			module: z.string(),
+			name: z.string(),
+		})
+		.optional(),
+});
+export type DeclarationJson = z.infer<typeof DeclarationJson>;
+
+/**
+ * A source file in `src/lib/` with its exported declarations.
+ */
+export const ModuleJson = z.looseObject({
+	/** Path relative to src/lib (e.g., `helpers.ts`). */
+	path: z.string(),
+	declarations: z.array(DeclarationJson).optional(),
+	/** File-level JSDoc comment. */
+	module_comment: z.string().optional(),
+	/** Modules this imports (paths relative to src/lib). */
+	dependencies: z.array(z.string()).optional(),
+	/** Modules that import this (paths relative to src/lib). */
+	dependents: z.array(z.string()).optional(),
+});
+export type ModuleJson = z.infer<typeof ModuleJson>;
+
+/**
+ * Metadata for a library's `src/lib/` exports.
+ */
+export const SourceJson = z.looseObject({
+	name: z.string(),
+	version: z.string(),
+	modules: z.array(ModuleJson).optional(),
+});
+export type SourceJson = z.infer<typeof SourceJson>;
+
+/**
+ * Format declaration name with generic parameters for display.
+ * @example declaration_get_display_name({name: 'Map', kind: 'type', generic_params: [{name: 'K'}, {name: 'V'}]})
+ * // => 'Map<K, V>'
+ */
+export const declaration_get_display_name = (declaration: DeclarationJson): string => {
+	if (!declaration.generic_params?.length) return declaration.name;
+	const params = declaration.generic_params.map((p) => {
+		let param = p.name;
+		if (p.constraint) param += ` extends ${p.constraint}`;
+		if (p.default_type) param += ` = ${p.default_type}`;
+		return param;
+	});
+	return `${declaration.name}<${params.join(', ')}>`;
+};
+
+/**
+ * Generate TypeScript import statement for a declaration.
+ * @example declaration_generate_import({name: 'Foo', kind: 'type'}, 'foo.ts', '@pkg/lib')
+ * // => "import type {Foo} from '@pkg/lib/foo.js';"
+ */
+export const declaration_generate_import = (
+	declaration: DeclarationJson,
+	module_path: string,
+	library_name: string,
+): string => {
+	const js_path = module_path.replace(/\.ts$/, '.js');
+	const specifier = `${library_name}/${js_path}`;
+
+	// Handle default exports by converting module name to PascalCase
+	if (declaration.name === 'default') {
+		const module_name = module_path.replace(/\.(js|ts|svelte)$/, '');
+		const pascal_case = module_name
+			.split(/[-_]/)
+			.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+			.join('');
+		return `import ${pascal_case} from '${specifier}';`;
+	}
+
+	const import_keyword = declaration.kind === 'type' ? 'import type' : 'import';
+	return `${import_keyword} {${declaration.name}} from '${specifier}';`;
+};

package/src/lib/string.ts

@@ -0,0 +1,99 @@
+import {count_iterator} from './iterator.js';
+
+/**
+ * Truncates a string to a maximum length, adding a suffix if needed that defaults to `...`.
+ */
+export const truncate = (str: string, maxLength: number, suffix = '...'): string => {
+	if (maxLength < suffix.length) return '';
+	if (str.length > maxLength) {
+		return str.substring(0, maxLength - suffix.length) + suffix;
+	}
+	return str;
+};
+
+/**
+ * Removes characters inclusive of `stripped`.
+ */
+export const strip_start = (source: string, stripped: string): string => {
+	if (!stripped || !source.startsWith(stripped)) return source;
+	return source.substring(stripped.length);
+};
+
+/**
+ * Removes characters inclusive of `stripped`.
+ */
+export const strip_end = (source: string, stripped: string): string => {
+	if (!stripped || !source.endsWith(stripped)) return source;
+	return source.substring(0, source.length - stripped.length);
+};
+
+/**
+ * Removes characters inclusive of `stripped`.
+ */
+export const strip_after = (source: string, stripped: string): string => {
+	if (!stripped) return source;
+	const idx = source.indexOf(stripped);
+	if (idx === -1) return source;
+	return source.substring(0, idx);
+};
+
+/**
+ * Removes characters inclusive of `stripped`.
+ */
+export const strip_before = (source: string, stripped: string): string => {
+	if (!stripped) return source;
+	const idx = source.indexOf(stripped);
+	if (idx === -1) return source;
+	return source.substring(idx + stripped.length);
+};
+
+/**
+ * Adds the substring `ensured` to the start of the `source` string if it's not already present.
+ */
+export const ensure_start = (source: string, ensured: string): string => {
+	if (source.startsWith(ensured)) return source;
+	return ensured + source;
+};
+
+/**
+ * Adds the substring `ensured` to the end of the `source` string if it's not already present.
+ */
+export const ensure_end = (source: string, ensured: string): string => {
+	if (source.endsWith(ensured)) return source;
+	return source + ensured;
+};
+
+/**
+ * Removes leading and trailing spaces from each line of a string.
+ */
+export const deindent = (str: string): string =>
+	str
+		.split('\n')
+		.filter(Boolean)
+		.map((s) => s.trim())
+		.join('\n');
+
+/**
+ * Returns a plural suffix based on a count.
+ */
+export const plural = (count: number | undefined | null, suffix = 's'): string =>
+	count === 1 ? '' : suffix;
+
+/**
+ * Returns the count of graphemes in a string, the individually rendered characters.
+ */
+export const count_graphemes = (str: string): number =>
+	count_iterator(new Intl.Segmenter().segment(str));
+
+/**
+ * Strips ANSI escape sequences from a string
+ */
+export const strip_ansi = (str: string): string => str.replaceAll(/\x1B\[[0-9;]*[a-zA-Z]/g, ''); // eslint-disable-line no-control-regex
+
+/**
+ * Stringifies a value like `JSON.stringify` but with some corner cases handled better.
+ *
+ * @source https://2ality.com/2025/04/stringification-javascript.html
+ */
+export const stringify = (value: unknown): string =>
+	typeof value === 'bigint' ? value + 'n' : (JSON.stringify(value) ?? String(value)); // eslint-disable-line @typescript-eslint/no-unnecessary-condition

package/src/lib/throttle.ts

@@ -0,0 +1,70 @@
+import {create_deferred, type Deferred} from './async.js';
+import {EMPTY_OBJECT} from './object.js';
+
+export interface ThrottleOptions {
+	/**
+	 * Enforced milliseconds between calls. For `when='trailing'` this is the debounce delay.
+	 */
+	delay?: number;
+	/**
+	 * When to call the throttled function. Defaults to `both`.
+	 */
+	when?: 'both' | 'leading' | 'trailing';
+}
+
+/**
+ * Throttles calls to a callback that returns a void promise.
+ * Immediately invokes the callback on the first call unless `leading=false`.
+ * If the throttled function is called while the promise is already pending,
+ * the call is queued to run after the pending promise completes plus `delay`,
+ * and only the last call is invoked.
+ * In other words, all calls and their args are discarded
+ * during the pending window except for the most recent.
+ * Unlike debouncing, this calls the throttled callback
+ * both on the leading and trailing edges of the delay window by default,
+ * and this can be customized by setting `leading` or `trailing.
+ * It also differs from a queue where every call to the throttled callback eventually runs.
+ * @returns same as `cb`
+ */
+export const throttle = <T extends (...args: Array<any>) => Promise<void>>(
+	cb: T,
+	{delay = 0, when = 'both'}: ThrottleOptions = EMPTY_OBJECT,
+): T => {
+	let pending_promise: Promise<void> | null = null;
+	let next_args: Array<any> | null = null;
+	let next_deferred: Deferred<void> | null = null;
+
+	const defer = (args: Array<any>): Promise<void> => {
+		next_args = args;
+		if (!next_deferred) {
+			next_deferred = create_deferred<void>();
+			setTimeout(flush, delay);
+		}
+		return next_deferred.promise;
+	};
+
+	const flush = async (): Promise<void> => {
+		if (!next_deferred) return;
+		const result = await call(next_args!);
+		next_args = null;
+		const {resolve} = next_deferred;
+		next_deferred = null;
+		resolve(result); // resolve last to prevent synchronous call issues
+	};
+
+	const call = (args: Array<any>): Promise<any> => {
+		pending_promise = cb(...args);
+		void pending_promise.finally(() => {
+			pending_promise = null;
+		});
+		return pending_promise;
+	};
+
+	return ((...args) => {
+		if (pending_promise || when === 'trailing') {
+			return when === 'leading' ? pending_promise : defer(args); // discarded when pending and not trailing
+		} else {
+			return call(args);
+		}
+	}) as T;
+};

package/src/lib/timings.ts

@@ -0,0 +1,93 @@
+import {round} from './maths.js';
+
+export type Stopwatch = (reset?: boolean) => number;
+
+/**
+ * Tracks elapsed time in milliseconds.
+ */
+export const create_stopwatch = (decimals = 2): Stopwatch => {
+	let start = performance.now();
+	return (reset = false) => {
+		const end = performance.now();
+		const elapsed = round(Number(end - start), decimals); // eslint-disable-line @typescript-eslint/no-unnecessary-type-conversion
+		if (reset) start = end;
+		return elapsed;
+	};
+};
+
+export type TimingsKey = string | number;
+
+/**
+ * Tracks and manages multiple timing operations.
+ * Allows starting, stopping, and retrieving timings with optional precision.
+ */
+export class Timings {
+	readonly decimals: number | undefined;
+
+	private readonly timings: Map<TimingsKey, number | undefined> = new Map();
+	private readonly stopwatches: Map<TimingsKey, Stopwatch> = new Map();
+
+	constructor(decimals?: number) {
+		this.decimals = decimals;
+	}
+
+	/**
+	 * Starts a timing operation for the given key.
+	 */
+	start(key: TimingsKey, decimals = this.decimals): () => number {
+		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);
+	}
+
+	private next_key(key: TimingsKey): TimingsKey {
+		if (!this.stopwatches.has(key)) return key;
+		let i = 2;
+		while (true) {
+			const next = key + '_' + i++;
+			if (!this.stopwatches.has(next)) return next;
+		}
+	}
+
+	/**
+	 * Stops a timing operation and records the elapsed time.
+	 */
+	private stop(key: TimingsKey): number {
+		const stopwatch = this.stopwatches.get(key);
+		if (!stopwatch) return 0; // TODO maybe warn?
+		this.stopwatches.delete(key);
+		const timing = stopwatch();
+		this.timings.set(key, timing);
+		return timing;
+	}
+
+	get(key: TimingsKey): number {
+		const timing = this.timings.get(key);
+		if (timing === undefined) return 0; // TODO maybe warn?
+		return timing;
+	}
+
+	entries(): IterableIterator<[TimingsKey, number | undefined]> {
+		return this.timings.entries();
+	}
+
+	/**
+	 * Merges other timings into this one,
+	 * adding together values with identical keys.
+	 */
+	merge(timings: Timings): void {
+		for (const [key, timing] of timings.entries()) {
+			this.timings.set(
+				key,
+				timing === undefined ? undefined : (this.timings.get(key) ?? 0) + timing,
+			);
+		}
+	}
+
+	// clear(): void {
+	// 	this.stopwatches.clear();
+	// 	this.timings.clear();
+	// }
+	// toJSON() {} ?????
+}