instrumentality 0.0.3 → 0.0.4

package/README.md

@@ -1,5 +1,5 @@
-![white title](./assets/title-white.gif#gh-dark-mode-only)
-![black title](./assets/title-black.gif#gh-light-mode-only)
+<!-- ![black title](./assets/titleDark.webp#gh-light-mode-only) -->
+![white title](./assets/titleLight.webp#gh-dark-mode-only)
 
 
 ## The INSTRUMENTALITY project (concept)

package/dist/base.d.ts

@@ -1,6 +1,4 @@
-/**
- * Subclass of {@link Error} that represents an error thrown from this library, providing a specific name for easier identification.
- */
+/** 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;
 }
@@ -9,29 +7,30 @@ export declare class InsErr extends Error {
  *
  * @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 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.
+ * @returns The result of {@link fn_} if it succeeds within the allowed attempts.
+ * @throws {unknown} If {@link fn_} fails after the maximum attempts, the last error thrown by {@link fn_} is re-thrown.
+ * @throws {InsErr} If the maximum attempts is less than 1 or if the operation is aborted.
  */
-export declare function retry<T>(fn_: () => T, maxAttempts_: number, _cbErr?: () => unknown, abs_?: AbortSignal): Promise<T>;
+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.
+ * Asynchronously sleep.
  *
  * @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.
+ * @throws {InsErr} If the sleep is aborted before or during the wait.
  */
 export declare function sleep(ms_: number, abs_?: AbortSignal): Promise<void>;
 /**
- * Helper type to build a tuple of a specified length.
+ * 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.
+ * Add two number types together.
  *
  * @template A - The first number type.
  * @template B - The second number type.
@@ -41,38 +40,35 @@ export type Add<A extends number, B extends number> = [
     ...BuildTuple<B>
 ]['length'];
 /**
- * Helper type to enumerate numbers from 0 to N-1.
+ * Enumerate numbers from 0 to N-1 as a union type.
  *
  * @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.
+ * Wrapper around {@link performance.now}
  *
  * @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.
- * @accessor {@link mn} - Elapsed time in months.
- * @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.
+ * @accessor {@link y} (years)
+ * @accessor {@link mn} (months)
+ * @accessor {@link w} (weeks)
+ * @accessor {@link d} (days)
+ * @accessor {@link h} (hours)
+ * @accessor {@link m} (minutes)
+ * @accessor {@link s} (seconds)
+ * @accessor {@link ms} (milliseconds)
+ * @accessor {@link μs} (microseconds)
+ * @accessor {@link ns} (nanoseconds)
+ * @accessor {@link ps} (picoseconds)
  */
 export declare class Benchmark {
-    /** An array that stores the recorded elapsed times from each round. */
+    /** An array that stores the recorded elapsed times from each round (relative to the previous). */
     rounds: number[];
-    /** Initializes the benchmark timer to the current time using `performance.now()`. */
+    /** The initial timestamp when the benchmark was created or last reset. */
     timer: number;
     /** Records the current elapsed time and restarts the timer. */
     round(): void;
@@ -102,9 +98,7 @@ export declare class Benchmark {
     get ps(): number;
 }
 export { Benchmark as Bench, Benchmark as Timer, Benchmark as Stopwatch };
-/**
- * Helper type that represents a view of a Uint8Array, exposing only view methods and properties, along with a readonly index signature for accessing elements.
- */
+/** Compiler sugar to hide mutating methods/properties for read-only operations (no runtime effect). */
 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;
 };
@@ -115,32 +109,21 @@ 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 14% overhead for regular data, 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.
+ * Encodes indexed data into a base-122 representation.
  *
- * @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
+ * @throws If somehow malformed UTF-8 data is generated, the {@link TextDecoder} will throw an error (shouldn't happen if the input is valid).
+ * @remarks The high density might not be suitable for all use cases, especially if the medium used to transmit the data has limitations on character sets or encoding.
+ * @see {@link TextDecoder} how the output string is generated from the byte array (this step is necessary for accurate translation to a string).
  */
 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<ArrayBuffer>;
 //# sourceMappingURL=base.d.ts.map

package/dist/base.d.ts.map

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

package/dist/base.js

@@ -1,6 +1,4 @@
-/**
- * Subclass of {@link Error} that represents an error thrown from this library, providing a specific name for easier identification.
- */
+/** 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";
 }
@@ -9,32 +7,33 @@ export class InsErr extends Error {
  *
  * @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 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.
+ * @returns The result of {@link fn_} if it succeeds within the allowed attempts.
+ * @throws {unknown} If {@link fn_} fails after the maximum attempts, the last error thrown by {@link fn_} is re-thrown.
+ * @throws {InsErr} If the maximum attempts is less than 1 or if the operation is aborted.
  */
-export async function retry(fn_, maxAttempts_, _cbErr, abs_) {
+export async function retry(fn_, maxAttempts_, cbErr_, abs_) {
     while (--maxAttempts_ >= 0 && !(abs_?.aborted ?? false))
         try {
             return await fn_();
         }
         catch (err) {
-            if (maxAttempts_ === 0)
+            if (maxAttempts_ <= 0)
                 throw err;
-            await _cbErr?.();
+            await cbErr_?.();
         }
     if (maxAttempts_ < 0)
-        throw new InsErr("Max attempts exceeded");
+        throw new InsErr("Max attempts must be at least 1");
     else
         throw new InsErr("Operation aborted");
 }
 /**
- * Asynchronously sleeps for a specified duration, with optional abort signal support.
+ * Asynchronously sleep.
  *
  * @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.
+ * @throws {InsErr} If the sleep is aborted before or during the wait.
  */
 export async function sleep(ms_, abs_) {
     if (abs_?.aborted)
@@ -53,31 +52,28 @@ export async function sleep(ms_, abs_) {
     });
 }
 /**
- * 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.
+ * Wrapper around {@link performance.now}
  *
  * @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.
- * @accessor {@link mn} - Elapsed time in months.
- * @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.
+ * @accessor {@link y} (years)
+ * @accessor {@link mn} (months)
+ * @accessor {@link w} (weeks)
+ * @accessor {@link d} (days)
+ * @accessor {@link h} (hours)
+ * @accessor {@link m} (minutes)
+ * @accessor {@link s} (seconds)
+ * @accessor {@link ms} (milliseconds)
+ * @accessor {@link μs} (microseconds)
+ * @accessor {@link ns} (nanoseconds)
+ * @accessor {@link ps} (picoseconds)
  */
 export class Benchmark {
-    /** An array that stores the recorded elapsed times from each round. */
+    /** An array that stores the recorded elapsed times from each round (relative to the previous). */
     rounds = [];
-    /** Initializes the benchmark timer to the current time using `performance.now()`. */
+    /** The initial timestamp when the benchmark was created or last reset. */
     timer = performance.now();
     /** Records the current elapsed time and restarts the timer. */
     round() { this.rounds.push(this.ms); this.timer = performance.now(); }
@@ -121,22 +117,13 @@ export const BASE122_ILLEGAL_INDEX = {
 /** 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 14% overhead for regular data, 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.
+ * Encodes indexed data into a base-122 representation.
  *
- * @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
+ * @throws If somehow malformed UTF-8 data is generated, the {@link TextDecoder} will throw an error (shouldn't happen if the input is valid).
+ * @remarks The high density might not be suitable for all use cases, especially if the medium used to transmit the data has limitations on character sets or encoding.
+ * @see {@link TextDecoder} how the output string is generated from the byte array (this step is necessary for accurate translation to a string).
  */
 export function encode122(data_) {
     const out = [];
@@ -171,12 +158,10 @@ export function encode122(data_) {
 }
 /**
  * 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 = [];

package/dist/dom.d.ts

@@ -1,49 +1,40 @@
 import * as bs from "./base.ts";
-/**
- * Subclass of {@link bs.InsErr} that represents an error thrown from this specific module of the library
- */
+/** 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.
+ * Resolves on `DOMContentLoaded` or immediately if the document is already ready.
  */
 export declare function onceReady(): Promise<void>;
 /**
- * Retrieves an HTML element by its ID and ensures it matches the specified type.
+ * Typed accessor for {@link document.getElementById}
  *
- * @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.
+ * @param id_ - The ID of the element to retrieve.
+ * @param type_ - Expected type, defaults to {@link HTMLElement}.
+ * @returns The corresponding element if found and of the expected type, otherwise `null`.
  */
-export declare function byId<T extends HTMLElement>(id_: string, elementType_?: new () => T): T;
+export declare function byId<T extends HTMLElement>(id_: string, type_: new () => T): T | null;
 /**
- * Retrieves all HTML elements with the specified class name and ensures they match the specified type.
+ * Typed accessor for {@link document.getElementsByClassName}
  *
  * @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.
+ * @param type_ - An optional constructor function for the expected element type.
+ * @returns All elements with the specified class name and type.
  */
-export declare function byClass<T extends HTMLElement>(className_: string, elementType_?: new () => T): T[];
+export declare function byClass<T extends HTMLElement>(className_: string, type_: new () => T): T[];
 /**
- * Retrieves all HTML elements with the specified tag name.
+ * Typed accessor for {@link document.getElementsByTagName}
  *
- * @param tagName_ - The tag name of the HTML elements to retrieve.
+ * @param tag_ - The HTML tag name of the elements to retrieve.
+ * @returns An array of {@link HTMLElement}s with the specified tag name.
  */
-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;
+export declare function byTag<K extends keyof HTMLElementTagNameMap>(tag_: K): HTMLElementTagNameMap[K][];
 /**
  * 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 data_ - The data to be stored in the cookie.
  * @param path_ - An optional path for the cookie; defaults to {@link DEFAULT_PATH}.
  */
 export declare function setCookie(name_: string, data_: {
@@ -54,14 +45,14 @@ export declare function setCookie(name_: string, data_: {
     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.
+ * Expires a cookie immediately.
  *
- * @param name_ - The name of the cookie to expire.
+ * @param name_ - The name of the cookie.
  * @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.
+ * Lists all cookies as a record of key-value pairs.
  *
  * @returns A record where each key is a cookie name and each value is the corresponding cookie value.
  */

package/dist/dom.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,WAAW,CAAA;AAI/B,6GAA6G;AAC7G,qBAAa,MAAO,SAAQ,EAAE,CAAC,MAAM;IAAY,IAAI,SAA8B;CAAE;AAIrF;;GAEG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAI/C;AAID;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,IAAI,CAKrF;AAGD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAE1F;AAGD;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,qBAAqB,EAAE,IAAI,EAAE,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAEhG;AAID;;;;;;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

@@ -1,68 +1,53 @@
 import * as bs from "./base.js";
-/**
- * Subclass of {@link bs.InsErr} that represents an error thrown from this specific module of the library
- */
+/** 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.
+ * Resolves on `DOMContentLoaded` or immediately if the document is already ready.
  */
 export async function onceReady() {
     if (document.readyState === "complete" || document.readyState === "interactive")
-        return Promise.resolve();
+        return;
     return new Promise(r => document.addEventListener("DOMContentLoaded", () => r(), { once: true }));
 }
 /**
- * Retrieves an HTML element by its ID and ensures it matches the specified type.
+ * Typed accessor for {@link document.getElementById}
  *
- * @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.
+ * @param id_ - The ID of the element to retrieve.
+ * @param type_ - Expected type, defaults to {@link HTMLElement}.
+ * @returns The corresponding element if found and of the expected type, otherwise `null`.
  */
-export function byId(id_, elementType_) {
+export function byId(id_, type_) {
     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;
+    if (element instanceof type_)
+        return element;
+    return null;
 }
 /**
- * Retrieves all HTML elements with the specified class name and ensures they match the specified type.
+ * Typed accessor for {@link document.getElementsByClassName}
  *
  * @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.
+ * @param type_ - An optional constructor function for the expected element type.
+ * @returns All elements with the specified class name and 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;
-    });
+export function byClass(className_, type_) {
+    return [...document.getElementsByClassName(className_)].filter((el) => el instanceof type_);
 }
 /**
- * Retrieves all HTML elements with the specified tag name.
+ * Typed accessor for {@link document.getElementsByTagName}
  *
- * @param tagName_ - The tag name of the HTML elements to retrieve.
+ * @param tag_ - The HTML tag name of the elements to retrieve.
+ * @returns An array of {@link HTMLElement}s with the specified tag name.
  */
-export function byTag(tagName_) {
-    return Array.from(document.getElementsByTagName(tagName_));
+export function byTag(tag_) {
+    return [...document.getElementsByTagName(tag_)];
 }
-/**
- * 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 data_ - The data to be stored in the cookie.
  * @param path_ - An optional path for the cookie; defaults to {@link DEFAULT_PATH}.
  */
 export function setCookie(name_, data_, path_ = '/') {
@@ -81,22 +66,22 @@ export function setCookie(name_, data_, path_ = '/') {
     document.cookie = cookieString;
 }
 /**
- * Expires a cookie by setting its value to an empty string and its expiration date to the Unix epoch.
+ * Expires a cookie immediately.
  *
- * @param name_ - The name of the cookie to expire.
+ * @param name_ - The name of the cookie.
  * @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.
+ * Lists all cookies as a record of key-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);
+    const matches = document.cookie.matchAll(/(?:^|; )([^=;]+)=([^;]*)/g);
     for (const match of matches)
         cookies[decodeURIComponent(match[1] ?? "")] = JSON.parse(decodeURIComponent(match[2] ?? ""));
     return cookies;