@digitaldefiance/i18n-lib 3.8.0 → 3.8.2

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

@@ -1754,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.8.0",
+  "version": "3.8.2",
   "description": "i18n library with enum translation support",
+  "homepage": "https://github.com/Digital-Defiance/i18n-lib",
+  "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.d.ts → active-context.ts}

@@ -2,4 +2,3 @@
  * Re-export IActiveContext from interfaces directory for backwards compatibility
  */
 export type { IActiveContext } from './interfaces/active-context.interface';
-//# sourceMappingURL=active-context.d.ts.map

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>;