import { ApiPropertyOptional } from '@nestjs/swagger';
import { IsDateString, IsOptional } from 'class-validator';

/**
 * DateRangeDto - Data Transfer Object for date range filtering
 *
 * This DTO provides a standardized way to accept date range parameters
 * for filtering time-based data. Both fields are optional to allow
 * flexible queries (start date only, end date only, or full range).
 *
 * Features:
 * - Optional start and end dates
 * - ISO 8601 date string validation
 * - OpenAPI/Swagger documentation with proper format
 * - Compatible with database date range queries
 *
 * Common use cases:
 * - Filtering records created within a date range
 * - Reporting data for specific time periods
 * - Analytics dashboards with date filters
 * - Audit logs and activity tracking
 *
 * @example
 * // Filter events from specific start date to now
 * {
 *   "from": "2024-01-01T00:00:00.000Z"
 * }
 *
 * @example
 * // Filter events up to a specific end date
 * {
 *   "to": "2024-12-31T23:59:59.999Z"
 * }
 *
 * @example
 * // Filter events within a specific range
 * {
 *   "from": "2024-01-01T00:00:00.000Z",
 *   "to": "2024-12-31T23:59:59.999Z"
 * }
 *
 * @example
 * // Usage in controller
 * @Get('transactions')
 * getTransactions(@Query() dateRange: DateRangeDto) {
 *   return this.transactionService.getByDateRange(dateRange);
 * }
 */
export class DateRangeDto {
  /**
   * Start date of the range (inclusive)
   *
   * The beginning of the date range. Records with dates on or after
   * this date will be included in results.
   *
   * Format requirements:
   * - ISO 8601 date-time string
   * - Should include timezone (Z for UTC or offset)
   * - Examples: "2024-01-01T00:00:00.000Z", "2024-01-01"
   *
   * Database query implications:
   * - Typically used in WHERE clause: `date_column >= from`
   * - Consider timezone handling for consistent results
   *
   * @optional When omitted, no start date limitation is applied
   * @example "2024-01-01T00:00:00.000Z"
   * @example "2024-01-01"
   */
  @ApiPropertyOptional({
    type: String,
    format: 'date-time',
    description: 'Start date of the range (inclusive). ISO 8601 format.',
    example: '2024-01-01T00:00:00.000Z',
  })
  @IsOptional()
  @IsDateString()
  from?: string;

  /**
   * End date of the range (inclusive)
   *
   * The end of the date range. Records with dates on or before
   * this date will be included in results.
   *
   * Format requirements:
   * - ISO 8601 date-time string
   * - Should include timezone (Z for UTC or offset)
   * - Typically includes end-of-day time (23:59:59.999)
   *
   * Database query implications:
   * - Typically used in WHERE clause: `date_column <= to`
   * - Consider using `< next_day` for date-only comparisons
   *
   * @optional When omitted, no end date limitation is applied
   * @example "2024-12-31T23:59:59.999Z"
   * @example "2024-12-31"
   */
  @ApiPropertyOptional({
    type: String,
    format: 'date-time',
    description: 'End date of the range (inclusive). ISO 8601 format.',
    example: '2024-12-31T23:59:59.999Z',
  })
  @IsOptional()
  @IsDateString()
  to?: string;
}
