@digitaldefiance/i18n-lib 3.7.5 → 3.8.1

package/src/errors/translatable-generic.ts

@@ -0,0 +1,245 @@
+import { I18nEngine } from '../core/i18n-engine';
+import { GenderCategory } from '../gender/gender-categories';
+
+/**
+ * Generic translatable error that works with any plugin engine and component.
+ *
+ * Uses lazy initialization to avoid circular dependencies with core modules.
+ * The I18nEngine is only accessed when the error is constructed, not at module load time.
+ *
+ * **Full i18n 3.0/3.5 Feature Support:**
+ * - ICU MessageFormat (all formatters: plural, select, selectordinal)
+ * - Pluralization for 37 languages with CLDR rules
+ * - Gender-aware translations (male, female, neutral, other)
+ * - Number formatting (integer, currency, percent)
+ * - Date/Time formatting (short, medium, long, full)
+ * - Nested messages up to 4 levels deep
+ * - Context variable injection
+ *
+ * **Usage Examples:**
+ * ```typescript
+ * // Plural-aware error
+ * new TranslatableGenericError('component', 'errorKey', { count: 5 });
+ * // Translation: \"{count, plural, one {# error} other {# errors}}\"
+ *
+ * // Gender-aware error
+ * new TranslatableGenericError('component', 'userError', { gender: 'female', name: 'Alice' });
+ * // Translation: \"{gender, select, male {He} female {She}} {name} caused an error\"
+ *
+ * // Number formatting
+ * new TranslatableGenericError('component', 'thresholdError', { value: 1500.50, limit: 1000 });
+ * // Translation: \"Value {value, number, currency} exceeds {limit, number, currency}\"
+ *
+ * // SelectOrdinal
+ * new TranslatableGenericError('component', 'stepError', { step: 3 });
+ * // Translation: \"Failed at {step, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} step\"
+ * ```
+ */
+export class TranslatableGenericError<
+  TStringKey extends string = string,
+> extends Error {
+  public readonly stringKey: TStringKey;
+  public override readonly componentId: string;
+  public readonly language?: string;
+  public readonly variables?: Record<string, string | number>;
+  public override readonly metadata?: Record<string, any>;
+
+  /**
+   * Create a translatable error
+   * @param componentId - The component ID to translate from
+   * @param stringKey - The translation key
+   * @param variables - Variables for interpolation
+   * @param language - Optional language override
+   * @param metadata - Additional error metadata
+   * @param instanceKey - Optional engine instance key
+   */
+  constructor(
+    componentId: string,
+    stringKey: TStringKey,
+    variables?: Record<string, string | number>,
+    language?: string,
+    metadata?: Record<string, any>,
+    instanceKey?: string,
+  ) {
+    // Lazy initialization: getInstance() is only called when error is constructed
+    let translatedMessage: string;
+    try {
+      const engine = I18nEngine.getInstance(instanceKey);
+      translatedMessage = engine.safeTranslate(
+        componentId,
+        stringKey,
+        variables,
+        language,
+      );
+    } catch (error) {
+      // Fallback if engine not found - TranslatableGenericError is designed to be flexible
+      translatedMessage = `[${componentId}.${stringKey}]`;
+    }
+
+    super(translatedMessage);
+    this.name = 'TranslatableGenericError';
+    this.stringKey = stringKey;
+    this.componentId = componentId;
+    this.language = language;
+    this.variables = variables;
+    this.metadata = metadata;
+  }
+
+  /**
+   * Create error with explicit engine instance
+   */
+  static withEngine<TStringKey extends string>(
+    engine: I18nEngine,
+    componentId: string,
+    stringKey: TStringKey,
+    variables?: Record<string, string | number>,
+    language?: string,
+    metadata?: Record<string, any>,
+  ): TranslatableGenericError<TStringKey> {
+    const translatedMessage = engine.safeTranslate(
+      componentId,
+      stringKey,
+      variables,
+      language,
+    );
+
+    const error = Object.create(TranslatableGenericError.prototype);
+    Error.call(error, translatedMessage);
+    error.name = 'TranslatableGenericError';
+    error.stringKey = stringKey;
+    error.componentId = componentId;
+    error.language = language;
+    error.variables = variables;
+    error.metadata = metadata;
+    error.message = translatedMessage;
+
+    return error;
+  }
+
+  /**
+   * Retranslate the error message in a different language
+   */
+  retranslate(language: string, instanceKey?: string): string {
+    try {
+      const engine = I18nEngine.getInstance(instanceKey);
+      return engine.safeTranslate(
+        this.componentId,
+        this.stringKey,
+        this.variables,
+        language,
+      );
+    } catch (error) {
+      // Fallback if engine not found
+      return `[${this.componentId}.${this.stringKey}]`;
+    }
+  }
+
+  /**
+   * Create error with plural count
+   * Translation string should use ICU plural format
+   */
+  static withCount<TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    count: number,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+    instanceKey?: string,
+  ): TranslatableGenericError<TStringKey> {
+    return new TranslatableGenericError(
+      componentId,
+      stringKey,
+      { ...otherVars, count },
+      language,
+      undefined,
+      instanceKey,
+    );
+  }
+
+  /**
+   * Create error with gender context
+   * Translation string should use ICU select format
+   */
+  static withGender<TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    gender: GenderCategory,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+    instanceKey?: string,
+  ): TranslatableGenericError<TStringKey> {
+    return new TranslatableGenericError(
+      componentId,
+      stringKey,
+      { ...otherVars, gender },
+      language,
+      undefined,
+      instanceKey,
+    );
+  }
+
+  /**
+   * Create error with ordinal number
+   * Translation string should use ICU selectordinal format
+   */
+  static withOrdinal<TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    ordinalNumber: number,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+    instanceKey?: string,
+  ): TranslatableGenericError<TStringKey> {
+    return new TranslatableGenericError(
+      componentId,
+      stringKey,
+      { ...otherVars, ordinalNumber },
+      language,
+      undefined,
+      instanceKey,
+    );
+  }
+
+  /**
+   * Create error with number formatting
+   * Translation string should use ICU number format
+   */
+  static withNumberFormat<TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    value: number,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+    instanceKey?: string,
+  ): TranslatableGenericError<TStringKey> {
+    return new TranslatableGenericError(
+      componentId,
+      stringKey,
+      { ...otherVars, value },
+      language,
+      undefined,
+      instanceKey,
+    );
+  }
+
+  /**
+   * Create error with multiple i18n features combined
+   * Translation string can use nested ICU messages
+   */
+  static withMultipleFeatures<TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    features: Record<string, string | number>,
+    language?: string,
+    instanceKey?: string,
+  ): TranslatableGenericError<TStringKey> {
+    return new TranslatableGenericError(
+      componentId,
+      stringKey,
+      features,
+      language,
+      undefined,
+      instanceKey,
+    );
+  }
+}

package/src/errors/translatable-handleable-generic.ts

@@ -0,0 +1,222 @@
+import { IHandleable } from '../interfaces/handleable';
+import { TranslatableGenericError } from './translatable-generic';
+import { PluralCategory } from '../pluralization/plural-categories';
+import { GenderCategory } from '../gender/gender-categories';
+
+/**
+ * Generic translatable handleable error with full i18n feature support.
+ * 
+ * Combines translation capabilities with handleable error patterns and provides
+ * static factory methods for all i18n features.
+ * 
+ * **Supported i18n Features:**
+ * - ICU MessageFormat: plural, select, selectordinal
+ * - Pluralization: 37 languages with CLDR rules
+ * - Gender support: male, female, neutral, other
+ * - Number formatting: integer, currency, percent
+ * - Nested messages: complex multi-level patterns
+ * 
+ * **Usage Examples:**
+ * ```typescript
+ * // Pluralization with handleable options
+ * throw TranslatableHandleableGenericError.withCount(
+ *   'api', 'validationError', 5,
+ *   {}, 'en-US', 'default',
+ *   { statusCode: 400 }
+ * );
+ * 
+ * // Gender-aware messages
+ * throw TranslatableHandleableGenericError.withGender(
+ *   'user', 'accountError', 'female',
+ *   {}, 'en-US', 'default',
+ *   { statusCode: 403 }
+ * );
+ * 
+ * // Number formatting with error handling
+ * throw TranslatableHandleableGenericError.withNumberFormat(
+ *   'payment', 'amountExceeded', 1599.99,
+ *   { limit: 1000 }, 'en-US', 'default',
+ *   { statusCode: 402 }
+ * );
+ * 
+ * // Ordinal formatting (1st, 2nd, 3rd)
+ * throw TranslatableHandleableGenericError.withOrdinal(
+ *   'workflow', 'stepFailed', 3,
+ *   {}, 'en-US', 'default',
+ *   { statusCode: 500, retryable: true }
+ * );
+ * ```
+ */
+export class TranslatableHandleableGenericError<
+    TStringKey extends string = string,
+  >
+  extends TranslatableGenericError<TStringKey>
+  implements IHandleable
+{
+  private _handled = false;
+  public override readonly cause?: Error;
+  public readonly statusCode: number;
+  public readonly sourceData?: unknown;
+
+  /**
+   * Create a translatable error
+   * @param componentId - The component ID to translate from
+   * @param stringKey - The translation key
+   * @param variables - Variables for interpolation
+   * @param language - Optional language override
+   * @param metadata - Additional error metadata
+   * @param instanceKey - Optional engine instance key
+   */
+  constructor(
+    componentId: string,
+    stringKey: TStringKey,
+    variables?: Record<string, string | number>,
+    language?: string,
+    metadata?: Record<string, any>,
+    instanceKey?: string,
+    handleableOptions?: {
+      statusCode?: number;
+      cause?: Error;
+      sourceData?: unknown;
+    },
+  ) {
+    super(componentId, stringKey, variables, language, metadata, instanceKey);
+    this.statusCode = handleableOptions?.statusCode ?? 500;
+    this.cause = handleableOptions?.cause;
+    this.sourceData = handleableOptions?.sourceData;
+    this.name = 'TranslatableHandleableGenericError';
+  }
+  public get handled(): boolean {
+    return this._handled;
+  }
+  public set handled(value: boolean) {
+    this._handled = value;
+  }
+  toJSON(): Record<string, unknown> {
+    return {
+      statusCode: this.statusCode,
+      message: this.message,
+      cause: this.cause,
+      sourceData: this.sourceData,
+    };
+  }
+
+  /**
+   * Create error with pluralization support
+   * Translation string should include: "{count, plural, one {...} other {...}}"
+   */
+  static override withCount<TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    count: number,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+    instanceKey?: string,
+    handleableOptions?: { statusCode?: number; cause?: Error; sourceData?: unknown },
+  ): TranslatableHandleableGenericError<TStringKey> {
+    return new TranslatableHandleableGenericError(
+      componentId,
+      stringKey,
+      { count, ...otherVars },
+      language,
+      undefined,
+      instanceKey,
+      handleableOptions,
+    );
+  }
+
+  /**
+   * Create error with gender-aware messages
+   * Translation string should include: "{gender, select, male {...} female {...} other {...}}"
+   */
+  static override withGender<TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    gender: GenderCategory,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+    instanceKey?: string,
+    handleableOptions?: { statusCode?: number; cause?: Error; sourceData?: unknown },
+  ): TranslatableHandleableGenericError<TStringKey> {
+    return new TranslatableHandleableGenericError(
+      componentId,
+      stringKey,
+      { gender, ...otherVars },
+      language,
+      undefined,
+      instanceKey,
+      handleableOptions,
+    );
+  }
+
+  /**
+   * Create error with ordinal formatting (1st, 2nd, 3rd)
+   * Translation string should include: "{number, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}"
+   */
+  static override withOrdinal<TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    ordinalNumber: number,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+    instanceKey?: string,
+    handleableOptions?: { statusCode?: number; cause?: Error; sourceData?: unknown },
+  ): TranslatableHandleableGenericError<TStringKey> {
+    return new TranslatableHandleableGenericError(
+      componentId,
+      stringKey,
+      { number: ordinalNumber, ...otherVars },
+      language,
+      undefined,
+      instanceKey,
+      handleableOptions,
+    );
+  }
+
+  /**
+   * Create error with number formatting (currency, percent, integer)
+   * Translation string should include: "{value, number, integer}" or "{amount, number, currency}"
+   */
+  static override withNumberFormat<TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    value: number,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+    instanceKey?: string,
+    handleableOptions?: { statusCode?: number; cause?: Error; sourceData?: unknown },
+  ): TranslatableHandleableGenericError<TStringKey> {
+    return new TranslatableHandleableGenericError(
+      componentId,
+      stringKey,
+      { value, ...otherVars },
+      language,
+      undefined,
+      instanceKey,
+      handleableOptions,
+    );
+  }
+
+  /**
+   * Create error with multiple i18n features combined
+   * Translation string can combine: plural, select, number formatting, etc.
+   */
+  static override withMultipleFeatures<TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    features: Record<string, string | number>,
+    language?: string,
+    instanceKey?: string,
+    handleableOptions?: { statusCode?: number; cause?: Error; sourceData?: unknown },
+  ): TranslatableHandleableGenericError<TStringKey> {
+    return new TranslatableHandleableGenericError(
+      componentId,
+      stringKey,
+      features,
+      language,
+      undefined,
+      instanceKey,
+      handleableOptions,
+    );
+  }
+}

package/src/errors/translatable.ts

@@ -0,0 +1,138 @@
+import { I18nEngine } from '../core/i18n-engine';
+import { GenderCategory } from '../gender/gender-categories';
+
+/**
+ * Translatable error class with full i18n 3.0/3.5 feature support.
+ *
+ * Uses lazy initialization to avoid circular dependencies with core modules.
+ * The I18nEngine is only accessed when the error is constructed, not at module load time.
+ * If the i18n engine is not initialized, falls back to displaying the raw key.
+ *
+ * **Supported Features:**
+ * - ICU MessageFormat (variables, plural, select, selectordinal)
+ * - Pluralization (37 languages, CLDR rules)
+ * - Gender-aware translations
+ * - Number formatting (integer, currency, percent)
+ * - Date/Time formatting
+ * - Nested messages (4 levels deep)
+ * - Context variables
+ *
+ * **Translation String Examples:**
+ * ```typescript
+ * // ICU plural
+ * "{count, plural, one {# error occurred} other {# errors occurred}}"
+ *
+ * // ICU select + gender
+ * "{gender, select, male {He encountered} female {She encountered}} an error"
+ *
+ * // Number formatting
+ * "Threshold {limit, number, integer} exceeded by {value, number, percent}"
+ *
+ * // SelectOrdinal
+ * "Failed at {step, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} step"
+ *
+ * // Nested messages
+ * "{severity, select, low {Minor: {count, plural, one {# issue} other {# issues}}} high {Critical error}}"
+ * ```
+ */
+export class TranslatableError<
+  TStringKey extends string = string,
+> extends Error {
+  public override readonly componentId: string;
+  public readonly stringKey: TStringKey;
+  public readonly variables?: Record<string, string | number>;
+  public readonly language?: string;
+
+  constructor(
+    componentId: string,
+    stringKey: TStringKey,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+  ) {
+    // Lazy initialization: getInstance() is only called when error is constructed, not at module load
+    const engine = I18nEngine.getInstance('default');
+    super(engine.safeTranslate(componentId, stringKey, otherVars, language));
+    this.name = 'TranslatableError';
+    this.componentId = componentId;
+    this.stringKey = stringKey;
+    this.variables = otherVars;
+    this.language = language;
+    Object.setPrototypeOf(this, TranslatableError.prototype);
+  }
+
+  /**
+   * Create error with plural count
+   * Translation string should use: {count, plural, one {...} other {...}}
+   */
+  static withCount<TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    count: number,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+  ): TranslatableError<TStringKey> {
+    return new TranslatableError(
+      componentId,
+      stringKey,
+      { count, ...otherVars },
+      language,
+    );
+  }
+
+  /**
+   * Create error with gender context
+   * Translation string should use: {gender, select, male {...} female {...} other {...}}
+   */
+  static withGender<TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    gender: GenderCategory,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+  ): TranslatableError<TStringKey> {
+    return new TranslatableError(
+      componentId,
+      stringKey,
+      { gender, ...otherVars },
+      language,
+    );
+  }
+
+  /**
+   * Create error with ordinal number
+   * Translation string should use: {number, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}
+   */
+  static withOrdinal<TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    number: number,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+  ): TranslatableError<TStringKey> {
+    return new TranslatableError(
+      componentId,
+      stringKey,
+      { number, ...otherVars },
+      language,
+    );
+  }
+
+  /**
+   * Create error with formatted number
+   * Translation string should use: {value, number, integer|currency|percent}
+   */
+  static withNumber<TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    value: number,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+  ): TranslatableError<TStringKey> {
+    return new TranslatableError(
+      componentId,
+      stringKey,
+      { value, ...otherVars },
+      language,
+    );
+  }
+}