@aidc-toolkit/core 1.0.38-beta → 1.0.39-beta

package/README.md

@@ -32,7 +32,9 @@ All AIDC Toolkit packages require internationalization. The localization functio
 > 
 > 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. Note that "dependency1" and "dependency2" are placeholders for the names of the packages on which the package depends, and "package" is the package itself.
+### Initialization
+
+Packages initialize 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 { i18nCoreInit, type I18nEnvironment, i18nInit } from "@aidc-toolkit/core";
@@ -110,7 +112,9 @@ 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:
+### Environment-Specific Language Detection
+
+Language detection is available for the following environments:
 
 - [Command-line interface](#command-line-interface)
   - Unit tests
@@ -118,7 +122,19 @@ Support is available for the following environments:
 - Web server - **NOT YET IMPLEMENTED**
 - [Web browser](#web-browser)
 
-### Command-Line Interface
+When a package's `i18next` object is initialized:
+
+Language detection starts with the full locale as provided by the environment then falls back as follows:
+
+- the full locale minus the regional variant if any;
+- the full locale minus the regional variant and the region if any; and
+- the first locale as defined in the default resource bundle.
+
+Caching (typically via the `i18nextLng` attribute in some form of storage) is disabled. Depending on the detector, this may still allow reading from a cache (e.g., the browser detector from local storage or session storage) but not writing. This leaves it to the application to decide how and when to persist the language setting.
+
+#### Command-Line Interface
+
+Language detection is implemented using [I18nextCLILanguageDetector](https://github.com/neet/i18next-cli-language-detector).
 
 Initializing internationalization for a command-line interface application is straightforward:
 
@@ -126,7 +142,9 @@ Initializing internationalization for a command-line interface application is st
 await i18nPackageInit(I18nEnvironment.CLI);
 ```
 
-### Web Browser
+#### Web Browser
+
+Language detection is implemented using [I18nextBrowserLanguageDetector](https://github.com/i18next/i18next-browser-languageDetector).
 
 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:
 
@@ -167,7 +185,7 @@ Parts of the AIDC Toolkit require persistent application data management, but th
 
 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 [`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:
+The [`AppData`](https://aidc-toolkit.com/v1.0/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`;
@@ -181,13 +199,13 @@ Two functions `encodeAppData()` and `decodeAppData()` are provided to convert be
 - 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.
+The functions are generally not called directly. Rather, they are called automatically by the [`ReadOnlyAppDataStorage`](https://aidc-toolkit.com/v1.0/api/Core/classes/ReadOnlyAppDataStorage.html) and [`AppDataStorage`](https://aidc-toolkit.com/v1.0/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)
+- [`LocalAppDataStorage`](https://aidc-toolkit.com/v1.0/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.
@@ -195,11 +213,11 @@ All storage providers take a path argument, which defines an implementation-spec
     - 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)
+- [`RemoteAppDataStorage`](https://aidc-toolkit.com/v1.0/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.
+The [`Cache`](https://aidc-toolkit.com/v1.0/api/Core/classes/Cache.html) class provides a simple cache that can be used to maintain synchronization with an external source.

package/dist/locale/i18n.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../../src/locale/i18n.ts"],"names":[],"mappings":"AAAA,OAAgB,EACZ,KAAK,IAAI,EAKT,KAAK,QAAQ,EAChB,MAAM,SAAS,CAAC;AAGjB,OAAO,iBAAiB,MAAM,0BAA0B,CAAC;AAGzD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,MAAM,CAAC;CAC3C;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB;IACzB;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;CAEG,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;AAgB1E,eAAO,MAAM,MAAM,eAAe,CAAC;AAEnC;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,iBAAiB,CAAC;AAE3D;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAOhC,CAAC;AAGF,eAAO,MAAM,WAAW,EAAE,IAA+B,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,GAAG,mBAAmB,EAAE,KAAK,CAAC,CAAC,WAAW,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiErQ;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,eAAe,EAAE,KAAK,UAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEjG"}
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../../src/locale/i18n.ts"],"names":[],"mappings":"AAAA,OAAgB,EACZ,KAAK,IAAI,EAKT,KAAK,QAAQ,EAChB,MAAM,SAAS,CAAC;AAGjB,OAAO,iBAAiB,MAAM,0BAA0B,CAAC;AAGzD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,MAAM,CAAC;CAC3C;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB;IACzB;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;CAEG,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;AAkB1E,eAAO,MAAM,MAAM,eAAe,CAAC;AAEnC;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,iBAAiB,CAAC;AAE3D;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAOhC,CAAC;AAGF,eAAO,MAAM,WAAW,EAAE,IAA+B,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,GAAG,mBAAmB,EAAE,KAAK,CAAC,CAAC,WAAW,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CA4ErQ;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,eAAe,EAAE,KAAK,UAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEjG"}

package/dist/locale/i18n.js

@@ -23,15 +23,17 @@ export const I18nEnvironments = {
 /**
  * Convert a string to lower case, skipping words that are all upper case.
  *
- * @param s
- * String.
+ * @param value
+ * Value.
  *
  * @returns
- * Lower case string.
+ * Lower case string if value is a string. If not, value is returned as a string but not converted to lower case.
  */
-function toLowerCase(s) {
-    // Words with no lower case letters are preserved as they are likely mnemonics.
-    return s.split(" ").map(word => /[a-z]/u.test(word) ? word.toLowerCase() : word).join(" ");
+function toLowerCase(value) {
+    return typeof value === "string" ?
+        // Words with no lower case letters are preserved as they are likely mnemonics.
+        value.split(" ").map(word => /[a-z]/u.test(word) ? word.toLowerCase() : word).join(" ") :
+        String(value);
 }
 export const coreNS = "aidct_core";
 /**
@@ -91,35 +93,48 @@ export async function i18nInit(i18next, environment, debug, defaultNS, defaultRe
                 const mergedLanguageResourceBundle = mergedResourceBundle[language];
                 // Merge namespaces.
                 for (const [namespace, resourceKey] of Object.entries(languageResourceBundle)) {
+                    if (namespace in mergedLanguageResourceBundle) {
+                        // Error prior to internationalization initialization; no localization possible.
+                        throw new Error(`Duplicate namespace ${namespace} in merged resource bundle for language ${language}`);
+                    }
                     mergedLanguageResourceBundle[namespace] = resourceKey;
                 }
             }
         }
         mergeResourceBundle(defaultResourceBundle);
         // Initialize dependencies and merge their resource bundles.
-        await Promise.all(i18nDependencyInits.map(async (i18nDependencyInit) => i18nDependencyInit(environment, debug).then(mergeResourceBundle))).then(() => {
-            let module;
-            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;
-                    break;
-                case I18nEnvironments.Browser:
-                    module = I18nextBrowserLanguageDetector;
-                    break;
-                default:
-                    throw new Error("Not supported");
-            }
-            return module;
-        }).then(async (module) => i18next.use(module).init({
+        for (const i18nDependencyInit of i18nDependencyInits) {
+            // eslint-disable-next-line no-await-in-loop -- Dependencies must initialized first.
+            await i18nDependencyInit(environment, debug).then(mergeResourceBundle);
+        }
+        let module;
+        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;
+                break;
+            case I18nEnvironments.Browser:
+                module = I18nextBrowserLanguageDetector;
+                break;
+            default:
+                throw new Error("Not supported");
+        }
+        await i18next.use(module).init({
             debug,
+            defaultNS,
             resources: mergedResourceBundle,
-            fallbackLng: "en",
-            defaultNS
-        })).then(() => {
-            // Add toLowerCase function.
-            i18next.services.formatter?.add("toLowerCase", value => typeof value === "string" ? toLowerCase(value) : String(value));
+            // Allow fallback by removing variant code then country code until match is found.
+            nonExplicitSupportedLngs: true,
+            // Fallback to first language defined.
+            fallbackLng: Object.keys(mergedResourceBundle)[0],
+            detection: {
+                // Disabling cache allows read but requires explicit saving of i18nextLng attribute (e.g., via UI).
+                caches: []
+            }
+        }).then(() => {
+            // Add toLowerCase formatter.
+            i18next.services.formatter?.add("toLowerCase", toLowerCase);
         });
     }
     return defaultResourceBundle;

package/dist/locale/i18n.js.map

@@ -1 +1 @@
-{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../../src/locale/i18n.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../../src/locale/i18n.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidc-toolkit/core",
-  "version": "1.0.38-beta",
+  "version": "1.0.39-beta",
   "description": "Core functionality for AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "build:doc": "npm run build:non-prod"
   },
   "devDependencies": {
-    "@aidc-toolkit/dev": "1.0.37-beta"
+    "@aidc-toolkit/dev": "1.0.38-beta"
   },
   "dependencies": {
     "base64-js": "^1.5.1",

package/src/locale/i18n.ts

@@ -51,15 +51,17 @@ export type I18nEnvironment = typeof I18nEnvironments[I18nEnvironmentKey];
 /**
  * Convert a string to lower case, skipping words that are all upper case.
  *
- * @param s
- * String.
+ * @param value
+ * Value.
  *
  * @returns
- * Lower case string.
+ * Lower case string if value is a string. If not, value is returned as a string but not converted to lower case.
  */
-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]/u.test(word) ? word.toLowerCase() : word).join(" ");
+function toLowerCase(value: unknown): string {
+    return typeof value === "string" ?
+        // Words with no lower case letters are preserved as they are likely mnemonics.
+        value.split(" ").map(word => /[a-z]/u.test(word) ? word.toLowerCase() : word).join(" ") :
+        String(value);
 }
 
 export const coreNS = "aidct_core";
@@ -131,6 +133,11 @@ export async function i18nInit(i18next: i18n, environment: I18nEnvironment, debu
 
                 // Merge namespaces.
                 for (const [namespace, resourceKey] of Object.entries(languageResourceBundle)) {
+                    if (namespace in mergedLanguageResourceBundle) {
+                        // Error prior to internationalization initialization; no localization possible.
+                        throw new Error(`Duplicate namespace ${namespace} in merged resource bundle for language ${language}`);
+                    }
+
                     mergedLanguageResourceBundle[namespace] = resourceKey;
                 }
             }
@@ -139,37 +146,43 @@ export async function i18nInit(i18next: i18n, environment: I18nEnvironment, debu
         mergeResourceBundle(defaultResourceBundle);
 
         // 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>;
-
-            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;
-
-                case I18nEnvironments.Browser:
-                    module = I18nextBrowserLanguageDetector;
-                    break;
-
-                default:
-                    throw new Error("Not supported");
-            }
+        for (const i18nDependencyInit of i18nDependencyInits) {
+            // eslint-disable-next-line no-await-in-loop -- Dependencies must initialized first.
+            await i18nDependencyInit(environment, debug).then(mergeResourceBundle);
+        }
+
+        let module: Module | Newable<Module> | NewableModule<Module>;
+
+        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;
 
-            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));
+            case I18nEnvironments.Browser:
+                module = I18nextBrowserLanguageDetector;
+                break;
+
+            default:
+                throw new Error("Not supported");
+        }
+
+        await i18next.use(module).init({
+            debug,
+            defaultNS,
+            resources: mergedResourceBundle,
+            // Allow fallback by removing variant code then country code until match is found.
+            nonExplicitSupportedLngs: true,
+            // Fallback to first language defined.
+            fallbackLng: Object.keys(mergedResourceBundle)[0],
+            detection: {
+                // Disabling cache allows read but requires explicit saving of i18nextLng attribute (e.g., via UI).
+                caches: []
+            }
+        }).then(() => {
+            // Add toLowerCase formatter.
+            i18next.services.formatter?.add("toLowerCase", toLowerCase);
         });
     }