@aidc-toolkit/core 1.0.44 → 1.0.45-beta

package/dist/app-data-storage.d.ts

@@ -0,0 +1,118 @@
+import { type AppData } from "./app-data.js";
+import type { Promisable } from "./type.js";
+/**
+ * Generic read-only application data storage.
+ */
+export declare abstract class ReadOnlyAppDataStorage<SupportsBinary extends boolean> {
+    #private;
+    /**
+     * Extension to identify binary data.
+     */
+    protected static readonly BINARY_EXTENSION = ".bin";
+    /**
+     * Extension to identify JSON data.
+     */
+    protected static readonly JSON_EXTENSION = ".json";
+    /**
+     * Constructor.
+     *
+     * @param supportsBinary
+     * True if binary data is supported.
+     *
+     * @param path
+     * Storage path prepended to each key along with '/' if defined, empty string if not.
+     */
+    protected constructor(supportsBinary: SupportsBinary, path?: string);
+    /**
+     * Determine if binary data is supported.
+     */
+    get supportsBinary(): SupportsBinary;
+    /**
+     * Get the storage path, prepended to each key.
+     */
+    get path(): string;
+    /**
+     * Build the full storage key.
+     *
+     * @param pathKey
+     * Key relative to path.
+     *
+     * @param isBinary
+     * True if key is to binary data, false or undefined if to string data. Ignored if binary data is not supported.
+     *
+     * @returns
+     * Full storage key.
+     */
+    protected fullKey(pathKey: string, isBinary: boolean): string;
+    /**
+     * Read a string or binary data from persistent storage.
+     *
+     * @param key
+     * Storage key (file path in Node.js, key in localStorage).
+     *
+     * @param asBinary
+     * True if binary data is requested, false or undefined if string data is requested. Ignored if binary data is not
+     * supported.
+     *
+     * @returns
+     * String or binary data or undefined if not found.
+     */
+    protected abstract doRead(key: string, asBinary: boolean | undefined): Promisable<(SupportsBinary extends true ? string | Uint8Array : string) | undefined>;
+    /**
+     * Read application data from storage.
+     *
+     * @param pathKey
+     * Key relative to path.
+     *
+     * @param asBinary
+     * True if binary data is requested, false or undefined if string data is requested. Ignored if binary data is not
+     * supported.
+     *
+     * @returns
+     * Application data or undefined if not found.
+     */
+    read(pathKey: string, asBinary?: boolean): Promise<AppData | undefined>;
+}
+/**
+ * Generic read/write application data storage.
+ */
+export declare abstract class AppDataStorage<SupportsBinary extends boolean> extends ReadOnlyAppDataStorage<SupportsBinary> {
+    /**
+     * Write a string or binary data in persistent storage.
+     *
+     * @param key
+     * Storage key (file path in Node.js, key in localStorage).
+     *
+     * @param data
+     * String or binary data.
+     */
+    protected abstract doWrite(key: string, data: SupportsBinary extends true ? string | Uint8Array : string): Promisable<void>;
+    /**
+     * Write application data to storage.
+     *
+     * @param pathKey
+     * Key relative to path.
+     *
+     * @param appData
+     * Application data to write.
+     */
+    write(pathKey: string, appData: AppData): Promise<void>;
+    /**
+     * Delete from persistent storage.
+     *
+     * @param key
+     * Storage key (file path in Node.js, key in localStorage).
+     */
+    protected abstract doDelete(key: string): Promisable<void>;
+    /**
+     * Delete application data from persistent storage.
+     *
+     * @param pathKey
+     * Key relative to path.
+     *
+     * @param asBinary
+     * True if key is to binary data, false or undefined if to string data. Ignored if binary data is not supported.
+     */
+    delete(pathKey: string, asBinary?: boolean): Promise<void>;
+}
+//# sourceMappingURL=app-data-storage.d.ts.map

package/dist/app-data-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-data-storage.d.ts","sourceRoot":"","sources":["../src/app-data-storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAgC,MAAM,eAAe,CAAC;AAC3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;GAEG;AACH,8BAAsB,sBAAsB,CAAC,cAAc,SAAS,OAAO;;IACvE;;OAEG;IACH,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,UAAU;IAEpD;;OAEG;IACH,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,WAAW;IAYnD;;;;;;;;OAQG;IACH,SAAS,aAAa,cAAc,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,MAAM;IAKnE;;OAEG;IACH,IAAI,cAAc,IAAI,cAAc,CAEnC;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM;IAS7D;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC,CAAC,cAAc,SAAS,IAAI,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;IAE3J;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;CAKhF;AAED;;GAEG;AACH,8BAAsB,cAAc,CAAC,cAAc,SAAS,OAAO,CAAE,SAAQ,sBAAsB,CAAC,cAAc,CAAC;IAC/G;;;;;;;;OAQG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,SAAS,IAAI,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC;IAE3H;;;;;;;;OAQG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7D;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC;IAE1D;;;;;;;;OAQG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAGnE"}

package/dist/app-data-storage.js

@@ -0,0 +1,117 @@
+import { decodeAppData, encodeAppData } from "./app-data.js";
+/**
+ * Generic read-only application data storage.
+ */
+export class ReadOnlyAppDataStorage {
+    /**
+     * Extension to identify binary data.
+     */
+    static BINARY_EXTENSION = ".bin";
+    /**
+     * Extension to identify JSON data.
+     */
+    static JSON_EXTENSION = ".json";
+    /**
+     * True if binary data is supported natively.
+     */
+    #supportsBinary;
+    /**
+     * Storage path prepended to each key.
+     */
+    #path;
+    /**
+     * Constructor.
+     *
+     * @param supportsBinary
+     * True if binary data is supported.
+     *
+     * @param path
+     * Storage path prepended to each key along with '/' if defined, empty string if not.
+     */
+    constructor(supportsBinary, path) {
+        this.#supportsBinary = supportsBinary;
+        this.#path = path !== undefined ? `${path}/` : "";
+    }
+    /**
+     * Determine if binary data is supported.
+     */
+    get supportsBinary() {
+        return this.#supportsBinary;
+    }
+    /**
+     * Get the storage path, prepended to each key.
+     */
+    get path() {
+        return this.#path;
+    }
+    /**
+     * Build the full storage key.
+     *
+     * @param pathKey
+     * Key relative to path.
+     *
+     * @param isBinary
+     * True if key is to binary data, false or undefined if to string data. Ignored if binary data is not supported.
+     *
+     * @returns
+     * Full storage key.
+     */
+    fullKey(pathKey, isBinary) {
+        const keyNoExtension = `${this.path}${pathKey}`;
+        // Add extension to key if binary data is supported.
+        return this.supportsBinary ?
+            `${keyNoExtension}${isBinary ? ReadOnlyAppDataStorage.BINARY_EXTENSION : ReadOnlyAppDataStorage.JSON_EXTENSION}` :
+            keyNoExtension;
+    }
+    /**
+     * Read application data from storage.
+     *
+     * @param pathKey
+     * Key relative to path.
+     *
+     * @param asBinary
+     * True if binary data is requested, false or undefined if string data is requested. Ignored if binary data is not
+     * supported.
+     *
+     * @returns
+     * Application data or undefined if not found.
+     */
+    async read(pathKey, asBinary) {
+        const data = await this.doRead(this.fullKey(pathKey, asBinary === true), asBinary);
+        return typeof data === "string" ? decodeAppData(data) : data;
+    }
+}
+/**
+ * Generic read/write application data storage.
+ */
+export class AppDataStorage extends ReadOnlyAppDataStorage {
+    /**
+     * Write application data to storage.
+     *
+     * @param pathKey
+     * Key relative to path.
+     *
+     * @param appData
+     * Application data to write.
+     */
+    async write(pathKey, appData) {
+        const isBinary = appData instanceof Uint8Array;
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Type is determined by supports binary flag.
+        await this.doWrite(this.fullKey(pathKey, isBinary), (this.supportsBinary && isBinary ?
+            appData :
+            encodeAppData(appData)));
+    }
+    /**
+     * Delete application data from persistent storage.
+     *
+     * @param pathKey
+     * Key relative to path.
+     *
+     * @param asBinary
+     * True if key is to binary data, false or undefined if to string data. Ignored if binary data is not supported.
+     */
+    async delete(pathKey, asBinary) {
+        await this.doDelete(this.fullKey(pathKey, asBinary === true));
+    }
+}
+//# sourceMappingURL=app-data-storage.js.map

package/dist/app-data-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-data-storage.js","sourceRoot":"","sources":["../src/app-data-storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG3E;;GAEG;AACH,MAAM,OAAgB,sBAAsB;IACxC;;OAEG;IACO,MAAM,CAAU,gBAAgB,GAAG,MAAM,CAAC;IAEpD;;OAEG;IACO,MAAM,CAAU,cAAc,GAAG,OAAO,CAAC;IAEnD;;OAEG;IACM,eAAe,CAAiB;IAEzC;;OAEG;IACM,KAAK,CAAS;IAEvB;;;;;;;;OAQG;IACH,YAAsB,cAA8B,EAAE,IAAa;QAC/D,IAAI,CAAC,eAAe,GAAG,cAAc,CAAC;QACtC,IAAI,CAAC,KAAK,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACtD,CAAC;IAED;;OAEG;IACH,IAAI,cAAc;QACd,OAAO,IAAI,CAAC,eAAe,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC;IACtB,CAAC;IAED;;;;;;;;;;;OAWG;IACO,OAAO,CAAC,OAAe,EAAE,QAAiB;QAChD,MAAM,cAAc,GAAG,GAAG,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,CAAC;QAEhD,oDAAoD;QACpD,OAAO,IAAI,CAAC,cAAc,CAAC,CAAC;YACxB,GAAG,cAAc,GAAG,QAAQ,CAAC,CAAC,CAAC,sBAAsB,CAAC,gBAAgB,CAAC,CAAC,CAAC,sBAAsB,CAAC,cAAc,EAAE,CAAC,CAAC;YAClH,cAAc,CAAC;IACvB,CAAC;IAiBD;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,IAAI,CAAC,OAAe,EAAE,QAAkB;QAC1C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,KAAK,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;QAEnF,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACjE,CAAC;;AAGL;;GAEG;AACH,MAAM,OAAgB,cAA+C,SAAQ,sBAAsC;IAY/G;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,CAAC,OAAe,EAAE,OAAgB;QACzC,MAAM,QAAQ,GAAG,OAAO,YAAY,UAAU,CAAC;QAE/C,sHAAsH;QACtH,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,cAAc,IAAI,QAAQ,CAAC,CAAC;YAClF,OAAO,CAAC,CAAC;YACT,aAAa,CAAC,OAAO,CAAC,CACa,CAAC,CAAC;IAC7C,CAAC;IAUD;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,CAAC,OAAe,EAAE,QAAkB;QAC5C,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC;IAClE,CAAC;CACJ"}

package/dist/app-data.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Application data.
+ */
+export type AppData = string | number | boolean | object;
+/**
+ * Decode application data from an encoded string.
+ *
+ * @param stringData
+ * String data.
+ *
+ * @returns
+ * Decoded application data.
+ */
+export declare function decodeAppData(stringData: string): AppData | undefined;
+/**
+ * Encode application data as a string for storage. Encoded string is in JSON format with date/time and binary data
+ * converted to identifiable strings for decoding.
+ *
+ * @param appData
+ * Application data.
+ *
+ * @returns
+ * Encoded application data.
+ */
+export declare function encodeAppData(appData: AppData): string;
+//# sourceMappingURL=app-data.d.ts.map

package/dist/app-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-data.d.ts","sourceRoot":"","sources":["../src/app-data.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAEzD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAqCrE;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAEtD"}

package/dist/app-data.js

@@ -0,0 +1,79 @@
+import { fromByteArray, toByteArray } from "base64-js";
+/**
+ * Decode application data from an encoded string.
+ *
+ * @param stringData
+ * String data.
+ *
+ * @returns
+ * Decoded application data.
+ */
+export function decodeAppData(stringData) {
+    let decodedAppData;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Mapping is expected to be correct.
+        decodedAppData = JSON.parse(stringData, (_key, value) => {
+            let replacementValue = value;
+            // Decode string representing date/time and binary array and pass through other values unmodified.
+            if (typeof value === "string") {
+                // First capture group is type, second is data; simple split at ':' character.
+                const stringDataGroups = /^(?<type>\w+):(?<data>.*)$/u.exec(value)?.groups;
+                if (stringDataGroups !== undefined) {
+                    const type = stringDataGroups["type"];
+                    const data = stringDataGroups["data"];
+                    switch (type) {
+                        case "dateTime":
+                            replacementValue = new Date(data);
+                            break;
+                        case "binary":
+                            replacementValue = toByteArray(data);
+                            break;
+                    }
+                }
+            }
+            return replacementValue;
+        });
+    }
+    catch {
+        // String data is not valid JSON; discard it.
+        decodedAppData = undefined;
+    }
+    return decodedAppData;
+}
+/**
+ * Encode an object to a format suitable for storage.
+ *
+ * @param o
+ * Object.
+ *
+ * @returns
+ * Object suitable for storage with date/time and binary types encoded as strings.
+ */
+function encodeObject(o) {
+    let mappedData;
+    // Encode date/time and binary array as string and pass through other values unmodified.
+    if (o instanceof Date) {
+        mappedData = `dateTime:${o.toISOString()}`;
+    }
+    else if (o instanceof Uint8Array) {
+        mappedData = `binary:${fromByteArray(o)}`;
+    }
+    else {
+        mappedData = Object.fromEntries(Object.entries(o).map(([key, value]) => [key, typeof value === "object" && value !== null ? encodeObject(value) : value]));
+    }
+    return mappedData;
+}
+/**
+ * Encode application data as a string for storage. Encoded string is in JSON format with date/time and binary data
+ * converted to identifiable strings for decoding.
+ *
+ * @param appData
+ * Application data.
+ *
+ * @returns
+ * Encoded application data.
+ */
+export function encodeAppData(appData) {
+    return JSON.stringify(typeof appData !== "object" ? appData : encodeObject(appData));
+}
+//# sourceMappingURL=app-data.js.map

package/dist/app-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-data.js","sourceRoot":"","sources":["../src/app-data.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAOvD;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,UAAkB;IAC5C,IAAI,cAAmC,CAAC;IAExC,IAAI,CAAC;QACD,6GAA6G;QAC7G,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,KAAc,EAAE,EAAE;YAC7D,IAAI,gBAAgB,GAAG,KAAK,CAAC;YAE7B,kGAAkG;YAClG,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC5B,8EAA8E;gBAC9E,MAAM,gBAAgB,GAAG,6BAA6B,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;gBAE3E,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;oBACjC,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;oBACtC,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;oBAEtC,QAAQ,IAAI,EAAE,CAAC;wBACX,KAAK,UAAU;4BACX,gBAAgB,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC;4BAClC,MAAM;wBAEV,KAAK,QAAQ;4BACT,gBAAgB,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;4BACrC,MAAM;oBACd,CAAC;gBACL,CAAC;YACL,CAAC;YAED,OAAO,gBAAgB,CAAC;QAC5B,CAAC,CAAY,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACL,6CAA6C;QAC7C,cAAc,GAAG,SAAS,CAAC;IAC/B,CAAC;IAED,OAAO,cAAc,CAAC;AAC1B,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,YAAY,CAAC,CAAS;IAC3B,IAAI,UAA2B,CAAC;IAEhC,wFAAwF;IACxF,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC;QACpB,UAAU,GAAG,YAAY,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;IAC/C,CAAC;SAAM,IAAI,CAAC,YAAY,UAAU,EAAE,CAAC;QACjC,UAAU,GAAG,UAAU,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9C,CAAC;SAAM,CAAC;QACJ,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAoB,EAAE,EAAE,CACtF,CAAC,GAAG,EAAE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CACnF,CAAC,CAAC;IACP,CAAC;IAED,OAAO,UAAU,CAAC;AACtB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC1C,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;AACzF,CAAC"}

package/dist/browser-app-data-storage.d.ts

@@ -0,0 +1,26 @@
+import { AppDataStorage } from "./app-data-storage.js";
+/**
+ * Application data storage using the browser local storage.
+ */
+export declare class BrowserAppDataStorage extends AppDataStorage<false> {
+    /**
+     * Constructor.
+     *
+     * @param path
+     * Storage path prepended to each key along with '/' if defined, empty string if not.
+     */
+    constructor(path?: string);
+    /**
+     * @inheritDoc
+     */
+    protected doRead(key: string): string | undefined;
+    /**
+     * @inheritDoc
+     */
+    protected doWrite(key: string, s: string): void;
+    /**
+     * @inheritDoc
+     */
+    protected doDelete(key: string): void;
+}
+//# sourceMappingURL=browser-app-data-storage.d.ts.map

package/dist/browser-app-data-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-app-data-storage.d.ts","sourceRoot":"","sources":["../src/browser-app-data-storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,cAAc,CAAC,KAAK,CAAC;IAC5D;;;;;OAKG;gBACS,IAAI,CAAC,EAAE,MAAM;IAIzB;;OAEG;cACgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI1D;;OAEG;cACgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAIxD;;OAEG;cACgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAGjD"}

package/dist/browser-app-data-storage.js

@@ -0,0 +1,34 @@
+import { AppDataStorage } from "./app-data-storage.js";
+/**
+ * Application data storage using the browser local storage.
+ */
+export class BrowserAppDataStorage extends AppDataStorage {
+    /**
+     * Constructor.
+     *
+     * @param path
+     * Storage path prepended to each key along with '/' if defined, empty string if not.
+     */
+    constructor(path) {
+        super(false, path);
+    }
+    /**
+     * @inheritDoc
+     */
+    doRead(key) {
+        return localStorage.getItem(key) ?? undefined;
+    }
+    /**
+     * @inheritDoc
+     */
+    doWrite(key, s) {
+        localStorage.setItem(key, s);
+    }
+    /**
+     * @inheritDoc
+     */
+    doDelete(key) {
+        localStorage.removeItem(key);
+    }
+}
+//# sourceMappingURL=browser-app-data-storage.js.map

package/dist/browser-app-data-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-app-data-storage.js","sourceRoot":"","sources":["../src/browser-app-data-storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,cAAqB;IAC5D;;;;;OAKG;IACH,YAAY,IAAa;QACrB,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACvB,CAAC;IAED;;OAEG;IACgB,MAAM,CAAC,GAAW;QACjC,OAAO,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC;IAClD,CAAC;IAED;;OAEG;IACgB,OAAO,CAAC,GAAW,EAAE,CAAS;QAC7C,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACgB,QAAQ,CAAC,GAAW;QACnC,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;CACJ"}

package/dist/cache.d.ts

@@ -0,0 +1,58 @@
+import type { Promisable } from "./type.js";
+/**
+ * Generic cache. Typically used to manage a local copy of remote data that is not refreshed regularly.
+ *
+ * @template TCache
+ * Type of cached data.
+ *
+ * @template TSource
+ * Type of source data. The type may be different from the cached data type if a transformation is required.
+ */
+export declare abstract class Cache<TCache, TSource = TCache> {
+    /**
+     * Get the date/time at or after which the source should be checked for updates. If the value is undefined, this is
+     * the first usage.
+     */
+    abstract get nextCheckDateTime(): Promisable<Date | undefined>;
+    /**
+     * Get the date/time at which the cache was last updated. This may more accurately reflect the date/time at which
+     * the last source retrieved was updated. If the value is undefined, there is no data in the cache.
+     */
+    abstract get cacheDateTime(): Promisable<Date | undefined>;
+    /**
+     * Get the cache data. This should only ever be called if the cache date/time is defined.
+     */
+    abstract get cacheData(): Promisable<TCache>;
+    /**
+     * Get the date/time at which the source was last updated. This should not be called unless the next check date/time
+     * has passed, as it may trigger an expensive remote retrieval.
+     */
+    abstract get sourceDateTime(): Promisable<Date>;
+    /**
+     * Get the source data. This should not be called unless the next check date/time has passed, as it may trigger an
+     * expensive remote retrieval.
+     */
+    abstract get sourceData(): Promisable<TSource>;
+    /**
+     * Update the cache with only the next check date/time. The cache date/time and cache data must not be modified.
+     * This is typically called when the cache is up to date with the source or source retrieval has failed.
+     *
+     * @param nextCheckDateTime
+     * Next check date/time.
+     */
+    abstract update(nextCheckDateTime: Date): Promisable<void>;
+    /**
+     * Update all cache parameters. This is typically called when the cache is updated from the source.
+     *
+     * @param nextCheckDateTime
+     * Next check date/time.
+     *
+     * @param cacheDateTime
+     * Cache date/time.
+     *
+     * @param cacheData
+     * Cache data.
+     */
+    abstract update(nextCheckDateTime: Date, cacheDateTime: Date, cacheData: TCache): Promisable<void>;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;;;;;;;GAQG;AACH,8BAAsB,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM;IAChD;;;OAGG;IACH,QAAQ,KAAK,iBAAiB,IAAI,UAAU,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC;IAE/D;;;OAGG;IACH,QAAQ,KAAK,aAAa,IAAI,UAAU,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC;IAE3D;;OAEG;IACH,QAAQ,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IAE7C;;;OAGG;IACH,QAAQ,KAAK,cAAc,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAEhD;;;OAGG;IACH,QAAQ,KAAK,UAAU,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;IAE/C;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,iBAAiB,EAAE,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;IAE1D;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,CAAC,iBAAiB,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC;CACrG"}

package/dist/cache.js

@@ -0,0 +1,12 @@
+/**
+ * Generic cache. Typically used to manage a local copy of remote data that is not refreshed regularly.
+ *
+ * @template TCache
+ * Type of cached data.
+ *
+ * @template TSource
+ * Type of source data. The type may be different from the cached data type if a transformation is required.
+ */
+export class Cache {
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,OAAgB,KAAK;CAoD1B"}

package/dist/file-app-data-storage.d.ts

@@ -0,0 +1,27 @@
+import { AppDataStorage } from "./app-data-storage.js";
+/**
+ * Application data storage using the file system.
+ */
+export declare class FileAppDataStorage extends AppDataStorage<true> {
+    #private;
+    /**
+     * Constructor.
+     *
+     * @param path
+     * Storage path prepended to each key along with '/' if defined, empty string if not.
+     */
+    constructor(path?: string);
+    /**
+     * @inheritDoc
+     */
+    protected doRead(key: string, asBinary: boolean | undefined): Promise<string | Uint8Array | undefined>;
+    /**
+     * @inheritDoc
+     */
+    protected doWrite(key: string, data: string | Uint8Array): Promise<void>;
+    /**
+     * @inheritDoc
+     */
+    protected doDelete(key: string): Promise<void>;
+}
+//# sourceMappingURL=file-app-data-storage.d.ts.map

package/dist/file-app-data-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-app-data-storage.d.ts","sourceRoot":"","sources":["../src/file-app-data-storage.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,cAAc,CAAC,IAAI,CAAC;;IAMxD;;;;;OAKG;gBACS,IAAI,CAAC,EAAE,MAAM;IAOzB;;OAEG;cACsB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAUrH;;OAEG;cACsB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAUvF;;OAEG;cACsB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOhE"}

package/dist/file-app-data-storage.js

@@ -0,0 +1,52 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { AppDataStorage } from "./app-data-storage.js";
+/**
+ * Application data storage using the file system.
+ */
+export class FileAppDataStorage extends AppDataStorage {
+    /**
+     * If true, node:fs has been polyfilled with empty object.
+     */
+    #isNoOp;
+    /**
+     * Constructor.
+     *
+     * @param path
+     * Storage path prepended to each key along with '/' if defined, empty string if not.
+     */
+    constructor(path) {
+        super(true, path);
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Condition is true in polyfilled environment.
+        this.#isNoOp = fs?.promises?.readFile === undefined;
+    }
+    /**
+     * @inheritDoc
+     */
+    async doRead(key, asBinary) {
+        return !this.#isNoOp ?
+            fs.promises.readFile(key).then(buffer => asBinary === true ? buffer : buffer.toString()).catch(() => undefined) :
+            undefined;
+    }
+    /**
+     * @inheritDoc
+     */
+    async doWrite(key, data) {
+        return !this.#isNoOp ?
+            fs.promises.mkdir(path.dirname(key), {
+                recursive: true
+            }).then(async () => fs.promises.writeFile(key, data)) :
+            undefined;
+    }
+    /**
+     * @inheritDoc
+     */
+    async doDelete(key) {
+        return !this.#isNoOp ?
+            fs.promises.rm(key, {
+                force: true
+            }) :
+            undefined;
+    }
+}
+//# sourceMappingURL=file-app-data-storage.js.map

package/dist/file-app-data-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-app-data-storage.js","sourceRoot":"","sources":["../src/file-app-data-storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,cAAoB;IACxD;;OAEG;IACM,OAAO,CAAU;IAE1B;;;;;OAKG;IACH,YAAY,IAAa;QACrB,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAElB,uHAAuH;QACvH,IAAI,CAAC,OAAO,GAAG,EAAE,EAAE,QAAQ,EAAE,QAAQ,KAAK,SAAS,CAAC;IACxD,CAAC;IAED;;OAEG;IACgB,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,QAA6B;QACtE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAClB,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CACpC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,CACjD,CAAC,KAAK,CAAC,GAAG,EAAE,CACT,SAAS,CACZ,CAAC,CAAC;YACH,SAAS,CAAC;IAClB,CAAC;IAED;;OAEG;IACgB,KAAK,CAAC,OAAO,CAAC,GAAW,EAAE,IAAyB;QACnE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAClB,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;gBACjC,SAAS,EAAE,IAAI;aAClB,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CACf,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CACnC,CAAC,CAAC;YACH,SAAS,CAAC;IAClB,CAAC;IAED;;OAEG;IACgB,KAAK,CAAC,QAAQ,CAAC,GAAW;QACzC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAClB,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE;gBAChB,KAAK,EAAE,IAAI;aACd,CAAC,CAAC,CAAC;YACJ,SAAS,CAAC;IAClB,CAAC;CACJ"}

package/dist/http-fetch.d.ts

@@ -0,0 +1,45 @@
+import type { Promisable } from "./type.js";
+/**
+ * HTTP status code for OK.
+ */
+export declare const HTTP_OK = 200;
+/**
+ * HTTP status code for not found.
+ */
+export declare const HTTP_NOT_FOUND = 404;
+/**
+ * Generic HTTP response.
+ */
+export interface HTTPResponse {
+    /**
+     * True if OK.
+     */
+    readonly ok: boolean;
+    /**
+     * HTTP status code.
+     */
+    readonly status: number;
+    /**
+     * Body as array buffer.
+     */
+    readonly arrayBuffer: () => Promisable<ArrayBuffer>;
+    /**
+     * Body as text.
+     */
+    readonly text: () => Promisable<string>;
+}
+/**
+ * HTTP fetch function.
+ */
+export type HTTPFetch = (url: string) => Promisable<HTTPResponse>;
+/**
+ * Default HTTP fetch function using global `fetch` function.
+ *
+ * @param url
+ * URL.
+ *
+ * @returns
+ * HTTP response.
+ */
+export declare function defaultHTTPFetch(url: string): Promise<HTTPResponse>;
+//# sourceMappingURL=http-fetch.d.ts.map

package/dist/http-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-fetch.d.ts","sourceRoot":"","sources":["../src/http-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,OAAO,MAAM,CAAC;AAE3B;;GAEG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,UAAU,CAAC,WAAW,CAAC,CAAC;IAEpD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,UAAU,CAAC,YAAY,CAAC,CAAC;AAElE;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAOzE"}