@digitaldefiance/i18n-lib 3.8.0 → 3.8.2

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

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