note:

This update of this package is in development, do not use in production

AsyncRunner v2.0.0

AsyncRunner is a Node.js utility for managing and executing asynchronous tasks with controlled concurrency. Version 2.0.0 introduces modern JavaScript features (async/await), task hashing, task naming, and enhanced event handling.

Table of Contents

• Features
• Installation
• Usage
  • Basic Usage
  • Adding Tasks
  • Event Handling
• Concurrency Control
• Task Execution Order
• API Reference
  • Constructor
  • add(task)
  • run()
  • Events
• Examples
  • Simple Example
  • Using Task Names and Hashes
• Version History

---

Features

• Asynchronous Task Management: Manage a queue of asynchronous tasks using async/await.
• Controlled Concurrency: Limit the number of tasks running concurrently.
• Task Hashing: Automatically assign a unique hash to each task based on its function code.
• Task Naming: Assign names to tasks for better identification.
• Event Emission: Emit events ('next', 'done', 'error') to track task execution.
• Result Collection: Collect results and errors, maintaining the order of tasks added.
• Error Handling: Optionally stop execution upon encountering an error.

Installation

You can install AsyncRunner via npm:

1npm install async-runner

Or add the async-runner.js file to your project.

Usage

Basic Usage

1const AsyncRunner = require('async-runner');
2
3const runner = new AsyncRunner({ maxThreads: 5, stopOnError: false });
4
5runner.add([
6  async function () {
7    // Your async code here
8  },
9  // ... more tasks
10]);
11
12runner.run().then((results) => {
13  console.log('Results:', results);
14});

Adding Tasks

Tasks can be added as functions or as objects with a task function and an optional name:

1// Adding a single task function
2runner.add(async function () {
3  // Task code
4});
5
6// Adding tasks with names
7runner.add([
8  {
9    task: async function () {
10      // Task code
11    },
12    name: 'Task One',
13  },
14  {
15    task: async function () {
16      // Task code
17    },
18    name: 'Task Two',
19  },
20]);

Event Handling

You can listen to various events emitted by the runner:

1runner.on('next', (taskFunction, taskHash, taskName) => {
2  console.log(`Starting task: ${taskName || 'Unnamed Task'}`);
3  console.log(`Task Hash: ${taskHash}`);
4});
5
6runner.on('done', (results, errors) => {
7  console.log('All tasks completed.');
8  console.log('Results:', results);
9  if (errors && errors.length > 0) {
10    console.log('Errors:', errors);
11  }
12});
13
14runner.on('error', (err) => {
15  console.error('Execution halted due to error:', err);
16});

Concurrency Control

The maxThreads option controls the maximum number of tasks that can run concurrently. Adjust it according to your needs:

1const runner = new AsyncRunner({ maxThreads: 3 });

• Note: Setting maxThreads to 1 will execute tasks sequentially.

Task Execution Order

• Task Start Order: Tasks are started in the order they are added.
• Task Completion Order: Tasks may complete out of order due to their asynchronous nature.
• Result Storage Order: Results are stored in the order of tasks added, regardless of completion order.

API Reference

Constructor

1new AsyncRunner(options)

• options: An object with the following properties:
  • maxThreads (number, default 10): Maximum number of concurrent tasks.
  • stopOnError (boolean, default false): Stop execution upon encountering an error.

add(task)

Add tasks to the runner.

• task: A function, an array of functions, an object, or an array of objects. Each object can have:
  • task (function): The task function to execute.
  • name (string, optional): A name for the task.

Example:

1runner.add(async function () {
2  // Task code
3});
4
5runner.add([
6  {
7    task: async function () {
8      // Task code
9    },
10    name: 'Task Name',
11  },
12]);

run()

Execute the tasks.

• Returns a Promise that resolves with the results array or rejects with an error if stopOnError is true.

Example:

1runner.run().then((results) => {
2  // Handle results
3}).catch((error) => {
4  // Handle error
5});

Events

• 'next': Emitted before a task starts execution.

  • Listener Parameters:
    • taskFunction (function): The task function.
    • taskHash (string): Unique hash of the task.
    • taskName (string or null): Name of the task.

• 'done': Emitted when all tasks have completed.

  • Listener Parameters:
    • results (array): Array of results from tasks.
    • errors (array): Array of errors (if any).

• 'error': Emitted when an error occurs and stopOnError is true.

  • Listener Parameters:
    • error (Error): The error that occurred.

Example:

1runner.on('next', (taskFunction, taskHash, taskName) => {
2  // Handle event
3});
4
5runner.on('done', (results, errors) => {
6  // Handle completion
7});
8
9runner.on('error', (err) => {
10  // Handle error
11});

Examples

Simple Example

1const AsyncRunner = require('async-runner');
2
3const runner = new AsyncRunner({ maxThreads: 2, stopOnError: false });
4
5runner.add([
6  async function () {
7    await new Promise((resolve) => setTimeout(resolve, 1000));
8    return 'Result 1';
9  },
10  async function () {
11    await new Promise((resolve) => setTimeout(resolve, 500));
12    return 'Result 2';
13  },
14]);
15
16runner.run().then((results) => {
17  console.log('Results:', results);
18});

Using Task Names and Hashes

1const AsyncRunner = require('async-runner');
2
3const runner = new AsyncRunner({ maxThreads: 2, stopOnError: false });
4
5runner.add([
6  {
7    task: async function () {
8      await new Promise((resolve) => setTimeout(resolve, 1000));
9      return 'Result 1';
10    },
11    name: 'Fetch Data',
12  },
13  {
14    task: async function () {
15      await new Promise((resolve) => setTimeout(resolve, 500));
16      return 'Result 2';
17    },
18    name: 'Process Data',
19  },
20]);
21
22runner.on('next', (taskFunction, taskHash, taskName) => {
23  console.log(`Starting task: ${taskName}`);
24  console.log(`Task Hash: ${taskHash}`);
25});
26
27runner.on('done', (results, errors) => {
28  console.log('All tasks completed.');
29  console.log('Results:', results);
30});
31
32runner.run();

Version History

• v2.0.0
  • Rewritten using async/await for modern Node.js support.
  • Tasks are assigned unique hashes based on their function code.
  • Tasks can be given names for identification.
  • Added 'next' event emitted before each task execution.