@digitaldefiance/i18n-lib 1.0.22 → 1.0.24

package/README.md

@@ -5,12 +5,15 @@ A comprehensive TypeScript internationalization library with enum translation su
 ## Features
 
 - **Type-Safe Translations**: Full TypeScript support with generic types for strings and languages
+- **Configuration Validation**: Automatic validation ensures all languages have complete string collections
+- **Localized Error Messages**: Error messages can be translated using the engine's own translation system
 - **Enum Translation Registry**: Translate enum values with complete type safety
 - **Template Processing**: Advanced template system with `{{EnumName.EnumKey}}` patterns and variable replacement
 - **Context Management**: Admin vs user translation contexts with automatic language switching
 - **Singleton Pattern**: Efficient instance management with named instances
 - **Currency Formatting**: Built-in currency formatting utilities with locale support
 - **Fallback System**: Graceful degradation when translations are missing
+- **Extensible Configuration**: Module augmentation support for layered library extension
 - **Zero Dependencies**: Lightweight with no external dependencies
 
 ## Installation
@@ -22,7 +25,7 @@ npm install @digitaldefiance/i18n-lib
 ## Quick Start
 
 ```typescript
-import { I18nEngine, I18nConfig, createContext } from '@digitaldefiance/i18n-lib';
+import { I18nEngine, I18nConfig, createContext, CurrencyCode, Timezone } from '@digitaldefiance/i18n-lib';
 
 // Define your enums
 enum MyStrings {
@@ -49,12 +52,15 @@ const config: I18nConfig<MyStrings, MyLanguages> = {
     }
   },
   defaultLanguage: MyLanguages.English,
-  defaultContext: 'user',
+  defaultTranslationContext: 'user',
+  defaultCurrencyCode: new CurrencyCode('USD'),
   languageCodes: {
     [MyLanguages.English]: 'en',
     [MyLanguages.Spanish]: 'es'
   },
-  languages: Object.values(MyLanguages)
+  languages: Object.values(MyLanguages),
+  timezone: new Timezone('UTC'),
+  adminTimezone: new Timezone('UTC')
 };
 
 // Create engine
@@ -216,7 +222,7 @@ I18nEngine.removeInstance('main');
 #### Translation Methods
 - `translate(key, vars?, language?, fallbackLanguage?)` - Translate string with optional variables
 - `translateEnum(enumObj, value, language)` - Translate enum value
-- `t(templateString, language?, ...vars)` - Process template with enum patterns
+- `t(templateString, language?, ...vars)` - Process template string with `{{EnumName.EnumKey}}` patterns
 
 #### Registration
 - `registerEnum(enumObj, translations, enumName)` - Register enum translations
@@ -266,16 +272,19 @@ type EnumLanguageTranslation<T extends string | number, TLanguage extends string
   [L in TLanguage]: EnumTranslation<T>;
 }>;
 
-interface I18nConfig<TStringKey, TLanguage, TConstants?, TContext?> {
+interface I18nConfig<TStringKey, TLanguage, TConstants?, TTranslationContext?> {
   stringNames: TStringKey[];
   strings: MasterStringsCollection<TStringKey, TLanguage>;
   defaultLanguage: TLanguage;
-  defaultContext: TContext;
+  defaultTranslationContext: TTranslationContext;
+  defaultCurrencyCode: CurrencyCode;
   languageCodes: LanguageCodeCollection<TLanguage>;
   languages: TLanguage[];
   constants?: TConstants;
   enumName?: string;
   enumObj?: Record<string, TStringKey>;
+  timezone: Timezone;
+  adminTimezone: Timezone;
 }
 ```
 
@@ -293,6 +302,124 @@ yarn test enum-registry.spec.ts
 yarn test i18n-engine.spec.ts
 ```
 
+## Extensible Configuration
+
+The library supports layered extension across multiple libraries using TypeScript module augmentation:
+
+### Base Library Setup
+
+```typescript
+// In your base library
+import { DefaultStringKey, DefaultLanguage } from '@digitaldefiance/i18n-lib';
+
+enum MyLibStringKey {
+  Feature_Save = 'feature_save',
+  Feature_Load = 'feature_load',
+}
+
+// Extend the global configuration
+declare global {
+  namespace I18n {
+    interface Config {
+      StringKey: DefaultStringKey | MyLibStringKey;
+    }
+  }
+}
+```
+
+### Extending Another Library
+
+```typescript
+// In a library that extends the base library
+import { DefaultStringKey } from '@digitaldefiance/i18n-lib';
+import { MyLibStringKey } from 'my-base-lib';
+
+enum AdvancedStringKey {
+  Advanced_Export = 'advanced_export',
+  Advanced_Import = 'advanced_import',
+}
+
+// Extend with union types
+declare global {
+  namespace I18n {
+    interface Config {
+      StringKey: DefaultStringKey | MyLibStringKey | AdvancedStringKey;
+    }
+  }
+}
+```
+
+### Final Application
+
+```typescript
+// In your final application
+import { StringKey, Language, getI18nEngine } from 'my-extended-lib';
+
+// All string keys from all layers are now available
+const engine = getI18nEngine();
+const translation = engine.translate('advanced_export' as StringKey);
+```
+
+### Default Configuration Helper
+
+Use the default configuration helper for quick setup:
+
+```typescript
+import { getDefaultI18nEngine } from '@digitaldefiance/i18n-lib';
+
+// Create engine with default configuration
+const engine = getDefaultI18nEngine(
+  { APP_NAME: 'MyApp' }, // constants
+  new Timezone('America/New_York'), // user timezone
+  new Timezone('UTC') // admin timezone
+);
+```
+
+## Configuration Validation
+
+The engine automatically validates configurations during construction to ensure completeness:
+
+### Validation Rules
+
+1. **All languages in `languageCodes` must have corresponding `strings` collections**
+2. **All `stringNames` must be present in every language's string collection**
+3. **The `defaultLanguage` must have a string collection**
+
+### Localized Error Messages
+
+Validation errors can be localized by including error message keys in your configuration:
+
+```typescript
+enum MyStrings {
+  Welcome = 'welcome',
+  // Error message keys
+  Error_MissingStringCollectionTemplate = 'error_missing_string_collection_template',
+  Error_MissingTranslationTemplate = 'error_missing_translation_template',
+  Error_DefaultLanguageNoCollectionTemplate = 'error_default_language_no_collection_template'
+}
+
+const config: I18nConfig<MyStrings, MyLanguages> = {
+  stringNames: Object.values(MyStrings),
+  strings: {
+    [MyLanguages.English]: {
+      [MyStrings.Welcome]: 'Welcome!',
+      [MyStrings.Error_MissingStringCollectionTemplate]: 'Missing translations for language: {language}',
+      [MyStrings.Error_MissingTranslationTemplate]: 'Key \'{key}\' not found in {language}',
+      [MyStrings.Error_DefaultLanguageNoCollectionTemplate]: 'Default language \'{language}\' has no translations'
+    }
+  },
+  // ... rest of config
+};
+```
+
+### Fallback Error Messages
+
+If localized error messages aren't provided, the engine falls back to English templates:
+
+- `Missing string collection for language: {language}`
+- `Missing translation for key '{key}' in language '{language}'`
+- `Default language '{language}' has no string collection`
+
 ## Best Practices
 
 1. **Complete Translations**: EnumTranslation requires all enum values to be translated
@@ -300,6 +427,8 @@ yarn test i18n-engine.spec.ts
 3. **Context Separation**: Use different contexts for admin and user interfaces
 4. **Instance Management**: Use named instances for different parts of your application
 5. **Error Handling**: Handle missing translations gracefully with fallback languages
+6. **Layered Extension**: Use union types when extending configurations across libraries
+7. **Default Configuration**: Use `getDefaultI18nEngine()` for standard setups
 
 ## License
 

package/dist/context.d.ts

@@ -10,7 +10,7 @@ import { I18nContext, LanguageContext } from './types';
  * @param defaultAdminTimezone - The default admin timezone (defaults to UTC)
  * @returns A new I18nContext instance
  */
-export declare function createContext<TLanguage extends string, TContext extends string = LanguageContext>(defaultLanguage: TLanguage, defaultContext: TContext, defaultCurrencyCode?: CurrencyCode, defaultTimezone?: Timezone, defaultAdminTimezone?: Timezone): I18nContext<TLanguage, TContext>;
+export declare function createContext<TLanguage extends string, TTranslationContext extends string = LanguageContext, TContext extends I18nContext<TLanguage, TTranslationContext> = I18nContext<TLanguage, TTranslationContext>>(defaultLanguage: TLanguage, defaultContext: TTranslationContext, defaultCurrencyCode?: CurrencyCode, defaultTimezone?: Timezone, defaultAdminTimezone?: Timezone): TContext;
 /**
  * Sets the language for the given I18n context.
  * @param context - The I18n context to modify

package/dist/default-config.d.ts

@@ -0,0 +1,31 @@
+import { I18nEngine } from './i18n-engine';
+import { Timezone } from './timezone';
+import { I18nContext, LanguageCodeCollection } from './types';
+export declare enum DefaultStringKey {
+    Common_Test = "common_test"
+}
+export declare enum DefaultLanguage {
+    EnglishUS = "English (US)",
+    EnglishUK = "English (UK)",
+    French = "Fran\u00E7ais",
+    MandarinChinese = "\u4E2D\u6587",
+    Spanish = "Espa\u00F1ol",
+    Ukrainian = "\u0423\u043A\u0440\u0430\u0457\u043D\u0441\u044C\u043A\u0438\u0439"
+}
+export declare const DefaultLanguageCodes: LanguageCodeCollection<DefaultLanguage>;
+declare global {
+    namespace I18n {
+        interface Config {
+            StringKey: DefaultStringKey;
+            Language: DefaultLanguage;
+            LanguageCodes: LanguageCodeCollection<DefaultLanguage>;
+            engine: I18nEngine<I18n.Config['StringKey'], I18n.Config['Language'], Record<any, any>, string>;
+        }
+    }
+}
+export type StringKey = I18n.Config['StringKey'];
+export type Language = I18n.Config['Language'];
+export type Engine = I18n.Config['engine'];
+export type LanguageCodes = I18n.Config['LanguageCodes'];
+export declare const getI18nEngine: () => Engine;
+export declare const getDefaultI18nEngine: <TConstants extends Record<string, any>, TTranslationContext extends string, TContext extends I18nContext<DefaultLanguage, TTranslationContext>>(constants: TConstants, timezone?: Timezone, adminTimezone?: Timezone) => I18nEngine<DefaultStringKey, DefaultLanguage, TConstants, TTranslationContext, TContext>;

package/dist/default-config.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultI18nEngine = exports.getI18nEngine = exports.DefaultLanguageCodes = exports.DefaultLanguage = exports.DefaultStringKey = void 0;
+const currency_code_1 = require("./currency-code");
+const i18n_engine_1 = require("./i18n-engine");
+const timezone_1 = require("./timezone");
+const types_1 = require("./types");
+// Default enum types that can be augmented by consumers
+var DefaultStringKey;
+(function (DefaultStringKey) {
+    DefaultStringKey["Common_Test"] = "common_test";
+})(DefaultStringKey || (exports.DefaultStringKey = DefaultStringKey = {}));
+var DefaultLanguage;
+(function (DefaultLanguage) {
+    DefaultLanguage["EnglishUS"] = "English (US)";
+    DefaultLanguage["EnglishUK"] = "English (UK)";
+    DefaultLanguage["French"] = "Fran\u00E7ais";
+    DefaultLanguage["MandarinChinese"] = "\u4E2D\u6587";
+    DefaultLanguage["Spanish"] = "Espa\u00F1ol";
+    DefaultLanguage["Ukrainian"] = "\u0423\u043A\u0440\u0430\u0457\u043D\u0441\u044C\u043A\u0438\u0439";
+})(DefaultLanguage || (exports.DefaultLanguage = DefaultLanguage = {}));
+exports.DefaultLanguageCodes = {
+    [DefaultLanguage.EnglishUS]: 'en',
+    [DefaultLanguage.EnglishUK]: 'en-GB',
+    [DefaultLanguage.French]: 'fr',
+    [DefaultLanguage.MandarinChinese]: 'zh-CN',
+    [DefaultLanguage.Spanish]: 'es',
+    [DefaultLanguage.Ukrainian]: 'uk',
+};
+// Singleton instance that uses the augmented types
+const getI18nEngine = () => i18n_engine_1.I18nEngine.getInstance();
+exports.getI18nEngine = getI18nEngine;
+const getConfig = (constants, timezone, adminTimezone) => ({
+    strings: {
+        [DefaultLanguage.EnglishUS]: {
+            [DefaultStringKey.Common_Test]: 'Test',
+        },
+        [DefaultLanguage.EnglishUK]: {
+            [DefaultStringKey.Common_Test]: 'Test',
+        },
+        [DefaultLanguage.French]: {
+            [DefaultStringKey.Common_Test]: 'Test',
+        },
+        [DefaultLanguage.MandarinChinese]: {
+            [DefaultStringKey.Common_Test]: '测试',
+        },
+        [DefaultLanguage.Spanish]: {
+            [DefaultStringKey.Common_Test]: 'Prueba',
+        },
+        [DefaultLanguage.Ukrainian]: {
+            [DefaultStringKey.Common_Test]: 'Тест',
+        },
+    },
+    stringNames: Object.values(DefaultStringKey),
+    defaultLanguage: DefaultLanguage.EnglishUS,
+    defaultTranslationContext: 'user',
+    defaultCurrencyCode: new currency_code_1.CurrencyCode(types_1.DefaultCurrencyCode),
+    languageCodes: exports.DefaultLanguageCodes,
+    languages: Object.values(DefaultLanguage),
+    constants: constants,
+    enumName: 'DefaultStringKey',
+    enumObj: DefaultStringKey,
+    timezone: timezone ?? new timezone_1.Timezone('UTC'),
+    adminTimezone: adminTimezone ?? new timezone_1.Timezone('UTC'),
+});
+const getDefaultI18nEngine = (constants, timezone, adminTimezone) => new i18n_engine_1.I18nEngine(getConfig(constants, timezone, adminTimezone), 'user');
+exports.getDefaultI18nEngine = getDefaultI18nEngine;

package/dist/i18n-engine.d.ts

@@ -3,7 +3,7 @@ import { EnumLanguageTranslation, I18nConfig, I18nContext } from './types';
 /**
  * Internationalization engine class
  */
-export declare class I18nEngine<TStringKey extends string, TLanguage extends string, TConstants extends Record<string, any> = Record<string, any>, TContext extends string = string> {
+export declare class I18nEngine<TStringKey extends string, TLanguage extends string, TConstants extends Record<string, any> = Record<string, any>, TTranslationContext extends string = string, TContext extends I18nContext<TLanguage, TTranslationContext> = I18nContext<TLanguage, TTranslationContext>> {
     /**
      * Registry for enum translations
      */
@@ -11,7 +11,7 @@ export declare class I18nEngine<TStringKey extends string, TLanguage extends str
     /**
      * Configuration for the i18n engine
      */
-    readonly config: I18nConfig<TStringKey, TLanguage, TConstants, TContext>;
+    readonly config: I18nConfig<TStringKey, TLanguage, TConstants, TTranslationContext>;
     /**
      * Static instances for semi-singleton pattern
      */
@@ -38,7 +38,7 @@ export declare class I18nEngine<TStringKey extends string, TLanguage extends str
      * @param key Optional instance key for the semi-singleton pattern
      * @throws Error if an instance with the same key already exists
      */
-    constructor(config: I18nConfig<TStringKey, TLanguage, TConstants, TContext>, key?: string);
+    constructor(config: I18nConfig<TStringKey, TLanguage, TConstants, TTranslationContext>, key?: string, newContext?: () => TContext);
     /**
      * Gets an instance of the I18nEngine by key. If no key is provided, the default instance is returned.
      * @param key The key of the instance to retrieve
@@ -68,12 +68,12 @@ export declare class I18nEngine<TStringKey extends string, TLanguage extends str
      * Gets the global context for translations
      * @returns The global context object
      */
-    get context(): I18nContext<TLanguage, TContext>;
+    get context(): TContext;
     /**
      * Sets the global context for translations (used if no context is provided) for this instance
      * @param context The context to set
      */
-    set context(context: Partial<I18nContext<TLanguage, TContext>>);
+    set context(context: Partial<TContext>);
     /**
      * Translates a string key into the specified language, replacing any variables as needed.
      * @param key The string key to translate
@@ -153,4 +153,19 @@ export declare class I18nEngine<TStringKey extends string, TLanguage extends str
      * @internal
      */
     static removeInstance(key?: string): void;
+    /**
+     * Static error message templates for validation
+     */
+    private static readonly ErrorTemplates;
+    /**
+     * Validates the configuration to ensure all languages have string collections
+     * and all string keys are provided for each language
+     * @param config The configuration to validate
+     * @throws Error if validation fails
+     */
+    private validateConfig;
+    /**
+     * Gets validation error message, trying translation first, falling back to template
+     */
+    private getValidationError;
 }

package/dist/i18n-engine.js

@@ -15,10 +15,11 @@ class I18nEngine {
      * @param key Optional instance key for the semi-singleton pattern
      * @throws Error if an instance with the same key already exists
      */
-    constructor(config, key) {
+    constructor(config, key, newContext = () => (0, context_1.createContext)(config.defaultLanguage, config.defaultTranslationContext, config.defaultCurrencyCode, config.timezone, config.adminTimezone)) {
+        this.validateConfig(config);
         this.config = config;
         this.enumRegistry = new enum_registry_1.EnumTranslationRegistry();
-        this._context = (0, context_1.createContext)(config.defaultLanguage, config.defaultTranslationContext, config.defaultCurrencyCode, config.timezone, config.adminTimezone);
+        this._context = newContext();
         const instanceKey = key || I18nEngine.DefaultInstanceKey;
         if (I18nEngine._instances.has(instanceKey)) {
             const existing = I18nEngine._instances.get(instanceKey);
@@ -247,9 +248,52 @@ class I18nEngine {
         I18nEngine._instances.delete(instanceKey);
         if (I18nEngine._defaultKey === instanceKey) {
             const nextKey = I18nEngine._instances.keys().next().value;
-            I18nEngine._defaultKey = I18nEngine._instances.size > 0 && nextKey ? nextKey : null;
+            I18nEngine._defaultKey =
+                I18nEngine._instances.size > 0 && nextKey ? nextKey : null;
         }
     }
+    /**
+     * Validates the configuration to ensure all languages have string collections
+     * and all string keys are provided for each language
+     * @param config The configuration to validate
+     * @throws Error if validation fails
+     */
+    validateConfig(config) {
+        // Check that all languages in languageCodes have string collections
+        for (const language of Object.keys(config.languageCodes)) {
+            if (!config.strings[language]) {
+                throw new Error(this.getValidationError('Error_MissingStringCollectionTemplate', { language }, config));
+            }
+            // Check that all string keys are provided for this language
+            const strings = config.strings[language];
+            for (const stringKey of config.stringNames) {
+                if (!strings[stringKey]) {
+                    throw new Error(this.getValidationError('Error_MissingTranslationTemplate', { key: stringKey, language }, config));
+                }
+            }
+        }
+        // Check that default language exists
+        if (!config.strings[config.defaultLanguage]) {
+            throw new Error(this.getValidationError('Error_DefaultLanguageNoCollectionTemplate', { language: config.defaultLanguage }, config));
+        }
+    }
+    /**
+     * Gets validation error message, trying translation first, falling back to template
+     */
+    getValidationError(key, vars, config) {
+        try {
+            const strings = config.strings[config.defaultLanguage];
+            if (strings?.[key]) {
+                return (0, utils_1.replaceVariables)(strings[key], vars, config.constants);
+            }
+        }
+        catch { }
+        // Fallback to static templates
+        const template = key.includes('MissingStringCollection') ? I18nEngine.ErrorTemplates.MissingStringCollection :
+            key.includes('MissingTranslation') ? I18nEngine.ErrorTemplates.MissingTranslation :
+                I18nEngine.ErrorTemplates.DefaultLanguageNoCollection;
+        return (0, utils_1.replaceVariables)(template, vars);
+    }
 }
 exports.I18nEngine = I18nEngine;
 /**
@@ -264,3 +308,11 @@ I18nEngine._defaultKey = null;
  * Default instance key if none is provided
  */
 I18nEngine.DefaultInstanceKey = 'default';
+/**
+ * Static error message templates for validation
+ */
+I18nEngine.ErrorTemplates = {
+    MissingStringCollection: 'Missing string collection for language: {language}',
+    MissingTranslation: 'Missing translation for key \'{key}\' in language \'{language}\'',
+    DefaultLanguageNoCollection: 'Default language \'{language}\' has no string collection'
+};

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './currency';
 export * from './currency-code';
 export * from './currency-format';
 export * from './enum-registry';
+export * from './default-config';
 export * from './i18n-engine';
 export * from './template';
 export * from './timezone';

package/dist/index.js

@@ -22,6 +22,7 @@ __exportStar(require("./currency"), exports);
 __exportStar(require("./currency-code"), exports);
 __exportStar(require("./currency-format"), exports);
 __exportStar(require("./enum-registry"), exports);
+__exportStar(require("./default-config"), exports);
 __exportStar(require("./i18n-engine"), exports);
 __exportStar(require("./template"), exports);
 __exportStar(require("./timezone"), exports);

package/dist/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@digitaldefiance/i18n-lib",
+  "version": "1.0.23",
+  "description": "Generic i18n library with enum translation support",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "yarn tsc",
+    "test": "yarn jest --detectOpenHandles",
+    "lint": "eslint src/**/*.ts tests/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts tests/**/*.ts --fix",
+    "prettier:check": "prettier --check 'src/**/*.{ts,tsx}' 'tests/**/*.{ts,tsx}'",
+    "prettier:fix": "prettier --write 'src/**/*.{ts,tsx}' 'tests/**/*.{ts,tsx}'",
+    "format": "yarn prettier:fix && yarn lint:fix",
+    "prepublishOnly": "yarn build",
+    "publish:public": "npm publish --access public"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.31.1",
+    "@typescript-eslint/parser": "^8.31.1",
+    "eslint": "^9.8.0",
+    "eslint-config-prettier": "^10.1.2",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.3.1",
+    "jest": "^29.0.0",
+    "jest-util": "^30.0.5",
+    "prettier": "^2.6.2",
+    "prettier-plugin-organize-imports": "^4.1.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.9.2"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "i18n",
+    "internationalization",
+    "typescript",
+    "enum",
+    "translation"
+  ],
+  "author": "Digital Defiance",
+  "license": "MIT",
+  "packageManager": "yarn@4.10.3",
+  "dependencies": {
+    "moment": "^2.30.1",
+    "moment-timezone": "^0.6.0"
+  },
+  "type": "commonjs"
+}

package/dist/src/active-context.d.ts

@@ -0,0 +1,29 @@
+import { LanguageContext } from './types';
+import { Timezone } from './timezone';
+import { CurrencyCode } from './currency-code';
+export interface IActiveContext<TLanguage extends string> {
+    /**
+     * The default language for the user facing application
+     */
+    language: TLanguage;
+    /**
+     * The default language for the admin interface
+     */
+    adminLanguage: TLanguage;
+    /**
+     * The default currency code for the user facing application
+     */
+    currencyCode: CurrencyCode;
+    /**
+     * The default language context for the current context
+     */
+    currentContext: LanguageContext;
+    /**
+     * The default timezone for the user facing application
+     */
+    timezone: Timezone;
+    /**
+     * The default timezone for the admin interface
+     */
+    adminTimezone: Timezone;
+}

package/dist/src/active-context.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/context-manager.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Context change management for i18n systems
+ */
+export type ContextChangeListener<T = any> = (property: string, oldValue: T, newValue: T) => void;
+/**
+ * Manages context changes and notifies listeners.
+ */
+export declare class ContextManager<TContext extends Record<string, any>> {
+    protected listeners: ContextChangeListener[];
+    /**
+     * Adds a listener to be notified of context changes.
+     * @param listener - The listener function to add
+     */
+    addListener(listener: ContextChangeListener): void;
+    /**
+     * Removes a listener from the notification list.
+     * @param listener - The listener function to remove
+     */
+    removeListener(listener: ContextChangeListener): void;
+    /**
+     * Notifies all listeners of a context change.
+     * @param property - The property that changed
+     * @param oldValue - The old value of the property
+     * @param newValue - The new value of the property
+     */
+    notifyChange<K extends keyof TContext>(property: K, oldValue: TContext[K], newValue: TContext[K]): void;
+    /**
+     * Creates a proxy for the given context to automatically notify listeners on changes.
+     * @param context - The context object to proxy
+     * @returns A proxied version of the context object
+     */
+    createProxy(context: TContext): TContext;
+}

package/dist/src/context-manager.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextManager = void 0;
+/**
+ * Manages context changes and notifies listeners.
+ */
+class ContextManager {
+    constructor() {
+        this.listeners = [];
+    }
+    /**
+     * Adds a listener to be notified of context changes.
+     * @param listener - The listener function to add
+     */
+    addListener(listener) {
+        this.listeners.push(listener);
+    }
+    /**
+     * Removes a listener from the notification list.
+     * @param listener - The listener function to remove
+     */
+    removeListener(listener) {
+        const index = this.listeners.indexOf(listener);
+        if (index > -1) {
+            this.listeners.splice(index, 1);
+        }
+    }
+    /**
+     * Notifies all listeners of a context change.
+     * @param property - The property that changed
+     * @param oldValue - The old value of the property
+     * @param newValue - The new value of the property
+     */
+    notifyChange(property, oldValue, newValue) {
+        this.listeners.forEach((listener) => {
+            try {
+                listener(property, oldValue, newValue);
+            }
+            catch (error) {
+                console.error('Error in context change listener:', error);
+            }
+        });
+    }
+    /**
+     * Creates a proxy for the given context to automatically notify listeners on changes.
+     * @param context - The context object to proxy
+     * @returns A proxied version of the context object
+     */
+    createProxy(context) {
+        const manager = this;
+        return new Proxy(context, {
+            set(target, property, value) {
+                const oldValue = target[property];
+                target[property] = value;
+                manager.notifyChange(property, oldValue, value);
+                return true;
+            },
+        });
+    }
+}
+exports.ContextManager = ContextManager;