/**
 * Base Mapper Interface
 *
 * Defines the contract for all mappers.
 * Mappers handle bidirectional transformations between domain entities and DTOs.
 *
 * Generic Parameters:
 * - TDomain: Domain entity type
 * - TDTO: Data Transfer Object type
 *
 * @layer Application
 */

/**
 * IMapper<TDomain, TDTO>
 *
 * Generic mapper interface for consistent DTO ↔ Domain transformations.
 *
 * @template TDomain - Domain entity type
 * @template TDTO - Data Transfer Object type
 */
export interface IMapper<TDomain, TDTO> {
  /**
   * Converts DTO to domain entity
   *
   * Transforms data from persistence/API layer to domain entity.
   * Applies domain validation and business rules.
   *
   * @param dto - Data Transfer Object from persistence/API
   * @returns Domain entity
   * @throws Error if DTO is invalid or fails domain validation
   */
  toDomain(dto: TDTO): TDomain;

  /**
   * Converts domain entity to DTO
   *
   * Transforms domain entity to persistence/API format.
   * Serializes domain objects for storage or transmission.
   *
   * @param entity - Domain entity
   * @returns Data Transfer Object for persistence/API
   */
  toDTO(entity: TDomain): TDTO;

  /**
   * Converts request/form data to domain entity
   *
   * Transforms user input (forms, API requests) to domain entity.
   * Applies validation and default values.
   *
   * @param request - Request/form data
   * @returns Domain entity
   * @throws Error if request data is invalid
   */
  fromRequest?(request: unknown): TDomain;
}

/**
 * Batch Mapper Utilities
 *
 * Helper functions for batch transformations.
 */
export class MapperUtils {
  /**
   * Maps array of DTOs to domain entities
   *
   * @param dtos - Array of DTOs
   * @param mapper - Mapper instance
   * @returns Array of domain entities
   */
  static toDomainArray<TDomain, TDTO>(
    dtos: TDTO[],
    mapper: IMapper<TDomain, TDTO>
  ): TDomain[] {
    return dtos.map((dto) => mapper.toDomain(dto));
  }

  /**
   * Maps array of domain entities to DTOs
   *
   * @param entities - Array of domain entities
   * @param mapper - Mapper instance
   * @returns Array of DTOs
   */
  static toDTOArray<TDomain, TDTO>(
    entities: TDomain[],
    mapper: IMapper<TDomain, TDTO>
  ): TDTO[] {
    return entities.map((entity) => mapper.toDTO(entity));
  }
}