@carlsebastian/jsu 1.0.34

package/src/types/custom/utils/generator/generator.d.ts

@@ -0,0 +1,92 @@
+/**
+ *  Configuration for generator's contents.
+ */
+interface GeneratorAPIConfig {
+    /**
+     *  A configuration state for including or excluding numerical values at generator's content.
+     */
+    numbers?: boolean;
+
+    /**
+     *  A configuration state for including or excluding lowercase characters at generator's content.
+     */
+    lowercase?: boolean;
+
+    /**
+     *  A configuration state for including or excluding symbol characters at generator's contents.
+     */
+    symbols?: boolean;
+
+    /**
+     *  A configuration state for including or excluding uppercase characters at generator's contents.
+     */
+    uppercase?: boolean;
+
+    /**
+     *  A configuration state for secure random values generator of generator's contents.
+     *
+     *  ***States***:
+     *   - `true`: Sets entropy to 'window.crypto' for secure generator's randomized value (32-bits).
+     *   - `false`: Sets entropy to `Math.random()` for fast but not secure generator's randomized contents.
+     */
+    secure?: boolean;
+}
+
+/**
+ *  A collection of randomized content generators.
+ */
+class GeneratorAPI {
+    /**
+     *  The `size` or `length` of contents of generators to generate.
+     */
+    Size: number;
+
+    /**
+     *  The maximum `size` or `length` of contents of generators to generate.
+     */
+    readonly Max: number;
+
+    /**
+     *  Configuration for generator's contents.
+     */
+    Conf?: GeneratorAPIConfig;
+
+    /**
+     *  A collection of characters that is used in generators as their contents referenced pool.
+     */
+    readonly Chars?: string[];
+
+    /**
+     *  Constructs the size and configuration for generator's contents.
+     *
+     *  ***Notes***:
+     *   - If `size` is less than the generator's minimum `size` or higher than its maximum `size`, it will be
+     *     clamped to it minimum and/or maximum `size`.
+     *   - If both of configuration `lowercase` and `uppercase` are set to `false` state, the generator's would
+     *     automatically use uppercase as preferred characters.
+     *   - By default, the secure randomized of generators are disabled for performance efficiency, you can just enabled
+     *     it for security related use for a little trade of performance.
+     *
+     *  @param size - The `size` or `length` of generator's contents to generate.
+     *  @param conf - A configuration for generator's contents.
+     */
+    constructor(size: number, conf?: GeneratorAPIConfig);
+
+    /**
+     *  Generates a random integer value and returns it.
+     *
+     *  @param min - The minimum or lowest integer value it can generate. (Default: 0)
+     *  @param max - The maximum or highest integer value it can generate. (Default: 1)
+     */
+    readonly RandomInteger(min?: number, max?: number): number;
+
+    /**
+     *  Generates a set of randomized characters in lowercase and/or uppercase.
+     */
+    readonly RandomCharacters(): string;
+
+    /**
+     *  Generates a new set of randomized tokens that can be used for ids, session id, etc.
+     */
+    readonly NewToken(): string;
+}

package/src/types/dom/attr/attr.class.d.ts

@@ -0,0 +1,81 @@
+interface DOMClassOfAPI {
+    /**
+     *  Search the given `class` token at the element's `DOMTokenList`.
+     *
+     *  ***Notes***:
+     *   - If the token is not in string format, it would automatically return a `false` state result.
+     *
+     *  @param token - The `class` token to search.
+     */
+    Has(token: string): boolean;
+
+    /**
+     *  Search every of the given collection of `class` tokens at the element's `DOMTokenList`.
+     *
+     *  ***Notes***:
+     *   - If one or more of token at collection of token are not in string format, It would automatically
+     *     return a `false` state result.
+     *
+     *  @param tokens - The collection of `class` token to search.
+     */
+    Has(...tokens: string[]): boolean;
+
+    /**
+     *  Retrieves the current collection of element's `DOMTokenList`.
+     */
+    List(): DOMTokenList;
+
+    /**
+     *  Removes the given `class` token at the element's `DOMTokenList`.
+     *
+     *  @param token - The `class` token to remove.
+     */
+    Remove(token: string): boolean;
+
+    /**
+     *  Removes the given `class` collection of tokens at the element's `DOMTokenList`.
+     *
+     *  @param token - The collection of `class` token to remove.
+     */
+    Remove(...tokens: string[]): boolean;
+
+    /**
+     *  Sets a new given `class` token at the element's `DOMTokenList`.
+     *
+     *  @param token - The `class` token to set.
+     */
+    Set(token: string): void;
+
+    /**
+     *  Sets a collection of new given `class` tokens at the element's `DOMTokenList`.
+     *
+     *  @param token - The collection of `class` token to set.
+     */
+    Set(...tokens: string[]): void;
+
+    /**
+     *  Toggles the state of the given `class` token at the element's `DOMTokenList`.
+     *
+     *  ***States***:
+     *   - TRUE: The given `class` token will be added at the element's `class` attribute and `DOMTokenList`.
+     *   - FALSE: The given `class` token will be remove at the element's `class` attribute and `DOMTokenList`.
+     *
+     *  @param token - The `class` token to toggle.
+     *  @param forceState - Forcefully set the state of the given `class` token, despite its current state.
+     *  @returns The new state of toggled `class` token.
+     */
+    Toggle(token: string, forceState?: boolean): boolean;
+
+    /**
+     *  Toggles the state of the given `class` collection tokens at the element's `DOMTokenList`.
+     *
+     *  ***States***:
+     *   - TRUE: A certain collection of `class` token will be added at the element's `class` attribute and `DOMTokenList`.
+     *   - FALSE: A certain collection of `class` token will be remove at the element's `class` attribute and `DOMTokenList`.
+     *
+     *  @param token - The `class` token to toggle.
+     *  @param forceState - Forcefully set the state of the given `class` collection token, despite their current state.
+     *  @returns The collection of new states of toggled `class` tokens.
+     */
+    Toggle(tokens: string[], forceState?: boolean): boolean[];
+}

package/src/types/dom/attr/attr.id.d.ts

@@ -0,0 +1,23 @@
+interface DOMIdOfAPI {
+    /**
+     *  The current unique `id` value of the element.
+     *
+     *  ***Note***:
+     *   - If the element has no `id`, the value of this property would be '\<NO_ID\>'.
+     */
+    Value: string;
+
+    /**
+     *  Removes the `id` attribute of the element.
+     *  @returns The state result of `id` removal process.
+     */
+    Remove(): boolean;
+
+    /**
+     *  Set (or change) a unique `id` attribute of element.
+     *
+     *  @param id - The new unique `id` of element.
+     *  @returns The new or current unique `id` of the element.
+     */
+    Set(id: string): string;
+}

package/src/types/dom/attr/attr.style.d.ts

@@ -0,0 +1,32 @@
+interface DOMStyleOfAPI {
+    /**
+     *  Set the given `CSSStyle` object properties from the element.
+     *
+     *  @param CSSObj - The `CSSStyle` object properties to set.
+     */
+    Set(CSSObj: CSSDeclaration): void;
+
+    /**
+     *  Removes the given `CSSStyle` property from the element.
+     *
+     *  @param CSSProperty - The `CSSStyle` property to remove.
+     *  @returns The state of `CSSStyle` property removal process result.
+     */
+    Remove(CSSProperty: keyof CSSDeclaration): boolean;
+
+    /**
+     *  Removes the given `CSSStyle` properties collection from the element.
+     *
+     *  @param CSSProperty - The collection of `CSSStyle` properties to remove.
+     *  @returns The state of `CSSStyle` properties removal process result.
+     */
+    Remove(...CSSProperties: (keyof CSSDeclaration)[]): boolean;
+
+    /**
+     *  Retrieves the current data value of the given `CSSStyle` property of the element.
+     *
+     *  @param CSSProperty - The `CSSStyle` property to retrieve.
+     *  @returns The retrieved data of given `CSSStyle` property.
+     */
+    Get(CSSProperty: keyof CSSDeclaration): string | null;
+}

package/src/types/dom/dom.d.ts

@@ -0,0 +1,8 @@
+declare global {
+    /**
+     *  A collection of customized and/or enhanced `DocumentObjectModel` methods.
+     */
+    readonly var DOM: DomAPI;
+}
+
+export { }

package/src/types/dom/element/create/element.create.d.ts

@@ -0,0 +1,67 @@
+/**
+ *  A collection of `DOM` element creation API methods.
+ */
+interface DOMCreateAPI {
+    /**
+     *  Generates an instance of `HTMLElement` with the given qualified tag.
+     *
+     *  @param tag - The tag of `HTMLElement` to generate.
+     *
+     *  @throws {ArgumentError} - When parameter tag is not in string format.
+     *  @throws {NoSuchElementTagError} - When the given tag of `HTMLElement` is not qualified.
+     */
+    HTMLElement<T extends keyof HTMLElementTags>(tag: T): ResolveTag<T>;
+
+    /**
+     *  Generates an instance of `HTMLElement` with the given qualified tag.
+     *
+     *  @param tag - The tag of `HTMLElement` to generate.
+     *  @param conf - A configuration properties for `HTMLElement` instance.
+     *
+     *  @throws {ArgumentError} - When parameter tag is not in string format.
+     *  @throws {NoSuchElementTagError} - When the given tag of `HTMLElement` is not qualified.
+     */
+    HTMLElement<T extends keyof HTMLElementTags>(tag: T, conf?: HTMLElementConfig): ResolveTag<T>;
+
+    /**
+     *  Generates an instance of `MathMLElement` with the given qualified tag.
+     *
+     *  @param tag - The tag of `MathMLElement` to generate.
+     *
+     *  @throws {ArgumentError} - When parameter tag is not in string format.
+     *  @throws {NoSuchElementTagError} - When the given tag of `MathMLElement` is not qualified.
+     */
+    MathElement<T extends keyof MathElementTags>(tag: T): ResolveTag<T>;
+
+    /**
+     *  Generates an instance of `MathMLElement` with the given qualified tag.
+     *
+     *  @param tag - The tag of `MathMLElement` to generate.
+     *  @param conf - A configuration properties for `MathMLElement` instance.
+     *
+     *  @throws {ArgumentError} - When parameter tag is not in string format.
+     *  @throws {NoSuchElementTagError} - When the given tag of `MathMLElement` is not qualified.
+     */
+    MathElement<T extends keyof MathElementTags>(tag: T, conf?: MathElementConfig): ResolveTag<T>;
+
+    /**
+     *  Generates an instance of `SVGElement` with the given qualified tag.
+     *
+     *  @param tag - The tag of `SVGElement` to generate.
+     *
+     *  @throws {ArgumentError} - When parameter tag is not in string format.
+     *  @throws {NoSuchElementTagError} - When the given tag of `SVGElement` is not qualified.
+     */
+    SVGElement<T extends keyof SVGElementTags>(tag: T): ResolveTag<T>;
+
+    /**
+     *  Generates an instance of `SVGElement` with the given qualified tag.
+     *
+     *  @param tag - The tag of `SVGElement` to generate.
+     *  @param conf - A configuration properties for `SVGElement` instance.
+     *
+     *  @throws {ArgumentError} - When parameter tag is not in string format.
+     *  @throws {NoSuchElementTagError} - When the given tag of `SVGElement` is not qualified.
+     */
+    SVGElement<T extends keyof SVGElementTags>(tag: T, conf?: SVGElementConfig): ResolveTag<T>;
+}

package/src/types/dom/element/getElementBy/dom.getElementBy.d.ts

@@ -0,0 +1,71 @@
+interface DOMGetElementByAPI {
+    /**
+     *  Search and retrieves the elements with the given class name.
+     *
+     *  @param cls - The class name of element to search.
+     *  @returns The collection of elements with the given class name.
+     */
+    ClassName(cls: string): HTMLCollectionOf<Element>;
+
+    /**
+     *  Search and retrieves the elements with the given class name.
+     *
+     *  @param cls - The class name of element to search.
+     *  @param root - The parent element of where to search the elements with the given class name. (Default: Document)
+     *  @returns The collection of elements with the given class name.
+    */
+    ClassName(cls: string, root?: ParentNode): HTMLCollectionOf<Element>;
+
+    /**
+     *  Search and retrieves the element with the given unique `id`.
+     *
+     *  @param id - The unique `id` of element to search.
+     *  @returns The element with the given unique `id`.
+     */
+    ID(id: string): HTMLElement | null;
+
+    /**
+     *  Search and retrieves the element with the given unique `id`.
+     *
+     *  @param id - The unique `id` of element to search.
+     *  @param root - The root element of where to search the element with the given `unique` id. (Default: Document)
+     *  @returns The element with the given unique `id`.
+     */
+    ID(id: string, root?: ParentNode): HTMLElement | null;
+
+    /**
+     *  Search and retrieves the elements with the given tag.
+     *
+     *  @param id - The tag of element to search.
+     *  @returns The collection of elements with the given tag.
+     */
+    TagName<T extends keyof ElementTags>(tag: T): ResolveTag<T>;
+
+    /**
+     *  Search and retrieves the elements with the given tag.
+     *
+     *  @param id - The tag of element to search.
+     *  @param root - The parent element of where to search the elements with the given tag. (Default: Document)
+     *  @returns The collection of elements with the given tag.
+     */
+    TagName<T extends keyof ElementTags>(tag: T, root?: ParentNode): ResolveTag<T>;
+
+    /**
+     *  Search and retrieves the elements with the given XML namespace and tag.
+     *
+     *  @param namespace - The XML namespace of element.
+     *  @param tag - The tag of element with the given XML namespace to search.
+     *  @returns The collection of elements with the given XML namespace and tag.
+     */
+    TagNameNS<NS extends XMLNameSpace, T extends keyof ElementTags>(namespace: NS, tag: T): ResolveTagNS<NS, T>;
+
+    /**
+     *  Search and retrieves the elements with the given XML namespace and tag.
+     *
+     *  @param namespace - The XML namespace of element.
+     *  @param tag - The tag of element with the given XML namespace to search.
+     *  @param root - The parent element of where to search the elements with the given XML namespace and tag. (Default: Document)
+     *  @returns The collection of elements with the given XML namespace and tag.
+     */
+    TagNameNS<NS extends XMLNameSpace, T extends keyof ElementTags>(namespace: NS, tag: T, root?: ParentNode): ResolveTagNS<NS, T>;
+}

package/src/types/dom/element/tag-verifier/verifier.d.ts

@@ -0,0 +1,16 @@
+interface VerifierTagAPI<K extends keyof ElementTags> {
+    /**
+     *  Verifies the given tag of element whether if its qualified as instance of `HTMLElement`.
+     */
+    HTMLElement(): ResolveTag<K>;
+
+    /**
+     *  Verifies the given tag of element whether if its qualified as instance of `MathMLElement`.
+     */
+    MathElement(): ResolveTag<K>;
+
+    /**
+     *  Verifies the given tag of element whether if its qualified as instance of `SVGElement`.
+     */
+    SVGElement(): ResolveTag<K>;
+}

package/src/types/global.d.ts

@@ -0,0 +1,13 @@
+declare global {
+    /**
+     *  A collection of enhanced and custom utilities modules.
+     */
+    readonly var Utils: EnhancedGlobalUtilsAPI;
+
+    /**
+     *  A enhanced version collection of element retrieval methods.
+     */
+    readonly var GetElementBy: DOMGetElementByAPI;
+}
+
+export { }

package/src/types/guards/data-types/data-types.d.ts

@@ -0,0 +1,5 @@
+type DataTypesModule = typeof import("../../../utils/guards/data-types/data-types.js");
+
+type GuardsDataTypesAPI = {
+    [K in keyof DataTypesModule]: DataTypesModule[K];
+}

package/src/types/guards/formats/formats.d.ts

@@ -0,0 +1,5 @@
+type FormatsModule = typeof import("../../../utils/guards/formats/formats.js");
+
+type GuardsFormatAPI = {
+    [K in keyof FormatsModule]: FormatsModule[K];
+}

package/src/types/guards/guards.d.ts

@@ -0,0 +1,8 @@
+declare global {
+    /**
+     *  A collection of data types and formats guards validation.
+     */
+    readonly var Guards: GuardsAPI;
+}
+
+export { }

package/src/types/primitives/obj/obj.accessor.d.ts

@@ -0,0 +1,5 @@
+type ObjAccessorModule = typeof import("../../../utils/primitives/obj/obj.accessor.js");
+
+type PrimitivesObjAccessorAPI = {
+    [K in keyof ObjAccessorModule]: ObjAccessorModule[K];
+}

package/src/types/primitives/obj/obj.iterator.d.ts

@@ -0,0 +1,5 @@
+type ObjIteratorModule = typeof import("../../../utils/primitives/obj/obj.iterator.js");
+
+type PrimitivesIteratorAPI = {
+    [K in keyof ObjIteratorModule]: ObjIteratorModule[K];
+}

package/src/types/primitives/primitives.d.ts

@@ -0,0 +1,8 @@
+declare global {
+    /**
+     *  A enhanced version of primitive methods API.
+     */
+    readonly var Primitives: PrimitivesAPI;
+}
+
+export { }

package/src/types/primitives/str/str.d.ts

@@ -0,0 +1,26 @@
+interface PrimitivesStrAPI {
+    /**
+     *  A collection of characters.
+     */
+    readonly Chars: {
+        /**
+         *  A collection of numeric characters. (`0-9`)
+         */
+        Numeric(): string;
+
+        /**
+         *  A collection of lowercase characters. (`a-z`)
+         */
+        Lowercase(): string;
+
+        /**
+         *  A collection of special or symbol characters. (`~!@#$...`)
+         */
+        Symbols(): string;
+
+        /**
+         *  A collection of uppercase characters. (`A-Z`)
+         */
+        Uppercase(): string;
+    }
+}

package/src/types/storage/local/storage.local.d.ts

@@ -0,0 +1,86 @@
+type LocalStorageResponse<OtherMeta extends {} = {}> = {
+    State: boolean;
+    Reason?: "DUPLICATE_KEY_FOUND" | "INVALID_KEY" | "NO_SUCH_KEY" | "NOT_SUPPORTED"
+} & OtherMeta;
+
+interface LocalStorageAPI {
+    /**
+     *  The current total count of items at `localStorage`.
+     */
+    ITEMS_COUNT: number;
+
+    /**
+     *  The current total accumulated bytes size of items at `localStorage`.
+     *
+     *  ***Notes***
+     *   - This does not tells or let you know on how much of a bytes size is remaining at your
+     *     browser `localStorage` API.
+     *
+     *  @returns The total accumulated bytes size.
+     */
+    SIZE(): number;
+
+    /**
+     *  Indicates whether if the `localStorage` API is supported on your or user's current browser environment version.
+     */
+    readonly IS_SUPPORTED: boolean;
+
+    /**
+     *  Retrieves the stored data of the specified `localStorage` key.
+     *
+     *  ***Notes***
+     *   - Automatically parsed the `JSON` object of the retrieved data. If you want it to
+     *     be in raw format, provide a `false` state as its second parameter.
+     *
+     *  @param localKey - The access key of `localStorage` item.
+     *  @returns The retrieved data at `localStorage`.
+     */
+    GET(localKey: string): LocalStorageResponse<{ Data: unknown | undefined }>;
+
+    /**
+     *  Retrieves the stored data of the specified `localStorage` key.
+     *
+     *  ***Notes***
+     *   - Automatically parsed the `JSON` object of the retrieved data. If you want it to
+     *     be in raw format, provide a `false` state as its second parameter.
+     *
+     *  @param localKey - The access key of storage item to retrieve.
+     *  @param autoParse - A state for controlling whether if it should automatically parse the retrieved data at `localStorage` item or not.
+     *  @returns The retrieved data at `localStorage`.
+     */
+    GET<B extends boolean = true>(localKey: string, autoParse?: B): LocalStorageResponse<{
+        Data: (B extends true ? unknown : string) | undefined;
+    }>;
+
+    /**
+     *  Store a new item with its data at the `localStorage` API.
+     *
+     *  ***Notes***:
+     *   - If there's a already storage item with the same `key` at `localStorage` API, it will automatically
+     *     terminate the process and returns a default response object with reason in it.
+     *   - Automatically converts the specified data to store along with the new storage item into its stringified
+     *     format using `JSON.stringify` built-in method.
+     *
+     *  @param localKey - The access key of new storage item.
+     *  @param data - The data of the new storage item.
+     *  @returns The response object of this process.
+     */
+    NEW(localKey: string, data?: any): LocalStorageResponse;
+
+    /**
+     *  Removes the specified `key` of a storage item at `localStorage` API.
+     *
+     *  @param localKey - The access key of storage item to remove.
+     *  @returns The response object of this process.
+     */
+    REMOVE(localKey: string): LocalStorageResponse;
+
+    /**
+     *  Updates the data of the specified `key` of storage item with the given new data for it at `localStorage` API.
+     *
+     *  @param localKey - The access key of storage item to update.
+     *  @param newData - The new data to set at storage item.
+     *  @returns The response object of this process.
+     */
+    UPDATE(localKey: string, newData?: any): LocalStorageResponse;
+}

package/src/types/storage/session/storage.session.d.ts

@@ -0,0 +1,86 @@
+type SessionStorageResponse<OtherMeta extends {} = {}> = {
+    State: boolean;
+    Reason?: "DUPLICATE_KEY_FOUND" | "INVALID_KEY" | "NO_SUCH_KEY" | "NOT_SUPPORTED"
+} & OtherMeta;
+
+interface SessionStorageAPI {
+    /**
+     *  The current total count of items at `sessionStorage`.
+     */
+    ITEMS_COUNT: number;
+
+    /**
+     *  The current total accumulated bytes size of items at `sessionStorage`.
+     *
+     *  ***Notes***
+     *   - This does not tells or let you know on how much of a bytes size is remaining at your
+     *     browser `sessionStorage` API.
+     *
+     *  @returns The total accumulated bytes size.
+     */
+    SIZE(): number;
+
+    /**
+     *  Indicates whether if the `sessionStorage` API is supported on your or user's current browser environment version.
+     */
+    readonly IS_SUPPORTED: boolean;
+
+    /**
+     *  Retrieves the stored data of the specified `sessionStorage` key.
+     *
+     *  ***Notes***
+     *   - Automatically parsed the `JSON` object of the retrieved data. If you want it to
+     *     be in raw format, provide a `false` state as its second parameter.
+     *
+     *  @param sessionKey - The access key of `sessionStorage` item.
+     *  @returns The retrieved data at `sessionStorage`.
+     */
+    GET(sessionKey: string): SessionStorageResponse<{ Data: unknown | undefined }>;
+
+    /**
+     *  Retrieves the stored data of the specified `sessionStorage` key.
+     *
+     *  ***Notes***
+     *   - Automatically parsed the `JSON` object of the retrieved data. If you want it to
+     *     be in raw format, provide a `false` state as its second parameter.
+     *
+     *  @param sessionKey - The access key of storage item to retrieve.
+     *  @param autoParse - A state for controlling whether if it should automatically parse the retrieved data at `sessionStorage` item or not.
+     *  @returns The retrieved data at `sessionStorage`.
+     */
+    GET<B extends boolean = true>(sessionKey: string, autoParse?: B): SessionStorageResponse<{
+        Data: (B extends true ? unknown : string) | undefined;
+    }>;
+
+    /**
+     *  Store a new item with its data at the `sessionStorage` API.
+     *
+     *  ***Notes***:
+     *   - If there's a already storage item with the same `key` at `sessionStorage` API, it will automatically
+     *     terminate the process and returns a default response object with reason in it.
+     *   - Automatically converts the specified data to store along with the new storage item into its stringified
+     *     format using `JSON.stringify` built-in method.
+     *
+     *  @param sessionKey - The access key of new storage item.
+     *  @param data - The data of the new storage item.
+     *  @returns The response object of this process.
+     */
+    NEW(sessionKey: string, data?: any): SessionStorageResponse;
+
+    /**
+     *  Removes the specified `key` of a storage item at `sessionStorage` API.
+     *
+     *  @param sessionKey - The access key of storage item to remove.
+     *  @returns The response object of this process.
+     */
+    REMOVE(sessionKey: string): SessionStorageResponse;
+
+    /**
+     *  Updates the data of the specified `key` of storage item with the given new data for it at `sessionStorage` API.
+     *
+     *  @param sessionKey - The access key of storage item to update.
+     *  @param newData - The new data to set at storage item.
+     *  @returns The response object of this process.
+     */
+    UPDATE(sessionKey: string, newData?: any): SessionStorageResponse;
+}

package/src/types/storage/storage.d.ts

@@ -0,0 +1,8 @@
+declare global {
+    /**
+     *  A enhanced version of `StorageAPI` methods.
+     */
+    readonly var STORAGE: StorageAPI;
+}
+
+export { }