// Import class-validator decorators for input validation
import { IsIn, IsNotEmpty } from 'class-validator';

// Import custom enum for type safety and validation
import { ByUserType } from 'src/utils/enums/enum';

// Import Swagger decorator for API documentation
import { ApiProperty } from '@nestjs/swagger';

/**
 * FetchByUsersDto - Data Transfer Object for fetching users by their involvement type
 *
 * This DTO is used to specify whether to fetch users who have "created" or "updated" records.
 * It provides type-safe filtering for user activity queries in the system.
 *
 * Purpose:
 * - Used in endpoints that need to retrieve lists of users based on their activity
 * - Commonly used for filter dropdowns in admin interfaces
 * - Supports audit reporting and user activity tracking
 *
 * Example Usage:
 * - GET /menus/fetch-users with { "by": "created_by" }
 * - Returns users who have created menu items
 * - Useful for filtering menus by creator in search interfaces
 */
export class FetchByUsersDto {
  /**
   * by - Filter type specifying which users to fetch
   *
   * This property determines whether to fetch users who have:
   * - 'created_by': Users who created records
   * - 'updated_by': Users who updated records
   *
   * Validation Rules:
   * - @IsNotEmpty(): Required field - must be provided
   * - @IsIn(Object.values(ByUserType)): Must be one of the valid enum values
   *
   * Swagger Documentation:
   * - @ApiProperty({ enum: ByUserType }): Shows as dropdown in Swagger UI
   * - Documents available options in API documentation
   *
   * Type Safety:
   * - Uses ByUserType enum for compile-time type checking
   * - Prevents invalid string values at runtime
   *
   * Business Context:
   * - Used in services to build appropriate database queries
   * - Determines which user relationship to join in queries
   * - Example: 'created_by' joins with creator user, 'updated_by' joins with updater user
   */
  @ApiProperty({ enum: ByUserType })
  @IsNotEmpty()
  @IsIn(Object.values(ByUserType))
  by: ByUserType;
}
