@fuzdev/fuz_util 0.42.0

package/src/lib/async.ts

@@ -0,0 +1,182 @@
+export type AsyncStatus = 'initial' | 'pending' | 'success' | 'failure';
+
+/**
+ * Waits for the given `duration` before resolving.
+ */
+export const wait = (duration = 0): Promise<void> =>
+	new Promise((resolve) => setTimeout(resolve, duration));
+
+/**
+ * Checks if `value` is a `Promise`.
+ */
+export const is_promise = (value: any): value is Promise<any> =>
+	value && typeof value.then === 'function';
+
+/**
+ * Creates a deferred object with a promise and its resolve/reject handlers.
+ */
+export interface Deferred<T> {
+	promise: Promise<T>;
+	resolve: (value: T) => void;
+	reject: (reason: any) => void;
+}
+
+/**
+ * Creates a object with a `promise` and its `resolve`/`reject` handlers.
+ */
+export const create_deferred = <T>(): Deferred<T> => {
+	let resolve!: (value: T) => void;
+	let reject!: (reason: any) => void;
+	const promise: Promise<T> = new Promise((res, rej) => {
+		resolve = res;
+		reject = rej;
+	});
+	return {promise, resolve, reject};
+};
+
+/**
+ * Maps over items with controlled concurrency, preserving input order.
+ *
+ * @param items array of items to process
+ * @param fn async function to apply to each item
+ * @param concurrency maximum number of concurrent operations
+ * @returns promise resolving to array of results in same order as input
+ *
+ * @example
+ * ```ts
+ * const results = await map_concurrent(
+ *   file_paths,
+ *   async (path) => readFile(path, 'utf8'),
+ *   5, // max 5 concurrent reads
+ * );
+ * ```
+ */
+export const map_concurrent = async <T, R>(
+	items: Array<T>,
+	fn: (item: T, index: number) => Promise<R>,
+	concurrency: number,
+): Promise<Array<R>> => {
+	if (concurrency < 1) {
+		throw new Error('concurrency must be at least 1');
+	}
+
+	const results: Array<R> = new Array(items.length);
+	let next_index = 0;
+	let active_count = 0;
+	let rejected = false;
+	let reject_error: unknown;
+
+	return new Promise((resolve, reject) => {
+		const run_next = (): void => {
+			// Stop spawning if we've rejected
+			if (rejected) return;
+
+			// Check if we're done
+			if (next_index >= items.length && active_count === 0) {
+				resolve(results);
+				return;
+			}
+
+			// Spawn workers up to concurrency limit
+			while (active_count < concurrency && next_index < items.length) {
+				const index = next_index++;
+				const item = items[index]!;
+				active_count++;
+
+				fn(item, index)
+					.then((result) => {
+						if (rejected) return;
+						results[index] = result;
+						active_count--;
+						run_next();
+					})
+					.catch((error) => {
+						if (rejected) return;
+						rejected = true;
+						reject_error = error;
+						reject(reject_error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
+					});
+			}
+		};
+
+		// Handle empty array
+		if (items.length === 0) {
+			resolve(results);
+			return;
+		}
+
+		run_next();
+	});
+};
+
+/**
+ * Like `map_concurrent` but collects all results/errors instead of failing fast.
+ * Returns an array of settlement objects matching the `Promise.allSettled` pattern.
+ *
+ * @param items array of items to process
+ * @param fn async function to apply to each item
+ * @param concurrency maximum number of concurrent operations
+ * @returns promise resolving to array of `PromiseSettledResult` objects in input order
+ *
+ * @example
+ * ```ts
+ * const results = await map_concurrent_settled(urls, fetch, 5);
+ * for (const [i, result] of results.entries()) {
+ *   if (result.status === 'fulfilled') {
+ *     console.log(`${urls[i]}: ${result.value.status}`);
+ *   } else {
+ *     console.error(`${urls[i]}: ${result.reason}`);
+ *   }
+ * }
+ * ```
+ */
+export const map_concurrent_settled = async <T, R>(
+	items: Array<T>,
+	fn: (item: T, index: number) => Promise<R>,
+	concurrency: number,
+): Promise<Array<PromiseSettledResult<R>>> => {
+	if (concurrency < 1) {
+		throw new Error('concurrency must be at least 1');
+	}
+
+	const results: Array<PromiseSettledResult<R>> = new Array(items.length);
+	let next_index = 0;
+	let active_count = 0;
+
+	return new Promise((resolve) => {
+		const run_next = (): void => {
+			// Check if we're done
+			if (next_index >= items.length && active_count === 0) {
+				resolve(results);
+				return;
+			}
+
+			// Spawn workers up to concurrency limit
+			while (active_count < concurrency && next_index < items.length) {
+				const index = next_index++;
+				const item = items[index]!;
+				active_count++;
+
+				fn(item, index)
+					.then((value) => {
+						results[index] = {status: 'fulfilled', value};
+					})
+					.catch((reason: unknown) => {
+						results[index] = {status: 'rejected', reason};
+					})
+					.finally(() => {
+						active_count--;
+						run_next();
+					});
+			}
+		};
+
+		// Handle empty array
+		if (items.length === 0) {
+			resolve(results);
+			return;
+		}
+
+		run_next();
+	});
+};

package/src/lib/colors.ts

@@ -0,0 +1,132 @@
+import type {Flavored} from './types.js';
+import {round} from './maths.js';
+
+// TODO for high-performance usecases, we may want to add variants for any that return a new array to reuse a single array
+// I've run into cases where this is a massive perceptible UX difference
+
+// https://stackoverflow.com/questions/2353211/hsl-to-rgb-color-conversion
+
+export type Hsl = readonly [Hue, Saturation, Lightness];
+export type Hue = Flavored<number, 'Hue'>; // [0, 1]
+export type Saturation = Flavored<number, 'Saturation'>; // [0, 1]
+export type Lightness = Flavored<number, 'Lightness'>; // [0, 1]
+
+export type Rgb = readonly [Red, Green, Blue];
+export type Red = Flavored<number, 'Red'>; // [0, 255]
+export type Green = Flavored<number, 'Green'>; // [0, 255]
+export type Blue = Flavored<number, 'Blue'>; // [0, 255]
+
+/**
+ * Converts an RGB color to a hex color.
+ */
+export const rgb_to_hex = (r: number, g: number, b: number): number => (r << 16) + (g << 8) + b;
+
+/**
+ * Converts a hex color to an RGB color.
+ */
+export const hex_to_rgb = (hex: number): Rgb => [(hex >> 16) & 255, (hex >> 8) & 255, hex & 255];
+
+export const hex_string_to_rgb = (hex: string): Rgb => {
+	var h = hex[0] === '#' ? hex.substring(1) : hex;
+	if (h.length !== 6 && h.length !== 8) throw new Error('invalid hex string');
+	return [parseInt(h[0]! + h[1]!, 16), parseInt(h[2]! + h[3]!, 16), parseInt(h[4]! + h[5]!, 16)];
+};
+
+export const rgb_to_hex_string = (r: number, g: number, b: number): string =>
+	'#' + to_hex_component(r) + to_hex_component(g) + to_hex_component(b);
+
+export const to_hex_component = (v: number): string => {
+	var h = v.toString(16);
+	return h.length === 1 ? '0' + h : h;
+};
+
+/**
+ * Converts an RGB color value to HSL. Conversion formula
+ * adapted from http://wikipedia.org/wiki/HSL_color_space.
+ * Values r/g/b are in the range [0,255] and
+ * returns h/s/l in the range [0,1].
+ */
+export const rgb_to_hsl = (r: number, g: number, b: number): Hsl => {
+	var r2 = r / 255;
+	var g2 = g / 255;
+	var b2 = b / 255;
+	var max = Math.max(r2, g2, b2);
+	var min = Math.min(r2, g2, b2);
+	var l: Lightness = (max + min) / 2;
+	var h!: Hue, s: Saturation;
+	if (max === min) {
+		h = s = 0; // achromatic
+	} else {
+		var d = max - min;
+		s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+		switch (max) {
+			case r2:
+				h = (g2 - b2) / d + (g2 < b2 ? 6 : 0);
+				break;
+			case g2:
+				h = (b2 - r2) / d + 2;
+				break;
+			case b2:
+				h = (r2 - g2) / d + 4;
+				break;
+		}
+		h /= 6;
+	}
+	return [h, round(s, 2), round(l, 2)];
+};
+
+/**
+ * Converts an HSL color value to RGB. Conversion formula
+ * adapted from http://wikipedia.org/wiki/HSL_color_space.
+ * Values h/s/l are in the range [0,1] and
+ * returns r/g/b in the range [0,255].
+ */
+export const hsl_to_rgb = (h: Hue, s: Saturation, l: Lightness): Rgb => {
+	var r: number, g: number, b: number;
+	if (s === 0) {
+		r = g = b = l; // achromatic
+	} else {
+		var q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+		var p = 2 * l - q;
+		r = hue_to_rgb_component(p, q, h + 1 / 3);
+		g = hue_to_rgb_component(p, q, h);
+		b = hue_to_rgb_component(p, q, h - 1 / 3);
+	}
+	return [Math.round(r * 255), Math.round(g * 255), Math.round(b * 255)];
+};
+
+export const hue_to_rgb_component = (p: number, q: number, t: number): number => {
+	var t2 = t < 0 ? t + 1 : t > 1 ? t - 1 : t;
+	if (t2 < 1 / 6) return p + (q - p) * 6 * t2;
+	if (t2 < 1 / 2) return q;
+	if (t2 < 2 / 3) return p + (q - p) * (2 / 3 - t2) * 6;
+	return p;
+};
+
+export const hsl_to_hex = (h: Hue, s: Saturation, l: Lightness): number => {
+	var rgb = hsl_to_rgb(h, s, l); // TODO could safely use the optimized variant
+	return rgb_to_hex(rgb[0], rgb[1], rgb[2]);
+};
+
+export const hsl_to_hex_string = (h: Hue, s: Saturation, l: Lightness): string => {
+	var rgb = hsl_to_rgb(h, s, l); // TODO could safely use the optimized variant
+	return rgb_to_hex_string(rgb[0], rgb[1], rgb[2]);
+};
+
+export const hsl_to_string = (h: Hue, s: Saturation, l: Lightness): string =>
+	`hsl(${Math.round(h * 360)} ${Math.round(s * 100)}% ${Math.round(l * 100)}%)`;
+
+export const hex_string_to_hsl = (hex: string): Hsl => {
+	var rgb = hex_string_to_rgb(hex); // TODO could safely use the optimized variant
+	return rgb_to_hsl(rgb[0], rgb[1], rgb[2]);
+};
+
+const HSL_STRING_MATCHER = /^(hsl\()?\s*(\d+),?\s*(\d+)%,?\s*(\d+)%/;
+
+export const parse_hsl_string = (hsl: string): Hsl => {
+	var match = HSL_STRING_MATCHER.exec(hsl);
+	if (!match) throw new Error('invalid HSL string');
+	return [Number(match[2]) / 360, Number(match[3]) / 100, Number(match[4]) / 100];
+};
+
+// TODO either add an hsla variant or support alpha in the hsl variant

package/src/lib/counter.ts

@@ -0,0 +1,11 @@
+export type Counter = () => number;
+
+export type CreateCounter = (initial?: number) => Counter;
+
+/**
+ * Creates a counter constructor function, starting at `0`.
+ */
+export const create_counter: CreateCounter = (count = 0) => {
+	let c = count;
+	return () => c++;
+};

package/src/lib/deep_equal.ts

@@ -0,0 +1,155 @@
+/**
+ * Deep equality comparison that checks both structure and type.
+ *
+ * Key behaviors:
+ *
+ * - Compares by constructor to prevent type confusion (security: `{}` ≠ `[]`, `{}` ≠ `new Map()`, `new ClassA()` ≠ `new ClassB()`)
+ * - Prevents asymmetry bugs: `deep_equal(a, b)` always equals `deep_equal(b, a)`
+ * - Compares only enumerable own properties (ignores prototypes, symbols, non-enumerable)
+ * - Special handling for: Date (timestamp), Number/Boolean (boxed primitives), Error (message/name)
+ * - Promises always return false (cannot be meaningfully compared)
+ * - Maps/Sets compare by reference for object keys/values
+ *
+ * @param a first value to compare
+ * @param b second value to compare
+ * @returns true if deeply equal, false otherwise
+ */
+export const deep_equal = (a: unknown, b: unknown): boolean => {
+	if (Object.is(a, b)) return true;
+
+	const a_type = typeof a;
+
+	if (a_type !== typeof b) return false;
+
+	switch (a_type) {
+		case 'string':
+		case 'number':
+		case 'bigint':
+		case 'boolean':
+		case 'symbol':
+		case 'undefined':
+		case 'function':
+			return false;
+		default:
+			break;
+	}
+
+	// a_type === 'object'
+
+	if (a === null || b === null) return false;
+
+	// Constructor equality check prevents type confusion and ensures symmetry
+	// This means: {} ≠ [], {} ≠ new Map(), new ClassA() ≠ new ClassB()
+	// Security: prevents structural type confusion in equality checks
+	// Cache constructor for reuse in subsequent checks (avoids repeated property access)
+	const a_ctor = (a as any).constructor;
+	if (a_ctor !== (b as any).constructor) return false;
+
+	// Regular arrays: inline length check before function call (fast-fail for mismatched lengths)
+	// Use Array.isArray() instead of instanceof Array (JIT-optimized, works cross-realm)
+	if (Array.isArray(a)) {
+		const len = a.length;
+		if ((b as any).length !== len) return false;
+		for (let i = 0; i < len; i++) {
+			if (!deep_equal(a[i], (b as any)[i])) return false;
+		}
+		return true;
+	}
+
+	// Use cached constructor for type checks (faster than instanceof - avoids prototype chain walk)
+	if (a_ctor === Set) {
+		if ((a as Set<unknown>).size !== (b as Set<unknown>).size) return false;
+		for (const a_value of a as Set<unknown>) {
+			if (!(b as Set<unknown>).has(a_value)) return false;
+		}
+		return true;
+	}
+	if (a_ctor === Map) {
+		if ((a as Map<unknown, unknown>).size !== (b as Map<unknown, unknown>).size) return false;
+		for (const [key, a_value] of a as Map<unknown, unknown>) {
+			if (
+				!(b as Map<unknown, unknown>).has(key) ||
+				!deep_equal(a_value, (b as Map<unknown, unknown>).get(key))
+			)
+				return false;
+		}
+		return true;
+	}
+	if (a_ctor === RegExp) {
+		return (
+			(a as RegExp).source === (b as RegExp).source && (a as RegExp).flags === (b as RegExp).flags
+		);
+	}
+
+	// Date objects: compare by timestamp value
+	if (a_ctor === Date) {
+		// Using Object.is to handle NaN correctly (invalid dates)
+		return Object.is((a as Date).getTime(), (b as Date).getTime());
+	}
+
+	// ArrayBuffer: convert to Uint8Array views for byte-by-byte comparison
+	if (a_ctor === ArrayBuffer) {
+		if ((a as ArrayBuffer).byteLength !== (b as ArrayBuffer).byteLength) return false;
+		const a_view = new Uint8Array(a as ArrayBuffer);
+		const b_view = new Uint8Array(b as ArrayBuffer);
+		const len = (a as ArrayBuffer).byteLength;
+		for (let i = 0; i < len; i++) {
+			if (a_view[i] !== b_view[i]) return false;
+		}
+		return true;
+	}
+
+	// TypedArrays: specialized fast path (no recursion needed - elements are always primitives)
+	// ArrayBuffer.isView() catches TypedArrays (Uint8Array, Int32Array, Float64Array, etc.)
+	// DataView is also caught by isView but needs special handling (no indexed access)
+	if (ArrayBuffer.isView(a)) {
+		// DataView: compare byte-by-byte using getUint8
+		if (a_ctor === DataView) {
+			const byte_len = (a as DataView).byteLength;
+			if ((b as DataView).byteLength !== byte_len) return false;
+			for (let i = 0; i < byte_len; i++) {
+				if ((a as DataView).getUint8(i) !== (b as DataView).getUint8(i)) return false;
+			}
+			return true;
+		}
+		// TypedArrays: use indexed access (much faster)
+		if ((b as any).length !== (a as any).length) return false;
+		const len = (a as any).length;
+		for (let i = 0; i < len; i++) {
+			if ((a as any)[i] !== (b as any)[i]) return false;
+		}
+		return true;
+	}
+
+	// Boxed Number objects: compare by primitive value
+	if (a_ctor === Number) {
+		return Object.is(a!.valueOf(), (b as number).valueOf());
+	}
+
+	// Boxed Boolean objects: compare by primitive value
+	if (a_ctor === Boolean) {
+		return a!.valueOf() === (b as boolean).valueOf();
+	}
+
+	// Error objects: compare by message and name
+	if (a_ctor === Error) {
+		return (a as Error).message === (b as Error).message && (a as Error).name === (b as Error).name;
+	}
+
+	// Promise objects: cannot be meaningfully compared for deep equality
+	if (a_ctor === Promise) {
+		return false;
+	}
+
+	// Plain objects: compare enumerable own properties
+	const a_keys = Object.keys(a!);
+	const a_keys_length = a_keys.length;
+	if (a_keys_length !== Object.keys(b!).length) return false;
+	for (let i = 0; i < a_keys_length; i++) {
+		const key = a_keys[i]!;
+		if (!(key in (b as any))) return false;
+		if (!deep_equal((a as any)[key], (b as any)[key])) return false;
+	}
+
+	return true;
+};

package/src/lib/dom.ts

@@ -0,0 +1,108 @@
+/**
+ * Checks if the given element is editable.
+ * Returns `true` for text-based input types, textareas, and contenteditable elements.
+ */
+export const is_editable = (el: any): boolean => {
+	if (!el) return false;
+	const {tagName} = el;
+	return (
+		(tagName === 'INPUT' && el.type !== 'hidden') ||
+		tagName === 'TEXTAREA' ||
+		el.contentEditable === 'true' ||
+		el.contentEditable === '' // Some browsers treat empty string as `'true'`
+	);
+};
+
+/**
+ * Returns `true` if the element is within a `contenteditable` ancestor.
+ */
+export const inside_editable = (el: Element): boolean => {
+	const found = el.closest('[contenteditable]');
+	return found !== null && (found as any).contentEditable !== 'false';
+};
+
+/**
+ * Checks if the element is interactive (clickable, focusable, or otherwise accepts user input).
+ * Returns `true` for buttons, links, form controls,
+ * and elements with interactive attributes and ARIA roles.
+ */
+export const is_interactive = (el: any): boolean => {
+	if (!el) return false;
+
+	const {tagName} = el;
+	if (
+		tagName === 'BUTTON' ||
+		tagName === 'SELECT' ||
+		tagName === 'TEXTAREA' ||
+		tagName === 'A' ||
+		tagName === 'AUDIO' ||
+		tagName === 'VIDEO' ||
+		(tagName === 'INPUT' && el.type !== 'hidden')
+	) {
+		return true;
+	}
+
+	const role = el.getAttribute?.('role');
+	return (
+		(role &&
+			(role === 'button' ||
+				role === 'link' ||
+				role === 'menuitem' ||
+				role === 'option' ||
+				role === 'switch' ||
+				role === 'tab')) ||
+		(el.hasAttribute?.('tabindex') && el.getAttribute('tabindex') !== '-1') ||
+		el.contentEditable === 'true' ||
+		el.contentEditable === '' ||
+		el.getAttribute?.('draggable') === 'true'
+	);
+};
+
+/**
+ * Stops an event from bubbling and doing default behavior.
+ * @param event
+ * @param immediate defaults to `true` to use `stopImmediatePropagation` over `stopPropagation`
+ * @param preventDefault defaults to `true`
+ * @mutates event calls preventDefault(), stopPropagation(), or stopImmediatePropagation()
+ * @returns
+ */
+export const swallow = <
+	T extends Pick<Event, 'preventDefault' | 'stopPropagation' | 'stopImmediatePropagation'>,
+>(
+	event: T,
+	immediate = true,
+	preventDefault = true,
+): T => {
+	if (preventDefault) event.preventDefault();
+	if (immediate) {
+		event.stopImmediatePropagation();
+	} else {
+		event.stopPropagation();
+	}
+	return event;
+};
+
+// TODO improve these types, the motivation was the strictness of Svelte DOM types
+/**
+ * Handles the value of an event's target and invokes a callback.
+ * Defaults to swallowing the event to prevent default actions and propagation.
+ * @mutates event calls `swallow()` which mutates the event if `swallow_event` is true
+ */
+export const handle_target_value =
+	(cb: (value: any, event: any) => void, swallow_event = true) =>
+	(e: any): void => {
+		if (swallow_event) swallow(e);
+		cb(e.target.value, e);
+	};
+
+/**
+ * Returns a boolean indicating if the current browser window, if any, is iframed inside of another.
+ */
+export const is_iframed = (): boolean => {
+	if (typeof window === 'undefined') return false;
+	try {
+		return window.self !== window.top; // some browsers may throw here due to the same origin policy
+	} catch (_err) {
+		return false;
+	}
+};

package/src/lib/error.ts

@@ -0,0 +1,22 @@
+/**
+ * Error for asserting unreachable code paths in TypeScript.
+ * Useful for exhaustive matching.
+ */
+export class UnreachableError extends Error {
+	constructor(value: never, message = `Unreachable case: ${value}`, options?: ErrorOptions) {
+		super(message, options);
+	}
+}
+
+/**
+ * Beyond terseness, this is useful because `throw` is not an expression,
+ * and therefore can't be used in places like Svelte markup without a workaround,
+ * at least until this proposal is accepted and widely available:
+ * https://github.com/tc39/proposal-throw-expressions
+ */
+export const unreachable: (value: never, message?: string) => asserts value is never = (
+	value,
+	message,
+) => {
+	throw new UnreachableError(value, message);
+};