@develia/commons 0.3.19 → 0.3.21

package/dist/index.cjs.js

@@ -2,7 +2,11 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var Type;
+/**
+ * Represents different types in JavaScript.
+ * @enum {string}
+ */
+exports.Type = void 0;
 (function (Type) {
     Type["Undefined"] = "undefined";
     Type["Number"] = "number";
@@ -12,9 +16,15 @@ var Type;
     Type["Function"] = "function";
     Type["Symbol"] = "symbol";
     Type["BigInt"] = "bigint";
-})(Type || (Type = {}));
-var Type$1 = Type;
+    Type["Null"] = "null";
+})(exports.Type || (exports.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;
@@ -29,55 +39,153 @@ class Pair {
 }
 
 // noinspection JSUnusedGlobalSymbols
+/**
+ * Checks if an object is iterable.
+ *
+ * @param {any} obj - The object to check.
+ * @return {boolean} - Returns true if the object is iterable, otherwise false.
+ */
 function isIterable(obj) {
     return obj[Symbol.iterator] === 'function';
 }
+/**
+ * Checks if a given value is a string.
+ *
+ * @param {*} value - The value to check.
+ * @return {boolean} - Returns true if the value is a string, otherwise returns false.
+ */
 function isString(value) {
     return typeof value === 'string';
 }
+/**
+ * Checks if a value is a number.
+ *
+ * @param {any} value - The value to check.
+ * @return {boolean} - Returns true if the value is a number, otherwise false.
+ */
 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)
@@ -91,6 +199,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) {
@@ -98,6 +212,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;
@@ -114,7 +234,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;
@@ -132,6 +252,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;
@@ -151,6 +277,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 ? exports.Type.Null : exports.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)) {
@@ -182,44 +325,84 @@ 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);
 }
 
 /**
- * Ensure prefix of a string
+ * Ensures that a given string has a specific prefix.
  *
- * @category String
+ * @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(prefix, str) {
+function ensurePrefix(str, prefix) {
     if (!str.startsWith(prefix))
         return prefix + str;
     return str;
 }
 /**
- * Ensure suffix of a string
+ * Ensures that a string ends with a specified suffix.
  *
- * @category String
+ * @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(suffix, str) {
+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 remaps a value from its source range [`inMin`, `inMax`] to the destination range [`outMin`, `outMax`]
+ * 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.
  *
- * @category Math
- * @example
- * ```
- * const value = remap(0.5, 0, 1, 200, 400) // value will be 300
- * ```
+ * @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;
@@ -362,14 +545,26 @@ class From {
         }
         return true;
     }
-    any(predicate) {
+    any(predicate = undefined) {
         for (let item of this) {
-            if (predicate(item)) {
+            if (predicate == null || predicate(item)) {
                 return true;
             }
         }
         return false;
     }
+    get length() {
+        return this.count();
+    }
+    count(predicate = undefined) {
+        let output = 0;
+        for (let item of this) {
+            if (predicate == null || predicate(item)) {
+                output++;
+            }
+        }
+        return output;
+    }
     filter(predicate) {
         const self = this;
         return From.fn(function* () {
@@ -735,6 +930,9 @@ class Grouping extends From {
     }
 }
 
+/**
+ * A class representing a timer that executes a callback function at a specified interval.
+ */
 class Timer {
     /**
      * @param callback Callback
@@ -786,6 +984,9 @@ class Timer {
     }
 }
 
+/**
+ * Represents a duration of time in milliseconds.
+ */
 class TimeSpan {
     constructor(milliseconds) {
         this.milliseconds = milliseconds;
@@ -954,6 +1155,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;
@@ -963,9 +1168,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;
@@ -976,6 +1181,11 @@ class Lazy {
     }
 }
 
+/**
+ * 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;
@@ -983,12 +1193,29 @@ class ArrayManipulator {
     [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) {
@@ -996,12 +1223,25 @@ class ArrayManipulator {
         }
         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])) {
@@ -1038,10 +1278,22 @@ class ArrayManipulator {
         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;
@@ -1050,6 +1302,12 @@ class ArrayManipulator {
         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);
 }
@@ -1061,7 +1319,6 @@ exports.Lazy = Lazy;
 exports.Pair = Pair;
 exports.TimeSpan = TimeSpan;
 exports.Timer = Timer;
-exports.Type = Type$1;
 exports.ajaxSubmission = ajaxSubmission;
 exports.ajaxSubmit = ajaxSubmit;
 exports.array = array;
@@ -1069,7 +1326,9 @@ exports.clamp = clamp;
 exports.deepClone = deepClone;
 exports.ensurePrefix = ensurePrefix;
 exports.ensureSuffix = ensureSuffix;
+exports.format = format;
 exports.from = from;
+exports.getType = getType;
 exports.isArray = isArray;
 exports.isBigInt = isBigInt;
 exports.isBoolean = isBoolean;