@aidc-toolkit/core 1.0.32-beta → 1.0.34-beta

package/dist/parse-version.js

@@ -0,0 +1,23 @@
+/**
+ * Parse version.
+ *
+ * @param version
+ * Version, typically from package.json.
+ *
+ * @returns
+ * Parsed version.
+ */
+export function parseVersion(version) {
+    const parsedVersionGroups = /^(?<majorVersion>\d+)\.(?<minorVersion>\d+)\.(?<patchVersion>\d+)(?:-(?<preReleaseIdentifier>alpha|beta)(?:\.(?<dateTime>\d{12}))?)?$/u.exec(version)?.groups;
+    if (parsedVersionGroups === undefined) {
+        throw new Error(`Invalid package version ${version}`);
+    }
+    return {
+        majorVersion: Number(parsedVersionGroups["majorVersion"]),
+        minorVersion: Number(parsedVersionGroups["minorVersion"]),
+        patchVersion: Number(parsedVersionGroups["patchVersion"]),
+        preReleaseIdentifier: parsedVersionGroups["preReleaseIdentifier"],
+        dateTime: parsedVersionGroups["dateTime"]
+    };
+}
+//# sourceMappingURL=parse-version.js.map

package/dist/parse-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-version.js","sourceRoot":"","sources":["../src/parse-version.ts"],"names":[],"mappings":"AA8BA;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IACxC,MAAM,mBAAmB,GAAG,wIAAwI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE3L,IAAI,mBAAmB,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,2BAA2B,OAAO,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,OAAO;QACH,YAAY,EAAE,MAAM,CAAC,mBAAmB,CAAC,cAAc,CAAC,CAAC;QACzD,YAAY,EAAE,MAAM,CAAC,mBAAmB,CAAC,cAAc,CAAC,CAAC;QACzD,YAAY,EAAE,MAAM,CAAC,mBAAmB,CAAC,cAAc,CAAC,CAAC;QACzD,oBAAoB,EAAE,mBAAmB,CAAC,sBAAsB,CAAC;QACjE,QAAQ,EAAE,mBAAmB,CAAC,UAAU,CAAC;KAC5C,CAAC;AACN,CAAC"}

package/dist/phase-url.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Get the URL for the phase as determined by the package version.
+ *
+ * @param version
+ * Package version.
+ *
+ * @param alphaURL
+ * Alpha URL.
+ *
+ * @param nonAlphaRelativeURL
+ * Non-alpha URL, relative to non-alpha base URL plus optionally the pre-release identifier and version.
+ *
+ * @returns
+ * Fully-formed URL for the phase.
+ */
+export declare function phaseURL(version: string, alphaURL: string, nonAlphaRelativeURL?: string): string;
+//# sourceMappingURL=phase-url.d.ts.map

package/dist/phase-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-url.d.ts","sourceRoot":"","sources":["../src/phase-url.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,mBAAmB,CAAC,EAAE,MAAM,GAAG,MAAM,CAsBhG"}

package/dist/phase-url.js

@@ -0,0 +1,39 @@
+import { parseVersion } from "./parse-version.js";
+const NON_ALPHA_BASE_URL = "https://aidc-toolkit.com";
+/**
+ * Get the URL for the phase as determined by the package version.
+ *
+ * @param version
+ * Package version.
+ *
+ * @param alphaURL
+ * Alpha URL.
+ *
+ * @param nonAlphaRelativeURL
+ * Non-alpha URL, relative to non-alpha base URL plus optionally the pre-release identifier and version.
+ *
+ * @returns
+ * Fully-formed URL for the phase.
+ */
+export function phaseURL(version, alphaURL, nonAlphaRelativeURL) {
+    const parsedVersion = parseVersion(version);
+    const preReleaseIdentifier = parsedVersion.preReleaseIdentifier;
+    let url;
+    if (preReleaseIdentifier === "alpha") {
+        // Alpha URL is absolute.
+        url = alphaURL;
+    }
+    else {
+        const relativeURL = nonAlphaRelativeURL !== undefined && nonAlphaRelativeURL !== "" ? `/${nonAlphaRelativeURL}` : "";
+        if (preReleaseIdentifier !== undefined) {
+            // Non-alpha URL is relative to non-alpha base URL plus pre-release identifier and version.
+            url = `${NON_ALPHA_BASE_URL}/${preReleaseIdentifier}/v${parsedVersion.majorVersion}.${parsedVersion.minorVersion}${relativeURL}`;
+        }
+        else {
+            // Production URL is relative to non-alpha base URL.
+            url = `${NON_ALPHA_BASE_URL}${relativeURL}`;
+        }
+    }
+    return url;
+}
+//# sourceMappingURL=phase-url.js.map

package/dist/phase-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-url.js","sourceRoot":"","sources":["../src/phase-url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,kBAAkB,GAAG,0BAA0B,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,QAAgB,EAAE,mBAA4B;IACpF,MAAM,aAAa,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,oBAAoB,GAAG,aAAa,CAAC,oBAAoB,CAAC;IAEhE,IAAI,GAAW,CAAC;IAEhB,IAAI,oBAAoB,KAAK,OAAO,EAAE,CAAC;QACnC,yBAAyB;QACzB,GAAG,GAAG,QAAQ,CAAC;IACnB,CAAC;SAAM,CAAC;QACJ,MAAM,WAAW,GAAG,mBAAmB,KAAK,SAAS,IAAI,mBAAmB,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,mBAAmB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAErH,IAAI,oBAAoB,KAAK,SAAS,EAAE,CAAC;YACrC,2FAA2F;YAC3F,GAAG,GAAG,GAAG,kBAAkB,IAAI,oBAAoB,KAAK,aAAa,CAAC,YAAY,IAAI,aAAa,CAAC,YAAY,GAAG,WAAW,EAAE,CAAC;QACrI,CAAC;aAAM,CAAC;YACJ,oDAAoD;YACpD,GAAG,GAAG,GAAG,kBAAkB,GAAG,WAAW,EAAE,CAAC;QAChD,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAC;AACf,CAAC"}

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

@@ -0,0 +1,18 @@
+import { ReadOnlyAppDataStorage } from "./app-data-storage.js";
+/**
+ * Remote application data storage using HTTP. The `store()` and `delete()` methods are not supported.
+ */
+export declare class RemoteAppDataStorage extends ReadOnlyAppDataStorage<true> {
+    /**
+     * Constructor.
+     *
+     * @param baseURL
+     * Base URL. The URL must not end with a slash.
+     */
+    constructor(baseURL: string);
+    /**
+     * @inheritDoc
+     */
+    protected doRead(key: string, asBinary: boolean | undefined): Promise<string | Uint8Array | undefined>;
+}
+//# sourceMappingURL=remote-app-data-storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remote-app-data-storage.d.ts","sourceRoot":"","sources":["../src/remote-app-data-storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAG/D;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,sBAAsB,CAAC,IAAI,CAAC;IAClE;;;;;OAKG;gBACS,OAAO,EAAE,MAAM;IAI3B;;OAEG;cACsB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;CAiBxH"}

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

@@ -0,0 +1,37 @@
+import { ReadOnlyAppDataStorage } from "./app-data-storage.js";
+import { i18nextCore } from "./locale/i18n.js";
+/**
+ * Remote application data storage using HTTP. The `store()` and `delete()` methods are not supported.
+ */
+export class RemoteAppDataStorage extends ReadOnlyAppDataStorage {
+    /**
+     * Constructor.
+     *
+     * @param baseURL
+     * Base URL. The URL must not end with a slash.
+     */
+    constructor(baseURL) {
+        super(true, baseURL);
+    }
+    /**
+     * @inheritDoc
+     */
+    async doRead(key, asBinary) {
+        return fetch(key).then(async (response) => {
+            let result;
+            if (response.ok) {
+                result = asBinary === true ? new Uint8Array(await response.arrayBuffer()) : await response.text();
+            }
+            else if (response.status === 404) {
+                result = undefined;
+            }
+            else {
+                throw new RangeError(i18nextCore.t("RemoteAppDataStorage.httpError", {
+                    status: response.status
+                }));
+            }
+            return result;
+        });
+    }
+}
+//# sourceMappingURL=remote-app-data-storage.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remote-app-data-storage.js","sourceRoot":"","sources":["../src/remote-app-data-storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,sBAA4B;IAClE;;;;;OAKG;IACH,YAAY,OAAe;QACvB,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;IAED;;OAEG;IACgB,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,QAA6B;QACtE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;YACtC,IAAI,MAAuC,CAAC;YAE5C,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACd,MAAM,GAAG,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACtG,CAAC;iBAAM,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBACjC,MAAM,GAAG,SAAS,CAAC;YACvB,CAAC;iBAAM,CAAC;gBACJ,MAAM,IAAI,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,gCAAgC,EAAE;oBACjE,MAAM,EAAE,QAAQ,CAAC,MAAM;iBAC1B,CAAC,CAAC,CAAC;YACR,CAAC;YAED,OAAO,MAAM,CAAC;QAClB,CAAC,CAAC,CAAC;IACP,CAAC;CACJ"}

package/dist/type-helper.js.map

@@ -1 +1 @@
-{"version":3,"file":"type-helper.js","sourceRoot":"","sources":["../src/type-helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAS,UAAU,CAAgE,QAAkB,EAAE,CAAI,EAAE,GAAG,IAAS;IACrH,yGAAyG;IACzG,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAQ,CAAC,KAAK,QAAQ,CAAC,CAAkD,CAAC;AAC1J,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,IAAI,CAAsC,CAAI,EAAE,GAAG,IAAS;IACxE,OAAO,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,IAAI,CAAsC,CAAI,EAAE,GAAG,IAAS;IACxE,OAAO,UAAU,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,OAAO,CAAyE,IAAW,EAAE,MAAe;IACxH,0FAA0F;IAC1F,OAAO,IAAI,CAAC,IAAI,EAAE,GAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAS,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,OAAO,CAAyE,IAAW,EAAE,MAAe;IACxH,0FAA0F;IAC1F,OAAO,IAAI,CAAC,IAAI,EAAE,GAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAS,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,UAAU,CAA4D,CAAI,EAAE,GAAM;IAC9F,2GAA2G;IAC3G,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QACd;YACI,sFAAsF;YACtF,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAY;SAC3B,CAAC,CAAC;QACH,EAAE,CAC2C,CAAC;AACtD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,QAAiB;IACvC,OAAO,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,SAAS,CAAC;AACvD,CAAC"}
+{"version":3,"file":"type-helper.js","sourceRoot":"","sources":["../src/type-helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAS,UAAU,CAAgE,QAAkB,EAAE,CAAI,EAAE,GAAG,IAAS;IACrH,yGAAyG;IACzG,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAQ,CAAC,KAAK,QAAQ,CAAC,CAAkD,CAAC;AAC1J,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,IAAI,CAAsC,CAAI,EAAE,GAAG,IAAS;IACxE,OAAO,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,IAAI,CAAsC,CAAI,EAAE,GAAG,IAAS;IACxE,OAAO,UAAU,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,OAAO,CAAyE,IAAW,EAAE,MAAe;IACxH,0FAA0F;IAC1F,OAAO,IAAI,CAAC,IAAI,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAQ,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,OAAO,CAAyE,IAAW,EAAE,MAAe;IACxH,0FAA0F;IAC1F,OAAO,IAAI,CAAC,IAAI,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAQ,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,UAAU,CAA4D,CAAI,EAAE,GAAM;IAC9F,2GAA2G;IAC3G,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QACd;YACI,sFAAsF;YACtF,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAY;SAC3B,CAAC,CAAC;QACH,EAAE,CAC2C,CAAC;AACtD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,QAAiB;IACvC,OAAO,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,SAAS,CAAC;AACvD,CAAC"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@aidc-toolkit/core",
-  "version": "1.0.32-beta",
+  "version": "1.0.34-beta",
   "description": "Core functionality for AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
-  "homepage": "https://aidc-toolkit.com/",
+  "homepage": "https://aidc-toolkit.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/aidc-toolkit/core.git"
@@ -20,16 +20,19 @@
   },
   "scripts": {
     "lint": "eslint",
-    "tsc:core": "tsc --project tsconfig-src.json",
-    "build:dev": "rimraf dist && npm run tsc:core -- --declarationMap --sourceMap",
-    "build:release": "npm run tsc:core -- --noEmit && tsup",
-    "build:doc": "npm run build:dev"
+    "tsc-src": "tsc --project tsconfig-src.json",
+    "build:non-prod": "rimraf dist && npm run tsc-src -- --declarationMap --sourceMap",
+    "build:alpha": "npm run build:non-prod && tsc --project tsconfig-config.json --noEmit",
+    "build:beta": "npm run build:non-prod",
+    "build:prod": "npm run tsc-src -- --noEmit && tsup",
+    "build:doc": "npm run build:non-prod"
   },
   "devDependencies": {
-    "@aidc-toolkit/dev": "1.0.32-beta"
+    "@aidc-toolkit/dev": "1.0.34-beta"
   },
   "dependencies": {
-    "i18next": "^25.7.4",
+    "base64-js": "^1.5.1",
+    "i18next": "^25.8.0",
     "i18next-browser-languagedetector": "^8.2.0",
     "i18next-cli-language-detector": "^1.1.8",
     "tslog": "^4.10.2"

package/src/app-data-storage.ts

@@ -0,0 +1,166 @@
+import { type AppData, decodeAppData, encodeAppData } from "./app-data.js";
+import type { Promisable } from "./type.js";
+
+/**
+ * Generic read-only application data storage.
+ */
+export abstract class ReadOnlyAppDataStorage<SupportsBinary extends boolean> {
+    /**
+     * Extension to identify binary data.
+     */
+    protected static readonly BINARY_EXTENSION = ".bin";
+
+    /**
+     * Extension to identify JSON data.
+     */
+    protected static readonly JSON_EXTENSION = ".json";
+
+    /**
+     * True if binary data is supported natively.
+     */
+    readonly #supportsBinary: SupportsBinary;
+
+    /**
+     * Storage path prepended to each key.
+     */
+    readonly #path: string;
+
+    /**
+     * 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) {
+        this.#supportsBinary = supportsBinary;
+        this.#path = path !== undefined ? `${path}/` : "";
+    }
+
+    /**
+     * Determine if binary data is supported.
+     */
+    get supportsBinary(): SupportsBinary {
+        return this.#supportsBinary;
+    }
+
+    /**
+     * Get the storage path, prepended to each key.
+     */
+    get path(): string {
+        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.
+     */
+    protected fullKey(pathKey: string, isBinary: boolean): string {
+        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 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.
+     */
+    async read(pathKey: string, asBinary?: boolean): Promise<AppData | undefined> {
+        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 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.
+     */
+    async write(pathKey: string, appData: AppData): Promise<void> {
+        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)
+        ) as Parameters<typeof this.doWrite>[1]);
+    }
+
+    /**
+     * 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.
+     */
+    async delete(pathKey: string, asBinary?: boolean): Promise<void> {
+        await this.doDelete(this.fullKey(pathKey, asBinary === true));
+    }
+}

package/src/app-data.ts

@@ -0,0 +1,94 @@
+import { fromByteArray, toByteArray } from "base64-js";
+
+/**
+ * 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 function decodeAppData(stringData: string): AppData | undefined {
+    let decodedAppData: AppData | undefined;
+
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Mapping is expected to be correct.
+        decodedAppData = JSON.parse(stringData, (_key, value: unknown) => {
+            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;
+        }) as AppData;
+    } 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: object): object | string {
+    let mappedData: object | string;
+
+    // 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]: [string, unknown]) =>
+            [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: AppData): string {
+    return JSON.stringify(typeof appData !== "object" ? appData : encodeObject(appData));
+}

package/src/browser-app-data-storage.ts

@@ -0,0 +1,37 @@
+import { AppDataStorage } from "./app-data-storage.js";
+
+/**
+ * Application data storage using the browser local storage.
+ */
+export 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) {
+        super(false, path);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected override doRead(key: string): string | undefined {
+        return localStorage.getItem(key) ?? undefined;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected override doWrite(key: string, s: string): void {
+        localStorage.setItem(key, s);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected override doDelete(key: string): void {
+        localStorage.removeItem(key);
+    }
+}

package/src/file-app-data-storage.ts

@@ -0,0 +1,49 @@
+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<true> {
+    /**
+     * Constructor.
+     *
+     * @param path
+     * Storage path prepended to each key along with '/' if defined, empty string if not.
+     */
+    constructor(path?: string) {
+        super(true, path);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected override async doRead(key: string, asBinary: boolean | undefined): Promise<string | Uint8Array | undefined> {
+        return fs.promises.readFile(key).then(buffer =>
+            asBinary === true ? buffer : buffer.toString()
+        ).catch(() =>
+            undefined
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected override async doWrite(key: string, data: string | Uint8Array): Promise<void> {
+        return fs.promises.mkdir(path.dirname(key), {
+            recursive: true
+        }).then(async () =>
+            fs.promises.writeFile(key, data)
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected override async doDelete(key: string): Promise<void> {
+        return fs.promises.rm(key, {
+            force: true
+        });
+    }
+}

package/src/index.ts

@@ -1,5 +1,5 @@
 /*!
- * Copyright © 2024-2025 Dolphin Data Development Ltd. and AIDC Toolkit
+ * Copyright © 2024-2026 Dolphin Data Development Ltd. and AIDC Toolkit
  * contributors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,12 +14,21 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 export type * from "./type.js";
 export * from "./type-helper.js";
 
 export * from "./logger.js";
 
+export * from "./parse-version.js";
+export * from "./phase-url.js";
+
+export * from "./app-data.js";
+export * from "./app-data-storage.js";
+export * from "./local-app-data-storage.js";
+export * from "./remote-app-data-storage.js";
 export * from "./cache.js";
+
 export type * from "./hyperlink.js";
 
 export * from "./locale/i18n.js";

package/src/local-app-data-storage.ts

@@ -0,0 +1,12 @@
+import type { AppDataStorage } from "./app-data-storage.js";
+
+/**
+ * Local application data storage class for the current environment. This is a variable representing a `Promise` as the
+ * implementing class is loaded dynamically to prevent the inclusion of unnecessary node dependencies in a browser
+ * environment.
+ */
+export const LocalAppDataStorage: Promise<new (path?: string) => AppDataStorage<boolean>> =
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- localStorage is undefined when running under Node.js.
+    globalThis.localStorage === undefined ?
+        import("./file-app-data-storage.js").then(module => module.FileAppDataStorage) :
+        import("./browser-app-data-storage.js").then(module => module.BrowserAppDataStorage);

package/src/locale/en/locale-resources.ts

@@ -1,5 +1,8 @@
 export default {
     Logger: {
         unknownLogLevel: "Unknown log level \"{{logLevel}}\""
+    },
+    RemoteAppDataStorage: {
+        httpError: "HTTP error {{status, number}} retrieving file"
     }
 };

package/src/locale/fr/locale-resources.ts

@@ -1,5 +1,8 @@
 export default {
     Logger: {
         unknownLogLevel: "Niveau de journalisation inconnu «{{logLevel}}»"
+    },
+    RemoteAppDataStorage: {
+        httpError: "Erreur HTTP {{status, number}} lors de la récupération du fichier"
     }
 };