@digitaldefiance/i18n-lib 1.0.32 → 1.1.0

package/dist/registry-error.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegistryError = void 0;
+const core_string_key_1 = require("./core-string-key");
+const registry_error_type_1 = require("./registry-error-type");
+const typed_error_1 = require("./typed-error");
+/**
+ * Reason map for registry errors
+ */
+const REGISTRY_ERROR_REASON_MAP = {
+    [registry_error_type_1.RegistryErrorType.ComponentNotFound]: core_string_key_1.CoreStringKey.Error_ComponentNotFoundTemplate,
+    [registry_error_type_1.RegistryErrorType.DuplicateComponent]: core_string_key_1.CoreStringKey.Error_DuplicateComponentTemplate,
+    [registry_error_type_1.RegistryErrorType.DuplicateLanguage]: core_string_key_1.CoreStringKey.Error_DuplicateLanguageTemplate,
+    [registry_error_type_1.RegistryErrorType.IncompleteRegistration]: core_string_key_1.CoreStringKey.Error_IncompleteRegistrationTemplate,
+    [registry_error_type_1.RegistryErrorType.LanguageNotFound]: core_string_key_1.CoreStringKey.Error_LanguageNotFoundTemplate,
+    [registry_error_type_1.RegistryErrorType.StringKeyNotFound]: core_string_key_1.CoreStringKey.Error_StringKeyNotFoundTemplate,
+    [registry_error_type_1.RegistryErrorType.ValidationFailed]: core_string_key_1.CoreStringKey.Error_ValidationFailedTemplate,
+};
+/**
+ * Registry error class that can work with plugin engines
+ */
+class RegistryError extends Error {
+    constructor(type, message, metadata) {
+        super(message);
+        this.type = type;
+        this.metadata = metadata;
+        this.name = 'RegistryError';
+    }
+    /**
+     * Create a registry error with translation support
+     */
+    static createWithEngine(engine, type, variables, language, metadata) {
+        const error = (0, typed_error_1.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, message, metadata) {
+        return new RegistryError(type, message, metadata);
+    }
+}
+exports.RegistryError = RegistryError;

package/dist/translation-request.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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/dist/translation-request.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/translation-response.d.ts

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

package/dist/translation-response.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/typed-error.d.ts

@@ -1,11 +1,36 @@
 import { Language, StringKey } from './default-config';
 import { I18nEngine } from './i18n-engine';
+import { CoreLanguage } from './core-language';
+import { CoreStringKey } from './core-string-key';
+import { PluginI18nEngine } from './plugin-i18n-engine';
+/**
+ * Interface for engines that can translate strings (unified interface)
+ */
+export interface TranslationEngine {
+    safeTranslate(componentId: string, stringKey: string, variables?: Record<string, string | number>, language?: string): string;
+}
 /**
  * Type constraint to ensure reasonMap has entries for all enum values
  */
-type CompleteReasonMap<TEnum extends Record<string, string | number>, TStringKey extends string> = Record<TEnum[keyof TEnum], TStringKey>;
+export type CompleteReasonMap<TEnum extends Record<string, string | number>, TStringKey extends string> = Record<TEnum[keyof TEnum], TStringKey>;
+/**
+ * Base typed error class with common patterns
+ */
+export declare abstract class BaseTypedError<TEnum extends Record<string, string>, TStringKey extends string> extends Error {
+    readonly type: TEnum[keyof TEnum];
+    readonly metadata?: Record<string, any> | undefined;
+    constructor(type: TEnum[keyof TEnum], message: string, metadata?: Record<string, any> | undefined);
+    /**
+     * Create a simple typed error without engine dependency
+     */
+    static createSimple<TEnum extends Record<string, string>, TStringKey extends string, TError extends BaseTypedError<TEnum, TStringKey>>(this: new (type: TEnum[keyof TEnum], message: string, metadata?: Record<string, any>) => TError, type: TEnum[keyof TEnum], message: string, metadata?: Record<string, any>): TError;
+    /**
+     * Create a typed error with translation support
+     */
+    static createTranslated<TEnum extends Record<string, string>, TStringKey extends string, TError extends BaseTypedError<TEnum, TStringKey>>(this: new (type: TEnum[keyof TEnum], message: string, metadata?: Record<string, any>) => TError, engine: TranslationEngine, componentId: string, type: TEnum[keyof TEnum], reasonMap: CompleteReasonMap<TEnum, TStringKey>, variables?: Record<string, string | number>, language?: string, metadata?: Record<string, any>): TError;
+}
 /**
- * Type-safe TypedError that ensures complete enum coverage
+ * Legacy TypedError that ensures complete enum coverage (for backward compatibility)
  */
 export declare abstract class TypedError<TEnum extends Record<string, string>, TStringKey extends string = StringKey> extends Error {
     readonly type: TEnum[keyof TEnum];
@@ -14,4 +39,39 @@ export declare abstract class TypedError<TEnum extends Record<string, string>, T
     readonly otherVars?: Record<string, string | number> | undefined;
     constructor(engine: I18nEngine<TStringKey, Language, Record<string, any>, string>, type: TEnum[keyof TEnum], reasonMap: CompleteReasonMap<TEnum, TStringKey>, language?: Language | undefined, otherVars?: Record<string, string | number> | undefined);
 }
-export type { CompleteReasonMap };
+/**
+ * Plugin-based TypedError that works with the new component registration system
+ */
+export declare abstract class PluginTypedError<TEnum extends Record<string, string>, TStringKey extends string, TLanguages extends string = CoreLanguage> extends Error {
+    readonly componentId: string;
+    readonly type: TEnum[keyof TEnum];
+    readonly reasonMap: CompleteReasonMap<TEnum, TStringKey>;
+    readonly language?: TLanguages | undefined;
+    readonly otherVars?: Record<string, string | number> | undefined;
+    constructor(engine: PluginI18nEngine<TLanguages>, componentId: string, type: TEnum[keyof TEnum], reasonMap: CompleteReasonMap<TEnum, TStringKey>, language?: TLanguages | undefined, otherVars?: Record<string, string | number> | undefined);
+}
+/**
+ * Core system TypedError using the core component strings
+ */
+export declare abstract class CoreTypedError<TEnum extends Record<string, string>> extends Error {
+    readonly type: TEnum[keyof TEnum];
+    readonly reasonMap: CompleteReasonMap<TEnum, CoreStringKey>;
+    readonly language?: CoreLanguage | undefined;
+    readonly otherVars?: Record<string, string | number> | undefined;
+    constructor(engine: PluginI18nEngine<CoreLanguage>, type: TEnum[keyof TEnum], reasonMap: CompleteReasonMap<TEnum, CoreStringKey>, language?: CoreLanguage | undefined, otherVars?: Record<string, string | number> | undefined);
+}
+/**
+ * Helper function to create a plugin-based TypedError with automatic engine detection
+ */
+export declare function createPluginTypedError<TEnum extends Record<string, string>, TStringKey extends string, TLanguages extends string = CoreLanguage>(componentId: string, type: TEnum[keyof TEnum], reasonMap: CompleteReasonMap<TEnum, TStringKey>, otherVars?: Record<string, string | number>, language?: TLanguages, instanceKey?: string): Error;
+/**
+ * Helper function to create a core system TypedError with automatic engine detection
+ */
+export declare function createCoreTypedError<TEnum extends Record<string, string>>(type: TEnum[keyof TEnum], reasonMap: CompleteReasonMap<TEnum, CoreStringKey>, otherVars?: Record<string, string | number>, language?: CoreLanguage, instanceKey?: string): Error;
+/**
+ * Create a simple error with translation support (generalized pattern from RegistryError)
+ */
+export declare function createTranslatedError<TEnum extends Record<string, string>, TStringKey extends string>(engine: TranslationEngine, componentId: string, type: TEnum[keyof TEnum], reasonMap: Record<TEnum[keyof TEnum], TStringKey>, variables?: Record<string, string | number>, language?: string, metadata?: Record<string, any>, errorName?: string): Error;
+/**
+ * Example usage of the new plugin-based TypedError system
+ */

package/dist/typed-error.js

@@ -1,9 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TypedError = void 0;
+exports.CoreTypedError = exports.PluginTypedError = exports.TypedError = exports.BaseTypedError = void 0;
+exports.createPluginTypedError = createPluginTypedError;
+exports.createCoreTypedError = createCoreTypedError;
+exports.createTranslatedError = createTranslatedError;
+// Legacy imports (for backward compatibility)
 const default_config_1 = require("./default-config");
+const core_string_key_1 = require("./core-string-key");
+const plugin_i18n_engine_1 = require("./plugin-i18n-engine");
 /**
- * Type-safe TypedError that ensures complete enum coverage
+ * Base typed error class with common patterns
+ */
+class BaseTypedError extends Error {
+    constructor(type, message, metadata) {
+        super(message);
+        this.type = type;
+        this.metadata = metadata;
+        this.name = this.constructor.name;
+    }
+    /**
+     * Create a simple typed error without engine dependency
+     */
+    static createSimple(type, message, metadata) {
+        return new this(type, message, metadata);
+    }
+    /**
+     * Create a typed error with translation support
+     */
+    static createTranslated(engine, componentId, type, reasonMap, variables, language, metadata) {
+        const key = reasonMap[type];
+        let message;
+        if (key && engine) {
+            // Try to translate the error message using the engine
+            message = engine.safeTranslate(componentId, key, variables, language);
+        }
+        else {
+            // Fallback to a basic English message
+            message = `Error: ${type}${metadata ? ` - ${JSON.stringify(metadata)}` : ''}`;
+        }
+        return new this(type, message, metadata);
+    }
+}
+exports.BaseTypedError = BaseTypedError;
+/**
+ * Legacy TypedError that ensures complete enum coverage (for backward compatibility)
  */
 class TypedError extends Error {
     constructor(engine, type, reasonMap, language, otherVars) {
@@ -19,3 +59,191 @@ class TypedError extends Error {
     }
 }
 exports.TypedError = TypedError;
+/**
+ * Plugin-based TypedError that works with the new component registration system
+ */
+class PluginTypedError extends Error {
+    constructor(engine, componentId, type, reasonMap, language, otherVars) {
+        const key = reasonMap[type];
+        // If key is not found in the reason map, use core error message
+        if (!key) {
+            const errorMsg = engine.safeTranslate('core', core_string_key_1.CoreStringKey.Error_StringKeyNotFoundTemplate, {
+                stringKey: String(type),
+                componentId: componentId,
+            }, language);
+            throw new Error(errorMsg);
+        }
+        // Translate the error message using the component and string key
+        const translatedMessage = engine.safeTranslate(componentId, key, otherVars, language);
+        super(translatedMessage);
+        this.componentId = componentId;
+        this.type = type;
+        this.reasonMap = reasonMap;
+        this.language = language;
+        this.otherVars = otherVars;
+        this.name = this.constructor.name;
+    }
+}
+exports.PluginTypedError = PluginTypedError;
+/**
+ * Core system TypedError using the core component strings
+ */
+class CoreTypedError extends Error {
+    constructor(engine, type, reasonMap, language, otherVars) {
+        const key = reasonMap[type];
+        // If key is not found in the reason map, use a fallback error
+        if (!key) {
+            const errorMsg = engine.safeTranslate('core', core_string_key_1.CoreStringKey.Error_StringKeyNotFoundTemplate, {
+                stringKey: String(type),
+                componentId: 'core',
+            }, language);
+            throw new Error(errorMsg);
+        }
+        // Translate the error message using the core component
+        const translatedMessage = engine.safeTranslate('core', key, otherVars, language);
+        super(translatedMessage);
+        this.type = type;
+        this.reasonMap = reasonMap;
+        this.language = language;
+        this.otherVars = otherVars;
+        this.name = this.constructor.name;
+    }
+}
+exports.CoreTypedError = CoreTypedError;
+/**
+ * Helper function to create a plugin-based TypedError with automatic engine detection
+ */
+function createPluginTypedError(componentId, type, reasonMap, otherVars, language, instanceKey) {
+    const engine = plugin_i18n_engine_1.PluginI18nEngine.getInstance(instanceKey);
+    return new (class extends PluginTypedError {
+        constructor() {
+            super(engine, componentId, type, reasonMap, language, otherVars);
+        }
+    })();
+}
+/**
+ * Helper function to create a core system TypedError with automatic engine detection
+ */
+function createCoreTypedError(type, reasonMap, otherVars, language, instanceKey) {
+    const engine = plugin_i18n_engine_1.PluginI18nEngine.getInstance(instanceKey);
+    return new (class extends CoreTypedError {
+        constructor() {
+            super(engine, type, reasonMap, language, otherVars);
+        }
+    })();
+}
+/**
+ * Create a simple error with translation support (generalized pattern from RegistryError)
+ */
+function createTranslatedError(engine, componentId, type, reasonMap, variables, language, metadata, errorName) {
+    const key = reasonMap[type];
+    let message;
+    if (key && engine) {
+        try {
+            // Try to translate the error message using the engine
+            message = engine.safeTranslate(componentId, key, variables, language);
+        }
+        catch (translationError) {
+            // Fallback if translation fails
+            message = `Error: ${type}${metadata ? ` - ${JSON.stringify(metadata)}` : ''}`;
+        }
+    }
+    else {
+        // Fallback to a basic English message
+        message = `Error: ${type}${metadata ? ` - ${JSON.stringify(metadata)}` : ''}`;
+    }
+    const error = new Error(message);
+    error.name = errorName || 'TranslatedError';
+    error.type = type;
+    error.metadata = metadata;
+    return error;
+}
+/**
+ * Example usage of the new plugin-based TypedError system
+ */
+// Example 1: Core system error using CoreStringKey
+/*
+enum DatabaseErrorType {
+  ConnectionFailed = 'connectionFailed',
+  QueryTimeout = 'queryTimeout',
+  AccessDenied = 'accessDenied'
+}
+
+const coreErrorReasonMap: CompleteReasonMap<typeof DatabaseErrorType, CoreStringKey> = {
+  [DatabaseErrorType.ConnectionFailed]: CoreStringKey.Error_NetworkError,
+  [DatabaseErrorType.QueryTimeout]: CoreStringKey.Error_InternalServer,
+  [DatabaseErrorType.AccessDenied]: CoreStringKey.Error_AccessDenied
+};
+
+class DatabaseError extends CoreTypedError<typeof DatabaseErrorType> {
+  constructor(
+    engine: PluginI18nEngine<CoreLanguage>,
+    type: DatabaseErrorType,
+    otherVars?: Record<string, string | number>,
+    language?: CoreLanguage
+  ) {
+    super(engine, type, coreErrorReasonMap, language, otherVars);
+  }
+}
+
+// Usage:
+// const engine = PluginI18nEngine.getInstance<CoreLanguage>();
+// throw new DatabaseError(engine, DatabaseErrorType.ConnectionFailed);
+*/
+// Example 2: Custom component error with custom strings
+/*
+enum UserErrorType {
+  UserNotFound = 'userNotFound',
+  InvalidCredentials = 'invalidCredentials',
+  AccountLocked = 'accountLocked'
+}
+
+enum UserErrorStringKey {
+  UserNotFoundMessage = 'userNotFoundMessage',
+  InvalidCredentialsMessage = 'invalidCredentialsMessage',
+  AccountLockedMessage = 'accountLockedMessage'
+}
+
+const userErrorReasonMap: CompleteReasonMap<typeof UserErrorType, UserErrorStringKey> = {
+  [UserErrorType.UserNotFound]: UserErrorStringKey.UserNotFoundMessage,
+  [UserErrorType.InvalidCredentials]: UserErrorStringKey.InvalidCredentialsMessage,
+  [UserErrorType.AccountLocked]: UserErrorStringKey.AccountLockedMessage
+};
+
+class UserError extends PluginTypedError<typeof UserErrorType, UserErrorStringKey, CoreLanguage> {
+  constructor(
+    engine: PluginI18nEngine<CoreLanguage>,
+    type: UserErrorType,
+    otherVars?: Record<string, string | number>,
+    language?: CoreLanguage
+  ) {
+    super(engine, 'user-system', type, userErrorReasonMap, language, otherVars);
+  }
+}
+
+// Usage:
+// const engine = PluginI18nEngine.getInstance<CoreLanguage>();
+// throw new UserError(engine, UserErrorType.UserNotFound, { username: 'john_doe' });
+*/
+// Example 3: Using helper functions for simpler error creation
+/*
+// Define your error types and mappings
+enum ApiErrorType {
+  Timeout = 'timeout',
+  NotFound = 'notFound'
+}
+
+const apiErrorMap: CompleteReasonMap<typeof ApiErrorType, CoreStringKey> = {
+  [ApiErrorType.Timeout]: CoreStringKey.Error_NetworkError,
+  [ApiErrorType.NotFound]: CoreStringKey.Error_NotFound
+};
+
+// Create errors using helper functions
+function throwApiError(type: ApiErrorType, vars?: Record<string, string | number>) {
+  throw createCoreTypedError(type, apiErrorMap, vars);
+}
+
+// Usage:
+// throwApiError(ApiErrorType.NotFound, { resource: 'user' });
+*/
+// Export the type for external use (already exported above)

package/dist/types.d.ts

@@ -1,5 +1,6 @@
-import { CurrencyCode } from './currency-code';
-import { Timezone } from './timezone';
+import { ComponentDefinition } from './component-definition';
+import { ComponentRegistration } from './component-registration';
+import { LanguageDefinition } from './language-definition';
 /**
  * Standard language contexts
  */
@@ -33,33 +34,29 @@ export type LanguageCodeCollection<TLanguage extends string> = Partial<Record<TL
  */
 export type EnumTranslationMap<TEnum extends string | number, TLanguage extends string> = Partial<Record<TLanguage, Partial<Record<TEnum, string>>>>;
 /**
- * I18n configuration interface
- */
-export interface I18nConfig<TStringKey extends string, TLanguage extends string, TConstants extends Record<string, any> = Record<string, any>, TTranslationContext extends string = LanguageContext> {
-    stringNames: TStringKey[];
-    strings: MasterStringsCollection<TStringKey, TLanguage>;
-    defaultLanguage: TLanguage;
-    defaultTranslationContext: TTranslationContext;
-    defaultCurrencyCode: CurrencyCode;
-    languageCodes: LanguageCodeCollection<TLanguage>;
-    languages: TLanguage[];
-    constants?: TConstants;
-    enumName?: string;
-    enumObj?: Record<string, TStringKey>;
-    timezone: Timezone;
-    adminTimezone: Timezone;
-}
-/**
- * I18n context interface
- */
-export interface I18nContext<TLanguage extends string, TTranslationContext extends string = LanguageContext> {
-    language: TLanguage;
-    adminLanguage: TLanguage;
-    currencyCode: CurrencyCode;
-    currentContext: TTranslationContext;
-    timezone: Timezone;
-    adminTimezone: Timezone;
-}
+ * 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
  */
@@ -72,6 +69,22 @@ export type EnumTranslation<T extends string | number> = {
 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;
+/**
+ * Type utility to create a strongly typed component registration
+ */
+export type CreateComponentRegistration<TComponent extends ComponentDefinition<any>, TLanguages extends string> = ComponentRegistration<ExtractStringKeys<TComponent>, TLanguages>;
+/**
+ * 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
  */

package/dist/validation-config.d.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/dist/validation-config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/validation-result.d.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/dist/validation-result.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@digitaldefiance/i18n-lib",
-  "version": "1.0.32",
+  "version": "1.1.0",
   "description": "Generic i18n library with enum translation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "yarn tsc",
     "test": "yarn jest --detectOpenHandles",
+    "test:stream": "yarn jest --detectOpenHandles --runInBand --outputStyle=stream",
     "lint": "eslint src/**/*.ts tests/**/*.ts",
     "lint:fix": "eslint src/**/*.ts tests/**/*.ts --fix",
     "prettier:check": "prettier --check 'src/**/*.{ts,tsx}' 'tests/**/*.{ts,tsx}'",