@develia/commons 0.3.19 → 0.3.21

package/src/utilities.ts

@@ -2,67 +2,158 @@
 
 
 import Pair from "./pair";
-import {Nullable, Provider} from "./types";
-import Type from "./type";
-
+import {Optional, Provider} from "./types";
+import {Type} from "./typing";
+
+/**
+ * Checks if an object is iterable.
+ *
+ * @param {any} obj - The object to check.
+ * @return {boolean} - Returns true if the object is iterable, otherwise false.
+ */
 export function isIterable(obj: any): boolean {
     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.
+ */
 export function isString(value: any): value is string {
     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.
+ */
 export function isNumber(value: any): value is number {
     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.
+ */
 export function isBoolean(value: any): value is boolean {
     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.
+ */
 export function isObject(value: any): value is object {
-    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.
+ */
 export function isArray(value: any): value is any[] {
     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.
+ */
 export function isFunction(value: any): value is Function {
     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.
+ */
 export function isUndefined(value: any): value is undefined {
     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.
+ */
 export function isDefined(value: any): value is undefined {
     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.
+ */
 export function isNull(value: any): value is null {
     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.
+ */
 export function isBigInt(value: any): value is bigint {
     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.
+ */
 export function isSymbol(value: any): value is symbol {
     return typeof value === 'symbol';
 }
 
-export function isNullOrUndefined(value: any) {
+/**
+ * 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.
+ */
+export function isNullOrUndefined(value: any): boolean {
     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.
+ */
 export function isEmpty(value: any): boolean {
     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.
+ */
 export function isEmptyOrWhitespace(value: any): boolean {
     return (Array.isArray(value) && value.length === 0) ||
         (typeof value === 'string' && value.trim() === '') ||
@@ -70,6 +161,13 @@ export function isEmptyOrWhitespace(value: any): boolean {
 }
 
 
+/**
+ * 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.
+ */
 export async function ajaxSubmit(selectorOrElement: HTMLFormElement | string): Promise<Response> {
 
     const form = typeof selectorOrElement === 'string'
@@ -87,7 +185,13 @@ export async function ajaxSubmit(selectorOrElement: HTMLFormElement | string): P
     });
 }
 
-export function toPairs(obj: any): Pair<any, any>[] {
+/**
+ * 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.
+ */
+export function toPairs(obj: Record<string, any>): Pair<string, any>[] {
 
     let output = [];
     for (const key in obj) {
@@ -97,6 +201,12 @@ export function toPairs(obj: any): Pair<any, any>[] {
 
 }
 
+/**
+ * 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.
+ */
 export function promisify<T>(thing: any): Promise<T> {
 
     if (thing instanceof Promise)
@@ -117,9 +227,10 @@ export function promisify<T>(thing: any): Promise<T> {
     return Promise.resolve(thing);
 }
 
+
 export function ajaxSubmission(selectorOrElement: HTMLFormElement | string,
-                               onSuccess: Nullable<Provider<Nullable<any>>> = null,
-                               onFailure: Nullable<Provider<Nullable<any>>> = null) {
+                               onSuccess: Optional<Provider<any>> = undefined,
+                               onFailure: Optional<Provider<any>> = undefined) : void {
 
     const form = typeof selectorOrElement === 'string'
         ? document.querySelector(selectorOrElement)
@@ -145,6 +256,12 @@ export function ajaxSubmission(selectorOrElement: HTMLFormElement | string,
 }
 
 
+/**
+ * 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.
+ */
 export function deepClone<T>(obj: T): T {
     if (obj === null || typeof obj !== 'object') {
         return obj;
@@ -167,10 +284,25 @@ export function deepClone<T>(obj: T): T {
     return copy as T;
 }
 
-function getType(value: any): Type {
-    return Type[typeof value as keyof typeof Type];
+/**
+ * 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.
+ */
+export function getType(value: any): Type {
+
+    return value === null ? Type.Null : Type[typeof value as keyof typeof Type];
 }
 
+/**
+ * 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: Record<string, any>, formData: FormData, parentKey: string = ''): FormData {
 
     for (const key in data) {
@@ -201,6 +333,12 @@ function _objectToFormData(data: Record<string, any>, formData: FormData, parent
     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.
+ */
 export function objectToFormData(data: Record<string, any>): FormData {
     let formData = new FormData();
     return _objectToFormData(data, formData);

package/src/strings.ts

@@ -1,21 +0,0 @@
-/**
- * Ensure prefix of a string
- *
- * @category String
- */
-export function ensurePrefix(str: string, prefix: string) {
-    if (!str.startsWith(prefix))
-        return prefix + str
-    return str
-}
-
-/**
- * Ensure suffix of a string
- *
- * @category String
- */
-export function ensureSuffix(str: string, suffix: string) {
-    if (!str.endsWith(suffix))
-        return str + suffix
-    return str
-}