@develia/commons 0.4.23 → 0.4.25

package/src/debouncer.ts

@@ -0,0 +1,135 @@
+import {delay} from "./utilities.js";
+import {noop} from "./functions.js";
+
+/**
+ * Cancellable task. It must honour `signal`: pass it to fetch/SDKs and check
+ * `signal.aborted` before producing irreversible side effects.
+ */
+export type DebouncedTask = (signal: AbortSignal) => Promise<void>;
+
+/** Options accepted by {@link Debouncer}. */
+export interface DebouncerOptions {
+    /** Default wait, in milliseconds, before a task is executed. */
+    delayMs: number;
+    /** Called every time a task is scheduled, after any previous task has been cancelled. */
+    onSchedule?: () => void;
+    /** Called when the wait elapses and the task is about to run. */
+    onStart?: () => void;
+    /** Called when a task completes without throwing and without being cancelled. */
+    onSuccess?: () => void;
+    /** Called when a live task is cancelled, either by {@link Debouncer.cancel} or by being replaced. */
+    onCancel?: () => void;
+    /** Receives task errors. Cancellations never reach this callback. Defaults to `console.error`. */
+    onError?: (error: unknown) => void;
+    /** Called every time the debouncer goes from busy to idle. */
+    onIdle?: () => void;
+}
+
+/**
+ * Keeps at most one live task.
+ * Scheduling a new task cancels the previous one, whether it was still
+ * waiting or already running.
+ *
+ * @example
+ * ```ts
+ * const debouncer = new Debouncer({delayMs: 1500});
+ *
+ * debouncer.schedule(async (signal) => {
+ *     const reply = await callAI(messages, {signal});
+ *     if (signal.aborted) return;
+ *     await sendReply(reply);
+ * });
+ * ```
+ */
+export default class Debouncer {
+    #controller: AbortController | undefined;
+    readonly #delayMs: number;
+    readonly #onSchedule: () => void;
+    readonly #onStart: () => void;
+    readonly #onSuccess: () => void;
+    readonly #onCancel: () => void;
+    readonly #onError: (error: unknown) => void;
+    readonly #onIdle: () => void;
+
+    constructor(options: DebouncerOptions) {
+        assertValidDelay(options.delayMs);
+        this.#delayMs = options.delayMs;
+        this.#onSchedule = options.onSchedule ?? noop;
+        this.#onStart = options.onStart ?? noop;
+        this.#onSuccess = options.onSuccess ?? noop;
+        this.#onCancel = options.onCancel ?? noop;
+        this.#onError = options.onError ?? console.error;
+        this.#onIdle = options.onIdle ?? noop;
+    }
+
+    /** Whether a task is waiting or running. */
+    get isPending(): boolean {
+        return this.#controller !== undefined;
+    }
+
+    /**
+     * Schedule `task`, cancelling any previous task.
+     *
+     * @param task - The task to run once the delay elapses.
+     * @param delayMs - Wait for this task only. Defaults to the configured `delayMs`.
+     */
+    schedule(task: DebouncedTask, delayMs: number = this.#delayMs): void {
+        assertValidDelay(delayMs);
+        if (this.#controller !== undefined) {
+            this.#controller.abort();
+            this.#onCancel();
+        }
+
+        const controller = new AbortController();
+        this.#controller = controller;
+        this.#onSchedule();
+        void this.#run(task, delayMs, controller);
+    }
+
+    /** Cancel the current task, if any. */
+    cancel(): void {
+        if (this.#controller === undefined) {
+            return;
+        }
+        this.#controller.abort();
+        this.#onCancel();
+        this.#becomeIdle();
+    }
+
+    async #run(task: DebouncedTask, delayMs: number, controller: AbortController): Promise<void> {
+        const signal = controller.signal;
+        try {
+            await delay(delayMs, signal);
+            this.#onStart();
+            await task(signal);
+            if (!signal.aborted) {
+                this.#onSuccess();
+            }
+        } catch (error) {
+            if (!signal.aborted) {
+                this.#onError(error);
+            }
+        } finally {
+            // A replaced or cancelled task must not touch the current state.
+            if (this.#controller === controller) {
+                this.#becomeIdle();
+            }
+        }
+    }
+
+    #becomeIdle(): void {
+        this.#controller = undefined;
+        this.#onIdle();
+    }
+}
+
+/**
+ * Throw a `RangeError` unless `delayMs` is a finite number >= 0.
+ *
+ * @internal Shared with `KeyedDebouncer`; not part of the public API.
+ */
+export function assertValidDelay(delayMs: number): void {
+    if (!Number.isFinite(delayMs) || delayMs < 0) {
+        throw new RangeError(`delayMs must be a number >= 0 (received: ${delayMs})`);
+    }
+}

package/src/functions.ts

@@ -1,14 +1,6 @@
 type AnyFunction = (this: any, ...args: any[]) => any;
 type TimerHandle = ReturnType<typeof setTimeout>;
 
-/** Options that control when a debounced function is executed. */
-export interface DebounceOptions {
-    /** Execute on the first call in a debounce window. Defaults to false. */
-    leading?: boolean;
-    /** Execute after the debounce window using the latest arguments. Defaults to true. */
-    trailing?: boolean;
-}
-
 /** Options that control when a throttled function is executed. */
 export interface ThrottleOptions {
     /** Execute immediately on the first call in a throttle window. Defaults to true. */
@@ -18,15 +10,15 @@ export interface ThrottleOptions {
 }
 
 /**
- * A delayed function returned by {@link debounce} or {@link throttle}.
+ * A delayed function returned by {@link throttle}.
  *
  * @example
  * ```ts
- * const saveLater = debounce(save, 250);
- * saveLater();
+ * const refresh = throttle(loadData, 250);
+ * refresh();
  *
- * if (saveLater.pending()) {
- *     saveLater.flush();
+ * if (refresh.pending()) {
+ *     refresh.flush();
  * }
  * ```
  */
@@ -199,107 +191,6 @@ export function memoize<F extends AnyFunction, K = Parameters<F>[0]>(
     return memoized;
 }
 
-/**
- * Delay a function until no calls have been made for the configured wait time.
- * The latest arguments and this-context are used for the trailing execution.
- *
- * @example
- * ```ts
- * const search = debounce((query: string) => {
- *     console.log(query);
- * }, 300);
- *
- * search("com");
- * search("commons"); // only this value is printed after 300 ms
- * ```
- *
- * @example
- * ```ts
- * const track = debounce(sendAnalytics, 1000, {leading: true, trailing: false});
- *
- * track("open"); // executed immediately
- * track.cancel(); // cancel the pending debounce window
- * ```
- */
-export function debounce<F extends AnyFunction>(
-    fn: F,
-    wait: number,
-    options: DebounceOptions = {}
-): DeferredFunction<F> {
-    const delay = normalizeDelay(wait);
-    const leading = options.leading ?? false;
-    const trailing = options.trailing ?? true;
-
-    let timer: TimerHandle | undefined;
-    let lastArgs: Parameters<F> | undefined;
-    let lastThis: ThisParameterType<F> | undefined;
-    let result: ReturnType<F> | undefined;
-
-    const invoke = (): ReturnType<F> => {
-        const args = lastArgs!;
-        const context = lastThis!;
-        lastArgs = undefined;
-        lastThis = undefined;
-        result = fn.apply(context, args);
-        return result as ReturnType<F>;
-    };
-
-    const expire = (): void => {
-        timer = undefined;
-        if (trailing && lastArgs) {
-            invoke();
-        } else {
-            lastArgs = undefined;
-            lastThis = undefined;
-        }
-    };
-
-    const start = (): void => {
-        timer = setTimeout(expire, delay);
-    };
-
-    const debounced = function (this: ThisParameterType<F>, ...args: Parameters<F>): ReturnType<F> | undefined {
-        const invokeLeading = leading && timer === undefined;
-        lastArgs = args;
-        lastThis = this;
-
-        if (timer !== undefined) {
-            clearTimeout(timer);
-        }
-        start();
-
-        if (invokeLeading) {
-            return invoke();
-        }
-
-        return result;
-    } as DeferredFunction<F>;
-
-    debounced.cancel = (): void => {
-        if (timer !== undefined) {
-            clearTimeout(timer);
-        }
-        timer = undefined;
-        lastArgs = undefined;
-        lastThis = undefined;
-    };
-
-    debounced.flush = (): ReturnType<F> | undefined => {
-        if (timer !== undefined) {
-            clearTimeout(timer);
-            timer = undefined;
-            if (lastArgs && trailing) {
-                return invoke();
-            }
-        }
-        return result;
-    };
-
-    debounced.pending = (): boolean => timer !== undefined;
-
-    return debounced;
-}
-
 /**
  * Limit how often a function can run during a time window.
  * Calls made while the function is throttled can optionally be replayed once at the end with the latest arguments.

package/src/index.ts

@@ -24,6 +24,10 @@ export {default as Stopwatch} from './stopwatch.js';
 export type {Result} from './result.js';
 export {TimeTrigger, CountTrigger} from './triggers.js';
 export {default as AsyncPoolExecutor} from './async-pool-executor.js';
+export {default as Debouncer} from './debouncer.js';
+export type {DebouncedTask, DebouncerOptions} from './debouncer.js';
+export {default as KeyedDebouncer} from './keyed-debouncer.js';
+export type {KeyedDebouncerOptions} from './keyed-debouncer.js';
 
 // ─── Patterns ────────────────────────────────────────
 export {default as Lazy} from './lazy.js';

package/src/keyed-debouncer.ts

@@ -0,0 +1,121 @@
+import Debouncer, {assertValidDelay, type DebouncedTask} from "./debouncer.js";
+import {noop} from "./functions.js";
+
+/** Options accepted by {@link KeyedDebouncer}. Every callback receives the affected key. */
+export interface KeyedDebouncerOptions<K> {
+    /** Default wait, in milliseconds, before a task is executed. */
+    delayMs: number;
+    /** Called every time a task is scheduled for `key`, after any previous task of that key has been cancelled. */
+    onSchedule?: (key: K) => void;
+    /** Called when the wait elapses and the task of `key` is about to run. */
+    onStart?: (key: K) => void;
+    /** Called when the task of `key` completes without throwing and without being cancelled. */
+    onSuccess?: (key: K) => void;
+    /** Called when a live task of `key` is cancelled, either explicitly or by being replaced. */
+    onCancel?: (key: K) => void;
+    /** Receives task errors. Cancellations never reach this callback. Defaults to `console.error`. */
+    onError?: (error: unknown, key: K) => void;
+    /** Called when `key` has no more pending work, after it has been removed from the debouncer. */
+    onIdle?: (key: K) => void;
+}
+
+/**
+ * An independent {@link Debouncer} per key.
+ * Debouncers only exist for keys with pending work: each one is created when
+ * its first task is scheduled and removed as soon as it becomes idle.
+ *
+ * @example
+ * ```ts
+ * const debouncer = new KeyedDebouncer<string>({delayMs: 1500});
+ *
+ * debouncer.schedule(chatId, async (signal) => {
+ *     const pending = await store.getPending(chatId);
+ *     const reply = await callAI(pending, {signal});
+ *     if (signal.aborted) return;
+ *     await sendReply(chatId, reply);
+ * });
+ * ```
+ */
+export default class KeyedDebouncer<K = string> {
+    readonly #debouncers = new Map<K, Debouncer>();
+    readonly #delayMs: number;
+    readonly #onSchedule: (key: K) => void;
+    readonly #onStart: (key: K) => void;
+    readonly #onSuccess: (key: K) => void;
+    readonly #onCancel: (key: K) => void;
+    readonly #onError: (error: unknown, key: K) => void;
+    readonly #onIdle: (key: K) => void;
+
+    constructor(options: KeyedDebouncerOptions<K>) {
+        assertValidDelay(options.delayMs);
+        this.#delayMs = options.delayMs;
+        this.#onSchedule = options.onSchedule ?? noop;
+        this.#onStart = options.onStart ?? noop;
+        this.#onSuccess = options.onSuccess ?? noop;
+        this.#onCancel = options.onCancel ?? noop;
+        this.#onError = options.onError ?? console.error;
+        this.#onIdle = options.onIdle ?? noop;
+    }
+
+    /** Number of keys with a task waiting or running. */
+    get size(): number {
+        return this.#debouncers.size;
+    }
+
+    /**
+     * Schedule `task` for `key`, cancelling any previous task of that key.
+     *
+     * @param key - The key whose task is replaced.
+     * @param task - The task to run once the delay elapses.
+     * @param delayMs - Wait for this task only. Defaults to the configured `delayMs`.
+     */
+    schedule(key: K, task: DebouncedTask, delayMs?: number): void {
+        const existing = this.#debouncers.get(key);
+        if (existing !== undefined) {
+            existing.schedule(task, delayMs);
+            return;
+        }
+
+        // Validate first so an invalid delay never registers the key.
+        assertValidDelay(delayMs ?? this.#delayMs);
+        const debouncer = this.#create(key);
+        this.#debouncers.set(key, debouncer);
+        debouncer.schedule(task, delayMs);
+    }
+
+    /** Cancel the task of `key`, if any. */
+    cancel(key: K): void {
+        this.#debouncers.get(key)?.cancel();
+    }
+
+    /** Cancel every task. Useful when shutting the process down. */
+    cancelAll(): void {
+        // Copy first: cancelling removes the debouncer from the map.
+        for (const debouncer of [...this.#debouncers.values()]) {
+            debouncer.cancel();
+        }
+    }
+
+    /** Whether a task is waiting or running for `key`. */
+    isPending(key: K): boolean {
+        return this.#debouncers.has(key);
+    }
+
+    #create(key: K): Debouncer {
+        const debouncer: Debouncer = new Debouncer({
+            delayMs: this.#delayMs,
+            onSchedule: () => this.#onSchedule(key),
+            onStart: () => this.#onStart(key),
+            onSuccess: () => this.#onSuccess(key),
+            onCancel: () => this.#onCancel(key),
+            onError: (error) => this.#onError(error, key),
+            onIdle: () => {
+                if (this.#debouncers.get(key) === debouncer) {
+                    this.#debouncers.delete(key);
+                    this.#onIdle(key);
+                }
+            },
+        });
+        return debouncer;
+    }
+}

package/src/utilities.ts

@@ -357,11 +357,37 @@ export function shallowEqual(a: any, b: any): boolean {
 /**
  * Pauses the execution of an asynchronous function for a specified duration.
  *
- * @param {number} ms - The delay duration in milliseconds.
- * @return {Promise<void>} A promise that resolves after the specified delay.
+ * When `signal` is provided, the returned promise rejects with `signal.reason`
+ * as soon as the signal is aborted (or immediately if it is already aborted),
+ * and the pending timer is cleared.
+ *
+ * @param ms - The delay duration in milliseconds.
+ * @param signal - Optional signal that cancels the wait.
+ * @return A promise that resolves after the specified delay.
  */
-export async function delay(ms: number): Promise<void> {
-    await new Promise(resolve => setTimeout(resolve, ms));
+export function delay(ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+        if (signal === undefined) {
+            setTimeout(resolve, ms);
+            return;
+        }
+
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+
+        const onAbort = (): void => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+
+        signal.addEventListener("abort", onAbort, {once: true});
+    });
 }
 
 /**

package/dist/cjs/array.js

@@ -1,106 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.pull = pull;
-exports.chunk = chunk;
-exports.clear = clear;
-exports.remove = remove;
-exports.pushIfAbsent = pushIfAbsent;
-exports.patchArray = patchArray;
-const utilities_js_1 = require("./utilities.js");
-/**
- * Removes all given values from the provided array and returns the number of removed elements.
- * The operation mutates the original array.
- * @template T
- * @param {Array<T>} array - The array to modify by removing specified items.
- * @param {...T} items - The values to remove from the array.
- * @return {number} The number of elements removed from the array.
- */
-function pull(array, ...items) {
-    let output = 0;
-    for (const item of items) {
-        let index;
-        while ((index = array.findIndex(val => Object.is(val, item))) !== -1) {
-            array.splice(index, 1);
-            output++;
-        }
-    }
-    return output;
-}
-/**
- * Splits an array into chunks of a given size.
- * @template T
- * @param {Array<T>} array - The array to split.
- * @param {number} size - The size of each chunk.
- * @return {Array<Array<T>>} The array of chunks.
- */
-function chunk(array, size) {
-    if (size <= 0)
-        throw new Error("Size must be greater than 0");
-    const result = [];
-    for (let i = 0; i < array.length; i += size) {
-        result.push(array.slice(i, i + size));
-    }
-    return result;
-}
-/**
- * Removes all elements from the array, mutating it.
- * @template T
- * @param {Array<T>} array - The array to clear.
- */
-function clear(array) {
-    array.length = 0;
-}
-/**
- * Removes all elements from the array that satisfy the predicate.
- * The operation mutates the original array.
- * @template T
- * @return {Array<T>} An array of removed elements.
- */
-function remove(array, predicate) {
-    const removed = [];
-    let i = 0;
-    while (i < array.length) {
-        if (predicate(array[i])) {
-            removed.push(array[i]);
-            array.splice(i, 1); // muta el array
-        }
-        else {
-            i++;
-        }
-    }
-    return removed;
-}
-/**
- * Adds an element to the array if it's not already present.
- * The operation mutates the original array.
- * @template T
- * @param {Array<T>} array - The array to modify.
- * @param {T} element - The element to add if absent.
- * @return {boolean} True if the element was added, false otherwise.
- */
-function pushIfAbsent(array, element) {
-    if (!array.includes(element)) {
-        array.push(element);
-        return true;
-    }
-    return false;
-}
-/**
- * Patches the Array prototype with the methods defined in this module:
- * - pull
- * - chunk
- * - clear
- * - remove
- * - pushIfAbsent
- *
- * Each method is added only if it doesn't already exist on Array.prototype.
- */
-function patchArray() {
-    const target = Array;
-    (0, utilities_js_1.monkeyPatch)(target, pull);
-    (0, utilities_js_1.monkeyPatch)(target, chunk);
-    (0, utilities_js_1.monkeyPatch)(target, clear);
-    (0, utilities_js_1.monkeyPatch)(target, remove);
-    (0, utilities_js_1.monkeyPatch)(target, pushIfAbsent);
-}
-//# sourceMappingURL=array.js.map

package/dist/cjs/array.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"array.js","sourceRoot":"","sources":["../../src/array.ts"],"names":[],"mappings":";;AAsBA,oBAWC;AASD,sBAOC;AAOD,sBAEC;AAQD,wBAcC;AAUD,oCAMC;AAYD,gCAQC;AAnHD,iDAA2C;AAa3C;;;;;;;GAOG;AACH,SAAgB,IAAI,CAAI,KAAe,EAAE,GAAG,KAAe;IAEvD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,KAAK,CAAC;QACV,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YACnE,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACvB,MAAM,EAAE,CAAC;QACb,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,KAAK,CAAI,KAAe,EAAE,IAAY;IAClD,IAAI,IAAI,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;QAC1C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,SAAgB,KAAK,CAAI,KAAe;IACpC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,MAAM,CAAI,KAAe,EAAC,SAAuB;IAC7D,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,CAAC,GAAG,CAAC,CAAC;IAEV,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QACtB,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACvB,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,gBAAgB;QACxC,CAAC;aAAM,CAAC;YACJ,CAAC,EAAE,CAAC;QACR,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,YAAY,CAAI,KAAe,EAAE,OAAU;IACvD,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,UAAU;IACtB,MAAM,MAAM,GAAG,KAA2C,CAAC;IAE3D,IAAA,0BAAW,EAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC1B,IAAA,0BAAW,EAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC3B,IAAA,0BAAW,EAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC3B,IAAA,0BAAW,EAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,IAAA,0BAAW,EAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AACtC,CAAC","sourcesContent":["import type {Constructor, Predicate} from \"./types.js\";\nimport {monkeyPatch} from \"./utilities.js\";\n\ndeclare global {\n    interface Array<T> {\n        pull(...items: Array<T>): number;\n        chunk(size: number): Array<Array<T>>;\n        clear(): void;\n        remove(predicate: Predicate<T>): Array<T>;\n        pushIfAbsent(element: T): boolean;\n    }\n}\n\n\n/**\n * Removes all given values from the provided array and returns the number of removed elements.\n * The operation mutates the original array.\n * @template T\n * @param {Array<T>} array - The array to modify by removing specified items.\n * @param {...T} items - The values to remove from the array.\n * @return {number} The number of elements removed from the array.\n */\nexport function pull<T>(array: Array<T>, ...items: Array<T>): number {\n\n    let output = 0;\n    for (const item of items) {\n        let index;\n        while ((index = array.findIndex(val => Object.is(val, item))) !== -1) {\n            array.splice(index, 1);\n            output++;\n        }\n    }\n    return output;\n}\n\n/**\n * Splits an array into chunks of a given size.\n * @template T\n * @param {Array<T>} array - The array to split.\n * @param {number} size - The size of each chunk.\n * @return {Array<Array<T>>} The array of chunks.\n */\nexport function chunk<T>(array: Array<T>, size: number): Array<Array<T>> {\n    if (size <= 0) throw new Error(\"Size must be greater than 0\");\n    const result: Array<Array<T>> = [];\n    for (let i = 0; i < array.length; i += size) {\n        result.push(array.slice(i, i + size));\n    }\n    return result;\n}\n\n/**\n * Removes all elements from the array, mutating it.\n * @template T\n * @param {Array<T>} array - The array to clear.\n */\nexport function clear<T>(array: Array<T>): void {\n    array.length = 0;\n}\n\n/**\n * Removes all elements from the array that satisfy the predicate.\n * The operation mutates the original array.\n * @template T\n * @return {Array<T>} An array of removed elements.\n */\nexport function remove<T>(array: Array<T>,predicate: Predicate<T>): Array<T> {\n    const removed: Array<T> = [];\n    let i = 0;\n\n    while (i < array.length) {\n        if (predicate(array[i])) {\n            removed.push(array[i]);\n            array.splice(i, 1); // muta el array\n        } else {\n            i++;\n        }\n    }\n\n    return removed;\n}\n\n/**\n * Adds an element to the array if it's not already present.\n * The operation mutates the original array.\n * @template T\n * @param {Array<T>} array - The array to modify.\n * @param {T} element - The element to add if absent.\n * @return {boolean} True if the element was added, false otherwise.\n */\nexport function pushIfAbsent<T>(array: Array<T>, element: T): boolean {\n    if (!array.includes(element)) {\n        array.push(element);\n        return true;\n    }\n    return false;\n}\n\n/**\n * Patches the Array prototype with the methods defined in this module:\n * - pull\n * - chunk\n * - clear\n * - remove\n * - pushIfAbsent\n *\n * Each method is added only if it doesn't already exist on Array.prototype.\n */\nexport function patchArray(): void {\n    const target = Array as unknown as Constructor<Array<any>>;\n\n    monkeyPatch(target, pull);\n    monkeyPatch(target, chunk);\n    monkeyPatch(target, clear);\n    monkeyPatch(target, remove);\n    monkeyPatch(target, pushIfAbsent);\n}"]}

package/dist/cjs/async-pool-executor.js

@@ -1,79 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const utilities_js_1 = require("./utilities.js");
-function normalizeMaxConcurrency(value) {
-    if (!Number.isInteger(value) || value < 1) {
-        throw new RangeError("maxConcurrency must be a positive integer");
-    }
-    return value;
-}
-function normalizeCheckInterval(value) {
-    return Number.isFinite(value) ? Math.max(0, value) : 0;
-}
-class AsyncPoolExecutor {
-    get maxConcurrency() {
-        return this._maxConcurrency;
-    }
-    set maxConcurrency(value) {
-        this._maxConcurrency = normalizeMaxConcurrency(value);
-    }
-    /**
-     * @param {number} maxConcurrency - The maximum number of concurrent tasks allowed.
-     * @param {number} [checkInterval=50] - The interval, in milliseconds, to check for capacity to run new tasks. Defaults to 50 ms.
-     */
-    constructor(maxConcurrency, checkInterval = 50) {
-        this._taskQueue = [];
-        this._maxConcurrency = normalizeMaxConcurrency(maxConcurrency);
-        this._checkIntervalMs = normalizeCheckInterval(checkInterval);
-        this._activeTasks = 0;
-    }
-    /**
-     * Submits a deferred task to a queue for asynchronous execution and returns a Promise resolving to its result.
-     * @template T
-     * @param {Supplier<T>} task - The deferred task to be executed asynchronously.
-     */
-    submit(task) {
-        const promise = new Promise((resolve, reject) => {
-            this._taskQueue.push({ task, resolve, reject });
-        });
-        if (this._process != null)
-            return promise;
-        this._process = setTimeout(async () => {
-            while (this._taskQueue.length > 0) {
-                while (this._activeTasks >= this._maxConcurrency) {
-                    await (0, utilities_js_1.delay)(this._checkIntervalMs);
-                }
-                const queuedTask = this._taskQueue.shift();
-                if (queuedTask) {
-                    this._activeTasks++;
-                    setTimeout(async () => {
-                        try {
-                            queuedTask.resolve(await queuedTask.task());
-                        }
-                        catch (error) {
-                            queuedTask.reject(error);
-                        }
-                        finally {
-                            this._activeTasks--;
-                        }
-                    });
-                }
-            }
-            this._process = null;
-        }, 0);
-        return promise;
-    }
-    /**
-     * Waits until all tasks (both queued and active) are completed.
-     * This method resolves only when there are no pending tasks.
-     *
-     * @return {Promise<void>} A promise that resolves when all tasks are complete.
-     */
-    async shutdown() {
-        while (this._taskQueue.length > 0 || this._activeTasks > 0) {
-            await (0, utilities_js_1.delay)(this._checkIntervalMs);
-        }
-    }
-}
-exports.default = AsyncPoolExecutor;
-//# sourceMappingURL=async-pool-executor.js.map

package/dist/cjs/async-pool-executor.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"async-pool-executor.js","sourceRoot":"","sources":["../../src/async-pool-executor.ts"],"names":[],"mappings":";;AACA,iDAAqC;AAQrC,SAAS,uBAAuB,CAAC,KAAa;IAC1C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,UAAU,CAAC,2CAA2C,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED,SAAS,sBAAsB,CAAC,KAAa;IACzC,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,MAAqB,iBAAiB;IAGlC,IAAI,cAAc;QACd,OAAO,IAAI,CAAC,eAAe,CAAC;IAChC,CAAC;IAED,IAAI,cAAc,CAAC,KAAa;QAC5B,IAAI,CAAC,eAAe,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;IAE1D,CAAC;IAQD;;;OAGG;IACH,YAAY,cAAsB,EAAE,gBAAwB,EAAE;QAPtD,eAAU,GAA2B,EAAE,CAAC;QAQ5C,IAAI,CAAC,eAAe,GAAG,uBAAuB,CAAC,cAAc,CAAC,CAAC;QAC/D,IAAI,CAAC,gBAAgB,GAAG,sBAAsB,CAAC,aAAa,CAAC,CAAC;QAC9D,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAI,IAA8B;QAC3C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC/C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAC,CAAC,CAAC;QAClD,CAAC,CAAC,CAAC;QAEH,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI;YACrB,OAAO,OAAO,CAAC;QAEnB,IAAI,CAAC,QAAQ,GAAG,UAAU,CAAC,KAAK,IAAI,EAAE;YAElC,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAEhC,OAAO,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;oBAC/C,MAAM,IAAA,oBAAK,EAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;gBACvC,CAAC;gBAED,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;gBAC3C,IAAI,UAAU,EAAE,CAAC;oBACb,IAAI,CAAC,YAAY,EAAE,CAAC;oBACpB,UAAU,CAAC,KAAK,IAAI,EAAE;wBAClB,IAAI,CAAC;4BACD,UAAU,CAAC,OAAO,CAAC,MAAM,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;wBAChD,CAAC;wBAAC,OAAO,KAAK,EAAE,CAAC;4BACb,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;wBAC7B,CAAC;gCAAS,CAAC;4BACP,IAAI,CAAC,YAAY,EAAE,CAAC;wBACxB,CAAC;oBACL,CAAC,CAAC,CAAC;gBACP,CAAC;YAGL,CAAC;YAED,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACzB,CAAC,EAAE,CAAC,CAAC,CAAC;QAEN,OAAO,OAAO,CAAC;IAGnB,CAAC;IAGD;;;;;OAKG;IACI,KAAK,CAAC,QAAQ;QACjB,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;YACzD,MAAM,IAAA,oBAAK,EAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACvC,CAAC;IACL,CAAC;CACJ;AAtFD,oCAsFC","sourcesContent":["import type {Supplier} from \"./types.js\";\nimport {delay} from \"./utilities.js\";\n\ntype QueuedTask<T> = {\n    task: Supplier<T | Promise<T>>;\n    resolve: (value: T) => void;\n    reject: (reason?: any) => void;\n};\n\nfunction normalizeMaxConcurrency(value: number): number {\n    if (!Number.isInteger(value) || value < 1) {\n        throw new RangeError(\"maxConcurrency must be a positive integer\");\n    }\n    return value;\n}\n\nfunction normalizeCheckInterval(value: number): number {\n    return Number.isFinite(value) ? Math.max(0, value) : 0;\n}\n\nexport default class AsyncPoolExecutor {\n    private _checkIntervalMs: number;\n\n    get maxConcurrency(): number {\n        return this._maxConcurrency;\n    }\n\n    set maxConcurrency(value: number) {\n        this._maxConcurrency = normalizeMaxConcurrency(value);\n\n    }\n\n    private _process: any;\n    private _maxConcurrency: number;\n    private _activeTasks: number;\n    private _taskQueue: Array<QueuedTask<any>> = [];\n\n\n    /**\n     * @param {number} maxConcurrency - The maximum number of concurrent tasks allowed.\n     * @param {number} [checkInterval=50] - The interval, in milliseconds, to check for capacity to run new tasks. Defaults to 50 ms.\n     */\n    constructor(maxConcurrency: number, checkInterval: number = 50) {\n        this._maxConcurrency = normalizeMaxConcurrency(maxConcurrency);\n        this._checkIntervalMs = normalizeCheckInterval(checkInterval);\n        this._activeTasks = 0;\n    }\n\n    /**\n     * Submits a deferred task to a queue for asynchronous execution and returns a Promise resolving to its result.\n     * @template T\n     * @param {Supplier<T>} task - The deferred task to be executed asynchronously.\n     */\n    public submit<T>(task: Supplier<T | Promise<T>>): Promise<T> {\n        const promise = new Promise<T>((resolve, reject) => {\n            this._taskQueue.push({task, resolve, reject});\n        });\n\n        if (this._process != null)\n            return promise;\n\n        this._process = setTimeout(async () => {\n\n            while (this._taskQueue.length > 0) {\n\n                while (this._activeTasks >= this._maxConcurrency) {\n                    await delay(this._checkIntervalMs);\n                }\n\n                const queuedTask = this._taskQueue.shift();\n                if (queuedTask) {\n                    this._activeTasks++;\n                    setTimeout(async () => {\n                        try {\n                            queuedTask.resolve(await queuedTask.task());\n                        } catch (error) {\n                            queuedTask.reject(error);\n                        } finally {\n                            this._activeTasks--;\n                        }\n                    });\n                }\n\n\n            }\n\n            this._process = null;\n        }, 0);\n\n        return promise;\n\n\n    }\n\n\n    /**\n     * Waits until all tasks (both queued and active) are completed.\n     * This method resolves only when there are no pending tasks.\n     *\n     * @return {Promise<void>} A promise that resolves when all tasks are complete.\n     */\n    public async shutdown(): Promise<void> {\n        while (this._taskQueue.length > 0 || this._activeTasks > 0) {\n            await delay(this._checkIntervalMs);\n        }\n    }\n}\n"]}