@digitaldefiance/branded-enum 0.0.1 → 0.0.3

package/dist/esm/lib/guards.d.ts

@@ -0,0 +1,297 @@
+/**
+ * Type guards for branded enums.
+ *
+ * Provides runtime type checking and assertion functions
+ * for validating values against branded enums.
+ */
+import { AnyBrandedEnum, EnumValues } from './types.js';
+/**
+ * Checks if a value belongs to a specific branded enum.
+ *
+ * Returns true if and only if:
+ * - enumObj is a valid branded enum (has Symbol metadata)
+ * - value is a string
+ * - value exists in the enum's value Set
+ *
+ * This function provides TypeScript type narrowing - when it returns true,
+ * the value's type is narrowed to the enum's value type.
+ *
+ * @template E - The branded enum type
+ * @param value - The value to check. Can be any type; non-strings return false.
+ * @param enumObj - The branded enum to check against
+ * @returns `true` if value is in the enum (with type narrowing), `false` otherwise.
+ *   Returns `false` for non-string values, null, undefined, or if enumObj
+ *   is not a branded enum.
+ *
+ * @example
+ * // Basic type guard usage
+ * const Status = createBrandedEnum('status', { Active: 'active', Inactive: 'inactive' } as const);
+ *
+ * function handleStatus(value: unknown) {
+ *   if (isFromEnum(value, Status)) {
+ *     // value is narrowed to 'active' | 'inactive'
+ *     console.log('Valid status:', value);
+ *   } else {
+ *     console.log('Invalid status');
+ *   }
+ * }
+ *
+ * @example
+ * // Returns false for non-string values
+ * isFromEnum(123, Status); // false
+ * isFromEnum(null, Status); // false
+ * isFromEnum(undefined, Status); // false
+ *
+ * @example
+ * // Returns false for non-branded enum objects
+ * isFromEnum('active', { Active: 'active' }); // false (not a branded enum)
+ */
+export declare function isFromEnum<E extends AnyBrandedEnum>(value: unknown, enumObj: E): value is EnumValues<E>;
+/**
+ * Asserts that a value belongs to a branded enum, throwing if not.
+ *
+ * Use this function when you want to validate a value and throw an error
+ * if it's invalid, rather than handling the false case manually.
+ *
+ * @template E - The branded enum type
+ * @param value - The value to check. Can be any type.
+ * @param enumObj - The branded enum to check against
+ * @returns The value with narrowed type if valid
+ * @throws {Error} Throws `Error` with message `Second argument is not a branded enum`
+ *   if enumObj is not a valid branded enum.
+ * @throws {Error} Throws `Error` with message `Value "${value}" is not a member of enum "${enumId}"`
+ *   if the value is not found in the enum.
+ *
+ * @example
+ * // Successful assertion
+ * const Status = createBrandedEnum('status', { Active: 'active', Inactive: 'inactive' } as const);
+ * const validated = assertFromEnum('active', Status);
+ * // validated is typed as 'active' | 'inactive'
+ *
+ * @example
+ * // Throws for invalid value
+ * try {
+ *   assertFromEnum('unknown', Status);
+ * } catch (e) {
+ *   console.log(e.message); // 'Value "unknown" is not a member of enum "status"'
+ * }
+ *
+ * @example
+ * // Throws for non-branded enum
+ * try {
+ *   assertFromEnum('active', { Active: 'active' });
+ * } catch (e) {
+ *   console.log(e.message); // 'Second argument is not a branded enum'
+ * }
+ */
+export declare function assertFromEnum<E extends AnyBrandedEnum>(value: unknown, enumObj: E): EnumValues<E>;
+/**
+ * Safely parses a value against a branded enum, returning a default if invalid.
+ *
+ * This is a non-throwing alternative to `assertFromEnum`. Instead of throwing
+ * an error when the value is not in the enum, it returns the provided default value.
+ *
+ * Use this function when you want to handle invalid values gracefully without
+ * try/catch blocks, such as when parsing user input or external data.
+ *
+ * @template E - The branded enum type
+ * @param value - The value to parse. Can be any type; non-strings will return the default.
+ * @param enumObj - The branded enum to validate against
+ * @param defaultValue - The value to return if parsing fails. Must be a valid enum value.
+ * @returns The original value if it exists in the enum, otherwise the default value.
+ *   The return type is narrowed to the enum's value type.
+ *
+ * @example
+ * // Basic usage with default fallback
+ * const Status = createBrandedEnum('status', {
+ *   Active: 'active',
+ *   Inactive: 'inactive',
+ *   Pending: 'pending',
+ * } as const);
+ *
+ * // Valid value returns as-is
+ * parseEnum('active', Status, Status.Pending); // 'active'
+ *
+ * // Invalid value returns default
+ * parseEnum('unknown', Status, Status.Pending); // 'pending'
+ *
+ * // Non-string value returns default
+ * parseEnum(null, Status, Status.Inactive); // 'inactive'
+ * parseEnum(123, Status, Status.Inactive); // 'inactive'
+ *
+ * @example
+ * // Parsing user input safely
+ * function handleUserStatus(input: unknown): void {
+ *   const status = parseEnum(input, Status, Status.Pending);
+ *   // status is guaranteed to be 'active' | 'inactive' | 'pending'
+ *   console.log('Processing status:', status);
+ * }
+ *
+ * @example
+ * // Parsing API response with fallback
+ * interface ApiResponse {
+ *   status?: string;
+ * }
+ *
+ * function processResponse(response: ApiResponse) {
+ *   const status = parseEnum(response.status, Status, Status.Inactive);
+ *   // Handles undefined, null, or invalid status values gracefully
+ *   return { status };
+ * }
+ *
+ * @example
+ * // Chaining with optional values
+ * const userStatus = parseEnum(
+ *   localStorage.getItem('userStatus'),
+ *   Status,
+ *   Status.Active
+ * );
+ */
+export declare function parseEnum<E extends AnyBrandedEnum>(value: unknown, enumObj: E, defaultValue: EnumValues<E>): EnumValues<E>;
+/**
+ * Represents a successful parse result from safeParseEnum.
+ *
+ * @template T - The type of the successfully parsed value
+ */
+export interface SafeParseSuccess<T> {
+    /** Indicates the parse was successful */
+    readonly success: true;
+    /** The validated enum value */
+    readonly value: T;
+}
+/**
+ * Represents a failed parse result from safeParseEnum.
+ *
+ * Contains detailed error information for debugging and user feedback.
+ */
+export interface SafeParseFailure {
+    /** Indicates the parse failed */
+    readonly success: false;
+    /** Detailed error information */
+    readonly error: SafeParseError;
+}
+/**
+ * Detailed error information for a failed parse.
+ */
+export interface SafeParseError {
+    /** Human-readable error message */
+    readonly message: string;
+    /** The code identifying the type of error */
+    readonly code: SafeParseErrorCode;
+    /** The input value that failed validation */
+    readonly input: unknown;
+    /** The enum ID (if available) */
+    readonly enumId?: string;
+    /** The valid values for the enum (if available) */
+    readonly validValues?: readonly string[];
+}
+/**
+ * Error codes for safe parse failures.
+ */
+export type SafeParseErrorCode = 'INVALID_ENUM_OBJECT' | 'INVALID_VALUE_TYPE' | 'VALUE_NOT_IN_ENUM';
+/**
+ * Union type representing the result of safeParseEnum.
+ *
+ * @template T - The type of the successfully parsed value
+ */
+export type SafeParseResult<T> = SafeParseSuccess<T> | SafeParseFailure;
+/**
+ * Safely parses a value against a branded enum, returning a result object.
+ *
+ * This function provides validated deserialization with detailed error information.
+ * Unlike `parseEnum` which returns a default value on failure, or `assertFromEnum`
+ * which throws an error, `safeParseEnum` returns a discriminated union result
+ * that allows for explicit success/failure handling.
+ *
+ * The result is either:
+ * - `{ success: true, value: T }` - The value is valid and typed correctly
+ * - `{ success: false, error: SafeParseError }` - The value is invalid with details
+ *
+ * Error codes:
+ * - `INVALID_ENUM_OBJECT` - The enumObj is not a valid branded enum
+ * - `INVALID_VALUE_TYPE` - The value is not a string
+ * - `VALUE_NOT_IN_ENUM` - The value is a string but not in the enum
+ *
+ * @template E - The branded enum type
+ * @param value - The value to parse. Can be any type.
+ * @param enumObj - The branded enum to validate against
+ * @returns A SafeParseResult containing either the validated value or error details
+ *
+ * @example
+ * // Basic usage with success
+ * const Status = createBrandedEnum('status', {
+ *   Active: 'active',
+ *   Inactive: 'inactive',
+ * } as const);
+ *
+ * const result = safeParseEnum('active', Status);
+ * if (result.success) {
+ *   console.log('Valid status:', result.value); // 'active'
+ * } else {
+ *   console.log('Error:', result.error.message);
+ * }
+ *
+ * @example
+ * // Handling invalid value
+ * const result = safeParseEnum('unknown', Status);
+ * if (!result.success) {
+ *   console.log(result.error.code); // 'VALUE_NOT_IN_ENUM'
+ *   console.log(result.error.message); // 'Value "unknown" is not a member of enum "status"'
+ *   console.log(result.error.validValues); // ['active', 'inactive']
+ * }
+ *
+ * @example
+ * // Handling non-string input
+ * const result = safeParseEnum(123, Status);
+ * if (!result.success) {
+ *   console.log(result.error.code); // 'INVALID_VALUE_TYPE'
+ *   console.log(result.error.message); // 'Expected a string value, received number'
+ * }
+ *
+ * @example
+ * // Parsing API response
+ * interface ApiResponse {
+ *   status?: string;
+ * }
+ *
+ * function processResponse(response: ApiResponse) {
+ *   const result = safeParseEnum(response.status, Status);
+ *   if (result.success) {
+ *     return { status: result.value };
+ *   } else {
+ *     // Log detailed error for debugging
+ *     console.error('Invalid status:', result.error);
+ *     return { status: Status.Inactive }; // fallback
+ *   }
+ * }
+ *
+ * @example
+ * // Form validation with detailed errors
+ * function validateForm(data: Record<string, unknown>) {
+ *   const statusResult = safeParseEnum(data.status, Status);
+ *   const errors: string[] = [];
+ *
+ *   if (!statusResult.success) {
+ *     errors.push(`Status: ${statusResult.error.message}`);
+ *   }
+ *
+ *   return {
+ *     isValid: errors.length === 0,
+ *     errors,
+ *     data: statusResult.success ? { status: statusResult.value } : null,
+ *   };
+ * }
+ *
+ * @example
+ * // Type narrowing with result
+ * const result = safeParseEnum(userInput, Status);
+ * if (result.success) {
+ *   // result.value is typed as 'active' | 'inactive'
+ *   handleStatus(result.value);
+ * } else {
+ *   // result.error is typed as SafeParseError
+ *   showError(result.error.message);
+ * }
+ */
+export declare function safeParseEnum<E extends AnyBrandedEnum>(value: unknown, enumObj: E): SafeParseResult<EnumValues<E>>;
+//# sourceMappingURL=guards.d.ts.map

package/dist/esm/lib/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../src/lib/guards.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,cAAc,EAKd,UAAU,EACX,MAAM,YAAY,CAAC;AAmBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,cAAc,EACjD,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,CAAC,GACT,KAAK,IAAI,UAAU,CAAC,CAAC,CAAC,CAaxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,cAAc,EACrD,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,CAAC,GACT,UAAU,CAAC,CAAC,CAAC,CAaf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,cAAc,EAChD,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,CAAC,EACV,YAAY,EAAE,UAAU,CAAC,CAAC,CAAC,GAC1B,UAAU,CAAC,CAAC,CAAC,CAQf;AAMD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,iCAAiC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,qBAAqB,GACrB,oBAAoB,GACpB,mBAAmB,CAAC;AAExB;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,cAAc,EACpD,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,CAAC,GACT,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAkDhC"}

package/dist/esm/lib/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/guards.ts"],"sourcesContent":["/**\n * Type guards for branded enums.\n *\n * Provides runtime type checking and assertion functions\n * for validating values against branded enums.\n */\n\nimport {\n  AnyBrandedEnum,\n  BrandedEnum,\n  BrandedEnumValue,\n  ENUM_ID,\n  ENUM_VALUES,\n  EnumValues,\n} from './types.js';\n\n/**\n * Checks if an object is a branded enum (has Symbol metadata).\n *\n * @param obj - The object to check\n * @returns true if obj is a branded enum\n */\nfunction isBrandedEnum(obj: unknown): obj is AnyBrandedEnum {\n  return (\n    obj !== null &&\n    typeof obj === 'object' &&\n    ENUM_ID in obj &&\n    ENUM_VALUES in obj &&\n    typeof (obj as AnyBrandedEnum)[ENUM_ID] === 'string' &&\n    (obj as AnyBrandedEnum)[ENUM_VALUES] instanceof Set\n  );\n}\n\n/**\n * Checks if a value belongs to a specific branded enum.\n *\n * Returns true if and only if:\n * - enumObj is a valid branded enum (has Symbol metadata)\n * - value is a string\n * - value exists in the enum's value Set\n *\n * This function provides TypeScript type narrowing - when it returns true,\n * the value's type is narrowed to the enum's value type.\n *\n * @template E - The branded enum type\n * @param value - The value to check. Can be any type; non-strings return false.\n * @param enumObj - The branded enum to check against\n * @returns `true` if value is in the enum (with type narrowing), `false` otherwise.\n *   Returns `false` for non-string values, null, undefined, or if enumObj\n *   is not a branded enum.\n *\n * @example\n * // Basic type guard usage\n * const Status = createBrandedEnum('status', { Active: 'active', Inactive: 'inactive' } as const);\n *\n * function handleStatus(value: unknown) {\n *   if (isFromEnum(value, Status)) {\n *     // value is narrowed to 'active' | 'inactive'\n *     console.log('Valid status:', value);\n *   } else {\n *     console.log('Invalid status');\n *   }\n * }\n *\n * @example\n * // Returns false for non-string values\n * isFromEnum(123, Status); // false\n * isFromEnum(null, Status); // false\n * isFromEnum(undefined, Status); // false\n *\n * @example\n * // Returns false for non-branded enum objects\n * isFromEnum('active', { Active: 'active' }); // false (not a branded enum)\n */\nexport function isFromEnum<E extends AnyBrandedEnum>(\n  value: unknown,\n  enumObj: E\n): value is EnumValues<E> {\n  // Return false for non-string values\n  if (typeof value !== 'string') {\n    return false;\n  }\n\n  // Return false if enumObj is not a branded enum\n  if (!isBrandedEnum(enumObj)) {\n    return false;\n  }\n\n  // Check if value exists in enum's value Set\n  return enumObj[ENUM_VALUES].has(value);\n}\n\n/**\n * Asserts that a value belongs to a branded enum, throwing if not.\n *\n * Use this function when you want to validate a value and throw an error\n * if it's invalid, rather than handling the false case manually.\n *\n * @template E - The branded enum type\n * @param value - The value to check. Can be any type.\n * @param enumObj - The branded enum to check against\n * @returns The value with narrowed type if valid\n * @throws {Error} Throws `Error` with message `Second argument is not a branded enum`\n *   if enumObj is not a valid branded enum.\n * @throws {Error} Throws `Error` with message `Value \"${value}\" is not a member of enum \"${enumId}\"`\n *   if the value is not found in the enum.\n *\n * @example\n * // Successful assertion\n * const Status = createBrandedEnum('status', { Active: 'active', Inactive: 'inactive' } as const);\n * const validated = assertFromEnum('active', Status);\n * // validated is typed as 'active' | 'inactive'\n *\n * @example\n * // Throws for invalid value\n * try {\n *   assertFromEnum('unknown', Status);\n * } catch (e) {\n *   console.log(e.message); // 'Value \"unknown\" is not a member of enum \"status\"'\n * }\n *\n * @example\n * // Throws for non-branded enum\n * try {\n *   assertFromEnum('active', { Active: 'active' });\n * } catch (e) {\n *   console.log(e.message); // 'Second argument is not a branded enum'\n * }\n */\nexport function assertFromEnum<E extends AnyBrandedEnum>(\n  value: unknown,\n  enumObj: E\n): EnumValues<E> {\n  // Check if enumObj is a branded enum\n  if (!isBrandedEnum(enumObj)) {\n    throw new Error('Second argument is not a branded enum');\n  }\n\n  // Check if value is in the enum\n  if (!isFromEnum(value, enumObj)) {\n    const enumId = enumObj[ENUM_ID];\n    throw new Error(`Value \"${value}\" is not a member of enum \"${enumId}\"`);\n  }\n\n  return value as EnumValues<E>;\n}\n\n/**\n * Safely parses a value against a branded enum, returning a default if invalid.\n *\n * This is a non-throwing alternative to `assertFromEnum`. Instead of throwing\n * an error when the value is not in the enum, it returns the provided default value.\n *\n * Use this function when you want to handle invalid values gracefully without\n * try/catch blocks, such as when parsing user input or external data.\n *\n * @template E - The branded enum type\n * @param value - The value to parse. Can be any type; non-strings will return the default.\n * @param enumObj - The branded enum to validate against\n * @param defaultValue - The value to return if parsing fails. Must be a valid enum value.\n * @returns The original value if it exists in the enum, otherwise the default value.\n *   The return type is narrowed to the enum's value type.\n *\n * @example\n * // Basic usage with default fallback\n * const Status = createBrandedEnum('status', {\n *   Active: 'active',\n *   Inactive: 'inactive',\n *   Pending: 'pending',\n * } as const);\n *\n * // Valid value returns as-is\n * parseEnum('active', Status, Status.Pending); // 'active'\n *\n * // Invalid value returns default\n * parseEnum('unknown', Status, Status.Pending); // 'pending'\n *\n * // Non-string value returns default\n * parseEnum(null, Status, Status.Inactive); // 'inactive'\n * parseEnum(123, Status, Status.Inactive); // 'inactive'\n *\n * @example\n * // Parsing user input safely\n * function handleUserStatus(input: unknown): void {\n *   const status = parseEnum(input, Status, Status.Pending);\n *   // status is guaranteed to be 'active' | 'inactive' | 'pending'\n *   console.log('Processing status:', status);\n * }\n *\n * @example\n * // Parsing API response with fallback\n * interface ApiResponse {\n *   status?: string;\n * }\n *\n * function processResponse(response: ApiResponse) {\n *   const status = parseEnum(response.status, Status, Status.Inactive);\n *   // Handles undefined, null, or invalid status values gracefully\n *   return { status };\n * }\n *\n * @example\n * // Chaining with optional values\n * const userStatus = parseEnum(\n *   localStorage.getItem('userStatus'),\n *   Status,\n *   Status.Active\n * );\n */\nexport function parseEnum<E extends AnyBrandedEnum>(\n  value: unknown,\n  enumObj: E,\n  defaultValue: EnumValues<E>\n): EnumValues<E> {\n  // If the value is valid, return it\n  if (isFromEnum(value, enumObj)) {\n    return value;\n  }\n\n  // Otherwise return the default\n  return defaultValue;\n}\n\n// =============================================================================\n// Safe Parse Result Types\n// =============================================================================\n\n/**\n * Represents a successful parse result from safeParseEnum.\n *\n * @template T - The type of the successfully parsed value\n */\nexport interface SafeParseSuccess<T> {\n  /** Indicates the parse was successful */\n  readonly success: true;\n  /** The validated enum value */\n  readonly value: T;\n}\n\n/**\n * Represents a failed parse result from safeParseEnum.\n *\n * Contains detailed error information for debugging and user feedback.\n */\nexport interface SafeParseFailure {\n  /** Indicates the parse failed */\n  readonly success: false;\n  /** Detailed error information */\n  readonly error: SafeParseError;\n}\n\n/**\n * Detailed error information for a failed parse.\n */\nexport interface SafeParseError {\n  /** Human-readable error message */\n  readonly message: string;\n  /** The code identifying the type of error */\n  readonly code: SafeParseErrorCode;\n  /** The input value that failed validation */\n  readonly input: unknown;\n  /** The enum ID (if available) */\n  readonly enumId?: string;\n  /** The valid values for the enum (if available) */\n  readonly validValues?: readonly string[];\n}\n\n/**\n * Error codes for safe parse failures.\n */\nexport type SafeParseErrorCode =\n  | 'INVALID_ENUM_OBJECT'\n  | 'INVALID_VALUE_TYPE'\n  | 'VALUE_NOT_IN_ENUM';\n\n/**\n * Union type representing the result of safeParseEnum.\n *\n * @template T - The type of the successfully parsed value\n */\nexport type SafeParseResult<T> = SafeParseSuccess<T> | SafeParseFailure;\n\n/**\n * Safely parses a value against a branded enum, returning a result object.\n *\n * This function provides validated deserialization with detailed error information.\n * Unlike `parseEnum` which returns a default value on failure, or `assertFromEnum`\n * which throws an error, `safeParseEnum` returns a discriminated union result\n * that allows for explicit success/failure handling.\n *\n * The result is either:\n * - `{ success: true, value: T }` - The value is valid and typed correctly\n * - `{ success: false, error: SafeParseError }` - The value is invalid with details\n *\n * Error codes:\n * - `INVALID_ENUM_OBJECT` - The enumObj is not a valid branded enum\n * - `INVALID_VALUE_TYPE` - The value is not a string\n * - `VALUE_NOT_IN_ENUM` - The value is a string but not in the enum\n *\n * @template E - The branded enum type\n * @param value - The value to parse. Can be any type.\n * @param enumObj - The branded enum to validate against\n * @returns A SafeParseResult containing either the validated value or error details\n *\n * @example\n * // Basic usage with success\n * const Status = createBrandedEnum('status', {\n *   Active: 'active',\n *   Inactive: 'inactive',\n * } as const);\n *\n * const result = safeParseEnum('active', Status);\n * if (result.success) {\n *   console.log('Valid status:', result.value); // 'active'\n * } else {\n *   console.log('Error:', result.error.message);\n * }\n *\n * @example\n * // Handling invalid value\n * const result = safeParseEnum('unknown', Status);\n * if (!result.success) {\n *   console.log(result.error.code); // 'VALUE_NOT_IN_ENUM'\n *   console.log(result.error.message); // 'Value \"unknown\" is not a member of enum \"status\"'\n *   console.log(result.error.validValues); // ['active', 'inactive']\n * }\n *\n * @example\n * // Handling non-string input\n * const result = safeParseEnum(123, Status);\n * if (!result.success) {\n *   console.log(result.error.code); // 'INVALID_VALUE_TYPE'\n *   console.log(result.error.message); // 'Expected a string value, received number'\n * }\n *\n * @example\n * // Parsing API response\n * interface ApiResponse {\n *   status?: string;\n * }\n *\n * function processResponse(response: ApiResponse) {\n *   const result = safeParseEnum(response.status, Status);\n *   if (result.success) {\n *     return { status: result.value };\n *   } else {\n *     // Log detailed error for debugging\n *     console.error('Invalid status:', result.error);\n *     return { status: Status.Inactive }; // fallback\n *   }\n * }\n *\n * @example\n * // Form validation with detailed errors\n * function validateForm(data: Record<string, unknown>) {\n *   const statusResult = safeParseEnum(data.status, Status);\n *   const errors: string[] = [];\n *\n *   if (!statusResult.success) {\n *     errors.push(`Status: ${statusResult.error.message}`);\n *   }\n *\n *   return {\n *     isValid: errors.length === 0,\n *     errors,\n *     data: statusResult.success ? { status: statusResult.value } : null,\n *   };\n * }\n *\n * @example\n * // Type narrowing with result\n * const result = safeParseEnum(userInput, Status);\n * if (result.success) {\n *   // result.value is typed as 'active' | 'inactive'\n *   handleStatus(result.value);\n * } else {\n *   // result.error is typed as SafeParseError\n *   showError(result.error.message);\n * }\n */\nexport function safeParseEnum<E extends AnyBrandedEnum>(\n  value: unknown,\n  enumObj: E\n): SafeParseResult<EnumValues<E>> {\n  // Check if enumObj is a branded enum\n  if (!isBrandedEnum(enumObj)) {\n    return {\n      success: false,\n      error: {\n        message: 'Second argument is not a branded enum',\n        code: 'INVALID_ENUM_OBJECT',\n        input: value,\n      },\n    };\n  }\n\n  const enumId = enumObj[ENUM_ID];\n  const validValues = Array.from(enumObj[ENUM_VALUES]).sort();\n\n  // Check if value is a string\n  if (typeof value !== 'string') {\n    const valueType = value === null ? 'null' : typeof value;\n    return {\n      success: false,\n      error: {\n        message: `Expected a string value, received ${valueType}`,\n        code: 'INVALID_VALUE_TYPE',\n        input: value,\n        enumId,\n        validValues,\n      },\n    };\n  }\n\n  // Check if value is in the enum\n  if (!enumObj[ENUM_VALUES].has(value)) {\n    return {\n      success: false,\n      error: {\n        message: `Value \"${value}\" is not a member of enum \"${enumId}\"`,\n        code: 'VALUE_NOT_IN_ENUM',\n        input: value,\n        enumId,\n        validValues,\n      },\n    };\n  }\n\n  // Success case\n  return {\n    success: true,\n    value: value as EnumValues<E>,\n  };\n}\n"],"names":["ENUM_ID","ENUM_VALUES","isBrandedEnum","obj","Set","isFromEnum","value","enumObj","has","assertFromEnum","Error","enumId","parseEnum","defaultValue","safeParseEnum","success","error","message","code","input","validValues","Array","from","sort","valueType"],"rangeMappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","mappings":"AAAA;;;;;CAKC,GAED,SAIEA,OAAO,EACPC,WAAW,QAEN,aAAa;AAEpB;;;;;CAKC,GACD,SAASC,cAAcC,GAAY;IACjC,OACEA,QAAQ,QACR,OAAOA,QAAQ,YACfH,WAAWG,OACXF,eAAeE,OACf,OAAO,AAACA,GAAsB,CAACH,QAAQ,KAAK,YAC5C,AAACG,GAAsB,CAACF,YAAY,YAAYG;AAEpD;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwCC,GACD,OAAO,SAASC,WACdC,KAAc,EACdC,OAAU;IAEV,qCAAqC;IACrC,IAAI,OAAOD,UAAU,UAAU;QAC7B,OAAO;IACT;IAEA,gDAAgD;IAChD,IAAI,CAACJ,cAAcK,UAAU;QAC3B,OAAO;IACT;IAEA,4CAA4C;IAC5C,OAAOA,OAAO,CAACN,YAAY,CAACO,GAAG,CAACF;AAClC;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCC,GACD,OAAO,SAASG,eACdH,KAAc,EACdC,OAAU;IAEV,qCAAqC;IACrC,IAAI,CAACL,cAAcK,UAAU;QAC3B,MAAM,IAAIG,MAAM;IAClB;IAEA,gCAAgC;IAChC,IAAI,CAACL,WAAWC,OAAOC,UAAU;QAC/B,MAAMI,SAASJ,OAAO,CAACP,QAAQ;QAC/B,MAAM,IAAIU,MAAM,CAAC,OAAO,EAAEJ,MAAM,2BAA2B,EAAEK,OAAO,CAAC,CAAC;IACxE;IAEA,OAAOL;AACT;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6DC,GACD,OAAO,SAASM,UACdN,KAAc,EACdC,OAAU,EACVM,YAA2B;IAE3B,mCAAmC;IACnC,IAAIR,WAAWC,OAAOC,UAAU;QAC9B,OAAOD;IACT;IAEA,+BAA+B;IAC/B,OAAOO;AACT;AA6DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiGC,GACD,OAAO,SAASC,cACdR,KAAc,EACdC,OAAU;IAEV,qCAAqC;IACrC,IAAI,CAACL,cAAcK,UAAU;QAC3B,OAAO;YACLQ,SAAS;YACTC,OAAO;gBACLC,SAAS;gBACTC,MAAM;gBACNC,OAAOb;YACT;QACF;IACF;IAEA,MAAMK,SAASJ,OAAO,CAACP,QAAQ;IAC/B,MAAMoB,cAAcC,MAAMC,IAAI,CAACf,OAAO,CAACN,YAAY,EAAEsB,IAAI;IAEzD,6BAA6B;IAC7B,IAAI,OAAOjB,UAAU,UAAU;QAC7B,MAAMkB,YAAYlB,UAAU,OAAO,SAAS,OAAOA;QACnD,OAAO;YACLS,SAAS;YACTC,OAAO;gBACLC,SAAS,CAAC,kCAAkC,EAAEO,UAAU,CAAC;gBACzDN,MAAM;gBACNC,OAAOb;gBACPK;gBACAS;YACF;QACF;IACF;IAEA,gCAAgC;IAChC,IAAI,CAACb,OAAO,CAACN,YAAY,CAACO,GAAG,CAACF,QAAQ;QACpC,OAAO;YACLS,SAAS;YACTC,OAAO;gBACLC,SAAS,CAAC,OAAO,EAAEX,MAAM,2BAA2B,EAAEK,OAAO,CAAC,CAAC;gBAC/DO,MAAM;gBACNC,OAAOb;gBACPK;gBACAS;YACF;QACF;IACF;IAEA,eAAe;IACf,OAAO;QACLL,SAAS;QACTT,OAAOA;IACT;AACF"}

package/dist/esm/lib/merge.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Enum composition functions for branded enums.
+ *
+ * Enables merging multiple branded enums into a new combined enum
+ * while maintaining type safety and registry tracking.
+ */
+import { AnyBrandedEnum, BrandedEnum } from './types.js';
+/**
+ * Merges multiple branded enums into a new branded enum.
+ *
+ * Creates a new branded enum that contains all key-value pairs from all
+ * source enums. The merged enum is registered in the global registry
+ * as a new independent enum.
+ *
+ * Key collision handling:
+ * - Duplicate keys (same key in multiple enums) throw an error
+ * - Duplicate values (same value in multiple enums) are allowed
+ *
+ * @template T - Tuple of branded enum types being merged
+ * @param newId - Unique identifier for the merged enum. Must not already
+ *   be registered.
+ * @param enums - One or more branded enums to merge
+ * @returns A new branded enum containing all values from source enums
+ * @throws {Error} Throws `Error` with message
+ *   `Cannot merge enums: duplicate key "${key}" found in enums "${enumId1}" and "${enumId2}"`
+ *   if the same key exists in multiple source enums.
+ * @throws {Error} Throws `Error` with message
+ *   `Branded enum with ID "${newId}" already exists` if newId is already registered.
+ * @throws {Error} Throws `Error` with message `All arguments must be branded enums`
+ *   if any argument is not a valid branded enum.
+ *
+ * @example
+ * // Basic merge
+ * const Colors = createBrandedEnum('colors', { Red: 'red', Blue: 'blue' } as const);
+ * const Sizes = createBrandedEnum('sizes', { Small: 'small', Large: 'large' } as const);
+ *
+ * const Combined = mergeEnums('combined', Colors, Sizes);
+ * // Combined has: Red, Blue, Small, Large
+ *
+ * Combined.Red; // 'red'
+ * Combined.Small; // 'small'
+ *
+ * @example
+ * // Duplicate values are allowed
+ * const Status1 = createBrandedEnum('status1', { Active: 'active' } as const);
+ * const Status2 = createBrandedEnum('status2', { Enabled: 'active' } as const);
+ *
+ * const Merged = mergeEnums('merged', Status1, Status2);
+ * // Both Active and Enabled have value 'active' - this is allowed
+ *
+ * @example
+ * // Duplicate keys throw an error
+ * const Enum1 = createBrandedEnum('enum1', { Key: 'value1' } as const);
+ * const Enum2 = createBrandedEnum('enum2', { Key: 'value2' } as const);
+ *
+ * try {
+ *   mergeEnums('merged', Enum1, Enum2);
+ * } catch (e) {
+ *   console.log(e.message);
+ *   // 'Cannot merge enums: duplicate key "Key" found in enums "enum1" and "enum2"'
+ * }
+ */
+export declare function mergeEnums<T extends readonly AnyBrandedEnum[]>(newId: string, ...enums: T): BrandedEnum<Record<string, string>>;
+//# sourceMappingURL=merge.d.ts.map

package/dist/esm/lib/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../../src/lib/merge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,WAAW,EAAwB,MAAM,YAAY,CAAC;AA2B/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,SAAS,cAAc,EAAE,EAC5D,KAAK,EAAE,MAAM,EACb,GAAG,KAAK,EAAE,CAAC,GACV,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA6BrC"}

package/dist/esm/lib/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/merge.ts"],"sourcesContent":["/**\n * Enum composition functions for branded enums.\n *\n * Enables merging multiple branded enums into a new combined enum\n * while maintaining type safety and registry tracking.\n */\n\nimport { AnyBrandedEnum, BrandedEnum, ENUM_ID, ENUM_VALUES } from './types.js';\nimport { createBrandedEnum } from './factory.js';\n\n/**\n * Type helper to extract the values type from a branded enum.\n */\ntype ExtractValues<E> = E extends BrandedEnum<infer T> ? T : never;\n\n/**\n * Type helper to merge multiple branded enum value types into one.\n */\ntype MergedValues<T extends AnyBrandedEnum[]> = {\n  [K in keyof T]: ExtractValues<T[K]>;\n}[number];\n\n/**\n * Checks if an object is a branded enum.\n */\nfunction isBrandedEnum(obj: unknown): obj is AnyBrandedEnum {\n  return (\n    typeof obj === 'object' &&\n    obj !== null &&\n    ENUM_ID in obj &&\n    ENUM_VALUES in obj\n  );\n}\n\n/**\n * Merges multiple branded enums into a new branded enum.\n *\n * Creates a new branded enum that contains all key-value pairs from all\n * source enums. The merged enum is registered in the global registry\n * as a new independent enum.\n *\n * Key collision handling:\n * - Duplicate keys (same key in multiple enums) throw an error\n * - Duplicate values (same value in multiple enums) are allowed\n *\n * @template T - Tuple of branded enum types being merged\n * @param newId - Unique identifier for the merged enum. Must not already\n *   be registered.\n * @param enums - One or more branded enums to merge\n * @returns A new branded enum containing all values from source enums\n * @throws {Error} Throws `Error` with message\n *   `Cannot merge enums: duplicate key \"${key}\" found in enums \"${enumId1}\" and \"${enumId2}\"`\n *   if the same key exists in multiple source enums.\n * @throws {Error} Throws `Error` with message\n *   `Branded enum with ID \"${newId}\" already exists` if newId is already registered.\n * @throws {Error} Throws `Error` with message `All arguments must be branded enums`\n *   if any argument is not a valid branded enum.\n *\n * @example\n * // Basic merge\n * const Colors = createBrandedEnum('colors', { Red: 'red', Blue: 'blue' } as const);\n * const Sizes = createBrandedEnum('sizes', { Small: 'small', Large: 'large' } as const);\n *\n * const Combined = mergeEnums('combined', Colors, Sizes);\n * // Combined has: Red, Blue, Small, Large\n *\n * Combined.Red; // 'red'\n * Combined.Small; // 'small'\n *\n * @example\n * // Duplicate values are allowed\n * const Status1 = createBrandedEnum('status1', { Active: 'active' } as const);\n * const Status2 = createBrandedEnum('status2', { Enabled: 'active' } as const);\n *\n * const Merged = mergeEnums('merged', Status1, Status2);\n * // Both Active and Enabled have value 'active' - this is allowed\n *\n * @example\n * // Duplicate keys throw an error\n * const Enum1 = createBrandedEnum('enum1', { Key: 'value1' } as const);\n * const Enum2 = createBrandedEnum('enum2', { Key: 'value2' } as const);\n *\n * try {\n *   mergeEnums('merged', Enum1, Enum2);\n * } catch (e) {\n *   console.log(e.message);\n *   // 'Cannot merge enums: duplicate key \"Key\" found in enums \"enum1\" and \"enum2\"'\n * }\n */\nexport function mergeEnums<T extends readonly AnyBrandedEnum[]>(\n  newId: string,\n  ...enums: T\n): BrandedEnum<Record<string, string>> {\n  // Collect all key-value pairs, checking for duplicate keys\n  const mergedValues: Record<string, string> = {};\n  const seenKeys = new Map<string, string>(); // key -> source enumId\n\n  for (const enumObj of enums) {\n    if (!isBrandedEnum(enumObj)) {\n      throw new Error('All arguments must be branded enums');\n    }\n\n    const sourceEnumId = enumObj[ENUM_ID];\n\n    // Iterate over enumerable properties (user-defined keys only)\n    for (const [key, value] of Object.entries(enumObj)) {\n      // Check for duplicate keys\n      if (seenKeys.has(key)) {\n        const originalEnumId = seenKeys.get(key);\n        throw new Error(\n          `Cannot merge enums: duplicate key \"${key}\" found in enums \"${originalEnumId}\" and \"${sourceEnumId}\"`\n        );\n      }\n\n      seenKeys.set(key, sourceEnumId);\n      mergedValues[key] = value as string;\n    }\n  }\n\n  // Create and return the new branded enum (this handles registration)\n  return createBrandedEnum(newId, mergedValues) as BrandedEnum<MergedValues<[...T]>>;\n}\n"],"names":["ENUM_ID","ENUM_VALUES","createBrandedEnum","isBrandedEnum","obj","mergeEnums","newId","enums","mergedValues","seenKeys","Map","enumObj","Error","sourceEnumId","key","value","Object","entries","has","originalEnumId","get","set"],"rangeMappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","mappings":"AAAA;;;;;CAKC,GAED,SAAsCA,OAAO,EAAEC,WAAW,QAAQ,aAAa;AAC/E,SAASC,iBAAiB,QAAQ,eAAe;AAcjD;;CAEC,GACD,SAASC,cAAcC,GAAY;IACjC,OACE,OAAOA,QAAQ,YACfA,QAAQ,QACRJ,WAAWI,OACXH,eAAeG;AAEnB;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsDC,GACD,OAAO,SAASC,WACdC,KAAa,EACb,GAAGC,KAAQ;IAEX,2DAA2D;IAC3D,MAAMC,eAAuC,CAAC;IAC9C,MAAMC,WAAW,IAAIC,OAAuB,uBAAuB;IAEnE,KAAK,MAAMC,WAAWJ,MAAO;QAC3B,IAAI,CAACJ,cAAcQ,UAAU;YAC3B,MAAM,IAAIC,MAAM;QAClB;QAEA,MAAMC,eAAeF,OAAO,CAACX,QAAQ;QAErC,8DAA8D;QAC9D,KAAK,MAAM,CAACc,KAAKC,MAAM,IAAIC,OAAOC,OAAO,CAACN,SAAU;YAClD,2BAA2B;YAC3B,IAAIF,SAASS,GAAG,CAACJ,MAAM;gBACrB,MAAMK,iBAAiBV,SAASW,GAAG,CAACN;gBACpC,MAAM,IAAIF,MACR,CAAC,mCAAmC,EAAEE,IAAI,kBAAkB,EAAEK,eAAe,OAAO,EAAEN,aAAa,CAAC,CAAC;YAEzG;YAEAJ,SAASY,GAAG,CAACP,KAAKD;YAClBL,YAAY,CAACM,IAAI,GAAGC;QACtB;IACF;IAEA,qEAAqE;IACrE,OAAOb,kBAAkBI,OAAOE;AAClC"}

package/dist/esm/lib/registry.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Global registry for branded enums.
+ *
+ * Uses globalThis to ensure cross-bundle compatibility - all instances
+ * of the library share the same registry regardless of how they're bundled.
+ */
+import { BrandedEnum, BrandedEnumRegistry } from './types.js';
+/**
+ * Gets the global registry, initializing it lazily if needed.
+ * Uses globalThis for cross-bundle compatibility.
+ *
+ * The registry is shared across all instances of the library, even when
+ * bundled separately or loaded as different module formats (ESM/CJS).
+ *
+ * @returns The global branded enum registry containing all registered enums
+ *   and a value index for reverse lookups.
+ *
+ * @example
+ * const registry = getRegistry();
+ * console.log(registry.enums.size); // Number of registered enums
+ */
+export declare function getRegistry(): BrandedEnumRegistry;
+/**
+ * Registers a branded enum in the global registry.
+ * Also updates the value index for reverse lookups.
+ *
+ * @param enumObj - The branded enum to register
+ * @throws Error if an enum with the same ID is already registered
+ */
+export declare function registerEnum<T extends Record<string, string>>(enumObj: BrandedEnum<T>): void;
+/**
+ * Gets all registered enum IDs.
+ *
+ * Returns an array of all enum IDs that have been registered via
+ * `createBrandedEnum`. Useful for debugging or introspection.
+ *
+ * @returns Array of all registered enum IDs. Returns empty array if no
+ *   enums have been registered.
+ *
+ * @example
+ * createBrandedEnum('colors', { Red: 'red' } as const);
+ * createBrandedEnum('sizes', { Small: 'small' } as const);
+ *
+ * getAllEnumIds(); // ['colors', 'sizes']
+ */
+export declare function getAllEnumIds(): string[];
+/**
+ * Gets a branded enum by its ID.
+ *
+ * Retrieves a previously registered branded enum from the global registry.
+ * Useful when you need to access an enum dynamically by its ID.
+ *
+ * @param enumId - The enum ID to look up
+ * @returns The branded enum object if found, or `undefined` if no enum
+ *   with the given ID has been registered.
+ *
+ * @example
+ * const Status = createBrandedEnum('status', { Active: 'active' } as const);
+ *
+ * const retrieved = getEnumById('status');
+ * console.log(retrieved === Status); // true
+ *
+ * const notFound = getEnumById('nonexistent');
+ * console.log(notFound); // undefined
+ */
+export declare function getEnumById(enumId: string): BrandedEnum<Record<string, string>> | undefined;
+/**
+ * Finds all enum IDs that contain a given value.
+ *
+ * Performs a reverse lookup to find which enums contain a specific value.
+ * Useful for debugging value collisions or routing values to handlers.
+ *
+ * @param value - The string value to search for
+ * @returns Array of enum IDs that contain the value. Returns empty array
+ *   if no enums contain the value.
+ *
+ * @example
+ * // Single enum containing value
+ * createBrandedEnum('colors', { Red: 'red', Blue: 'blue' } as const);
+ * findEnumSources('red'); // ['colors']
+ *
+ * @example
+ * // Multiple enums with same value (collision detection)
+ * createBrandedEnum('status1', { Active: 'active' } as const);
+ * createBrandedEnum('status2', { Enabled: 'active' } as const);
+ * findEnumSources('active'); // ['status1', 'status2']
+ *
+ * @example
+ * // Value not found
+ * findEnumSources('nonexistent'); // []
+ */
+export declare function findEnumSources(value: string): string[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/esm/lib/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/lib/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,WAAW,EACX,mBAAmB,EAKpB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,IAAI,mBAAmB,CAajD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3D,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,GACtB,IAAI,CA6BN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAGxC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,GACb,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAIjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAIvD"}

package/dist/esm/lib/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/registry.ts"],"sourcesContent":["/**\n * Global registry for branded enums.\n *\n * Uses globalThis to ensure cross-bundle compatibility - all instances\n * of the library share the same registry regardless of how they're bundled.\n */\n\nimport {\n  BrandedEnum,\n  BrandedEnumRegistry,\n  RegistryEntry,\n  REGISTRY_KEY,\n  ENUM_ID,\n  ENUM_VALUES,\n} from './types.js';\n\n/**\n * Gets the global registry, initializing it lazily if needed.\n * Uses globalThis for cross-bundle compatibility.\n *\n * The registry is shared across all instances of the library, even when\n * bundled separately or loaded as different module formats (ESM/CJS).\n *\n * @returns The global branded enum registry containing all registered enums\n *   and a value index for reverse lookups.\n *\n * @example\n * const registry = getRegistry();\n * console.log(registry.enums.size); // Number of registered enums\n */\nexport function getRegistry(): BrandedEnumRegistry {\n  const global = globalThis as typeof globalThis & {\n    [REGISTRY_KEY]?: BrandedEnumRegistry;\n  };\n\n  if (!(REGISTRY_KEY in global) || !global[REGISTRY_KEY]) {\n    global[REGISTRY_KEY] = {\n      enums: new Map<string, RegistryEntry>(),\n      valueIndex: new Map<string, Set<string>>(),\n    };\n  }\n\n  return global[REGISTRY_KEY];\n}\n\n/**\n * Registers a branded enum in the global registry.\n * Also updates the value index for reverse lookups.\n *\n * @param enumObj - The branded enum to register\n * @throws Error if an enum with the same ID is already registered\n */\nexport function registerEnum<T extends Record<string, string>>(\n  enumObj: BrandedEnum<T>\n): void {\n  const registry = getRegistry();\n  const enumId = enumObj[ENUM_ID];\n  const values = enumObj[ENUM_VALUES];\n\n  // Check for duplicate ID\n  if (registry.enums.has(enumId)) {\n    throw new Error(`Branded enum with ID \"${enumId}\" already exists`);\n  }\n\n  // Create registry entry\n  const entry: RegistryEntry = {\n    enumId,\n    enumObj: enumObj as BrandedEnum<Record<string, string>>,\n    values,\n  };\n\n  // Add to enums map\n  registry.enums.set(enumId, entry);\n\n  // Update value index for reverse lookups\n  for (const value of values) {\n    let enumIds = registry.valueIndex.get(value);\n    if (!enumIds) {\n      enumIds = new Set<string>();\n      registry.valueIndex.set(value, enumIds);\n    }\n    enumIds.add(enumId);\n  }\n}\n\n/**\n * Gets all registered enum IDs.\n *\n * Returns an array of all enum IDs that have been registered via\n * `createBrandedEnum`. Useful for debugging or introspection.\n *\n * @returns Array of all registered enum IDs. Returns empty array if no\n *   enums have been registered.\n *\n * @example\n * createBrandedEnum('colors', { Red: 'red' } as const);\n * createBrandedEnum('sizes', { Small: 'small' } as const);\n *\n * getAllEnumIds(); // ['colors', 'sizes']\n */\nexport function getAllEnumIds(): string[] {\n  const registry = getRegistry();\n  return Array.from(registry.enums.keys());\n}\n\n/**\n * Gets a branded enum by its ID.\n *\n * Retrieves a previously registered branded enum from the global registry.\n * Useful when you need to access an enum dynamically by its ID.\n *\n * @param enumId - The enum ID to look up\n * @returns The branded enum object if found, or `undefined` if no enum\n *   with the given ID has been registered.\n *\n * @example\n * const Status = createBrandedEnum('status', { Active: 'active' } as const);\n *\n * const retrieved = getEnumById('status');\n * console.log(retrieved === Status); // true\n *\n * const notFound = getEnumById('nonexistent');\n * console.log(notFound); // undefined\n */\nexport function getEnumById(\n  enumId: string\n): BrandedEnum<Record<string, string>> | undefined {\n  const registry = getRegistry();\n  const entry = registry.enums.get(enumId);\n  return entry?.enumObj;\n}\n\n/**\n * Finds all enum IDs that contain a given value.\n *\n * Performs a reverse lookup to find which enums contain a specific value.\n * Useful for debugging value collisions or routing values to handlers.\n *\n * @param value - The string value to search for\n * @returns Array of enum IDs that contain the value. Returns empty array\n *   if no enums contain the value.\n *\n * @example\n * // Single enum containing value\n * createBrandedEnum('colors', { Red: 'red', Blue: 'blue' } as const);\n * findEnumSources('red'); // ['colors']\n *\n * @example\n * // Multiple enums with same value (collision detection)\n * createBrandedEnum('status1', { Active: 'active' } as const);\n * createBrandedEnum('status2', { Enabled: 'active' } as const);\n * findEnumSources('active'); // ['status1', 'status2']\n *\n * @example\n * // Value not found\n * findEnumSources('nonexistent'); // []\n */\nexport function findEnumSources(value: string): string[] {\n  const registry = getRegistry();\n  const enumIds = registry.valueIndex.get(value);\n  return enumIds ? Array.from(enumIds) : [];\n}\n"],"names":["REGISTRY_KEY","ENUM_ID","ENUM_VALUES","getRegistry","global","globalThis","enums","Map","valueIndex","registerEnum","enumObj","registry","enumId","values","has","Error","entry","set","value","enumIds","get","Set","add","getAllEnumIds","Array","from","keys","getEnumById","findEnumSources"],"rangeMappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","mappings":"AAAA;;;;;CAKC,GAED,SAIEA,YAAY,EACZC,OAAO,EACPC,WAAW,QACN,aAAa;AAEpB;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASC;IACd,MAAMC,SAASC;IAIf,IAAI,CAAEL,CAAAA,gBAAgBI,MAAK,KAAM,CAACA,MAAM,CAACJ,aAAa,EAAE;QACtDI,MAAM,CAACJ,aAAa,GAAG;YACrBM,OAAO,IAAIC;YACXC,YAAY,IAAID;QAClB;IACF;IAEA,OAAOH,MAAM,CAACJ,aAAa;AAC7B;AAEA;;;;;;CAMC,GACD,OAAO,SAASS,aACdC,OAAuB;IAEvB,MAAMC,WAAWR;IACjB,MAAMS,SAASF,OAAO,CAACT,QAAQ;IAC/B,MAAMY,SAASH,OAAO,CAACR,YAAY;IAEnC,yBAAyB;IACzB,IAAIS,SAASL,KAAK,CAACQ,GAAG,CAACF,SAAS;QAC9B,MAAM,IAAIG,MAAM,CAAC,sBAAsB,EAAEH,OAAO,gBAAgB,CAAC;IACnE;IAEA,wBAAwB;IACxB,MAAMI,QAAuB;QAC3BJ;QACAF,SAASA;QACTG;IACF;IAEA,mBAAmB;IACnBF,SAASL,KAAK,CAACW,GAAG,CAACL,QAAQI;IAE3B,yCAAyC;IACzC,KAAK,MAAME,SAASL,OAAQ;QAC1B,IAAIM,UAAUR,SAASH,UAAU,CAACY,GAAG,CAACF;QACtC,IAAI,CAACC,SAAS;YACZA,UAAU,IAAIE;YACdV,SAASH,UAAU,CAACS,GAAG,CAACC,OAAOC;QACjC;QACAA,QAAQG,GAAG,CAACV;IACd;AACF;AAEA;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASW;IACd,MAAMZ,WAAWR;IACjB,OAAOqB,MAAMC,IAAI,CAACd,SAASL,KAAK,CAACoB,IAAI;AACvC;AAEA;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,SAASC,YACdf,MAAc;IAEd,MAAMD,WAAWR;IACjB,MAAMa,QAAQL,SAASL,KAAK,CAACc,GAAG,CAACR;IACjC,OAAOI,OAAON;AAChB;AAEA;;;;;;;;;;;;;;;;;;;;;;;;CAwBC,GACD,OAAO,SAASkB,gBAAgBV,KAAa;IAC3C,MAAMP,WAAWR;IACjB,MAAMgB,UAAUR,SAASH,UAAU,CAACY,GAAG,CAACF;IACxC,OAAOC,UAAUK,MAAMC,IAAI,CAACN,WAAW,EAAE;AAC3C"}