Server : Apache/2.4.41 (Ubuntu) System : Linux absol.cf 5.4.0-198-generic #218-Ubuntu SMP Fri Sep 27 20:18:53 UTC 2024 x86_64 User : www-data ( 33) PHP Version : 7.4.33 Disable Function : pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wifcontinued,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_get_handler,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,pcntl_async_signals,pcntl_unshare, Directory :  /usr/local/lib/node_modules/awaitqueue/

Upload File : current_dir [ Writeable ] document_root [ Writeable ]

# AwaitQueue

JavaScript utility to enqueue async tasks for Node.js and the browser.


## Installation

```bash
$ npm install awaitqueue
```

## Usage

* CommonJS usage:

```js
const { AwaitQueue, AwaitQueueTask, AwaitQueueDumpItem } = require('awaitqueue');
```

* ES6 usage:

```js
import { AwaitQueue, AwaitQueueTask, AwaitQueueDumpItem } from 'awaitqueue';
```


## API

### type AwaitQueueDumpItem

```typescript
type AwaitQueueDumpItem =
{
  task: AwaitQueueTask<unknown>;
  name?: string;
  enqueuedTime: number;
  executingTime: number;
};
```

TypeScript type representing an item in the array returned by the `awaitQueue.dump()` method.

* `task`: The function to be executed.
* `name`: The name of the given `function` (if any) or the `name` argument given to `awaitQueue.push()` method (if any).
* `enqueuedTime`: Time in milliseconds since the task was enqueued, this is, since `awaitQueue.push()` was called until its execution started or until now if not yet started.
* `executingTime`: Time in milliseconds since the task execution started (or 0 if not yet started).

### type AwaitQueueTask

```typescript
type AwaitQueueTask<T> = () => (Promise<T> | T)
```

TypeScript type representing a function that returns a value `T` or a Promise that resolves with `T`.

### new AwaitQueue({ ClosedErrorClass? = Error, StoppedErrorClass? = Error })

Creates an `AwaitQueue` instance.

* `@param {Error} ClosedErrorClass`: Custom `Error` derived class that will be used to reject pending tasks after `close()` method has been called. If not set, `Error` class is used.
* `@param {Error} StoppedErrorClass`: Custom `Error` derived class that will be used to reject pending tasks after `stop()` method has been called. If not set, `Error` class is used.

### async awaitQueue.push(task: AwaitQueueTask<T>, name?: string): Promise<T>

Accepts a task as argument and enqueues it after pending tasks. Once processed, the `push()` method resolves (or rejects) with the result returned by the given task.

* `@param task`: Function that must return a `Promise` or a directly a value.
* `@param name`: Optional task name (useful for `awaitQueue.dump()` method).

### awaitQueue.size: number

The number of ongoing enqueued tasks.

### awaitQueue.close(): void

Closes the queue. Pending tasks will be rejected with the given  `ClosedErrorClass` error. The `AwaitQueue` instance is no longer usable (this method is terminal).

### awaitQueue.stop(): void

Make ongoing pending tasks reject with the given `StoppedErrorClass` error. The `AwaitQueue` instance is still usable for future tasks added via `push()` method.

### awaitQueue.dump(): AwaitQueueDumpItem[]

Returns an array with information about pending tasks in the queue. See the `AwaitQueueDumpItem` type above.


## Usage example

```js
const { AwaitQueue } = require('awaitqueue');

function taskFactory(id)
{
  console.log('creating task %d', id);

  // Return a function that returns a Promise (a task).
  return function()
  {
    return new Promise((resolve) =>
    {
      console.log('running task %d', id);
      setTimeout(() => resolve(id), 2000);
    });
  };
}

async function run()
{
  const queue = new AwaitQueue();
  let result;

  console.log('1. calling queue.push()');
  result = await queue.push(taskFactory('1'));
  console.log('1. task result:', result);

  console.log('2. calling queue.push()');
  result = await queue.push(taskFactory('2'));
  console.log('2. task result:', result);

  console.log('3. calling queue.push()');
  await new Promise((resolve) =>
  {
    queue.push(taskFactory('3'))
      .then(() =>
      {
        console.warn('3. task should not succeed (it was stopped)');
        resolve();
      })
      .catch((error) =>
      {
        console.log('3. task failed as expected because it was stopped (%s)', error.toString());
        resolve();
      });

    console.log('3. calling queue.stop()');
    queue.stop();
  });

  console.log('calling queue.close()');
  queue.close();

  try
  {
    console.log('4. calling queue.push()');
    await queue.push(taskFactory('4'));
  }
  catch (error)
  {
    console.error('4. task failed as expected because it was closed (%s)', error.toString());
  }
}

run();
```

Output:

```
1. calling queue.push()
creating task 1
running task 1
1. task result: 1

2. calling queue.push()
creating task 2
running task 2
2. task result: 2

3. calling queue.push()
creating task 3
running task 3
3. calling queue.stop()
3. task failed as expected because it was stopped (Error: AwaitQueue stopped)

calling queue.close()

4. calling queue.push()
creating task 4
4. task failed as expected because it was closed (Error: AwaitQueue closed)
```


## Author

* Iñaki Baz Castillo [[website](https://inakibaz.me)|[github](https://github.com/ibc/)]


## License

[ISC](./LICENSE)