@carlsebastian/jsu 1.0.34

package/src/utils/custom/utils/generator/generator.js

@@ -0,0 +1,222 @@
+import { IsPlainObjEmpty } from '../../../guards/formats/formats.js';
+import { IsBool, IsNum, IsPlainObj } from '../../../guards/data-types/data-types.js';
+import { CountOf, KeysOf } from '../../../primitives/obj/obj.accessor.js';
+import { EachOf, MapOf } from '../../../primitives/obj/obj.iterator.js';
+import Str from '../../../primitives/str/str.js';
+import Emit from '../../error/builder/error.builder.js';
+import { Clamp } from '../custom.utils.js';
+
+/**
+ *  A collection of generators module.
+ */
+export default class Generator {
+    /**
+     *  The `size` of generators in this `@class` to be used.
+     */
+    Size = 0;
+
+    /**
+     *  A configuration that allows you to customize the generators contents.
+     */
+    Conf = {
+        /**
+         * @type { boolean } - Includes or excludes numerical characters (0-9) from generator's contents.
+         */
+        numbers: true,
+
+        /**
+         *  @type { boolean } - Includes or excludes symbol characters (!@#...) from generator's contents.
+         */
+        symbols: true,
+
+        /**
+         *  @type { boolean } - Includes or excludes lowercase characters (a-z) from generator's contents.
+         */
+        lowercase: true,
+
+        /**
+         *  @type { boolean } - Includes or excludes uppercase characters (A-Z) from generator's contents.
+         */
+        uppercase: true,
+
+        /**
+         *  @type { boolean } - Whether to change its entropy from `Math.random()` into `window.crypto`.
+         *
+         *  ***Notes***:
+         *   - When entropy set to `window.crypto` it makes the generator of integer more secure but with some
+         *     performance cost. While `Math.random()` does no reduce performance but procures a non-secure random integer value.
+         */
+        secure: false,
+    };
+
+    /**
+     *  Construct the specified size and configuration to use throughout the generators.
+     *
+     *  ***Notes***:
+     *   - If the specified `size` is less than 1, it will be automatically set by the generators requirement.
+     *   - If `size` is below 0, it will be automatically converted into its absolute value.
+     *   - The maximum `size` of generator(s) are 25, it will be automatically clamped if its above the maximum.
+     *   - The generators in this class is not for security related use, as its uses `Math.random()` as its entropy.
+     *
+     *  @param { number } [Size] - The `size` of contents to generate. {Default: Generator-Specified}
+     *  @param {{ numbers?: boolean, symbols?: boolean, lowercase?: boolean, uppercase?: boolean, secure?: boolean }} [Conf] - A configuration for security and customization of the generator's contents.
+     */
+    constructor(Size = this.Size, Conf = this.Conf) {
+        Size = Math.abs(parseInt(Size));
+        const CONFKeys = ["numbers", "symbols", "lowercase", "uppercase", "secure"];
+
+        if (!IsNum(Size))
+            Emit._ArgumentError(this.constructor.name, "Size", Size, "Number");
+
+        if (!IsPlainObj(Conf))
+            Emit._ArgumentError(this.constructor.name, "Conf", Conf, "Plain Object");
+
+        if (IsPlainObjEmpty(Conf))
+            Conf = { numbers: true, symbols: true, lowercase: true, uppercase: true, secure: false };
+
+        Conf = CONFKeys.reduce((Acc, Key) => {
+            const Keys = KeysOf(Conf);
+
+            const Pos = MapOf(Keys, K => K.toLowerCase()).indexOf(Key);
+            if (Pos < 0 || !IsBool(Conf[Keys[Pos]]))
+                Acc[Key] = Key === "secure" ? false : true;
+            else
+                Acc[Key] = Conf[Keys[Pos]];
+
+            return Acc;
+        }, {});
+
+        this.Conf = Conf;
+        this.Size = Size;
+        Object.defineProperties(this, {
+            Max: {
+                value: 25,
+                writable: false, configurable: false, enumerable: false
+            },
+            Chars: {
+                value: MapOf(KeysOf(Str.Chars), K => Str.Chars[K]()),
+                writable: false, configurable: false, enumerable: false
+            }
+        });
+    }
+
+    /**
+     *  Generate a randomized integer value within the specified `maximum` value.
+     *
+     *  ***Notes***:
+     *   - If `max` is below zero (0), it will be automatically converted into its absolute value.
+     *   - When `max` is zero, the generator would add a 1 to `max` value. (E.g. max = 0 -> max = 0 + 1)
+     *
+     *  @overload
+     *  @param { number } [max] - The specified maximum value of integer to generate. (Default: 10)
+     *  @returns { number } Returns a randomized integer within the specified range.
+     */
+    /**
+     *  Generate a randomized integer value within the specified `minimum` and `maximum` range.
+     *
+     *  ***Notes***:
+     *   - If `min` and/or `max` are below zero (0), it will automatically converted into their absolute value.
+     *   - When `min` is greater than `max`, their value will be switched. (min -> max, max -> min)
+     *   - If `min` and `max` are the same, the generator would add a 1 to `max` value. (E.g. min & max = 10, max + 1);
+     *
+     *  @overload
+     *  @param { number } [min] - The specified minimum value of integer to generate. (Default: 0)
+     *  @param { number } [max] - The specified maximum value of integer to generate. (Default: 1)
+     *  @returns { number } Returns a randomized integer within the specified range.
+     */
+    RandomInteger(min = 0, max = 1) {
+        const Method = "RandomInteger";
+        let Range = MapOf([min, max], Val => Math.abs(parseInt(Val, 10)));
+
+        EachOf(Range, (R, Pos) => {
+            if (!IsNum(R))
+                Emit._ArgumentError(Method, ["min", "max"][Pos], R, "Number");
+        });
+
+        if (Range[0] > Range[1])
+            [Range[0], Range[1]] = [Range[1], Range[0]];
+
+        if (Range[0] === Range[1])
+            Range[1]++;
+
+        const R = (Range[1] - Range[0]) + 1;
+        if (this.Conf.secure) {
+            // console.log(`--[GENERATING IN ${this.Conf.secure ? "SECURE-MODE" : "NON-SECURE-MODE"}]--`);
+            const Arr = new Uint32Array(1); // 32-bit
+            const MaxUInt = 0xFFFFFFFF; // 32-bit
+            crypto.getRandomValues(Arr);
+            return Range[0] + Math.floor((Arr[0] / (MaxUInt + 1)) * R);
+        }
+
+        return Math.floor(Math.random() * (Range[1] - Range[0] + 1) + Range[0]);
+    }
+
+    /**
+     *  Generates a set of randomized characters (numeric & symbol characters are not included) within the specified `size`.
+     *
+     *  ***Notes***:
+     *   - If `size` is below 6 or higher than 25, it will be automatically clamped between this value.
+     *   - If both of configuration `lowercase` and `uppercase` as set to false, the generated will use `uppercase` as default.
+     *
+     *  @returns { string } The generated random characters.
+     */
+    RandomCharacters() {
+        const Method = "RandomCharacters", CONFKeys = ["lowercase", "uppercase"];
+        let [Size, Conf] = [
+            Clamp(this.Size, 6, this.Max),
+            { lowercase: this.Conf.lowercase, uppercase: this.Conf.uppercase }
+        ];
+
+        const Map = Conf.lowercase ? Conf.uppercase ? (this.Chars[CountOf(this.Chars) - 1] + this.Chars[0]) : this.Chars[0] : this.Chars[CountOf(this.Chars) - 1];
+
+        return Array.from({ length: Size }, (_, I) => {
+            return Map[this.RandomInteger(Map.length - 1)];
+        }).join("");
+    }
+
+    /**
+     *  Generates a randomized token string that can be used as temporary id, lobby, etc., and returns it.
+     *
+     *  ***Notes***:
+     *   - If `size` is below 7 or higher than 25, it will be automatically clamped between this value.
+     *   - If both of configuration `lowercase` and `uppercase` as set to false, the generated will use `uppercase` as default.
+     *
+     *  @returns { string } The generated token.
+     */
+    NewToken() {
+        const Method = "NewToken";
+        let [Size, Conf] = [Clamp(this.Size, 7, this.Max), this.Conf], Token = "";
+        const CharsOnly = (Conf.lowercase || Conf.uppercase) && (!Conf.numbers && !Conf.symbols);
+        const Chars = Conf.uppercase ? Conf.lowercase ? (this.Chars[CountOf(this.Chars) - 1] + this.Chars[0]) : this.Chars[CountOf(this.Chars) - 1] : this.Chars[0];
+        const Map = Chars + (Conf.numbers ? Conf.symbols ? (this.Chars[1] + this.Chars[2]) : this.Chars[1] : this.Chars[2]);
+
+        for (let I = 0; I < Size; I++) {
+            if (CharsOnly) {
+                Token += Chars[this.RandomInteger(Chars.length - 1)];
+                continue;
+            }
+
+            if (/([A-Za-z]{6,})$/.test(Token)) {
+                const NS = (Conf.numbers ? this.Chars[1] : "") + (Conf.symbols ? this.Chars[2] : "");
+                Token += NS[this.RandomInteger(NS.length - 1)];
+                continue;
+            }
+
+            if (Conf.symbols && /([^A-Za-z\d]{3,})$/.test(Token)) {
+                const CN = Chars + (Conf.numbers ? this.Chars[1] : "");
+                Token += CN[this.RandomInteger(CN.length - 1)];
+                continue;
+            }
+
+            if (Conf.numbers && /\d{2,}$/.test(Token)) {
+                const CS = Chars + (Conf.symbols ? this.Chars[2] : "");
+                Token += CS[this.RandomInteger(CS.length - 1)];
+                continue;
+            }
+
+            Token += Map[this.RandomInteger(Map.length - 1)];
+        }
+
+        return Token;
+    }
+}

package/src/utils/dom/attr/attr.class.js

@@ -0,0 +1,186 @@
+import Emit from '../../custom/error/builder/error.builder.js';
+import { IsStrEmpty } from '../../guards/formats/formats.js';
+import { IsArr, IsElement, IsStr } from '../../guards/data-types/data-types.js';
+import { CountOf } from '../../primitives/obj/obj.accessor.js';
+
+/**
+ *  Access the `DOMTokenList` ('class') attribute of the specified target element.
+ *
+ *  @param { Element } element - The target element.
+ *  @returns The response object methods for mutating class of element.
+ *
+ *  @throws {ArgumentError} - When there's no element provided or an invalid element provided.
+ *  @throws {NotSupportedError} - When the provided element does not support 'classList' property.
+ */
+export default function ClassOf(element) {
+    const Method = "ClassOf";
+
+    if (!IsElement(element))
+        Emit._ArgumentError(Method, "element", element, "Element");
+
+    if (!("classList" in element))
+        Emit._NotSupportedError(Method, "classList");
+
+    const ClassList = element.classList;
+    return {
+        /**
+         *  Checks if the specified `class` token is existing at the element's `DOMTokenList`.
+         *
+         *  @overload
+         *  @param { string } token - The token to check.
+         *  @returns { boolean } The response state result of validation.
+         */
+        /**
+         *  Checks if the specified collection of `class` tokens are existing at the element's `DOMTokenList`.
+         *
+         *  @overload
+         *  @param { string[] } tokens - The collection of tokens to check.
+         *  @returns { boolean } The response state result of validation.
+         */
+        Has(...tokens) {
+            const Caller = `${Method}.Has`, ICtr = CountOf(tokens);
+
+            if (ICtr === 0)
+                return false;
+
+            if (ICtr === 1)
+                return IsStr(tokens[0]) && !IsStrEmpty(tokens[0]) && ClassList.contains(tokens[0]);
+
+            return tokens.every(token =>
+                IsStr(token) && !IsStrEmpty(token) && ClassList.contains(token)
+            );
+        },
+
+        /**
+         *  Retrieve and returns the collection of element's `DOMTokenList`.
+         *
+         *  @returns { DOMTokenList } The response object result of retrieval.
+         */
+        List() {
+            return ClassList;
+        },
+
+        /**
+         *  Removes the specified `class` token from the element's `DOMTokenList`.
+         *
+         *  @overload
+         *  @param { string } token - The token to remove.
+         *  @returns { boolean } The response state result of token removal.
+         */
+        /**
+         *  Removes the specified collection of `class` tokens from the element's `DOMTokenList`.
+         *
+         *  @overload
+         *  @param { string[] } tokens - The collection of tokens to remove.
+         *  @returns { boolean } The response state result of tokens removal.
+         */
+        Remove(...tokens) {
+            const Caller = `${Method}.Remove`, ICtr = CountOf(tokens);
+
+            if (ICtr === 0)
+                return false;
+
+            for (const token of tokens) {
+                if (!IsStr(token)) {
+                    console.warn(`${Caller}(@${ICtr > 1 ? "tokens" : "token"}: ${ICtr > 1 ? `[${token}]` : token}): Expected to be in string format! (Skipped)`);
+                    continue;
+                }
+
+                if (IsStrEmpty(token))
+                    continue;
+
+                ClassList.remove(token);
+            }
+
+            return true;
+        },
+
+        /**
+         *  Set (or update) the specified `class` token from the element's `DOMTokenList`.
+         *
+         *  @overload
+         *  @param { string } token - The token to set (or update).
+         *  @returns { void }
+         */
+        /**
+         *  Set (or update) the specified collection of `class` tokens from the element's `DOMTokenList`.
+         *
+         *  @overload
+         *  @param { string[] } tokens - The collection of tokens to set (or update).
+         *  @returns { void }
+         */
+        Set(...tokens) {
+            const Caller = `${Method}.Set`, ICtr = CountOf(tokens);
+
+            if (ICtr === 0)
+                return;
+
+            for (const token of tokens.flat(Infinity)) {
+                if (!IsStr(token)) {
+                    console.warn(`${Caller}(@${ICtr > 1 ? "tokens" : "token"}: ${ICtr > 1 ? `[${token}]` : token}): Expected to be in string format! (Skipped)`);
+                    continue;
+                }
+
+                if (IsStrEmpty(token))
+                    continue;
+
+                ClassList.add(token);
+            }
+        },
+
+        /**
+         *  Toggles the state of the specified `class` token from the element's `DOMTokenList`.
+         *
+         *  ***States***:
+         *   - If the specified token is not currently existing in the element's `DOMTokenList`,
+         *     it will be added automatically to the element's `DOMTokenList`, or else, if present, it will be removed
+         *     from the element's `DOMTokenList`.
+         *
+         *  @overload
+         *  @param { string } token - The token to toggle.
+         *  @param { boolean } [forceState] - A state to set forcefully from the token despite its current state.
+         *  @returns { boolean } The response state result of toggled state.
+         */
+        /**
+         *  Toggles the state of the specified collection of `class` tokens from the element's `DOMTokenList`.
+         *
+         *  ***States***
+         *   - If a certain token from the collection of tokens is not currently existing in the element's `DOMTokenList`,
+         *     it will be added automatically to the element's `DOMTokenList`, or else, if present, it will be removed
+         *     from the element's `DOMTokenList`.
+         *
+         *  @overload
+         *  @param { string[] } tokens - The collection of tokens to toggle.
+         *  @param { boolean } [forceState] - A state to set forcefully from the token despite its current state.
+         *  @returns { boolean } The response state result of toggled states.
+         */
+        Toggle(tokens, forceState) {
+            const Caller = `${Method}.Toggle`;
+
+            if (!IsArr(tokens))
+                tokens = [tokens];
+
+            const ICtr = CountOf(tokens);
+            if (ICtr === 0)
+                return false;
+
+            if (forceState && typeof forceState !== "boolean")
+                Emit._ArgumentError(Caller, "forceState", forceState, "Boolean");
+
+            const Response = [];
+            for (const token of tokens) {
+                if (!IsStr(token)) {
+                    console.warn(`${Caller}(@${ICtr > 1 ? "tokens" : "token"}: ${ICtr > 1 ? `[${token}]` : token}): Expected to be in string format! (Skipped)`);
+                    continue;
+                }
+
+                if (IsStrEmpty(token))
+                    continue;
+
+                Response.push(forceState ? ClassList.toggle(token, forceState) : ClassList.toggle(token));
+            }
+
+            return CountOf(Response) > 1 ? Response : Response[0];
+        },
+    }
+}

package/src/utils/dom/attr/attr.id.js

@@ -0,0 +1,64 @@
+import Emit from '../../custom/error/builder/error.builder.js';
+import { IsStrEmpty } from '../../guards/formats/formats.js';
+import { IsElement, IsNullOrUndefined, IsStr } from '../../guards/data-types/data-types.js';
+
+/**
+ *  Access the `id` attribute of element and returns a set of methods for it.
+ *
+ *  @param { Element } element - The element to access the `id` attribute.
+ *  @returns The set of methods for `id` attribute.
+ */
+export default function IdOf(element) {
+    const Method = "IdOf";
+
+    if (!IsElement(element))
+        Emit._ArgumentError(Method, "element", element, "Element");
+
+    return {
+        /**
+         *  The current unique `id` of element.
+         *
+         *  ***Note***:
+         *   - If the element has no `id`, the default value would be '\<NO_ID\>'.
+         */
+        Value: IsStrEmpty(element.id) || IsNullOrUndefined(element.id) ? "\<NO_ID\>" : element.id,
+
+        /**
+         *  Removes the `id` of the element.
+         *
+         *  @returns { boolean } The response state result of removal `id` process.
+         */
+        Remove() {
+            if (!element.hasAttribute("id")) {
+                console.warn(`${Method}.Remove(@element): Does not currently have an id! (Exited)`);
+                return false;
+            }
+
+            element.removeAttribute("id");
+            this.Value = "<NO_ID>";
+            return true;
+        },
+
+        /**
+         *  Set the current unique `id` of the element.
+         *
+         *  @param id - The new unique `id` to set.
+         *  @returns { string } The new current unique `id` of element.
+         */
+        Set(id = "") {
+            const Caller = `${Method}.Set`;
+
+            if (!IsStr(id))
+                Emit._ArgumentError(Caller, "id", id, "String");
+
+            if (IsStrEmpty(id)) {
+                element.removeAttribute("id");
+                this.Value = "<NO_ID>";
+                return "<NO_ID>";
+            }
+
+            element.setAttribute("id", id);
+            this.Value = id;
+        },
+    }
+}

package/src/utils/dom/attr/attr.style.js

@@ -0,0 +1,128 @@
+import Emit from '../../custom/error/builder/error.builder.js';
+import { IsPlainObjEmpty, IsStrEmpty } from '../../guards/formats/formats.js';
+import { IsArr, IsElement, IsPlainObj, IsStr } from '../../guards/data-types/data-types.js';
+import { CountOf } from '../../primitives/obj/obj.accessor.js';
+
+/**
+ *  Access the element's style object and returns a collection object methods for it.
+ *
+ *  @param { Element } element - The target element.
+ *  @returns The response object method for mutating style of element.
+ */
+export default function StyleOf(element) {
+    const Method = "StyleOf";
+
+    if (!IsElement(element))
+        Emit._ArgumentError(Method, "element", element, "Element");
+
+    if (!("style" in element))
+        Emit._NotSupportedError(Method, "style");
+
+    /** @type { CSSStyleDeclaration } */
+    const StyleObj = element.style;
+    return {
+        /**
+         *  Set and apply the CSSStyle object properties from the target element.
+         *
+         *  @param { CSSStyleDeclaration } CSSObj - The CSSStyle object properties.
+         *  @returns { void }
+         */
+        Set(CSSObj = {}) {
+            const Caller = `${Method}.Set`;
+
+            if (!IsPlainObj(CSSObj))
+                Emit._ArgumentError(Caller, "CSSObj", CSSObj, "Plain Object ({})");
+
+            if (IsPlainObjEmpty(CSSObj))
+                return;
+
+            for (const [SK, SV] of Object.entries(CSSObj)) {
+                if (!(SK in StyleObj)) {
+                    console.warn(`${Caller}(@CSSObj: { ${SK}: ... }): Unknown CSS property! (Skipped)`);
+                    continue;
+                }
+
+                if (!IsStr(SV)) {
+                    console.warn(`${Caller}(@CSSObj: { ${SK}: ${SV} }): Expects a string format value! (Skipped)`);
+                    continue;
+                }
+
+                if (IsStrEmpty(SV)) {
+                    console.warn(`${Caller}(@CSSObj: { ${SK}: "" }): Expects a value! (Skipped)`);
+                    continue;
+                }
+
+                StyleObj[SK] = SV;
+            }
+        },
+
+        /**
+         *  Removes the specified CSS property from the target element.
+         *
+         *  @overload
+         *  @param { keyof CSSStyleDeclaration } CSSProperty - The CSS property to remove.
+         *  @returns { boolean }
+         */
+        /**
+         *  Removes the specified CSS properties from the target element.
+         *
+         *  @overload
+         *  @param { Array<keyof CSSStyleDeclaration> } CSSProperties - The CSS properties to remove.
+         *  @returns { boolean }
+         */
+        Remove(...CSSProperties) {
+            const Caller = `${Method}.Remove`, ICtr = CountOf(CSSProperties), P = ICtr > 1 ? "CSSProperties" : "CSSProperty";
+
+            if (ICtr === 0)
+                return false;
+
+            for (const SK of CSSProperties) {
+                const PV = ICtr > 1 ? `[${SK}]` : `: ${SK}`
+                if (!IsStr(SK)) {
+                    console.warn(`${Caller}(@${P}${PV}): Expects a CSS property to be in string format! (Skipped)`);
+                    continue;
+                }
+
+                if (IsStrEmpty(SK)) {
+                    console.warn(`${Caller}(@${P}${PV}): Expects a non-empty value! (Skipped)`);
+                    continue;
+                }
+
+                if (!(SK in StyleObj)) {
+                    console.warn(`${Method}(@${P}${PV}): Unknown CSS Property! (Skipped)`);
+                    continue;
+                }
+
+                StyleObj.removeProperty(SK);
+            }
+
+            return true;
+        },
+
+        /**
+         *  Returns the current value of the specified CSSStyle property.
+         *
+         *  @param { keyof CSSStyleDeclaration } CSSProperty - The CSS property to retrieve.
+         *  @returns { string | null }
+         */
+        Get(CSSProperty) {
+            const Caller = `${Method}.Get`;
+            if (!IsStr(CSSProperty))
+                Emit._ArgumentError(Caller, "CSSProperty", CSSProperty, "String");
+
+            if (IsStrEmpty(CSSProperty)) {
+                console.warn(`${Caller}(@CSSProperty: ${CSSProperty}): Expects a non-empty string key value! (Exited with null)`);
+                return null;
+            }
+
+            if (!(CSSProperty in StyleObj)) {
+                console.warn(`${Caller}(@CSSProperty: ${CSSProperty}): Unknown CSS property! (Exited with null)`);
+                return null;
+            }
+
+            const Value = StyleObj[CSSProperty];
+
+            return IsStrEmpty(Value) ? "<NO_DATA>" : Value;
+        }
+    }
+}

package/src/utils/dom/dom.js

@@ -0,0 +1,29 @@
+import { DefineProperty, Global, NameOf } from '../custom/utils/custom.utils.js';
+import ClassOf from './attr/attr.class.js';
+import StyleOf from './attr/attr.style.js';
+import Create from './element/create/element.create.js';
+import VerifyTag from './element/tag-verifier/verifier.js';
+import Mount from './lifecycle/mount.js';
+import Unmount from './lifecycle/unmount.js';
+import { Select, SelectAll } from "./element/query/dom.query.js";
+import GetElementBy from "./element/getElementBy/dom.getElementBy.js";
+import { IsNullOrUndefined, IsPropertyAt } from '../guards/data-types/data-types.js';
+import { IsStrEmpty } from '../guards/formats/formats.js';
+
+/**
+ *  A customized or enhanced collection of `DOM` methods.
+ */
+export default function DOM() {
+    const DomAPI = {};
+
+    for (const Method of [ClassOf, Create, GetElementBy, Mount, Unmount, Select, SelectAll, StyleOf, VerifyTag]) {
+        const Key = NameOf(Method);
+
+        if (!IsNullOrUndefined(Key) && !IsStrEmpty(Key) && !IsPropertyAt(DomAPI, Key) && !(Key === "(ANONYMOUS)"))
+            DefineProperty(DomAPI, Key, Method, "med");
+    }
+
+    Global("DOM", DomAPI, "soft");
+}
+
+DOM();