@develia/commons 0.4.15 → 0.4.18

package/src/array.ts

@@ -1,69 +1,117 @@
-import type {Predicate} from "./types.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.
- */
-export function pull<T>(array: Array<T>, ...items: Array<T>): number {
-
-    let output = 0;
-    for (const item of items) {
-        const index = array.indexOf(item);
-        if (index !== -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.
- */
-export function chunk<T>(array: Array<T>, size: number): Array<Array<T>> {
-    if (size <= 0) throw new Error("Size must be greater than 0");
-    const result: Array<Array<T>> = [];
-    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.
- */
-export function clear<T>(array: Array<T>): void {
-    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.
- */
-export function remove<T>(array: Array<T>,predicate: Predicate<T>): Array<T> {
-    const removed: Array<T> = [];
-    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;
+import type {Constructor, Predicate} from "./types.js";
+import {monkeyPatch} from "./utilities.js";
+
+declare global {
+    interface Array<T> {
+        pull(...items: Array<T>): number;
+        chunk(size: number): Array<Array<T>>;
+        clear(): void;
+        remove(predicate: Predicate<T>): Array<T>;
+        pushIfAbsent(element: T): boolean;
+    }
+}
+
+
+/**
+ * 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.
+ */
+export function pull<T>(array: Array<T>, ...items: Array<T>): number {
+
+    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.
+ */
+export function chunk<T>(array: Array<T>, size: number): Array<Array<T>> {
+    if (size <= 0) throw new Error("Size must be greater than 0");
+    const result: Array<Array<T>> = [];
+    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.
+ */
+export function clear<T>(array: Array<T>): void {
+    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.
+ */
+export function remove<T>(array: Array<T>,predicate: Predicate<T>): Array<T> {
+    const removed: Array<T> = [];
+    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.
+ */
+export function pushIfAbsent<T>(array: Array<T>, element: T): boolean {
+    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.
+ */
+export function patchArray(): void {
+    const target = Array as unknown as Constructor<Array<any>>;
+
+    monkeyPatch(target, pull);
+    monkeyPatch(target, chunk);
+    monkeyPatch(target, clear);
+    monkeyPatch(target, remove);
+    monkeyPatch(target, pushIfAbsent);
 }

package/src/async-pool-executor.ts

@@ -1,85 +1,107 @@
-import type {Supplier} from "./types.js";
-import {delay} from "./utilities.js";
-
-export default class AsyncPoolExecutor {
-    private _checkIntervalMs: number;
-
-    get maxConcurrency(): number {
-        return this._maxConcurrency;
-    }
-
-    set maxConcurrency(value: number) {
-        this._maxConcurrency = value;
-
-    }
-
-    private _proccess: any;
-    private _maxConcurrency: number;
-    private _activeTasks: number;
-    private _taskQueue: Array<Supplier<any>> = [];
-
-
-    /**
-     * @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: number, checkInterval: number = 50) {
-        this._maxConcurrency = maxConcurrency;
-        this._checkIntervalMs = 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.
-     */
-    public submit(task: Supplier<any>): void {
-
-        this._taskQueue.push(task);
-
-        if (this._proccess != null)
-            return;
-
-        this._proccess = setTimeout(async () => {
-
-            while (this._taskQueue.length > 0) {
-
-                while (this._activeTasks >= this._maxConcurrency) {
-                    await delay(this._checkIntervalMs);
-                }
-
-                const task = this._taskQueue.shift();
-                if (task) {
-                    this._activeTasks++;
-                    setTimeout(async () => {
-                        try {
-                            await task();
-                        } finally {
-                            this._activeTasks--;
-                        }
-                    });
-                }
-
-
-            }
-
-            this._proccess = null;
-        }, 0);
-
-
-    }
-
-
-    /**
-     * 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.
-     */
-    public async shutdown(): Promise<void> {
-        while (this._taskQueue.length > 0 || this._activeTasks > 0) {
-            await delay(this._checkIntervalMs);
-        }
-    }
-}
+import type {Supplier} from "./types.js";
+import {delay} from "./utilities.js";
+
+type QueuedTask<T> = {
+    task: Supplier<T | Promise<T>>;
+    resolve: (value: T) => void;
+    reject: (reason?: any) => void;
+};
+
+function normalizeMaxConcurrency(value: number): number {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new RangeError("maxConcurrency must be a positive integer");
+    }
+    return value;
+}
+
+function normalizeCheckInterval(value: number): number {
+    return Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+
+export default class AsyncPoolExecutor {
+    private _checkIntervalMs: number;
+
+    get maxConcurrency(): number {
+        return this._maxConcurrency;
+    }
+
+    set maxConcurrency(value: number) {
+        this._maxConcurrency = normalizeMaxConcurrency(value);
+
+    }
+
+    private _process: any;
+    private _maxConcurrency: number;
+    private _activeTasks: number;
+    private _taskQueue: Array<QueuedTask<any>> = [];
+
+
+    /**
+     * @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: number, checkInterval: number = 50) {
+        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.
+     */
+    public submit<T>(task: Supplier<T | Promise<T>>): Promise<T> {
+        const promise = new Promise<T>((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 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.
+     */
+    public async shutdown(): Promise<void> {
+        while (this._taskQueue.length > 0 || this._activeTasks > 0) {
+            await delay(this._checkIntervalMs);
+        }
+    }
+}

package/src/browser/form-utilities.ts

@@ -51,28 +51,34 @@ export function submitForm(
      * @param keyPrefix - Key path, e.g., 'user[name]' or 'tags[]'
      * @param value - The value to append (can be nested)
      */
+    const appendInput = (key: string, value: any) => {
+        const input = document.createElement('input');
+        input.type = 'hidden';
+        input.name = key;
+        input.value = String(value);
+        form.appendChild(input);
+    };
+
     const appendInputs = (keyPrefix: string, value: any) => {
         if (Array.isArray(value)) {
             for (const val of value) {
                 appendInputs(`${keyPrefix}[]`, val);
             }
+        } else if (value instanceof Date) {
+            appendInput(keyPrefix, value.toISOString());
         } else if (typeof value === 'object' && value !== null) {
             for (const subKey in value) {
-                if (value.hasOwnProperty(subKey)) {
+                if (Object.prototype.hasOwnProperty.call(value, subKey)) {
                     appendInputs(`${keyPrefix}[${subKey}]`, value[subKey]);
                 }
             }
         } else {
-            const input = document.createElement('input');
-            input.type = 'hidden';
-            input.name = keyPrefix;
-            input.value = String(value);
-            form.appendChild(input);
+            appendInput(keyPrefix, value);
         }
     };
 
     for (const key in data) {
-        if (data.hasOwnProperty(key)) {
+        if (Object.prototype.hasOwnProperty.call(data, key)) {
             appendInputs(key, data[key]);
         }
     }
@@ -86,7 +92,7 @@ export function formToObject(form: HTMLFormElement): Record<string, FormDataEntr
     const out: Record<string, FormDataEntryValue | FormDataEntryValue[]> = {};
 
     for (const [key, value] of fd.entries()) {
-        if (key in out) {
+        if (Object.prototype.hasOwnProperty.call(out, key)) {
             const current = out[key];
             if (Array.isArray(current)) {
                 current.push(value);
@@ -109,31 +115,26 @@ export function formToObject(form: HTMLFormElement): Record<string, FormDataEntr
  * @param {string} parentKey - The parent key to append to child keys in the `FormData`.
  * @returns {FormData} - The `FormData` instance with the converted data.
  */
-function _objectToFormData(data: Record<string, any>, formData: FormData, parentKey: string = ''): FormData {
+function _appendFormDataValue(formData: FormData, key: string, value: any): void {
+    if (value instanceof Date) {
+        formData.append(key, value.toISOString());
+    } else if (value instanceof File) {
+        formData.append(key, value);
+    } else if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index++) {
+            _appendFormDataValue(formData, `${key}[${index}]`, value[index]);
+        }
+    } else if (value !== null && typeof value === 'object') {
+        _objectToFormData(value, formData, key);
+    } else {
+        formData.append(key, value);
+    }
+}
 
+function _objectToFormData(data: Record<string, any>, formData: FormData, parentKey: string = ''): FormData {
     for (const key in data) {
-        if (data.hasOwnProperty(key)) {
-            const value = data[key];
-
-            if (value instanceof Date) {
-                formData.append(parentKey ? `${parentKey}[${key}]` : key, value.toISOString());
-            } else if (value instanceof File) {
-                formData.append(parentKey ? `${parentKey}[${key}]` : key, value);
-            } else if (typeof value === 'object' && !Array.isArray(value)) {
-                _objectToFormData(value, formData, parentKey ? `${parentKey}[${key}]` : key);
-            } else if (Array.isArray(value)) {
-                for (let index = 0; index < value.length; index++) {
-                    const item = value[index];
-                    const arrayKey = `${parentKey ? `${parentKey}[${key}]` : key}[${index}]`;
-                    if (typeof item === 'object' && !Array.isArray(item)) {
-                        _objectToFormData(item, formData, arrayKey);
-                    } else {
-                        formData.append(arrayKey, item);
-                    }
-                }
-            } else {
-                formData.append(parentKey ? `${parentKey}[${key}]` : key, value);
-            }
+        if (Object.prototype.hasOwnProperty.call(data, key)) {
+            _appendFormDataValue(formData, parentKey ? `${parentKey}[${key}]` : key, data[key]);
         }
     }