@digitaldefiance/i18n-lib 1.1.0 → 1.1.2

package/README.md

@@ -231,6 +231,37 @@ const userNotFound = getUserTranslation(
 
 ### Advanced Plugin Usage
 
+#### Compile-Time Completeness Enforcement (Strict Mode)
+
+By default the plugin engine performs runtime validation and provides fallbacks. If you want **compile-time** enforcement that every language mapping contains every string key, use the helper in `strict-types`:
+
+```typescript
+import { createCompleteComponentStrings } from '@digitaldefiance/i18n-lib';
+
+enum MyStrings {
+  Welcome = 'welcome',
+  Farewell = 'farewell'
+}
+
+type AppLang = 'en' | 'fr';
+
+// This will only compile if BOTH languages contain BOTH keys.
+const myStrictStrings = createCompleteComponentStrings<MyStrings, AppLang>({
+  en: {
+    [MyStrings.Welcome]: 'Welcome',
+    [MyStrings.Farewell]: 'Goodbye'
+  },
+  fr: {
+    [MyStrings.Welcome]: 'Bienvenue',
+    [MyStrings.Farewell]: 'Au revoir'
+  }
+});
+
+// If any key is missing, TypeScript reports an error before runtime.
+```
+
+The core library itself uses this helper for the core component (`createCoreComponentStrings`) to guarantee internal completeness. For partial / iterative authoring you can still start with normal objects and later switch to the strict helper when translations stabilize.
+
 #### Adding New Languages
 
 ```typescript
@@ -690,6 +721,52 @@ yarn test enum-registry.spec.ts
 yarn test i18n-engine.spec.ts
 ```
 
+### Test Cleanup and Instance Management
+
+For proper test isolation when using the plugin-based architecture, use the cleanup utilities:
+
+```typescript
+import { PluginI18nEngine, resetAllI18nEngines } from '@digitaldefiance/i18n-lib';
+
+describe('My tests', () => {
+  beforeEach(() => {
+    // Clean up any existing instances before each test
+    PluginI18nEngine.clearAllInstances();
+  });
+
+  afterEach(() => {
+    // Or use the convenience function
+    resetAllI18nEngines();
+  });
+
+  // Or use specific cleanup methods
+  it('should manage instances', () => {
+    const engine1 = PluginI18nEngine.createInstance('app1', [englishLang]);
+    const engine2 = PluginI18nEngine.createInstance('app2', [frenchLang]);
+
+    // Check if instances exist
+    expect(PluginI18nEngine.hasInstance('app1')).toBe(true);
+    expect(PluginI18nEngine.hasInstance('app2')).toBe(true);
+
+    // Remove specific instance
+    PluginI18nEngine.removeInstance('app1');
+    expect(PluginI18nEngine.hasInstance('app1')).toBe(false);
+
+    // Clear all instances and component registrations
+    PluginI18nEngine.resetAll();
+    expect(PluginI18nEngine.hasInstance('app2')).toBe(false);
+  });
+});
+```
+
+#### Available Cleanup Methods
+
+- `PluginI18nEngine.clearAllInstances()` - Remove all engine instances
+- `PluginI18nEngine.removeInstance(key?)` - Remove specific instance by key
+- `PluginI18nEngine.hasInstance(key?)` - Check if instance exists  
+- `PluginI18nEngine.resetAll()` - Clear instances and component registrations
+- `resetAllI18nEngines()` - Convenience function that calls `resetAll()`
+
 ## Extensible Configuration
 
 The library supports layered extension across multiple libraries using TypeScript module augmentation:
@@ -859,6 +936,17 @@ Part of the DigitalBurnbag project - a secure file sharing and automated protoco
 
 ## ChangeLog
 
+### Version 1.1.2
+
+- Sat Oct 11 2025 19:25:00 GMT-0700 (Pacific Daylight Time)
+  - Added cleanup mechanisms for other modules to deregister, etc.
+
+### Version 1.1.1
+
+- Sat Oct 11 2025 17:47:00 GMT-0700 (Pacific Daylight Time)
+  - Improved type checking for completeness of component translations during registration
+  - Updated README/Migration guide for clarity.
+
 ### Version 1.1.0
 
 - Sat Oct 11 2025 16:49:00 GMT-0700 (Pacific Daylight Time)

package/dist/component-registry.d.ts

@@ -61,4 +61,8 @@ export declare class ComponentRegistry<TLanguages extends string> {
      * Merge existing strings with new strings
      */
     private mergeStrings;
+    /**
+     * Clear all components and their strings (useful for testing)
+     */
+    clearAllComponents(): void;
 }

package/dist/component-registry.js

@@ -234,5 +234,12 @@ class ComponentRegistry {
         }
         return result;
     }
+    /**
+     * Clear all components and their strings (useful for testing)
+     */
+    clearAllComponents() {
+        this.components.clear();
+        this.componentStrings.clear();
+    }
 }
 exports.ComponentRegistry = ComponentRegistry;

package/dist/core-i18n.d.ts

@@ -18,296 +18,7 @@ export declare const CoreComponentDefinition: ComponentDefinition<CoreStringKey>
 /**
  * Core component strings for all default languages
  */
-export declare function createCoreComponentStrings(): {
-    "en-US": {
-        common_yes: string;
-        common_no: string;
-        common_cancel: string;
-        common_ok: string;
-        common_save: string;
-        common_delete: string;
-        common_edit: string;
-        common_create: string;
-        common_update: string;
-        common_loading: string;
-        common_error: string;
-        common_success: string;
-        common_warning: string;
-        common_info: string;
-        error_invalidInput: string;
-        error_networkError: string;
-        error_notFound: string;
-        error_accessDenied: string;
-        error_internalServer: string;
-        error_validationFailed: string;
-        error_requiredField: string;
-        error_componentNotFoundTemplate: string;
-        error_languageNotFoundTemplate: string;
-        error_stringKeyNotFoundTemplate: string;
-        error_incompleteRegistrationTemplate: string;
-        error_duplicateComponentTemplate: string;
-        error_duplicateLanguageTemplate: string;
-        error_validationFailedTemplate: string;
-        system_welcome: string;
-        system_goodbye: string;
-        system_pleaseWait: string;
-        system_processingRequest: string;
-        system_operationComplete: string;
-        system_noDataAvailable: string;
-    };
-    "en-UK": {
-        common_yes: string;
-        common_no: string;
-        common_cancel: string;
-        common_ok: string;
-        common_save: string;
-        common_delete: string;
-        common_edit: string;
-        common_create: string;
-        common_update: string;
-        common_loading: string;
-        common_error: string;
-        common_success: string;
-        common_warning: string;
-        common_info: string;
-        error_invalidInput: string;
-        error_networkError: string;
-        error_notFound: string;
-        error_accessDenied: string;
-        error_internalServer: string;
-        error_validationFailed: string;
-        error_requiredField: string;
-        error_componentNotFoundTemplate: string;
-        error_languageNotFoundTemplate: string;
-        error_stringKeyNotFoundTemplate: string;
-        error_incompleteRegistrationTemplate: string;
-        error_duplicateComponentTemplate: string;
-        error_duplicateLanguageTemplate: string;
-        error_validationFailedTemplate: string;
-        system_welcome: string;
-        system_goodbye: string;
-        system_pleaseWait: string;
-        system_processingRequest: string;
-        system_operationComplete: string;
-        system_noDataAvailable: string;
-    };
-    fr: {
-        common_yes: string;
-        common_no: string;
-        common_cancel: string;
-        common_ok: string;
-        common_save: string;
-        common_delete: string;
-        common_edit: string;
-        common_create: string;
-        common_update: string;
-        common_loading: string;
-        common_error: string;
-        common_success: string;
-        common_warning: string;
-        common_info: string;
-        error_invalidInput: string;
-        error_networkError: string;
-        error_notFound: string;
-        error_accessDenied: string;
-        error_internalServer: string;
-        error_validationFailed: string;
-        error_requiredField: string;
-        error_componentNotFoundTemplate: string;
-        error_languageNotFoundTemplate: string;
-        error_stringKeyNotFoundTemplate: string;
-        error_incompleteRegistrationTemplate: string;
-        error_duplicateComponentTemplate: string;
-        error_duplicateLanguageTemplate: string;
-        error_validationFailedTemplate: string;
-        system_welcome: string;
-        system_goodbye: string;
-        system_pleaseWait: string;
-        system_processingRequest: string;
-        system_operationComplete: string;
-        system_noDataAvailable: string;
-    };
-    es: {
-        common_yes: string;
-        common_no: string;
-        common_cancel: string;
-        common_ok: string;
-        common_save: string;
-        common_delete: string;
-        common_edit: string;
-        common_create: string;
-        common_update: string;
-        common_loading: string;
-        common_error: string;
-        common_success: string;
-        common_warning: string;
-        common_info: string;
-        error_invalidInput: string;
-        error_networkError: string;
-        error_notFound: string;
-        error_accessDenied: string;
-        error_internalServer: string;
-        error_validationFailed: string;
-        error_requiredField: string;
-        error_componentNotFoundTemplate: string;
-        error_languageNotFoundTemplate: string;
-        error_stringKeyNotFoundTemplate: string;
-        error_incompleteRegistrationTemplate: string;
-        error_duplicateComponentTemplate: string;
-        error_duplicateLanguageTemplate: string;
-        error_validationFailedTemplate: string;
-        system_welcome: string;
-        system_goodbye: string;
-        system_pleaseWait: string;
-        system_processingRequest: string;
-        system_operationComplete: string;
-        system_noDataAvailable: string;
-    };
-    de: {
-        common_yes: string;
-        common_no: string;
-        common_cancel: string;
-        common_ok: string;
-        common_save: string;
-        common_delete: string;
-        common_edit: string;
-        common_create: string;
-        common_update: string;
-        common_loading: string;
-        common_error: string;
-        common_success: string;
-        common_warning: string;
-        common_info: string;
-        error_invalidInput: string;
-        error_networkError: string;
-        error_notFound: string;
-        error_accessDenied: string;
-        error_internalServer: string;
-        error_validationFailed: string;
-        error_requiredField: string;
-        error_componentNotFoundTemplate: string;
-        error_languageNotFoundTemplate: string;
-        error_stringKeyNotFoundTemplate: string;
-        error_incompleteRegistrationTemplate: string;
-        error_duplicateComponentTemplate: string;
-        error_duplicateLanguageTemplate: string;
-        error_validationFailedTemplate: string;
-        system_welcome: string;
-        system_goodbye: string;
-        system_pleaseWait: string;
-        system_processingRequest: string;
-        system_operationComplete: string;
-        system_noDataAvailable: string;
-    };
-    "zh-CN": {
-        common_yes: string;
-        common_no: string;
-        common_cancel: string;
-        common_ok: string;
-        common_save: string;
-        common_delete: string;
-        common_edit: string;
-        common_create: string;
-        common_update: string;
-        common_loading: string;
-        common_error: string;
-        common_success: string;
-        common_warning: string;
-        common_info: string;
-        error_invalidInput: string;
-        error_networkError: string;
-        error_notFound: string;
-        error_accessDenied: string;
-        error_internalServer: string;
-        error_validationFailed: string;
-        error_requiredField: string;
-        error_componentNotFoundTemplate: string;
-        error_languageNotFoundTemplate: string;
-        error_stringKeyNotFoundTemplate: string;
-        error_incompleteRegistrationTemplate: string;
-        error_duplicateComponentTemplate: string;
-        error_duplicateLanguageTemplate: string;
-        error_validationFailedTemplate: string;
-        system_welcome: string;
-        system_goodbye: string;
-        system_pleaseWait: string;
-        system_processingRequest: string;
-        system_operationComplete: string;
-        system_noDataAvailable: string;
-    };
-    ja: {
-        common_yes: string;
-        common_no: string;
-        common_cancel: string;
-        common_ok: string;
-        common_save: string;
-        common_delete: string;
-        common_edit: string;
-        common_create: string;
-        common_update: string;
-        common_loading: string;
-        common_error: string;
-        common_success: string;
-        common_warning: string;
-        common_info: string;
-        error_invalidInput: string;
-        error_networkError: string;
-        error_notFound: string;
-        error_accessDenied: string;
-        error_internalServer: string;
-        error_validationFailed: string;
-        error_requiredField: string;
-        error_componentNotFoundTemplate: string;
-        error_languageNotFoundTemplate: string;
-        error_stringKeyNotFoundTemplate: string;
-        error_incompleteRegistrationTemplate: string;
-        error_duplicateComponentTemplate: string;
-        error_duplicateLanguageTemplate: string;
-        error_validationFailedTemplate: string;
-        system_welcome: string;
-        system_goodbye: string;
-        system_pleaseWait: string;
-        system_processingRequest: string;
-        system_operationComplete: string;
-        system_noDataAvailable: string;
-    };
-    uk: {
-        common_yes: string;
-        common_no: string;
-        common_cancel: string;
-        common_ok: string;
-        common_save: string;
-        common_delete: string;
-        common_edit: string;
-        common_create: string;
-        common_update: string;
-        common_loading: string;
-        common_error: string;
-        common_success: string;
-        common_warning: string;
-        common_info: string;
-        error_invalidInput: string;
-        error_networkError: string;
-        error_notFound: string;
-        error_accessDenied: string;
-        error_internalServer: string;
-        error_validationFailed: string;
-        error_requiredField: string;
-        error_componentNotFoundTemplate: string;
-        error_languageNotFoundTemplate: string;
-        error_stringKeyNotFoundTemplate: string;
-        error_incompleteRegistrationTemplate: string;
-        error_duplicateComponentTemplate: string;
-        error_duplicateLanguageTemplate: string;
-        error_validationFailedTemplate: string;
-        system_welcome: string;
-        system_goodbye: string;
-        system_pleaseWait: string;
-        system_processingRequest: string;
-        system_operationComplete: string;
-        system_noDataAvailable: string;
-    };
-};
+export declare function createCoreComponentStrings(): import("./strict-types").CompleteComponentLanguageStrings<CoreStringKey, CoreLanguage>;
 /**
  * Create core component registration
  */

package/dist/core-i18n.js

@@ -14,6 +14,7 @@ const core_language_1 = require("./core-language");
 const core_string_key_1 = require("./core-string-key");
 const language_registry_1 = require("./language-registry");
 const plugin_i18n_engine_1 = require("./plugin-i18n-engine");
+const strict_types_1 = require("./strict-types");
 /**
  * Create default language definitions
  */
@@ -74,7 +75,7 @@ exports.CoreComponentDefinition = {
  * Core component strings for all default languages
  */
 function createCoreComponentStrings() {
-    return {
+    return (0, strict_types_1.createCompleteComponentStrings)({
         [core_language_1.CoreLanguage.EnglishUS]: {
             // Common/General
             [core_string_key_1.CoreStringKey.Common_Yes]: 'Yes',
@@ -395,7 +396,7 @@ function createCoreComponentStrings() {
             [core_string_key_1.CoreStringKey.System_OperationComplete]: 'Операція успішно завершена',
             [core_string_key_1.CoreStringKey.System_NoDataAvailable]: 'Дані недоступні',
         },
-    };
+    });
 }
 /**
  * Create core component registration

package/dist/index.d.ts

@@ -33,3 +33,8 @@ export * from './translation-response';
 export { createCoreI18nEngine as createCoreI18n } from './core-i18n';
 export { I18nEngine as I18n } from './i18n-engine';
 export { PluginI18nEngine as PluginI18n } from './plugin-i18n-engine';
+/**
+ * Reset all I18n engines and clear component registrations
+ * Useful for test cleanup
+ */
+export declare function resetAllI18nEngines(): void;

package/dist/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PluginI18n = exports.I18n = exports.createCoreI18n = void 0;
+exports.resetAllI18nEngines = resetAllI18nEngines;
 // Legacy exports (for backwards compatibility)
 __exportStar(require("./active-context"), exports);
 __exportStar(require("./component-definition"), exports);
@@ -55,3 +56,12 @@ var i18n_engine_1 = require("./i18n-engine");
 Object.defineProperty(exports, "I18n", { enumerable: true, get: function () { return i18n_engine_1.I18nEngine; } });
 var plugin_i18n_engine_1 = require("./plugin-i18n-engine");
 Object.defineProperty(exports, "PluginI18n", { enumerable: true, get: function () { return plugin_i18n_engine_1.PluginI18nEngine; } });
+// Testing utilities
+const plugin_i18n_engine_2 = require("./plugin-i18n-engine");
+/**
+ * Reset all I18n engines and clear component registrations
+ * Useful for test cleanup
+ */
+function resetAllI18nEngines() {
+    plugin_i18n_engine_2.PluginI18nEngine.resetAll();
+}

package/dist/plugin-i18n-engine.d.ts

@@ -123,4 +123,25 @@ export declare class PluginI18nEngine<TLanguages extends string> {
         errors: string[];
         warnings: string[];
     };
+    /**
+     * Clear all component registrations for this instance (useful for testing)
+     */
+    clearAllComponents(): void;
+    /**
+     * Clear all named instances (useful for testing)
+     */
+    static clearAllInstances(): void;
+    /**
+     * Remove a specific named instance
+     */
+    static removeInstance(key?: string): boolean;
+    /**
+     * Check if an instance exists
+     */
+    static hasInstance(key?: string): boolean;
+    /**
+     * Reset all plugin engines and clear component registrations
+     * Useful for test cleanup
+     */
+    static resetAll(): void;
 }

package/dist/plugin-i18n-engine.js

@@ -49,6 +49,11 @@ class PluginI18nEngine {
             timezone: this.config.timezone,
             adminTimezone: this.config.adminTimezone,
         };
+        // Auto-register as default instance if none exists
+        if (!PluginI18nEngine._defaultKey) {
+            PluginI18nEngine._instances.set(PluginI18nEngine.DefaultInstanceKey, this);
+            PluginI18nEngine._defaultKey = PluginI18nEngine.DefaultInstanceKey;
+        }
     }
     /**
      * Create a new instance with a specific key
@@ -256,6 +261,50 @@ class PluginI18nEngine {
         }
         return { isValid, errors, warnings };
     }
+    /**
+     * Clear all component registrations for this instance (useful for testing)
+     */
+    clearAllComponents() {
+        this.componentRegistry.clearAllComponents();
+    }
+    /**
+     * Clear all named instances (useful for testing)
+     */
+    static clearAllInstances() {
+        PluginI18nEngine._instances.clear();
+        PluginI18nEngine._defaultKey = null;
+    }
+    /**
+     * Remove a specific named instance
+     */
+    static removeInstance(key) {
+        const instanceKey = key || PluginI18nEngine.DefaultInstanceKey;
+        const removed = PluginI18nEngine._instances.delete(instanceKey);
+        // If we removed the default instance, clear the default key
+        if (removed && PluginI18nEngine._defaultKey === instanceKey) {
+            PluginI18nEngine._defaultKey = null;
+        }
+        return removed;
+    }
+    /**
+     * Check if an instance exists
+     */
+    static hasInstance(key) {
+        const instanceKey = key || PluginI18nEngine.DefaultInstanceKey;
+        return PluginI18nEngine._instances.has(instanceKey);
+    }
+    /**
+     * Reset all plugin engines and clear component registrations
+     * Useful for test cleanup
+     */
+    static resetAll() {
+        for (const [key, engine] of PluginI18nEngine._instances) {
+            // Clear component registrations for each engine
+            engine.clearAllComponents();
+        }
+        PluginI18nEngine._instances.clear();
+        PluginI18nEngine._defaultKey = null;
+    }
 }
 exports.PluginI18nEngine = PluginI18nEngine;
 /**

package/dist/strict-types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Enforces that for each language L, all string keys K are present.
+ */
+export type CompleteLanguageStrings<TStringKey extends string> = {
+    [K in TStringKey]: string;
+};
+export type CompleteComponentLanguageStrings<TStringKey extends string, TLanguages extends string> = {
+    [L in TLanguages]: CompleteLanguageStrings<TStringKey>;
+};
+/**
+ * Helper to assert at compile-time that an object is a complete component language map.
+ * Returns the object unchanged at runtime.
+ */
+export declare function createCompleteComponentStrings<TStringKey extends string, TLanguages extends string>(obj: CompleteComponentLanguageStrings<TStringKey, TLanguages>): CompleteComponentLanguageStrings<TStringKey, TLanguages>;
+/**
+ * Utility to extract missing keys at compile time (identity, purely for readability)
+ */
+export declare function defineLanguageStrings<TStringKey extends string>(strings: CompleteLanguageStrings<TStringKey>): CompleteLanguageStrings<TStringKey>;

package/dist/strict-types.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCompleteComponentStrings = createCompleteComponentStrings;
+exports.defineLanguageStrings = defineLanguageStrings;
+/**
+ * Helper to assert at compile-time that an object is a complete component language map.
+ * Returns the object unchanged at runtime.
+ */
+function createCompleteComponentStrings(obj) {
+    return obj;
+}
+/**
+ * Utility to extract missing keys at compile time (identity, purely for readability)
+ */
+function defineLanguageStrings(strings) {
+    return strings;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitaldefiance/i18n-lib",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Generic i18n library with enum translation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",