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

package/README.md

@@ -1,6 +1,6 @@
 # Core Package
 
-**Copyright © 2024-2025 Dolphin Data Development Ltd. and AIDC Toolkit contributors**
+**Copyright © 2024-2026 Dolphin Data Development Ltd. and AIDC Toolkit contributors**
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
 
@@ -10,15 +10,15 @@ Unless required by applicable law or agreed to in writing, software distributed
 
 ## Overview
 
-> [!WARNING]
-> 
-> **This software is in beta**, with production release is scheduled for 2025Q4. To follow the status of this and other projects, go to the AIDC Toolkit [projects](https://github.com/orgs/aidc-toolkit/projects) page.
-
 The AIDC Toolkit `core` package contains artefacts to support other AIDC Toolkit packages; it does not itself provide any of the functionality of the AIDC Toolkit. It is a required dependency for all AIDC Toolkit packages.
 
-## Types
+## Types and Type Helpers
+
+Generic types that go beyond TypeScript's utility types are defined here. The types are designed to provide even greater type safety. There are also helper functions for working with objects (e.g., by picking or omitting properties).
 
-Generic types that go beyond TypeScript's utility types are defined here. The types are designed to provide even greater type safety.
+## Hyperlink
+
+A simple interface defining a hyperlink is defined in this package to provide a consistent type across all AIDC Toolkit packages.
 
 ## Logger
 
@@ -30,38 +30,38 @@ All AIDC Toolkit packages require internationalization. The localization functio
 
 > [!TIP]
 > 
-> For a complete example, including how to use application-specific resource bundles, see the AIDC Toolkit [demo source](https://github.com/aidc-toolkit/demo).
+> For a complete example, including how to use application-specific resource bundles, see the AIDC Toolkit [demo source](https://github.com/aidc-toolkit/demo/tree/main/src/locale).
 
-Packages install their resources as follows in `i18n.ts` or similar:
+Packages install their resources as follows in `i18n.ts` or similar. Note that "dependency1" and "dependency2" are placeholders for the names of the packages on which the package depends, and "package" is the package itself.
 
 ```typescript
-import { type I18nEnvironment, i18nFinalizeInit } from "@aidc-toolkit/core";
-import { dependency1Resources, i18nDependency1Init } from "@aidc-toolkit/dependency1";
-import { dependency2Resources, i18nDependency2Init } from "@aidc-toolkit/dependency2";
+import { i18nCoreInit, type I18nEnvironment, i18nInit } from "@aidc-toolkit/core";
+import { i18nDependency1Init } from "@aidc-toolkit/dependency1";
+import { i18nDependency2Init } from "@aidc-toolkit/dependency2";
 import i18next, { type i18n, type Resource } from "i18next";
-import { localeStrings as enLocaleStrings } from "./en/locale-strings";
-import { localeStrings as frLocaleStrings } from "./fr/locale-strings";
+import enLocaleResources from "./en/locale-resources.js";
+import frLocaleResources from "./fr/locale-resources.js";
 
-export const packageNS = "aidct_package";
+const packageNS = "aidct_package";
 
 /**
  * Locale strings type is extracted from the English locale strings object.
  */
-export type PackageLocaleStrings = typeof enLocaleStrings;
+export type PackageLocaleResources = typeof enLocaleResources;
 
 /**
- * Package resources.
+ * Package resource bundle.
  */
-export const packageResources: Resource = {
-    en: {
-        aidct_package: enLocaleStrings
-    },
-    fr: {
-        aidct_package: frLocaleStrings
-    }
+const packageResourceBundle = {
+  en: {
+    aidct_package: enLocaleResources
+  },
+  fr: {
+    aidct_package: frLocaleResources
+  }
 };
 
-// Explicit type is necessary to work around bug in type discovery with linked packages.
+// Explicit type is necessary because type can't be inferred without additional references.
 export const i18nextPackage: i18n = i18next.createInstance();
 
 /**
@@ -74,18 +74,17 @@ export const i18nextPackage: i18n = i18next.createInstance();
  * Debug setting.
  *
  * @returns
- * Void promise.
+ * Package resource bundle.
  */
-export async function i18nPackageInit(environment: I18nEnvironment, debug = false): Promise<void> {
-    await i18nDependency1Init(environment, debug);
-    await i18nDependency2Init(environment, debug);
-    await i18nFinalizeInit(i18nextPackage, environment, debug, packageNS, dependency1Resources, dependency2Resources, packageResources);
+export async function i18nPackageInit(environment: I18nEnvironment, debug = false): Promise<Resource> {
+  return i18nInit(i18nextPackage, environment, debug, packageNS, packageResourceBundle, i18nCoreInit, i18nDependency2Init, i18nDependency1Init);
 }
 ```
 
 The resource types are declared in `i18next.d.ts` or similar:
 
 ```typescript
+import type { CoreLocaleResources } from "@aidc-toolkit/core";
 import type { Dependency1LocaleStrings } from "@aidc-toolkit/dependency1";
 import type { Dependency2LocaleStrings } from "@aidc-toolkit/dependency2";
 import type { PackageLocaleStrings } from "./i18n";
@@ -100,6 +99,7 @@ declare module "i18next" {
     interface CustomTypeOptions {
         defaultNS: "aidct_package";
         resources: {
+            aidct_core: CoreLocaleResources;
             aidct_dependency1: Dependency1LocaleStrings;
             aidct_dependency2: Dependency2LocaleStrings;
             aidct_package: PackageLocaleStrings;
@@ -108,11 +108,13 @@ declare module "i18next" {
 }
 ```
 
+The declaration in `i18next.d.ts` exposes the resources of the dependencies to the package. The initialization process merges all the resources into a single resource bundle matching the declaration.
+
 Support is available for the following environments:
 
 - [Command-line interface](#command-line-interface)
   - Unit tests
-  - Batch applications
+  - Command-line or helper applications
 - Web server - **NOT YET IMPLEMENTED**
 - [Web browser](#web-browser)
 
@@ -126,73 +128,78 @@ await i18nPackageInit(I18nEnvironment.CLI);
 
 ### Web Browser
 
-Initializing internationalization for a web browser requires awaiting the fulfillment of the `Promise` returned by the call to the initialization function before rendering any content. For example, in the React framework, this may be accomplished with a component like this:
+Initializing internationalization for a web browser requires awaiting the fulfillment of the `Promise` returned by the call to the initialization function before rendering any content. For example, in the React framework, this would be done before creating the root:
 
 ```typescript jsx
-import { I18nEnvironment } from "@aidc-toolkit/core";
-import { type ReactElement, type ReactNode, useEffect, useState } from "react";
-import { i18nPackageInit, i18nextPackage } from "./locale/i18n";
+import { I18nEnvironments } from "@aidc-toolkit/core";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App.jsx";
+import { i18nPackageInit, i18nextPackage } from "./locale/i18n.js";
+
+i18nPackageInit(I18nEnvironments.Browser).then(() => {
+    // Set the page title.
+    document.title = i18nextPackage.t("App.title");
+
+    createRoot(document.getElementById("root")!).render(
+        <StrictMode>
+            <App />
+        </StrictMode>
+    );
+}).catch((e: unknown) => {
+    console.error(e);
+    alert(e);
+});
+```
 
-/**
- * I18n wrapper properties.
- */
-export interface I18nProperties {
-    /**
-     * Children.
-     */
-    readonly children?: ReactNode | undefined;
-}
+## Resources
 
-/**
- * I18n wrapper. Ensures initialization of internationalization regardless of entry point.
- *
- * @param properties
- * Properties.
- *
- * @returns
- * React element.
- */
-export function I18n(properties: I18nProperties): ReactElement {
-    const [isI18nInitialized, setIsI18nInitialized] = useState<boolean>(i18nextPackage.isInitialized);
-
-    useEffect(() => {
-        if (!isI18nInitialized) {
-            i18nPackageInit(I18nEnvironment.Browser).then(() => {
-                // Force refresh.
-                setIsI18nInitialized(true);
-            }).catch((e: unknown) => {
-                console.error(e);
-                alert(e);
-            });
-        }
-    }, [isI18nInitialized]);
-
-    return <>{isI18nInitialized ? properties.children : undefined}</>;
-}
-```
+The `resource` folder contains common resources (e.g., AIDC Toolkit icon) usable by all AIDC Toolkit packages.
 
-The component would then wrap the application as follows:
+## Application Data Management
 
-```typescript jsx
-import { type ReactElement, StrictMode } from "react";
-import { App } from "./App";
-import { I18n } from "./I18n";
+Parts of the AIDC Toolkit require persistent application data management, but there is no universal way to manage a persistence store:
 
-/**
- * Index.
- *
- * @returns
- * React element.
- */
-export default function Index(): ReactElement {
-    return <StrictMode>
-        <I18n>
-            <App />
-        </I18n>
-    </StrictMode>;
-}
-```
+- Command-line applications use the local file system, which supports data in any format.
+- Browser-based applications use local storage, which supports string data only.
+- Server-based applications use a database, which may have a strict schema.
+- Other applications may use a different mechanism entirely, such as storing content in an XML node in a document.
 
-## Resources
+The application data management functionality in this package provides a simple and consistent mechanism for managing application data. While not suitable for high-volumne or transactional data, it's sufficient for most applications that require simple key-value storage.
 
-The `resource` folder contains common resources (e.g., AIDC Toolkit icon) usable by all AIDC Toolkit packages.
+The [`AppData`](https://aidc-toolkit.com/api/Core/type-aliases/AppData.html) type alias is a simple constrained type of `string`, `number`, `boolean`, or `object`. An object type must be one of:
+
+- `Date`;
+- `Uint8Array`;
+- array of `AppData` or `undefined`; or
+- object containing only `AppData` or `undefined`
+
+Limitations in TypeScript prevent the use of recursive types and string index signatures, so there is no type enforcement beyond the basic type checks.
+
+Two functions `encodeAppData()` and `decodeAppData()` are provided to convert between `AppData` and JSON. These enhance the normal JSON serialization/deserialization rules by:
+
+- encoding `Date` objects as ISO 8601 strings preceded by the string "dateTime:"; and
+- encoding `Uint8Array` objects as [Base64](https://developer.mozilla.org/en-US/docs/Glossary/Base64) strings preceded by the string "binary:".
+
+The functions are generally not called directly. Rather, they are called automatically by the [`ReadOnlyAppDataStorage`](https://aidc-toolkit.com/api/Core/classes/ReadOnlyAppDataStorage.html) and [`AppDataStorage`](https://aidc-toolkit.com/api/Core/classes/AppDataStorage.html) classes, which are used to manage application data in the AIDC Toolkit packages.
+
+Internally, each storage provider defines whether it supports binary data natively. If so, a request to read binary data will return raw content as `Uint8Array` from the underlying storage mechanism and a request to write binary data will write the `Uint8Array` as-is. This applies only to top-level read and write operations, not to `Uint8Array` values stored in nested objects.
+
+All storage providers take a path argument, which defines an implementation-specific location for the data. The following storage providers are provided by default:
+
+- [`LocalAppDataStorage`](https://aidc-toolkit.com/api/Core/variables/LocalAppDataStorage.html)
+  - Not a class, but rather a `Promise` of a constructor to one of the following implementations:
+    - File-based storage
+      - Supports binary data.
+      - Maps the path to an absolute or relative directory.
+    - Browser-based storage
+      - Does not support binary data.
+      - Maps the path by prepending it plus `/` to the key for use in [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).
+- [`RemoteAppDataStorage`](https://aidc-toolkit.com/api/Core/classes/RemoteAppDataStorage.html)
+  - Read-only.
+  - Supports binary data.
+  - Maps the path to a base URL.
+
+## Caching
+
+The [`Cache`](https://aidc-toolkit.com/api/Core/classes/Cache.html) class provides a simple cache that can be used to maintain synchronization with an external source.

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"}