power-tasks

Powerful task management for JavaScript/TypeScript. Support for hierarchical tasks, dependencies, concurrency control, and a task queue.

Installation

• npm install power-tasks --save

Node Compatibility

• node >= 14.x

Core Concepts

Task

A Task represents a unit of work that can be executed. It can be a simple function, or it can have children and dependencies. Tasks are AsyncEventEmitter instances, meaning they emit events during their lifecycle.

Creating a Simple Task

import { Task } from 'power-tasks';

const task = new Task(async ({signal}) => {
  // Do some work
  return 'Result';
});

task.on('start', () => console.log('Task started!'));
task.on('finish', (t) => console.log(`Task finished with result: ${t.result}`));

await task.start();

Hierarchical Tasks

Tasks can have children. A parent task is considered finished when all its children are finished.

const parent = new Task([
  new Task(async () => 'Child 1'),
  new Task(async () => 'Child 2')
], {name: 'Parent Task'});

await parent.start();

Task Dependencies

Tasks can depend on other tasks by their name or instance. A task will wait for its dependencies to finish before starting.

const task1 = new Task(async () => 'Result 1', {name: 'T1'});
const task2 = new Task(async () => 'Result 2', {
  name: 'T2',
  dependencies: ['T1']
});

const parent = new Task([task1, task2]);
await parent.start();

TaskQueue

TaskQueue manages a list of tasks with concurrency control. It allows you to limit the number of tasks running at the same time and provides methods to pause, resume, and clear the queue.

import { TaskQueue } from 'power-tasks';

const queue = new TaskQueue({concurrency: 2});

queue.enqueue(async () => { /* ... */
});
queue.enqueue(async () => { /* ... */
});
queue.enqueue(async () => { /* ... */
});

await queue.wait(); // Wait for all tasks to finish

API Reference

Task

A Task represents a unit of work that can be executed. It supports hierarchical tasks, dependencies, and emits events throughout its lifecycle.

Constructor

• new Task(execute, options?)
  • execute: TaskFunction - The function to be executed by the task.
  • options: `TaskOptions - Configuration options for the task.
• new Task(children, options?)
  • children: TaskLike[] - An array of child tasks or task functions.
  • options: TaskOptions - Configuration options for the task.

Properties

Property	Type	Description
id	string	Unique identifier of the task.
name	string | undefined	Name of the task.
status	TaskStatus	Current status of the task.
message	string	Current message of the task.
result	any	Result produced by the task.
error	any	Error if the task failed.
isFailed	boolean	Whether the task has failed.
isAborted	boolean	Whether the task has been aborted or aborting
isFinished	boolean	Whether the task has completed (successfully, failed, or aborted).
isStarted	boolean	Whether the task has started but not yet finished.
executeDuration	number | undefined	Duration of the task execution in milliseconds.
children	Task[] | undefined	List of child tasks.
dependencies	Task[] | undefined	List of tasks this task depends on.
failedChildren	Task[] | undefined	List of child tasks that failed.
failedDependencies	Task[] | undefined	List of dependencies that failed.
needWaiting	boolean	Whether the task is currently waiting for children or dependencies to finish.
options	TaskOptions	Task configuration options.
parent	Task | undefined	The parent task if this is a child task.

Methods

• start(): Starts the task execution. Returns the task instance.

  task.start();

• abort(): Aborts the task execution. Returns the task instance.

  task.abort();

• toPromise(): Returns a promise that resolves with the task result or rejects with the task error.

  const result = await task.toPromise();

• getWaitingTasks(): Gets a list of tasks that this task is currently waiting for.

  const waitingTasks = task.getWaitingTasks();

• reset(): Resets the task to its initial state so it can be started again.

  task.reset();

• toJSON(): Returns a JSON-compatible representation of the task.

  const json = task.toJSON();

Events

• start: Emitted when the task starts.

  task.on('start', (task) => console.log('Started'));

• run: Emitted when the execution function is called.

  task.on('run', (task) => console.log('Running'));

• finish: Emitted when the task finishes (successfully, failed, or aborted).

  task.on('finish', (task) => console.log('Finished'));

• abort: Emitted when the task is aborted.

  task.on('abort', (task) => console.log('Aborted'));

• status-change: Emitted when the task status changes.

  task.on('status-change', (task, status) => console.log('Status changed to', status));

• update: Emitted when task properties are updated.

  task.on('update', (task, properties) => console.log('Updated', properties));

• update-recursive: Emitted when properties of the task or any of its children are updated.

  task.on('update-recursive', (task, properties) => console.log('Recursive update', properties));

• error: Emitted when an error occurs.

  task.on('error', (error, task) => console.error(error));

• wait-end: Emitted when the task stops waiting for dependencies.

  task.on('wait-end', () => console.log('Wait ended'));

TaskOptions

Option	Type	Description
id	any	Unique identifier for the task.
name	string	Name of the task (used for dependencies).
args	any[]	Arguments passed to the task function.
children	TaskLike[] | () => ...	List of child tasks or a function that returns them.
dependencies	(Task | string)[]	Tasks that must finish before this task starts.
concurrency	number	Number of child tasks to run in parallel.
bail	boolean	If true (default), aborts children if one fails.
serial	boolean	If true, runs children one by one (shortcut for concurrency: 1).
exclusive	boolean	If true, the task queue waits for this task to complete exclusively.
abortSignal	AbortSignal	An optional AbortSignal object that can be used to communicate with, or to abort, an operation.
abortTimeout	number	Timeout in ms to wait for aborting tasks.
onStart	Function	Callback invoked when the task starts.
onFinish	Function	Callback invoked when the task finishes.
onRun	Function	Callback invoked when the task's execution function begins.
onStatusChange	Function	Callback invoked when the task's status changes.
onUpdate	Function	Callback invoked when the task's properties are updated.
onUpdateRecursive	Function	Callback invoked when properties of the task or its children are updated.

TaskStatus

A task can be in one of the following states:

• idle: Task is created but not yet started.
• waiting: Task is waiting for its dependencies.
• running: Task is currently executing.
• fulfilled: Task completed successfully.
• failed: Task failed with an error.
• aborting: Task is in the process of being aborted.
• aborted: Task has been aborted.

TaskQueue

TaskQueue manages the execution of tasks with concurrency control.

Constructor

• new TaskQueue(options?)
  • options: TaskQueueOptions - Configuration options for the queue.

Properties

Property	Type	Description
size	number	Total number of tasks in the queue (both queued and running).
running	number	Number of tasks currently running.
queued	number	Number of tasks currently waiting in the queue.
paused	boolean	Whether the queue is currently paused.
concurrency	number | undefined	The maximum number of tasks to run concurrently.
maxQueue	number | undefined	The maximum number of tasks allowed in the queue.

Methods

• enqueue(task): Adds a task to the end of the queue. Returns the Task instance.

  const task = queue.enqueue(async () => 'Done');

• enqueuePrepend(task): Adds a task to the beginning of the queue. Returns the Task instance.

  queue.enqueuePrepend(myTask);

• getTask(id): Retrieves a task by its ID. Returns the Task instance if found, or undefined otherwise.

  const task = queue.getTask('my-task-id');

• pause(): Pauses the queue execution.

  queue.pause();

• resume(): Resumes the queue execution.

  queue.resume();

• clearQueue(): Removes all queued tasks and aborts them.

  queue.clearQueue();

• abortAll(): Aborts all running tasks and clears the queue.

  queue.abortAll();

• wait(): Returns a promise that resolves when all tasks have finished and the queue is empty.

  await queue.wait();

Events

• enqueue: Emitted when a task is added to the queue.

  queue.on('enqueue', (task) => console.log('Task enqueued'));

• finish: Emitted when all tasks in the queue have finished and the queue is empty.

  queue.on('finish', () => console.log('Queue finished'));

• error: Emitted when a task in the queue emits an error.

  queue.on('error', (error, task) => console.error(error));

TaskQueueOptions

Option	Type	Description
concurrency	number	The maximum number of tasks to run concurrently.
maxQueue	number	The maximum number of tasks allowed in the queue (including running).
paused	boolean	Whether the queue should start in a paused state.

License

MIT