@carlsebastian/jsu 1.0.34

package/src/utils/custom/custom.js

@@ -0,0 +1,20 @@
+import { IsNullOrUndefined, IsPropertyAt } from '../guards/data-types/data-types.js';
+import { IsStrEmpty } from '../guards/formats/formats.js';
+import * as CustomUtils from "./utils/custom.utils.js";
+import Generator from './utils/generator/generator.js';
+
+/**
+ *  Attach a collection of customized `@modules` and/or `@utilities` to `globalThis`.
+ */
+export default function Custom() {
+    const CustomAPI = {};
+
+    for (const Method of [...Object.values(CustomUtils), Generator]) {
+        const Key = CustomUtils.NameOf(Method);
+        if (!IsNullOrUndefined(Key) && !IsStrEmpty(Key) && !IsPropertyAt(CustomAPI, Key) && !(Key === "(ANONYMOUS)"))
+            CustomUtils.DefineProperty(CustomAPI, Key, Method, "med");
+    }
+
+    CustomUtils.Global("Custom", CustomAPI, "soft");
+}
+Custom();

package/src/utils/custom/error/builder/error.builder.js

@@ -0,0 +1,181 @@
+import * as _ from "../constructor/error.custom.js";
+
+/* Meta Builder */
+/**
+ *  @param { string } message
+ *  @param { string } c_message
+ *  @param { string } emitter_id
+ *  @param { string } argument_id
+ *  @param { Record<string, any> } otherArgument
+ *  @param { string } [guide]
+ */
+const BuildMeta = (message, c_message, emitter_id, argument_id, otherArgument, guide) => {
+    /** @type { MetaBaseObject<{}> } */
+    const Meta = {
+        Message: message,
+        Context: {
+            Message: c_message,
+            Emitter: emitter_id
+        },
+        Args: {
+            Id: argument_id
+        },
+        Guide: guide
+    }
+
+    if ((typeof otherArgument === "object" && !Array.isArray(otherArgument) &&
+        !(otherArgument === null || otherArgument === undefined) &&
+        !(otherArgument instanceof Map || otherArgument instanceof Set)) &&
+        Object.values(otherArgument).length > 0)
+        Object.assign(Meta.Args, otherArgument);
+
+    return Meta;
+}
+
+/**
+ *  Contains a `@custom` or `@enhance` collection version of `error` builder.
+ *
+ *  Note:
+ *   - The contents of available error builder(s) in this object are fixed, only the specified or
+ *     required value are changing.
+ */
+const Emit = {
+    /**
+     *  Name of this object.
+     */
+    name: "Emit",
+
+    /**
+     *  Builds and emit the contents of `@ArgumentError`.
+     *
+     *  @param { string } emitter_id - The id of object that throws this error.
+     *  @param { string } argument_id - The id of object's argument (either an object or parameter) that triggered or cause the error.
+     *  @param { Array<string> } [expected_arguments] - The expected argument(s) that should be received by the argument.
+     */
+    _ArgumentError(emitter_id, argument_id, received_argument, ...expected_argument) {
+        throw new _.ArgumentError(BuildMeta(
+            `An argument error has occurred at ${emitter_id}()! ${emitter_id} expects a '${expected_argument.join(" | ")}' not '${received_argument}'.`,
+            `${emitter_id}(@${argument_id}: INVALID_ARGUMENT) {...}`,
+            emitter_id, argument_id,
+            { ReceivedArgument: received_argument, ExpectedArgument: expected_argument },
+            `Ensure to provide the expected argument(s) from this '${argument_id}' argument.`
+        ));
+    },
+
+    /**
+     *  Builds and emit the contents of `@IndexOutOfBoundsError`.
+     *
+     *  @param { string } emitter_id - The id of object that throws this error.
+     *  @param { string } argument_id - The id of object's argument (either an object or parameter) that triggered or cause the error.
+     *  @param { number } [index] - The index that the argument received that is out-of-bounds. (Undefined: -1)
+     *  @param { number } [maximum_bound] - The maximum bound index of the argument object value that an index can be. (Undefined: -1)
+     */
+    _IndexOutOfBoundsError(emitter_id, argument_id, index = -1, maximum_bound = -1) {
+        throw new _.IndexOutOfBoundsError(BuildMeta(
+            `A out-of-bounds index has been received at ${emitter_id}()!`,
+            `${emitter_id}(@${argument_id}[${index}]: OUT_OF_BOUNDS) {...}`,
+            emitter_id, argument_id, { Index: index, MaxBound: maximum_bound },
+            `Ensure to provide an index that is within the bounds of this ${argument_id} argument.`
+        ));
+    },
+
+    /**
+     *  Builds an emit the contents of `@InvalidPropertyError`.
+     *
+     *  @param { string } emitter_id - The id of object that throws this error.
+     *  @param { string } argument_id - The id of object's argument (either an object or parameter) that triggered or cause the error.
+     *  @param { string } property_id - The invalid property that the argument received.
+     */
+    _InvalidPropertyError(emitter_id, argument_id, property_id) {
+        throw new _.InvalidPropertyError(BuildMeta(
+            `An invalid property is found at ${emitter_id}()!`,
+            `${emitter_id}(@${argument_id}[${property_id}]: INVALID_PROPERTY) {...}`,
+            emitter_id, argument_id, { PropertyId: property_id },
+            `Ensure to provide a valid or available property (provided by its intellisense) from this '${argument_id}' argument object at ${emitter_id}.`
+        ));
+    },
+
+    /**
+     *  Builds and emit the contents of `@MissingParameterError`.
+     *
+     *  @param { string } emitter_id - The id of object that throws this error.
+     *  @param { string } argument_id - The id of object's argument (either an object or parameter) that triggered or cause the error.
+     *  @param { any } [argument_value] - The current value of the argument.
+     */
+    _MissingParameterError(emitter_id, argument_id, argument_value) {
+        throw new _.MissingParameterError(BuildMeta(
+            `A missing parameter is found at ${emitter_id}!`,
+            `${emitter_id}(@${argument_id}: MISSING) {...}`,
+            emitter_id, argument_id, { Value: argument_value },
+            `Ensure to provide or assign a value from this '${argument_id}' argument at ${emitter_id}.`
+        ));
+    },
+
+    /**
+     *  Builds and emit the contents of `@MissingPropertyError`.
+     *
+     *  @param { string } emitter_id - The id of object that throws this error.
+     *  @param { string } argument_id - The id of object's argument (either an object or parameter) that triggered or cause the error.
+     *  @param { string } property_id - The missing property that the argument received.
+     */
+    _MissingPropertyError(emitter_id, argument_id, property_id) {
+        throw new _.MissingPropertyError(BuildMeta(
+            `A missing property is found at ${emitter_id}()!`,
+            `${emitter_id}(@${argument_id}[${property_id}]: MISSING_PROPERTY) {...}`,
+            emitter_id, argument_id, { MissingPropertyId: property_id },
+            `Ensure to provide the property '${property_id}' and its dedicated value from this '${argument_id}' argument object at ${emitter_id}.`
+        ));
+    },
+
+    /**
+     *  Builds and emit the contents of `@NoSuchElementTagError`.
+     *
+     *  @param { string } emitter_id - The id of object that throws this error.
+     *  @param { string } argument_id - The id of object's argument (either an object or parameter) that triggered or cause the error.
+     *  @param { string } tag - The tag that is not known or exists.
+     *  @param { "HTMLElement" | "SVGElement" | "MathMLElement" } tagOf - The instance/type of element
+     */
+    _NoSuchElementTagError(emitter_id, argument_id, tag, tagOf) {
+        tagOf = typeof tagOf == "string" && tagOf.trim().length > 0 ? tagOf : "NOT_PROVIDED";
+
+        throw new _.NoSuchElementTagError(BuildMeta(
+            `A non-qualified tag of ${tagOf} is found at ${emitter_id}()!`,
+            `${emitter_id}(@tag: ${tag} - UNKNOWN_TAG_OF_${tagOf.toUpperCase()}) {...}`,
+            emitter_id, argument_id, { Tag: tag, TagOf: tagOf },
+            `Ensure to only provide the valid tag of ${tagOf} at this @${argument_id} parameter.`
+        ));
+    },
+
+    /**
+     *  Builds and emit the contents of `@NotSupportedError`.
+     *
+     *  @param { string } emitter_id - The id of object that throws this error.
+     *  @param { string } unsupported_id - The id of the unsupported object that is being accessed.
+     */
+    _NotSupportedError(emitter_id, unsupported_id) {
+        throw new _.NotSupportedError(BuildMeta(
+            `A not supported method or object is being accessed!`,
+            `${emitter_id}.${unsupported_id}() { NOT_SUPPORTED }`,
+            emitter_id, unsupported_id,
+            `Ensure to upgrade your browser environment or your Javascript version.`
+        ));
+    },
+
+    /**
+     *  Builds and emit the contents of `@UnknownPropertyError`.
+     *
+     *  @param { string } emitter_id - The id of object that throws this error.
+     *  @param { string } argument_id - The id of object's argument (either an object or parameter) that triggered or cause the error.
+     *  @param { string } property_id - The unknown property id that is trying to be accessed.
+     */
+    _UnknownPropertyError(emitter_id, argument_id, property_id) {
+        throw new _.UnknownPropertyError(BuildMeta(
+            `Cannot access a unknown or non-existing property at ${emitter_id}()!`,
+            `${emitter_id}(@${argument_id}: { ${property_id}: UNKNOWN_OR_NOT_FOUND }) {...}`,
+            emitter_id, argument_id, { PropertyId: property_id },
+            `Ensure to only access a existing key-pair or property at this '${argument_id}' argument object at ${emitter_id}.`
+        ));
+    }
+}
+
+export default Emit;

package/src/utils/custom/error/constructor/error.base.js

@@ -0,0 +1,71 @@
+import { MissingParameterError } from './error.custom.js';
+
+/* -- Default Values -- */
+const Base = (id) => `_NO_${typeof id === "string" ? id.toUpperCase() : String(id).toUpperCase()}_PROVIDED_`;
+const Default = {
+    Message: Base("message"),
+    Context: Base("context"),
+    Args: Base("args"),
+    Guide: Base("guide")
+}
+
+/* -- Meta Data Property Validation -- */
+
+/**
+ *  @param { string | Record<string, unknown> | Array<unknown> } metaValue
+ *  @param { any } defaultValue
+ */
+const ValidateMetaProperty = (metaValue, defaultValue) => {
+    if (metaValue === null || metaValue === undefined)
+        return defaultValue;
+
+    if (typeof metaValue === "string" && metaValue.trim().length <= 0)
+        return defaultValue;
+
+    if (typeof metaValue === "object" && ((Array.isArray(metaValue) && metaValue.length <= 0) || Object.values(metaValue).length <= 0))
+        return defaultValue;
+
+    return metaValue;
+}
+
+/**
+ * A centralized custom error class for custom and/or modified error classes.
+ * @template {Record<string, any>} OtherArgs
+ */
+export default class CustomError extends Error {
+    Args = { Id: undefined };
+    Context = {
+        Message: undefined,
+        Emitter: undefined
+    };
+    Guide = "";
+    Message = "";
+    Name = "CustomError";
+    TimeStamp = new Date();
+    /**
+     * @param { MetaBaseObject<OtherArgs> } Meta
+     */
+    constructor(Meta) {
+        if (Meta.Message === null || Meta.Message === undefined || typeof Meta.Message === "string" && Meta.Message.trim().length === 0)
+            throw new MissingParameterError({
+                Message: `A message must be provided for the error!`,
+                Context: {
+                    Message: `CustomError.constructor(Meta: { Message: undefined } [REQUIRED]) {...}`,
+                    Emitter: "CustomError.constructor"
+                },
+                Args: {
+                    Id: "Meta",
+                    Value: Meta
+                },
+                Guide: "Ensure to provide the 'Message' property at 'Meta' object!"
+            });
+
+        super(Meta.Message);
+        this.Name = ValidateMetaProperty(Meta.Name, this.constructor.name);
+        this.Message = ValidateMetaProperty(Meta.Message, Default.Message);
+        this.Context = ValidateMetaProperty(Meta.Context, Default.Context);
+        this.Args = ValidateMetaProperty(Meta.Args, Default.Args);
+        this.Guide = ValidateMetaProperty(Meta.Guide, Default.Guide);
+        this.TimeStamp = new Date();
+    }
+}

package/src/utils/custom/error/constructor/error.custom.js

@@ -0,0 +1,107 @@
+import CustomError from './error.base.js';
+
+/**
+ *  A custom error class for invalid or unknown arguments.
+ *  @class Argument
+ *  @extends { CustomError<ArgumentErrorMeta> }
+ */
+export class ArgumentError extends CustomError {
+    /**
+     * @param { ArgumentErrorMeta } meta
+     */
+    constructor(meta) {
+        super(meta);
+    }
+}
+
+/**
+ *  A custom error class for invalid key-pair object.
+ *
+ *  @extends { CustomError<InvalidPropertyErrorMeta> }
+ */
+export class InvalidPropertyError extends CustomError {
+    /**
+     *  @param { InvalidPropertyErrorMeta } meta
+     */
+    constructor(meta) {
+        super(meta);
+    }
+}
+
+/**
+ *  A custom error class for out-of-bounds index accessor at object(s).
+ *  @extends { CustomError<IndexOutOfBoundsErrorMeta> }
+ */
+export class IndexOutOfBoundsError extends CustomError {
+    /**
+     *  @param { IndexOutOfBoundsErrorMeta } meta
+     */
+    constructor(meta) {
+        super(meta);
+    }
+}
+
+/**
+ *  A custom error class for missing parameter value.
+ *  @extends { CustomError<MissingParameterErrorMeta> }
+ */
+export class MissingParameterError extends CustomError {
+    /**
+     *  @param { MissingParameterErrorMeta } meta
+     */
+    constructor(meta) {
+        super(meta);
+    }
+}
+
+/**
+ *  A custom error class for missing key-pair object.
+ *  @extends { CustomError<MissingPropertyErrorMeta> }
+ */
+export class MissingPropertyError extends CustomError {
+    /**
+     *  @param { MissingPropertyErrorMeta } meta
+     */
+    constructor(meta) {
+        super(meta);
+    }
+}
+
+/**
+ *  A custom error class for not supported method.
+ *  @extends { CustomError<NotSupportedErrorMeta> }
+ */
+export class NotSupportedError extends CustomError {
+    /**
+     *  @param { NotSupportedErrorMeta } meta
+     */
+    constructor(meta) {
+        super(meta);
+    }
+}
+
+/**
+ *  A custom error class for unknown key-pair object.
+ *  @extends { CustomError<UnknownPropertyErrorMeta> }
+ */
+export class UnknownPropertyError extends CustomError {
+    /**
+     *  @param { UnknownPropertyErrorMeta } meta
+     */
+    constructor(meta) {
+        super(meta);
+    }
+}
+
+/**
+ *  A custom error class for unknown element tag.
+ *  @extends { CustomError<NoSuchElementTagErrorMeta> }
+ */
+export class NoSuchElementTagError extends CustomError {
+    /**
+     *  @param { NoSuchElementTagErrorMeta } meta
+     */
+    constructor(meta) {
+        super(meta);
+    }
+}

package/src/utils/custom/error/error.js

@@ -0,0 +1,23 @@
+import * as CustomErrorClasses from "./constructor/error.custom.js";
+import Emit from './builder/error.builder.js';
+import { DefineProperty, Global, NameOf } from '../utils/custom.utils.js';
+import { IsNullOrUndefined, IsPropertyAt, IsStr } from '../../guards/data-types/data-types.js';
+import { IsStrEmpty } from '../../guards/formats/formats.js';
+
+/**
+ *  Returns a customized collection of `@error_class_modules` and `@error_class_builder_modules`.
+ */
+function ERROR() {
+    const ErrorAPI = {};
+    const Constructors = { name: "Constructors", ...CustomErrorClasses };
+
+    for (const Method of [Constructors, Emit]) {
+        const Key = NameOf(Method);
+        if (!IsNullOrUndefined(Key) && !IsStrEmpty(Key) && !IsPropertyAt(ErrorAPI, Key) && !(Key === "(ANONYMOUS)"))
+            DefineProperty(ErrorAPI, NameOf(Method), Method, "med")
+    }
+
+    Global("ERROR", ErrorAPI, "soft");
+}
+
+ERROR();

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

@@ -0,0 +1,150 @@
+import { IsNullOrUndefined, IsNum, IsPlainObj, IsStr } from '../../guards/data-types/data-types.js';
+import { IsStrEmpty } from '../../guards/formats/formats.js';
+import { EachOf, MapOf, SomeOf } from '../../primitives/obj/obj.iterator.js';
+import Emit from '../error/builder/error.builder.js';
+
+/**
+ *  Retrieves the `name` property of the specified `function` or other `object` that supports this property.
+ *
+ *  ***Notes***:
+ *   - This is not case-sensitive for `name` property of the specified object as long as it has it.
+ *
+ *  @param {{}} obj - The object to get the name from.
+ *  @returns { string } Returns a '(ANONYMOUS)' value as default when the specified object does not have or support the `name` property.
+ */
+export function NameOf(obj) {
+    let Key = null;
+
+    const Keys = Object.getOwnPropertyNames(obj).filter(K => K.length === 4);
+    for (const K of Keys) {
+        if (!(/^(N|n)/.test(K)))
+            continue;
+
+        if (!(/(A|a)/.test(K.charAt(1))))
+            continue;
+
+        if (!(/(M|m)/.test(K.charAt(2))))
+            continue;
+
+        if (!(/(E|e)/.test(K.charAt(K.length - 1))))
+            continue;
+
+        Key = K;
+        break;
+    }
+
+    return !IsStr(Key) ? "(Anonymous)" : obj[Key];
+}
+
+/**
+ *  Returns the `constructor` or `type` of the specified `argument`.
+ *
+ *  @param { any } arg - The argument to get its constructor or type.
+ *  @returns { string | undefined } Returns a stringified `constructor` and/or `type` of the argument.
+ */
+export function ConstructorOrTypeOf(arg) {
+    if (IsNullOrUndefined(arg))
+        return undefined;
+
+    return !IsNullOrUndefined(arg["constructor"]) ? arg["constructor"]["name"] : typeof arg;
+}
+
+/**
+ *  Clamps the given `number` value to its specified `minimum` and `maximum` value that it can have.
+ *
+ *  ***Notes***:
+ *   - If the specified `value`, `min` and `max` are not a valid numeric value, it will return a `-1` value.
+ *   - If the specified `min` value is greater than the specified `max` value, it will swap their values.
+ *
+ *  @param { number } value - The current numeric value.
+ *  @param { number } min - The minimum value that the current numeric value can have.
+ *  @param { number } max - The maximum value that the current numeric value can have.
+ *  @returns { number } The clamped numeric value.
+ */
+export function Clamp(value, min = 0, max = 1) {
+    let RANGE = MapOf([value, min, max], VAL => parseInt(VAL));
+
+    // ❌ - Exits if value, minimum, and/or maximum are not valid numeric values.
+    if (SomeOf(RANGE, VAL => !IsNum(VAL)))
+        return -1;
+
+    if (RANGE[1] > RANGE[2] || RANGE[2] < RANGE[1]) {
+        const TEMP = RANGE[1];
+        RANGE[1] = RANGE[2];
+        RANGE[2] = TEMP;
+    }
+
+    return Math.min(Math.max(RANGE[0], RANGE[1]), RANGE[2]);
+}
+
+/**
+ *  Define the given key-pair from the object.
+ *
+ *  @param {{ [p: string]: any }} obj - The object to define the key-pair at.
+ *  @param { string } key - The access key of key-pair item.
+ *  @param { * } data - The data of key-pair item.
+ *  @param { "hard" | "med" | "soft" | "def" } [opt] - Optional on how to store the key-pair dat at `globalThis` API. (writable, configurable, enumerable)
+ */
+export function DefineProperty(obj = {}, key, data, opt = "def") {
+    const Method = "DefineProperty";
+
+    if (!IsPlainObj(obj))
+        obj = {};
+
+    if (!IsStr(key))
+        Emit._ArgumentError(Method, "key", key, "String");
+
+    if (IsStrEmpty(key)) {
+        console.warn(`${Method}(@key: \'\'): Expects a not-empty-string! (Exited)`);
+        return;
+    }
+
+    const CONF = {
+        Writable: true,
+        Configurable: true,
+        Enumerable: true
+    }
+    if (!IsStr(opt) || IsStrEmpty(opt) || !(opt === "def" || opt === "hard" || opt === "med" || opt === "soft"))
+        opt = "def";
+
+    if (opt === "hard")
+        CONF.Configurable = false, CONF.Enumerable = false, CONF.Writable = false;
+
+    if (opt === "med")
+        CONF.Configurable = false, CONF.Writable = false;
+
+    if (opt === "soft")
+        CONF.Writable = false;
+
+    if (opt === "def")
+        CONF.Configurable = true, CONF.Enumerable = true, CONF.Writable = true;
+
+    return Object.defineProperty(obj, key, {
+        value: data,
+        writable: CONF.Writable, configurable: CONF.Configurable, enumerable: CONF.Enumerable
+    });
+}
+
+/**
+ *  Register the specified key-pair to `globalThis` API.
+ *
+ *  @param { string } key - The access key of item to store at `globalThis` API.
+ *  @param { * } data - The data of new item at `globalThis` API.
+ *  @param { "hard" | "med" | "soft" | "def" } [opt] - Optional on how to store the key-pair dat at `globalThis` API. (writable, configurable, enumerable)
+ */
+export function Global(key, data, opt = "def") {
+    const Method = "Global";
+
+    if (!IsStr(key))
+        Emit._ArgumentError(Method, "key", key, "String");
+
+    if (IsStrEmpty(key)) {
+        console.warn(`${Method}(@key: \'\'): Expects a non-empty-string! (Exited)`);
+        return;
+    }
+
+    if (!IsStr(opt) || IsStrEmpty(opt) || !(opt === "def" || opt === "hard" || opt === "med" || opt === "soft"))
+        opt = "def";
+
+    DefineProperty(globalThis, key, data, opt);
+}