@digitaldefiance/i18n-lib 3.8.2 → 3.8.4

package/src/types/engine.ts

@@ -1,55 +0,0 @@
-/**
- * I18n Engine type definitions
- *
- * This file provides type-safe interfaces for i18n engine implementations.
- */
-
-/**
- * Generic I18n Engine interface with type-safe string key constraints
- *
- * This interface defines the core methods that any i18n engine implementation
- * should provide, with proper generic constraints for string keys.
- *
- * @template TStringKeys - Union type of valid string keys for translation
- */
-export interface II18nEngine<TStringKeys extends string = string> {
-  /**
-   * Translate a string key with optional variables
-   * @param key - The translation key
-   * @param params - Optional parameters for interpolation
-   * @returns The translated string
-   */
-  translate(key: TStringKeys, params?: Record<string, unknown>): string;
-
-  /**
-   * Translate an enum value to a string
-   * @template T - The enum type
-   * @param enumObj - The enum object
-   * @param value - The enum value to translate
-   * @param language - Optional language override
-   * @returns The translated enum value
-   */
-  translateEnum<T extends Record<string, string | number>>(
-    enumObj: T,
-    value: T[keyof T],
-    language?: string,
-  ): string;
-
-  /**
-   * Set the current language for translations
-   * @param language - The language code to set
-   */
-  setLanguage(language: string): void;
-
-  /**
-   * Get the current language
-   * @returns The current language code
-   */
-  getLanguage(): string;
-}
-
-/**
- * Re-export the main II18nEngine interface from interfaces
- * This provides a centralized location for engine type imports
- */
-export type { II18nEngine as IMainI18nEngine } from '../interfaces/i18n-engine.interface';

package/src/utils/currency.ts

@@ -1,141 +0,0 @@
-/**
- * Currency utilities (v2)
- */
-
-import { codes, data } from 'currency-codes';
-
-/**
- * Position of the currency symbol relative to the amount.
- */
-export type CurrencyPosition = 'prefix' | 'postfix' | 'infix';
-
-/**
- * Configuration for formatting currency values in a specific locale.
- */
-export interface CurrencyFormat {
-  /** The currency symbol (e.g., "$", "€") */
-  symbol: string;
-  /** Position of the symbol relative to the amount */
-  position: CurrencyPosition;
-  /** Character used to separate thousands (e.g., ",") */
-  groupSeparator: string;
-  /** Character used to separate decimal places (e.g., ".") */
-  decimalSeparator: string;
-}
-
-/**
- * Detailed information about a currency.
- */
-export interface CurrencyData {
-  /** ISO 4217 currency code (e.g., "USD") */
-  code: string;
-  /** Numeric currency code */
-  number: string;
-  /** Number of decimal digits */
-  digits: number;
-  /** Currency name */
-  currency: string;
-  /** Countries using this currency */
-  countries: string[];
-}
-
-/**
- * Represents a valid ISO 4217 currency code with validation.
- */
-export class CurrencyCode {
-  private _value: string;
-
-  /**
-   * Creates a new CurrencyCode instance.
-   * @param value - The ISO 4217 currency code (defaults to 'USD')
-   * @throws {Error} If the currency code is invalid
-   */
-  constructor(value: string = 'USD') {
-    if (!CurrencyCode.isValid(value)) {
-      throw new Error(`Invalid currency code: ${value}`);
-    }
-    this._value = value;
-  }
-
-  /**
-   * Gets the currency code value.
-   * @returns The ISO 4217 currency code
-   */
-  get value(): string {
-    return this._value;
-  }
-
-  /**
-   * Gets the currency code (alias for value).
-   * @returns The ISO 4217 currency code
-   */
-  get code(): string {
-    return this._value;
-  }
-
-  /**
-   * Checks if a currency code is valid according to ISO 4217.
-   * @param code - The currency code to validate
-   * @returns True if the code is valid, false otherwise
-   */
-  static isValid(code: string): boolean {
-    return codes().includes(code);
-  }
-
-  /**
-   * Gets all valid ISO 4217 currency codes.
-   * @returns Array of currency codes
-   */
-  static getAll(): string[] {
-    return codes();
-  }
-
-  /**
-   * Gets detailed information for all currencies.
-   * @returns Array of currency data objects
-   */
-  static getAllData(): CurrencyData[] {
-    return data as CurrencyData[];
-  }
-}
-
-/**
- * Gets the currency formatting rules for a specific locale and currency.
- * @param locale - The locale code (e.g., 'en-US', 'fr-FR')
- * @param currencyCode - The ISO 4217 currency code
- * @returns Currency format configuration including symbol, position, and separators
- */
-export function getCurrencyFormat(
-  locale: string,
-  currencyCode: string,
-): CurrencyFormat {
-  const formatter = new Intl.NumberFormat(locale, {
-    style: 'currency',
-    currency: currencyCode,
-  });
-
-  const parts = formatter.formatToParts(1234567.89);
-  const symbol = parts.find((part) => part.type === 'currency')?.value || '';
-  const symbolIndex = parts.findIndex((part) => part.type === 'currency');
-  const decimalIndex = parts.findIndex((part) => part.type === 'decimal');
-  const integerIndex = parts.findIndex((part) => part.type === 'integer');
-
-  let position: CurrencyPosition;
-  if (decimalIndex === -1) {
-    position = symbolIndex < integerIndex ? 'prefix' : 'postfix';
-  } else if (symbolIndex < decimalIndex && symbolIndex < integerIndex) {
-    position = 'prefix';
-  } else if (symbolIndex > decimalIndex) {
-    position = 'postfix';
-  } else {
-    position = 'infix';
-  }
-
-  return {
-    symbol,
-    position,
-    groupSeparator: parts.find((part) => part.type === 'group')?.value || ',',
-    decimalSeparator:
-      parts.find((part) => part.type === 'decimal')?.value || '.',
-  };
-}

package/src/utils/html-escape.ts

@@ -1,55 +0,0 @@
-/**
- * HTML escaping utilities for XSS prevention
- */
-
-/**
- * Map of HTML characters to their escaped equivalents.
- */
-const HTML_ESCAPES: Record<string, string> = {
-  '&': '&amp;',
-  '<': '&lt;',
-  '>': '&gt;',
-  '"': '&quot;',
-  "'": '&#x27;',
-  '/': '&#x2F;',
-};
-
-/**
- * Regular expression to match characters that need HTML escaping.
- */
-const HTML_ESCAPE_REGEX = /[&<>"'/]/g;
-
-/**
- * Escapes HTML special characters to prevent XSS attacks.
- * @param str - The string to escape
- * @returns The escaped string
- */
-export function escapeHtml(str: string): string {
-  return str.replace(HTML_ESCAPE_REGEX, char => HTML_ESCAPES[char]);
-}
-
-/**
- * Safely converts a value to a string, optionally escaping HTML.
- * Rejects objects to prevent toString exploits.
- * @param value - The value to stringify
- * @param options - Options including whether to escape HTML
- * @param options.escapeHtml - If true, HTML-escapes the result
- * @returns The stringified value
- * @throws {Error} If the value is an object (to prevent exploits)
- */
-export function safeStringify(value: any, options?: { escapeHtml?: boolean }): string {
-  if (value === null || value === undefined) {
-    return '';
-  }
-  
-  if (typeof value === 'string') {
-    return options?.escapeHtml ? escapeHtml(value) : value;
-  }
-  
-  if (typeof value === 'number' || typeof value === 'boolean') {
-    return String(value);
-  }
-  
-  // Reject objects to prevent toString exploits
-  throw new Error('Invalid value type for stringification');
-}

package/src/utils/lru-cache.ts

@@ -1,76 +0,0 @@
-/**
- * Simple LRU Cache implementation for security
- */
-
-/**
- * Least Recently Used (LRU) cache implementation.
- * Automatically evicts the oldest entries when the cache reaches maximum size.
- * @template K - The type of cache keys
- * @template V - The type of cached values
- */
-export class LRUCache<K, V> {
-  private cache = new Map<K, V>();
-  private readonly maxSize: number;
-
-  /**
-   * Creates a new LRUCache instance.
-   * @param maxSize - Maximum number of entries to store (default: 1000)
-   */
-  constructor(maxSize: number = 1000) {
-    this.maxSize = maxSize;
-  }
-
-  /**
-   * Retrieves a value from the cache by key.
-   * Accessing an item moves it to the end (marks it as most recently used).
-   * @param key - The key to look up
-   * @returns The cached value, or undefined if not found
-   */
-  get(key: K): V | undefined {
-    const value = this.cache.get(key);
-    if (value !== undefined) {
-      // Move to end (most recently used)
-      this.cache.delete(key);
-      this.cache.set(key, value);
-    }
-    return value;
-  }
-
-  /**
-   * Adds or updates a value in the cache.
-   * If the cache is at capacity, the oldest entry is removed.
-   * @param key - The key to store
-   * @param value - The value to cache
-   */
-  set(key: K, value: V): void {
-    // Remove if exists to update position
-    if (this.cache.has(key)) {
-      this.cache.delete(key);
-    }
-    
-    // Remove oldest if at capacity
-    if (this.cache.size >= this.maxSize) {
-      const firstKey = this.cache.keys().next().value;
-      if (firstKey !== undefined) {
-        this.cache.delete(firstKey);
-      }
-    }
-    
-    this.cache.set(key, value);
-  }
-
-  /**
-   * Removes all entries from the cache.
-   */
-  clear(): void {
-    this.cache.clear();
-  }
-
-  /**
-   * Gets the current number of entries in the cache.
-   * @returns The number of cached entries
-   */
-  size(): number {
-    return this.cache.size;
-  }
-}

package/src/utils/string-utils.ts

@@ -1,77 +0,0 @@
-/**
- * String utility functions
- */
-
-import { escapeHtml, safeStringify } from './html-escape';
-
-/**
- * Extract the actual value from an object that might be a wrapper (CurrencyCode, Timezone, etc.).
- * @param value - The value to extract from
- * @returns The extracted value or the original value if not a wrapper
- */
-function extractValue(value: any): any {
-  // Handle objects with a 'value' property (CurrencyCode, Timezone, etc.)
-  if (value && typeof value === 'object' && 'value' in value && typeof value.value !== 'function') {
-    return value.value;
-  }
-  return value;
-}
-
-/**
- * Options for the replaceVariables function.
- */
-export interface ReplaceVariablesOptions {
-  /** If true, HTML-escapes the replaced values */
-  escapeHtml?: boolean;
-}
-
-/**
- * Replaces variables in a string template with values from vars or constants.
- * Variables are denoted by {variableName} in the template string.
- * @param str - The template string containing variables
- * @param vars - Optional object mapping variable names to values
- * @param constants - Optional object containing constant values
- * @param options - Optional configuration including HTML escaping
- * @returns The string with variables replaced
- */
-export function replaceVariables(
-  str: string,
-  vars?: Record<string, any>,
-  constants?: Record<string, any>,
-  options?: ReplaceVariablesOptions,
-): string {
-  if (typeof str !== 'string') {
-    str = String(str);
-  }
-
-  const variables = str.match(/\{(.+?)\}/g);
-  if (!variables) return str;
-
-  let result = str;
-  for (const variable of variables) {
-    const varName = variable.slice(1, -1);
-    let replacement = '';
-
-    if (vars && varName in vars) {
-      const value = extractValue(vars[varName]);
-      replacement = safeStringify(value, options);
-      result = result.replace(variable, replacement);
-    } else if (constants && varName in constants) {
-      const value = extractValue(constants[varName]);
-      replacement = safeStringify(value, options);
-      result = result.replace(variable, replacement);
-    }
-  }
-
-  return result;
-}
-
-/**
- * Checks if a string key indicates a template that expects variable replacement.
- * Template keys end with 'template' (case-insensitive).
- * @param key - The key to check
- * @returns True if the key indicates a template, false otherwise
- */
-export function isTemplate(key: string): boolean {
-  return key.trim().toLowerCase().endsWith('template');
-}

package/src/utils/timezone.ts

@@ -1,76 +0,0 @@
-/**
- * Timezone utilities (v2)
- */
-
-import moment from 'moment-timezone';
-
-/**
- * Represents a valid timezone with validation.
- * Uses moment-timezone for validation and timezone database.
- */
-export class Timezone {
-  private readonly _value: string;
-
-  /**
-   * Creates a new Timezone instance.
-   * @param timezone - The timezone name (e.g., 'America/New_York', 'UTC')
-   * @throws {Error} If the timezone is invalid
-   */
-  constructor(timezone: string) {
-    if (!Timezone.isValid(timezone)) {
-      throw new Error(`Invalid timezone: ${timezone}`);
-    }
-    this._value = timezone;
-  }
-
-  /**
-   * Gets the timezone name.
-   * @returns The timezone name
-   */
-  get value(): string {
-    return this._value;
-  }
-
-  /**
-   * Gets the timezone name (alias for value).
-   * @returns The timezone name
-   */
-  get name(): string {
-    return this._value;
-  }
-
-  /**
-   * Checks if a timezone name is valid.
-   * @param timezone - The timezone name to validate
-   * @returns True if the timezone is valid, false otherwise
-   */
-  static isValid(timezone: string): boolean {
-    return moment.tz.zone(timezone) !== null;
-  }
-
-  /**
-   * Gets all available timezone names.
-   * @returns Array of timezone names
-   */
-  static getAll(): string[] {
-    return moment.tz.names();
-  }
-
-  /**
-   * Attempts to guess the user's timezone based on their system settings.
-   * @returns The guessed timezone name
-   */
-  static guess(): string {
-    return moment.tz.guess();
-  }
-}
-
-/**
- * Checks if a timezone name is valid.
- * This is a convenience function that delegates to Timezone.isValid().
- * @param timezone - The timezone name to validate
- * @returns True if the timezone is valid, false otherwise
- */
-export function isValidTimezone(timezone: string): boolean {
-  return Timezone.isValid(timezone);
-}

package/src/utils/validation.ts

@@ -1,66 +0,0 @@
-/**
- * Input validation utilities
- */
-
-/**
- * Security limits for various input types to prevent abuse.
- */
-export const LIMITS = {
-  MAX_TEMPLATE_LENGTH: 10000,
-  MAX_KEY_LENGTH: 200,
-  MAX_COMPONENT_ID_LENGTH: 100,
-  MAX_LANGUAGE_CODE_LENGTH: 10,
-  MAX_NESTING_DEPTH: 10,
-} as const;
-
-/**
- * Validates that a template string does not exceed the maximum allowed length.
- * @param template - The template string to validate
- * @throws {Error} If the template exceeds the maximum length
- */
-export function validateTemplateLength(template: string): void {
-  if (template.length > LIMITS.MAX_TEMPLATE_LENGTH) {
-    throw new Error(`Template exceeds maximum length of ${LIMITS.MAX_TEMPLATE_LENGTH}`);
-  }
-}
-
-/**
- * Validates that a key does not exceed the maximum allowed length.
- * @param key - The key to validate
- * @throws {Error} If the key exceeds the maximum length
- */
-export function validateKeyLength(key: string): void {
-  if (key.length > LIMITS.MAX_KEY_LENGTH) {
-    throw new Error(`Key exceeds maximum length of ${LIMITS.MAX_KEY_LENGTH}`);
-  }
-}
-
-/**
- * Validates that a component ID meets length and character requirements.
- * Component IDs must contain only alphanumeric characters, underscores, and hyphens.
- * @param componentId - The component ID to validate
- * @throws {Error} If the component ID is invalid
- */
-export function validateComponentId(componentId: string): void {
-  if (componentId.length > LIMITS.MAX_COMPONENT_ID_LENGTH) {
-    throw new Error(`Component ID exceeds maximum length of ${LIMITS.MAX_COMPONENT_ID_LENGTH}`);
-  }
-  if (!/^[a-zA-Z0-9_-]+$/.test(componentId)) {
-    throw new Error('Component ID contains invalid characters');
-  }
-}
-
-/**
- * Validates that a language code meets BCP 47 format requirements.
- * Expected format: two lowercase letters, optionally followed by a hyphen and two uppercase letters (e.g., 'en', 'en-US').
- * @param language - The language code to validate
- * @throws {Error} If the language code is invalid
- */
-export function validateLanguageCode(language: string): void {
-  if (language.length > LIMITS.MAX_LANGUAGE_CODE_LENGTH) {
-    throw new Error(`Language code exceeds maximum length of ${LIMITS.MAX_LANGUAGE_CODE_LENGTH}`);
-  }
-  if (!/^[a-z]{2}(-[A-Z]{2})?$/.test(language)) {
-    throw new Error('Invalid language code format');
-  }
-}