@digitaldefiance/i18n-lib 3.7.5 → 3.8.1

package/src/utils/string-utils.ts

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

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

@@ -0,0 +1,66 @@
+/**
+ * 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');
+  }
+}

package/src/utils.ts

@@ -0,0 +1,215 @@
+import moment from 'moment-timezone';
+
+/**
+ * Replaces variables in a string with their corresponding values from vars or constants.
+ * @param str - The string containing variables to replace
+ * @param vars - An object mapping variable names to their replacement values
+ * @param constants - An object containing constant values for replacement
+ * @returns The string with variables replaced
+ */
+export function replaceVariables(
+  str: string,
+  vars?: Record<string, string | number>,
+  constants?: any,
+): string {
+  // Ensure input is a 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) {
+      replacement = String(vars[varName]);
+    } else if (constants && varName in constants) {
+      replacement = String(constants[varName]);
+    }
+
+    if (replacement) {
+      result = result.replace(variable, replacement);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Checks if a given key indicates a template string.
+ * @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');
+}
+
+/**
+ * Checks if a given timezone string is valid.
+ * @param timezone - The timezone string to validate
+ * @returns
+ */
+export function isValidTimezone(timezone: string): boolean {
+  return moment.tz.zone(timezone) !== null;
+}
+
+/**
+ * Converts parts to a single string key, joining with underscores.
+ * @param parts - The parts to join
+ * @returns The joined string key
+ */
+export function toStringKey<TStringKey extends string>(
+  ...parts: string[]
+): TStringKey {
+  return parts.join('_') as TStringKey;
+}
+
+/**
+ * Converts an enum value to a string key by joining parts with underscores and appending the enum value.
+ * @param value - The enum value
+ * @param parts - Additional parts to join
+ * @returns The constructed string key
+ */
+export function toStringKeyFromEnum<TStringKey extends string>(
+  value: string,
+  ...parts: string[]
+): TStringKey {
+  const allParts = [...parts, value];
+  return allParts.join('_') as TStringKey;
+}
+
+/**
+ * Type that constructs string keys from enum values with prefixes and optional template suffix
+ */
+type BuildStringKey<
+  TEnumValue extends string,
+  TPrefixes extends readonly string[],
+  TIsTemplate extends boolean = false,
+> = TPrefixes extends readonly []
+  ? `${TEnumValue}${TIsTemplate extends true ? 'Template' : ''}`
+  : TPrefixes extends readonly [infer First, ...infer Rest]
+  ? First extends string
+    ? Rest extends readonly string[]
+      ? `${First}_${BuildStringKey<TEnumValue, Rest, TIsTemplate>}`
+      : never
+    : never
+  : never;
+
+/**
+ * Type that maps all enum values to their corresponding string keys
+ */
+type ReasonMapFromEnum<
+  TEnum extends Record<string, string>,
+  TStringKey extends string,
+  TPrefixes extends readonly string[] = [],
+  TTemplateKeys extends Set<TEnum[keyof TEnum]> = never,
+> = {
+  [K in TEnum[keyof TEnum]]: BuildStringKey<
+    K,
+    TPrefixes,
+    TTemplateKeys extends Set<K> ? true : false
+  > extends TStringKey
+    ? BuildStringKey<K, TPrefixes, TTemplateKeys extends Set<K> ? true : false>
+    : never;
+};
+
+/**
+ * Builds a reason map from an enum object, mapping each enum value to a string key.
+ * @param enumObj - The enum object
+ * @param prefixes - Prefixes to prepend to each string key
+ * @param templateKeys - Optional set of enum values that should have 'Template' suffix for template processing
+ * @returns The constructed reason map
+ */
+export function buildReasonMap<
+  TEnum extends Record<string, string>,
+  TStringKey extends string,
+>(
+  enumObj: TEnum,
+  prefixes: string[] = [],
+  templateKeys?: Set<TEnum[keyof TEnum]>,
+): Record<TEnum[keyof TEnum], TStringKey> {
+  const map = {} as Record<TEnum[keyof TEnum], TStringKey>;
+
+  Object.values(enumObj).forEach((value) => {
+    const baseKey = [...prefixes, value].join('_');
+    const finalKey = templateKeys?.has(value as TEnum[keyof TEnum])
+      ? baseKey + 'Template'
+      : baseKey;
+    map[value as TEnum[keyof TEnum]] = finalKey as TStringKey;
+  });
+
+  return map;
+}
+
+/**
+ * Type-safe version of buildReasonMap that ensures all enum values are mapped and all string keys exist
+ */
+export function buildTypeSafeReasonMap<
+  TEnum extends Record<string, string>,
+  TStringKey extends string,
+  TPrefixes extends readonly string[] = [],
+  TTemplateKeys extends Set<TEnum[keyof TEnum]> = never,
+>(
+  enumObj: TEnum,
+  prefixes: TPrefixes,
+  templateKeys?: TTemplateKeys,
+): ReasonMapFromEnum<TEnum, TStringKey, TPrefixes, TTemplateKeys> {
+  const map: Partial<
+    ReasonMapFromEnum<TEnum, TStringKey, TPrefixes, TTemplateKeys>
+  > = {};
+
+  Object.values(enumObj).forEach((value) => {
+    const baseKey = [...prefixes, value].join('_');
+    const finalKey = templateKeys?.has(value as TEnum[keyof TEnum])
+      ? baseKey + 'Template'
+      : baseKey;
+    map[value as TEnum[keyof TEnum]] = finalKey as any;
+  });
+
+  return map as ReasonMapFromEnum<TEnum, TStringKey, TPrefixes, TTemplateKeys>;
+}
+
+/**
+ * Validates that a reason map has entries for all enum values
+ */
+export function validateReasonMap<
+  TEnum extends Record<string, string>,
+  TStringKey extends string,
+>(
+  enumObj: TEnum,
+  reasonMap: Partial<Record<TEnum[keyof TEnum], TStringKey>>,
+): reasonMap is Record<TEnum[keyof TEnum], TStringKey> {
+  return Object.values(enumObj).every(
+    (value) =>
+      value in reasonMap &&
+      reasonMap[value as TEnum[keyof TEnum]] !== undefined,
+  );
+}
+
+/**
+ * Creates a complete reason map ensuring all enum values are covered
+ */
+export function createCompleteReasonMap<
+  TEnum extends Record<string, string>,
+  TStringKey extends string,
+>(
+  enumObj: TEnum,
+  prefixes: readonly string[] = [],
+  templateKeys?: Set<TEnum[keyof TEnum]>,
+): Record<TEnum[keyof TEnum], TStringKey> {
+  const map = buildReasonMap(enumObj, [...prefixes], templateKeys) as Record<
+    TEnum[keyof TEnum],
+    TStringKey
+  >;
+
+  if (!validateReasonMap(enumObj, map)) {
+    const missing = Object.values(enumObj).filter((value) => !(value in map));
+    throw new Error(`Missing reason map entries for: ${missing.join(', ')}`);
+  }
+
+  return map;
+}

package/src/validation/{index.d.ts → index.ts}

@@ -1,2 +1 @@
 export * from './plural-validator';
-//# sourceMappingURL=index.d.ts.map

package/src/validation/plural-validator.ts

@@ -0,0 +1,168 @@
+/**
+ * Plural form validation
+ */
+
+import { PluralCategory } from '../pluralization/plural-categories';
+import { PluralString, isPluralString } from '../types/plural-types';
+import { getRequiredPluralForms, getAllPluralForms } from '../pluralization/language-plural-map';
+
+/**
+ * Result of validating plural forms.
+ */
+export interface PluralValidationResult {
+  /** Whether the validation passed */
+  isValid: boolean;
+  /** Array of validation errors */
+  errors: string[];
+  /** Array of validation warnings */
+  warnings: string[];
+}
+
+/**
+ * Options for plural form validation.
+ */
+export interface PluralValidationOptions {
+  /** If true, treat missing required forms as errors instead of warnings */
+  strict?: boolean;
+  /** If true, warn about unused plural forms */
+  checkUnused?: boolean;
+  /** If true, check for consistent variable usage across forms */
+  checkVariables?: boolean;
+}
+
+/**
+ * Validate plural forms for a specific language.
+ * Checks that all required plural forms are present and optionally validates variable consistency.
+ * @param value - The plural string value to validate
+ * @param language - The language code
+ * @param key - The translation key (for error messages)
+ * @param options - Validation options
+ * @returns Validation result with errors and warnings
+ */
+export function validatePluralForms(
+  value: PluralString,
+  language: string,
+  key: string,
+  options: PluralValidationOptions = {}
+): PluralValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (!isPluralString(value)) {
+    return { isValid: true, errors, warnings };
+  }
+
+  const required = getRequiredPluralForms(language);
+  const all = getAllPluralForms(language);
+  const provided = Object.keys(value) as PluralCategory[];
+
+  // Check required forms
+  for (const form of required) {
+    if (!value[form as PluralCategory]) {
+      if (options.strict) {
+        errors.push(`Missing required plural form '${form}' for language '${language}' in key '${key}'`);
+      } else {
+        warnings.push(`Missing required plural form '${form}' for language '${language}' in key '${key}'`);
+      }
+    }
+  }
+
+  // Check unused forms
+  if (options.checkUnused) {
+    for (const form of provided) {
+      if (!all.includes(form)) {
+        warnings.push(`Unused plural form '${form}' for language '${language}' in key '${key}'`);
+      }
+    }
+  }
+
+  // Check variable consistency
+  if (options.checkVariables) {
+    const variables = extractVariables(value);
+    const inconsistent = findInconsistentVariables(value, variables);
+    for (const [form, missing] of Object.entries(inconsistent)) {
+      warnings.push(`Plural form '${form}' in key '${key}' missing variables: ${missing.join(', ')}`);
+    }
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Extract all variables from plural forms.
+ * Scans all plural form texts for {variable} patterns.
+ * @param value - The plural string value
+ * @returns Set of all variable names found
+ */
+function extractVariables(value: PluralString): Set<string> {
+  const vars = new Set<string>();
+  if (typeof value === 'string') return vars;
+
+  for (const text of Object.values(value)) {
+    if (text) {
+      const matches = text.match(/\{(\w+)\}/g);
+      if (matches) {
+        matches.forEach(m => vars.add(m.slice(1, -1)));
+      }
+    }
+  }
+  return vars;
+}
+
+/**
+ * Find forms with inconsistent variables.
+ * Identifies plural forms that are missing variables used in other forms.
+ * @param value - The plural string value
+ * @param allVars - Set of all variables found across all forms
+ * @returns Object mapping form names to arrays of missing variable names
+ */
+function findInconsistentVariables(
+  value: PluralString,
+  allVars: Set<string>
+): Record<string, string[]> {
+  const inconsistent: Record<string, string[]> = {};
+  if (typeof value === 'string') return inconsistent;
+
+  for (const [form, text] of Object.entries(value)) {
+    if (text) {
+      const formVars = new Set<string>();
+      const matches = text.match(/\{(\w+)\}/g);
+      if (matches) {
+        matches.forEach(m => formVars.add(m.slice(1, -1)));
+      }
+
+      const missing = Array.from(allVars).filter(v => !formVars.has(v));
+      if (missing.length > 0) {
+        inconsistent[form] = missing;
+      }
+    }
+  }
+  return inconsistent;
+}
+
+/**
+ * Validate that count variable exists when plural forms are used.
+ * Pluralization requires a 'count' variable to determine which form to use.
+ * @param value - The plural string value
+ * @param variables - The variables object to check
+ * @param key - The translation key (for error messages)
+ * @returns Validation result with warnings if count is missing
+ */
+export function validateCountVariable(
+  value: PluralString,
+  variables: Record<string, any> | undefined,
+  key: string
+): PluralValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (isPluralString(value) && (!variables || variables.count === undefined)) {
+    warnings.push(`Plural forms used in key '${key}' but no 'count' variable provided`);
+  }
+
+  return { isValid: true, errors, warnings };
+}

package/src/validation-config.ts

@@ -0,0 +1,11 @@
+/**
+ * Configuration for component registration validation
+ */
+export interface ValidationConfig {
+  /** Whether to require all languages to have all strings */
+  readonly requireCompleteStrings: boolean;
+  /** Whether to allow registration with missing strings (will use fallbacks) */
+  readonly allowPartialRegistration: boolean;
+  /** Default language to fall back to for missing strings */
+  readonly fallbackLanguageId: string;
+}

package/src/validation-result.ts

@@ -0,0 +1,12 @@
+/**
+ * Validation result for component registration
+ */
+export interface ValidationResult {
+  readonly isValid: boolean;
+  readonly missingKeys: ReadonlyArray<{
+    readonly languageId: string;
+    readonly componentId: string;
+    readonly stringKey: string;
+  }>;
+  readonly errors: readonly string[];
+}

package/src/active-context.d.ts

@@ -1,36 +0,0 @@
-import { CurrencyCode } from './utils/currency';
-import { Timezone } from './utils/timezone';
-import { LanguageContextSpace } from './types';
-/**
- * Represents the active internationalization context for user and admin interfaces,
- * including language, currency, and timezone settings.
- *
- * @template TLanguage The type of language codes (e.g., 'en-US', 'fr').
- */
-export interface IActiveContext<TLanguage extends string> {
-    /**
-     * The default language for the user-facing application.
-     */
-    language: TLanguage;
-    /**
-     * The default language for the admin interface.
-     */
-    adminLanguage: TLanguage;
-    /**
-     * The default currency code for the user-facing application.
-     */
-    currencyCode: CurrencyCode;
-    /**
-     * The current language context space (e.g., 'user' or 'admin').
-     */
-    currentContext: LanguageContextSpace;
-    /**
-     * The default timezone for the user-facing application.
-     */
-    timezone: Timezone;
-    /**
-     * The default timezone for the admin interface.
-     */
-    adminTimezone: Timezone;
-}
-//# sourceMappingURL=active-context.d.ts.map

package/src/active-context.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"active-context.d.ts","sourceRoot":"","sources":["../../../../packages/digitaldefiance-i18n-lib/src/active-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,WAAW,cAAc,CAAC,SAAS,SAAS,MAAM;IACtD;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,aAAa,EAAE,SAAS,CAAC;IAEzB;;OAEG;IACH,YAAY,EAAE,YAAY,CAAC;IAE3B;;OAEG;IACH,cAAc,EAAE,oBAAoB,CAAC;IAErC;;OAEG;IACH,QAAQ,EAAE,QAAQ,CAAC;IAEnB;;OAEG;IACH,aAAa,EAAE,QAAQ,CAAC;CACzB"}

package/src/active-context.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=active-context.js.map

package/src/active-context.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"active-context.js","sourceRoot":"","sources":["../../../../packages/digitaldefiance-i18n-lib/src/active-context.ts"],"names":[],"mappings":""}