@digitaldefiance/branded-enum 0.0.1 → 0.0.2

package/dist/lib/advanced.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../../src/lib/advanced.ts"],"names":[],"mappings":"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"}

package/dist/lib/branded-enum.d.ts

@@ -0,0 +1,2 @@
+export declare function brandedEnum(): string;
+//# sourceMappingURL=branded-enum.d.ts.map

package/dist/lib/branded-enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branded-enum.d.ts","sourceRoot":"","sources":["../../src/lib/branded-enum.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}

package/dist/lib/decorators.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Decorators for branded enums.
+ *
+ * Provides runtime validation decorators for class properties
+ * that should only accept values from branded enums.
+ */
+import { AnyBrandedEnum, BrandedEnum, EnumConsumerEntry } from './types.js';
+/**
+ * Options for the EnumValue decorator.
+ */
+export interface EnumValueOptions {
+    /**
+     * Whether the property is optional (can be undefined).
+     * @default false
+     */
+    optional?: boolean;
+    /**
+     * Whether the property is nullable (can be null).
+     * @default false
+     */
+    nullable?: boolean;
+}
+/**
+ * Property decorator that validates values against a branded enum at runtime.
+ *
+ * When a value is assigned to the decorated property, it validates that the value
+ * is a member of the specified branded enum. If validation fails, a descriptive
+ * error is thrown.
+ *
+ * Supports optional and nullable properties through the options parameter.
+ *
+ * @template E - The branded enum type
+ * @param enumObj - The branded enum to validate against
+ * @param options - Optional configuration for nullable/optional support
+ * @returns A property decorator function
+ * @throws {Error} Throws `Error` if enumObj is not a valid branded enum
+ * @throws {Error} Throws `Error` at runtime if assigned value is not in the enum
+ *
+ * @example
+ * // Basic usage
+ * const Status = createBrandedEnum('status', { Active: 'active', Inactive: 'inactive' } as const);
+ *
+ * class User {
+ *   \@EnumValue(Status)
+ *   accessor status: string = Status.Active;
+ * }
+ *
+ * const user = new User();
+ * user.status = Status.Active; // OK
+ * user.status = 'invalid'; // Throws Error
+ *
+ * @example
+ * // Optional property
+ * class Config {
+ *   \@EnumValue(Status, { optional: true })
+ *   accessor status: string | undefined;
+ * }
+ *
+ * const config = new Config();
+ * config.status = undefined; // OK
+ * config.status = Status.Active; // OK
+ *
+ * @example
+ * // Nullable property
+ * class Settings {
+ *   \@EnumValue(Status, { nullable: true })
+ *   accessor status: string | null = null;
+ * }
+ *
+ * const settings = new Settings();
+ * settings.status = null; // OK
+ * settings.status = Status.Active; // OK
+ */
+export declare function EnumValue<E extends BrandedEnum<any>>(enumObj: E, options?: EnumValueOptions): <V extends string | null | undefined>(target: ClassAccessorDecoratorTarget<unknown, V>, context: ClassAccessorDecoratorContext<unknown, V>) => ClassAccessorDecoratorResult<unknown, V>;
+/**
+ * Gets all class names that consume a specific branded enum.
+ *
+ * @param enumId - The enum ID to look up
+ * @returns Array of class names that consume the enum
+ *
+ * @example
+ * const Status = createBrandedEnum('status', { Active: 'active' } as const);
+ *
+ * \@EnumClass(Status)
+ * class User { }
+ *
+ * getEnumConsumers('status'); // ['User']
+ */
+export declare function getEnumConsumers(enumId: string): string[];
+/**
+ * Gets all enum IDs consumed by a specific class.
+ *
+ * @param className - The class name to look up
+ * @returns Array of enum IDs consumed by the class
+ *
+ * @example
+ * const Status = createBrandedEnum('status', { Active: 'active' } as const);
+ * const Priority = createBrandedEnum('priority', { High: 'high' } as const);
+ *
+ * \@EnumClass(Status, Priority)
+ * class Task { }
+ *
+ * getConsumedEnums('Task'); // ['status', 'priority']
+ */
+export declare function getConsumedEnums(className: string): string[];
+/**
+ * Gets all registered enum consumer entries.
+ *
+ * @returns Array of all consumer entries
+ *
+ * @example
+ * getAllEnumConsumers(); // [{ className: 'User', enumIds: Set(['status']) }, ...]
+ */
+export declare function getAllEnumConsumers(): EnumConsumerEntry[];
+/**
+ * Clears the consumer registry. Useful for testing.
+ * @internal
+ */
+export declare function clearConsumerRegistry(): void;
+/**
+ * Class decorator that registers a class as a consumer of branded enums.
+ *
+ * This decorator tracks which classes use which branded enums, enabling
+ * debugging and introspection of enum usage across the codebase.
+ *
+ * @param enums - One or more branded enums that the class consumes
+ * @returns A class decorator function
+ * @throws {Error} Throws `Error` if any argument is not a valid branded enum
+ *
+ * @example
+ * const Status = createBrandedEnum('status', { Active: 'active', Inactive: 'inactive' } as const);
+ * const Priority = createBrandedEnum('priority', { High: 'high', Low: 'low' } as const);
+ *
+ * \@EnumClass(Status, Priority)
+ * class Task {
+ *   status = Status.Active;
+ *   priority = Priority.High;
+ * }
+ *
+ * // Query which classes consume an enum
+ * getEnumConsumers('status'); // ['Task']
+ *
+ * // Query which enums a class consumes
+ * getConsumedEnums('Task'); // ['status', 'priority']
+ */
+export declare function EnumClass(...enums: AnyBrandedEnum[]): <T extends new (...args: any[]) => any>(target: T, context: ClassDecoratorContext<T>) => T;
+//# sourceMappingURL=decorators.d.ts.map

package/dist/lib/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../src/lib/decorators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,cAAc,EACd,WAAW,EAKX,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAsBpB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,SAAS,CAEvB,CAAC,SAAS,WAAW,CAAC,GAAG,CAAC,EAE1B,OAAO,EAAE,CAAC,EACV,OAAO,GAAE,gBAAqB,GAC7B,CAAC,CAAC,SAAS,MAAM,GAAG,IAAI,GAAG,SAAS,EACrC,MAAM,EAAE,4BAA4B,CAAC,OAAO,EAAE,CAAC,CAAC,EAChD,OAAO,EAAE,6BAA6B,CAAC,OAAO,EAAE,CAAC,CAAC,KAC/C,4BAA4B,CAAC,OAAO,EAAE,CAAC,CAAC,CAwG5C;AA8DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAIzD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAI5D;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,iBAAiB,EAAE,CAGzD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAK5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,SAAS,CACvB,GAAG,KAAK,EAAE,cAAc,EAAE,GAEzB,CAAC,CAAC,SAAS,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACvC,MAAM,EAAE,CAAC,EACT,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAC9B,CAAC,CA0BL"}

package/dist/lib/factory.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Factory function for creating branded enums.
+ *
+ * Creates enum-like objects with runtime metadata for identification,
+ * while keeping values as raw strings for serialization compatibility.
+ */
+import { BrandedEnum } from './types.js';
+/**
+ * Creates a branded enum with runtime metadata.
+ *
+ * The returned object:
+ * - Contains all provided key-value pairs as enumerable properties
+ * - Has non-enumerable Symbol properties for metadata (ENUM_ID, ENUM_VALUES)
+ * - Is frozen to prevent modification
+ * - Is registered in the global registry
+ *
+ * @template T - The shape of the values object (use `as const` for literal types)
+ * @param enumId - Unique identifier for this enum. Must be unique across all
+ *   branded enums in the application.
+ * @param values - Object containing key-value pairs where keys are enum member
+ *   names and values are the string values. Use `as const` for literal type inference.
+ * @returns A frozen branded enum object with attached metadata
+ * @throws {Error} Throws `Error` with message `Branded enum with ID "${enumId}" already exists`
+ *   if an enum with the same ID has already been registered.
+ *
+ * @example
+ * // Basic usage
+ * const Status = createBrandedEnum('status', {
+ *   Active: 'active',
+ *   Inactive: 'inactive',
+ * } as const);
+ *
+ * Status.Active // 'active' (raw string)
+ * getEnumId(Status) // 'status'
+ *
+ * @example
+ * // Type inference with as const
+ * const Colors = createBrandedEnum('colors', {
+ *   Red: 'red',
+ *   Green: 'green',
+ *   Blue: 'blue',
+ * } as const);
+ *
+ * type ColorValue = typeof Colors[keyof typeof Colors]; // 'red' | 'green' | 'blue'
+ *
+ * @example
+ * // Error handling for duplicate IDs
+ * createBrandedEnum('myEnum', { A: 'a' } as const);
+ * createBrandedEnum('myEnum', { B: 'b' } as const); // Throws Error
+ */
+export declare function createBrandedEnum<T extends Record<string, string>>(enumId: string, values: T): BrandedEnum<T>;
+//# sourceMappingURL=factory.d.ts.map

package/dist/lib/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/lib/factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,WAAW,EAIZ,MAAM,YAAY,CAAC;AAGpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChE,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,CAAC,GACR,WAAW,CAAC,CAAC,CAAC,CA6BhB"}

package/dist/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/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/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/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"}