import { IsIn, IsNotEmpty } from 'class-validator';
import { ByUserType } from 'src/utils/enums/enum';
import { ApiProperty } from '@nestjs/swagger';

/**
 * Data Transfer Object (DTO) for fetching data filtered by user type.
 *
 * This DTO is used to filter records based on the type of user who created
 * or is associated with the data. Commonly used in reporting, analytics,
 * or data segregation scenarios where different user types have different
 * data access or display requirements.
 *
 * The ByUserType enum provides clear, type-safe options for filtering.
 *
 * @example
 * // Fetch data created by admin users:
 * {
 *   "by": "admin"
 * }
 *
 * @example
 * // Fetch data created by affiliate users:
 * {
 *   "by": "affiliate"
 * }
 *
 * @example
 * // Fetch data created by regular users:
 * {
 *   "by": "user"
 * }
 *
 * @example
 * // In a controller:
 * @Post('filter')
 * async filterData(@Body() fetchDto: FetchByUsersDto) {
 *   return this.service.getDataByUserType(fetchDto.by);
 * }
 */
export class FetchByUsersDto {
  /**
   * User type to filter records by.
   * Determines which user category's data to retrieve.
   *
   * @type {ByUserType}
   * @required
   * @example ByUserType.ADMIN (likely 'admin')
   * @example ByUserType.AFFILIATE (likely 'affiliate')
   * @example ByUserType.USER (likely 'user')
   *
   * @isNotEmpty - Validation: Cannot be null, undefined, or empty
   *   Error message: "by should not be empty"
   *
   * @isIn - Validation: Must be one of the specified enum values
   *   Error message: "by must be one of the following values: ..."
   *
   * @apiProperty - Swagger documentation with enum values
   *
   * @note The enum values are extracted using Object.values(ByUserType)
   * which ensures the validation always matches the current enum definition.
   */
  @ApiProperty({
    description: 'User type to filter records by',
    enum: ByUserType,
    enumName: 'ByUserType',
    // example: ByUserType.ADMIN, // Assuming ADMIN is a value in the enum
  })
  @IsNotEmpty({ message: 'User type filter is required' })
  @IsIn(Object.values(ByUserType), {
    message: `User type must be one of: ${Object.values(ByUserType).join(', ')}`,
  })
  by: ByUserType;
}
