Node-async-runner NPM

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.

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:

npm install async-runner

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

Usage

Basic Usage

const AsyncRunner = require('async-runner');

const runner = new AsyncRunner({ maxThreads: 5, stopOnError: false });

runner.add([
  async function () {
    // Your async code here
  },
  // ... more tasks
]);

runner.run().then((results) => {
  console.log('Results:', results);
});

Adding Tasks

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

// Adding a single task function
runner.add(async function () {
  // Task code
});

// Adding tasks with names
runner.add([
  {
    task: async function () {
      // Task code
    },
    name: 'Task One',
  },
  {
    task: async function () {
      // Task code
    },
    name: 'Task Two',
  },
]);

Event Handling

You can listen to various events emitted by the runner:

runner.on('next', (taskFunction, taskHash, taskName) => {
  console.log(`Starting task: ${taskName || 'Unnamed Task'}`);
  console.log(`Task Hash: ${taskHash}`);
});

runner.on('done', (results, errors) => {
  console.log('All tasks completed.');
  console.log('Results:', results);
  if (errors && errors.length > 0) {
    console.log('Errors:', errors);
  }
});

runner.on('error', (err) => {
  console.error('Execution halted due to error:', err);
});

Concurrency Control

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

const 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

new 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:

runner.add(async function () {
  // Task code
});

runner.add([
  {
    task: async function () {
      // Task code
    },
    name: 'Task Name',
  },
]);

run()

Execute the tasks.

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

Example:

runner.run().then((results) => {
  // Handle results
}).catch((error) => {
  // Handle error
});

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:

runner.on('next', (taskFunction, taskHash, taskName) => {
  // Handle event
});

runner.on('done', (results, errors) => {
  // Handle completion
});

runner.on('error', (err) => {
  // Handle error
});

Examples

Simple Example

const AsyncRunner = require('async-runner');

const runner = new AsyncRunner({ maxThreads: 2, stopOnError: false });

runner.add([
  async function () {
    await new Promise((resolve) => setTimeout(resolve, 1000));
    return 'Result 1';
  },
  async function () {
    await new Promise((resolve) => setTimeout(resolve, 500));
    return 'Result 2';
  },
]);

runner.run().then((results) => {
  console.log('Results:', results);
});

Using Task Names and Hashes

const AsyncRunner = require('async-runner');

const runner = new AsyncRunner({ maxThreads: 2, stopOnError: false });

runner.add([
  {
    task: async function () {
      await new Promise((resolve) => setTimeout(resolve, 1000));
      return 'Result 1';
    },
    name: 'Fetch Data',
  },
  {
    task: async function () {
      await new Promise((resolve) => setTimeout(resolve, 500));
      return 'Result 2';
    },
    name: 'Process Data',
  },
]);

runner.on('next', (taskFunction, taskHash, taskName) => {
  console.log(`Starting task: ${taskName}`);
  console.log(`Task Hash: ${taskHash}`);
});

runner.on('done', (results, errors) => {
  console.log('All tasks completed.');
  console.log('Results:', results);
});

runner.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.