@digitaldefiance/i18n-lib 3.8.1 → 3.8.3

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

@@ -1,260 +0,0 @@
-/**
- * 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

@@ -1,152 +0,0 @@
-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) }
-        : {}),
-    };
-  }
-}