@carlsebastian/jsu 1.0.34

package/src/utils/primitives/obj/obj.accessor.js

@@ -0,0 +1,242 @@
+import Emit from '../../custom/error/builder/error.builder.js';
+import { ConstructorOrTypeOf } from '../../custom/utils/custom.utils.js';
+import { IsArrEmpty, IsMapObjEmpty, IsPlainObjEmpty, IsSetObjEmpty, IsStrEmpty } from "../../guards/formats/formats.js";
+import { IsArr, IsMapObj, IsNullOrUndefined, IsNum, IsPlainObj, IsSetObj, IsStr } from "../../guards/data-types/data-types.js";
+
+/**
+ *  Returns an iterable entries of data from the specified ***object*** or
+ *  an array of data from a ***plain object***.
+ *
+ *  ***Expected Objects***:
+ *   - ***ARRAY*** | ***PLAIN OBJECT*** | ***MAP OBJECT*** | ***SET OBJECT***.
+ *
+ *  ***Notes***:
+ *   - When object is ***plain object*** it would preserve the array (same result as Object.entries(o)),
+ *     the same thing with objects that is an Array, Map, and Set. (E.g. ArrayIterator, MapIterator, and SetIterator)
+ *
+ *  @template T
+ *  @param { T } obj - The object to get its content's entries.
+ *  @returns { T extends Map<infer K, infer V> ? MapIterator<[K, V]> :
+ *      T extends Set<infer U> ? SetIterator<[U, U]> :
+ *      T extends readonly Array<infer V> ? ArrayIterator<[number, V]>
+ *      T extends { [p: string]: infer V } | ArrayLike<infer V> ? Array<[string, V]> :
+ *      never[]
+ *  }
+ */
+export function EntriesOf(obj) {
+    // ❌ - Exits when @obj is none of these expected object formats.
+    if (!IsArr(obj) && !IsPlainObj(obj) && !IsMapObj(obj) && !IsSetObj(obj))
+        Emit._ArgumentError("EntriesOf", "obj", ConstructorOrTypeOf(obj), "Array", "Map", "Plain Object", "Set");
+
+    // ⚠️ - Warns when the specified @obj is empty or does not have present contents.
+    if (IsPlainObj(obj) && IsPlainObjEmpty(obj) || IsArr(obj) && IsArrEmpty(obj) ||
+        IsMapObj(obj) && IsMapObjEmpty(obj) || IsSetObj(obj) && IsSetObjEmpty(obj)
+    ) {
+        console.warn(`EntriesOf(@obj: NO_ELEMENTS_FOUND): The specified object does not have any present elements or contents! (Exited with [])`);
+        return [];
+    }
+
+    // 📍 - @type = OBJECT
+    if (IsPlainObj(obj))
+        return Object.entries(obj);
+
+    // 📍 - @type = ARRAY | MAP | SET
+    if (IsArr(obj) || IsMapObj(obj) || IsSetObj(obj))
+        return obj.entries();
+
+    // 📍 - @type = undefined | null.
+    // 💬 - Default detection if type is not in the option (for module namespace, freezed objects, and no constructor objects)
+    if (IsNullOrUndefined(ConstructorOrTypeOf(obj)) || IsNullOrUndefined(Object.getPrototypeOf(obj)))
+        if (IsPlainObj(obj))
+            return Object.entries(obj);
+        else if (IsArr(obj) || IsMapObj(obj) || IsSetObj(obj))
+            return obj.entries();
+        else
+            return [];
+}
+
+/**
+ *  Returns an iterable keys or index of the specified ***object***.
+ *
+ *  ***Expected Objects***:
+ *   - ***ARRAY*** | ***PLAIN OBJECT*** | ***MAP OBJECT*** | ***SET OBJECT***.
+ *
+ *  @template T
+ *  @param { T } obj - The object to get its content's keys.
+ *  @returns { T extends Map<infer K, unknown> ? MapIterator<K> :
+ *      T extends Set<infer U> ? SetIterator<U> :
+ *      T extends Array<infer V> ? ArrayIterator<number> :
+ *      T extends { [p: string]: infer V } | ArrayLike<infer V> ? Array<string> :
+ *      never[]
+ *  }
+ */
+export function KeysOf(obj) {
+    // ❌ - Exits when @obj is none of these expected object formats.
+    if (!IsArr(obj) && !IsPlainObj(obj) && !IsMapObj(obj) && !IsSetObj(obj))
+        Emit._ArgumentError("KeysOf", "obj", ConstructorOrTypeOf(obj), "Array", "Map", "Plain Object", "Set");
+
+    // ⚠️ - Warns when the specified @obj is empty or does not have present contents.
+    if (IsPlainObj(obj) && IsPlainObjEmpty(obj) || IsArr(obj) && IsArrEmpty(obj) ||
+        IsMapObj(obj) && IsMapObjEmpty(obj) || IsSetObj(obj) && IsSetObjEmpty(obj)
+    ) {
+        console.warn(`KeysOf(@obj: NO_ELEMENTS_FOUND): The specified object does not have any present elements or contents! (Exited with [])`);
+        return [];
+    }
+
+    // 📍 - @type = OBJECT
+    if (IsPlainObj(obj))
+        return Object.keys(obj);
+
+    // 📍 - @type = ARRAY | MAP | SET
+    if (IsArr(obj) || IsMapObj(obj) || IsSetObj(obj))
+        return obj.keys();
+
+    // 📍 - @type = undefined | null.
+    // 💬 - Default detection if type is not in the option (for module namespace, freezed objects, and no constructor objects)
+    if (IsNullOrUndefined(obj.constructor) || IsNullOrUndefined(Object.getPrototypeOf(obj)))
+        if (IsPlainObj(obj))
+            return Object.keys(obj);
+        else if (IsArr(obj) || IsMapObj(obj) || IsSetObj(obj))
+            return obj.keys();
+        else
+            return [];
+}
+
+/**
+ *  Returns an iterable values of the specified ***object***.
+ *
+ *  ***Expected Objects***:
+ *   - ***ARRAY*** | ***PLAIN OBJECT*** | ***MAP OBJECT*** | ***SET OBJECT***.
+ *
+ *  @template T
+ *  @param { T } obj - The object to return its content's values.
+ *  @throws `@ArgumentError` when the specified object is invalid.
+ *  @returns { T extends Map<unknown, infer V> ? MapIterator<V> :
+ *      T extends Set<infer U> ? SetIterator<U> :
+ *      T extends Array<infer V> ? ArrayIterator<V> :
+ *      T extends { [p: string]: infer V } | ArrayLike<infer V> ? Array<V> :
+ *      never[]
+ *  }
+ */
+export function ValuesOf(obj) {
+    // ❌ - Exits when @obj is none of these expected object formats.
+    if (!IsArr(obj) && !IsPlainObj(obj) && !IsMapObj(obj) && !IsSetObj(obj))
+        Emit._ArgumentError("ValuesOf", "obj", ConstructorOrTypeOf(obj), "Array", "Map", "Plain Object", "Set");
+
+    // ⚠️ - Warns when the specified @obj is empty or does not have present contents.
+    if (IsPlainObj(obj) && IsPlainObjEmpty(obj) || IsArr(obj) && IsArrEmpty(obj) ||
+        IsMapObj(obj) && IsMapObjEmpty(obj) || IsSetObj(obj) && IsSetObjEmpty(obj)
+    ) {
+        console.warn(`ValuesOf(@obj: NO_ELEMENTS_FOUND): The specified object does not have any present elements or contents! (Exited with [])`);
+        return [];
+    }
+
+    // 📍 - @type = OBJECT
+    if (IsPlainObj(obj))
+        return Object.values(obj);
+
+    // 📍 - @type = ARRAY | MAP | SET
+    if (IsArr(obj) || IsMapObj(obj) || IsSetObj(obj))
+        return obj.values();
+
+    // 📍 - @type = undefined | null.
+    // 💬 - Default detection if type is not in the option (for module namespace, freezed objects, and no constructor objects)
+    if (IsNullOrUndefined(obj.constructor) || IsNullOrUndefined(Object.getPrototypeOf(obj)))
+        if (IsPlainObj(obj))
+            return Object.values(obj);
+        else if (IsArr(obj) || IsMapObj(obj) || IsSetObj(obj))
+            return obj.values();
+        else
+            return [];
+}
+
+/**
+ *  Returns the current `size` or `length` of the specified argument.
+ *
+ *  ***Known Objects or Types***:
+ *   - ***ARRAY*** | ***PLAIN OBJECT*** | ***MAP OBJECT*** | ***SET OBJECT*** | ***STRING***
+ *
+ *  ***Capability-Based Behavior***:
+ *   - This accessor is **not strictly type-limited**.
+ *   - Any value that exposes a numeric `length` or `size` property
+ *     may be supported, including **custom user-defined objects**,
+ *     **library abstractions**, **module namespaces**, and other
+ *     object-like structures.
+ *
+ *  ***Notes***:
+ *   - The accessor prioritizes the `length` property when present,
+ *     otherwise falls back to the `size` property.
+ *   - A default value of `-1` is returned if the specified argument
+ *     is invalid, unsupported, or exposes a non-numeric `length`
+ *     or `size` property.
+ *
+ *  @template T
+ *  @param { T } arg - The argument to retrieve the current size or length from.
+ *  @returns { number } The computed size or length, or `-1` on failure.
+ */
+export function CountOf(arg) {
+    const Method = "CountOf";
+
+    // ❌ - Exits with default value if argument is not provided.
+    if (IsNullOrUndefined(arg))
+        return -1;
+
+    // ⚠️ - Warns and exit with default value if the argument does not support or have 'length' and 'size' property.
+    if ((typeof arg === "string" && IsNullOrUndefined(arg.length) || IsPlainObj(arg) && IsNullOrUndefined(Object.keys(arg).length)) && IsNullOrUndefined(arg.size)) {
+        console.warn(`${Method}(@arg: NOT_SUPPORTED): The provided argument of type '${ConstructorOrTypeOf(arg)}' does not support or have 'length' and/or 'size' property! (Exited with -1)`);
+        return -1;
+    }
+
+    // 📍 - length property.
+    if (Object.hasOwn(arg, "length") || IsPlainObj(arg)) {
+        const parsedLength = IsPlainObj(arg) ? parseInt(Object.entries(arg)["length"], 10) : parseInt(arg["length"]);
+        if (!IsNum(arg["length"]) && !IsNum(parsedLength)) {
+            console.warn(`CountOf(@arg.length): The length '${arg["length"]}' property value of the specified argument is not a valid number! (Exited with -1)`);
+            return -1;
+        }
+
+        return parsedLength;
+    }
+
+    // 📍 - size property.
+    if (Object.hasOwn(arg, "size")) {
+        const parsedSize = parseInt(arg["size"], 10);
+        if (!IsNum(arg["size"]) && !IsNum(parsedSize)) {
+            console.warn(`CountOf(@arg.size): The size '${arg["size"]}' property value of the specified argument is not a valid number! (Exited with -1)`);
+            return -1;
+        }
+
+        return parsedSize;
+    }
+}
+
+/**
+ *  Retrieves and returns the value of the specified property in the specified plain `object`.
+ *
+ *  ***Notes***:
+ *   - This uses a non-case-sensitive for retrieving the data of the specified property id at
+ *     plain object, this would retrieve the data of the first property that matches the specified
+ *     property id in any case.
+ *   - Returns `undefined` if parameter `obj` or `propertyId` is invalid.
+ *
+ *  @template T
+ *  @template { InferKeyOptions<T> } P
+ *  @param { T } obj - The collection of key-pairs to retrieve at.
+ *  @param { P } propertyId - The property id of key-pair to retrieve.
+ *  @returns { T[P] | undefined }
+ */
+export function GetPropertyOf(obj, propertyId) {
+    if (!IsPlainObj(obj) || !IsStr(propertyId) || !IsStrEmpty(propertyId))
+        return undefined;
+
+    let Result;
+    for (const [PK, PV] of Object.entries(obj)) {
+        if (PK.trim().toLowerCase() !== propertyId.trim().toLowerCase())
+            continue;
+
+        Result = PV;
+        break;
+    }
+
+    return Result;
+}

package/src/utils/primitives/obj/obj.iterator.js

@@ -0,0 +1,148 @@
+import Emit from '../../custom/error/builder/error.builder.js';
+import { ConstructorOrTypeOf } from '../../custom/utils/custom.utils.js';
+import { IsFuncAnonymous } from '../../guards/formats/formats.js';
+import { IsArr, IsFunc, IsMapObj, IsNullOrUndefined, IsSetObj } from '../../guards/data-types/data-types.js';
+import { CountOf } from './obj.accessor.js';
+
+/* Parameters Id and Expected Object Formats */
+const Args = ["obj", "callback", "thisArg"];
+const ObjectFormats = ["Array", "Map", "Set"];
+
+/**
+ *  Iterates and perform the specified `callback function` on each of the elements of the specified `object`.
+ *
+ *  @template T, A
+ *  @param { T } obj - The object to get the elements from.
+ *  @param { (value: IterableValue<T>, index: number, arr: IterableValue<T>[]) => void } callback - The callback function to perform.
+ *  @param { A } [thisArg] - An optional parameter to hold the specified value and access it using the `this` keyword.
+ *  @returns { void } - Does not return any data or value.
+ */
+export function EachOf(obj, callback, thisArg) {
+    const Method = "EachOf";
+
+    // ❌ - Exits when the provided object is not valid or not supported.
+    if (!IsArr(obj) && !IsMapObj(obj) && !IsSetObj(obj) && !("forEach" in obj))
+        Emit._ArgumentError(Method, Args[0], ConstructorOrTypeOf(obj), ...ObjectFormats);
+
+    // ❌ - Exits when callback is not callable or function.
+    if (!IsFunc(callback))
+        Emit._ArgumentError(Method, Args[1], ConstructorOrTypeOf(callback), "Function");
+
+    // ⚠️ - Notify and terminate the continuation of this process when the provided object is empty.
+    if (!(obj instanceof Iterator) && CountOf(obj) <= 0) {
+        console.warn(`${Method}(${Args[0]}: EMPTY): No elements to iterate. (Terminated)`);
+        return;
+    }
+
+    // ⚠️ - Warns about possible conflicts when accessing or using the provided @thisArg inside of a anonymous @callback function.
+    if (!IsNullOrUndefined(thisArg) && IsFuncAnonymous(callback))
+        console.warn(`${Method}(@callback: anonymous): May throw or cause an error to your program if 'this' keyword is used inside of the anonymous callback function.`);
+
+    /* @Iterate */
+    obj["forEach"](callback, thisArg);
+}
+
+/**
+ *  Iterates and perform the specified `callback function` on each of the elements of the specified `object`,
+ *  and returns a new array that contains the result(s).
+ *
+ *  @template T, A, U
+ *  @param { T } obj - The object to get the elements from.
+ *  @param { (value: IterableValue<T>, index: number, arr: IterableValue<T>[]) => U } callback - The callback function to perform.
+ *  @param { A } [thisArg] - An optional parameter to hold the specified value and access it using the `this` keyword.
+ *  @returns { U[] } - Returns a new array that contains the result(s).
+ */
+export function MapOf(obj, callback, thisArg) {
+    const Method = "MapOf";
+
+    // ❌ - Exits when the provided object is not valid or not supported.
+    if (!IsArr(obj) && !IsMapObj(obj) && !IsSetObj(obj) && !("map" in obj))
+        Emit._ArgumentError(Method, Args[0], ConstructorOrTypeOf(obj), ...ObjectFormats);
+
+    // ❌ - Exits when callback is not callable or function.
+    if (!IsFunc(callback))
+        Emit._ArgumentError(Method, Args[1], ConstructorOrTypeOf(callback), "Function");
+
+    // ⚠️ - Notify and terminate the continuation of this process when the provided object is empty.
+    if (!(obj instanceof Iterator) && CountOf(obj) <= 0) {
+        console.warn(`${Method}(${Args[0]}: EMPTY): No elements to iterate. (Terminated)`);
+        return [];
+    }
+
+    // ⚠️ - Warns about possible conflicts when accessing or using the provided @thisArg inside of a anonymous @callback function.
+    if (!IsNullOrUndefined(thisArg) && IsFuncAnonymous(callback))
+        console.warn(`${Method}(@callback: anonymous): May throw or cause an error to your program if 'this' keyword is used inside of the anonymous callback function.`);
+
+    /* @Iterate */
+    return obj["map"](callback, thisArg);
+}
+
+/**
+ *  Iterates and perform the specified `callback function` on each of the elements of the specified `object`,
+ *  and determines whether if some of the elements in the `object` satisfies the specified `callback function`.
+ *
+ *  @template T, A
+ * @param { T } obj - The object to get the elements from.
+ *  @param { (value: IterableValue<T>, index: number, arr: IterableValue<T>[]) => unknown } callback - The callback function to perform.
+ *  @param { A } [thisArg] - An optional parameter to hold the specified value and access it using the `this` keyword.
+ *  @returns { boolean } - Returns `true` if some of the elements in the `object` satisfies the specified `callback function`, otherwise `false`.
+ */
+export function SomeOf(obj, callback, thisArg) {
+    const Method = "SomeOf";
+
+    // ❌ - Exits when the provided object is not valid or not supported.
+    if (!IsArr(obj) && !IsMapObj(obj) && !IsSetObj(obj) && !("some" in obj))
+        Emit._ArgumentError(Method, Args[0], ConstructorOrTypeOf(obj), ...ObjectFormats);
+
+    // ❌ - Exits when callback is not callable or function.
+    if (!IsFunc(callback))
+        Emit._ArgumentError(Method, Args[1], ConstructorOrTypeOf(callback), "Function");
+
+    // ⚠️ - Notify and terminate the continuation of this process when the provided object is empty.
+    if (!(obj instanceof Iterator) && CountOf(obj) <= 0) {
+        console.warn(`${Method}(${Args[0]}: EMPTY): No elements to iterate. (Terminated)`);
+        return [];
+    }
+
+    // ⚠️ - Warns about possible conflicts when accessing or using the provided @thisArg inside of a anonymous @callback function.
+    if (!IsNullOrUndefined(thisArg) && IsFuncAnonymous(callback))
+        console.warn(`${Method}(@callback: anonymous): May throw or cause an error to your program if 'this' keyword is used inside of the anonymous callback function.`);
+
+    /* @Iterate */
+    return obj["some"](callback, thisArg);
+}
+
+/**
+ *  Iterates and perform the specified `callback function` on each of the elements of the specified `object`,
+ *  and determines whether if all of the elements in the `object` satisfies the specified `callback function`.
+ *
+ *  @template T, A
+ * @param { T } obj - The object to get the elements from.
+ *  @param { (value: IterableValue<T>, index: number, arr: IterableValue<T>[]) => unknown } callback - The callback function to perform.
+ *  @param { A } [thisArg] - An optional parameter to hold the specified value and access it using the `this` keyword.
+ *  @returns { boolean } - Returns `true` if all of the elements in the `object` satisfies the specified `callback function`, otherwise `false`.
+ */
+export function EveryOf(obj, callback, thisArg) {
+    const Method = "EveryOf";
+
+    // ❌ - Exits when the provided object is not valid or not supported.
+    if (!IsArr(obj) && !IsMapObj(obj) && !IsSetObj(obj) && !("every" in obj))
+        Emit._ArgumentError(Method, Args[0], ConstructorOrTypeOf(obj), ...ObjectFormats);
+
+    // ❌ - Exits when callback is not callable or function.
+    if (!IsFunc(callback))
+        Emit._ArgumentError(Method, Args[1], ConstructorOrTypeOf(callback), "Function");
+
+    // ⚠️ - Notify and terminate the continuation of this process when the provided object is empty.
+    if (!(obj instanceof Iterator) && CountOf(obj) <= 0) {
+        console.warn(`${Method}(${Args[0]}: EMPTY): No elements to iterate. (Terminated)`);
+        return [];
+    }
+
+    // ⚠️ - Warns about possible conflicts when accessing or using the provided @thisArg inside of a anonymous @callback function.
+    if (!IsNullOrUndefined(thisArg) && IsFuncAnonymous(callback))
+        console.warn(`${Method}(@callback: anonymous): May throw or cause an error to your program if 'this' keyword is used inside of the anonymous callback function.`);
+
+    /* @Iterate */
+    return obj["every"](callback, thisArg);
+}

package/src/utils/primitives/primitives.js

@@ -0,0 +1,23 @@
+import { DefineProperty, Global, NameOf } from '../custom/utils/custom.utils.js';
+import { IsNullOrUndefined, IsPropertyAt } from '../guards/data-types/data-types.js';
+import { IsStrEmpty } from '../guards/formats/formats.js';
+import * as OAC from "./obj/obj.accessor.js";
+import * as OI from "./obj/obj.iterator.js";
+import STR from "./str/str.js";
+
+/**
+ *  Contains reusable primitives methods of ***array***, ***string***, and many more!.
+ */
+export default function Primitives() {
+    const PrimitivesAPI = {};
+
+    for (const Method of [...Object.values(OAC), ...Object.values(OI), STR]) {
+        const Key = NameOf(Method);
+        if (!IsNullOrUndefined(Key) && !IsStrEmpty(Key) && !IsPropertyAt(PrimitivesAPI, Key) && !(Key === "(ANONYMOUS)"))
+            DefineProperty(PrimitivesAPI, Key, Method, "med");
+    }
+
+    Global("Primitives", PrimitivesAPI, "soft");
+}
+
+Primitives();

package/src/utils/primitives/str/str.js

@@ -0,0 +1,52 @@
+/**
+ *  Contains `@custom` and/or `@enhance` string methods.
+ */
+const Str = {
+    /**
+     *  Name of this object.
+     */
+    name: "Str",
+
+    /**
+     *  Contains collection of characters. (E.g. Lowercase(): a-z)
+     */
+    Chars: {
+        /**
+         *  Returns a set of character codes of `lowercase` characters.
+         *
+         *  @returns { string } The set of `lowercase` characters.
+         */
+        Lowercase() {
+            return String.fromCharCode(...Array.from({ length: 26 }, (_, i) => i + 97));
+        },
+
+        /**
+         *  Returns a set of character codes of `numeric` characters.
+         *
+         *  @returns { string } The set of `numeric` characters.
+         */
+        Numeric() {
+            return String.fromCharCode(...Array.from({ length: 10 }, (_, i) => i + 48));
+        },
+
+        /**
+         *  Returns a set of character codes of `special` or `symbol` characters.
+         *
+         *  @returns { string } The set of `special` or `symbol` characters.
+         */
+        Symbols() {
+            return String.fromCharCode(...Array.from({ length: 15 }, (_, i) => i + 33)) + `=_[]@~{}<>?\\`;
+        },
+
+        /**
+         *  Returns a set of character codes of `uppercase` characters.
+         *
+         *  @returns { string } The set of `uppercase` characters.
+         */
+        Uppercase() {
+            return String.fromCharCode(...Array.from({ length: 26 }, (_, i) => i + 65));
+        },
+    },
+}
+
+export default Str;