@develia/commons 0.3.17 → 0.3.20

package/dist/index.esm.js

@@ -1,3 +1,26 @@
+/**
+ * Represents different types in JavaScript.
+ * @enum {string}
+ */
+var Type;
+(function (Type) {
+    Type["Undefined"] = "undefined";
+    Type["Number"] = "number";
+    Type["String"] = "string";
+    Type["Boolean"] = "boolean";
+    Type["Object"] = "object";
+    Type["Function"] = "function";
+    Type["Symbol"] = "symbol";
+    Type["BigInt"] = "bigint";
+    Type["Null"] = "null";
+})(Type || (Type = {}));
+
+/**
+ * Represents a pair of key and value.
+ *
+ * @template TKey The type of the key.
+ * @template TValue The type of the value.
+ */
 class Pair {
     get value() {
         return this._value;
@@ -12,91 +35,153 @@ class Pair {
 }
 
 // noinspection JSUnusedGlobalSymbols
-function isIterable(obj) {
-    return obj[Symbol.iterator] === 'function';
-}
-function clamp(n, min, max) {
-    if (n <= min)
-        return min;
-    if (n >= max)
-        return max;
-    return n;
-}
 /**
- * Linearly remaps a value from its source range [`inMin`, `inMax`] to the destination range [`outMin`, `outMax`]
+ * Checks if an object is iterable.
  *
- * @category Math
- * @example
- * ```
- * const value = remap(0.5, 0, 1, 200, 400) // value will be 300
- * ```
+ * @param {any} obj - The object to check.
+ * @return {boolean} - Returns true if the object is iterable, otherwise false.
  */
-function lerp(n, inMin, inMax, outMin, outMax) {
-    return outMin + (outMax - outMin) * ((n - inMin) / (inMax - inMin));
+function isIterable(obj) {
+    return obj[Symbol.iterator] === 'function';
 }
 /**
- * Ensure prefix of a string
+ * Checks if a given value is a string.
  *
- * @category String
+ * @param {*} value - The value to check.
+ * @return {boolean} - Returns true if the value is a string, otherwise returns false.
  */
-function ensurePrefix(prefix, str) {
-    if (!str.startsWith(prefix))
-        return prefix + str;
-    return str;
+function isString(value) {
+    return typeof value === 'string';
 }
 /**
- * Ensure suffix of a string
+ * Checks if a value is a number.
  *
- * @category String
+ * @param {any} value - The value to check.
+ * @return {boolean} - Returns true if the value is a number, otherwise false.
  */
-function ensureSuffix(suffix, str) {
-    if (!str.endsWith(suffix))
-        return str + suffix;
-    return str;
-}
-function isString(value) {
-    return typeof value === 'string';
-}
 function isNumber(value) {
     return typeof value === 'number';
 }
+/**
+ * Checks if a given value is a boolean.
+ *
+ * @param {any} value - The value to be checked.
+ *
+ * @return {boolean} - Returns true if the value is a boolean, otherwise false.
+ */
 function isBoolean(value) {
     return typeof value === 'boolean';
 }
+/**
+ * Checks if a value is an object.
+ * @param {any} value - The value to be checked.
+ * @returns {boolean} - Returns true if the value is an object, otherwise returns false.
+ */
 function isObject(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
+    return value != null && typeof value === 'object' && !Array.isArray(value);
 }
+/**
+ * Determines if a value is an array.
+ *
+ * @param value - The value to be checked.
+ *
+ * @return Whether the value is an array.
+ */
 function isArray(value) {
     return Array.isArray(value);
 }
+/**
+ * Checks if a value is a function.
+ *
+ * @param {any} value - The value to be checked.
+ * @return {boolean} - Returns true if the value is a function, otherwise returns false.
+ */
 function isFunction(value) {
     return typeof value === 'function';
 }
+/**
+ * Checks if a value is undefined.
+ *
+ * @param {any} value - The value to check.
+ * @returns {boolean} - True if the value is undefined, false otherwise.
+ */
 function isUndefined(value) {
     return typeof value === 'undefined';
 }
+/**
+ * Checks if a value is defined or not.
+ *
+ * @param {any} value - The value to be checked.
+ *
+ * @return {boolean} - True if the value is defined, false otherwise.
+ */
+function isDefined(value) {
+    return typeof value !== 'undefined';
+}
+/**
+ * Checks if a given value is null.
+ *
+ * @param {any} value - The value to check for null.
+ * @return {boolean} - Returns true if the value is null, otherwise returns false.
+ */
 function isNull(value) {
     return value === null;
 }
+/**
+ * Determines whether the given value is of type bigint.
+ * @param {any} value - The value to be checked.
+ * @return {boolean} - Returns true if the value is of type bigint, false otherwise.
+ */
 function isBigInt(value) {
     return typeof value === 'bigint';
 }
+/**
+ * Checks if a given value is a symbol.
+ *
+ * @param {any} value - The value to be checked.
+ * @return {boolean} - Returns true if the value is a symbol, false otherwise.
+ */
 function isSymbol(value) {
     return typeof value === 'symbol';
 }
+/**
+ * Checks if a value is null or undefined.
+ *
+ * @param {any} value - The value to check.
+ * @return {boolean} - Returns true if the value is null or undefined, false otherwise.
+ */
 function isNullOrUndefined(value) {
     return value === null || typeof value === 'undefined';
 }
+/**
+ * Checks if a given value is empty.
+ *
+ * @param {any} value - The value to check.
+ * @return {boolean} - Returns true if the value is empty, otherwise returns false.
+ */
 function isEmpty(value) {
     return (Array.isArray(value) && value.length === 0) ||
         (typeof value === 'string' && value === '') ||
         value === null || typeof value === 'undefined';
 }
+/**
+ * Check if a value is empty or contains only whitespace characters.
+ *
+ * @param {any} value - The value to check.
+ * @return {boolean} Returns true if the value is empty or contains only whitespace characters, otherwise returns false.
+ */
 function isEmptyOrWhitespace(value) {
     return (Array.isArray(value) && value.length === 0) ||
         (typeof value === 'string' && value.trim() === '') ||
         value === null || typeof value === 'undefined';
 }
+/**
+ * Submits a form via AJAX and returns a Promise that resolves to the Response object.
+ *
+ * @param {HTMLFormElement | string} selectorOrElement - The form element or selector.
+ * @return {Promise<Response>} A Promise that resolves to the Response object.
+ * @throws {Error} If the element is invalid.
+ */
 async function ajaxSubmit(selectorOrElement) {
     const form = typeof selectorOrElement === 'string'
         ? document.querySelector(selectorOrElement)
@@ -110,6 +195,12 @@ async function ajaxSubmit(selectorOrElement) {
         body: new FormData(form),
     });
 }
+/**
+ * Converts an object into an array of key-value pairs.
+ *
+ * @param {Record<string, any>} obj - The object to convert.
+ * @return {Pair<string, any>[]} - The array of key-value pairs.
+ */
 function toPairs(obj) {
     let output = [];
     for (const key in obj) {
@@ -117,6 +208,12 @@ function toPairs(obj) {
     }
     return output;
 }
+/**
+ * Converts a given thing into a Promise.
+ * @template T
+ * @param {any} thing - The thing to be converted into a Promise.
+ * @returns {Promise<T>} - A Promise representing the given thing.
+ */
 function promisify(thing) {
     if (thing instanceof Promise)
         return thing;
@@ -133,7 +230,7 @@ function promisify(thing) {
     }
     return Promise.resolve(thing);
 }
-function ajaxSubmission(selectorOrElement, onSuccess = null, onFailure = null) {
+function ajaxSubmission(selectorOrElement, onSuccess = undefined, onFailure = undefined) {
     const form = typeof selectorOrElement === 'string'
         ? document.querySelector(selectorOrElement)
         : selectorOrElement;
@@ -151,6 +248,12 @@ function ajaxSubmission(selectorOrElement, onSuccess = null, onFailure = null) {
         }
     });
 }
+/**
+ * Creates a deep clone of the given object.
+ * @template T
+ * @param {T} obj - The object to clone.
+ * @return {T} - The deep clone of the given object.
+ */
 function deepClone(obj) {
     if (obj === null || typeof obj !== 'object') {
         return obj;
@@ -170,6 +273,23 @@ function deepClone(obj) {
     }
     return copy;
 }
+/**
+ * Returns the type of the given value.
+ *
+ * @param {any} value - The value to determine the type of.
+ * @return {Type} - The type of the given value.
+ */
+function getType(value) {
+    return value === null ? Type.Null : Type[typeof value];
+}
+/**
+ * Converts an object to `FormData` format recursively.
+ *
+ * @param {Record<string, any>} data - The object data to convert.
+ * @param {FormData} formData - The `FormData` instance to append data to.
+ * @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, formData, parentKey = '') {
     for (const key in data) {
         if (data.hasOwnProperty(key)) {
@@ -201,11 +321,92 @@ function _objectToFormData(data, formData, parentKey = '') {
     }
     return formData;
 }
+/**
+ * Converts an object into FormData.
+ *
+ * @param {Record<string, any>} data - The object to be converted into FormData.
+ * @return {FormData} - The FormData object representing the converted data.
+ */
 function objectToFormData(data) {
     let formData = new FormData();
     return _objectToFormData(data, formData);
 }
 
+/**
+ * Ensures that a given string has a specific prefix.
+ *
+ * @param {string} str - The string to ensure the prefix on.
+ * @param {string} prefix - The prefix to ensure on the string.
+ * @return {string} - The resulting string with the ensured prefix.
+ */
+function ensurePrefix(str, prefix) {
+    if (!str.startsWith(prefix))
+        return prefix + str;
+    return str;
+}
+/**
+ * Ensures that a string ends with a specified suffix.
+ *
+ * @param {string} str - The original string.
+ * @param {string} suffix - The suffix to ensure.
+ * @return {string} - The modified string with the suffix added if it was not already present.
+ */
+function ensureSuffix(str, suffix) {
+    if (!str.endsWith(suffix))
+        return str + suffix;
+    return str;
+}
+/**
+ * Formats a string using a template and provided arguments.
+ *
+ * @param {string} template - The template string containing placeholders.
+ * @param {any[]} args - Optional arguments to replace the placeholders in the template.
+ * @return {string} The formatted string.
+ */
+function format(template, ...args) {
+    let regex;
+    if (args.length === 1 && typeof args[0] === 'object') {
+        args = args[0];
+        regex = /{(.+?)}/g;
+    }
+    else {
+        regex = /{(\d+?)}/g;
+    }
+    return template.replace(regex, (match, key) => {
+        return typeof args[key] !== 'undefined' ? args[key] : "";
+    });
+}
+
+/**
+ * Linearly interpolates a number between two ranges.
+ *
+ * @param {number} n - The number to interpolate.
+ * @param {number} inMin - The minimum value of the input range.
+ * @param {number} inMax - The maximum value of the input range.
+ * @param {number} outMin - The minimum value of the output range.
+ * @param {number} outMax - The maximum value of the output range.
+ *
+ * @return {number} - The interpolated value.
+ */
+function lerp(n, inMin, inMax, outMin, outMax) {
+    return outMin + (outMax - outMin) * ((n - inMin) / (inMax - inMin));
+}
+/**
+ * Clamps a number between a minimum and maximum value.
+ *
+ * @param {number} n - The value to be clamped.
+ * @param {number} min - The minimum value.
+ * @param {number} max - The maximum value.
+ * @return {number} The clamped value.
+ */
+function clamp(n, min, max) {
+    if (n <= min)
+        return min;
+    if (n >= max)
+        return max;
+    return n;
+}
+
 class CacheDictionary {
     constructor(fallback = null, defaultDuration = null) {
         this.fallback = fallback;
@@ -713,6 +914,9 @@ class Grouping extends From {
     }
 }
 
+/**
+ * A class representing a timer that executes a callback function at a specified interval.
+ */
 class Timer {
     /**
      * @param callback Callback
@@ -764,6 +968,9 @@ class Timer {
     }
 }
 
+/**
+ * Represents a duration of time in milliseconds.
+ */
 class TimeSpan {
     constructor(milliseconds) {
         this.milliseconds = milliseconds;
@@ -932,6 +1139,10 @@ class TimeSpan {
 TimeSpan.INFINITE = new TimeSpan(Number.POSITIVE_INFINITY);
 TimeSpan.NEGATIVE_INFINITE = new TimeSpan(Number.NEGATIVE_INFINITY);
 
+/**
+ * Represents a lazy value that is created only when it is accessed for the first time.
+ * @template T The type of the lazy value.
+ */
 class Lazy {
     constructor(getter) {
         this._valueCreated = false;
@@ -941,9 +1152,9 @@ class Lazy {
     get valueCreated() {
         return this._valueCreated;
     }
-    async getValue() {
+    get value() {
         if (!this._valueCreated) {
-            this._value = await promisify(this._factoryMethod);
+            this._value = this._factoryMethod();
             this._valueCreated = true;
         }
         return this._value;
@@ -954,5 +1165,136 @@ class Lazy {
     }
 }
 
-export { CacheDictionary, From, Lazy, Pair, TimeSpan, Timer, ajaxSubmission, ajaxSubmit, clamp, deepClone, ensurePrefix, ensureSuffix, from, isArray, isBigInt, isBoolean, isEmpty, isEmptyOrWhitespace, isFunction, isIterable, isNull, isNullOrUndefined, isNumber, isObject, isString, isSymbol, isUndefined, lerp, objectToFormData, promisify, toPairs };
+/**
+ * Represents a class for manipulating an array of items.
+ *
+ * @template T - The type of items in the array.
+ */
+class ArrayManipulator {
+    constructor(array) {
+        this._array = array;
+    }
+    [Symbol.iterator]() {
+        return this._array[Symbol.iterator]();
+    }
+    /**
+     * Retrieves or sets the value at the specified index in the array.
+     * If `item` is not provided, returns the value at index `n`.
+     * If `item` is provided, sets the value at index `n` to the provided value.
+     *
+     * @param {number} n - The index at which to retrieve or set the value.
+     * @param {T | undefined} [item] - The value to set at index `n`, if provided.
+     *
+     * @return {T | void} - If `item` is not provided, returns the value at index `n`.
+     *                    - If `item` is provided, does not return anything.
+     */
+    at(n, item = undefined) {
+        if (item === undefined)
+            return this._array[n];
+        else
+            this._array[n] = item;
+    }
+    /**
+     * Removes the specified item from the array.
+     *
+     * @param {T} item - The item to be removed.
+     * @returns {ArrayManipulator<T>} - The updated ArrayManipulator instance.
+     */
+    remove(item) {
+        const index = this._array.indexOf(item);
+        if (index !== -1) {
+            this._array.splice(index, 1);
+        }
+        return this;
+    }
+    /**
+     * Applies a mapping function to each element in the array, transforming it into a new array.
+     * @template R
+     * @param {UnaryFunction<T, R>} mapFn - The function to be applied to each element.
+     * @return {ArrayManipulator<R>} - The new ArrayManipulator instance with the mapped elements.
+     */
+    map(mapFn) {
+        for (let i = 0; i < this._array.length; i++) {
+            this._array[i] = mapFn(this._array[i]);
+        }
+        return this;
+    }
+    /**
+     * Filters the elements of the array based on a given filter function.
+     * The filter function should return a boolean value, indicating whether the element should be included in the filtered array or not.
+     *
+     * @param {Predicate<T>} filterFn - The function that will be used to filter the elements. It should accept an element of type T and return a boolean value.
+     * @returns {ArrayManipulator<T>} - The filtered ArrayManipulator instance with the elements that passed the filter.
+     */
+    filter(filterFn) {
+        for (let i = 0; i < this._array.length; i++) {
+            if (!filterFn(this._array[i])) {
+                this._array.splice(i, 1);
+                i--;
+            }
+        }
+        return this;
+    }
+    head(n) {
+        this._array.splice(n);
+        return this;
+    }
+    slice(start, count = undefined) {
+        this._array.splice(0, start); // Eliminar los primeros elementos hasta `start`
+        if (count !== undefined) {
+            this._array.splice(count); // Mantener solo `count` elementos restantes
+        }
+        return this;
+    }
+    mapMany(mapper) {
+        let i = 0;
+        while (i < this._array.length) {
+            let mappedItems = mapper(this._array[i]);
+            if (!Array.isArray(mappedItems))
+                mappedItems = Array.from(mappedItems);
+            this._array.splice(i, 1, ...mappedItems);
+            i += mappedItems.length;
+        }
+        return this;
+    }
+    tail(n) {
+        const start = this._array.length - n;
+        this._array.splice(0, start);
+        return this;
+    }
+    /**
+     * Appends one or more items to the array.
+     *
+     * @param {...T} items - The items to be appended to the array.
+     * @return {ArrayManipulator<T>} - The ArrayManipulator instance.
+     */
+    append(...items) {
+        this._array.push(...items);
+        return this;
+    }
+    /**
+     * Prepend items to the beginning of the array.
+     *
+     * @param {...T} items - The items to be prepended.
+     * @return {ArrayManipulator<T>} The ArrayManipulator instance.
+     */
+    prepend(...items) {
+        this._array.unshift(...items);
+        return this;
+    }
+    get array() {
+        return this._array;
+    }
+}
+/**
+ * Creates an instance of ArrayManipulator with the given array.
+ * @template T
+ * @param {T[]} array - The input array.
+ * @return {ArrayManipulator<T>} - An instance of the ArrayManipulator class.
+ */
+function array(array) {
+    return new ArrayManipulator(array);
+}
+
+export { ArrayManipulator, CacheDictionary, From, Lazy, Pair, TimeSpan, Timer, Type, ajaxSubmission, ajaxSubmit, array, clamp, deepClone, ensurePrefix, ensureSuffix, format, from, getType, isArray, isBigInt, isBoolean, isDefined, isEmpty, isEmptyOrWhitespace, isFunction, isIterable, isNull, isNullOrUndefined, isNumber, isObject, isString, isSymbol, isUndefined, lerp, objectToFormData, promisify, toPairs };
 //# sourceMappingURL=index.esm.js.map