# async-queue-progress

**Repository Path**: sharp-feel/async-queue-progress

## Basic Information

- **Project Name**: async-queue-progress
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: ISC
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2019-05-11
- **Last Updated**: 2021-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

### 简介
这是一个有执行进度展示的异步任务队列，常用于批量抓取接口的任务执行和进度展示等...
借鉴于 [`single-line-log`](https://www.npmjs.com/package/single-line-log) 库，在原基础上进行调整并封装了异步任务队列及执行进度展示

### 示例
```javascript
const AsyncQueueProgress = require('async-queue-progress');
const taskQueue = AsyncQueueProgress({
  asyncMax: 5,
});

main();

function main() {
  taskQueue.progressBar.describe('加载中...');
  for (let i = 0; i < 100; i += 1) {
    taskQueue.add(task, `describe-${i}...`, `title-${i}:`, `data-${i}`);
  }

  taskQueue.start();
}

function task(data, index) {
  return new Promise((resolve) => {
    // 模拟完成任务
    setTimeout(() => {
      console.log(data);
      if (index === 30) {
        taskQueue.stop().then(() => {
          console.log('[stop ] end', new Date());
        });
      }
      resolve();
    }, 1000 * Math.random());
  });
}

```

### 文档
#### TaskQueue
- `progressBar`：`ProgressBar` - 当前队列的进度条对象

- `config`：`(opts: TaskQueue.Options) => void` - 配置

- `reset`：`async () => void` - 重置

- `clear`：`async (opts: TaskQueue.Options) => void` - 清空
  - `opts`：配置项

- `add`：`(promise, describe, title, data) => void` - 添加一个任务
  - `promise`：`(data, index: Number) => Promise | async (data, index: Number) => void` - 要执行的任务
  - `describe`：`String` - 执行时显示的描述
  - `title`：`String` - 执行时显示的标题
  - `data`：`String` - 数据

- `start`：`() => Promise` - 开始/继续 执行任务

- `stop`：`() => Promise` - 暂停 执行任务

- `index`：`() => Number` - 当前执行的任务的下标

- `length`：`() => Number` -任务队列的长度

- `isStop`：`() => Boolean` - 是否未开始

- `isWillComplete`：`() => Boolean` - 是否即将完成

- `isComplete`：`() => Boolean` - 是否已经完成

#### TaskQueue.Options
- `asyncMax`：`Number` - 任务最大异步执行数，默认为 `3`

- `log`：`Boolean` - 是否显示日志，默认为 `true`

- `onComplete`：`(isComplete: Boolean) => void` - 完成回调，默认为 `null`
  - `isComplete`：`Boolean` - 是否完全的完成了，判断标准 `index` 等于 `length`

- `onStop`：`(index: Number) => void` - 暂停回调，默认为 `null`
  - `index`：`Number` - 暂停时当前项的下标

- `onError`：`(error: Error, task: Task) => void` - 报错回调，默认为 `null`
  - `error`：`Error` - 错误内容
  - `task`：`Task` - 报错的任务

#### TaskQueue.Task
  - `promise`：`(data, index: Number) => Promise | async (data, index: Number) => void` - 要执行的任务

  - `describe`：`String` - 执行时显示的描述

  - `title`：`String` - 执行时显示的标题

  - `data`：`String` - 数据

#### ProgressBar
- `config`：`(opts: ProgressBar.Options) => this` - 配置

- `title`：`(val: String) => this` - 设置标题

- `describe`：`(val: String) => this` - 设置描述

- `add`：`(val: Number) => this` - 增加进度值
  - `val`：`Number` - 要增加的进度值，默认 `1`

- `value`：`(val: Number, append: Boolean) => this` - 设置/增加 进度值
  - `val`：`Number` - 要 设置/增加 的进度值，默认 `1`
  - `append`：`Boolean` - `false` 设置，`true` 增加

- `total`：`(val: Number, append: Boolean) => this` - 设置/增加 总数值
  - `val`：`Number` - 要 设置/增加 的总数值，默认`1`
  - `append`：`Boolean` - `false` 设置，`true` 增加

- `isFull`：`() => Boolean` - 进度是否是 `100%`

- `render`：`(force: Boolean) => void` - 刷新进度条
  - `force`：`Boolean` - 是否强行刷新，否则按 `Options.renderRate` ms 刷新一次

- `quit`：`() => void` - 结束这个进度条，下次刷新绘制新的进度条

#### ProgressBar.Options
- `valueChar`：`String` - 进度填充字符，默认为 `'#'`

- `emptyChar`：`String` - 进度空白字符，默认为 `' '`

- `length`：`String` - 进度条长度，默认为 `50`

- `title`：`String` - 标题，默认为 `'load:'`

- `describe`：`String` - 描述，默认为 `''`

- `total`：`Number` - 总值，默认为 `0`

- `value`：`Number` - 进度值，默认为 `0`

- `renderRate`：`Number` - 刷新频率：ms/次，默认为 `16`

- `format`：`(data: PercentData) => String` - 将进度数据转换为字符串以显示，默认为：
  ```javascript
  function format(data) {
    let title = `${data.title} ${(100 * data.percent).toFixed(3).substr(0, 5)}%`;
    if (data.describe) title = `${data.describe}\n${title}`;
    return `${title} [${data.cells}] [${data.percent * data.total}/${data.total}]\n`;
  },
  ```