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