@digitaldefiance/i18n-lib 3.7.5 → 3.8.1

package/src/types/engine.ts

@@ -0,0 +1,55 @@
+/**
+ * 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/types/{index.d.ts → index.ts}

@@ -1,6 +1,6 @@
 /**
  * Type exports
  */
+
 export * from './engine';
 export * from './plural-types';
-//# sourceMappingURL=index.d.ts.map

package/src/types/{plural-types.d.ts → plural-types.ts}

@@ -1,18 +1,24 @@
 /**
  * Type definitions for pluralization support
  */
+
 import { PluralCategory } from '../pluralization/plural-categories';
+
 /**
  * A string value that can be either a simple string or an object with plural forms.
  * When using plural forms, the object should have keys matching PluralCategory values.
  */
 export type PluralString = string | Partial<Record<PluralCategory, string>>;
+
 /**
  * Check if a value is a plural string object (not a simple string).
  * @param value - The value to check
  * @returns True if the value is a plural string object, false if it's a simple string
  */
-export declare function isPluralString(value: any): value is Record<PluralCategory, string>;
+export function isPluralString(value: any): value is Record<PluralCategory, string> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 /**
  * Get the appropriate plural form from a PluralString based on the category.
  * Falls back to 'other' if the exact category is not found, then to the first available form.
@@ -20,5 +26,25 @@ export declare function isPluralString(value: any): value is Record<PluralCatego
  * @param category - The plural category to retrieve
  * @returns The resolved string, or undefined if no suitable form is found
  */
-export declare function resolvePluralString(value: PluralString, category: PluralCategory): string | undefined;
-//# sourceMappingURL=plural-types.d.ts.map
+export function resolvePluralString(
+  value: PluralString,
+  category: PluralCategory
+): string | undefined {
+  if (typeof value === 'string') {
+    return value;
+  }
+  
+  // Try exact match first
+  if (value[category]) {
+    return value[category];
+  }
+  
+  // Fallback to 'other'
+  if (value.other) {
+    return value.other;
+  }
+  
+  // Fallback to first available form
+  const forms = Object.values(value);
+  return forms.length > 0 ? forms[0] : undefined;
+}

package/src/types.ts

@@ -0,0 +1,142 @@
+import { ComponentDefinition } from './component-definition';
+import { LanguageDefinition } from './language-definition';
+
+/**
+ * Standard language context spaces
+ */
+export type LanguageContextSpace = 'admin' | 'user';
+
+/**
+ * Default currency code
+ */
+export const DefaultCurrencyCode: string = 'USD';
+
+/**
+ * Default timezone
+ */
+export const DefaultTimezone: string = 'UTC';
+
+/**
+ * Default language code
+ */
+export const DefaultLanguageCode: string = 'en-US';
+
+/**
+ * Currency position type
+ */
+export type CurrencyPosition = 'prefix' | 'postfix' | 'infix';
+
+/**
+ * Collection of localized strings for a specific language
+ */
+export type StringsCollection<TStringKey extends string> = Partial<
+  Record<TStringKey, string>
+>;
+
+/**
+ * Mapping of languages to their respective string collections
+ */
+export type MasterStringsCollection<
+  TStringKey extends string,
+  TLanguage extends string,
+> = Partial<Record<TLanguage, StringsCollection<TStringKey>>>;
+
+/**
+ * Mapping of language codes to their respective languages
+ */
+export type LanguageCodeCollection<TLanguage extends string> = Partial<
+  Record<TLanguage, string>
+>;
+
+/**
+ * Mapping of enumeration values to their translations in multiple languages
+ */
+export type EnumTranslationMap<
+  TEnum extends string | number,
+  TLanguage extends string,
+> = Partial<Record<TLanguage, Partial<Record<TEnum, string>>>>;
+
+/**
+ * String collection for a specific language and component
+ */
+export type ComponentStrings<TStringKeys extends string> = {
+  [K in TStringKeys]: string;
+};
+
+/**
+ * Partial string collection (used during registration before validation)
+ */
+export type PartialComponentStrings<TStringKeys extends string> = {
+  [K in TStringKeys]?: string;
+};
+
+/**
+ * Language strings for a component across all registered languages
+ */
+export type ComponentLanguageStrings<
+  TStringKeys extends string,
+  TLanguages extends string,
+> = {
+  [L in TLanguages]: ComponentStrings<TStringKeys>;
+};
+
+/**
+ * Partial language strings (used during registration before validation)
+ */
+export type PartialComponentLanguageStrings<
+  TStringKeys extends string,
+  TLanguages extends string,
+> = {
+  [L in TLanguages]?: PartialComponentStrings<TStringKeys>;
+};
+
+/**
+ * Generic translation type for any enumeration
+ */
+export type EnumTranslation<T extends string | number> = {
+  [K in T]: string;
+};
+
+/**
+ * Generic language translation type for any enumeration
+ */
+export type EnumLanguageTranslation<
+  T extends string | number,
+  TLanguage extends string = string,
+> = Partial<{
+  [L in TLanguage]: EnumTranslation<T>;
+}>;
+
+/**
+ * Type utility to extract string keys from a component definition
+ */
+export type ExtractStringKeys<T> = T extends ComponentDefinition<infer K>
+  ? K
+  : never;
+
+/**
+ * Type utility to extract languages from registry
+ */
+export type ExtractLanguages<T> = T extends LanguageDefinition
+  ? T['id']
+  : never;
+
+/**
+ * Utility type to ensure all string keys are provided for all languages
+ */
+export type CompleteComponentStrings<
+  TStringKeys extends string,
+  TLanguages extends string,
+> = ComponentLanguageStrings<TStringKeys, TLanguages>;
+
+/**
+ * Helper function to create typed translations for an enumeration
+ */
+export function createTranslations<
+  T extends string | number,
+  TLanguage extends string,
+>(
+  translations: EnumLanguageTranslation<T, TLanguage>,
+): EnumLanguageTranslation<T, TLanguage> {
+  return translations;
+}

package/src/utils/currency.ts

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

@@ -0,0 +1,55 @@
+/**
+ * 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/{index.d.ts → index.ts}

@@ -6,4 +6,3 @@ export * from './timezone';
 export * from './validation';
 export * from './html-escape';
 export * from './lru-cache';
-//# sourceMappingURL=index.d.ts.map

package/src/utils/lru-cache.ts

@@ -0,0 +1,76 @@
+/**
+ * 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/{plural-helpers.d.ts → plural-helpers.ts}

@@ -1,26 +1,36 @@
 /**
  * Helper functions for creating plural and gender strings
  */
+
 import { PluralCategory } from '../pluralization/plural-categories';
 import { PluralString } from '../types/plural-types';
 import { GenderCategory, GenderedString } from '../gender/gender-categories';
+import { getRequiredPluralForms as getRequiredFormsFromMap } from '../pluralization/language-plural-map';
+
 /**
  * Creates a PluralString from a partial record of plural forms.
  * @param forms - Object mapping plural categories to their string forms
  * @returns A PluralString that can be used in translations
  */
-export declare function createPluralString(forms: Partial<Record<PluralCategory, string>>): PluralString;
+export function createPluralString(forms: Partial<Record<PluralCategory, string>>): PluralString {
+  return forms;
+}
+
 /**
  * Creates a GenderedString from a partial record of gender forms.
  * @param forms - Object mapping gender categories to their string forms
  * @returns A GenderedString that can be used in translations
  */
-export declare function createGenderedString(forms: Partial<Record<GenderCategory, string>>): GenderedString;
+export function createGenderedString(forms: Partial<Record<GenderCategory, string>>): GenderedString {
+  return forms;
+}
+
 /**
  * Gets the required plural forms for a given language.
  * Different languages have different plural rules and require different forms.
  * @param language - The language code
  * @returns Array of plural categories required for the language
  */
-export declare function getRequiredPluralForms(language: string): PluralCategory[];
-//# sourceMappingURL=plural-helpers.d.ts.map
+export function getRequiredPluralForms(language: string): PluralCategory[] {
+  return getRequiredFormsFromMap(language) as PluralCategory[];
+}

package/src/utils/{safe-object.js → safe-object.ts}

@@ -1,34 +1,31 @@
-"use strict";
 /**
  * Safe object utilities to prevent prototype pollution
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createSafeObject = createSafeObject;
-exports.isDangerousKey = isDangerousKey;
-exports.safeAssign = safeAssign;
-exports.safeObjectEntries = safeObjectEntries;
-exports.validateObjectKeys = validateObjectKeys;
+
 /**
  * List of dangerous keys that should never be set on objects to prevent prototype pollution.
  */
 const DANGEROUS_KEYS = ['__proto__', 'constructor', 'prototype'];
+
 /**
  * Creates a safe object without a prototype chain.
  * This prevents prototype pollution attacks.
  * @template T - The type of values in the object
  * @returns A new object without a prototype
  */
-function createSafeObject() {
-    return Object.create(null);
+export function createSafeObject<T = any>(): Record<string, T> {
+  return Object.create(null);
 }
+
 /**
  * Checks if a key is in the list of dangerous keys that could enable prototype pollution.
  * @param key - The key to check
  * @returns True if the key is dangerous, false otherwise
  */
-function isDangerousKey(key) {
-    return DANGEROUS_KEYS.includes(key);
+export function isDangerousKey(key: string): boolean {
+  return DANGEROUS_KEYS.includes(key);
 }
+
 /**
  * Safely assigns properties from source objects to a target object.
  * Filters out dangerous keys to prevent prototype pollution.
@@ -37,42 +34,48 @@ function isDangerousKey(key) {
  * @param sources - One or more source objects to copy properties from
  * @returns The target object with properties assigned
  */
-function safeAssign(target, ...sources) {
-    for (const source of sources) {
-        if (!source)
-            continue;
-        for (const key of Object.keys(source)) {
-            if (!isDangerousKey(key)) {
-                // Type-safe property assignment using index signature
-                target[key] = source[key];
-            }
-        }
+export function safeAssign<T extends Record<string, any>>(
+  target: T,
+  ...sources: Array<Record<string, any> | undefined>
+): T {
+  for (const source of sources) {
+    if (!source) continue;
+
+    for (const key of Object.keys(source)) {
+      if (!isDangerousKey(key)) {
+        // Type-safe property assignment using index signature
+        (target as Record<string, any>)[key] = source[key];
+      }
     }
-    return target;
+  }
+  return target;
 }
+
 /**
  * Gets key-value pairs from an object, filtering out dangerous keys.
  * @template T - The type of values in the object
  * @param obj - The object to get entries from
  * @returns Array of [key, value] pairs, excluding dangerous keys
  */
-function safeObjectEntries(obj) {
-    return Object.entries(obj).filter(([key]) => !isDangerousKey(key));
+export function safeObjectEntries<T>(
+  obj: Record<string, T>,
+): Array<[string, T]> {
+  return Object.entries(obj).filter(([key]) => !isDangerousKey(key));
 }
+
 /**
  * Validates that an object does not contain dangerous keys.
  * @param obj - The object to validate
  * @throws {Error} If a dangerous key is detected
  */
-function validateObjectKeys(obj) {
-    if (!obj || typeof obj !== 'object')
-        return;
-    // Check for dangerous keys in Object.keys and getOwnPropertyNames
-    const allKeys = [...Object.keys(obj), ...Object.getOwnPropertyNames(obj)];
-    for (const key of allKeys) {
-        if (DANGEROUS_KEYS.includes(key)) {
-            throw new Error(`Dangerous key detected: ${key}`);
-        }
+export function validateObjectKeys(obj: Record<string, any>): void {
+  if (!obj || typeof obj !== 'object') return;
+
+  // Check for dangerous keys in Object.keys and getOwnPropertyNames
+  const allKeys = [...Object.keys(obj), ...Object.getOwnPropertyNames(obj)];
+  for (const key of allKeys) {
+    if (DANGEROUS_KEYS.includes(key)) {
+      throw new Error(`Dangerous key detected: ${key}`);
     }
+  }
 }
-//# sourceMappingURL=safe-object.js.map