@digitaldefiance/i18n-lib 1.3.11 → 1.3.13

package/src/plugin-typed-handleable.ts

@@ -0,0 +1,77 @@
+import { HandleableError } from './handleable';
+import { IHandleable } from './i-handleable';
+import { HandleableErrorOptions } from './i-handleable-error-options';
+import { PluginI18nEngine } from './plugin-i18n-engine';
+import { CompleteReasonMap, PluginTypedError } from './typed-error';
+
+type ErrorConstructorWithStack = ErrorConstructor & {
+  captureStackTrace?: (target: Error, constructorOpt?: Function) => void;
+};
+
+export class PluginTypedHandleableError<
+    TEnum extends Record<string, string>,
+    TStringKey extends string,
+    TLanguages extends string = string,
+  >
+  extends PluginTypedError<TEnum, TStringKey, TLanguages>
+  implements IHandleable
+{
+  public override readonly cause?: Error;
+  public readonly statusCode: number;
+  public readonly sourceData?: unknown;
+  private _handled: boolean;
+
+  constructor(
+    engine: PluginI18nEngine<TLanguages>,
+    componentId: string,
+    type: TEnum[keyof TEnum],
+    reasonMap: CompleteReasonMap<TEnum, TStringKey>,
+    source: Error,
+    options?: HandleableErrorOptions,
+    language?: TLanguages,
+    otherVars?: Record<string, string | number>,
+  ) {
+    super(engine, componentId, type, reasonMap, language, otherVars);
+    this.cause = options?.cause ?? source;
+    this.statusCode = options?.statusCode ?? 500;
+    this._handled = options?.handled ?? false;
+    this.sourceData = options?.sourceData;
+
+    // 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;
+    }
+    this.name = this.constructor.name;
+  }
+
+  public get handled(): boolean {
+    return this._handled;
+  }
+
+  public set handled(value: boolean) {
+    this._handled = value;
+  }
+
+  public toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      message: this.message,
+      statusCode: this.statusCode,
+      handled: this.handled,
+      stack: this.stack,
+      cause:
+        this.cause instanceof HandleableError ||
+        this.cause instanceof PluginTypedHandleableError
+          ? this.cause.toJSON()
+          : this.cause?.message,
+      ...(this.sourceData ? { sourceData: this.sourceData } : {}),
+    };
+  }
+}

package/src/registry-config.ts

@@ -0,0 +1,15 @@
+import { CurrencyCode } from './currency-code';
+import { Timezone } from './timezone';
+import { ValidationConfig } from './validation-config';
+
+/**
+ * Registry configuration
+ */
+export interface RegistryConfig<TLanguages extends string> {
+  readonly defaultLanguage: TLanguages;
+  readonly fallbackLanguage: TLanguages;
+  readonly defaultCurrencyCode: CurrencyCode;
+  readonly timezone: Timezone;
+  readonly adminTimezone: Timezone;
+  readonly validation: ValidationConfig;
+}

package/src/registry-error-type.ts

@@ -0,0 +1,12 @@
+/**
+ * Error types for registry operations
+ */
+export enum RegistryErrorType {
+  ComponentNotFound = 'COMPONENT_NOT_FOUND',
+  LanguageNotFound = 'LANGUAGE_NOT_FOUND',
+  StringKeyNotFound = 'STRING_KEY_NOT_FOUND',
+  IncompleteRegistration = 'INCOMPLETE_REGISTRATION',
+  DuplicateComponent = 'DUPLICATE_COMPONENT',
+  DuplicateLanguage = 'DUPLICATE_LANGUAGE',
+  ValidationFailed = 'VALIDATION_FAILED',
+}

package/src/registry-error.ts

@@ -0,0 +1,74 @@
+// CoreLanguageCode is deprecated - using string
+import { CoreStringKey } from './core-string-key';
+import { RegistryErrorType } from './registry-error-type';
+import { TranslationEngine, createTranslatedError } from './typed-error';
+
+/**
+ * Reason map for registry errors
+ */
+const REGISTRY_ERROR_REASON_MAP = {
+  [RegistryErrorType.ComponentNotFound]:
+    CoreStringKey.Error_ComponentNotFoundTemplate,
+  [RegistryErrorType.DuplicateComponent]:
+    CoreStringKey.Error_DuplicateComponentTemplate,
+  [RegistryErrorType.DuplicateLanguage]:
+    CoreStringKey.Error_DuplicateLanguageTemplate,
+  [RegistryErrorType.IncompleteRegistration]:
+    CoreStringKey.Error_IncompleteRegistrationTemplate,
+  [RegistryErrorType.LanguageNotFound]:
+    CoreStringKey.Error_LanguageNotFoundTemplate,
+  [RegistryErrorType.StringKeyNotFound]:
+    CoreStringKey.Error_StringKeyNotFoundTemplate,
+  [RegistryErrorType.ValidationFailed]:
+    CoreStringKey.Error_ValidationFailedTemplate,
+} as const;
+
+/**
+ * Registry error class that can work with plugin engines
+ */
+export class RegistryError extends Error {
+  constructor(
+    public readonly type: RegistryErrorType,
+    message: string,
+    public readonly metadata?: Record<string, any>,
+  ) {
+    super(message);
+    this.name = 'RegistryError';
+  }
+
+  /**
+   * Create a registry error with translation support
+   */
+  static createWithEngine(
+    engine: TranslationEngine,
+    type: RegistryErrorType,
+    variables?: Record<string, string | number>,
+    language?: string,
+    metadata?: Record<string, any>,
+  ): RegistryError {
+    const error = createTranslatedError(
+      engine,
+      'core',
+      type,
+      REGISTRY_ERROR_REASON_MAP,
+      variables,
+      language,
+      metadata,
+      'RegistryError',
+    );
+
+    // Convert to RegistryError instance
+    return new RegistryError(type, error.message, metadata);
+  }
+
+  /**
+   * Create a simple RegistryError without engine dependency
+   */
+  static createSimple(
+    type: RegistryErrorType,
+    message: string,
+    metadata?: Record<string, any>,
+  ): RegistryError {
+    return new RegistryError(type, message, metadata);
+  }
+}

package/src/strict-types.ts

@@ -0,0 +1,35 @@
+/**
+ * Enforces that for each language L, all string keys K are present.
+ */
+export type CompleteLanguageStrings<TStringKey extends string> = {
+  [K in TStringKey]: string;
+};
+
+export type CompleteComponentLanguageStrings<
+  TStringKey extends string,
+  TLanguages extends string,
+> = {
+  [L in TLanguages]: CompleteLanguageStrings<TStringKey>;
+};
+
+/**
+ * Helper to assert at compile-time that an object is a complete component language map.
+ * Returns the object unchanged at runtime.
+ */
+export function createCompleteComponentStrings<
+  TStringKey extends string,
+  TLanguages extends string,
+>(
+  obj: CompleteComponentLanguageStrings<TStringKey, TLanguages>,
+): CompleteComponentLanguageStrings<TStringKey, TLanguages> {
+  return obj;
+}
+
+/**
+ * Utility to extract missing keys at compile time (identity, purely for readability)
+ */
+export function defineLanguageStrings<TStringKey extends string>(
+  strings: CompleteLanguageStrings<TStringKey>,
+): CompleteLanguageStrings<TStringKey> {
+  return strings;
+}

package/src/template.ts

@@ -0,0 +1,63 @@
+/**
+ * Template processing utilities for i18n
+ */
+export type EnumKeys<T> = keyof T;
+
+/**
+ * Recursive type to validate that all enum keys in the template string exist in the provided enum type
+ */
+export type IsValidEnumTemplate<
+  T extends string,
+  TEnum,
+> = T extends `${string}{{${string}.${infer Key}}}${infer Rest}`
+  ? Key extends EnumKeys<TEnum>
+    ? IsValidEnumTemplate<Rest, TEnum>
+    : false
+  : true;
+
+/**
+ * Template function that processes {{EnumName.EnumKey}} patterns
+ */
+export function createTemplateProcessor<
+  TEnum extends Record<string, string>,
+  TLanguage extends string,
+>(
+  enumObj: TEnum,
+  translateFn: (
+    key: TEnum[keyof TEnum],
+    vars?: Record<string, string | number>,
+    language?: TLanguage,
+  ) => string,
+  enumName: string,
+) {
+  return function t<T extends string>(
+    str: IsValidEnumTemplate<T, TEnum> extends true ? T : never,
+    language?: TLanguage,
+    ...otherVars: Record<string, string | number>[]
+  ): string {
+    let varIndex = 0;
+    const pattern = new RegExp(`\\{\\{${enumName}\\.(\\w+)\\}\\}`, 'g');
+
+    // First replace enum patterns
+    let result = str.replace(pattern, (match, enumKey) => {
+      const enumValue = enumObj[enumKey as keyof TEnum];
+      if (!enumValue) {
+        return match; // Return original if enum key not found
+      }
+
+      const needsVars = (enumValue as string)
+        .toLowerCase()
+        .endsWith('template');
+      const vars = needsVars ? otherVars[varIndex++] ?? {} : {};
+      return translateFn(enumValue, vars, language);
+    });
+
+    // Then replace any remaining variables from all otherVars
+    const allVars = otherVars.reduce((acc, vars) => ({ ...acc, ...vars }), {});
+    result = result.replace(/\{(\w+)\}/g, (match, varName) => {
+      return allVars[varName] !== undefined ? String(allVars[varName]) : match;
+    });
+
+    return result;
+  };
+}

package/src/timezone.ts

@@ -0,0 +1,20 @@
+import { isValidTimezone } from './utils';
+
+/**
+ * Class representing a validated timezone.
+ */
+export class Timezone {
+  private readonly _timezone: string;
+  constructor(timezone: string) {
+    if (!isValidTimezone(timezone)) {
+      throw new Error(`Invalid timezone: ${timezone}`);
+    }
+    this._timezone = timezone;
+  }
+  /**
+   * Gets the timezone value.
+   */
+  public get value(): string {
+    return this._timezone;
+  }
+}

package/src/translatable.ts

@@ -0,0 +1,15 @@
+import { I18nEngine } from './i18n-engine';
+import { Language } from './default-config';
+
+export class TranslatableError<TStringKey extends string> extends Error {
+  constructor(
+    engine: I18nEngine<TStringKey, Language, any, any>,
+    string: TStringKey,
+    otherVars?: Record<string, string | number>,
+    language?: Language,
+  ) {
+    super(engine.translate(string, otherVars, language));
+    this.name = 'TranslatableError';
+    Object.setPrototypeOf(this, TranslatableError.prototype);
+  }
+}

package/src/translation-engine.ts

@@ -0,0 +1,8 @@
+/**
+ * Minimal interface for translation engines
+ * Allows flexibility in what can be used as a translation engine
+ */
+export interface TranslationEngine<TStringKey extends string = string> {
+  translate: (key: TStringKey, vars?: Record<string, string | number>, lang?: any) => string;
+  safeTranslate: (key: TStringKey, vars?: Record<string, string | number>, lang?: any) => string;
+}

package/src/translation-request.ts

@@ -0,0 +1,12 @@
+/**
+ * Translation request interface
+ */
+export interface TranslationRequest<
+  TStringKeys extends string,
+  TLanguages extends string,
+> {
+  readonly componentId: string;
+  readonly stringKey: TStringKeys;
+  readonly language?: TLanguages;
+  readonly variables?: Record<string, string | number>;
+}

package/src/translation-response.ts

@@ -0,0 +1,8 @@
+/**
+ * Translation response interface
+ */
+export interface TranslationResponse {
+  readonly translation: string;
+  readonly actualLanguage: string;
+  readonly wasFallback: boolean;
+}