import { ApiPropertyOptional } from '@nestjs/swagger';
import { IsDateString, IsOptional, IsString } from 'class-validator';
import { PaginationDto } from 'src/config/pagination/paginationDto';

/**
 * Data Transfer Object (DTO) for searching/filtering course portal entries.
 * Extends PaginationDto to include pagination parameters (page, limit, etc.)
 * along with course portal specific filters.
 *
 * This DTO is typically used in GET requests for filtering and paginating
 * course portal release/update records.
 *
 * @extends PaginationDto - Inherits pagination properties (page, limit, sort, etc.)
 *
 * @example
 * // Search for course portal releases with specific version and pagination
 * // GET /course-portal?release_version=2.1.0&release_date=2024-01-15&page=1&limit=10
 * {
 *   "release_version": "2.1.0",
 *   "release_date": "2024-01-15",
 *   "page": 1,
 *   "limit": 10
 * }
 *
 * @example
 * // Search with only pagination (no filters)
 * // GET /course-portal?page=2&limit=20
 * {
 *   "page": 2,
 *   "limit": 20
 * }
 */
export class SearchCoursePortalDto extends PaginationDto {
  /**
   * Optional filter for release version of course portal updates.
   * Used to search for specific versions or version patterns.
   *
   * @type {string}
   * @optional
   * @example "2.1.0" (exact version)
   * @example "2.1" (partial version match)
   * @example "beta" (version label)
   *
   * @apiPropertyOptional - Marks this field as optional in Swagger documentation
   *
   * @isOptional - Validation: Field is not required
   *
   * @isString - Validation: If provided, must be a string
   *   Error message: "release_version must be a string"
   */
  @ApiPropertyOptional({
    description: 'Filter by release version (e.g., "2.1.0", "beta")',
    example: '2.1.0',
    type: String,
  })
  @IsOptional()
  @IsString({ message: 'Release version must be a string if provided' })
  release_version?: string;

  /**
   * Optional filter for release date of course portal updates.
   * Used to find releases on a specific date or within a date range.
   * Should be in ISO 8601 date format (YYYY-MM-DD).
   *
   * @type {Date}
   * @optional
   * @example "2024-01-15" (January 15, 2024)
   * @example "2023-12-01" (December 1, 2023)
   *
   * @apiPropertyOptional - Marks this field as optional in Swagger documentation
   *
   * @isOptional - Validation: Field is not required
   *
   * @isDateString - Validation: If provided, must be a valid ISO date string
   *   Error message: "release_date must be a valid ISO 8601 date string"
   *   Note: Uses strict mode - only date portion (no time)
   */
  @ApiPropertyOptional({
    description: 'Filter by release date (ISO 8601 format: YYYY-MM-DD)',
    example: '2024-01-15',
    type: String, // Swagger shows as string (Date type would show as timestamp)
    format: 'date',
  })
  @IsOptional()
  @IsDateString(
    { strict: true },
    {
      message: 'Release date must be a valid date in YYYY-MM-DD format',
    },
  )
  release_date?: Date;
}
