import { ApiProperty } from '@nestjs/swagger';
import { IsEnum, IsNotEmpty, IsArray, IsInt } from 'class-validator';
import { StatusAction } from 'src/utils/enums/enum';

/**
 * Data Transfer Object (DTO) for updating status of multiple records.
 *
 * This DTO is used for bulk status updates where you need to activate or
 * deactivate multiple records at once. Commonly used in admin panels for
 * managing record visibility, activation states, or soft deletion.
 *
 * @example
 * // Activate multiple records:
 * {
 *   "action": "activate",
 *   "ids": [1, 2, 3, 4]
 * }
 *
 * @example
 * // Deactivate multiple records:
 * {
 *   "action": "deactivate",
 *   "ids": [5, 6, 7]
 * }
 *
 * @example
 * // Usage in controller:
 * @Patch('update-status')
 * async updateStatus(@Body() updateStatusDto: UpdateStatusDto) {
 *   return this.service.bulkUpdateStatus(
 *     updateStatusDto.ids,
 *     updateStatusDto.action
 *   );
 * }
 */
export class UpdateStatusDto {
  /**
   * Action to perform on the selected records.
   * Determines whether to activate or deactivate the records.
   *
   * @type {StatusAction}
   * @required
   * @example StatusAction.ACTIVATE (likely 'activate')
   * @example StatusAction.DEACTIVATE (likely 'deactivate')
   *
   * @isEnum - Validation: Must be one of the StatusAction enum values
   *   Error message: "action must be either activate or deactivate"
   *
   * @isNotEmpty - Validation: Cannot be null, undefined, or empty
   *   Error message: "action should not be empty"
   *
   * @apiProperty - Swagger documentation with enum values
   *
   * @note The enum validation ensures type safety and prevents invalid actions.
   */
  @ApiProperty({
    description: 'Action to perform: activate or deactivate records',
    enum: StatusAction,
    enumName: 'StatusAction',
    example: StatusAction.ACTIVATE,
  })
  @IsNotEmpty({ message: 'Action is required' })
  @IsEnum(StatusAction, {
    message: 'action must be either activate or deactivate',
  })
  action: StatusAction;

  /**
   * Array of record IDs to update.
   * Contains the numeric identifiers of records to activate/deactivate.
   *
   * @type {number[]}
   * @required
   * @example [1, 2, 3, 4]
   * @example [101, 102, 103]
   *
   * @isArray - Validation: Must be an array
   *   Error message: "ids must be an array"
   *
   * @isNotEmpty - Validation: Array cannot be empty
   *   Error message: "ids should not be empty"
   *
   * @apiProperty - Swagger documentation with array type
   *
   * @note Consider adding additional validations:
   *   - @ArrayMinSize(1) - Ensure at least one ID
   *   - @IsInt({ each: true }) - Each element must be an integer
   *   - @ArrayMaxSize(100) - Limit bulk operations for performance
   */
  @ApiProperty({
    description: 'Array of record IDs to update',
    type: [Number],
    example: [1, 2, 3, 4],
  })
  @IsNotEmpty({ message: 'At least one ID is required' })
  @IsArray({ message: 'IDs must be provided as an array' })
  @IsInt({ each: true, message: 'Each ID must be an integer' })
  ids: number[];
}
