@digitaldefiance/i18n-lib 3.7.5 → 3.8.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Digital Defiance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -853,6 +853,85 @@ const error = new TypedError('Error message', {
 
 None - This release maintains full backward compatibility while improving internal type safety.
 
+### Version 3.8.0
+
+**Internal Refactoring Release** - Circular Dependency Elimination
+
+This release eliminates all circular dependencies from the codebase through internal architectural improvements. All changes are non-breaking and maintain full backward compatibility.
+
+**Internal Improvements:**
+
+- **Zero Circular Dependencies**: Eliminated all 15 circular dependencies that existed in the codebase
+  - Broke core/i18n-engine ↔ core-i18n cycle
+  - Broke errors/translatable → core/i18n-engine → errors/index cycle
+  - Broke core-i18n ↔ plugin-i18n-engine cycle
+  - Broke context-related cycles
+  - Broke registry-error cycles
+  - Optimized barrel exports with type-only exports
+
+- **Lazy Initialization Pattern**: Error classes and core modules now use lazy initialization to avoid circular dependencies
+  - `TranslatableError` uses `getInstance()` at construction time instead of module load
+  - `TypedError` and related classes use lazy engine lookup
+  - Registry errors use lazy initialization for core dependencies
+  - Fallback behavior if engine not initialized
+
+- **Factory Pattern**: Introduced `core-plugin-factory.ts` to break plugin engine cycles
+  - `createCorePluginI18nEngine()` moved to factory file
+  - Factory imports both core-i18n and plugin-i18n-engine
+  - Breaks circular dependency between these modules
+
+- **Type-Only Exports**: Optimized barrel exports to eliminate runtime dependencies
+  - `src/interfaces/index.ts` uses `export type` for all type exports
+  - `src/errors/index.ts` split into base.ts and translatable-exports.ts
+  - `src/core/index.ts` uses type-only exports where appropriate
+
+- **Module Organization**: Established clear dependency hierarchy
+  - Interfaces & Types (no implementation dependencies)
+  - Error Classes (lazy initialization for i18n)
+  - Core Modules (clear hierarchy, no cycles)
+  - High-Level Modules (core-i18n, plugin-i18n-engine)
+
+**Testing & Quality:**
+
+- **Automated Circular Dependency Detection**: Added test that fails if circular dependencies are introduced
+- **Module Independence Tests**: Verify modules can be imported independently
+- **All Tests Passing**: 1,779 tests passing with no regressions
+- **Zero Breaking Changes**: Public API remains completely unchanged
+
+**Documentation:**
+
+- **[CIRCULAR_DEPENDENCY_FIXES.md](docs/CIRCULAR_DEPENDENCY_FIXES.md)** - Comprehensive internal documentation
+  - Detailed explanation of all patterns used
+  - Best practices for maintaining zero circular dependencies
+  - Examples of lazy initialization, factory pattern, and type-only exports
+  - Guidelines for adding new modules without creating cycles
+
+**Files Modified:**
+
+- `src/core-plugin-factory.ts` - New factory file for plugin engine creation
+- `src/core-i18n.ts` - Lazy initialization with Proxy pattern
+- `src/errors/*.ts` - Lazy initialization in error constructors
+- `src/errors/index.ts` - Split into separate barrel files
+- `src/interfaces/index.ts` - Type-only exports
+- `src/core/index.ts` - Optimized barrel exports
+- `src/registry-error.ts` - Lazy initialization for core dependencies
+- `tests/circular-dependencies.spec.ts` - Automated detection test
+
+**Breaking Changes:**
+
+None - This release is fully backward compatible. All changes are internal refactoring only.
+
+**Migration:**
+
+No migration required! Your existing code works unchanged. The improvements are entirely internal.
+
+**Benefits:**
+
+- **Improved Maintainability**: Clearer module structure and dependencies
+- **Better Tree-Shaking**: Reduced runtime dependencies improve bundle optimization
+- **Predictable Initialization**: No more initialization order issues
+- **Future-Proof**: Established patterns prevent circular dependencies from being reintroduced
+
 ### Version 3.7.2
 
 - Minor version bump to fix an export
@@ -1675,6 +1754,188 @@ const registration: ComponentRegistration<MyStringKeys, MyLanguages> = {
 - Safari: Latest 2 versions
 - Node.js: 18+
 
+## Testing
+
+### Testing Approach
+
+The i18n-lib package uses a comprehensive testing strategy combining unit tests, integration tests, and property-based testing to ensure correctness across all features.
+
+**Test Framework**: Jest with TypeScript support  
+**Property-Based Testing**: fast-check for testing universal properties  
+**Coverage Target**: 90%+ statement coverage, 85%+ branch coverage
+
+### Test Structure
+
+```
+tests/
+  ├── unit/              # Unit tests for individual components
+  ├── integration/       # Integration tests for component interactions
+  ├── property/          # Property-based tests using fast-check
+  └── fixtures/          # Test data and mock translations
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm test -- --coverage
+
+# Run specific test file
+npm test -- plugin-i18n-engine.spec.ts
+
+# Run in watch mode
+npm test -- --watch
+```
+
+### Test Patterns
+
+#### Testing Translation Registration
+
+```typescript
+import { PluginI18nEngine, LanguageCodes } from '@digitaldefiance/i18n-lib';
+
+describe('Component Registration', () => {
+  let engine: PluginI18nEngine;
+
+  beforeEach(() => {
+    PluginI18nEngine.resetAll();
+    engine = PluginI18nEngine.createInstance('test', [
+      { id: LanguageCodes.EN_US, name: 'English', code: 'en-US', isDefault: true }
+    ]);
+  });
+
+  afterEach(() => {
+    PluginI18nEngine.resetAll();
+  });
+
+  it('should register component with translations', () => {
+    engine.registerComponent({
+      component: {
+        id: 'test',
+        name: 'Test',
+        stringKeys: ['hello']
+      },
+      strings: {
+        [LanguageCodes.EN_US]: {
+          hello: 'Hello, {name}!'
+        }
+      }
+    });
+
+    expect(engine.translate('test', 'hello', { name: 'World' }))
+      .toBe('Hello, World!');
+  });
+});
+```
+
+#### Testing ICU MessageFormat
+
+```typescript
+import { formatICUMessage } from '@digitaldefiance/i18n-lib';
+
+describe('ICU MessageFormat', () => {
+  it('should format plural messages', () => {
+    const message = '{count, plural, one {# item} other {# items}}';
+    
+    expect(formatICUMessage(message, { count: 1 })).toBe('1 item');
+    expect(formatICUMessage(message, { count: 5 })).toBe('5 items');
+  });
+
+  it('should handle nested select and plural', () => {
+    const message = '{gender, select, male {He has} female {She has}} {count, plural, one {# item} other {# items}}';
+    
+    expect(formatICUMessage(message, { gender: 'female', count: 2 }))
+      .toBe('She has 2 items');
+  });
+});
+```
+
+#### Testing Error Handling
+
+```typescript
+import { RegistryError, RegistryErrorType } from '@digitaldefiance/i18n-lib';
+
+describe('Error Handling', () => {
+  it('should throw RegistryError for missing component', () => {
+    expect(() => {
+      engine.translate('missing', 'key');
+    }).toThrow(RegistryError);
+  });
+
+  it('should provide error metadata', () => {
+    try {
+      engine.translate('missing', 'key');
+    } catch (error) {
+      expect(error).toBeInstanceOf(RegistryError);
+      expect(error.type).toBe(RegistryErrorType.COMPONENT_NOT_FOUND);
+      expect(error.metadata).toEqual({ componentId: 'missing' });
+    }
+  });
+});
+```
+
+#### Property-Based Testing
+
+```typescript
+import * as fc from 'fast-check';
+import { createPluralString } from '@digitaldefiance/i18n-lib';
+
+describe('Pluralization Properties', () => {
+  it('should always return a string for any count', () => {
+    fc.assert(
+      fc.property(fc.integer(), (count) => {
+        const plural = createPluralString({
+          one: '{count} item',
+          other: '{count} items'
+        });
+        
+        const result = engine.translate('test', 'items', { count });
+        expect(typeof result).toBe('string');
+        expect(result.length).toBeGreaterThan(0);
+      })
+    );
+  });
+});
+```
+
+### Testing Best Practices
+
+1. **Always reset engine state** between tests using `PluginI18nEngine.resetAll()`
+2. **Test with multiple languages** to ensure translations work correctly
+3. **Test edge cases** like empty strings, special characters, and missing variables
+4. **Use property-based tests** for testing universal properties across many inputs
+5. **Mock external dependencies** when testing error conditions
+
+### Cross-Package Testing
+
+When testing packages that depend on i18n-lib:
+
+```typescript
+import { PluginI18nEngine } from '@digitaldefiance/i18n-lib';
+import { YourService } from 'your-package';
+
+describe('Service with i18n', () => {
+  beforeEach(() => {
+    // Set up i18n engine for your service
+    PluginI18nEngine.resetAll();
+    const engine = PluginI18nEngine.createInstance('test', languages);
+    // Register your component translations
+  });
+
+  afterEach(() => {
+    PluginI18nEngine.resetAll();
+  });
+
+  it('should use translated error messages', () => {
+    const service = new YourService();
+    expect(() => service.doSomething()).toThrow(/translated message/);
+  });
+});
+```
+
 ## License
 
 MIT License - See LICENSE file for details

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@digitaldefiance/i18n-lib",
-  "version": "3.7.5",
+  "version": "3.8.1",
   "description": "i18n library with enum translation support",
+  "homepage": "https://github.com/Digital-Defiance/i18n-lib/blob/main/README.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Digital-Defiance/i18n-lib.git"
+  },  
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "scripts": {
@@ -41,7 +46,10 @@
     "moment-timezone": "^0.6.0"
   },
   "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.48.0",
+    "@typescript-eslint/parser": "^8.48.0",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.4",
     "fast-check": "^4.3.0"
-  },
-  "type": "commonjs"
-}
+  }
+}

package/src/active-context.ts

@@ -0,0 +1,4 @@
+/**
+ * Re-export IActiveContext from interfaces directory for backwards compatibility
+ */
+export type { IActiveContext } from './interfaces/active-context.interface';

package/src/builders/i18n-builder.ts

@@ -0,0 +1,82 @@
+/**
+ * Fluent builder for I18n Engine
+ */
+
+import { I18nEngine } from '../core/i18n-engine';
+import { EngineConfig, LanguageDefinition } from '../interfaces';
+
+export class I18nBuilder {
+  private languages: LanguageDefinition[] = [];
+  private config: EngineConfig = {};
+  private instanceKey = 'default';
+  private registerInstance = true;
+  private setAsDefault = true;
+
+  private constructor() {}
+
+  static create(): I18nBuilder {
+    return new I18nBuilder();
+  }
+
+  withLanguages(languages: readonly LanguageDefinition[]): this {
+    this.languages = [...languages];
+    return this;
+  }
+
+  withDefaultLanguage(languageId: string): this {
+    this.config.defaultLanguage = languageId;
+    return this;
+  }
+
+  withFallbackLanguage(languageId: string): this {
+    this.config.fallbackLanguage = languageId;
+    return this;
+  }
+
+  withConstants(constants: Record<string, any>): this {
+    this.config.constants = constants;
+    return this;
+  }
+
+  withValidation(validation: EngineConfig['validation']): this {
+    this.config.validation = validation;
+    return this;
+  }
+
+  withInstanceKey(key: string): this {
+    this.instanceKey = key;
+    return this;
+  }
+
+  withRegisterInstance(register: boolean): this {
+    this.registerInstance = register;
+    return this;
+  }
+
+  withSetAsDefault(setDefault: boolean): this {
+    this.setAsDefault = setDefault;
+    return this;
+  }
+
+  isolated(): this {
+    this.registerInstance = false;
+    return this;
+  }
+
+  asDefault(): this {
+    this.setAsDefault = true;
+    return this;
+  }
+
+  build(): I18nEngine {
+    if (this.languages.length === 0) {
+      throw new Error('At least one language must be provided');
+    }
+
+    return new I18nEngine(this.languages, this.config, {
+      instanceKey: this.instanceKey,
+      registerInstance: this.registerInstance,
+      setAsDefault: this.setAsDefault,
+    });
+  }
+}

package/src/builders/{index.d.ts → index.ts}

@@ -1,5 +1,5 @@
 /**
  * Builder exports
  */
+
 export * from './i18n-builder';
-//# sourceMappingURL=index.d.ts.map

package/src/component-definition.ts

@@ -0,0 +1,11 @@
+/**
+ * Component definition with its string keys
+ */
+export interface ComponentDefinition<TStringKeys extends string> {
+  /** Unique identifier for the component */
+  readonly id: string;
+  /** Human-readable name for the component */
+  readonly name: string;
+  /** Array of all string keys this component requires */
+  readonly stringKeys: readonly TStringKeys[];
+}

package/src/component-registration.ts

@@ -0,0 +1,29 @@
+import { ComponentDefinition } from './component-definition';
+import { PartialComponentLanguageStrings } from './types';
+
+/**
+ * Registration payload for a component with its strings
+ */
+export interface ComponentRegistration<
+  TStringKeys extends string,
+  TLanguages extends string,
+> {
+  readonly component: ComponentDefinition<TStringKeys>;
+  readonly strings: PartialComponentLanguageStrings<TStringKeys, TLanguages>;
+  readonly enumName?: string;
+  readonly enumObject?: Record<string, TStringKeys>;
+  readonly aliases?: readonly string[];
+}
+
+/**
+ * Type utility to extract string keys from a component definition
+ */
+type ExtractStringKeys<T> = T extends ComponentDefinition<infer K> ? K : never;
+
+/**
+ * Type utility to create a strongly typed component registration
+ */
+export type CreateComponentRegistration<
+  TComponent extends ComponentDefinition<any>,
+  TLanguages extends string,
+> = ComponentRegistration<ExtractStringKeys<TComponent>, TLanguages>;