/**
 * 模块: Upload
 * 文件功能描述: 该模块定义了上传文件的数据模型，包括文件的基本信息和存储信息。
 * 使用场景: 用于管理文件上传过程中的元数据和状态，适用于需要处理文件上传的Web应用或服务。
 */

/**
 * 类型: TUpload
 * 核心功能概述: 定义了上传文件的数据结构，包括文件ID、大小、偏移量、元数据、存储信息等。
 */
type TUpload = {
  id: string // 文件唯一标识符
  size?: number // 文件大小，可选
  offset: number // 文件上传的偏移量
  metadata?: Record<string, string | null> // 文件的元数据，可选
  storage?: { // 文件的存储信息，可选
    type: string // 存储类型
    path: string // 存储路径
    bucket?: string // 存储桶，可选
  }
  creation_date?: string // 文件创建日期，可选
}

/**
 * 类: Upload
 * 核心功能概述: 封装了上传文件的数据模型，提供了文件信息的初始化和访问方法。
 * 设计模式解析: 使用构造函数模式初始化对象，通过getter方法提供属性访问。
 * 使用示例: 
 * const upload = new Upload({ id: '123', size: 1024, offset: 0 });
 * console.log(upload.sizeIsDeferred); // 检查文件大小是否延迟
 */
export class Upload {
  id: TUpload['id'] // 文件ID
  metadata: TUpload['metadata'] // 文件元数据
  size: TUpload['size'] // 文件大小
  offset: TUpload['offset'] // 文件上传偏移量
  creation_date: TUpload['creation_date'] // 文件创建日期
  storage: TUpload['storage'] // 文件存储信息

  /**
   * 构造函数
   * 功能详细描述: 初始化Upload对象，检查必要的ID属性，并设置默认的创建日期。
   * 输入参数解析: 
   * - upload: TUpload类型，包含文件的基本信息和存储信息。
   * 异常处理机制: 如果未提供ID，则抛出错误。
   */
  constructor(upload: TUpload) {
    // 检查ID是否存在，不存在则抛出错误
    if (!upload.id) {
      throw new Error('[File] constructor must be given an ID')
    }

    // 初始化属性
    this.id = upload.id
    this.size = upload.size
    this.offset = upload.offset
    this.metadata = upload.metadata
    this.storage = upload.storage

    // 如果未提供创建日期，则设置为当前时间
    this.creation_date = upload.creation_date ?? new Date().toISOString()
  }

  /**
   * 方法: sizeIsDeferred
   * 功能详细描述: 检查文件大小是否未定义，即是否延迟上传。
   * 返回值说明: 返回布尔值，true表示文件大小未定义，false表示已定义。
   */
  get sizeIsDeferred(): boolean {
    return this.size === undefined
  }
}