smiling-source-down/README.md

A powerful source download library with resume capability and batch processing

# Smiling Source Down

一个强大的源代码下载库，支持断点续传、批量下载和并发控制。

## 特性

- 🚀 **断点续传**: 支持下载中断后继续下载
- 📦 **批量下载**: 支持批量文件下载
- ⚡ **并发控制**: 可配置并发下载数量
- 🔄 **自动重试**: 下载失败时自动重试
- 📊 **进度监控**: 实时监控下载进度
- 🎯 **灵活配置**: 支持多种配置选项
- 🌐 **内置网络**: 使用 Node.js 内置模块，无需额外依赖

## 安装

```bash
npm install smiling-source-down
```

## 使用方法

### 基本用法

```javascript
const { download } = require("smiling-source-down");

// 配置下载任务
const config = [
  {
    type: "file",
    name: "example.txt",
    path: "https://example.com/file.txt",
  },
  {
    type: "directory",
    name: "docs",
    children: [
      {
        type: "file",
        name: "readme.md",
        path: "https://example.com/docs/readme.md",
      },
    ],
  },
];

// 开始下载
download(config, {
  baseDir: "./downloads",
  concurrency: 5,
  retries: 3,
  onStart: (info) => {
    console.log(info.msg);
  },
  onProgress: (progress) => {
    console.log(`下载进度: ${progress.percent}% (${progress.count})`);
  },
  onSuccess: (filePath) => {
    console.log(`下载成功: ${filePath}`);
  },
  onError: (error) => {
    console.error(`下载失败: ${error.message}`);
  },
  onEnd: (result) => {
    console.log(`下载完成! 耗时: ${result.time}秒`);
  },
});
```

### 从 URL 加载配置

```javascript
const { download } = require("smiling-source-down");

// 从远程URL加载配置
download("https://example.com/download-config.json", {
  baseDir: "./downloads",
  concurrency: 10,
});
```

### 检查是否需要下载

```javascript
const { isNeedDownload } = require("smiling-source-down");

// 检查目录是否存在
if (isNeedDownload("./downloads")) {
  console.log("开始下载...");
  // 执行下载逻辑
} else {
  console.log("文件已存在，跳过下载");
}
```

## API 文档

### `download(config, options)`

#### 参数

- `config` (Array|string): 下载配置数组或配置文件的 URL
- `options` (Object): 下载选项

#### 配置格式

```javascript
[
  {
    type: 'file',           // 文件类型
    name: 'filename.txt',   // 文件名
    path: 'https://...'     // 文件URL
  },
  {
    type: 'directory',      // 目录类型
    name: 'dirname',        // 目录名
    children: [...]         // 子文件/目录
  }
]
```

#### 选项

| 参数          | 类型     | 默认值       | 描述               |
| ------------- | -------- | ------------ | ------------------ |
| `baseDir`     | string   | "./download" | 文件保存的基础目录 |
| `concurrency` | number   | 10           | 并发下载数量       |
| `retries`     | number   | 3            | 下载失败重试次数   |
| `delayMs`     | number   | 1000         | 重试间隔时间(毫秒) |
| `onStart`     | function | () => {}     | 开始下载回调       |
| `onProgress`  | function | () => {}     | 下载进度回调       |
| `onSuccess`   | function | () => {}     | 下载成功回调       |
| `onError`     | function | () => {}     | 下载失败回调       |
| `onEnd`       | function | () => {}     | 下载完成回调       |

#### 回调函数

**onStart(info)**

- `info.msg`: 开始信息消息

**onProgress(progress)**

- `progress.url`: 当前下载的文件 URL
- `progress.progress`: 下载进度 (0-1)
- `progress.percent`: 下载进度百分比 (0-100)
- `progress.completed`: 已完成的下载数量
- `progress.total`: 总下载数量
- `progress.count`: 下载计数字符串

**onSuccess(filePath)**

- `filePath`: 下载成功的文件路径

**onError(error)**

- `error`: 错误对象

**onEnd(result)**

- `result.progress`: 最终进度
- `result.percent`: 最终进度百分比
- `result.completed`: 完成的下载数量
- `result.total`: 总下载数量
- `result.time`: 总耗时(秒)
- `result.isAllSuccess`: 是否全部下载成功

### `isNeedDownload(baseDir)`

#### 参数

- `baseDir` (string): 要检查的目录路径

#### 返回值

- `boolean`: 如果目录不存在返回 true，存在返回 false

## 示例

查看 `example/index.js` 文件了解完整的使用示例。

## 依赖

**注意**: 本库使用 Node.js 内置模块处理网络请求和文件操作，无需安装额外的网络库。

## 系统要求

- Node.js >= 14.0.0

## 许可证

ISC

## 贡献

欢迎提交 Issue 和 Pull Request！

Issue地址 https://github.com/smilingovo/smiling-source-down/issues