import { ILogger } from '../../../logger';
/**
 * Safely transforms a value to BigInt with comprehensive error handling.
 * Handles precision loss prevention for large numbers while gracefully
 * handling invalid inputs without crashing the application.
 *
 * **IMPORTANT**: When isRequired=true, this function throws IdTransformationError
 * for invalid values instead of returning undefined. This ensures data integrity
 * but requires proper error handling in consuming code.
 *
 * @param value - The value to transform (string, number, bigint, null, or undefined)
 * @param isRequired - Whether the field is required (throws error if true and value is invalid)
 * @param fieldName - Name of the field being transformed (for error context)
 * @param logger - Optional logger for structured error reporting
 * @returns BigInt for valid large integers, undefined for invalid inputs when not required
 * @throws {IdTransformationError} When required field has invalid value
 *
 * @example
 * ```typescript
 * // Required field - throws on invalid data
 * @Transform(({ value }) => transformToBigInt(value, true, 'Id'))
 * id!: bigint;
 *
 * // Optional field - returns undefined on invalid data
 * @Transform(({ value }) => transformToBigInt(value, false, 'OptionalId'))
 * optionalId?: bigint;
 * ```
 */
export declare function transformToBigInt(value: unknown, isRequired?: boolean, fieldName?: string, logger?: ILogger): bigint | undefined;