// eslint-disable-next-line max-classes-per-file
import { ApiProperty } from '@nestjs/swagger';
import { Transform } from 'class-transformer';
import { IsInt, IsOptional } from 'class-validator';

/**
 * PaginationDto
 * -------------
 * Data Transfer Object used to receive pagination parameters
 * from query strings.
 *
 * Example:
 *   GET /users?per_page=10&page=2
 */
export class PaginationDto {
  /**
   * Number of records to return per page
   * - Optional query parameter
   * - Defaults to 5 if not provided
   * - Transformed to number since query params are strings
   */
  @IsInt()
  @IsOptional()
  @ApiProperty({
    required: false,
    default: 5,
  })
  @Transform(({ value }) => Number(value))
  per_page: number;

  /**
   * Current page number
   * - Optional query parameter
   * - Defaults to 1 if not provided
   * - Must be an integer
   */
  @IsInt()
  @IsOptional()
  @ApiProperty({ description: 'page', required: false, default: 1 })
  @Transform(({ value }) => Number(value))
  page: number;
}

/**
 * PaginationResult
 * ----------------
 * Represents pagination metadata returned in API responses.
 * Typically accompanies a paginated data list.
 */
export class PaginationResult {
  /**
   * Total number of records available
   */
  @ApiProperty({ description: 'total' })
  total: number;

  /**
   * Currently requested page number
   */
  @ApiProperty({ description: 'current_page' })
  current_page: number;

  /**
   * Last available page number based on total and per_page
   */
  @ApiProperty({ description: 'last_page' })
  last_page: number;

  /**
   * Number of records returned per page
   */
  @ApiProperty({ description: 'per_page' })
  per_page: number;
}

/**
 * Response<T>
 * -----------
 * Generic API response wrapper for list-based endpoints.
 *
 * @template T Type of data contained in the list
 */
export class Response<T> {
  /**
   * List of records returned by the API
   */
  @ApiProperty({ description: 'data' })
  list: T[];

  /**
   * Pagination metadata
   * - Optional for non-paginated endpoints
   */
  @ApiProperty({ description: 'pagination' })
  pagination?: PaginationResult;
}
