@fuzdev/fuz_util 0.45.2 → 0.46.0

package/dist/regexp.js

@@ -6,7 +6,7 @@ export const escape_regexp = (str) => 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
+ * @mutates regexp - sets lastIndex to 0 if regexp is global or sticky
  */
 export const reset_regexp = (regexp) => {
     if (regexp.global || regexp.sticky) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_util",
-  "version": "0.45.2",
+  "version": "0.46.0",
   "description": "utility belt for JS",
   "glyph": "🦕",
   "logo": "logo.svg",
@@ -61,16 +61,17 @@
   },
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
-    "@fuzdev/fuz_code": "^0.38.0",
-    "@fuzdev/fuz_css": "^0.43.0",
-    "@fuzdev/fuz_ui": "^0.177.0",
+    "@fuzdev/fuz_code": "^0.40.0",
+    "@fuzdev/fuz_css": "^0.44.1",
+    "@fuzdev/fuz_ui": "^0.179.0",
     "@ryanatkn/eslint-config": "^0.9.0",
-    "@ryanatkn/gro": "^0.184.0",
+    "@ryanatkn/gro": "^0.186.0",
     "@sveltejs/adapter-static": "^3.0.10",
     "@sveltejs/kit": "^2.49.1",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.1",
     "@types/node": "^24.10.1",
+    "@webref/css": "^8.2.0",
     "dequal": "^2.0.3",
     "eslint": "^9.39.1",
     "eslint-plugin-svelte": "^3.13.1",

package/src/lib/array.ts

@@ -9,7 +9,7 @@ export const to_array = <T>(value: T): T extends ReadonlyArray<any> ? T : Array<
 
 /**
  * Removes an element from `array` at `index` in an unordered manner.
- * @mutates array swaps element at index with last element, then removes last element
+ * @mutates array - swaps element at index with last element, then removes last element
  */
 export const remove_unordered = (array: Array<any>, index: number): void => {
 	array[index] = array[array.length - 1];

package/src/lib/async.ts

@@ -34,6 +34,77 @@ export const create_deferred = <T>(): Deferred<T> => {
 	return {promise, resolve, reject};
 };
 
+/**
+ * Runs an async function on each item with controlled concurrency.
+ * Like `map_concurrent` but doesn't collect results (more efficient for side effects).
+ *
+ * @param items array of items to process
+ * @param fn async function to apply to each item
+ * @param concurrency maximum number of concurrent operations
+ *
+ * @example
+ * ```ts
+ * await each_concurrent(
+ *   file_paths,
+ *   async (path) => { await unlink(path); },
+ *   5, // max 5 concurrent deletions
+ * );
+ * ```
+ */
+export const each_concurrent = async <T>(
+	items: Array<T>,
+	fn: (item: T, index: number) => Promise<void>,
+	concurrency: number,
+): Promise<void> => {
+	if (concurrency < 1) {
+		throw new Error('concurrency must be at least 1');
+	}
+
+	let next_index = 0;
+	let active_count = 0;
+	let rejected = false;
+
+	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();
+				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(() => {
+						if (rejected) return;
+						active_count--;
+						run_next();
+					})
+					.catch((error) => {
+						if (rejected) return;
+						rejected = true;
+						reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
+					});
+			}
+		};
+
+		// Handle empty array
+		if (items.length === 0) {
+			resolve();
+			return;
+		}
+
+		run_next();
+	});
+};
+
 /**
  * Maps over items with controlled concurrency, preserving input order.
  *
@@ -64,7 +135,6 @@ export const map_concurrent = async <T, R>(
 	let next_index = 0;
 	let active_count = 0;
 	let rejected = false;
-	let reject_error: unknown;
 
 	return new Promise((resolve, reject) => {
 		const run_next = (): void => {
@@ -93,8 +163,7 @@ export const map_concurrent = async <T, R>(
 					.catch((error) => {
 						if (rejected) return;
 						rejected = true;
-						reject_error = error;
-						reject(reject_error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
+						reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
 					});
 			}
 		};

package/src/lib/dom.ts

@@ -63,7 +63,7 @@ export const is_interactive = (el: any): boolean => {
  * @param event
  * @param immediate defaults to `true` to use `stopImmediatePropagation` over `stopPropagation`
  * @param preventDefault defaults to `true`
- * @mutates event calls preventDefault(), stopPropagation(), or stopImmediatePropagation()
+ * @mutates event - calls preventDefault(), stopPropagation(), or stopImmediatePropagation()
  * @returns
  */
 export const swallow = <
@@ -86,7 +86,7 @@ export const swallow = <
 /**
  * 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
+ * @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) =>

package/src/lib/fetch.ts

@@ -48,7 +48,7 @@ export interface FetchValueOptions<TValue, TParams = undefined> {
  * If the `value` is cached, only the cached safe subset of the `headers` are returned.
  * (currently just `etag` and `last-modified`)
  * Otherwise the full `res.headers` are included.
- * @mutates options.cache calls `cache.set()` to store fetched results if cache is provided
+ * @mutates options.cache - calls `cache.set()` to store fetched results if cache is provided
  */
 export const fetch_value = async <TValue = any, TParams = undefined>(
 	url: string | URL,

package/src/lib/git.ts

@@ -1,7 +1,7 @@
 import type {SpawnOptions} from 'node:child_process';
 import {z} from 'zod';
 
-import {spawn, spawn_out} from './process.js';
+import {spawn, spawn_out, spawn_result_to_message} from './process.js';
 import type {Flavored} from './types.js';
 import {to_file_path} from './path.js';
 import {fs_exists} from './fs.js';
@@ -65,11 +65,11 @@ export const git_remote_branch_exists = async (
 	);
 	if (result.ok) {
 		return true;
-	} else if (result.code === 2) {
+	} else if ('code' in result && result.code === 2) {
 		return false;
 	} else {
 		throw Error(
-			`git_remote_branch_exists failed for origin '${origin}' and branch '${final_branch}' with code ${result.code}`,
+			`git_remote_branch_exists failed for origin '${origin}' and branch '${final_branch}' with ${spawn_result_to_message(result)}`,
 		);
 	}
 };
@@ -235,7 +235,7 @@ export const git_fetch = async (
 	const result = await spawn('git', args, options);
 	if (!result.ok) {
 		throw Error(
-			`git_fetch failed for origin '${origin}' and branch '${branch}' with code ${result.code}`,
+			`git_fetch failed for origin '${origin}' and branch '${branch}' with ${spawn_result_to_message(result)}`,
 		);
 	}
 };
@@ -254,7 +254,9 @@ export const git_checkout = async (
 	}
 	const result = await spawn('git', ['checkout', branch], options);
 	if (!result.ok) {
-		throw Error(`git_checkout failed for branch '${branch}' with code ${result.code}`);
+		throw Error(
+			`git_checkout failed for branch '${branch}' with ${spawn_result_to_message(result)}`,
+		);
 	}
 	return current_branch;
 };
@@ -271,7 +273,7 @@ export const git_pull = async (
 	if (branch) args.push(branch);
 	const result = await spawn('git', args, options);
 	if (!result.ok) {
-		throw Error(`git_pull failed for branch '${branch}' with code ${result.code}`);
+		throw Error(`git_pull failed for branch '${branch}' with ${spawn_result_to_message(result)}`);
 	}
 };
 
@@ -289,7 +291,9 @@ export const git_push = async (
 	if (set_upstream) args.push('-u');
 	const result = await spawn('git', args, options);
 	if (!result.ok) {
-		throw Error(`git_push failed for branch '${final_branch}' with code ${result.code}`);
+		throw Error(
+			`git_push failed for branch '${final_branch}' with ${spawn_result_to_message(result)}`,
+		);
 	}
 };
 
@@ -311,7 +315,9 @@ export const git_push_to_create = async (
 	push_args.push(final_branch);
 	const result = await spawn('git', push_args, options);
 	if (!result.ok) {
-		throw Error(`git_push failed for branch '${final_branch}' with code ${result.code}`);
+		throw Error(
+			`git_push failed for branch '${final_branch}' with ${spawn_result_to_message(result)}`,
+		);
 	}
 };
 
@@ -324,7 +330,9 @@ export const git_delete_local_branch = async (
 ): Promise<void> => {
 	const result = await spawn('git', ['branch', '-D', branch], options);
 	if (!result.ok) {
-		throw Error(`git_delete_local_branch failed for branch '${branch}' with code ${result.code}`);
+		throw Error(
+			`git_delete_local_branch failed for branch '${branch}' with ${spawn_result_to_message(result)}`,
+		);
 	}
 };
 
@@ -338,7 +346,9 @@ export const git_delete_remote_branch = async (
 ): Promise<void> => {
 	const result = await spawn('git', ['push', origin, ':' + branch], options);
 	if (!result.ok) {
-		throw Error(`git_delete_remote_branch failed for branch '${branch}' with code ${result.code}`);
+		throw Error(
+			`git_delete_remote_branch failed for branch '${branch}' with ${spawn_result_to_message(result)}`,
+		);
 	}
 };
 

package/src/lib/path.ts

@@ -98,7 +98,7 @@ export const parse_path_pieces = (raw_path: string): Array<PathPiece> => {
  * 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
+ * @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();
@@ -123,7 +123,7 @@ 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
+ * @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;

package/src/lib/print.ts

@@ -7,7 +7,7 @@ export let st: typeof styleText = (_, v) => v;
 
 /**
  * Configures the module-level styling function for colored output.
- * @mutates st assigns the module-level `st` variable
+ * @mutates st - assigns the module-level `st` variable
  */
 export const configure_print_colors = (
 	s: typeof styleText | null | undefined,