# Download Library

一个用于文件下载的 JavaScript/TypeScript 库，提供简单易用的文件下载功能。

## 功能特性

- 支持文件下载
- 支持进度监控
- 支持断点续传
- 支持一个文件多个源
- 支持提示文本本地化
- 支持多个文件并发下载

## 安装

使用 npm:

bash
npm install @yeez-tech/ydl

使用 yarn:

bash
yarn add @yeez-tech/ydl

## 生成验证文件

下载器在下载目标文件前，需要首先下载验证文件，验证文件中包含了目标文件的大小、块信息、哈希值等信息，用于验证下载结果的正确性。

本库提供了工具ydl-vf，用于生成该验证文件。

- 创建验证文件: ydl-vf create INPUT_FILE OUTPUT_FILE
- 读取验证文件: ydl-vf read VERIFICATION_FILE
- 验证文件: ydl-vf verify FILE_TO_VERIFY VERIFICATION_FILE

## 打包配置说明

### ⚠️ Electron/Vite/Webpack 打包注意事项

本库使用 Node.js Worker Threads，需要确保 worker 文件（DVTaskProcessor.js、IOTaskProcessor.js）在打包时被正确包含。

库会自动尝试从多个路径查找 worker 文件，但如果打包工具没有包含这些文件，仍然需要手动配置。

### Electron 配置示例

在 vue.config.js 中配置：

javascript
const path = require("path");
module.exports = {
  configureWebpack: {
    plugins: [
      new (require("copy-webpack-plugin"))({
        patterns: [
          {
            from: path.resolve(
              __dirname,
              "node_modules/@yeez-tech/ydl/dist/utils/"
            ),
            to: "utils/[name][ext]",
            noErrorOnMissing: true,
          },
        ],
      }),
    ],
  },
};

### 其他打包工具

请参考 Electron 配置，确保将 node_modules/@yeez-tech/ydl/dist/utils/ 目录下的 .js 文件复制到打包输出目录的 utils/ 子目录中。

如果遇到 "Cannot find worker file" 错误，请检查：

1. Worker 文件是否被正确复制到打包输出目录
2. Worker 文件路径是否与库的查找路径匹配

## 使用方法

### 基本用法

javascript
import { Downloader, initDL, ProgressIO } from "@yeez-tech/ydl";
class MyProgressIO extends ProgressIO {}
// 初始化环境
await initDL();
// 定义进度IO对象
const io = new MyProgressIO();
//初始化下载器
const dl = new Downloader(500, io, {});
const taskId = dl.download({ 0: [url] }, vdfUrl, filePath);
// 暂停任务
dl.pause(taskId);
// 恢复任务
dl.resume(taskId);
//获取任务信息
const task = dl.getTask(taskId);
// 获取任务状态
const taskStatus = dl.taskStatus(taskId);
// 获取所有任务
const allTasks = dl.getAllTasks();
// 删除任务
dl.remove(taskId);
//关闭下载器
dl.close();

### URL 与 Header 配置

download(urls, checkFileUrl, outputFile) 支持为同一个任务的多个镜像源配置权重和自定义 HTTP Header：

javascript
const urls = {
  0: [
    {
      url: "https://cdn-a.example.com/video.bin",
      headers: {
        "User-Agent": "MyApp/1.0",
        Referer: "https://example.com/download",
        Authorization: "Bearer ",
      },
    },
    // 同一优先级下可以放多个源，下载器会根据速度/权重自动切换
    {
      url: "https://cdn-b.example.com/video.bin",
    },
  ],
  1: [
    {
      url: "https://fallback.example.com/video.bin",
      headers: {
        Cookie: "session=abc123",
      },
    },
  ],
};
const checkFile = {
  url: "https://cdn-a.example.com/video.bin.dvf",
  headers: {
    "User-Agent": "MyApp/Checkfile",
  },
};
const taskId = dl.download(urls, checkFile, "/absolute/path/to/video.bin");

- urls 是一个“优先级 → URL 列表”的映射：
- key 为字符串数字（"0", "1" ...），数值越小优先级越高；
- 每个 value 是 URL 或 { url, headers } 对象，表示同一任务的不同镜像源；
- headers 支持任意自定义字段（User-Agent、Referer、Authorization、Cookie 等），会透传给所有 range 请求和重试。
- checkFileUrl 也可以是字符串或 { url, headers } 对象，用于下载 .dvf 校验文件。
- outputFile 支持绝对或相对路径，下载完成并通过校验后会自动删除生成的 .dmf/.dvf 临时文件。

### 自定义 IO 对象

下载器在下载过程中会将下载任务、进度信息保存到外部存储中，为了保证保存信息的一致性，我们定义了保存进度的接口，并在合适的时机调用这些接口以保存、读取下载任务。

用户需要根据自身的需要继承并实现该接口，可以将任务信息保存到文件中，也可以保存到页面缓存或数据库（如 SQLite）中。

javascript
import { ProgressIO } from "@yeez-tech/ydl";
class MyIO extends ProgressIO {
  constructor(type) {
    super(type);
  }
getAllDownloadTasks() {
    //读取所有任务
  }
saveDownloadTask(task) {
    //保存任务
  }
removeDownloadTask(task) {
    // 删除任务
  }
}

### 下载器的事件

可以在下载器中监听多个事件，以了解下载器的状态。

javascript
dl.on("speed", (taskIdSpeed) => {
  // 速度更新
})
  .on("download-progress", (taskId, complete, total) => {
    // 下载进度
  })
  .on("verify-progress", (taskId, complete, total) => {
    // 验证进度
  })
  .on("start-download-checkfile", (taskId) => {
    // 开始下载检查文件
  })
  .on("download-checkfile-done", (taskId) => {
    // 下载检查文件完成
  })
  .on("start-verify", (taskId) => {
    // 开始验证下载文件
  })
  .on("download-succ", (taskId) => {
    // 下载成功
  })
  .on("error", (err) => {
    // 错误
  });

各个事件发生的顺序如下：

start-download-checkfile -> download-checkfile-done -> download-progresss -> ... -> download-progress -> start-verfiy -> verify-progress -> ... -> verify-progress -> download-succ

各个阶段，均可能发生error事件。

### 错误处理

调用 Downloader 中的方法时，错误信息会立刻抛出，用户应该进行相应的处理，如果是异步操作，则会通过error事件返回。

### 多语言支持

库提供了中英文支持，主要用于 error 事件中的错误信息，错误信息会根据系统中的语言设定显示相应的语言。

javascript
dl.on("error", (err) => {
  console.log(err.message); //本地化语言
});

语言支持基于 i18next 实现，如果需要扩展新的语言，可以调用 setAppTranslationDirs增加新的语言，如果需要手动指定语言，可以调用setLanguage。

## API 文档

### Downloader

下载器主类

参数:

- timeInterval: 速度更新间隔（毫秒）
- progressIO: ProgressIO 实例，用于持久化下载任务
- options: 配置选项

示例:

typescript
import { Downloader, initDL, ProgressIO } from "@yeez-tech/ydl";
class MyProgressIO extends ProgressIO {
  getAllDownloadTasks() {
    return [];
  }
  saveDownloadTask(task) {
    / 保存任务 /
  }
  removeDownloadTask(task) {
    / 删除任务 /
  }
}
async function example() {
  await initDL();
  const io = new MyProgressIO();
  const downloader = new Downloader(500, io, {});
  // 使用下载器...
  downloader.close();
}

## 开发指南

### 项目设置

1. 克隆仓库:

bash
git clone 
cd download-lib

2. 安装依赖:

bash
npm install

### 开发命令

- npm run dev - 启动开发环境
- npm run build - 构建项目
- npm run test - 运行测试
- npm run debug - 运行调试脚本
- npm run types - 生成类型声明文件
- npm run lint - 运行代码检查

### 开发流程

1. 本地开发

- 在 packages 目录下开发功能
- 使用 npm run debug 运行调试脚本 (scripts/dev.ts)
- 实时测试功能

2. 测试

- 在 packages/__test__ 目录下编写测试用例
- 使用 npm run test 运行测试

3. 构建

- 使用 npm run build 构建项目
- 构建产物将输出到 dist 目录

4. 本地测试
- 使用 npm run publish:local 在本地发布
- 使用 yalc 在其他项目中测试

### 目录结构

download-lib/
├── packages/              # 源代码目录
│   ├── index.ts          # 主入口文件
│   ├── utils/            # 工具函数
│   └── __test__/         # 测试文件
├── scripts/              # 开发脚本
│   └── dev.ts           # 开发调试脚本
├── dist/                # 构建输出目录
└── package.json         # 项目配置文件

### 提交规范

项目使用 husky 和 lint-staged 进行代码规范控制：

1. 代码提交前会自动运行：

- ESLint 检查
- TypeScript 类型检查
- 单元测试

2. 提交信息格式：

feat: 添加新功能
fix: 修复问题
docs: 更新文档
style: 代码格式调整
refactor: 代码重构
test: 添加测试
chore: 构建过程或辅助工具的变动

## 发布

1. 构建项目：

bash
npm run build

2. 发布到 npm：

bash
npm run publish

## 许可证

商业软件，闭源。

## 贡献指南

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

## 更新日志

### [0.0.0] - 开发中

- 初始版本
- 基本下载功能实现

### [待开发功能]

- 超大文件，例如 100TB 时，是否会存在整数溢出问题，需要检查
- 动态更新下载链接
- 支持 http，https 等网络代理

# 生成组件类库

## 相关命令

- 项目运行 npm run dev
- 构建类库 npm run build
- 快捷创建组件 npm run gen (该命令会根据输入生成组件模板，包括组件 serve 与 store 以及 test)
- 单测 npm run test

## 项目规范

- 请按照 standard 标准书写代码，在 commit 阶段配备 lint，无 lint 错误方可提交
- 请不要将与生产环境无关的依赖安装到 dependencies 中

## 组件库本地调试

1. 请安装 yalc npm i yalc -g
2. 发布本地依赖 npm run publish:local
3. 目标项目安装该库 yalc add xxx

## 组件库更新

组件库修改后请重新构建 npm run build

1. 本地推送组件更新 npm run push
已安装本库的项目即更新为最新代码
注意：由于 vite 存在缓存 node_module 依赖，如果推送后页面没有刷新，可以尝试使用 vite --force 重启项目，这将重新构建运行中的项目依赖

## 组件库运行中可能存在的问题

1. 接口相关代码不会走 mock，全部调用真实接口，可能出现接口 404，接入时请确保接口调通