@fuzdev/fuz_util 0.50.1 → 0.52.0

package/src/lib/async.ts

@@ -13,7 +13,7 @@ export const is_promise = (value: unknown): value is Promise<unknown> =>
 	value != null && typeof (value as Promise<unknown>).then === 'function';
 
 /**
- * Creates a deferred object with a promise and its resolve/reject handlers.
+ * A deferred object with a promise and its resolve/reject handlers.
  */
 export interface Deferred<T> {
 	promise: Promise<T>;
@@ -22,7 +22,7 @@ export interface Deferred<T> {
 }
 
 /**
- * Creates a object with a `promise` and its `resolve`/`reject` handlers.
+ * Creates an object with a `promise` and its `resolve`/`reject` handlers.
  */
 export const create_deferred = <T>(): Deferred<T> => {
 	let resolve!: (value: T) => void;
@@ -35,72 +35,87 @@ export const create_deferred = <T>(): Deferred<T> => {
 };
 
 /**
- * Runs an async function on each item with controlled concurrency.
+ * Runs a 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 items items to process
  * @param concurrency maximum number of concurrent operations
+ * @param fn function to apply to each item
+ * @param signal optional `AbortSignal` to cancel processing
  *
  * @example
  * ```ts
  * await each_concurrent(
  *   file_paths,
- *   async (path) => { await unlink(path); },
  *   5, // max 5 concurrent deletions
+ *   async (path) => { await unlink(path); },
  * );
  * ```
  */
 export const each_concurrent = async <T>(
-	items: Array<T>,
-	fn: (item: T, index: number) => Promise<void>,
+	items: Iterable<T>,
 	concurrency: number,
+	fn: (item: T, index: number) => Promise<void> | void,
+	signal?: AbortSignal,
 ): Promise<void> => {
-	if (concurrency < 1) {
+	if (!(concurrency >= 1)) {
 		throw new Error('concurrency must be at least 1');
 	}
 
+	const iterator = items[Symbol.iterator]();
 	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
+		const cleanup = signal ? () => signal.removeEventListener('abort', on_abort) : undefined;
+
+		const done = (): void => {
+			cleanup?.();
+			resolve();
+		};
+
+		const fail = (error: unknown): void => {
 			if (rejected) return;
+			rejected = true;
+			cleanup?.();
+			reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
+		};
 
-			// Check if we're done
-			if (next_index >= items.length && active_count === 0) {
-				resolve();
-				return;
-			}
+		function on_abort(): void {
+			fail(signal!.reason);
+		}
+
+		if (signal?.aborted) {
+			fail(signal.reason);
+			return;
+		}
+		signal?.addEventListener('abort', on_abort);
+
+		const run_next = (): void => {
+			if (rejected) return;
 
 			// Spawn workers up to concurrency limit
-			while (active_count < concurrency && next_index < items.length) {
+			while (active_count < concurrency) {
+				const next = iterator.next();
+				if (next.done) {
+					if (active_count === 0) done();
+					return;
+				}
 				const index = next_index++;
-				const item = items[index]!;
+				const item = next.value;
 				active_count++;
 
-				fn(item, index)
+				new Promise<void>((r) => r(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
-					});
+					.catch(fail);
 			}
 		};
 
-		// Handle empty array
-		if (items.length === 0) {
-			resolve();
-			return;
-		}
-
 		run_next();
 	});
 };
@@ -108,72 +123,87 @@ export const each_concurrent = async <T>(
 /**
  * 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 items items to process
  * @param concurrency maximum number of concurrent operations
+ * @param fn function to apply to each item
+ * @param signal optional `AbortSignal` to cancel processing
  * @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
+ *   async (path) => readFile(path, 'utf8'),
  * );
  * ```
  */
 export const map_concurrent = async <T, R>(
-	items: Array<T>,
-	fn: (item: T, index: number) => Promise<R>,
+	items: Iterable<T>,
 	concurrency: number,
+	fn: (item: T, index: number) => Promise<R> | R,
+	signal?: AbortSignal,
 ): Promise<Array<R>> => {
-	if (concurrency < 1) {
+	if (!(concurrency >= 1)) {
 		throw new Error('concurrency must be at least 1');
 	}
 
-	const results: Array<R> = new Array(items.length);
+	const results: Array<R> = [];
+	const iterator = items[Symbol.iterator]();
 	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
+		const cleanup = signal ? () => signal.removeEventListener('abort', on_abort) : undefined;
+
+		const done = (): void => {
+			cleanup?.();
+			resolve(results);
+		};
+
+		const fail = (error: unknown): void => {
 			if (rejected) return;
+			rejected = true;
+			cleanup?.();
+			reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
+		};
 
-			// Check if we're done
-			if (next_index >= items.length && active_count === 0) {
-				resolve(results);
-				return;
-			}
+		function on_abort(): void {
+			fail(signal!.reason);
+		}
+
+		if (signal?.aborted) {
+			fail(signal.reason);
+			return;
+		}
+		signal?.addEventListener('abort', on_abort);
+
+		const run_next = (): void => {
+			if (rejected) return;
 
 			// Spawn workers up to concurrency limit
-			while (active_count < concurrency && next_index < items.length) {
+			while (active_count < concurrency) {
+				const next = iterator.next();
+				if (next.done) {
+					if (active_count === 0) done();
+					return;
+				}
 				const index = next_index++;
-				const item = items[index]!;
+				const item = next.value;
 				active_count++;
 
-				fn(item, index)
+				new Promise<R>((r) => r(fn(item, index)))
 					.then((result) => {
 						if (rejected) return;
 						results[index] = result;
 						active_count--;
 						run_next();
 					})
-					.catch((error) => {
-						if (rejected) return;
-						rejected = true;
-						reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
-					});
+					.catch(fail);
 			}
 		};
 
-		// Handle empty array
-		if (items.length === 0) {
-			resolve(results);
-			return;
-		}
-
 		run_next();
 	});
 };
@@ -182,14 +212,18 @@ export const map_concurrent = async <T, R>(
  * 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
+ * On abort, resolves with partial results: completed items keep their real settlements,
+ * in-flight and un-started items are settled as rejected with the abort reason.
+ *
+ * @param items items to process
  * @param concurrency maximum number of concurrent operations
+ * @param fn function to apply to each item
+ * @param signal optional `AbortSignal` to cancel processing
  * @returns promise resolving to array of `PromiseSettledResult` objects in input order
  *
  * @example
  * ```ts
- * const results = await map_concurrent_settled(urls, fetch, 5);
+ * const results = await map_concurrent_settled(urls, 5, fetch);
  * for (const [i, result] of results.entries()) {
  *   if (result.status === 'fulfilled') {
  *     console.log(`${urls[i]}: ${result.value.status}`);
@@ -200,52 +234,78 @@ export const map_concurrent = async <T, R>(
  * ```
  */
 export const map_concurrent_settled = async <T, R>(
-	items: Array<T>,
-	fn: (item: T, index: number) => Promise<R>,
+	items: Iterable<T>,
 	concurrency: number,
+	fn: (item: T, index: number) => Promise<R> | R,
+	signal?: AbortSignal,
 ): Promise<Array<PromiseSettledResult<R>>> => {
-	if (concurrency < 1) {
+	if (!(concurrency >= 1)) {
 		throw new Error('concurrency must be at least 1');
 	}
 
-	const results: Array<PromiseSettledResult<R>> = new Array(items.length);
+	const results: Array<PromiseSettledResult<R>> = [];
+	const iterator = items[Symbol.iterator]();
 	let next_index = 0;
 	let active_count = 0;
+	let aborted = false;
 
 	return new Promise((resolve) => {
-		const run_next = (): void => {
-			// Check if we're done
-			if (next_index >= items.length && active_count === 0) {
-				resolve(results);
-				return;
+		const cleanup = signal ? () => signal.removeEventListener('abort', on_abort) : undefined;
+
+		const done = (): void => {
+			cleanup?.();
+			resolve(results);
+		};
+
+		function on_abort(): void {
+			if (aborted) return;
+			aborted = true;
+			cleanup?.();
+			// Settle in-flight items as rejected with the abort reason
+			const reason: unknown = signal!.reason;
+			for (let i = 0; i < next_index; i++) {
+				if (!(i in results)) {
+					results[i] = {status: 'rejected', reason};
+				}
 			}
+			resolve(results);
+		}
+
+		if (signal?.aborted) {
+			resolve(results);
+			return;
+		}
+		signal?.addEventListener('abort', on_abort);
+
+		const run_next = (): void => {
+			if (aborted) return;
 
 			// Spawn workers up to concurrency limit
-			while (active_count < concurrency && next_index < items.length) {
+			while (active_count < concurrency) {
+				const next = iterator.next();
+				if (next.done) {
+					if (active_count === 0) done();
+					return;
+				}
 				const index = next_index++;
-				const item = items[index]!;
+				const item = next.value;
 				active_count++;
 
-				fn(item, index)
+				new Promise<R>((r) => r(fn(item, index)))
 					.then((value) => {
-						results[index] = {status: 'fulfilled', value};
+						if (!aborted) results[index] = {status: 'fulfilled', value};
 					})
 					.catch((reason: unknown) => {
-						results[index] = {status: 'rejected', reason};
+						if (!aborted) results[index] = {status: 'rejected', reason};
 					})
 					.finally(() => {
+						if (aborted) return;
 						active_count--;
 						run_next();
 					});
 			}
 		};
 
-		// Handle empty array
-		if (items.length === 0) {
-			resolve(results);
-			return;
-		}
-
 		run_next();
 	});
 };
@@ -260,13 +320,16 @@ export class AsyncSemaphore {
 	#waiters: Array<() => void> = [];
 
 	constructor(permits: number) {
+		if (!(permits >= 0)) {
+			throw new Error('permits must be >= 0');
+		}
 		this.#permits = permits;
 	}
 
-	async acquire(): Promise<void> {
+	acquire(): Promise<void> {
 		if (this.#permits > 0) {
 			this.#permits--;
-			return;
+			return Promise.resolve();
 		}
 		return new Promise<void>((resolve) => {
 			this.#waiters.push(resolve);

package/src/lib/path.ts

@@ -37,7 +37,10 @@ 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']
+ * @example
+ * ```ts
+ * 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);
@@ -53,7 +56,10 @@ export const parse_path_parts = (path: string): Array<string> => {
 
 /**
  * Gets the individual parts of a path, ignoring dots and separators.
- * @example parse_path_segments('/foo/bar/baz.ts') => ['foo', 'bar', 'baz.ts']
+ * @example
+ * ```ts
+ * 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 !== '..');

package/src/lib/process.ts

@@ -616,7 +616,10 @@ export const spawn_detached = (
 /**
  * Formats a child process for display.
  *
- * @example `pid(1234) <- node server.js`
+ * @example
+ * ```ts
+ * `pid(1234) <- node server.js`
+ * ```
  */
 export const print_child_process = (child: ChildProcess): string =>
 	`${st('gray', 'pid(')}${child.pid ?? 'none'}${st('gray', ')')} ← ${st('green', child.spawnargs.join(' '))}`;

package/src/lib/source_json.ts

@@ -72,6 +72,16 @@ export const ComponentPropInfo = z.looseObject({
 	description: z.string().optional(),
 	default_value: z.string().optional(),
 	bindable: z.boolean().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 raw TSDoc 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(),
 });
 export type ComponentPropInfo = z.infer<typeof ComponentPropInfo>;
 
@@ -110,6 +120,8 @@ export const DeclarationJson = z.looseObject({
 	throws: z.array(z.looseObject({type: z.string().optional(), description: z.string()})).optional(),
 	/** Version introduced, from `@since` tag. */
 	since: z.string().optional(),
+	/** Mutation documentation from `@mutates` tags (non-standard), mapping parameter names to descriptions. */
+	mutates: z.record(z.string(), z.string()).optional(),
 	/** Extended classes/interfaces. */
 	extends: z.array(z.string()).optional(),
 	/** Implemented interfaces. */
@@ -136,6 +148,7 @@ export const DeclarationJson = z.looseObject({
 		.object({
 			module: z.string(),
 			name: z.string(),
+			kind: DeclarationKind,
 		})
 		.optional(),
 });
@@ -174,8 +187,14 @@ 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'}]})
+ *
+ * @deprecated Use `getDisplayName` from `@fuzdev/svelte-docinfo/types.js` instead.
+ *
+ * @example
+ * ```ts
+ * 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;
@@ -190,8 +209,14 @@ export const declaration_get_display_name = (declaration: DeclarationJson): stri
 
 /**
  * Generate TypeScript import statement for a declaration.
- * @example declaration_generate_import({name: 'Foo', kind: 'type'}, 'foo.ts', '@pkg/lib')
+ *
+ * @deprecated Use `generateImport` from `@fuzdev/svelte-docinfo/types.js` instead.
+ *
+ * @example
+ * ```ts
+ * 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,