# a-small-promise-queue

**Repository Path**: roman_123/a-small-promise-queue

## Basic Information

- **Project Name**: a-small-promise-queue
- **Description**: A simple queue for better control of your asynchronous events.
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-21
- **Last Updated**: 2025-12-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# a-small-promise-queue
 ![QQ](https://img.shields.io/badge/QQ-306863030-green.svg) [![Gitee](https://img.shields.io/badge/Gitee-roman_123-blue.svg)](https://gitee.com/roman_123/a-small-promise-queue.git) [![GitHub](https://img.shields.io/badge/GitHub-roman_123-blue.svg)](https://github.com/qq306863030/a-small-promise-queue) [![NPM](https://img.shields.io/badge/NPM-roman_123-blue.svg)](https://www.npmjs.com/package/a-small-promise-queue)

> A simple queue for better control of your asynchronous events.

## Setup

```bash
npm install --save a-small-promise-queue
```

## Usage

You can then use it as a window global or as an CommonJs module

### Node

```js
// for commonjs
const QueueTool = require('a-small-promise-queue')
QueueTool.PromiseQueue

// for esModule
import PromiseQueue from 'a-small-promise-queue'
```
### Browser

```html
<script src="./lib/a-small-promise-queue.umd.js"></script>
QueueTool.PromiseQueue
```

## Example

```js
import PromiseQueue from 'a-small-promise-queue'

const queue = new PromiseQueue({
    maxConcurrenceCount: 2, // 最大并发数设置为2
    successCallBack: (result) => {
        console.log('执行完成', result)
    }
})

function test(index, time) {
    return new Promise((resolve, reject) => {
        setTimeout(() => {
            resolve(index)
        }, time)
    })
}

queue.add(() => {
    return test(1, 2000) // 输入Promise函数
})

queue.add(async () => {
    await test(2, 2000) // 使用async await
    return 2
})

queue.add(() => {
    return test(3, 2000)
})

queue.add(() => {
    return test(4, 2000)
})

queue.add(() => {
    return test(5, 2000)
})

queue.add(() => {
    return test(6, 2000)
})

queue.add(() => {
    console.log('开始执行', 7) // 输入普通函数
})

queue.add((opt: PQCallbackOptions) => { // 自动在函数最后一个参数追加一个回调函数对象，可以用于中断异步函数的执行
    return '开始执行8' + JSON.stringify(opt)
})

queue.add(() => {
    return test(9, 2000)
})

queue.add(test.bind(null, 10, 2000)) // 使用bind方法
```

## Interface

```typescript
type TaskState = "ready" | "running" | "pause" | "clear";

interface PQOptions {
  /**
   * 是否跳过错误(默认true)
   */
  isSkipError?: boolean;
  /**
   * 是否在添加时自动执行(默认true)
   */
  isAutoExecByAdd?: boolean;
  /**
   * 超时时长(ms)(默认为-1，不限制)
   */
  timeout?: number;
  /**
   * 最大队列长度(默认为-1，不限制)
   */
  maxSize?: number;
  /**
   * 最大并发数(默认为1)
   */
  maxConcurrenceCount?: number;
  /**
   * 执行成功的回调函数
   * @param result 传入异步方法的返回值
   * @returns
   */
  successCallBack?: (result: any) => void;
  /**
   * 执行错误时的回调函数
   * @param error
   * @returns
   */
  errorCallBack?: (error: any) => void;
  /**
   * 任务列表执行完成时的返回值
   * @returns
   */
  taskEndCallBack?: () => void;
}

interface PQItemOptions {
  /**
   * 是否跳过错误
   */
  isSkipError?: boolean;
  /**
   * 超时时长(ms)
   */
  timeout?: number;
  /**
   * 执行成功的回调函数
   * @param result 传入异步方法的返回值
   * @returns
   */
  successCallBack?: (result: any) => void;
  /**
   * 执行错误时的回调函数
   * @param error
   * @returns
   */
  errorCallBack?: (error: any) => void;
}

interface PQCallbackOptions {
  /**
   * 是否超时
   */
  isTimeout: boolean;
  /**
   * 是否处于暂停状态
   */
  isPaused: boolean;
  /**
   * 调度器的状态(ready就绪状态、running执行状态、pause暂停状态、clear清除状态)
   */
  schedulerState: TaskState;
}

class PromiseQueue {
  constructor(options?: PQOptions);
  /**
   * 当前列表中的任务数
   */
  size: number;
  /**
   * 列表中的最大任务数
   */
  maxSize: number;
  /**
   * 当前正在执行的任务数
   */
  runningSize: number;
  /**
   * 添加任务到队列中
   * @param asyncEvent 在执行中会自动在函数的最后追加一个参数，用于传递当前的执行状态
   * @param opt 单独任务的配置项
   */
  add(asyncEvent: (...args: any[]) => Promise<any>, opt?: PQItemOptions): void;
  /**
   * 开始执行
   */
  start(): void;
  /**
   * 暂停执行
   */
  pause(): void;
  /**
   * 清除任务队列
   */
  clear(): void;
}
```