@oliversalzburg/js-utils 0.7.0 → 0.8.0

package/lib/data/string.js

@@ -0,0 +1,53 @@
+import { mustExist } from "./nil.js";
+/**
+ * Indent every line of the passed text.
+ * @param subject - The text to indent.
+ * @param depth - How often to apply the indenting.
+ * @param prefix - The string to use as the indent.
+ * @returns The indented text.
+ */
+export const indent = (subject, depth = 0, prefix = "    ") => subject.replaceAll(/^/gm, prefix.repeat(depth));
+/**
+ * A fast and simple 53-bit string hash function with decent collision resistance.
+ * Largely inspired by MurmurHash2/3, but with a focus on speed/simplicity.
+ * License: Public domain. Attribution appreciated.
+ * cyrb53 (c) 2018 bryc (github.com/bryc)
+ * @param subject - The string to hash.
+ * @param seed - An optional seed value.
+ * @returns A hash of the string.
+ */
+export const hashCyrb53 = (subject, seed = 0) => {
+    let h1 = 0xdeadbeef ^ seed, h2 = 0x41c6ce57 ^ seed;
+    for (let i = 0, ch = 0; i < subject.length; i++) {
+        ch = subject.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
+    h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
+    h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return ((h2 >>> 0).toString(16).padStart(8, "0") +
+        (h1 >>> 0).toString(16).padStart(8, "0"));
+};
+/**
+ * Encodes the provided string in Base64.
+ * @param subject - The string to encode.
+ * @returns The subject string encoded in Base64.
+ */
+export const base64Encode = (subject) => {
+    const bytes = new TextEncoder().encode(subject);
+    const binString = String.fromCodePoint(...bytes);
+    return btoa(binString);
+};
+/**
+ * Decodes the provided Base64 encoded string.
+ * @param subject - The string to decode.
+ * @returns The decoded subject string.
+ */
+export const base64Decode = (subject) => {
+    const binString = atob(subject);
+    const bytes = Uint8Array.from(binString, (m) => mustExist(m.codePointAt(0)));
+    return new TextDecoder().decode(bytes);
+};
+//# sourceMappingURL=string.js.map

package/lib/data/string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.js","sourceRoot":"","sources":["../../source/data/string.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,OAAe,EAAE,KAAK,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAU,EAAE,CAC7E,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAAe,EAAE,IAAI,GAAG,CAAC,EAAU,EAAE;IAC/D,IAAI,EAAE,GAAG,UAAU,GAAG,IAAI,EACzB,EAAE,GAAG,UAAU,GAAG,IAAI,CAAC;IACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACjD,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC3B,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,UAAU,CAAC,CAAC;QACpC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC;IACD,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;IAC7C,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;IAC9C,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;IAC7C,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;IAC9C,OAAO,CACN,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC;QACxC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CACxC,CAAC;AACH,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAe,EAAU,EAAE;IACvD,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,MAAM,CAAC,aAAa,CAAC,GAAG,KAAK,CAAC,CAAC;IACjD,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC;AACxB,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAe,EAAU,EAAE;IACvD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7E,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACxC,CAAC,CAAC"}

package/lib/data/tree.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Base class to quickly provide parent-child relationships.
+ * @typeParam TNode - Your sub-class.
+ */
+export declare abstract class TreeNode<TNode> {
+    #private;
+    /**
+     * The parent.
+     * @returns The parent.
+     */
+    get parent(): TNode | undefined;
+    /**
+     * The children.
+     * @returns The children.
+     */
+    get children(): Set<TNode>;
+    /**
+     * Construct tree node.
+     * @param parent - The parent.
+     */
+    constructor(parent?: TNode);
+    /**
+     * Register a new child on the tree.
+     * @param child - A new child.
+     * @returns The child.
+     */
+    child(child: TNode): TNode;
+}

package/lib/data/tree.js

@@ -0,0 +1,45 @@
+/**
+ * Base class to quickly provide parent-child relationships.
+ * @typeParam TNode - Your sub-class.
+ */
+export class TreeNode {
+    /**
+     * The parent.
+     */
+    #parent;
+    /**
+     * Our children.
+     */
+    #children = new Set();
+    /**
+     * The parent.
+     * @returns The parent.
+     */
+    get parent() {
+        return this.#parent;
+    }
+    /**
+     * The children.
+     * @returns The children.
+     */
+    get children() {
+        return this.#children;
+    }
+    /**
+     * Construct tree node.
+     * @param parent - The parent.
+     */
+    constructor(parent) {
+        this.#parent = parent;
+    }
+    /**
+     * Register a new child on the tree.
+     * @param child - A new child.
+     * @returns The child.
+     */
+    child(child) {
+        this.children.add(child);
+        return child;
+    }
+}
+//# sourceMappingURL=tree.js.map

package/lib/data/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../source/data/tree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAgB,QAAQ;IAC7B;;OAEG;IACH,OAAO,CAAoB;IAC3B;;OAEG;IACH,SAAS,GAAG,IAAI,GAAG,EAAS,CAAC;IAE7B;;;OAGG;IACH,IAAI,MAAM;QACT,OAAO,IAAI,CAAC,OAAO,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,IAAI,QAAQ;QACX,OAAO,IAAI,CAAC,SAAS,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,YAAY,MAAc;QACzB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAY;QACjB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACzB,OAAO,KAAK,CAAC;IACd,CAAC;CACD"}

package/lib/device/shake.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The type of the details of a shake event.
+ */
+export type ShakeEventData = DeviceMotionEvent;
+/**
+ * The type of the `"shake"` event.
+ */
+export type ShakeEvent = CustomEvent<ShakeEventData> & {
+    type: "shake";
+};
+/**
+ * The type of a handler for the `"shake"` event.
+ */
+export type ShakeEventListener = (event: ShakeEvent) => void;
+/**
+ * The options for constructing a {@linkcode Shake} handler.
+ */
+export interface ShakeOptions {
+    /**
+     * Minimum acceleration needed to dispatch an event:
+     * meters per second squared (m/s²).
+     *
+     * https://developer.mozilla.org/en-US/docs/Web/API/DeviceMotionEvent/acceleration
+     */
+    threshold: number;
+    /**
+     * After a shake event is dispatched, subsequent events will not be dispatched
+     * until after a duration greater than or equal to this value (milliseconds).
+     */
+    timeout: number;
+}
+/**
+ * A device motion handler that dispatches a `"shake"` event as appropriate.
+ *
+ * Original author: Jesse Jackson - https://github.com/jsejcksn
+ * This part of the code is licensed under CC BY-SA 4.0
+ */
+export declare class Shake extends EventTarget {
+    #private;
+    /**
+     * Construct a new device shake handler.
+     * @param options - The options for the handler.
+     */
+    constructor(options?: Partial<ShakeOptions>);
+    /**
+     * Add a new shake event listener.
+     * @param type - The type of the event to handle.
+     * @param listener - The event handler to call.
+     * @param options - The options for this handler.
+     */
+    addEventListener(type: "shake", listener: ShakeEventListener | null, options?: boolean | AddEventListenerOptions): void;
+    /**
+     * Dispatch a shake event.
+     * @param event - The event to dispatch.
+     * @returns true if the event was cancelled, false otherwise.
+     */
+    dispatchEvent(event: ShakeEvent): boolean;
+    /**
+     * Removes a previously added event listener.
+     * @param type - The type of the event to remove.
+     * @param callback - The event handler to remove.
+     * @param options - The options the event handler was added with.
+     */
+    removeEventListener(type: "shake", callback: ShakeEventListener | null, options?: EventListenerOptions | boolean): void;
+    /**
+     * Requests approval to handle device motion events.
+     * @returns true if we got approval, false otherwise.
+     */
+    approve(): Promise<boolean>;
+    /**
+     * Start handling device shake.
+     * @returns true if we were able to register our handler, false otherwise.
+     */
+    start(): Promise<boolean>;
+    /**
+     * Stop handling device shake.
+     */
+    stop(): void;
+}

package/lib/device/shake.js

@@ -0,0 +1,135 @@
+import { createEvent } from "../events/event.js";
+const getMaxAcceleration = (event) => {
+    let max = 0;
+    if (event.acceleration) {
+        for (const key of ["x", "y", "z"]) {
+            const value = Math.abs(event.acceleration[key] ?? 0);
+            if (value > max)
+                max = value;
+        }
+    }
+    return max;
+};
+/**
+ * A device motion handler that dispatches a `"shake"` event as appropriate.
+ *
+ * Original author: Jesse Jackson - https://github.com/jsejcksn
+ * This part of the code is licensed under CC BY-SA 4.0
+ */
+export class Shake extends EventTarget {
+    /**
+     * Have we been granted permissions to use device motion events?
+     */
+    #approved;
+    /**
+     * How strong does the motion have to be to trigger the event?
+     */
+    #threshold;
+    /**
+     * After the event has been triggered, don't trigger another event for
+     * how many milliseconds?
+     */
+    #timeout;
+    /**
+     * The last time we triggered an event.
+     */
+    #timeStamp;
+    /**
+     * Construct a new device shake handler.
+     * @param options - The options for the handler.
+     */
+    constructor(options) {
+        super();
+        const { threshold = 15, timeout = 1000 } = options ?? {};
+        this.#threshold = threshold;
+        this.#timeout = timeout;
+        this.#timeStamp = timeout * -1;
+    }
+    /**
+     * Add a new shake event listener.
+     * @param type - The type of the event to handle.
+     * @param listener - The event handler to call.
+     * @param options - The options for this handler.
+     */
+    // @ts-expect-error
+    addEventListener(type, listener, options) {
+        super.addEventListener(type, listener, options);
+    }
+    /**
+     * Dispatch a shake event.
+     * @param event - The event to dispatch.
+     * @returns true if the event was cancelled, false otherwise.
+     */
+    dispatchEvent(event) {
+        return super.dispatchEvent(event);
+    }
+    /**
+     * Removes a previously added event listener.
+     * @param type - The type of the event to remove.
+     * @param callback - The event handler to remove.
+     * @param options - The options the event handler was added with.
+     */
+    // @ts-expect-error
+    removeEventListener(type, callback, options) {
+        super.removeEventListener(type, callback, options);
+    }
+    /**
+     * Requests approval to handle device motion events.
+     * @returns true if we got approval, false otherwise.
+     */
+    async approve() {
+        if (typeof this.#approved === "undefined") {
+            if (!("DeviceMotionEvent" in window)) {
+                this.#approved = false;
+                return false;
+            }
+            try {
+                if (typeof DeviceMotionEvent.requestPermission === "function") {
+                    const permissionState = await DeviceMotionEvent.requestPermission();
+                    this.#approved = permissionState === "granted";
+                }
+                else {
+                    this.#approved = true;
+                }
+            }
+            catch {
+                this.#approved = false;
+            }
+        }
+        return this.#approved;
+    }
+    /**
+     * Handles a device motion event.
+     * @param event - The device motion event.
+     */
+    #handleDeviceMotion = (event) => {
+        const diff = event.timeStamp - this.#timeStamp;
+        if (diff < this.#timeout) {
+            return;
+        }
+        const accel = getMaxAcceleration(event);
+        if (accel < this.#threshold) {
+            return;
+        }
+        this.#timeStamp = event.timeStamp;
+        this.dispatchEvent(createEvent("shake", event));
+    };
+    /**
+     * Start handling device shake.
+     * @returns true if we were able to register our handler, false otherwise.
+     */
+    async start() {
+        const approved = await this.approve();
+        if (!approved)
+            return false;
+        window.addEventListener("devicemotion", this.#handleDeviceMotion);
+        return true;
+    }
+    /**
+     * Stop handling device shake.
+     */
+    stop() {
+        window.removeEventListener("devicemotion", this.#handleDeviceMotion);
+    }
+}
+//# sourceMappingURL=shake.js.map

package/lib/device/shake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shake.js","sourceRoot":"","sources":["../../source/device/shake.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,kBAAkB,GAAG,CAAC,KAAwB,EAAU,EAAE;IAC/D,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QACxB,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAU,EAAE,CAAC;YAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;YACrD,IAAI,KAAK,GAAG,GAAG;gBAAE,GAAG,GAAG,KAAK,CAAC;QAC9B,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC,CAAC;AAoCF;;;;;GAKG;AACH,MAAM,OAAO,KAAM,SAAQ,WAAW;IACrC;;OAEG;IACH,SAAS,CAAW;IAEpB;;OAEG;IACH,UAAU,CAA4B;IAEtC;;;OAGG;IACH,QAAQ,CAA0B;IAElC;;OAEG;IACH,UAAU,CAAS;IAEnB;;;OAGG;IACH,YAAY,OAA+B;QAC1C,KAAK,EAAE,CAAC;QAER,MAAM,EAAE,SAAS,GAAG,EAAE,EAAE,OAAO,GAAG,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QACzD,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,UAAU,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACH,mBAAmB;IACnB,gBAAgB,CACf,IAAa,EACb,QAAmC,EACnC,OAA2C;QAG3C,KAAK,CAAC,gBAAgB,CAAC,IAAI,EAAE,QAAgB,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,KAAiB;QAC9B,OAAO,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,mBAAmB;IACnB,mBAAmB,CAClB,IAAa,EACb,QAAmC,EACnC,OAAwC;QAGxC,KAAK,CAAC,mBAAmB,CAAC,IAAI,EAAE,QAAgB,EAAE,OAAO,CAAC,CAAC;IAC5D,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO;QACZ,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,WAAW,EAAE,CAAC;YAC3C,IAAI,CAAC,CAAC,mBAAmB,IAAI,MAAM,CAAC,EAAE,CAAC;gBACtC,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;gBACvB,OAAO,KAAK,CAAC;YACd,CAAC;YAED,IAAI,CAAC;gBAMJ,IACC,OAAQ,iBAAyB,CAAC,iBAAiB,KAAK,UAAU,EACjE,CAAC;oBACF,MAAM,eAAe,GAAG,MACvB,iBACA,CAAC,iBAAiB,EAAE,CAAC;oBACtB,IAAI,CAAC,SAAS,GAAG,eAAe,KAAK,SAAS,CAAC;gBAChD,CAAC;qBAAM,CAAC;oBACP,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;gBACvB,CAAC;YACF,CAAC;YAAC,MAAM,CAAC;gBACR,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;YACxB,CAAC;QACF,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,mBAAmB,GAAG,CAAC,KAAwB,EAAQ,EAAE;QACxD,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC;QAC/C,IAAI,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC1B,OAAO;QACR,CAAC;QAED,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,KAAK,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YAC7B,OAAO;QACR,CAAC;QAED,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;IACjD,CAAC,CAAC;IAEF;;;OAGG;IACH,KAAK,CAAC,KAAK;QACV,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACtC,IAAI,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC5B,MAAM,CAAC,gBAAgB,CAAC,cAAc,EAAE,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;OAEG;IACH,IAAI;QACH,MAAM,CAAC,mBAAmB,CAAC,cAAc,EAAE,IAAI,CAAC,mBAAmB,CAAC,CAAC;IACtE,CAAC;CACD"}

package/lib/dom/core.d.ts

@@ -0,0 +1,21 @@
+import type { ConstructorOf } from "../core.js";
+/**
+ * Retrieves an element from the document and returns it if it is
+ * non-null and has the expected type. Otherwise an error is thrown.
+ * @param document - The document from which to look up the element.
+ * @param id - The ID of the element.
+ * @param Type - The type you expect the element to have.
+ * @returns The requested element, if it has the expected type.
+ * @throws {@linkcode InvalidOperationError} When the document element has an unexpected type.
+ * @throws {@linkcode  UnexpectedNilError} When the the document element is `null`.
+ */
+export declare const getDocumentElementTypeByIdStrict: <T extends HTMLElement>(document: Document, id: string, Type: ConstructorOf<T>) => T;
+/**
+ * Retrieves an element from the document and returns it if it has the
+ * expected type.
+ * @param document - The document from which to look up the element.
+ * @param id - The ID of the element.
+ * @param Type - The type you expect the element to have.
+ * @returns The requested element, if it has the expected type; `null` otherwise.
+ */
+export declare const getDocumentElementTypeById: <T extends HTMLElement>(document: Document, id: string, Type: ConstructorOf<T>) => T | null;

package/lib/dom/core.js

@@ -0,0 +1,41 @@
+import { UnexpectedNilError } from "../data/nil.js";
+import { InvalidOperationError } from "../errors/InvalidOperationError.js";
+/**
+ * Retrieves an element from the document and returns it if it is
+ * non-null and has the expected type. Otherwise an error is thrown.
+ * @param document - The document from which to look up the element.
+ * @param id - The ID of the element.
+ * @param Type - The type you expect the element to have.
+ * @returns The requested element, if it has the expected type.
+ * @throws {@linkcode InvalidOperationError} When the document element has an unexpected type.
+ * @throws {@linkcode  UnexpectedNilError} When the the document element is `null`.
+ */
+export const getDocumentElementTypeByIdStrict = (document, id, Type) => {
+    const element = document.getElementById(id);
+    if (element === null) {
+        throw new UnexpectedNilError(`The document element '${id}' does not exist.`);
+    }
+    if (!(element instanceof Type)) {
+        throw new InvalidOperationError(`The document element '${id}' has an unexpected type.`);
+    }
+    return element;
+};
+/**
+ * Retrieves an element from the document and returns it if it has the
+ * expected type.
+ * @param document - The document from which to look up the element.
+ * @param id - The ID of the element.
+ * @param Type - The type you expect the element to have.
+ * @returns The requested element, if it has the expected type; `null` otherwise.
+ */
+export const getDocumentElementTypeById = (document, id, Type) => {
+    const element = document.getElementById(id);
+    if (element === null) {
+        return null;
+    }
+    if (!(element instanceof Type)) {
+        return null;
+    }
+    return element;
+};
+//# sourceMappingURL=core.js.map

package/lib/dom/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../source/dom/core.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAE3E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAC/C,QAAkB,EAClB,EAAU,EACV,IAAsB,EAClB,EAAE;IACN,MAAM,OAAO,GAAG,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;IAE5C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,kBAAkB,CAC3B,yBAAyB,EAAE,mBAAmB,CAC9C,CAAC;IACH,CAAC;IAED,IAAI,CAAC,CAAC,OAAO,YAAY,IAAI,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,qBAAqB,CAC9B,yBAAyB,EAAE,2BAA2B,CACtD,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CACzC,QAAkB,EAClB,EAAU,EACV,IAAsB,EACX,EAAE;IACb,MAAM,OAAO,GAAG,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;IAE5C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,IAAI,CAAC,CAAC,OAAO,YAAY,IAAI,CAAC,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACb,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC,CAAC"}

package/lib/errors/AbstractError.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Base class for all errors.
+ */
+export declare class AbstractError extends Error {
+    /**
+     * The HTTP status code to associate with this error.
+     */
+    status: number;
+    /**
+     * An application-unique, readable error code.
+     */
+    code: string;
+    /**
+     * Constructs a new {@linkcode AbstractError}.
+     * @param code - The main identification code for the error.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(code: string, message: string, status: number);
+    /**
+     * Checks if an object is an instance of {@linkcode AbstractError}, or one of its subclasses.
+     * @param error - The object to check.
+     * @param allowForeignModule - Only check for similar looking error codes.
+     * You're going to want to use this if you're dealing with a setup where
+     * multiple versions of js-utils are loaded.
+     * @returns `true` if the object is an {@linkcode AbstractError}, `false` otherwise.
+     */
+    static isAbstractError(error: unknown, allowForeignModule?: boolean): error is AbstractError;
+}

package/lib/errors/AbstractError.js

@@ -0,0 +1,59 @@
+/**
+ * Base class for all errors.
+ */
+export class AbstractError extends Error {
+    /**
+     * The HTTP status code to associate with this error.
+     */
+    status;
+    /**
+     * An application-unique, readable error code.
+     */
+    code;
+    /**
+     * Constructs a new {@linkcode AbstractError}.
+     * @param code - The main identification code for the error.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.name = "AbstractError";
+        this.status = status;
+        if (typeof Error.captureStackTrace !== "undefined") {
+            // Capture a new stacktrace, otherwise it will include our base-class constructor instead of the code
+            // location we're actually interested in.
+            Error.captureStackTrace(this, AbstractError);
+        }
+    }
+    /**
+     * Checks if an object is an instance of {@linkcode AbstractError}, or one of its subclasses.
+     * @param error - The object to check.
+     * @param allowForeignModule - Only check for similar looking error codes.
+     * You're going to want to use this if you're dealing with a setup where
+     * multiple versions of js-utils are loaded.
+     * @returns `true` if the object is an {@linkcode AbstractError}, `false` otherwise.
+     */
+    static isAbstractError(error, allowForeignModule = true) {
+        if (error instanceof AbstractError) {
+            return true;
+        }
+        // When multiple versions of js-utils are loaded at runtime, the
+        // prototypes of errors don't align. In that case, we just analyze the
+        // error code.
+        if (allowForeignModule) {
+            const errorRecord = error;
+            if (Object(error) === error &&
+                "code" in errorRecord &&
+                typeof errorRecord.code === "string") {
+                const codedError = error;
+                if (codedError.code.match(/^ERR_OS_/)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=AbstractError.js.map

package/lib/errors/AbstractError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractError.js","sourceRoot":"","sources":["../../source/errors/AbstractError.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IACvC;;OAEG;IACH,MAAM,CAAS;IAEf;;OAEG;IACH,IAAI,CAAS;IAEb;;;;;OAKG;IACH,YAAY,IAAY,EAAE,OAAe,EAAE,MAAc;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,IAAI,OAAO,KAAK,CAAC,iBAAiB,KAAK,WAAW,EAAE,CAAC;YACpD,qGAAqG;YACrG,yCAAyC;YACzC,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAC9C,CAAC;IACF,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,eAAe,CACrB,KAAc,EACd,kBAAkB,GAAG,IAAI;QAEzB,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;YACpC,OAAO,IAAI,CAAC;QACb,CAAC;QAED,gEAAgE;QAChE,sEAAsE;QACtE,cAAc;QACd,IAAI,kBAAkB,EAAE,CAAC;YACxB,MAAM,WAAW,GAAG,KAAgC,CAAC;YACrD,IACC,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK;gBACvB,MAAM,IAAI,WAAW;gBACrB,OAAO,WAAW,CAAC,IAAI,KAAK,QAAQ,EACnC,CAAC;gBACF,MAAM,UAAU,GAAG,KAAyB,CAAC;gBAC7C,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;oBACvC,OAAO,IAAI,CAAC;gBACb,CAAC;YACF,CAAC;QACF,CAAC;QAED,OAAO,KAAK,CAAC;IACd,CAAC;CACD"}

package/lib/errors/InternalError.d.ts

@@ -0,0 +1,19 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * Used when an {@linkcode !Error}-like object was caught and converted into an
+ * implementation of {@linkcode AbstractError} for further processing.
+ */
+export declare class InternalError extends AbstractError {
+    /**
+     * Constructs a new {@linkcode InternalError}.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(message: string, status?: number);
+    /**
+     * Converts an error into an {@linkcode InternalError}.
+     * @param error - The error to convert.
+     * @returns An {@linkcode InternalError} that represents the given error.
+     */
+    static fromError(error: Error): InternalError;
+}

package/lib/errors/InternalError.js

@@ -0,0 +1,38 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * Used when an {@linkcode !Error}-like object was caught and converted into an
+ * implementation of {@linkcode AbstractError} for further processing.
+ */
+export class InternalError extends AbstractError {
+    /**
+     * Constructs a new {@linkcode InternalError}.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(message, status = 500) {
+        super("ERR_OS_INTERNAL", message, status);
+        this.name = "InternalError";
+        if (typeof Error.captureStackTrace !== "undefined") {
+            // Capture a new stacktrace, otherwise it will include our base-class
+            // constructor instead of the code location we're actually interested in.
+            Error.captureStackTrace(this, InternalError);
+        }
+    }
+    /**
+     * Converts an error into an {@linkcode InternalError}.
+     * @param error - The error to convert.
+     * @returns An {@linkcode InternalError} that represents the given error.
+     */
+    static fromError(error) {
+        // Create a _real_ `InternalError` instance, which we will return later.
+        const internalError = new InternalError(error.message);
+        // Assign the error to it, to inherit all the fields in the error.
+        // Then assign another `InternalError` to replace key fields, like:
+        // name, code, status, ...
+        Object.assign(internalError, error, new InternalError(error.message));
+        // Inherit the original error stack again.
+        internalError.stack = error.stack;
+        return internalError;
+    }
+}
+//# sourceMappingURL=InternalError.js.map

package/lib/errors/InternalError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InternalError.js","sourceRoot":"","sources":["../../source/errors/InternalError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;GAGG;AACH,MAAM,OAAO,aAAc,SAAQ,aAAa;IAC/C;;;;OAIG;IACH,YAAY,OAAe,EAAE,MAAM,GAAG,GAAG;QACxC,KAAK,CAAC,iBAAiB,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAE1C,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAE5B,IAAI,OAAO,KAAK,CAAC,iBAAiB,KAAK,WAAW,EAAE,CAAC;YACpD,qEAAqE;YACrE,yEAAyE;YACzE,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAC9C,CAAC;IACF,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,KAAY;QAC5B,wEAAwE;QACxE,MAAM,aAAa,GAAG,IAAI,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACvD,kEAAkE;QAClE,mEAAmE;QACnE,0BAA0B;QAC1B,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,KAAK,EAAE,IAAI,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QACtE,0CAA0C;QAC1C,aAAa,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAElC,OAAO,aAAa,CAAC;IACtB,CAAC;CACD"}

package/lib/errors/InvalidArgumentError.d.ts

@@ -0,0 +1,13 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * Used when the user supplied an argument that is not valid in the current
+ * context.
+ */
+export declare class InvalidArgumentError extends AbstractError {
+    /**
+     * Constructs a new {@linkcode InvalidArgumentError}.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(message: string, status?: number);
+}

package/lib/errors/InvalidArgumentError.js

@@ -0,0 +1,22 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * Used when the user supplied an argument that is not valid in the current
+ * context.
+ */
+export class InvalidArgumentError extends AbstractError {
+    /**
+     * Constructs a new {@linkcode InvalidArgumentError}.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(message, status = 400) {
+        super("ERR_OS_INVALID_ARGUMENT", message, status);
+        this.name = "InvalidArgumentError";
+        if (typeof Error.captureStackTrace !== "undefined") {
+            // Capture a new stacktrace, otherwise it will include our base-class
+            // constructor instead of the code location we're actually interested in.
+            Error.captureStackTrace(this, InvalidArgumentError);
+        }
+    }
+}
+//# sourceMappingURL=InvalidArgumentError.js.map

package/lib/errors/InvalidArgumentError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InvalidArgumentError.js","sourceRoot":"","sources":["../../source/errors/InvalidArgumentError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,aAAa;IACtD;;;;OAIG;IACH,YAAY,OAAe,EAAE,MAAM,GAAG,GAAG;QACxC,KAAK,CAAC,yBAAyB,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAElD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QAEnC,IAAI,OAAO,KAAK,CAAC,iBAAiB,KAAK,WAAW,EAAE,CAAC;YACpD,qEAAqE;YACrE,yEAAyE;YACzE,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;QACrD,CAAC;IACF,CAAC;CACD"}

package/lib/errors/InvalidOperationError.d.ts

@@ -0,0 +1,13 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * Used when an operation was attempted that can not be completed in the current
+ * context.
+ */
+export declare class InvalidOperationError extends AbstractError {
+    /**
+     * Constructs a new {@linkcode InvalidOperationError}.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(message: string, status?: number);
+}

package/lib/errors/InvalidOperationError.js

@@ -0,0 +1,22 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * Used when an operation was attempted that can not be completed in the current
+ * context.
+ */
+export class InvalidOperationError extends AbstractError {
+    /**
+     * Constructs a new {@linkcode InvalidOperationError}.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(message, status = 400) {
+        super("ERR_OS_INVALID_OPERATION", message, status);
+        this.name = "InvalidOperationError";
+        if (typeof Error.captureStackTrace !== "undefined") {
+            // Capture a new stacktrace, otherwise it will include our base-class
+            // constructor instead of the code location we're actually interested in.
+            Error.captureStackTrace(this, InvalidOperationError);
+        }
+    }
+}
+//# sourceMappingURL=InvalidOperationError.js.map