@carlsebastian/jsu 1.0.34

package/src/utils/dom/lifecycle/unmount.js

@@ -0,0 +1,43 @@
+import Emit from '../../custom/error/builder/error.builder.js';
+import { IsChildNode, IsPropertyAt } from '../../guards/data-types/data-types.js';
+
+/**
+ *  Unmounts the given `childNode` to its `parentNode`.
+ *
+ *  ***Reference***:
+ *      `remove()`
+ *
+ *  @overload
+ *  @param { ChildNode } childNode - The `childNode` to unmount at its `parentNode`.
+ *  @returns { void }
+ */
+/**
+ *  Unmounts the given `childNode` collection to their `parentNode`.
+ *
+ *  ***Reference***:
+ *      `remove()`
+ *
+ *  @overload
+ *  @param { ...ChildNode[] } childNodes - The `childNode` collection to unmount to their respective `parentNode`.
+ *  @return { void }
+ */
+export default function Unmount(...childNodes) {
+    const Method = "Unmount", ICtr = childNodes.length, PCN = ICtr > 1 ? "childNodes" : "childNode";
+
+    if (childNodes.length === 0) {
+        console.warn(`${Method}(): Expects at least 1 or more 'childNode' to remove. (Exited)`);
+        return;
+    }
+
+    for (const Node of childNodes) {
+        if (!IsChildNode(Node))
+            Emit._ArgumentError(Method, PCN, Node, "ChildNode");
+
+        if (!IsPropertyAt(Node, "remove")) {
+            console.warn(`${Method}(@${PCN}${ICtr > 1 ? `[${Node}]` : `: ${Node}`}: NOT_SUPPORTED_METHOD): A given child node does not support the 'remove()' method! (${ICtr > 1 ? "Skipped" : "Exited"})`);
+            continue;
+        }
+
+        Node.remove();
+    }
+}

package/src/utils/guards/data-types/data-types.js

@@ -0,0 +1,201 @@
+/**
+ *  Validates whether if the specified argument is `null` or `undefined`.
+ *
+ * @template T
+ *  @param { T } arg - The argument to validate.
+ *  @returns { arg is Extract<T, null | undefined> }
+ */
+export function IsNullOrUndefined(arg) {
+    return arg === null || arg === undefined;
+}
+
+/**
+ *  Validates whether if the specified argument is a `string`.
+ *
+ *  @param { any } arg - The argument to validate.
+ *  @returns { arg is string }
+ */
+export function IsStr(arg) {
+    return typeof arg === "string" || arg?.constructor === String;
+}
+
+/**
+ *  Validates whether if the specified argument is an `array`.
+ *
+ *  @template T
+ *  @param { T } arg - The argument to validate.
+ *  @returns { arg is Array<T> }
+ */
+export function IsArr(arg) {
+    return typeof arg === "object" && Array.isArray(arg);
+}
+
+/**
+ *  Validates whether if the specified argument is a `function`.
+ *
+ *  @param { any } arg - The argument to validate.
+ *  @returns { arg is Function }
+ */
+export function IsFunc(arg) {
+    return typeof arg === "function" || arg?.constructor === Function;
+}
+
+/**
+ *  Validates whether if the specified argument is a `map object`.
+ *
+ *  @template T
+ *  @param { T } arg - The argument to validate.
+ *  @returns { arg is T extends Map<infer K, infer V> ? Map<K, V> : boolean }
+ */
+export function IsMapObj(arg) {
+    return arg?.constructor === Map || arg instanceof Map;
+}
+
+/**
+ *  Validates whether if the specified argument is a `set object`.
+ *
+ *  @template T
+ *  @param { T } arg - The argument to validate.
+ *  @returns { arg is Set<T> }
+ */
+export function IsSetObj(arg) {
+    return arg?.constructor === Set || arg instanceof Set;
+}
+
+/**
+ *  Validates whether if the specified argument is a `plain object`.
+ *
+ *  @template T
+ *  @param { T } arg - The argument to validate.
+ *  @returns { arg is T extends { [p: string]: infer V } ? Record<string, V> : boolean }
+ */
+export function IsPlainObj(arg) {
+    return typeof arg === "object" && !(IsArr(arg) || IsNullOrUndefined(arg) || IsMapObj(arg) || IsSetObj(arg));
+}
+
+/**
+ *  Validates whether if the specified argument is a `boolean`.
+ *
+ *  @param { any } arg - The argument to validate.
+ *  @returns { arg is boolean }
+ */
+export function IsBool(arg) {
+    return typeof arg === "boolean" || arg?.constructor === Boolean;
+}
+
+/**
+ *  Validates whether if the specified argument is a `number`.
+ *
+ *  @param { any } arg - The argument to validate.
+ *  @returns { arg is number }
+ */
+export function IsNum(arg) {
+    return (typeof arg === "number" || arg?.constructor === Number) && !Number.isNaN(arg);
+}
+
+/**
+ *  Validates whether if the specified argument is a `Node`.
+ *
+ *  @param { any } arg - The argument to validate.
+ *  @returns { arg is Node }
+ */
+export function IsNode(arg) {
+    return arg?.constructor === Node;
+}
+
+/**
+ *  Validates whether if the specified argument is a `ParentNode`.
+ *
+ *  @param { any } arg - The argument to validate.
+ *  @returns { arg is ParentNode }
+ */
+export function IsParentNode(arg) {
+    if (arg === null || arg === undefined)
+        return false;
+
+    const IsQueryAble = [
+        "getElementsByClassName", "getElementsByTagName", "getElementsByTagNameNS"
+    ].every(prop => typeof arg[prop] === "function");
+
+    return "children" in arg && "firstElementChild" in arg && "lastElementChild" in arg && IsQueryAble;
+}
+
+/**
+ *  Validates whether if the specified argument is a `ChildNode`.
+ *
+ *  @param { any } arg - The argument to validate.
+ *  @returns { arg is ChildNode }
+ */
+export function IsChildNode(arg) {
+    if (IsNullOrUndefined(arg))
+        return false;
+
+    return (
+        typeof arg.after === "function" && typeof arg.before === "function" &&
+        typeof arg.remove === "function" && typeof arg.replaceWith === "function"
+    );
+}
+
+/**
+ *  Validates whether if the specified argument is an `Element` or instance of it.
+ *
+ *  @param { any } arg - The argument to validate.
+ *  @returns { arg is Element }
+ */
+export function IsElement(arg) {
+    return arg?.constructor === Element || arg instanceof Element;
+}
+
+/**
+ *  Validates whether if the specified argument is an `HTMLElement` or instance of it.
+ *
+ *  @param { any } arg - The argument to validate.
+ *  @returns { arg is HTMLElement }
+ */
+export function IsHTMLElement(arg) {
+    return arg?.constructor === HTMLElement || arg instanceof HTMLElement;
+}
+
+/**
+ *  Validates whether if the specified argument is an `HTMLUnknownElement` or instance of it.
+ *
+ *  @param { any } arg - The argument to validate.
+ *  @returns { arg is HTMLUnknownElement }
+ */
+export function IsUnknownElement(arg) {
+    return arg?.constructor === HTMLUnknownElement || arg instanceof HTMLUnknownElement;
+}
+
+/**
+ *  Validates whether if the specified argument is `Iterator`.
+ *
+ *  @param { any } arg - The argument to validate.
+ *  @returns { arg is Iterator }
+ */
+export function IsIterator(arg) {
+    return arg?.constructor === Iterator || arg instanceof Iterator;
+}
+
+/**
+ *  Validates whether if the specified argument is `RegExp`.
+ *
+ *  @param { any } arg - The argument to validate.
+ *  @returns { arg is RegExp }
+ */
+export function IsRegExp(arg) {
+    return arg?.constructor === RegExp || arg instanceof RegExp;
+}
+
+/**
+ *  Validates whether if the specified argument supported the specified property.
+ *
+ *  @param { any } arg - The argument to validate.
+ *  @param { string } property - The property to check.
+ *  @returns { boolean } The validation state result.
+ */
+export function IsPropertyAt(arg, property) {
+    if (IsNullOrUndefined(arg) || !IsStr(property) || property.trim().length === 0)
+        return false;
+
+    return Object.hasOwn(arg, property) || property in arg;
+}

package/src/utils/guards/formats/formats.js

@@ -0,0 +1,274 @@
+import { HTMLElementTags } from '../../variables.js';
+import { IsArr, IsFunc, IsMapObj, IsNullOrUndefined, IsNum, IsPlainObj, IsSetObj, IsStr } from '../data-types/data-types.js';
+
+/**
+ *  Validates whether if the specified ***function*** argument is ***anonymous***.
+ *
+ *  @param { Function } func - The function to validate.
+ *  @returns { boolean }
+ */
+export function IsFuncAnonymous(func) {
+    return IsFunc(func) && !func.toString().startsWith("function") && !func.toString().includes("=>");
+}
+
+/**
+ *  Validates whether if the specified ***function*** argument is ***asynchronous***.
+ *
+ *  @param { Function } func - The function to validate.
+ *  @returns { boolean }
+ */
+export function IsFuncAsynchronous(func) {
+    return IsFunc(func) && !IsNullOrUndefined(func?.constructor?.name) && func.constructor.name === "AsyncFunction";
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument includes lowercase characters.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function HasLowerCase(str) {
+    return IsStr(str) && /[a-z]/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument starts with lowercase character.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function IsStartsWithLowerCase(str) {
+    return IsStr(str) && /^[a-z]/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument ends with lowercase character.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function IsEndsWithLowerCase(str) {
+    return IsStr(str) && /[a-z]$/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument includes uppercase characters.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function HasUpperCase(str) {
+    return IsStr(str) && /[A-Z]/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument starts with uppercase character.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function IsStartsWithUpperCase(str) {
+    return IsStr(str) && /^[A-Z]/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument ends with uppercase character.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function IsEndsWithUpperCase(str) {
+    return IsStr(str) && /[A-Z]$/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument includes numbers.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function HasNumbers(str) {
+    return IsStr(str) && /\d/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument starts with number.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function IsStartsWithNumber(str) {
+    return IsStr(str) && /^\d/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument ends with number.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function IsEndsWithNumber(str) {
+    return IsStr(str) && /\d$/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument includes specified characters.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function HasSpecialCharacters(str) {
+    return IsStr(str) && /[^a-zA-Z\d]/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument starts with special character.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function IsStartsWithSpecialCharacter(str) {
+    return IsStr(str) && /^[^a-zA-Z\d]/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument ends with special character.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function IsEndsWithSpecialCharacter(str) {
+    return IsStr(str) && /[^a-zA-Z\d]$/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument includes ASCII characters.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function HasASCII(str) {
+    return IsStr(str) && /[^\x00-\x7F]/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument starts with ASCII character.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function IsStartsWithASCII(str) {
+    return IsStr(str) && /^[^\x00-\x7F]/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument ends with ASCII character.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function IsEndsWithASCII(str) {
+    return IsStr(str) && /[^\x00-\x7F]$/.test(str);
+}
+
+/**
+ *  Validates whether if the specified ***string*** argument is empty.
+ *
+ *  @param { string } str - The string to validate.
+ *  @returns { boolean }
+ */
+export function IsStrEmpty(str) {
+    return IsStr(str) && str.trim().length <= 0;
+}
+
+/**
+ *  Validates whether if the specified ***array*** argument is empty.
+ *
+ *  @template T
+ *  @param { Array<T> } arr - The array to validate.
+ *  @returns { arr extends Array<never> ? true : false }
+ */
+export function IsArrEmpty(arr) {
+    return IsArr(arr) && arr.length <= 0;
+}
+
+/**
+ *  Validates whether if the specified ***plain object*** is empty.
+ *
+ *  @param { Record<string, unknown> } obj - The plain object to validate.
+ *  @returns { boolean }
+ */
+export function IsPlainObjEmpty(obj) {
+    return IsPlainObj(obj) && Object.entries(obj).length <= 0;
+}
+
+/**
+ *  Validates whether if the specified ***map object*** is empty.
+ *
+ *  @param { Map<unknown, unknown> } mObj - The map object to validate.
+ *  @returns { boolean }
+ */
+export function IsMapObjEmpty(mObj) {
+    return IsMapObj(mObj) && mObj.size <= 0;
+}
+
+/**
+ *  Validates whether if the specified ***set object*** is empty.
+ *
+ *  @param { Set<unknown> } sObj - The set object to validate.
+ *  @returns { boolean }
+ */
+export function IsSetObjEmpty(sObj) {
+    return IsSetObj(sObj) && sObj.size <= 0;
+}
+
+/**
+ *  Validates whether if the specified `object` has the specified `property` id.
+ *
+ *  @overload
+ *  @param {{ [prop: string]: unknown }} obj - The object to check the property.
+ *  @param { string } propertyId - The property id to check.
+ *  @returns { boolean }
+ */
+/**
+ *  Validates whether if the specified `map object` has the specified `property` id.
+ *
+ *  @template T
+ *  @overload
+ *  @param { T } obj - The map object to check the property.
+ *  @param { string } propertyId - The property id to check.
+ *  @returns { boolean }
+ */
+export function HasProperty(obj = {}, propertyId) {
+    if (IsPlainObj(obj)) {
+        if (!IsStr(propertyId) || !IsStrEmpty(propertyId))
+            return false;
+
+        return Object.hasOwn(obj, propertyId);
+    }
+
+    if (IsMapObj(obj))
+        return obj.has(propertyId);
+
+    return false;
+}
+
+/**
+ *  Validates whether if the specified `Array` or `Set` of elements includes the specified search `element`.
+ *
+ *  @param { Array<unknown> | Set<unknown> } obj - The `Array` or `Set` of elements.
+ *  @param { any } searchElement - The element to search.
+ *  @param { number } [atPos] - A optional parameter to start looking at collection of elements. (Default: 0)
+ *  @returns { boolean }
+ */
+export function HasValue(obj, searchElement, atPos = 0) {
+    const Pos = atPos < 0 ? Math.abs(atPos) : atPos;
+
+    if (IsArr(obj))
+        return obj.includes(searchElement, Pos);
+
+    if (IsSetObj(obj))
+        return [...obj.values()].includes(searchElement, Pos);
+
+    return false;
+}

package/src/utils/guards/guards.js

@@ -0,0 +1,21 @@
+import { DefineProperty, Global } from '../custom/utils/custom.utils.js';
+import * as T from "./data-types/data-types.js";
+import * as F from "./formats/formats.js";
+
+/**
+ *  Contains validations methods for types such ah ***string***, ***null***,
+ *  ***function*** and many more!
+ */
+export default function Guards() {
+  const GuardsAPI = {};
+
+  for (const Method of [...Object.values(T), ...Object.values(F)]) {
+    const Key = Method.name;
+    if (!T.IsNullOrUndefined(Key) && !F.IsStrEmpty(Key) && !T.IsPropertyAt(GuardsAPI, Key))
+      DefineProperty(GuardsAPI, Key, Method, "med");
+  }
+
+  Global("Guards", GuardsAPI, "soft");
+}
+
+Guards();