@fuzdev/fuz_util 0.42.0

package/src/lib/package_json.ts

@@ -0,0 +1,135 @@
+import {z} from 'zod';
+
+import {count_graphemes} from './string.js';
+import {transform_empty_object_to_undefined} from './object.js';
+import {Url} from './url.js';
+
+export const PackageJsonRepository = z.union([
+	z.string(),
+	z.looseObject({
+		type: z.string(),
+		url: Url,
+		directory: z.string().optional(),
+	}),
+]);
+export type PackageJsonRepository = z.infer<typeof PackageJsonRepository>;
+
+export const PackageJsonAuthor = z.union([
+	z.string(),
+	z.looseObject({
+		name: z.string(),
+		email: z.email().optional(),
+		url: Url.optional(),
+	}),
+]);
+export type PackageJsonAuthor = z.infer<typeof PackageJsonAuthor>;
+
+export const PackageJsonFunding = z.union([
+	z.string(),
+	z.looseObject({
+		type: z.string(),
+		url: Url,
+	}),
+]);
+export type PackageJsonFunding = z.infer<typeof PackageJsonFunding>;
+
+// The base export value schema that can be a string, null, or nested conditions
+const export_value_schema: z.ZodType = z.lazy(() =>
+	z.union([
+		z.string(),
+		z.null(),
+		z.record(
+			z.string(),
+			z.lazy(() => export_value_schema),
+		),
+	]),
+);
+export const ExportValue = export_value_schema;
+export type ExportValue = z.infer<typeof ExportValue>;
+
+/**
+ * Package exports can be:
+ * 1. A string (shorthand for main export)
+ * 2. null (to block exports)
+ * 3. A record of export conditions/paths
+ */
+export const PackageJsonExports = z.union([
+	z.string(),
+	z.null(),
+	z.record(z.string(), export_value_schema),
+]);
+export type PackageJsonExports = z.infer<typeof PackageJsonExports>;
+
+/**
+ * @see https://docs.npmjs.com/cli/v10/configuring-npm/package-json
+ */
+export const PackageJson = z.looseObject({
+	// according to the npm docs, `name` and `version` are the only required properties
+	name: z.string(),
+	version: z.string(),
+	private: z
+		.boolean()
+		.meta({description: 'disallow publishing to the configured registry'})
+		.optional(),
+	public: z
+		.boolean()
+		.meta({
+			description:
+				'a Gro extension that enables publishing `.well-known/package.json` and `.well-known/src`',
+		})
+		.optional(),
+	description: z.string().optional(),
+	motto: z
+		.string()
+		.meta({description: "a Gro extension that's a short phrase that represents this project"})
+		.optional(),
+	glyph: z
+		.string()
+		.meta({
+			description: "a Gro extension that's a single unicode character that represents this project",
+		})
+		.refine((v) => count_graphemes(v) === 1, 'must be a single unicode character')
+		.optional(),
+	logo: z
+		.string()
+		.meta({
+			description:
+				"a Gro extension that's a link relative to the `homepage` to an image that represents this project",
+		})
+		.optional(),
+	logo_alt: z
+		.string()
+		.meta({description: "a Gro extension that's the alt text for the `logo`"})
+		.optional(),
+	license: z.string().optional(),
+	scripts: z.record(z.string(), z.string()).optional(),
+	homepage: Url.optional(),
+	author: z.union([z.string(), PackageJsonAuthor.optional()]),
+	repository: z.union([z.string(), Url, PackageJsonRepository]).optional(),
+	contributors: z.array(z.union([z.string(), PackageJsonAuthor])).optional(),
+	bugs: z
+		.union([z.string(), z.looseObject({url: Url.optional(), email: z.email().optional()})])
+		.optional(),
+	funding: z
+		.union([Url, PackageJsonFunding, z.array(z.union([Url, PackageJsonFunding]))])
+		.optional(),
+	keywords: z.array(z.string()).optional(),
+
+	type: z.string().optional(),
+	engines: z.record(z.string(), z.string()).optional(),
+	os: z.array(z.string()).optional(),
+	cpu: z.array(z.string()).optional(),
+
+	dependencies: z.record(z.string(), z.string()).optional(),
+	devDependencies: z.record(z.string(), z.string()).optional(),
+	peerDependencies: z.record(z.string(), z.string()).optional(),
+	peerDependenciesMeta: z.record(z.string(), z.looseObject({optional: z.boolean()})).optional(),
+	optionalDependencies: z.record(z.string(), z.string()).optional(),
+
+	bin: z.record(z.string(), z.string()).optional(),
+	sideEffects: z.array(z.string()).optional(),
+	files: z.array(z.string()).optional(),
+	main: z.string().optional(),
+	exports: PackageJsonExports.transform(transform_empty_object_to_undefined).optional(),
+});
+export type PackageJson = z.infer<typeof PackageJson>;

package/src/lib/path.ts

@@ -0,0 +1,137 @@
+import type {Flavored} from './types.js';
+
+/**
+ * An absolute path on the filesystem. Named "id" to be consistent with Rollup.
+ */
+export type PathId = Flavored<string, 'PathId'>;
+
+/**
+ * Basic information about a filesystem path.
+ */
+export interface PathInfo {
+	id: PathId;
+	is_directory: boolean;
+}
+
+/**
+ * A resolved path with both the original path string and its absolute id.
+ */
+export interface ResolvedPath extends PathInfo {
+	path: string;
+}
+
+/**
+ * A filter function for paths, can distinguish between files and directories.
+ */
+export type PathFilter = (path: string, is_directory: boolean) => boolean;
+
+/**
+ * A filter function for file paths only.
+ */
+export type FileFilter = (path: string) => boolean;
+
+/**
+ * Converts a URL to a file path string, or returns the string as-is.
+ */
+export const to_file_path = (path_or_url: string | URL): string =>
+	typeof path_or_url === 'string' ? path_or_url : decodeURIComponent(path_or_url.pathname);
+
+/**
+ * @example parse_path_parts('./foo/bar/baz.ts') => ['foo', 'foo/bar', 'foo/bar/baz.ts']
+ */
+export const parse_path_parts = (path: string): Array<string> => {
+	const segments = parse_path_segments(path);
+	let current_path = path.startsWith('/') ? '/' : '';
+	return segments.map((segment) => {
+		if (current_path && current_path !== '/') {
+			current_path += '/';
+		}
+		current_path += segment;
+		return current_path;
+	});
+};
+
+/**
+ * Gets the individual parts of a path, ignoring dots and separators.
+ * @example parse_path_segments('/foo/bar/baz.ts') => ['foo', 'bar', 'baz.ts']
+ */
+export const parse_path_segments = (path: string): Array<string> =>
+	path.split('/').filter((s) => s && s !== '.' && s !== '..');
+
+/**
+ * A piece of a parsed path, either a path segment or separator.
+ */
+export type PathPiece =
+	| {
+			type: 'piece';
+			path: PathId;
+			name: string;
+	  }
+	| {
+			type: 'separator';
+			path: PathId;
+	  };
+
+/**
+ * Treats all paths as absolute, so the first piece is always a `'/'` with type `'separator'`.
+ * @todo maybe rethink this API, it's a bit weird, but fits the usage in `ui/Breadcrumbs.svelte`
+ */
+export const parse_path_pieces = (raw_path: string): Array<PathPiece> => {
+	const pieces: Array<PathPiece> = [];
+	const path_segments = parse_path_segments(raw_path);
+	if (path_segments.length) {
+		pieces.push({type: 'separator', path: '/'});
+	}
+	let path = '';
+	for (let i = 0; i < path_segments.length; i++) {
+		const path_segment = path_segments[i]!;
+		path += '/' + path_segment;
+		pieces.push({type: 'piece', name: path_segment, path});
+		if (i !== path_segments.length - 1) {
+			pieces.push({type: 'separator', path});
+		}
+	}
+	return pieces;
+};
+
+/**
+ * Converts a string into a URL-compatible slug.
+ * @param str the string to convert
+ * @param map_special_characters if `true`, characters like `ñ` are converted to their ASCII equivalents, runs around 5x faster when disabled
+ * @mutates special_char_mappers calls `get_special_char_mappers()` which lazily initializes the module-level array if `map_special_characters` is true
+ */
+export const slugify = (str: string, map_special_characters = true): string => {
+	let s = str.toLowerCase();
+	if (map_special_characters) {
+		for (const mapper of get_special_char_mappers()) {
+			s = mapper(s);
+		}
+	}
+	return s
+		.replace(/[^\s\w-]/g, '')
+		.split(/[\s-]+/g) // collapse whitespace
+		.filter(Boolean)
+		.join('-'); // remove all `''`
+};
+
+/**
+ * @see https://stackoverflow.com/questions/1053902/how-to-convert-a-title-to-a-url-slug-in-jquery/5782563#5782563
+ */
+const special_char_from = 'áäâàãåÆþčçćďđéěëèêẽĕȇğíìîïıňñóöòôõøðřŕšşßťúůüùûýÿž';
+const special_char_to = 'aaaaaaabcccddeeeeeeeegiiiiinnooooooorrssstuuuuuyyz';
+let special_char_mappers: Array<(s: string) => string> | undefined;
+/**
+ * Lazily constructs `special_char_mappers` which
+ * converts special characters to their ASCII equivalents.
+ * @mutates special_char_mappers pushes mapper functions into module-level array on first call
+ */
+const get_special_char_mappers = (): Array<(s: string) => string> => {
+	if (special_char_mappers) return special_char_mappers;
+	special_char_mappers = [];
+	for (let i = 0, j = special_char_from.length; i < j; i++) {
+		special_char_mappers.push((s) =>
+			s.replaceAll(special_char_from.charAt(i), special_char_to.charAt(i)),
+		);
+	}
+	return special_char_mappers;
+};

package/src/lib/print.ts

@@ -0,0 +1,111 @@
+import type {styleText} from 'node:util';
+
+import type {Timings} from './timings.js';
+import type {Logger} from './log.js';
+
+export let st: typeof styleText = (_, v) => v;
+
+/**
+ * Configures the module-level styling function for colored output.
+ * @mutates st assigns the module-level `st` variable
+ */
+export const configure_print_colors = (
+	s: typeof styleText | null | undefined,
+): typeof styleText => {
+	st = s ?? ((_, v) => v);
+	return st;
+};
+
+/**
+ * Formats a key-value pair for printing.
+ */
+export const print_key_value = (key: string, value: string | number): string =>
+	st('gray', `${key}(`) + value + st('gray', ')');
+
+/**
+ * Formats a `number` of milliseconds for printing.
+ */
+export const print_ms = (ms: number, decimals?: number, separator?: string): string => {
+	const decimal_count = decimals ?? (ms >= 10 ? 0 : ms < 0.1 ? 2 : 1);
+	const rounded = ms.toFixed(decimal_count);
+	return st('white', print_number_with_separators(rounded, separator)) + st('gray', 'ms');
+};
+
+/**
+ * Formats a `number` with separators for improved readability.
+ */
+export const print_number_with_separators = (v: string, separator = ','): string => {
+	if (!separator) return v;
+	const decimal_index = v.indexOf('.');
+	const start_index = (decimal_index === -1 ? v.length : decimal_index) - 1;
+	let s = decimal_index === -1 ? '' : v.slice(start_index + 1);
+	let count = 0;
+	for (let i = start_index; i >= 0; i--) {
+		count++;
+		if (count > 3 && count % 3 === 1) s = separator + s;
+		s = v[i] + s;
+	}
+	return s;
+};
+
+/**
+ * Formats a `string` for printing.
+ */
+export const print_string = (value: string): string => st('green', `'${value}'`);
+
+/**
+ * Formats a `number` for printing.
+ */
+export const print_number = (value: number): string => st('cyan', value + '');
+
+/**
+ * Formats a `boolean` for printing.
+ */
+export const print_boolean = (value: boolean): string => st('yellow', value + '');
+
+/**
+ * Formats any value for printing.
+ */
+export const print_value = (value: unknown): string => {
+	if (Array.isArray(value)) {
+		return st('blue', '[') + value.map(print_value).join(st('blue', ', ')) + st('blue', ']');
+	}
+	switch (typeof value) {
+		case 'string':
+			return print_string(value);
+		case 'number':
+			return print_number(value);
+		case 'boolean':
+			return print_boolean(value);
+		case 'object':
+			return value === null ? st('blue', 'null') : st('magenta', JSON.stringify(value));
+		default:
+			return st('blue', value + '');
+	}
+};
+
+/**
+ * Formats an error for printing.
+ * Because throwing errors and rejecting promises isn't typesafe,
+ * don't assume the arg is an `Error` and try to return something useful.
+ */
+export const print_error = (err: Error): string =>
+	st(
+		'yellow',
+		err.stack ?? ((err.message && `Error: ${err.message}`) || `Unknown error: ${err as any}`),
+	);
+
+/**
+ * Formats a timing entry with `key` for printing.
+ */
+export const print_timing = (key: string | number, timing: number | undefined): string =>
+	`${timing === undefined ? '...' : print_ms(timing, undefined)} ${st('gray', '←')} ${st('gray', key + '')}`;
+
+/**
+ * Prints all timings in a `Timings` object.
+ */
+export const print_timings = (timings: Timings, log: Logger): void => {
+	for (const [key, timing] of timings.entries()) {
+		log.debug(print_timing(key, timing));
+	}
+};

package/src/lib/process.ts

@@ -0,0 +1,207 @@
+import {
+	spawn as spawn_child_process,
+	type SpawnOptions,
+	type ChildProcess,
+} from 'node:child_process';
+import {styleText as st} from 'node:util';
+
+import {Logger} from './log.js';
+import {print_error, print_key_value} from './print.js';
+import type {Result} from './result.js';
+
+const log = new Logger('process');
+
+export interface SpawnedProcess {
+	child: ChildProcess;
+	closed: Promise<SpawnResult>;
+}
+
+export interface Spawned {
+	child: ChildProcess;
+	signal: NodeJS.Signals | null;
+	code: number | null;
+}
+
+// TODO are `code` and `signal` more related than that?
+// e.g. should this be a union type where one is always `null`?
+export type SpawnResult = Result<Spawned, Spawned>;
+
+/**
+ * A convenient promise wrapper around `spawn_process`
+ * intended for commands that have an end, not long running-processes like watchers.
+ * Any more advanced usage should use `spawn_process` directly for access to the `child` process.
+ */
+export const spawn = (...args: Parameters<typeof spawn_process>): Promise<SpawnResult> =>
+	spawn_process(...args).closed;
+
+export interface SpawnedOut {
+	result: SpawnResult;
+	stdout: string | null;
+	stderr: string | null;
+}
+
+/**
+ * Similar to `spawn` but buffers and returns `stdout` and `stderr` as strings.
+ */
+export const spawn_out = async (
+	command: string,
+	args: ReadonlyArray<string> = [],
+	options?: SpawnOptions,
+): Promise<SpawnedOut> => {
+	const {child, closed} = spawn_process(command, args, {...options, stdio: 'pipe'});
+	let stdout: string | null = null;
+	child.stdout!.on('data', (data: Buffer) => {
+		stdout = (stdout ?? '') + data.toString();
+	});
+	let stderr: string | null = null;
+	child.stderr!.on('data', (data: Buffer) => {
+		stderr = (stderr ?? '') + data.toString();
+	});
+	const result = await closed;
+	return {result, stdout, stderr};
+};
+
+/**
+ * Wraps the normal Node `childProcess.spawn` with graceful child shutdown behavior.
+ * Also returns a convenient `closed` promise.
+ * If you only need `closed`, prefer the shorthand function `spawn`.
+ * @mutates global_spawn calls `register_global_spawn()` which adds to the module-level Set
+ */
+export const spawn_process = (
+	command: string,
+	args: ReadonlyArray<string> = [],
+	options?: SpawnOptions,
+): SpawnedProcess => {
+	let resolve: (v: SpawnResult) => void;
+	const closed: Promise<SpawnResult> = new Promise((r) => (resolve = r));
+	const child = spawn_child_process(command, args, {stdio: 'inherit', ...options});
+	const unregister = register_global_spawn(child);
+	child.once('close', (code, signal) => {
+		unregister();
+		resolve(code ? {ok: false, child, code, signal} : {ok: true, child, code, signal});
+	});
+	return {closed, child};
+};
+
+export const print_child_process = (child: ChildProcess): string =>
+	`${st('gray', 'pid(')}${child.pid}${st('gray', ')')} ← ${st('green', child.spawnargs.join(' '))}`;
+
+/**
+ * We register spawned processes gloabally so we can gracefully exit child processes.
+ * Otherwise, errors can cause zombie processes, sometimes blocking ports even!
+ */
+export const global_spawn: Set<ChildProcess> = new Set();
+
+/**
+ * Returns a function that unregisters the `child`.
+ * @param child the child process to register
+ * @returns cleanup function that removes the child from `global_spawn`
+ * @mutates global_spawn adds child to the module-level Set, and the returned function removes it
+ */
+export const register_global_spawn = (child: ChildProcess): (() => void) => {
+	if (global_spawn.has(child)) {
+		log.error(st('red', 'already registered global spawn:'), print_child_process(child));
+	}
+	global_spawn.add(child);
+	return () => {
+		if (!global_spawn.has(child)) {
+			log.error(st('red', 'spawn not registered:'), print_child_process(child));
+		}
+		global_spawn.delete(child);
+	};
+};
+
+/**
+ * Kills a child process and returns a `SpawnResult`.
+ */
+export const despawn = (child: ChildProcess): Promise<SpawnResult> => {
+	let resolve: (v: SpawnResult) => void;
+	const closed: Promise<SpawnResult> = new Promise((r) => (resolve = r));
+	log.debug('despawning', print_child_process(child));
+	child.once('close', (code, signal) => {
+		resolve(code ? {ok: false, child, code, signal} : {ok: true, child, code, signal});
+	});
+	child.kill();
+	return closed;
+};
+
+/**
+ * Kills all globally registered child processes.
+ * @mutates global_spawn indirectly removes processes through `despawn()` calls
+ */
+export const despawn_all = (): Promise<Array<SpawnResult>> =>
+	Promise.all(Array.from(global_spawn, (child) => despawn(child)));
+
+/**
+ * Attaches the `'uncoughtException'` event to despawn all processes,
+ * and enables custom error logging with `to_error_label`.
+ * @param to_error_label - Customize the error label or return `null` for the default `origin`.
+ * @param map_error_text - Customize the error text. Return `''` to silence, or `null` for the default `print_error(err)`.
+ */
+export const attach_process_error_handlers = (
+	to_error_label?: (err: Error, origin: NodeJS.UncaughtExceptionOrigin) => string | null,
+	map_error_text?: (err: Error, origin: NodeJS.UncaughtExceptionOrigin) => string | null,
+	handle_error: (err: Error, origin: NodeJS.UncaughtExceptionOrigin) => void = () =>
+		process.exit(1),
+): void => {
+	process.on('uncaughtException', async (err, origin): Promise<void> => {
+		const label = to_error_label?.(err, origin) ?? origin;
+		if (label) {
+			const error_text = map_error_text?.(err, origin) ?? print_error(err);
+			if (error_text) {
+				new Logger(label).error(error_text);
+			}
+		}
+		await despawn_all();
+		handle_error(err, origin);
+	});
+};
+
+/**
+ * Formats a `SpawnResult` for printing.
+ */
+export const print_spawn_result = (result: SpawnResult): string => {
+	if (result.ok) return 'ok';
+	let text = result.code === null ? '' : print_key_value('code', result.code);
+	if (result.signal !== null) text += (text ? ' ' : '') + print_key_value('signal', result.signal);
+	return text;
+};
+
+// TODO might want to expand this API for some use cases - assumes always running
+export interface RestartableProcess {
+	restart: () => void;
+	kill: () => Promise<void>;
+}
+
+/**
+ * Like `spawn_process` but with `restart` and `kill`,
+ * handling many concurrent `restart` calls gracefully.
+ */
+export const spawn_restartable_process = (
+	command: string,
+	args: ReadonlyArray<string> = [],
+	options?: SpawnOptions,
+): RestartableProcess => {
+	let spawned: SpawnedProcess | null = null;
+	let restarting: Promise<any> | null = null;
+	const close = async (): Promise<void> => {
+		if (!spawned) return;
+		restarting = spawned.closed;
+		spawned.child.kill();
+		spawned = null;
+		await restarting;
+		restarting = null;
+	};
+	const restart = async (): Promise<void> => {
+		if (restarting) return restarting;
+		if (spawned) await close();
+		spawned = spawn_process(command, args, {stdio: 'inherit', ...options});
+	};
+	const kill = async (): Promise<void> => {
+		if (restarting) await restarting;
+		await close();
+	};
+	// Start immediately -- it sychronously starts the process so there's no need to await.
+	void restart();
+	return {restart, kill};
+};

package/src/lib/random.ts

@@ -0,0 +1,48 @@
+import type {ArrayElement} from './types.js';
+
+/**
+ * Generates a random `number` between `min` and `max`.
+ */
+export const random_float = (min: number, max: number, random = Math.random): number =>
+	random() * (max - min) + min;
+
+/**
+ * Returns a random integer between `min` and `max` inclusive.
+ * Node's `randomInt` is similar but exclusive of the max value, and makes `min` optional -
+ * https://nodejs.org/docs/latest-v20.x/api/crypto.html#cryptorandomintmin-max-callback
+ */
+export const random_int = (min: number, max: number, random = Math.random): number =>
+	Math.floor(random() * (max - min + 1)) + min;
+
+/**
+ * Generates a random `boolean`.
+ */
+export const random_boolean = (random = Math.random): boolean => random() > 0.5;
+
+/**
+ * Selects a random item from an array.
+ */
+export const random_item = <T extends ReadonlyArray<any>>(
+	arr: T,
+	random = Math.random,
+): ArrayElement<T> => arr[random_int(0, arr.length - 1, random)];
+
+/**
+ * Mutates `array` with random ordering.
+ * @mutates array randomly reorders elements in place using Fisher-Yates shuffle
+ */
+export const shuffle: <T extends Array<any>>(array: T, random?: typeof random_int) => T = (
+	array,
+	random = random_int,
+) => {
+	const {length} = array;
+	const max = length - 1;
+	for (let i = 0; i < length; i++) {
+		const index = random(0, max);
+		if (i === index) continue;
+		const item = array[index];
+		array[index] = array[i];
+		array[i] = item;
+	}
+	return array;
+};