@digitaldefiance/i18n-lib 4.1.2 → 4.2.0

package/README.md

@@ -924,6 +924,176 @@ const allValues = getStringKeyValues(AllKeys);
 
 For complete migration guide, see [BRANDED_ENUM_MIGRATION.md](docs/BRANDED_ENUM_MIGRATION.md).
 
+### Branded Enum Translation
+
+The enum translation system supports branded enums from `@digitaldefiance/branded-enum`, enabling automatic name inference and type-safe enum value translations.
+
+#### Why Use Branded Enums for Enum Translation?
+
+- **Automatic Name Inference**: No need to provide an explicit enum name - it's extracted from the branded enum's component ID
+- **Type Safety**: Full TypeScript support for enum values and translations
+- **Consistent Naming**: Enum names in error messages match your component IDs
+- **Unified Pattern**: Use the same branded enum pattern for both string keys and enum translations
+
+#### Registering Branded Enums for Translation
+
+```typescript
+import { createBrandedEnum } from '@digitaldefiance/branded-enum';
+import { I18nEngine, LanguageCodes } from '@digitaldefiance/i18n-lib';
+
+// Create a branded enum
+const Status = createBrandedEnum('status', {
+  Active: 'active',
+  Inactive: 'inactive',
+  Pending: 'pending',
+});
+
+// Create engine
+const engine = new I18nEngine([
+  { id: LanguageCodes.EN_US, name: 'English', code: 'en-US', isDefault: true },
+  { id: LanguageCodes.ES, name: 'Spanish', code: 'es' },
+]);
+
+// Register branded enum - name is automatically inferred as 'status'
+engine.registerEnum(Status, {
+  [LanguageCodes.EN_US]: {
+    active: 'Active',
+    inactive: 'Inactive',
+    pending: 'Pending',
+  },
+  [LanguageCodes.ES]: {
+    active: 'Activo',
+    inactive: 'Inactivo',
+    pending: 'Pendiente',
+  },
+});
+
+// Translate enum values
+engine.translateEnum(Status, Status.Active, LanguageCodes.EN_US); // 'Active'
+engine.translateEnum(Status, Status.Active, LanguageCodes.ES);    // 'Activo'
+```
+
+#### Comparison: Traditional vs Branded Enum Registration
+
+```typescript
+// Traditional enum - requires explicit name
+enum TraditionalStatus {
+  Active = 'active',
+  Inactive = 'inactive',
+}
+engine.registerEnum(TraditionalStatus, translations, 'Status'); // Name required
+
+// Branded enum - name inferred from component ID
+const BrandedStatus = createBrandedEnum('status', {
+  Active: 'active',
+  Inactive: 'inactive',
+});
+engine.registerEnum(BrandedStatus, translations); // Name 'status' inferred automatically
+```
+
+#### Using with PluginI18nEngine
+
+The `PluginI18nEngine` also supports branded enum translation with language validation:
+
+```typescript
+import { PluginI18nEngine, LanguageCodes } from '@digitaldefiance/i18n-lib';
+import { createBrandedEnum } from '@digitaldefiance/branded-enum';
+
+const Priority = createBrandedEnum('priority', {
+  High: 'high',
+  Medium: 'medium',
+  Low: 'low',
+});
+
+const engine = PluginI18nEngine.createInstance('myapp', [
+  { id: LanguageCodes.EN_US, name: 'English', code: 'en-US', isDefault: true },
+  { id: LanguageCodes.FR, name: 'French', code: 'fr' },
+]);
+
+// Register with automatic name inference
+engine.registerEnum(Priority, {
+  [LanguageCodes.EN_US]: {
+    high: 'High Priority',
+    medium: 'Medium Priority',
+    low: 'Low Priority',
+  },
+  [LanguageCodes.FR]: {
+    high: 'Haute Priorité',
+    medium: 'Priorité Moyenne',
+    low: 'Basse Priorité',
+  },
+});
+
+// Translate
+engine.translateEnum(Priority, Priority.High); // Uses current language
+engine.translateEnum(Priority, Priority.High, LanguageCodes.FR); // 'Haute Priorité'
+```
+
+#### Utility Functions
+
+The library provides utility functions for working with branded enums:
+
+```typescript
+import { 
+  isBrandedEnum, 
+  getBrandedEnumComponentId, 
+  getBrandedEnumId 
+} from '@digitaldefiance/i18n-lib';
+
+// Check if an enum is branded
+if (isBrandedEnum(Status)) {
+  // TypeScript knows Status is a branded enum here
+  const componentId = getBrandedEnumComponentId(Status);
+  console.log(componentId); // 'status'
+}
+
+// Get the raw brand ID (includes 'i18n:' prefix for i18n string keys)
+const rawId = getBrandedEnumId(Status); // 'status'
+```
+
+#### Error Messages with Branded Enums
+
+When translation errors occur, the enum name in error messages is automatically derived from the branded enum's component ID:
+
+```typescript
+const Status = createBrandedEnum('user-status', { Active: 'active' });
+engine.registerEnum(Status, { en: { active: 'Active' } });
+
+// If translation fails, error message includes the inferred name:
+// "No translations found for enum: user-status"
+// "Translation missing for enum value 'unknown' in language 'en'"
+```
+
+#### Type Definitions
+
+New types are available for working with branded enum translations:
+
+```typescript
+import type {
+  BrandedEnumTranslation,
+  RegisterableEnum,
+  TranslatableEnumValue,
+} from '@digitaldefiance/i18n-lib';
+
+// Type for branded enum translation maps
+type MyTranslations = BrandedEnumTranslation<typeof Status, 'en' | 'es'>;
+
+// Union type accepting both traditional and branded enums
+function registerAnyEnum<T extends string | number>(
+  enumObj: RegisterableEnum<T>,
+  translations: Record<string, Record<string, string>>,
+): void {
+  // Works with both enum types
+}
+
+// Union type for translatable values
+function translateAnyValue<T extends string | number>(
+  value: TranslatableEnumValue<T>,
+): string {
+  // Works with both traditional and branded enum values
+}
+```
+
 ## Browser Support
 
 - Chrome/Edge: Latest 2 versions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitaldefiance/i18n-lib",
-  "version": "4.1.2",
+  "version": "4.2.0",
   "description": "i18n library with enum translation support",
   "homepage": "https://github.com/Digital-Defiance/i18n-lib",
   "repository": {

package/src/branded-enum-utils.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Branded Enum Utilities for i18n enum translation support
+ *
+ * This module provides utility functions for detecting and extracting
+ * information from branded enums created with `@digitaldefiance/branded-enum`.
+ * These utilities enable the i18n library to seamlessly support both traditional
+ * TypeScript enums and branded enums for enum translations.
+ *
+ * ## Overview
+ *
+ * Branded enums carry runtime metadata (a unique component ID) that enables:
+ * - Automatic enum name inference during registration
+ * - Runtime identification for debugging and logging
+ * - Type-safe translation lookups
+ *
+ * ## Key Functions
+ *
+ * - {@link isBrandedEnum} - Type guard to detect branded enums
+ * - {@link getBrandedEnumComponentId} - Extract component ID (prefix stripped)
+ * - {@link getBrandedEnumId} - Get raw brand ID (for debugging)
+ *
+ * ## Usage with Enum Translation
+ *
+ * These utilities are used internally by `EnumRegistry` and `EnumTranslationRegistry`
+ * to provide automatic name inference and proper translation lookups for branded enums.
+ *
+ * @example
+ * ```typescript
+ * import { createBrandedEnum } from '@digitaldefiance/branded-enum';
+ * import { isBrandedEnum, getBrandedEnumComponentId } from '@digitaldefiance/i18n-lib';
+ *
+ * const Status = createBrandedEnum('status', { Active: 'active', Inactive: 'inactive' });
+ *
+ * if (isBrandedEnum(Status)) {
+ *   const componentId = getBrandedEnumComponentId(Status);
+ *   console.log(componentId); // 'status'
+ * }
+ * ```
+ *
+ * @module branded-enum-utils
+ * @see {@link EnumRegistry} - V2 enum registry with branded enum support
+ * @see {@link EnumTranslationRegistry} - Legacy registry with branded enum support
+ */
+import type { AnyBrandedEnum } from '@digitaldefiance/branded-enum';
+/**
+ * Type guard to check if an object is a branded enum from `@digitaldefiance/branded-enum`.
+ *
+ * Branded enums are identified by having a valid enum ID retrievable via `getEnumId()`.
+ * This function safely checks for this property without throwing errors, making it
+ * suitable for use in conditional logic and type narrowing.
+ *
+ * ## When to Use
+ *
+ * Use this function when you need to:
+ * - Determine if an enum object is branded or traditional
+ * - Conditionally apply branded enum-specific logic
+ * - Type-narrow an unknown enum object
+ *
+ * ## Implementation Details
+ *
+ * The function checks:
+ * 1. The object is not null or undefined
+ * 2. The object is of type 'object'
+ * 3. The object has a valid enum ID (via `getEnumId()`)
+ *
+ * @param obj - The object to check (can be any value)
+ * @returns `true` if the object is a branded enum, `false` otherwise
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createBrandedEnum } from '@digitaldefiance/branded-enum';
+ * import { isBrandedEnum } from '@digitaldefiance/i18n-lib';
+ *
+ * const BrandedStatus = createBrandedEnum('status', { Active: 'active' });
+ * const TraditionalStatus = { Active: 'active' };
+ *
+ * isBrandedEnum(BrandedStatus);     // true
+ * isBrandedEnum(TraditionalStatus); // false
+ * ```
+ *
+ * @example Type narrowing
+ * ```typescript
+ * function processEnum(enumObj: object) {
+ *   if (isBrandedEnum(enumObj)) {
+ *     // TypeScript knows enumObj is AnyBrandedEnum here
+ *     const id = getBrandedEnumComponentId(enumObj);
+ *     console.log(`Processing branded enum: ${id}`);
+ *   } else {
+ *     console.log('Processing traditional enum');
+ *   }
+ * }
+ * ```
+ *
+ * @example Edge cases
+ * ```typescript
+ * isBrandedEnum(null);        // false
+ * isBrandedEnum(undefined);   // false
+ * isBrandedEnum('string');    // false
+ * isBrandedEnum(123);         // false
+ * isBrandedEnum({});          // false
+ * ```
+ *
+ * @see {@link getBrandedEnumComponentId} - Extract component ID from branded enum
+ * @see {@link getBrandedEnumId} - Get raw brand ID from branded enum
+ */
+export declare function isBrandedEnum(obj: unknown): obj is AnyBrandedEnum;
+/**
+ * Extracts the component ID from a branded enum.
+ *
+ * For branded enums created with `createI18nStringKeys()`, the brand ID
+ * is prefixed with `'i18n:'`. This function strips that prefix to return
+ * just the component ID, which is suitable for use as an enum name in
+ * registration and error messages.
+ *
+ * ## Prefix Stripping
+ *
+ * | Input Brand ID | Returned Component ID |
+ * |----------------|----------------------|
+ * | `'i18n:my-component'` | `'my-component'` |
+ * | `'my-component'` | `'my-component'` |
+ * | `'status'` | `'status'` |
+ *
+ * ## When to Use
+ *
+ * Use this function when you need:
+ * - The component ID for automatic enum name inference
+ * - A clean identifier without the `i18n:` prefix
+ * - The default name for error messages
+ *
+ * For debugging purposes where you need the full brand ID including prefix,
+ * use {@link getBrandedEnumId} instead.
+ *
+ * @param enumObj - The object to extract the component ID from
+ * @returns The component ID without the `'i18n:'` prefix, or `null` if not a branded enum
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createI18nStringKeys } from '@digitaldefiance/i18n-lib';
+ *
+ * const MyKeys = createI18nStringKeys('my-component', { A: 'a' });
+ *
+ * getBrandedEnumComponentId(MyKeys); // 'my-component'
+ * getBrandedEnumComponentId({ A: 'a' }); // null (not a branded enum)
+ * ```
+ *
+ * @example With createBrandedEnum (no prefix)
+ * ```typescript
+ * import { createBrandedEnum } from '@digitaldefiance/branded-enum';
+ *
+ * const Status = createBrandedEnum('status', { Active: 'active' });
+ *
+ * getBrandedEnumComponentId(Status); // 'status'
+ * ```
+ *
+ * @example Automatic name inference in registration
+ * ```typescript
+ * const MyKeys = createI18nStringKeys('user-profile', { Title: 'title' });
+ *
+ * // When registering without explicit name, component ID is used
+ * registry.register(MyKeys, translations);
+ * // Internally uses: getBrandedEnumComponentId(MyKeys) → 'user-profile'
+ * ```
+ *
+ * @see {@link isBrandedEnum} - Check if an object is a branded enum
+ * @see {@link getBrandedEnumId} - Get raw brand ID without prefix stripping
+ */
+export declare function getBrandedEnumComponentId(enumObj: unknown): string | null;
+/**
+ * Gets the raw brand/ID from a branded enum without prefix stripping.
+ *
+ * Unlike {@link getBrandedEnumComponentId}, this function returns the full
+ * brand ID including any prefixes (such as `'i18n:'`). This is useful for
+ * debugging, logging, and cases where you need the exact brand identifier.
+ *
+ * ## Comparison with getBrandedEnumComponentId
+ *
+ * | Function | Input Brand | Output |
+ * |----------|-------------|--------|
+ * | `getBrandedEnumId` | `'i18n:my-component'` | `'i18n:my-component'` |
+ * | `getBrandedEnumComponentId` | `'i18n:my-component'` | `'my-component'` |
+ *
+ * ## When to Use
+ *
+ * Use this function when you need:
+ * - The exact brand ID for debugging or logging
+ * - To distinguish between different branded enum sources
+ * - The full identifier including any prefixes
+ *
+ * For registration and user-facing names, use {@link getBrandedEnumComponentId}
+ * which strips the `i18n:` prefix.
+ *
+ * @param enumObj - The object to get the brand ID from
+ * @returns The raw brand ID, or `null` if not a branded enum
+ *
+ * @example Debugging and logging
+ * ```typescript
+ * import { createI18nStringKeys } from '@digitaldefiance/i18n-lib';
+ *
+ * const MyKeys = createI18nStringKeys('my-component', { A: 'a' });
+ *
+ * // For debugging, get the full brand ID
+ * console.log(`Brand ID: ${getBrandedEnumId(MyKeys)}`);
+ * // Output: 'Brand ID: i18n:my-component'
+ *
+ * // For user-facing names, use component ID
+ * console.log(`Component: ${getBrandedEnumComponentId(MyKeys)}`);
+ * // Output: 'Component: my-component'
+ * ```
+ *
+ * @example Comparing branded enums
+ * ```typescript
+ * import { createBrandedEnum } from '@digitaldefiance/branded-enum';
+ * import { createI18nStringKeys } from '@digitaldefiance/i18n-lib';
+ *
+ * const RegularBranded = createBrandedEnum('status', { A: 'a' });
+ * const I18nBranded = createI18nStringKeys('status', { A: 'a' });
+ *
+ * getBrandedEnumId(RegularBranded); // 'status'
+ * getBrandedEnumId(I18nBranded);    // 'i18n:status'
+ * ```
+ *
+ * @see {@link isBrandedEnum} - Check if an object is a branded enum
+ * @see {@link getBrandedEnumComponentId} - Get component ID with prefix stripped
+ */
+export declare function getBrandedEnumId(enumObj: unknown): string | null;
+//# sourceMappingURL=branded-enum-utils.d.ts.map

package/src/branded-enum-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branded-enum-utils.d.ts","sourceRoot":"","sources":["../../../../packages/digitaldefiance-i18n-lib/src/branded-enum-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAGpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAOjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAUzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAMhE"}

package/src/branded-enum-utils.js

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * Branded Enum Utilities for i18n enum translation support
+ *
+ * This module provides utility functions for detecting and extracting
+ * information from branded enums created with `@digitaldefiance/branded-enum`.
+ * These utilities enable the i18n library to seamlessly support both traditional
+ * TypeScript enums and branded enums for enum translations.
+ *
+ * ## Overview
+ *
+ * Branded enums carry runtime metadata (a unique component ID) that enables:
+ * - Automatic enum name inference during registration
+ * - Runtime identification for debugging and logging
+ * - Type-safe translation lookups
+ *
+ * ## Key Functions
+ *
+ * - {@link isBrandedEnum} - Type guard to detect branded enums
+ * - {@link getBrandedEnumComponentId} - Extract component ID (prefix stripped)
+ * - {@link getBrandedEnumId} - Get raw brand ID (for debugging)
+ *
+ * ## Usage with Enum Translation
+ *
+ * These utilities are used internally by `EnumRegistry` and `EnumTranslationRegistry`
+ * to provide automatic name inference and proper translation lookups for branded enums.
+ *
+ * @example
+ * ```typescript
+ * import { createBrandedEnum } from '@digitaldefiance/branded-enum';
+ * import { isBrandedEnum, getBrandedEnumComponentId } from '@digitaldefiance/i18n-lib';
+ *
+ * const Status = createBrandedEnum('status', { Active: 'active', Inactive: 'inactive' });
+ *
+ * if (isBrandedEnum(Status)) {
+ *   const componentId = getBrandedEnumComponentId(Status);
+ *   console.log(componentId); // 'status'
+ * }
+ * ```
+ *
+ * @module branded-enum-utils
+ * @see {@link EnumRegistry} - V2 enum registry with branded enum support
+ * @see {@link EnumTranslationRegistry} - Legacy registry with branded enum support
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBrandedEnum = isBrandedEnum;
+exports.getBrandedEnumComponentId = getBrandedEnumComponentId;
+exports.getBrandedEnumId = getBrandedEnumId;
+const branded_enum_1 = require("@digitaldefiance/branded-enum");
+/**
+ * Type guard to check if an object is a branded enum from `@digitaldefiance/branded-enum`.
+ *
+ * Branded enums are identified by having a valid enum ID retrievable via `getEnumId()`.
+ * This function safely checks for this property without throwing errors, making it
+ * suitable for use in conditional logic and type narrowing.
+ *
+ * ## When to Use
+ *
+ * Use this function when you need to:
+ * - Determine if an enum object is branded or traditional
+ * - Conditionally apply branded enum-specific logic
+ * - Type-narrow an unknown enum object
+ *
+ * ## Implementation Details
+ *
+ * The function checks:
+ * 1. The object is not null or undefined
+ * 2. The object is of type 'object'
+ * 3. The object has a valid enum ID (via `getEnumId()`)
+ *
+ * @param obj - The object to check (can be any value)
+ * @returns `true` if the object is a branded enum, `false` otherwise
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createBrandedEnum } from '@digitaldefiance/branded-enum';
+ * import { isBrandedEnum } from '@digitaldefiance/i18n-lib';
+ *
+ * const BrandedStatus = createBrandedEnum('status', { Active: 'active' });
+ * const TraditionalStatus = { Active: 'active' };
+ *
+ * isBrandedEnum(BrandedStatus);     // true
+ * isBrandedEnum(TraditionalStatus); // false
+ * ```
+ *
+ * @example Type narrowing
+ * ```typescript
+ * function processEnum(enumObj: object) {
+ *   if (isBrandedEnum(enumObj)) {
+ *     // TypeScript knows enumObj is AnyBrandedEnum here
+ *     const id = getBrandedEnumComponentId(enumObj);
+ *     console.log(`Processing branded enum: ${id}`);
+ *   } else {
+ *     console.log('Processing traditional enum');
+ *   }
+ * }
+ * ```
+ *
+ * @example Edge cases
+ * ```typescript
+ * isBrandedEnum(null);        // false
+ * isBrandedEnum(undefined);   // false
+ * isBrandedEnum('string');    // false
+ * isBrandedEnum(123);         // false
+ * isBrandedEnum({});          // false
+ * ```
+ *
+ * @see {@link getBrandedEnumComponentId} - Extract component ID from branded enum
+ * @see {@link getBrandedEnumId} - Get raw brand ID from branded enum
+ */
+function isBrandedEnum(obj) {
+    if (obj === null || obj === undefined || typeof obj !== 'object') {
+        return false;
+    }
+    // Branded enums have an enum ID retrievable via getEnumId
+    const enumId = (0, branded_enum_1.getEnumId)(obj);
+    return enumId !== undefined;
+}
+/**
+ * Extracts the component ID from a branded enum.
+ *
+ * For branded enums created with `createI18nStringKeys()`, the brand ID
+ * is prefixed with `'i18n:'`. This function strips that prefix to return
+ * just the component ID, which is suitable for use as an enum name in
+ * registration and error messages.
+ *
+ * ## Prefix Stripping
+ *
+ * | Input Brand ID | Returned Component ID |
+ * |----------------|----------------------|
+ * | `'i18n:my-component'` | `'my-component'` |
+ * | `'my-component'` | `'my-component'` |
+ * | `'status'` | `'status'` |
+ *
+ * ## When to Use
+ *
+ * Use this function when you need:
+ * - The component ID for automatic enum name inference
+ * - A clean identifier without the `i18n:` prefix
+ * - The default name for error messages
+ *
+ * For debugging purposes where you need the full brand ID including prefix,
+ * use {@link getBrandedEnumId} instead.
+ *
+ * @param enumObj - The object to extract the component ID from
+ * @returns The component ID without the `'i18n:'` prefix, or `null` if not a branded enum
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createI18nStringKeys } from '@digitaldefiance/i18n-lib';
+ *
+ * const MyKeys = createI18nStringKeys('my-component', { A: 'a' });
+ *
+ * getBrandedEnumComponentId(MyKeys); // 'my-component'
+ * getBrandedEnumComponentId({ A: 'a' }); // null (not a branded enum)
+ * ```
+ *
+ * @example With createBrandedEnum (no prefix)
+ * ```typescript
+ * import { createBrandedEnum } from '@digitaldefiance/branded-enum';
+ *
+ * const Status = createBrandedEnum('status', { Active: 'active' });
+ *
+ * getBrandedEnumComponentId(Status); // 'status'
+ * ```
+ *
+ * @example Automatic name inference in registration
+ * ```typescript
+ * const MyKeys = createI18nStringKeys('user-profile', { Title: 'title' });
+ *
+ * // When registering without explicit name, component ID is used
+ * registry.register(MyKeys, translations);
+ * // Internally uses: getBrandedEnumComponentId(MyKeys) → 'user-profile'
+ * ```
+ *
+ * @see {@link isBrandedEnum} - Check if an object is a branded enum
+ * @see {@link getBrandedEnumId} - Get raw brand ID without prefix stripping
+ */
+function getBrandedEnumComponentId(enumObj) {
+    if (!isBrandedEnum(enumObj)) {
+        return null;
+    }
+    const brand = (0, branded_enum_1.getEnumId)(enumObj);
+    if (brand === undefined) {
+        return null;
+    }
+    // Remove 'i18n:' prefix if present (used by createI18nStringKeys)
+    return brand.startsWith('i18n:') ? brand.slice(5) : brand;
+}
+/**
+ * Gets the raw brand/ID from a branded enum without prefix stripping.
+ *
+ * Unlike {@link getBrandedEnumComponentId}, this function returns the full
+ * brand ID including any prefixes (such as `'i18n:'`). This is useful for
+ * debugging, logging, and cases where you need the exact brand identifier.
+ *
+ * ## Comparison with getBrandedEnumComponentId
+ *
+ * | Function | Input Brand | Output |
+ * |----------|-------------|--------|
+ * | `getBrandedEnumId` | `'i18n:my-component'` | `'i18n:my-component'` |
+ * | `getBrandedEnumComponentId` | `'i18n:my-component'` | `'my-component'` |
+ *
+ * ## When to Use
+ *
+ * Use this function when you need:
+ * - The exact brand ID for debugging or logging
+ * - To distinguish between different branded enum sources
+ * - The full identifier including any prefixes
+ *
+ * For registration and user-facing names, use {@link getBrandedEnumComponentId}
+ * which strips the `i18n:` prefix.
+ *
+ * @param enumObj - The object to get the brand ID from
+ * @returns The raw brand ID, or `null` if not a branded enum
+ *
+ * @example Debugging and logging
+ * ```typescript
+ * import { createI18nStringKeys } from '@digitaldefiance/i18n-lib';
+ *
+ * const MyKeys = createI18nStringKeys('my-component', { A: 'a' });
+ *
+ * // For debugging, get the full brand ID
+ * console.log(`Brand ID: ${getBrandedEnumId(MyKeys)}`);
+ * // Output: 'Brand ID: i18n:my-component'
+ *
+ * // For user-facing names, use component ID
+ * console.log(`Component: ${getBrandedEnumComponentId(MyKeys)}`);
+ * // Output: 'Component: my-component'
+ * ```
+ *
+ * @example Comparing branded enums
+ * ```typescript
+ * import { createBrandedEnum } from '@digitaldefiance/branded-enum';
+ * import { createI18nStringKeys } from '@digitaldefiance/i18n-lib';
+ *
+ * const RegularBranded = createBrandedEnum('status', { A: 'a' });
+ * const I18nBranded = createI18nStringKeys('status', { A: 'a' });
+ *
+ * getBrandedEnumId(RegularBranded); // 'status'
+ * getBrandedEnumId(I18nBranded);    // 'i18n:status'
+ * ```
+ *
+ * @see {@link isBrandedEnum} - Check if an object is a branded enum
+ * @see {@link getBrandedEnumComponentId} - Get component ID with prefix stripped
+ */
+function getBrandedEnumId(enumObj) {
+    if (!isBrandedEnum(enumObj)) {
+        return null;
+    }
+    const brand = (0, branded_enum_1.getEnumId)(enumObj);
+    return brand ?? null;
+}
+//# sourceMappingURL=branded-enum-utils.js.map

package/src/branded-enum-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branded-enum-utils.js","sourceRoot":"","sources":["../../../../packages/digitaldefiance-i18n-lib/src/branded-enum-utils.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;;AAkEH,sCAOC;AA8DD,8DAUC;AA2DD,4CAMC;AA/MD,gEAA0D;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,SAAgB,aAAa,CAAC,GAAY;IACxC,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACjE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,0DAA0D;IAC1D,MAAM,MAAM,GAAG,IAAA,wBAAS,EAAC,GAAqB,CAAC,CAAC;IAChD,OAAO,MAAM,KAAK,SAAS,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,SAAgB,yBAAyB,CAAC,OAAgB;IACxD,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,IAAA,wBAAS,EAAC,OAAO,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,kEAAkE;IAClE,OAAO,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,SAAgB,gBAAgB,CAAC,OAAgB;IAC/C,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,IAAA,wBAAS,EAAC,OAAO,CAAC,CAAC;IACjC,OAAO,KAAK,IAAI,IAAI,CAAC;AACvB,CAAC"}