instrumentality 0.0.1

package/README.md

@@ -0,0 +1,35 @@
+![white title](./assets/title-white.gif#gh-dark-mode-only)
+![black title](./assets/title-black.gif#gh-light-mode-only)
+
+
+## The INSTRUMENTALITY project
+A utility library for TypeScript/Node.js
+
+
+#
+### What is this?
+A combination of files to handle TS/JS by itself, Node and DOM (for web) that provides functions, classes and whatnot to reduce boilerplate for common operations.
+
+
+#
+### How to use
+```sh
+npm install git+https://github.com/clerkburk/ts-instrumentality.git
+```
+then
+```ts
+import * as isb from "ts-instrumentality" // Base
+import * as isn from "ts-instrumentality/dom" // Browser (if available)
+import * as isd from "ts-instrumentality/road" // Filesystem using Node.js (if available)
+```
+thats literally it
+
+
+#
+### Other things
+...?
+
+
+#
+### LICENSE
+MIT

package/dist/base.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Subclass of {@link Error} that represents an error thrown from this library, providing a specific name for easier identification.
+ */
+export declare class InsErr extends Error {
+    name: string;
+}
+/**
+ * Retries a function multiple times with optional error handling and abort signal.
+ *
+ * @param fn_ - The function to be retried.
+ * @param maxAttempts_ - The maximum number of attempts to execute the function.
+ * @param _cbErr - An optional callback function to be executed after each failed attempt.
+ * @param abs_ - An optional AbortSignal to abort the retry process.
+ * @returns The result of the function if it succeeds within the allowed attempts.
+ * @throws If the maximum number of attempts is exceeded or if the operation is aborted.
+ */
+export declare function retry<T>(fn_: () => T, maxAttempts_: number, _cbErr?: () => unknown, abs_?: AbortSignal): Promise<T>;
+/**
+ * Asynchronously sleeps for a specified duration, with optional abort signal support.
+ *
+ * @param ms_ - The number of milliseconds to sleep.
+ * @param abs_ - An optional AbortSignal to abort the sleep.
+ * @returns A Promise that resolves after the specified duration or rejects if aborted.
+ */
+export declare function sleep(ms_: number, abs_?: AbortSignal): Promise<void>;
+/**
+ * Helper type to build a tuple of a specified length.
+ *
+ * @template N - The desired length of the tuple.
+ * @template T - The tuple being built (used for recursion).
+ */
+type BuildTuple<N extends number, T extends number[] = []> = T['length'] extends N ? T : BuildTuple<N, [...T, T['length']]>;
+/**
+ * Helper type to add two number types together.
+ *
+ * @template A - The first number type.
+ * @template B - The second number type.
+ */
+export type Add<A extends number, B extends number> = [
+    ...BuildTuple<A>,
+    ...BuildTuple<B>
+]['length'];
+/**
+ * Helper type to enumerate numbers from 0 to N-1.
+ *
+ * @template N - The upper limit (exclusive) for the enumeration.
+ * @template A - The accumulator array used for recursion.
+ */
+export type Enumerate<N extends number, A extends number[] = []> = A['length'] extends N ? A[number] : Enumerate<N, [...A, A['length']]>;
+/**
+ * A benchmarking class that provides various time units for measuring elapsed time.
+ *
+ * The class starts a timer upon instantiation and provides properties to access the elapsed time in different units (milliseconds, seconds, minutes, etc.).
+ * The `round` method can be called to record the current elapsed time and restart the timer.
+ *
+ * @property {@link rounds} - An array that stores the recorded elapsed times from each round.
+ * @property {@link timer} - The initial timestamp when the benchmark was created or last reset.
+ * @method {@link round} - Records the current elapsed time and restarts the timer.
+ * @method {@link reset} - Resets the benchmark timer to the current time and clears recorded rounds.
+ * @accessor {@link y} - Elapsed time in years (assuming 365.25 days per year).
+ * @accessor {@link mn} - Elapsed time in months (assuming 30.44 days per month).
+ * @accessor {@link w} - Elapsed time in weeks.
+ * @accessor {@link d} - Elapsed time in days.
+ * @accessor {@link h} - Elapsed time in hours.
+ * @accessor {@link m} - Elapsed time in minutes.
+ * @accessor {@link s} - Elapsed time in seconds.
+ * @accessor {@link ms} - Elapsed time in milliseconds.
+ * @accessor {@link μs} - Elapsed time in microseconds.
+ * @accessor {@link ns} - Elapsed time in nanoseconds.
+ * @accessor {@link ps} - Elapsed time in picoseconds.
+ */
+export declare class Benchmark {
+    /** An array that stores the recorded elapsed times from each round. */
+    rounds: number[];
+    /** Initializes the benchmark timer to the current time using `performance.now()`. */
+    timer: number;
+    /** Records the current elapsed time and restarts the timer. */
+    round(): void;
+    /** Resets the benchmark timer to the current time and clears recorded rounds. */
+    reset(): void;
+    /** Elapsed time in years (assuming 365.25 days per year). */
+    get y(): number;
+    /** Elapsed time in months (assuming 30.44 days per month). */
+    get mn(): number;
+    /** Elapsed time in weeks. */
+    get w(): number;
+    /** Elapsed time in days. */
+    get d(): number;
+    /** Elapsed time in hours. */
+    get h(): number;
+    /** Elapsed time in minutes. */
+    get m(): number;
+    /** Elapsed time in seconds. */
+    get s(): number;
+    /** Elapsed time in milliseconds. */
+    get ms(): number;
+    /** Elapsed time in microseconds. */
+    get μs(): number;
+    /** Elapsed time in nanoseconds. */
+    get ns(): number;
+    /** Elapsed time in picoseconds. */
+    get ps(): number;
+}
+/**
+ * Helper type that represents a view of a Uint8Array, exposing only view methods and properties, along with a readonly index signature for accessing elements.
+ */
+export type Uint8ArrayView = Pick<Uint8Array, "at" | "includes" | "indexOf" | "lastIndexOf" | "find" | "findIndex" | "findLast" | "findLastIndex" | "every" | "some" | "forEach" | "entries" | "keys" | "values" | typeof Symbol.iterator | "reduce" | "reduceRight" | "join" | "toLocaleString" | "toString" | "map" | "filter" | "slice" | "toReversed" | "toSorted" | "with" | "length" | "byteLength" | "byteOffset"> & {
+    readonly [n: number]: number;
+};
+/** Specific reserved 7-bit values codes that must be escaped when encoding data into base-122, as they are considered illegal in the encoding scheme. */
+export declare const BASE122_ILLEGAL: readonly [0, 10, 13, 34, 38, 92];
+/** Mapping of illegal ascii codes to their corresponding indices in {@link BASE122_ILLEGAL} (reverse lookup). */
+export declare const BASE122_ILLEGAL_INDEX: Readonly<Record<number, number>>;
+/** Shortened payload marker used when escaping an illegal 7-bit value and no subsequent 7-bit chunk is available (the current chunk is reused as payload). */
+export declare const BASE122_SHORT: 7;
+/**
+ * Encodes indexed data into a base-122 representation, going as low as 9% overhead for large datasets, making base-64 look pathetic in comparison with its 33% overhead.
+ * The encoding process packs 7 bits of data into each character, and uses a two-byte sequence for reserved characters to ensure that the output string remains valid.
+ *
+ * @remarks The high density of base-122 comes with the trade-off of not being able to use the output string in certain contexts, such as URLs or file names.
+ * @param data_ - An array-like object containing the data to be encoded.
+ * @returns A string representing the base-122 encoded data.
+ * @throws If somehow malformed UTF-8 data is generated, the TextDecoder will throw an error (shouldn't happen if the input is valid).
+ * @see {@link decode122} for decoding the base-122 string back into its original byte representation.
+ * @see {@link BASE122_ILLEGAL} for the list of reserved characters that are escaped during encoding.
+ * @example
+ * // (pseudo-code)
+ * // build script
+ * appendFile(".html", `<script type="text/plain">${encode122(compress(readFile(".jpg")))}</script>`)
+ *
+ * // HTML
+ * <script type="text/plain">!!pƋ

Ƹ€€²VӦnKZ6w)jpA</script> // embedd data into HTML without it being interpreted as HTML or JS
+ */
+export declare function encode122(data_: ArrayLike<number>): string;
+/**
+ * Decodes a base-122 encoded string back into its original byte representation.
+ * The decoding process reverses the encoding, extracting 7 bits of data from each character and handling two-byte sequences for illegal characters.
+ *
+ * @param base122_ - The base-122 encoded string to decode.
+ * @returns A Uint8Array containing the original byte data.
+ * @throws If an invalid base-122 illegal index is encountered during decoding (shouldn't happen if the input was generated by {@link encode122}).
+ * @see {@link encode122} for encoding data into base-122.
+ */
+export declare function decode122(base122_: string): Uint8Array;
+export {};
+//# sourceMappingURL=base.d.ts.map

package/dist/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"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"}

package/dist/base.js

@@ -0,0 +1,209 @@
+/**
+ * Subclass of {@link Error} that represents an error thrown from this library, providing a specific name for easier identification.
+ */
+export class InsErr extends Error {
+    name = "Instrumentality-Error";
+}
+/**
+ * Retries a function multiple times with optional error handling and abort signal.
+ *
+ * @param fn_ - The function to be retried.
+ * @param maxAttempts_ - The maximum number of attempts to execute the function.
+ * @param _cbErr - An optional callback function to be executed after each failed attempt.
+ * @param abs_ - An optional AbortSignal to abort the retry process.
+ * @returns The result of the function if it succeeds within the allowed attempts.
+ * @throws If the maximum number of attempts is exceeded or if the operation is aborted.
+ */
+export async function retry(fn_, maxAttempts_, _cbErr, abs_) {
+    while (--maxAttempts_ >= 0 && !(abs_?.aborted ?? false))
+        try {
+            return await fn_();
+        }
+        catch (err) {
+            if (maxAttempts_ === 0)
+                throw err;
+            await _cbErr?.();
+        }
+    if (maxAttempts_ < 0)
+        throw new InsErr("Max attempts exceeded");
+    else
+        throw new InsErr("Operation aborted");
+}
+/**
+ * Asynchronously sleeps for a specified duration, with optional abort signal support.
+ *
+ * @param ms_ - The number of milliseconds to sleep.
+ * @param abs_ - An optional AbortSignal to abort the sleep.
+ * @returns A Promise that resolves after the specified duration or rejects if aborted.
+ */
+export async function sleep(ms_, abs_) {
+    if (abs_?.aborted)
+        return Promise.reject(new InsErr("Sleep aborted before start"));
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            abs_?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms_);
+        function onAbort() {
+            clearTimeout(timeout);
+            abs_?.removeEventListener("abort", onAbort);
+            reject(new InsErr("Sleep aborted during wait"));
+        }
+        abs_?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * A benchmarking class that provides various time units for measuring elapsed time.
+ *
+ * The class starts a timer upon instantiation and provides properties to access the elapsed time in different units (milliseconds, seconds, minutes, etc.).
+ * The `round` method can be called to record the current elapsed time and restart the timer.
+ *
+ * @property {@link rounds} - An array that stores the recorded elapsed times from each round.
+ * @property {@link timer} - The initial timestamp when the benchmark was created or last reset.
+ * @method {@link round} - Records the current elapsed time and restarts the timer.
+ * @method {@link reset} - Resets the benchmark timer to the current time and clears recorded rounds.
+ * @accessor {@link y} - Elapsed time in years (assuming 365.25 days per year).
+ * @accessor {@link mn} - Elapsed time in months (assuming 30.44 days per month).
+ * @accessor {@link w} - Elapsed time in weeks.
+ * @accessor {@link d} - Elapsed time in days.
+ * @accessor {@link h} - Elapsed time in hours.
+ * @accessor {@link m} - Elapsed time in minutes.
+ * @accessor {@link s} - Elapsed time in seconds.
+ * @accessor {@link ms} - Elapsed time in milliseconds.
+ * @accessor {@link μs} - Elapsed time in microseconds.
+ * @accessor {@link ns} - Elapsed time in nanoseconds.
+ * @accessor {@link ps} - Elapsed time in picoseconds.
+ */
+export class Benchmark {
+    /** An array that stores the recorded elapsed times from each round. */
+    rounds = [];
+    /** Initializes the benchmark timer to the current time using `performance.now()`. */
+    timer = performance.now();
+    /** Records the current elapsed time and restarts the timer. */
+    round() { this.rounds.push(this.ms); this.timer = performance.now(); }
+    /** Resets the benchmark timer to the current time and clears recorded rounds. */
+    reset() { this.rounds = []; this.timer = performance.now(); }
+    /** Elapsed time in years (assuming 365.25 days per year). */
+    get y() { return this.mn / 12; }
+    /** Elapsed time in months (assuming 30.44 days per month). */
+    get mn() { return this.w / 4; }
+    /** Elapsed time in weeks. */
+    get w() { return this.d / 7; }
+    /** Elapsed time in days. */
+    get d() { return this.h / 24; }
+    /** Elapsed time in hours. */
+    get h() { return this.m / 60; }
+    /** Elapsed time in minutes. */
+    get m() { return this.s / 60; }
+    /** Elapsed time in seconds. */
+    get s() { return this.ms / 1000; }
+    /** Elapsed time in milliseconds. */
+    get ms() { return performance.now() - this.timer; }
+    /** Elapsed time in microseconds. */
+    get μs() { return this.ms * 1e3; }
+    /** Elapsed time in nanoseconds. */
+    get ns() { return this.μs * 1e3; }
+    /** Elapsed time in picoseconds. */
+    get ps() { return this.ns * 1e3; }
+}
+/** Specific reserved 7-bit values codes that must be escaped when encoding data into base-122, as they are considered illegal in the encoding scheme. */
+export const BASE122_ILLEGAL = [0, 10, 13, 34, 38, 92];
+/** Mapping of illegal ascii codes to their corresponding indices in {@link BASE122_ILLEGAL} (reverse lookup). */
+export const BASE122_ILLEGAL_INDEX = {
+    0: 0,
+    10: 1,
+    13: 2,
+    34: 3,
+    38: 4,
+    92: 5,
+};
+/** Shortened payload marker used when escaping an illegal 7-bit value and no subsequent 7-bit chunk is available (the current chunk is reused as payload). */
+export const BASE122_SHORT = 0b111;
+/**
+ * Encodes indexed data into a base-122 representation, going as low as 9% overhead for large datasets, making base-64 look pathetic in comparison with its 33% overhead.
+ * The encoding process packs 7 bits of data into each character, and uses a two-byte sequence for reserved characters to ensure that the output string remains valid.
+ *
+ * @remarks The high density of base-122 comes with the trade-off of not being able to use the output string in certain contexts, such as URLs or file names.
+ * @param data_ - An array-like object containing the data to be encoded.
+ * @returns A string representing the base-122 encoded data.
+ * @throws If somehow malformed UTF-8 data is generated, the TextDecoder will throw an error (shouldn't happen if the input is valid).
+ * @see {@link decode122} for decoding the base-122 string back into its original byte representation.
+ * @see {@link BASE122_ILLEGAL} for the list of reserved characters that are escaped during encoding.
+ * @example
+ * // (pseudo-code)
+ * // build script
+ * appendFile(".html", `<script type="text/plain">${encode122(compress(readFile(".jpg")))}</script>`)
+ *
+ * // HTML
+ * <script type="text/plain">!!pƋ

Ƹ€€²VӦnKZ6w)jpA</script> // embedd data into HTML without it being interpreted as HTML or JS
+ */
+export function encode122(data_) {
+    const out = [];
+    let byteIndex = 0;
+    let bitIndex = 0;
+    function next7() {
+        if (byteIndex >= data_.length)
+            return undefined;
+        const first = data_[byteIndex];
+        const head = (((0b11111110 >>> bitIndex) & first) << bitIndex) >>> 1;
+        bitIndex += 7;
+        if (bitIndex < 8)
+            return head;
+        bitIndex -= 8;
+        byteIndex++;
+        if (byteIndex >= data_.length)
+            return head;
+        const tail = ((((0xff00 >>> bitIndex) & data_[byteIndex]) & 0xff) >>> (8 - bitIndex));
+        return head | tail;
+    }
+    for (let value = next7(); value !== undefined; value = next7()) {
+        const illegalIndex = BASE122_ILLEGAL_INDEX[value];
+        if (illegalIndex === undefined)
+            out.push(value);
+        else {
+            const next = next7();
+            const payload = next ?? value;
+            out.push(0b11000010 | ((next === undefined ? BASE122_SHORT : illegalIndex) << 2) | (payload >>> 6), 0b10000000 | (payload & 0b00111111));
+        }
+    }
+    return new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(out));
+}
+/**
+ * Decodes a base-122 encoded string back into its original byte representation.
+ * The decoding process reverses the encoding, extracting 7 bits of data from each character and handling two-byte sequences for illegal characters.
+ *
+ * @param base122_ - The base-122 encoded string to decode.
+ * @returns A Uint8Array containing the original byte data.
+ * @throws If an invalid base-122 illegal index is encountered during decoding (shouldn't happen if the input was generated by {@link encode122}).
+ * @see {@link encode122} for encoding data into base-122.
+ */
+export function decode122(base122_) {
+    const out = [];
+    let current = 0;
+    let bitIndex = 0;
+    function push7(value_) {
+        let bits = (value_ & 0b01111111) << 1;
+        current |= bits >>> bitIndex;
+        bitIndex += 7;
+        if (bitIndex < 8)
+            return;
+        out.push(current & 0xff);
+        bitIndex -= 8;
+        bits = (bits << (7 - bitIndex)) & 0xff;
+        current = bits;
+    }
+    for (let i = 0; i < base122_.length; i++) {
+        const code = base122_.charCodeAt(i);
+        if (code <= 0x7f) {
+            push7(code);
+            continue;
+        }
+        const illegalIndex = (code >>> 8) & 0b111;
+        if (illegalIndex < BASE122_ILLEGAL.length)
+            push7(BASE122_ILLEGAL[illegalIndex]);
+        else if (illegalIndex !== BASE122_SHORT)
+            throw new InsErr(`Invalid base-122 illegal index ${illegalIndex} at position ${i}`);
+        push7(code & 0b01111111);
+    }
+    return Uint8Array.from(out);
+}

package/dist/dom.d.ts

@@ -0,0 +1,69 @@
+import * as bs from "./base.ts";
+/**
+ * Subclass of {@link bs.InsErr} that represents an error thrown from this specific module of the library
+ */
+export declare class DomErr extends bs.InsErr {
+    name: string;
+}
+/**
+ * Returns a Promise that resolves when the DOM is fully loaded and ready.
+ *
+ * @returns A Promise that resolves when the DOM is ready.
+ */
+export declare function onceReady(): Promise<void>;
+/**
+ * Retrieves an HTML element by its ID and ensures it matches the specified type.
+ *
+ * @param id_ - The ID of the HTML element to retrieve.
+ * @param elementType_ - An optional constructor function for the expected element type.
+ * @returns The HTML element with the specified ID and type.
+ * @throws Will throw an error if the element is not found or does not match the expected type.
+ */
+export declare function byId<T extends HTMLElement>(id_: string, elementType_?: new () => T): T;
+/**
+ * Retrieves all HTML elements with the specified class name and ensures they match the specified type.
+ *
+ * @param className_ - The class name of the elements to retrieve.
+ * @param elementType_ - An optional constructor function for the expected element type.
+ * @returns An array of {@link HTMLElement} with the specified class name and type.
+ * @throws Will throw an error if any element does not match the expected type.
+ */
+export declare function byClass<T extends HTMLElement>(className_: string, elementType_?: new () => T): T[];
+/**
+ * Retrieves all HTML elements with the specified tag name.
+ *
+ * @param tagName_ - The tag name of the HTML elements to retrieve.
+ */
+export declare function byTag<K extends keyof HTMLElementTagNameMap>(tagName_: K): HTMLElementTagNameMap[K][];
+/**
+ * Regular expression to match cookie name-value pairs in a cookie string.
+ */
+export declare const COOKIE_PAIR_REGEX: RegExp;
+/**
+ * Sets a cookie with the specified name, data, and optional path.
+ *
+ * @param name_ - The name of the cookie.
+ * @param data_ - The data to be stored in the cookie, including its value and optional attributes.
+ * @param path_ - An optional path for the cookie; defaults to {@link DEFAULT_PATH}.
+ */
+export declare function setCookie(name_: string, data_: {
+    value: unknown;
+    expires?: Date | number;
+    domain?: string;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}, path_?: string): void;
+/**
+ * Expires a cookie by setting its value to an empty string and its expiration date to the Unix epoch.
+ *
+ * @param name_ - The name of the cookie to expire.
+ * @param path_ - An optional path for the cookie; defaults to {@link DEFAULT_PATH}.
+ */
+export declare function expireCookie(name_: string, path_?: string): void;
+/**
+ * Lists all cookies as a record of name-value pairs.
+ *
+ * @returns A record where each key is a cookie name and each value is the corresponding cookie value.
+ */
+export declare function cookies(): Record<string, unknown>;
+//# sourceMappingURL=dom.d.ts.map

package/dist/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,WAAW,CAAA;AAC/B;;GAEG;AACH,qBAAa,MAAO,SAAQ,EAAE,CAAC,MAAM;IAAY,IAAI,SAA8B;CAAE;AAIrF;;;;GAIG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAI/C;AAID;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,CAMtF;AAGD;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAOlG;AAGD;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,qBAAqB,EAAE,QAAQ,EAAE,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAEpG;AAID;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAA8B,CAAA;AAI5D;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE;IAC9C,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAA;CACrC,EAAE,KAAK,SAAM,GAAG,IAAI,CASpB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,IAAI,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMjD"}

package/dist/dom.js

@@ -0,0 +1,103 @@
+import * as bs from "./base.js";
+/**
+ * Subclass of {@link bs.InsErr} that represents an error thrown from this specific module of the library
+ */
+export class DomErr extends bs.InsErr {
+    name = "Instrumentality-DOM-Error";
+}
+/**
+ * Returns a Promise that resolves when the DOM is fully loaded and ready.
+ *
+ * @returns A Promise that resolves when the DOM is ready.
+ */
+export async function onceReady() {
+    if (document.readyState === "complete" || document.readyState === "interactive")
+        return Promise.resolve();
+    return new Promise(r => document.addEventListener("DOMContentLoaded", () => r(), { once: true }));
+}
+/**
+ * Retrieves an HTML element by its ID and ensures it matches the specified type.
+ *
+ * @param id_ - The ID of the HTML element to retrieve.
+ * @param elementType_ - An optional constructor function for the expected element type.
+ * @returns The HTML element with the specified ID and type.
+ * @throws Will throw an error if the element is not found or does not match the expected type.
+ */
+export function byId(id_, elementType_) {
+    const element = document.getElementById(id_);
+    const typeCtor = elementType_ ?? HTMLElement;
+    if (!(element instanceof typeCtor))
+        throw new DomErr(`Type missmatch: Element with id '${id_}' is not of type ${typeCtor.name}`);
+    return element;
+}
+/**
+ * Retrieves all HTML elements with the specified class name and ensures they match the specified type.
+ *
+ * @param className_ - The class name of the elements to retrieve.
+ * @param elementType_ - An optional constructor function for the expected element type.
+ * @returns An array of {@link HTMLElement} with the specified class name and type.
+ * @throws Will throw an error if any element does not match the expected type.
+ */
+export function byClass(className_, elementType_) {
+    return Array.from(document.getElementsByClassName(className_)).map((element, index) => {
+        const typeCtor = elementType_ ?? HTMLElement;
+        if (!(element instanceof typeCtor))
+            throw new DomErr(`Type missmatch: Element at index ${index} with class '${className_}' is not of type ${typeCtor.name}`);
+        return element;
+    });
+}
+/**
+ * Retrieves all HTML elements with the specified tag name.
+ *
+ * @param tagName_ - The tag name of the HTML elements to retrieve.
+ */
+export function byTag(tagName_) {
+    return Array.from(document.getElementsByTagName(tagName_));
+}
+/**
+ * Regular expression to match cookie name-value pairs in a cookie string.
+ */
+export const COOKIE_PAIR_REGEX = /(?:^|; )([^=;]+)=([^;]*)/g;
+/**
+ * Sets a cookie with the specified name, data, and optional path.
+ *
+ * @param name_ - The name of the cookie.
+ * @param data_ - The data to be stored in the cookie, including its value and optional attributes.
+ * @param path_ - An optional path for the cookie; defaults to {@link DEFAULT_PATH}.
+ */
+export function setCookie(name_, data_, path_ = '/') {
+    let cookieString = `${encodeURIComponent(name_)}=${encodeURIComponent(JSON.stringify(data_.value))}; Path=${path_}`;
+    if (data_.expires)
+        if (data_.expires instanceof Date)
+            cookieString += `; Expires=${data_.expires.toUTCString()}`;
+        else
+            cookieString += `; Max-Age=${data_.expires}`;
+    if (data_.domain)
+        cookieString += `; Domain=${data_.domain}`;
+    if (data_.secure)
+        cookieString += `; Secure`;
+    if (data_.sameSite)
+        cookieString += `; SameSite=${data_.sameSite}`;
+    document.cookie = cookieString;
+}
+/**
+ * Expires a cookie by setting its value to an empty string and its expiration date to the Unix epoch.
+ *
+ * @param name_ - The name of the cookie to expire.
+ * @param path_ - An optional path for the cookie; defaults to {@link DEFAULT_PATH}.
+ */
+export function expireCookie(name_, path_ = '/') {
+    setCookie(name_, { value: "", expires: new Date(0) }, path_);
+}
+/**
+ * Lists all cookies as a record of name-value pairs.
+ *
+ * @returns A record where each key is a cookie name and each value is the corresponding cookie value.
+ */
+export function cookies() {
+    const cookies = {};
+    const matches = document.cookie.matchAll(COOKIE_PAIR_REGEX);
+    for (const match of matches)
+        cookies[decodeURIComponent(match[1] ?? "")] = JSON.parse(decodeURIComponent(match[2] ?? ""));
+    return cookies;
+}