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

package/src/locale/i18n.ts

@@ -1,4 +1,11 @@
-import i18next, { type i18n, type LanguageDetectorModule, type 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";
@@ -63,9 +70,9 @@ export const coreNS = "aidct_core";
 export type CoreLocaleResources = typeof enLocaleResources;
 
 /**
- * Core resources.
+ * Core resource bundle.
  */
-export const coreResources: Resource = {
+export const coreResourceBundle: Resource = {
     en: {
         aidct_core: enLocaleResources
     },
@@ -77,24 +84,11 @@ export const coreResources: Resource = {
 // Explicit type is necessary because type can't be inferred without additional references.
 export const i18nextCore: i18n = i18next.createInstance();
 
-/**
- * Initialize internationalization.
- *
- * @param environment
- * Environment in which the application is running.
- *
- * @param debug
- * Debug setting.
- */
-export async function i18nCoreInit(environment: I18nEnvironment, debug = false): Promise<void> {
-    await i18nFinalizeInit(i18nextCore, environment, debug, coreNS, coreResources);
-}
-
 /**
  * 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
@@ -106,56 +100,94 @@ export async function i18nCoreInit(environment: I18nEnvironment, debug = false):
  * @param defaultNS
  * Default namespace.
  *
- * @param resources
- * Resources.
+ * @param defaultResourceBundle
+ * Default resource bundle.
+ *
+ * @param i18nDependencyInits
+ * Dependency internationalization initialization functions.
+ *
+ * @returns
+ * Default resource bundle.
  */
-export async function i18nFinalizeInit(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;
 
-        await i18next.use(module).init({
-            debug,
-            resources: mergedResource,
-            fallbackLng: "en",
-            defaultNS
-        }).then(() => {
+                default:
+                    throw new Error("Not supported");
+            }
+
+            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/logger.ts

@@ -67,10 +67,12 @@ export function logLevelOf(untypedLogLevel?: string | number): LogLevel {
  * [`tslog`](https://tslog.js.org/).
  *
  * @param logLevel
- * Log level as enumeration value or string. Mapped to `minLevel` in settings.
+ * Log level as enumeration value or string. Mapped to `minLevel` and sets `hideLogPositionForProduction` to true in
+ * settings if at {@linkcode LogLevels.Info} or higher. Default is {@linkcode LogLevels.Info}.
  *
  * @param settings
- * Detailed settings. See [`tslog`](https://tslog.js.org/#/?id=settings) documentation for details.
+ * Detailed settings. See [`tslog`](https://tslog.js.org/#/?id=settings) documentation for details. The `minLevel` is
+ * ignored in favour of `logLevel` but `hideLogPositionForProduction` will override the default logic.
  *
  * @param logObj
  * Default log object. See [`tslog`](https://tslog.js.org/#/?id=defining-and-accessing-logobj) documentation for
@@ -83,9 +85,14 @@ export function logLevelOf(untypedLogLevel?: string | number): LogLevel {
  * Log object type.
  */
 export function getLogger<T extends object = object>(logLevel?: string | number, settings?: ISettingsParam<T>, logObj?: T): Logger<T> {
+    const minLevel = logLevelOf(logLevel);
+
     return new Logger({
+        // Hiding log position for production can be overridden in settings parameter.
+        hideLogPositionForProduction: minLevel >= LogLevels.Info,
         ...settings ?? {},
-        minLevel: logLevelOf(logLevel)
+        // Minimum log level overrides settings parameter.
+        minLevel
     }, logObj);
 }
 

package/src/parse-version.ts

@@ -0,0 +1,54 @@
+/**
+ * Parsed version.
+ */
+export interface ParsedVersion {
+    /**
+     * Major version.
+     */
+    readonly majorVersion: number;
+
+    /**
+     * Minor version.
+     */
+    readonly minorVersion: number;
+
+    /**
+     * Patch version.
+     */
+    readonly patchVersion: number;
+
+    /**
+     * Pre-release identifier.
+     */
+    readonly preReleaseIdentifier: string | undefined;
+
+    /**
+     * Date/time included with pre-release identifier.
+     */
+    readonly dateTime: string | undefined;
+}
+
+/**
+ * Parse version.
+ *
+ * @param version
+ * Version, typically from package.json.
+ *
+ * @returns
+ * Parsed version.
+ */
+export function parseVersion(version: string): ParsedVersion {
+    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"]
+    };
+}

package/src/phase-url.ts

@@ -0,0 +1,42 @@
+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: string, alphaURL: string, nonAlphaRelativeURL?: string): string {
+    const parsedVersion = parseVersion(version);
+    const preReleaseIdentifier = parsedVersion.preReleaseIdentifier;
+
+    let url: string;
+
+    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;
+}

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

@@ -0,0 +1,38 @@
+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<true> {
+    /**
+     * Constructor.
+     *
+     * @param baseURL
+     * Base URL. The URL must not end with a slash.
+     */
+    constructor(baseURL: string) {
+        super(true, baseURL);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected override async doRead(key: string, asBinary: boolean | undefined): Promise<string | Uint8Array | undefined> {
+        return fetch(key).then(async (response) => {
+            let result: string | Uint8Array | undefined;
+
+            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;
+        });
+    }
+}

package/src/type-helper.ts

@@ -94,7 +94,7 @@ export function pick<T extends object, K extends keyof T>(o: T, ...keys: K[]): P
  */
 export function exclude<TWide extends TNarrow, TNarrow extends object, K extends keyof TNarrow>(wide: TWide, narrow: TNarrow): Omit<TWide, K> {
     // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Keys are valid.
-    return omit(wide, ...(Object.keys(narrow) as K[]));
+    return omit(wide, ...Object.keys(narrow) as K[]);
 }
 
 /**
@@ -120,7 +120,7 @@ export function exclude<TWide extends TNarrow, TNarrow extends object, K extends
  */
 export function include<TWide extends TNarrow, TNarrow extends object, K extends keyof TNarrow>(wide: TWide, narrow: TNarrow): Pick<TWide, K> {
     // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Keys are valid.
-    return pick(wide, ...(Object.keys(narrow) as K[]));
+    return pick(wide, ...Object.keys(narrow) as K[]);
 }
 
 /**