@carlsebastian/jsu 1.0.34

package/src/utils/storage/local/storage.local.js

@@ -0,0 +1,236 @@
+import Emit from '../../custom/error/builder/error.builder.js';
+
+/* -- Helper -- */
+/**
+     *  Validates the parameter `localKey` format.
+     *
+     *  @param { string } caller - The caller method id that performs this validation.
+     *  @param { string } localKey - The access key of the storage to validate.
+     *  @param { string } processId - The process of caller id that is going to be performed.
+     *  @returns { string | false } The state of validation process result.
+     */
+function ValidateStorageKey(caller, localKey, processId) {
+    const Method = typeof caller === "string" && caller.length > 0
+        ? caller : `STORAGE.LOCAL.(ANONYMOUS)`;
+
+    if (typeof localKey !== "string")
+        Emit._ArgumentError(Method, "localKey", localKey, "String");
+
+    if (typeof processId !== "string")
+        Emit._ArgumentError(Method, "processId", processId, "String");
+
+    const Key = localKey.trim();
+    if (Key.length === 0) {
+        console.warn(`${Method}(): Cannot perform the ${processId} process with an empty string of storage access key!`);
+        return false;
+    }
+
+    return Key;
+}
+
+/**
+ *  A local `storage` API methods for accessing user's built-in browser local storage.
+ */
+const LocalStorageMethods = {
+    /**
+     *  Name of this object.
+     */
+    NAME: "LOCAL",
+
+    /**
+     *  The total count of existing items at local `storage`.
+     */
+    ITEMS_COUNT: localStorage.length,
+
+    /**
+     *  The total used storage size (MB) in bytes that is calculated in UTF-16 for every existing data at local `storage`.
+     *
+     *  ***Notes***:
+     *   - This is not the base for checking on the maximum size in (bytes) of local `storage` that it can hold, but
+     *     can be used to check on the current used (bytes) size of local `storage`.
+     *   - The maximum (bytes) size of local `storage` may vary on your or the user's browser environment. But commonly is
+     *     ~ `5` Megabytes per domain.
+     *
+     *  @returns { number } The current total used (bytes) size in local `storage`.
+     */
+    SIZE() {
+        let Byte = 0;
+
+        for (let I = 0; I < this.ITEMS_COUNT; I++) {
+            const Key = localStorage.key(I);
+
+            if (!Key)
+                continue;
+
+            const Data = localStorage.getItem(Key) ?? "";
+
+            Byte += (Key.length + Data.length) * 2;
+        }
+
+        return Byte;
+    },
+
+    /**
+     *  A state that indicates whether if the local `storage` API is supported in user's browser version.
+     */
+    IS_SUPPORTED: (function () {
+        try {
+            const Key = "__TEST_LOCAL_KEY__";
+
+            localStorage.setItem(Key, "__TEST__");
+            localStorage.removeItem(Key);
+
+            return true;
+        } catch (err) {
+            return false;
+        }
+    })(),
+
+    /**
+     *  Returns the data of the specified access key of item at local `storage`.
+     *
+     *  ***Notes***:
+     *   - If there's no existing item for the specified access key at local `storage`, it will
+     *     return a default response `object`.
+     *   - Automatically parsed the data of the item of specified access key at local `storage` into its
+     *     original type by using `JSON.parse()` parser. (Can be disabled by providing a `false` state as second parameter.)
+     *
+     *  @template { boolean } [B=true]
+     *  @overload
+     *  @param { string } localKey - The access key of item at local `storage`.
+     *  @param { B } [autoParse] - A optional state parameter for automatically parsing the retrieved data.
+     *  @returns {{
+     *      State: boolean,
+     *      Data: B extends true ? unknown : string | undefined,
+     *      Reason?: "INVALID_KEY" | "NO_SUCH_KEY" | "NOT_SUPPORTED"
+     *  }} The response object result of retrieval process.
+     */
+    GET(localKey, autoParse = true) {
+        const Method = "STORAGE.LOCAL.GET", Response = { State: false, Data: undefined };
+
+        if (!this.IS_SUPPORTED) {
+            console.error(`${Method}(): Your current environment does not supported 'Storage' API! Please upgrade your environment to its latest version.`);
+            return { ...Response, Reason: "NOT_SUPPORTED" };
+        }
+
+        const Key = ValidateStorageKey(Method, localKey, "retrieval");
+        if (Key === false)
+            return { ...Response, Reason: "INVALID_KEY" };
+
+        if (typeof autoParse !== "boolean")
+            autoParse = true;
+
+        if (this.ITEMS_COUNT === 0 || Object.keys(localStorage).indexOf(Key) < 0)
+            return { ...Response, Reason: "NO_SUCH_KEY" };
+
+        const Data = localStorage.getItem(Key);
+
+        Response.State = true;
+        Response.Data = autoParse ? JSON.parse(Data) : Data;
+
+        return Response;
+    },
+
+    /**
+     *  Store a new local `storage` item with the specified access key and its data at local `storage`.
+     *
+     *  ***Notes***:
+     *   - Terminates the creation process when there's already existing local item with the same key provided
+     *     at local `storage`.
+     *
+     *  @param { string } localKey - The access key of item at local `storage`.
+     *  @param { any } [data] - The data to store at new local item. (Default: undefined)
+     *  @returns {{ State: boolean, Reason?: "DUPLICATE_KEY_FOUND" | "INVALID_KEY" | "NOT_SUPPORTED" }} The response object result of creation process.
+     */
+    NEW(localKey, data) {
+        const Method = "STORAGE.LOCAL.NEW", Response = { State: false, Reason: undefined };
+
+        if (!this.IS_SUPPORTED) {
+            console.error(`${Method}(): Your current environment does not supported 'Storage' API! Please upgrade your environment to its latest version.`);
+            Response.Reason = "NOT_SUPPORTED";
+            return Response;
+        }
+
+        const Key = ValidateStorageKey(Method, localKey, "creation");
+        if (Key === false) {
+            Response.Reason = "INVALID_KEY";
+            return Response;
+        }
+
+        if (this.GET(Key).State) {
+            Response.Reason = "DUPLICATE_KEY_FOUND";
+            return Response;
+        }
+
+        localStorage.setItem(Key, JSON.stringify(data));
+        Response.State = true;
+        return Response;
+    },
+
+    /**
+     *  Removes an item at local `storage` that matches the specified access key.
+     *
+     *  @param { string } localKey - The access key of item at local `storage`.
+     *  @returns {{ State: boolean, Reason?: "INVALID_KEY" | "NO_SUCH_KEY" | "NOT_SUPPORTED" }} The response object result of removal process.
+     */
+    REMOVE(localKey) {
+        const Method = "STORAGE.LOCAL.REMOVE", Response = { State: false, Reason: undefined };
+
+        if (!this.IS_SUPPORTED) {
+            console.error(`${Method}(): Your current environment does not supported 'Storage' API! Please upgrade your environment to its latest version.`);
+            Response.Reason = "NOT_SUPPORTED";
+            return Response;
+        }
+
+        const Key = ValidateStorageKey(Method, localKey, "removal");
+        if (Key === false) {
+            Response.Reason = "INVALID_KEY";
+            return Response;
+        }
+
+        if (!this.GET(Key).State) {
+            Response.Reason = "NO_SUCH_KEY";
+            return Response;
+        }
+
+        localStorage.removeItem(Key);
+        Response.State = true;
+        return Response;
+    },
+
+    /**
+     *  Updates the current data with the specified new data of an item at local `storage` that matches the specified access key.
+     *
+     *  @param { string } localKey - The access key of item at local `storage`.
+     *  @param { any } newData - The data to set as new data of the item of local `storage`.
+     *  @returns {{ State: boolean, Reason?: "INVALID_KEY" | "NO_SUCH_KEY" | "NOT_SUPPORTED" }} The response object result of update process.
+     */
+    UPDATE(localKey, newData) {
+        const Method = "STORAGE.LOCAL.UPDATE", Response = { State: false, Reason: undefined };
+
+        if (!this.IS_SUPPORTED) {
+            console.error(`${Method}(): Your current environment does not supported 'Storage' API! Please upgrade your environment to its latest version.`);
+            Response.Reason = "NOT_SUPPORTED"
+            return Response;
+        }
+
+        const Key = ValidateStorageKey(Method, localKey, "data update");
+        if (Key === false) {
+            Response.Reason = "INVALID_KEY";
+            return Response;
+        }
+
+        let Local = this.GET(Key);
+        if (!Local.State) {
+            Response.Reason = "NO_SUCH_KEY";
+            return Response;
+        }
+
+        Local.Data = JSON.stringify(newData);
+        localStorage.setItem(Key, Local.Data);
+        Response.State = true;
+        return Response;
+    },
+}
+
+export default LocalStorageMethods;

package/src/utils/storage/session/storage.session.js

@@ -0,0 +1,236 @@
+import Emit from '../../custom/error/builder/error.builder.js';
+
+/* Helper */
+/**
+ *  Validates the parameter `sessionKey` format.
+ *
+ *  @param { string } caller - The caller method id that performs this validation.
+ *  @param { string } sessionKey - The access key of the storage to validate.
+ *  @param { string } processId - The process of caller id that is going to be performed.
+ *  @returns { string | false } The state of validation process result.
+ */
+function ValidateStorageKey(caller, sessionKey, processId) {
+    const Method = typeof caller === "string" && caller.length > 0
+        ? caller : `STORAGE.SESSION.(ANONYMOUS)`;
+
+    if (typeof sessionKey !== "string")
+        Emit._ArgumentError(Method, "sessionKey", sessionKey, "String");
+
+    if (typeof processId !== "string")
+        Emit._ArgumentError(Method, "processId", processId, "String");
+
+    const Key = sessionKey.trim();
+    if (Key.length === 0) {
+        console.warn(`${Method}(): Cannot perform the ${processId} process with an empty string of storage access key!`);
+        return false;
+    }
+
+    return Key;
+}
+
+/**
+ *  A session `storage` API methods for accessing user's built-in browser session storage.
+ */
+const SessionStorageMethods = {
+    /**
+     *  The name of this object.
+     */
+    NAME: "SESSION",
+
+    /**
+     *  The total count of existing items at session `storage`.
+     */
+    ITEM_COUNT: sessionStorage.length,
+
+    /**
+     *  The total accumulated size of session `storage` API in `bytes` format.
+     *
+     *  ***Notes***:
+     *   - This is not the base for checking on the maximum size in (bytes) of session `storage` that it can hold, but
+     *     can be used to check on the current accumulated (bytes) size of session `storage`.
+     *   - The maximum (bytes) size of session `storage` may vary on your or the user's browser environment. But commonly is
+     *     ~ `5` Megabytes per domain.
+     *
+     *  @returns { number } The current total used (bytes) size in session `storage`.
+     */
+    SIZE() {
+        let Byte = 0;
+
+        for (let I = 0; I < this.ITEM_COUNT; I++) {
+            const Key = localStorage.key(I);
+
+            if (!Key)
+                continue;
+
+            const Data = localStorage.getItem(Key) ?? "";
+
+            Byte += (Key.length + Data.length) * 2;
+        }
+
+        return Byte;
+    },
+
+    /**
+     *  A state that indicates whether if the session `storage` API is supported in user's browser version.
+     */
+    IS_SUPPORTED: (function () {
+        try {
+            const Key = "__TEST_SESSION_KEY__";
+
+            sessionStorage.setItem(Key, "__TEST__");
+            sessionStorage.removeItem(Key);
+
+            return true;
+        } catch (err) {
+            return false;
+        }
+    })(),
+
+    /**
+     *  Returns the data of the specified access key of item at session `storage`.
+     *
+     *  ***Notes***:
+     *   - If there's no existing item for the specified access key at session `storage`, it will
+     *     return a default response `object`.
+     *   - Automatically parsed the data of the item of specified access key at session `storage` into its
+     *     original type by using `JSON.parse()` parser. (Can be disabled by providing a `false` state as second parameter.)
+     *
+     *  @template { boolean } [B=true]
+     *  @overload
+     *  @param { string } sessionKey - The access key of item at session `storage`.
+     *  @param { B } [autoParse] - A optional state parameter for automatically parsing the retrieved data.
+     *  @returns {{
+     *      State: boolean,
+     *      Data: B extends true ? unknown : string | undefined,
+     *      Reason?: "INVALID_KEY" | "NO_SUCH_KEY" | "NOT_SUPPORTED"
+     *  }} The response object result of retrieval process.
+     */
+    GET(sessionKey, autoParse = true) {
+        const Method = `STORAGE.${this.NAME}.GET`, Response = { State: false, Data: undefined };
+
+        if (!this.IS_SUPPORTED) {
+            console.error(`${Method}(): Your current environment does not supported 'Storage' API! Please upgrade your environment to its latest version.`);
+            return { ...Response, Reason: "NOT_SUPPORTED" };
+        }
+
+        const Key = ValidateStorageKey(Method, sessionKey, "retrieval");
+        if (!Key)
+            return { ...Response, Reason: "INVALID_KEY" };
+
+        if (typeof autoParse !== "boolean")
+            autoParse = true;
+
+        if (this.ITEM_COUNT === 0 || Object.keys(sessionStorage).indexOf(Key) < 0)
+            return { ...Response, Reason: "NO_SUCH_KEY" };
+
+        const Data = sessionStorage.getItem(Key);
+        Response.State = true;
+        Response.Data = autoParse ? JSON.parse(Data) : Data;
+
+        return Response;
+    },
+
+    /**
+     *  Store a new session `storage` item with the specified access key and its data at session `storage`.
+     *
+     *  ***Notes***:
+     *   - Terminates the creation process when there's already existing session item with the same key provided
+     *     at session `storage`.
+     *
+     *  @param { string } sessionKey - The access key of item at session `storage`.
+     *  @param { any } [data] - The data to store at new session item. (Default: undefined)
+     *  @returns {{ State: boolean, Reason?: "DUPLICATE_KEY_FOUND" | "INVALID_KEY" | "NOT_SUPPORTED" }} The response object result of creation process.
+     */
+    NEW(sessionKey, data) {
+        const Method = `STORAGE.${this.NAME}.NEW`, Response = { State: false, Reason: undefined };
+
+        if (!this.IS_SUPPORTED) {
+            console.error(`${Method}(): Your current environment does not supported 'Storage' API! Please upgrade your environment to its latest version.`);
+            Response.Reason = "NOT_SUPPORTED";
+            return Response;
+        }
+
+        const Key = ValidateStorageKey(Method, sessionKey, "creation");
+        if (!Key) {
+            Response.Reason = "INVALID_KEY";
+            return Response;
+        }
+
+        if (this.GET(Key).State) {
+            console.warn(`${Method}(): There's already existing session storage item with an access key of '${Key}'! (Exited)`);
+            Response.Reason = "DUPLICATE_KEY_FOUND";
+            return Response;
+        }
+
+        sessionStorage.setItem(sessionKey, JSON.stringify(data));
+        Response.State = true;
+        return Response;
+    },
+
+    /**
+     *  Removes an item at session `storage` that matches the specified access key.
+     *
+     *  @param { string } sessionKey - The access key of item at session `storage`.
+     *  @returns {{ State: boolean, Reason?: "INVALID_KEY" | "NO_SUCH_KEY" | "NOT_SUPPORTED" }} The response object result of removal process.
+     */
+    REMOVE(sessionKey) {
+        const Method = `STORAGE.${this.NAME}.REMOVE`, Response = { State: false, Reason: undefined };
+
+        if (!this.IS_SUPPORTED) {
+            console.error(`${Method}(): Your current environment does not supported 'Storage' API! Please upgrade your environment to its latest version.`);
+            Response.Reason = "NOT_SUPPORTED";
+            return Response;
+        }
+
+        const Key = ValidateStorageKey(sessionKey);
+        if (!Key) {
+            Response.Reason = "INVALID_KEY";
+            return Response;
+        }
+
+        if (!this.GET(Key).State) {
+            Response.Reason = "NO_SUCH_KEY";
+            return Response;
+        }
+
+        sessionStorage.removeItem(Key);
+        Response.State = true;
+        return Response;
+    },
+
+    /**
+     *  Updates the current data with the specified new data of an item at session `storage` that matches the specified access key.
+     *
+     *  @param { string } sessionKey - The access key of item at session `storage`.
+     *  @param { any } newData - The data to set as new data of the item of session `storage`.
+     *  @returns {{ State: boolean, Reason?: "INVALID_KEY" | "NO_SUCH_KEY" | "NOT_SUPPORTED" }} The response object result of update process.
+     */
+    UPDATE(sessionKey, newData) {
+        const Method = `STORAGE.${this.NAME}.UPDATE`, Response = { State: false, Reason: undefined };
+
+        if (!this.IS_SUPPORTED) {
+            console.error(`${Method}(): Your current environment does not supported 'Storage' API! Please upgrade your environment to its latest version.`);
+            Response.Reason = "NOT_SUPPORTED";
+            return Response;
+        }
+
+        const Key = ValidateStorageKey(sessionKey);
+        if (!Key) {
+            Response.Reason = "INVALID_KEY";
+            return Response;
+        }
+
+        const This = this.GET(Key);
+        if (!This.State) {
+            Response.Reason = This.Reason;
+            return Response;
+        }
+
+        This.Data = JSON.stringify(newData);
+        sessionStorage.setItem(Key, This.Data);
+        Response.State = true;
+        return Response;
+    }
+}
+
+export default SessionStorageMethods;

package/src/utils/storage/storage.js

@@ -0,0 +1,59 @@
+import Emit from '../custom/error/builder/error.builder.js';
+import { Global } from '../custom/utils/custom.utils.js';
+import { IsNullOrUndefined, IsPropertyAt } from '../guards/data-types/data-types.js';
+import LocalStorageMethods from './local/storage.local.js';
+import SessionStorageMethods from './session/storage.session.js';
+
+/**
+ *  A built-in `Storage` API interfaces for user's browser environment.
+ */
+const STORAGE = {
+    /**
+     *  The name of this object.
+     *  @readonly
+     */
+    NAME: "STORAGE",
+
+    /**
+     *  Verifies a state whether if all of available `storage` instances or API are supported in your or user's current environment.
+     *
+     *  ***Notes***:
+     *   - Does not throw a `NotSupportedError` when there's at least 1 or more of the `storage` instances or API that is supported.
+     *   - Only throw a `NotSupportedError` when trying to access the not supported `storage` instances or API.
+     *
+     *  @returns { true | void }
+     */
+    IS_SUPPORTED() {
+        if (!this.LOCAL.IS_SUPPORTED && !this.SESSION.IS_SUPPORTED)
+            Emit._NotSupportedError(`${this.NAME}.${this.IS_SUPPORTED.name}`, this.NAME);
+
+        return true;
+    },
+
+    /**
+     *  A local `storage` API for storing user's activity or history permanently which can be used for storing
+     *  configurations, and many more.
+     *
+     *  ***Notes***:
+     *   - This local `storage` API has a very limited size to offer, that is could only be around `5` to `10` Megabytes (MB).
+     *
+     *  @readonly
+     */
+    LOCAL: LocalStorageMethods,
+
+    /**
+     *  A session `storage` API methods for storing user's activity temporarily that would be automatically
+     *  removed once the page changed or the user's leaved.
+     *
+     *  ***Notes***:
+     *   - This session `storage` API has a very limited size to offer, that is could only about `5` to `10` Megabytes (MB).
+     *
+     *  @readonly
+     */
+    SESSION: SessionStorageMethods,
+}
+
+export default STORAGE;
+
+if (IsNullOrUndefined(globalThis.STORAGE) || !IsPropertyAt(globalThis, "STORAGE"))
+    Global("STORAGE", STORAGE, "soft");

package/src/utils/variables.js

@@ -0,0 +1,78 @@
+/**
+ *  A collection of HTMLElements tags.
+ *
+ *  ***Source***: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements
+ *
+ *  @type { Map<string, { Generate: () => HTMLElement }> }
+ */
+export const HTMLElementTags = [
+    "a", "abbr", "acronym", "address", "address", "area", "article", "aside", "audio", "b", "base", "bdi",
+    "bdo", "big", "blockquote", "body", "br", "button", "canvas", "caption", "center", "cite", "code", "col",
+    "colgroup", "data", "datalist", "dd", "del", "details", "dfn", "dialog", "dir", "div", "dl", "dt", "em",
+    "embed", "fencedframe", "fieldset", "figcaption", "figure", "font", "footer", "form", "frame", "frameset",
+    "geolocation", "h1", "h2", "h3", "h4", "h5", "h6", "head", "header", "hgroup", "hr", "html", "i", "iframe",
+    "img", "input", "ins", "kbd", "label", "legend", "li", "link", "main", "map", "mark", "marquee", "menu",
+    "meta", "meter", "nav", "nobr", "noembed", "noframes", "noscript", "object", "ol", "optgroup", "option",
+    "output", "p", "param", "picture", "plaintext", "pre", "progress", "q", "rb", "rp", "rt", "rtc", "ruby",
+    "s", "samp", "script", "search", "section", "select", "selectioncontent", "slot", "small", "source", "span",
+    "strike", "strong", "style", "sub", "summary", "sup", "table", "tbody", "td", "template", "textarea", "tfoot",
+    "th", "thead", "time", "title", "tr", "track", "tt", "u", "ul", "var", "video", "wbr", "xmp"
+].reduce((Acc, Tag) => {
+    const T = Tag.trim().toLowerCase();
+    Acc.set(T, { Generate: () => document.createElement(T) });
+    return Acc;
+}, new Map([]));
+
+/**
+ *  A collection of SVGElements tags.
+ *
+ *  ***Source***: https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element
+ *
+ *  @type { Map<string, { Generate: () => SVGElement}> }
+ */
+export const SVGElementTags = [
+    "a", "animate", "animateMotion", "animateTransform", "circle", "clipPath", "defs", "desc", "ellipse",
+    "feBlend", "feColorMatrix", "feComponentTransfer", "feComposite", "feConvolveMatrix", "feDiffuseLighting",
+    "feDisplacementMap", "feDistantLight", "feDropShadow", "feFlood", "feFuncA", "feFuncB", "feFuncG", "feFuncR",
+    "feGaussianBlur", "feImage", "feMerge", "feMergeNode", "feMorphology", "feOffset", "fePointLight", "feSpecularLighting",
+    "feSpotLight", "feTile", "feTurbulence", "filter", "foreignObject", "g", "image", "line", "linearGradient",
+    "marker", "mask", "metadata", "mpath", "path", "pattern", "polygon", "polyline", "radialGradient", "rect",
+    "script", "set", "stop", "style", "svg", "switch", "symbol", "text", "textPath", "title", "tspan", "use",
+    "view"
+].reduce((Acc, Tag) => {
+    const T = Tag.trim().toLowerCase();
+    Acc.set(T, { Generate: () => document.createElementNS("http://www.w3.org/2000/svg", T) });
+    return Acc;
+}, new Map([]));
+
+/**
+ *  A collection of MathMLElements tags.
+ *
+ *  ***Source***: https://developer.mozilla.org/en-US/docs/Web/MathML/Reference/Element
+ *
+ *  @type { Map<string, { Generate: () => MathMLElement}> }
+ */
+export const MathMLElementTags = [
+    "math", "maction", "annotation", "annotation-xml", "menclose", "merror", "mfenced", "mfrac", "mi", "mmultiscripts",
+    "mn", "mo", "mover", "mpadded", "mphantom", "mpresscripts", "mroot", "mrow", "ms", "semantics", "mspace",
+    "msqrt", "mstyle", "msub", "msup", "msubsup", "mtable", "mtd", "mtext", "mtr", "munder", "munderover"
+].reduce((Acc, Tag) => {
+    const T = Tag.trim().toLowerCase();
+    Acc.set(T, { Generate: () => document.createElementNS("http://www.w3.org/1998/Math/MathML", T) });
+    return Acc;
+}, new Map([]));
+
+/**
+ *  A collection of available element's XML namespace.
+ */
+export const XMLNameSpace = ["http://www.w3.org/1998/Math/MathML", "http://www.w3.org/1999/xhtml", "http://www.w3.org/2000/svg"];
+
+[
+    ["HTMLElementTags", HTMLElementTags], ["MathMLElementTags", MathMLElementTags],
+    ["SVGElementTags", SVGElementTags], ["XMLNameSpace", XMLNameSpace]
+].forEach((key, val) => {
+    Object.defineProperty(globalThis, key, {
+        value: val,
+        writable: false, configurable: true, enumerable: true
+    });
+});