@digitaldefiance/i18n-lib 3.8.0 → 3.8.2

package/src/errors/enhanced-error-base.ts

@@ -0,0 +1,260 @@
+/**
+ * Enhanced error base with i18n 3.0/3.5 feature support
+ * Provides helper methods for ICU MessageFormat, pluralization, gender, and advanced features
+ */
+
+import { formatICUMessage } from '../icu/helpers';
+import { PluralCategory } from '../pluralization/plural-categories';
+import { GenderCategory } from '../gender/gender-categories';
+
+/**
+ * Options for enhanced error message formatting
+ */
+export interface EnhancedErrorOptions {
+  /** Variables for ICU substitution */
+  variables?: Record<string, string | number | boolean>;
+  /** Language code for message formatting */
+  language?: string;
+  /** Count for plural formatting */
+  count?: number;
+  /** Gender for gender-aware formatting */
+  gender?: GenderCategory;
+  /** Additional metadata */
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Helper class providing advanced i18n features for error messages
+ * This can be used as a mixin or utility class for error classes
+ */
+export class EnhancedErrorHelper {
+  /**
+   * Format error message with ICU MessageFormat
+   * @param pattern - ICU message pattern
+   * @param options - Formatting options
+   * @returns Formatted message string
+   */
+  static formatMessage(
+    pattern: string,
+    options: EnhancedErrorOptions = {},
+  ): string {
+    const { variables = {}, language = 'en-US', count, gender } = options;
+    
+    // Add count and gender to variables if provided
+    const allVars = {
+      ...variables,
+      ...(count !== undefined ? { count } : {}),
+      ...(gender ? { gender } : {}),
+    };
+
+    return formatICUMessage(pattern, allVars, language);
+  }
+
+  /**
+   * Create a plural-aware error message
+   * @param singularPattern - Pattern for singular form
+   * @param pluralPattern - Pattern for plural form
+   * @param count - Count value
+   * @param options - Additional formatting options
+   * @returns Formatted message
+   */
+  static formatPlural(
+    singularPattern: string,
+    pluralPattern: string,
+    count: number,
+    options: Omit<EnhancedErrorOptions, 'count'> = {},
+  ): string {
+    const pattern = `{count, plural, one {${singularPattern}} other {${pluralPattern}}}`;
+    return this.formatMessage(pattern, { ...options, count });
+  }
+
+  /**
+   * Create a gender-aware error message
+   * @param patterns - Patterns for different genders
+   * @param gender - Gender value
+   * @param options - Additional formatting options
+   * @returns Formatted message
+   */
+  static formatGender(
+    patterns: Partial<Record<GenderCategory, string>>,
+    gender: GenderCategory,
+    options: Omit<EnhancedErrorOptions, 'gender'> = {},
+  ): string {
+    const { male, female, neutral, other } = patterns;
+    const selectPattern = `{gender, select, ${male ? `male {${male}}` : ''} ${female ? `female {${female}}` : ''} ${neutral ? `neutral {${neutral}}` : ''} other {${other || patterns.male || patterns.female || patterns.neutral || 'Error'}}}`;
+    return this.formatMessage(selectPattern, { ...options, gender });
+  }
+
+  /**
+   * Format ordinal numbers (1st, 2nd, 3rd, etc.)
+   * @param number - The number to format
+   * @param pattern - Pattern with {number} placeholder
+   * @param options - Additional formatting options
+   * @returns Formatted message with ordinal
+   */
+  static formatOrdinal(
+    number: number,
+    pattern: string,
+    options: EnhancedErrorOptions = {},
+  ): string {
+    const ordinalPattern = pattern.replace(
+      '{number}',
+      `{number, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}`
+    );
+    return this.formatMessage(ordinalPattern, {
+      ...options,
+      variables: { ...options.variables, number },
+    });
+  }
+
+  /**
+   * Format numbers with specific formatting (integer, currency, percent)
+   * @param value - Number value
+   * @param format - Format type
+   * @param pattern - Pattern with {value} placeholder
+   * @param options - Additional formatting options
+   * @returns Formatted message
+   */
+  static formatNumber(
+    value: number,
+    format: 'integer' | 'currency' | 'percent',
+    pattern: string,
+    options: EnhancedErrorOptions = {},
+  ): string {
+    const numberPattern = pattern.replace(
+      '{value}',
+      `{value, number, ${format}}`
+    );
+    return this.formatMessage(numberPattern, {
+      ...options,
+      variables: { ...options.variables, value },
+    });
+  }
+
+  /**
+   * Create nested messages with multiple levels of ICU formatting
+   * @param pattern - Complex nested ICU pattern
+   * @param options - Formatting options
+   * @returns Formatted message
+   */
+  static formatNested(
+    pattern: string,
+    options: EnhancedErrorOptions = {},
+  ): string {
+    return this.formatMessage(pattern, options);
+  }
+
+  /**
+   * Detect if a string key represents a nested path
+   * @param key - String key to check
+   * @returns Object with nesting information
+   */
+  static analyzeKeyPath(key: string): {
+    isNested: boolean;
+    depth: number;
+    parts: string[];
+  } {
+    const parts = key.split('.');
+    return {
+      isNested: parts.length > 1,
+      depth: parts.length,
+      parts,
+    };
+  }
+
+  /**
+   * Create metadata object with count information for debugging
+   * @param count - Count value
+   * @param additionalMetadata - Additional metadata to include
+   * @returns Metadata object
+   */
+  static createCountMetadata(
+    count: number,
+    additionalMetadata: Record<string, any> = {},
+  ): Record<string, any> {
+    return {
+      count,
+      ...additionalMetadata,
+    };
+  }
+
+  /**
+   * Validate that all required ICU variables are provided
+   * @param pattern - ICU pattern
+   * @param variables - Provided variables
+   * @returns Object with validation result
+   */
+  static validateVariables(
+    pattern: string,
+    variables: Record<string, any>,
+  ): { valid: boolean; missing: string[] } {
+    // Extract variable names from ICU pattern
+    const variableMatches = pattern.match(/\{([a-zA-Z_][a-zA-Z0-9_]*)/g);
+    if (!variableMatches) {
+      return { valid: true, missing: [] };
+    }
+
+    const required = variableMatches
+      .map(match => match.substring(1))
+      .filter((name, index, self) => self.indexOf(name) === index);
+
+    const missing = required.filter(name => !(name in variables));
+
+    return {
+      valid: missing.length === 0,
+      missing,
+    };
+  }
+}
+
+/**
+ * Mixin function to add enhanced i18n features to error classes
+ * @param Base - Base error class
+ * @returns Enhanced error class
+ */
+export function withEnhancedI18n<T extends new (...args: any[]) => Error>(
+  Base: T
+) {
+  return class extends Base {
+    public formatMessage(
+      pattern: string,
+      options: EnhancedErrorOptions = {},
+    ): string {
+      return EnhancedErrorHelper.formatMessage(pattern, options);
+    }
+
+    public formatPlural(
+      singularPattern: string,
+      pluralPattern: string,
+      count: number,
+      options: Omit<EnhancedErrorOptions, 'count'> = {},
+    ): string {
+      return EnhancedErrorHelper.formatPlural(singularPattern, pluralPattern, count, options);
+    }
+
+    public formatGender(
+      patterns: Partial<Record<GenderCategory, string>>,
+      gender: GenderCategory,
+      options: Omit<EnhancedErrorOptions, 'gender'> = {},
+    ): string {
+      return EnhancedErrorHelper.formatGender(patterns, gender, options);
+    }
+
+    public formatOrdinal(
+      number: number,
+      pattern: string,
+      options: EnhancedErrorOptions = {},
+    ): string {
+      return EnhancedErrorHelper.formatOrdinal(number, pattern, options);
+    }
+
+    public formatNumber(
+      value: number,
+      format: 'integer' | 'currency' | 'percent',
+      pattern: string,
+      options: EnhancedErrorOptions = {},
+    ): string {
+      return EnhancedErrorHelper.formatNumber(value, format, pattern, options);
+    }
+  };
+}

package/src/errors/handleable.ts

@@ -0,0 +1,152 @@
+import { IHandleable } from '../interfaces/handleable';
+import { HandleableErrorOptions } from '../interfaces/handleable-error-options';
+
+/**
+ * Extended Error constructor type that includes stack trace capture functionality.
+ */
+type ErrorConstructorWithStack = ErrorConstructor & {
+  captureStackTrace?: (target: Error, constructorOpt?: Function) => void;
+};
+
+/**
+ * Base error class that implements IHandleable interface with full i18n support.
+ * 
+ * Provides enhanced error handling capabilities including status codes, handled state tracking,
+ * and source data preservation. Fully compatible with all i18n features when used with
+ * translation strings.
+ * 
+ * **Supported i18n Features** (via translation strings in derived classes):
+ * - 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 patterns
+ * 
+ * **Usage Pattern:**
+ * ```typescript
+ * // Extend HandleableError with translated messages
+ * class MyHandleableError extends HandleableError {
+ *   constructor(componentId: string, stringKey: string, variables?: Record<string, any>) {
+ *     const engine = I18nEngine.getInstance();
+ *     const message = engine.translate(componentId, stringKey, variables);
+ *     const error = new Error(message);
+ *     super(error, { statusCode: 400 });
+ *   }
+ * }
+ * 
+ * // Register translation with ICU features
+ * engine.registerComponent({
+ *   component: { id: 'api', stringKeys: ['validationError'] },
+ *   strings: {
+ *     'en-US': {
+ *       validationError: \"{count, plural, one {# field is invalid} other {# fields are invalid}}\"
+ *     }
+ *   }
+ * });
+ * 
+ * // Use with i18n features
+ * throw new MyHandleableError('api', 'validationError', { count: 3 });
+ * // Result: \"3 fields are invalid\"
+ * ```
+ */
+export class HandleableError extends Error implements IHandleable {
+  /** The original error that caused this error */
+  public override readonly cause?: Error;
+  /** HTTP status code associated with this error */
+  public readonly statusCode: number;
+  /** Optional source data related to the error */
+  public readonly sourceData?: unknown;
+  /** Internal tracking of whether this error has been handled */
+  private _handled: boolean;
+
+  /**
+   * Creates a new HandleableError instance.
+   * @param source - The original error being wrapped
+   * @param options - Optional configuration for the error
+   */
+  constructor(source: Error, options?: HandleableErrorOptions) {
+    super(source.message);
+    this.name = this.constructor.name;
+    this.cause = options?.cause ?? source;
+    this.statusCode = options?.statusCode ?? 500;
+    this._handled = options?.handled ?? false;
+    this.sourceData = options?.sourceData;
+    this.name = 'HandleableError';
+
+    // Capture stack trace - prioritize source stack, then capture new one
+    if (source.stack) {
+      this.stack = source.stack;
+    } else if ((Error as ErrorConstructorWithStack).captureStackTrace) {
+      (Error as ErrorConstructorWithStack).captureStackTrace?.(
+        this,
+        this.constructor,
+      );
+    } else {
+      this.stack = new Error().stack;
+    }
+  }
+
+  /**
+   * Gets the handled state of this error.
+   * @returns True if the error has been handled, false otherwise
+   */
+  public get handled(): boolean {
+    return this._handled;
+  }
+
+  /**
+   * Sets the handled state of this error.
+   * @param value - The new handled state
+   */
+  public set handled(value: boolean) {
+    this._handled = value;
+  }
+
+  /**
+   * Serializes a value to a JSON-compatible format.
+   * Handles objects with toJSON methods, Error instances, arrays, and plain objects.
+   * @param value - The value to serialize
+   * @returns The serialized value
+   */
+  private serializeValue(value: unknown): unknown {
+    if (
+      value &&
+      typeof value === 'object' &&
+      'toJSON' in value &&
+      typeof value.toJSON === 'function'
+    ) {
+      return value.toJSON();
+    }
+    if (value instanceof Error) {
+      return value.message;
+    }
+    if (Array.isArray(value)) {
+      return value.map((item) => this.serializeValue(item));
+    }
+    if (value && typeof value === 'object') {
+      return Object.fromEntries(
+        Object.entries(value).map(([k, v]) => [k, this.serializeValue(v)]),
+      );
+    }
+    return value;
+  }
+
+  /**
+   * Converts the error to a JSON-serializable object.
+   * Includes name, message, status code, handled state, stack trace, and optional source data.
+   * @returns A plain object representation of the error
+   */
+  public toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      message: this.message,
+      statusCode: this.statusCode,
+      handled: this.handled,
+      stack: this.stack,
+      cause: this.serializeValue(this.cause),
+      ...(this.sourceData
+        ? { sourceData: this.serializeValue(this.sourceData) }
+        : {}),
+    };
+  }
+}