@digitaldefiance/i18n-lib 1.3.11 → 1.3.13

package/README.md

@@ -2274,6 +2274,14 @@ For issues, questions, or contributions:
 
 ## ChangeLog
 
+### Version 1.3.13
+
+- Migrate to es2022/nx monorepo
+
+### Version 1.3.12
+
+- Update typed-handleable to plugin i18n
+
 ### Version 1.3.11
 
 - Export i18nconfig

package/package.json

@@ -1,38 +1,23 @@
 {
   "name": "@digitaldefiance/i18n-lib",
-  "version": "1.3.11",
-  "description": "Generic i18n library with enum translation support",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "version": "1.3.13",
+  "description": "i18n library with enum translation support",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
   "scripts": {
-    "build": "yarn tsc",
-    "test": "yarn jest --detectOpenHandles",
-    "test:stream": "yarn jest --detectOpenHandles --runInBand --outputStyle=stream",
-    "lint": "eslint src/**/*.ts tests/**/*.ts",
-    "lint:fix": "eslint src/**/*.ts tests/**/*.ts --fix",
+    "build": "npx nx build digitaldefiance-i18n-lib",
+    "test": "npx nx test digitaldefiance-i18n-lib",
+    "lint": "npx nx lint digitaldefiance-i18n-lib",
+    "lint:fix": "npx nx lint digitaldefiance-i18n-lib --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",
+    "format": "npx nx format:write --projects=digitaldefiance-i18n-lib",
+    "format:check": "npx nx format:check --projects=digitaldefiance-i18n-lib",
+    "prepublishOnly": "npx nx build digitaldefiance-i18n-lib",
     "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",
+    "src",
     "README.md"
   ],
   "keywords": [

package/src/active-context.ts

@@ -0,0 +1,30 @@
+import { CurrencyCode } from './currency-code';
+import { Timezone } from './timezone';
+import { LanguageContextSpace } from './types';
+
+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: LanguageContextSpace;
+  /**
+   * The default timezone for the user facing application
+   */
+  timezone: Timezone;
+  /**
+   * The default timezone for the admin interface
+   */
+  adminTimezone: Timezone;
+}

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,13 @@
+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>;
+}

package/src/component-registry.ts

@@ -0,0 +1,392 @@
+/**
+ * Component registry for managing internationalization components and their string translations
+ */
+
+import { ComponentDefinition } from './component-definition';
+import { ComponentRegistration } from './component-registration';
+import { RegistryError } from './registry-error';
+import { RegistryErrorType } from './registry-error-type';
+import { TranslationRequest } from './translation-request';
+import { TranslationResponse } from './translation-response';
+import {
+  ComponentLanguageStrings,
+  ComponentStrings,
+  PartialComponentLanguageStrings,
+  PartialComponentStrings,
+} from './types';
+import { isTemplate, replaceVariables } from './utils';
+import { ValidationConfig } from './validation-config';
+import { ValidationResult } from './validation-result';
+
+/**
+ * Registry for managing components and their translations
+ */
+export class ComponentRegistry<TLanguages extends string> {
+  private readonly components = new Map<string, ComponentDefinition<any>>();
+  private readonly componentStrings = new Map<
+    string,
+    ComponentLanguageStrings<any, TLanguages>
+  >();
+  private readonly validationConfig: ValidationConfig;
+  private readonly registeredLanguages: Set<TLanguages>;
+
+  constructor(
+    languages: readonly TLanguages[],
+    validationConfig: ValidationConfig,
+  ) {
+    this.registeredLanguages = new Set(languages);
+    this.validationConfig = validationConfig;
+  }
+
+  /**
+   * Update the set of registered languages (for dynamic language addition)
+   */
+  public updateRegisteredLanguages(languages: readonly TLanguages[]): void {
+    this.registeredLanguages.clear();
+    languages.forEach((lang) => this.registeredLanguages.add(lang));
+  }
+
+  /**
+   * Register a new component with its translations
+   */
+  public registerComponent<TStringKeys extends string>(
+    registration: ComponentRegistration<TStringKeys, TLanguages>,
+  ): ValidationResult {
+    const { component, strings } = registration;
+
+    // Check for duplicate component
+    if (this.components.has(component.id)) {
+      throw RegistryError.createSimple(
+        RegistryErrorType.DuplicateComponent,
+        `Component '${component.id}' is already registered`,
+        { componentId: component.id },
+      );
+    }
+
+    // Validate the registration
+    const validationResult = this.validateComponentRegistration(registration);
+
+    if (
+      !validationResult.isValid &&
+      !this.validationConfig.allowPartialRegistration
+    ) {
+      throw RegistryError.createSimple(
+        RegistryErrorType.ValidationFailed,
+        `Component registration validation failed: ${validationResult.errors.join(
+          ', ',
+        )}`,
+        {
+          componentId: component.id,
+          missingKeys: validationResult.missingKeys,
+          errors: validationResult.errors,
+        },
+      );
+    }
+
+    // Complete missing strings with fallbacks if partial registration is allowed
+    const completeStrings = this.completeStringsWithFallbacks(
+      component,
+      strings,
+    );
+
+    // Register the component
+    this.components.set(component.id, component);
+    this.componentStrings.set(component.id, completeStrings);
+
+    return validationResult;
+  }
+
+  /**
+   * Update strings for an existing component
+   */
+  public updateComponentStrings<TStringKeys extends string>(
+    componentId: string,
+    strings: PartialComponentLanguageStrings<TStringKeys, TLanguages>,
+  ): ValidationResult {
+    const component = this.components.get(componentId);
+    if (!component) {
+      throw RegistryError.createSimple(
+        RegistryErrorType.ComponentNotFound,
+        `Component with ID '${componentId}' not found`,
+        { componentId },
+      );
+    }
+
+    const registration: ComponentRegistration<TStringKeys, TLanguages> = {
+      component: component as ComponentDefinition<TStringKeys>,
+      strings,
+    };
+
+    const validationResult = this.validateComponentRegistration(registration);
+
+    if (
+      validationResult.isValid ||
+      this.validationConfig.allowPartialRegistration
+    ) {
+      const existingStrings =
+        this.componentStrings.get(componentId) ||
+        ({} as ComponentLanguageStrings<TStringKeys, TLanguages>);
+      const updatedStrings = this.mergeStrings(existingStrings, strings);
+      const completeStrings = this.completeStringsWithFallbacks(
+        component,
+        updatedStrings,
+      );
+
+      this.componentStrings.set(componentId, completeStrings);
+    }
+
+    return validationResult;
+  }
+
+  /**
+   * Get a translation for a specific component, string key, and language
+   */
+  public getTranslation<TStringKeys extends string>(
+    request: TranslationRequest<TStringKeys, TLanguages>,
+  ): TranslationResponse {
+    const { componentId, stringKey, language, variables } = request;
+
+    // Check if component exists
+    if (!this.components.has(componentId)) {
+      throw RegistryError.createSimple(
+        RegistryErrorType.ComponentNotFound,
+        `Component '${componentId}' not found`,
+        { componentId },
+      );
+    }
+
+    const componentStrings = this.componentStrings.get(componentId);
+    if (!componentStrings) {
+      throw RegistryError.createSimple(
+        RegistryErrorType.StringKeyNotFound,
+        `No strings registered for component '${componentId}'`,
+        { componentId },
+      );
+    }
+
+    const targetLanguage =
+      language || (this.validationConfig.fallbackLanguageId as TLanguages);
+    let actualLanguage = targetLanguage;
+    let wasFallback = false;
+
+    // Try to get the string in the requested language
+    let languageStrings = componentStrings[targetLanguage];
+
+    // If not found and different from fallback, try fallback language
+    if (
+      !languageStrings &&
+      targetLanguage !== this.validationConfig.fallbackLanguageId
+    ) {
+      languageStrings =
+        componentStrings[
+          this.validationConfig.fallbackLanguageId as TLanguages
+        ];
+      actualLanguage = this.validationConfig.fallbackLanguageId as TLanguages;
+      wasFallback = true;
+    }
+
+    if (!languageStrings) {
+      throw RegistryError.createSimple(
+        RegistryErrorType.LanguageNotFound,
+        `No strings found for language '${targetLanguage}' in component '${componentId}'`,
+        { componentId, language: targetLanguage },
+      );
+    }
+
+    const translation = languageStrings[stringKey];
+    if (!translation) {
+      throw RegistryError.createSimple(
+        RegistryErrorType.StringKeyNotFound,
+        `String key '${stringKey}' not found for component '${componentId}' in language '${actualLanguage}'`,
+        { componentId, stringKey, language: actualLanguage },
+      );
+    }
+
+    // Process variables if the string key indicates it's a template
+    let processedTranslation: string = translation;
+    if (variables && isTemplate(stringKey)) {
+      processedTranslation = replaceVariables(translation, variables);
+    }
+
+    return {
+      translation: processedTranslation,
+      actualLanguage,
+      wasFallback,
+    };
+  }
+
+  /**
+   * Get all registered components
+   */
+  public getComponents(): ReadonlyArray<ComponentDefinition<any>> {
+    return Array.from(this.components.values());
+  }
+
+  /**
+   * Get a specific component by ID
+   */
+  public getComponent<TStringKeys extends string>(
+    componentId: string,
+  ): ComponentDefinition<TStringKeys> | undefined {
+    return this.components.get(componentId) as
+      | ComponentDefinition<TStringKeys>
+      | undefined;
+  }
+
+  /**
+   * Check if a component is registered
+   */
+  public hasComponent(componentId: string): boolean {
+    return this.components.has(componentId);
+  }
+
+  /**
+   * Get all strings for a component in all languages
+   */
+  public getComponentStrings<TStringKeys extends string>(
+    componentId: string,
+  ): ComponentLanguageStrings<TStringKeys, TLanguages> | undefined {
+    return this.componentStrings.get(componentId) as
+      | ComponentLanguageStrings<TStringKeys, TLanguages>
+      | undefined;
+  }
+
+  /**
+   * Validate a component registration
+   */
+  private validateComponentRegistration<TStringKeys extends string>(
+    registration: ComponentRegistration<TStringKeys, TLanguages>,
+  ): ValidationResult {
+    const { component, strings } = registration;
+    const missingKeys: Array<{
+      languageId: string;
+      componentId: string;
+      stringKey: string;
+    }> = [];
+    const errors: string[] = [];
+
+    // Check if all required string keys are provided for each language
+    for (const languageId of this.registeredLanguages) {
+      const languageStrings = strings[languageId];
+
+      if (!languageStrings) {
+        if (this.validationConfig.requireCompleteStrings) {
+          errors.push(
+            `Missing all strings for language '${languageId}' in component '${component.id}'`,
+          );
+        }
+        // Add all missing keys for this language
+        for (const stringKey of component.stringKeys) {
+          missingKeys.push({
+            languageId,
+            componentId: component.id,
+            stringKey,
+          });
+        }
+        continue;
+      }
+
+      // Check individual string keys
+      for (const stringKey of component.stringKeys) {
+        if (!languageStrings[stringKey]) {
+          missingKeys.push({
+            languageId,
+            componentId: component.id,
+            stringKey,
+          });
+
+          if (this.validationConfig.requireCompleteStrings) {
+            errors.push(
+              `Missing string key '${stringKey}' for language '${languageId}' in component '${component.id}'`,
+            );
+          }
+        }
+      }
+    }
+
+    return {
+      isValid: missingKeys.length === 0,
+      missingKeys,
+      errors,
+    };
+  }
+
+  /**
+   * Complete missing strings with fallbacks
+   */
+  private completeStringsWithFallbacks<TStringKeys extends string>(
+    component: ComponentDefinition<TStringKeys>,
+    strings: PartialComponentLanguageStrings<TStringKeys, TLanguages>,
+  ): ComponentLanguageStrings<TStringKeys, TLanguages> {
+    const result: { [L in TLanguages]: ComponentStrings<TStringKeys> } =
+      {} as any;
+    const fallbackLanguage = this.validationConfig
+      .fallbackLanguageId as TLanguages;
+    const fallbackStrings = strings[fallbackLanguage];
+
+    // Ensure all languages have all required keys
+    for (const languageId of this.registeredLanguages) {
+      const existingLanguageStrings =
+        strings[languageId] || ({} as PartialComponentStrings<TStringKeys>);
+      const languageStrings: { [K in TStringKeys]: string } = {} as any;
+
+      for (const stringKey of component.stringKeys) {
+        if (existingLanguageStrings[stringKey]) {
+          languageStrings[stringKey] = existingLanguageStrings[stringKey]!;
+        } else if (fallbackStrings && fallbackStrings[stringKey]) {
+          // Try to use fallback language
+          languageStrings[stringKey] = fallbackStrings[stringKey]!;
+        } else {
+          // Last resort: use a placeholder
+          languageStrings[stringKey] = `[${component.id}.${stringKey}]`;
+        }
+      }
+
+      result[languageId] = languageStrings;
+    }
+
+    return result;
+  }
+
+  /**
+   * Merge existing strings with new strings
+   */
+  private mergeStrings<TStringKeys extends string>(
+    existing: ComponentLanguageStrings<TStringKeys, TLanguages>,
+    updates: PartialComponentLanguageStrings<TStringKeys, TLanguages>,
+  ): PartialComponentLanguageStrings<TStringKeys, TLanguages> {
+    const result: { [L in TLanguages]?: PartialComponentStrings<TStringKeys> } =
+      {};
+
+    // Copy existing strings
+    for (const [languageId, languageStrings] of Object.entries(existing) as [
+      TLanguages,
+      ComponentStrings<TStringKeys>,
+    ][]) {
+      result[languageId] = { ...languageStrings };
+    }
+
+    // Apply updates
+    for (const [languageId, languageStrings] of Object.entries(updates) as [
+      TLanguages,
+      PartialComponentStrings<TStringKeys> | undefined,
+    ][]) {
+      if (languageStrings) {
+        result[languageId] = {
+          ...result[languageId],
+          ...languageStrings,
+        };
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Clear all components and their strings (useful for testing)
+   */
+  public clearAllComponents(): void {
+    this.components.clear();
+    this.componentStrings.clear();
+  }
+}

package/src/context-error-type.ts

@@ -0,0 +1,3 @@
+export enum ContextErrorType {
+  InvalidContext = 'InvalidContext',
+}

package/src/context-error.ts

@@ -0,0 +1,16 @@
+import { ContextErrorType } from './context-error-type';
+
+export class ContextError extends Error {
+  public readonly type: ContextErrorType;
+  public readonly contextKey?: string;
+
+  constructor(type: ContextErrorType, contextKey?: string) {
+    const message = contextKey 
+      ? `Invalid context: ${contextKey}`
+      : 'Invalid context';
+    super(message);
+    this.name = 'ContextError';
+    this.type = type;
+    this.contextKey = contextKey;
+  }
+}

package/src/context-manager.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 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
+   */
+  public addListener(listener: ContextChangeListener): void {
+    this.listeners.push(listener);
+  }
+
+  /**
+   * Removes a listener from the notification list.
+   * @param listener - The listener function to remove
+   */
+  public removeListener(listener: ContextChangeListener): void {
+    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
+   */
+  public notifyChange<K extends keyof TContext>(
+    property: K,
+    oldValue: TContext[K],
+    newValue: TContext[K],
+  ): void {
+    this.listeners.forEach((listener) => {
+      try {
+        listener(property as string, 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
+   */
+  public createProxy(context: TContext): TContext {
+    const manager = this;
+    return new Proxy(context, {
+      set(target, property, value) {
+        const oldValue = target[property as keyof TContext];
+        target[property as keyof TContext] = value;
+        manager.notifyChange(property as keyof TContext, oldValue, value);
+        return true;
+      },
+    });
+  }
+}

package/src/context.ts

@@ -0,0 +1,90 @@
+import { CurrencyCode } from './currency-code';
+import { I18nContext } from './i18n-context';
+import { Timezone } from './timezone';
+import { LanguageContextSpace } from './types';
+
+/**
+ * Creates a new I18n context with default values.
+ * @param defaultLanguage - The default language for the context
+ * @param defaultContext - The default language context
+ * @param defaultCurrencyCode - The default currency code (defaults to USD)
+ * @param defaultTimezone - The default timezone (defaults to UTC)
+ * @param defaultAdminTimezone - The default admin timezone (defaults to UTC)
+ * @returns A new I18nContext instance
+ */
+export function createContext<TLanguage extends string>(
+  defaultLanguage: TLanguage,
+  defaultContext: LanguageContextSpace = 'admin',
+  defaultCurrencyCode: CurrencyCode = new CurrencyCode('USD'),
+  defaultTimezone: Timezone = new Timezone('UTC'),
+  defaultAdminTimezone: Timezone = new Timezone('UTC'),
+): I18nContext<TLanguage> {
+  return {
+    language: defaultLanguage,
+    adminLanguage: defaultLanguage,
+    currencyCode: defaultCurrencyCode,
+    currentContext: defaultContext,
+    timezone: defaultTimezone,
+    adminTimezone: defaultAdminTimezone,
+  };
+}
+
+/**
+ * Sets the language for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param language - The language to set
+ */
+export function setLanguage<TLanguage extends string>(
+  context: I18nContext<TLanguage>,
+  language: TLanguage,
+): void {
+  context.language = language;
+}
+
+/**
+ * Sets the admin language for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param language - The admin language to set
+ */
+export function setAdminLanguage<TLanguage extends string>(
+  context: I18nContext<TLanguage>,
+  language: TLanguage,
+): void {
+  context.adminLanguage = language;
+}
+
+/**
+ * Sets the current context for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param languageContext - The language context to set
+ */
+export function setContext<TLanguage extends string>(
+  context: I18nContext<TLanguage>,
+  languageContext: LanguageContextSpace,
+): void {
+  context.currentContext = languageContext;
+}
+
+/**
+ * Sets the timezone for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param timezone - The timezone to set
+ */
+export function setTimezone<TLanguage extends string>(
+  context: I18nContext<TLanguage>,
+  timezone: Timezone,
+): void {
+  context.timezone = timezone;
+}
+
+/**
+ * Sets the admin timezone for the given I18n context.
+ * @param context - The I18n context to modify
+ * @param timezone - The admin timezone to set
+ */
+export function setAdminTimezone<TLanguage extends string>(
+  context: I18nContext<TLanguage>,
+  timezone: Timezone,
+): void {
+  context.adminTimezone = timezone;
+}