@fuzdev/fuz_util 0.51.0 → 0.52.0

package/dist/async.d.ts

@@ -8,7 +8,7 @@ export declare const wait: (duration?: number) => Promise<void>;
  */
 export declare const is_promise: (value: unknown) => value is Promise<unknown>;
 /**
- * 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>;
@@ -16,57 +16,63 @@ export interface Deferred<T> {
     reject: (reason: any) => void;
 }
 /**
- * Creates a object with a `promise` and its `resolve`/`reject` handlers.
+ * Creates an object with a `promise` and its `resolve`/`reject` handlers.
  */
 export declare 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 declare const each_concurrent: <T>(items: Array<T>, fn: (item: T, index: number) => Promise<void>, concurrency: number) => Promise<void>;
+export declare const each_concurrent: <T>(items: Iterable<T>, concurrency: number, fn: (item: T, index: number) => Promise<void> | void, signal?: AbortSignal) => Promise<void>;
 /**
  * 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 declare const map_concurrent: <T, R>(items: Array<T>, fn: (item: T, index: number) => Promise<R>, concurrency: number) => Promise<Array<R>>;
+export declare const map_concurrent: <T, R>(items: Iterable<T>, concurrency: number, fn: (item: T, index: number) => Promise<R> | R, signal?: AbortSignal) => Promise<Array<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}`);
@@ -76,7 +82,7 @@ export declare const map_concurrent: <T, R>(items: Array<T>, fn: (item: T, index
  * }
  * ```
  */
-export declare const map_concurrent_settled: <T, R>(items: Array<T>, fn: (item: T, index: number) => Promise<R>, concurrency: number) => Promise<Array<PromiseSettledResult<R>>>;
+export declare const map_concurrent_settled: <T, R>(items: Iterable<T>, concurrency: number, fn: (item: T, index: number) => Promise<R> | R, signal?: AbortSignal) => Promise<Array<PromiseSettledResult<R>>>;
 /**
  * Async semaphore for concurrency limiting.
  *

package/dist/async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/async.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,IAAI,GAAI,iBAAY,KAAG,OAAO,CAAC,IAAI,CACQ,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,OAAO,CAAC,OAAO,CACI,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,MAAM,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,OAAK,QAAQ,CAAC,CAAC,CAQ/C,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,GAAU,CAAC,EACtC,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EAC7C,aAAa,MAAM,KACjB,OAAO,CAAC,IAAI,CAgDd,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,GAAU,CAAC,EAAE,CAAC,EACxC,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,aAAa,MAAM,KACjB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAkDlB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,sBAAsB,GAAU,CAAC,EAAE,CAAC,EAChD,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,aAAa,MAAM,KACjB,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CA6CxC,CAAC;AAEF;;;;GAIG;AACH,qBAAa,cAAc;;gBAId,OAAO,EAAE,MAAM;IAIrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B,OAAO,IAAI,IAAI;CAQf"}
+{"version":3,"file":"async.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/async.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,IAAI,GAAI,iBAAY,KAAG,OAAO,CAAC,IAAI,CACQ,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,OAAO,CAAC,OAAO,CACI,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,MAAM,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,OAAK,QAAQ,CAAC,CAAC,CAQ/C,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,GAAU,CAAC,EACtC,OAAO,QAAQ,CAAC,CAAC,CAAC,EAClB,aAAa,MAAM,EACnB,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EACpD,SAAS,WAAW,KAClB,OAAO,CAAC,IAAI,CA6Dd,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,GAAU,CAAC,EAAE,CAAC,EACxC,OAAO,QAAQ,CAAC,CAAC,CAAC,EAClB,aAAa,MAAM,EACnB,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAC9C,SAAS,WAAW,KAClB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CA+DlB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,sBAAsB,GAAU,CAAC,EAAE,CAAC,EAChD,OAAO,QAAQ,CAAC,CAAC,CAAC,EAClB,aAAa,MAAM,EACnB,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAC9C,SAAS,WAAW,KAClB,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAsExC,CAAC;AAEF;;;;GAIG;AACH,qBAAa,cAAc;;gBAId,OAAO,EAAE,MAAM;IAO3B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAUxB,OAAO,IAAI,IAAI;CAQf"}

package/dist/async.js

@@ -7,7 +7,7 @@ export const wait = (duration = 0) => new Promise((resolve) => setTimeout(resolv
  */
 export const is_promise = (value) => value != null && typeof value.then === 'function';
 /**
- * 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 = () => {
     let resolve;
@@ -19,108 +19,142 @@ export const create_deferred = () => {
     return { promise, resolve, reject };
 };
 /**
- * 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 (items, fn, concurrency) => {
-    if (concurrency < 1) {
+export const each_concurrent = async (items, concurrency, fn, signal) => {
+    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 = () => {
-            // Stop spawning if we've rejected
+        const cleanup = signal ? () => signal.removeEventListener('abort', on_abort) : undefined;
+        const done = () => {
+            cleanup?.();
+            resolve();
+        };
+        const fail = (error) => {
             if (rejected)
                 return;
-            // Check if we're done
-            if (next_index >= items.length && active_count === 0) {
-                resolve();
+            rejected = true;
+            cleanup?.();
+            reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
+        };
+        function on_abort() {
+            fail(signal.reason);
+        }
+        if (signal?.aborted) {
+            fail(signal.reason);
+            return;
+        }
+        signal?.addEventListener('abort', on_abort);
+        const run_next = () => {
+            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(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();
     });
 };
 /**
  * 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 (items, fn, concurrency) => {
-    if (concurrency < 1) {
+export const map_concurrent = async (items, concurrency, fn, signal) => {
+    if (!(concurrency >= 1)) {
         throw new Error('concurrency must be at least 1');
     }
-    const results = new Array(items.length);
+    const results = [];
+    const iterator = items[Symbol.iterator]();
     let next_index = 0;
     let active_count = 0;
     let rejected = false;
     return new Promise((resolve, reject) => {
-        const run_next = () => {
-            // Stop spawning if we've rejected
+        const cleanup = signal ? () => signal.removeEventListener('abort', on_abort) : undefined;
+        const done = () => {
+            cleanup?.();
+            resolve(results);
+        };
+        const fail = (error) => {
             if (rejected)
                 return;
-            // Check if we're done
-            if (next_index >= items.length && active_count === 0) {
-                resolve(results);
+            rejected = true;
+            cleanup?.();
+            reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
+        };
+        function on_abort() {
+            fail(signal.reason);
+        }
+        if (signal?.aborted) {
+            fail(signal.reason);
+            return;
+        }
+        signal?.addEventListener('abort', on_abort);
+        const run_next = () => {
+            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(fn(item, index)))
                     .then((result) => {
                     if (rejected)
                         return;
@@ -128,19 +162,9 @@ export const map_concurrent = async (items, fn, concurrency) => {
                     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();
     });
 };
@@ -148,14 +172,18 @@ export const map_concurrent = async (items, fn, concurrency) => {
  * 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}`);
@@ -165,43 +193,71 @@ export const map_concurrent = async (items, fn, concurrency) => {
  * }
  * ```
  */
-export const map_concurrent_settled = async (items, fn, concurrency) => {
-    if (concurrency < 1) {
+export const map_concurrent_settled = async (items, concurrency, fn, signal) => {
+    if (!(concurrency >= 1)) {
         throw new Error('concurrency must be at least 1');
     }
-    const results = new Array(items.length);
+    const results = [];
+    const iterator = items[Symbol.iterator]();
     let next_index = 0;
     let active_count = 0;
+    let aborted = false;
     return new Promise((resolve) => {
-        const run_next = () => {
-            // Check if we're done
-            if (next_index >= items.length && active_count === 0) {
-                resolve(results);
+        const cleanup = signal ? () => signal.removeEventListener('abort', on_abort) : undefined;
+        const done = () => {
+            cleanup?.();
+            resolve(results);
+        };
+        function on_abort() {
+            if (aborted)
                 return;
+            aborted = true;
+            cleanup?.();
+            // Settle in-flight items as rejected with the abort reason
+            const reason = 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 = () => {
+            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(fn(item, index)))
                     .then((value) => {
-                    results[index] = { status: 'fulfilled', value };
+                    if (!aborted)
+                        results[index] = { status: 'fulfilled', value };
                 })
                     .catch((reason) => {
-                    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();
     });
 };
@@ -214,12 +270,15 @@ export class AsyncSemaphore {
     #permits;
     #waiters = [];
     constructor(permits) {
+        if (!(permits >= 0)) {
+            throw new Error('permits must be >= 0');
+        }
         this.#permits = permits;
     }
-    async acquire() {
+    acquire() {
         if (this.#permits > 0) {
             this.#permits--;
-            return;
+            return Promise.resolve();
         }
         return new Promise((resolve) => {
             this.#waiters.push(resolve);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_util",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "utility belt for JS",
   "glyph": "🦕",
   "logo": "logo.svg",
@@ -69,10 +69,10 @@
   },
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
-    "@fuzdev/fuz_code": "^0.45.0",
-    "@fuzdev/fuz_css": "^0.50.0",
-    "@fuzdev/fuz_ui": "^0.183.1",
-    "@fuzdev/gro": "^0.192.1",
+    "@fuzdev/fuz_code": "^0.45.1",
+    "@fuzdev/fuz_css": "^0.52.0",
+    "@fuzdev/fuz_ui": "^0.184.0",
+    "@fuzdev/gro": "^0.194.0",
     "@jridgewell/trace-mapping": "^0.3.31",
     "@ryanatkn/eslint-config": "^0.9.0",
     "@sveltejs/adapter-static": "^3.0.10",

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);