@aidc-toolkit/core 1.0.31-beta → 1.0.33-beta

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/cache.ts

@@ -0,0 +1,64 @@
+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 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>;
+}

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/hyperlink.ts

@@ -0,0 +1,19 @@
+/**
+ * Hyperlink.
+ */
+export interface Hyperlink {
+    /**
+     * Reference, relative or absolute depending on the application.
+     */
+    readonly reference: string;
+
+    /**
+     * Human-readable text.
+     */
+    readonly text?: string | undefined;
+
+    /**
+     * Additional details.
+     */
+    readonly details?: string | undefined;
+}

package/src/index.ts

@@ -16,5 +16,15 @@
  */
 export type * from "./type.js";
 export * from "./type-helper.js";
+
 export * from "./logger.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

@@ -0,0 +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

@@ -0,0 +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"
+    }
+};

package/src/locale/i18n.ts

@@ -1,6 +1,15 @@
-import type { i18n, LanguageDetectorModule, Resource } from "i18next";
+import i18next, {
+    type i18n,
+    type LanguageDetectorModule,
+    type Module,
+    type Newable,
+    type NewableModule,
+    type Resource
+} from "i18next";
 import I18nextBrowserLanguageDetector from "i18next-browser-languagedetector";
 import I18nextCLILanguageDetector from "i18next-cli-language-detector";
+import enLocaleResources from "./en/locale-resources.js";
+import frLocaleResources from "./fr/locale-resources.js";
 
 /**
  * Locale strings type for generic manipulation.
@@ -50,14 +59,36 @@ export type I18nEnvironment = typeof I18nEnvironments[I18nEnvironmentKey];
  */
 function toLowerCase(s: string): string {
     // Words with no lower case letters are preserved as they are likely mnemonics.
-    return s.split(" ").map(word => /[a-z]/.test(word) ? word.toLowerCase() : word).join(" ");
+    return s.split(" ").map(word => /[a-z]/u.test(word) ? word.toLowerCase() : word).join(" ");
 }
 
+export const coreNS = "aidct_core";
+
+/**
+ * Locale resources type is extracted from the English locale resources object.
+ */
+export type CoreLocaleResources = typeof enLocaleResources;
+
+/**
+ * Core resource bundle.
+ */
+export const coreResourceBundle: Resource = {
+    en: {
+        aidct_core: enLocaleResources
+    },
+    fr: {
+        aidct_core: frLocaleResources
+    }
+};
+
+// Explicit type is necessary because type can't be inferred without additional references.
+export const i18nextCore: i18n = i18next.createInstance();
+
 /**
  * Initialize internationalization.
  *
  * @param i18next
- * Internationalization object. As multiple objects exists, this parameter represents the one for the module for which
+ * Internationalization object. As multiple objects exist, this parameter represents the one for the module for which
  * internationalization is being initialized.
  *
  * @param environment
@@ -69,59 +100,94 @@ function toLowerCase(s: string): string {
  * @param defaultNS
  * Default namespace.
  *
- * @param resources
- * Resources.
+ * @param defaultResourceBundle
+ * Default resource bundle.
+ *
+ * @param i18nDependencyInits
+ * Dependency internationalization initialization functions.
  *
  * @returns
- * Void promise.
+ * Default resource bundle.
  */
-export async function i18nCoreInit(i18next: i18n, environment: I18nEnvironment, debug: boolean, defaultNS: string, ...resources: Resource[]): Promise<void> {
+export async function i18nInit(i18next: i18n, environment: I18nEnvironment, debug: boolean, defaultNS: string, defaultResourceBundle: Resource, ...i18nDependencyInits: Array<(environment: I18nEnvironment, debug: boolean) => Promise<Resource>>): Promise<Resource> {
     // Initialization may be called more than once.
     if (!i18next.isInitialized) {
-        const mergedResource: Resource = {};
-
-        // Merge resources.
-        for (const resource of resources) {
+        const mergedResourceBundle: Resource = {};
+
+        /**
+         * Merge a package resource bundle into the merged resource bundle.
+         *
+         * @param resourceBundle
+         * Package resource bundle.
+         */
+        function mergeResourceBundle(resourceBundle: Resource): void {
             // Merge languages.
-            for (const [language, resourceLanguage] of Object.entries(resource)) {
-                if (!(language in mergedResource)) {
-                    mergedResource[language] = {};
+            for (const [language, languageResourceBundle] of Object.entries(resourceBundle)) {
+                if (!(language in mergedResourceBundle)) {
+                    mergedResourceBundle[language] = {};
                 }
 
-                const mergedResourceLanguage = mergedResource[language];
+                const mergedLanguageResourceBundle = mergedResourceBundle[language];
 
                 // Merge namespaces.
-                for (const [namespace, resourceKey] of Object.entries(resourceLanguage)) {
-                    mergedResourceLanguage[namespace] = resourceKey;
+                for (const [namespace, resourceKey] of Object.entries(languageResourceBundle)) {
+                    mergedLanguageResourceBundle[namespace] = resourceKey;
                 }
             }
         }
 
-        let module: Parameters<typeof i18next.use>[0];
+        mergeResourceBundle(defaultResourceBundle);
 
-        switch (environment) {
-            case I18nEnvironments.CLI:
-                // TODO Refactor when https://github.com/neet/i18next-cli-language-detector/issues/281 resolved.
-                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Per above.
-                module = I18nextCLILanguageDetector as unknown as LanguageDetectorModule;
-                break;
+        // Initialize dependencies and merge their resource bundles.
+        await Promise.all(i18nDependencyInits.map(async i18nDependencyInit =>
+            i18nDependencyInit(environment, debug).then(mergeResourceBundle))
+        ).then(() => {
+            let module: Module | Newable<Module> | NewableModule<Module>;
 
-            case I18nEnvironments.Browser:
-                module = I18nextBrowserLanguageDetector;
-                break;
+            switch (environment) {
+                case I18nEnvironments.CLI:
+                    // TODO Refactor when https://github.com/neet/i18next-cli-language-detector/issues/281 resolved.
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Per above.
+                    module = I18nextCLILanguageDetector as unknown as LanguageDetectorModule;
+                    break;
 
-            default:
-                throw new Error("Not supported");
-        }
+                case I18nEnvironments.Browser:
+                    module = I18nextBrowserLanguageDetector;
+                    break;
+
+                default:
+                    throw new Error("Not supported");
+            }
 
-        await i18next.use(module).init({
-            debug,
-            resources: mergedResource,
-            fallbackLng: "en",
-            defaultNS
-        }).then(() => {
+            return module;
+        }).then(async module =>
+            i18next.use(module).init({
+                debug,
+                resources: mergedResourceBundle,
+                fallbackLng: "en",
+                defaultNS
+            })
+        ).then(() => {
             // Add toLowerCase function.
             i18next.services.formatter?.add("toLowerCase", value => typeof value === "string" ? toLowerCase(value) : String(value));
         });
     }
+
+    return defaultResourceBundle;
+}
+
+/**
+ * Initialize internationalization.
+ *
+ * @param environment
+ * Environment in which the application is running.
+ *
+ * @param debug
+ * Debug setting.
+ *
+ * @returns
+ * Core resource bundle.
+ */
+export async function i18nCoreInit(environment: I18nEnvironment, debug = false): Promise<Resource> {
+    return i18nInit(i18nextCore, environment, debug, coreNS, coreResourceBundle);
 }

package/src/locale/i18next.d.ts

@@ -0,0 +1,16 @@
+import type { CoreLocaleResources } from "./i18n.js";
+
+/**
+ * Internationalization module.
+ */
+declare module "i18next" {
+    /**
+     * Custom type options for this package.
+     */
+    interface CustomTypeOptions {
+        defaultNS: "aidct_core";
+        resources: {
+            aidct_core: CoreLocaleResources;
+        };
+    }
+}