ThreadedOperation

A simple yet powerful library for running operations concurrently with control over threading, progress tracking, and event management.

Features

• Threading: Run tasks concurrently with a customizable number of threads.
• Progress Tracking: Monitor the progress of operations in real time.
• Event System: Emit and listen to events like progress, end, and others.
• Flexible: Customizable iteration array and thread function.

Installation

To install the package, run:

npm install threaded-operation

Usage

Basic example

import { ThreadedOperation } from 'threaded-operation';

async function bootstrap() {
  const options = {
    iterationArray: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
    maxThreads: 3,
    maxThreadRetries: 1,
    progressStep: 10,
    threadFn: async (item: number) => {
      await new Promise((resolve) => setTimeout(resolve, 500));
      return item * 2;
    },
  };

  const threadedOperation = new ThreadedOperation<number, number>(options);

  // Listen to progress updates
  threadedOperation.on('progress', (data) => {
    console.log(
      `Progress: ${data.percentage}% - Items left: ${data.itemsLeft}`,
    );
  });

  // Listen to the end of the operation
  threadedOperation.on('end', (results) => {
    console.log('Operation finished with results:', results);
  });

  // Start the operation
  const results = await threadedOperation.run();

  console.log('Final results:', results);
}

bootstrap();

You can also use the threadedOperation without awaiting for results :

import { ThreadedOperation } from 'threaded-operation';

async function bootstrap() {
  const options = {
    iterationArray: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
    maxThreads: 3,
    maxThreadRetries: 1,
    progressStep: 10,
    threadFn: async (item: number) => {
      await new Promise((resolve) => setTimeout(resolve, 500));
      return item * 2;
    },
  };

  const threadedOperation = new ThreadedOperation<number, number>(options);

  // Listen to the end of the operation
  threadedOperation.on('end', (results) => {
    console.log('Operation finished with results:', results);
  });

  // Start the operation
  threadedOperation.run();

  // Do whatever you want here...
}

bootstrap();

Options

| Name | Description | Required | Default | Example | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------- | ------------------------------------------------- | | iterationArray | The array of items to iterate over. These can be any values that your threadFn function can handle. | yes | undefined | [1, 2] | | threadFn | A function that will be executed for each item in the iteration array. It must return a Promise that resolves to the result of the operation. | yes | undefined | async (value: number, context?: unknown) => value | | maxThreads | The maximum number of concurrent threads to use. | no | 1 | 10 | | progressStep | Defines the progress step (percentage intervals) to emit the progress events. | no | 1 | 10 | | maxThreadRetries | The number of retries if threadFn fails. | no | 0 | 10 | | finishActiveThreadsOnStop | Do we wait active threads when stopping operation | no | true | true | | keepIteratedValuesInResult | Do we return iteratedValues in result in the same order as results | no | false | false | | threadTimeout | Timeout for threads (a timed out thread will be counted as an error), 0 means disabled | no | 0 | 0 | | context | Object that is passed to events and thread function | no | undefined | { totalSize: 100 } |

Events

The following events are available:

• progress: Emitted as the operation progresses.
  • data: { percentage: number, itemsLeft: number, context: unknown }
• fail: Emitted when any thread fails.
  • value: IteratedValue
• end: Emitted when the operation finishes.
  • data: { results: ThreadResult[], iteratedValues?: IteratedValue[], errors?: IteratedValue[], left?: IteratedValue[] }

Example of listening to events :

threadedOperation.on('progress', (data) => {
  console.log(`Progress: ${data.percentage}%`);
});

threadedOperation.on('fail', (value) => {
  console.log('Failed value:', value);
});

threadedOperation.on('end', (results) => {
  console.log('Finished results:', results);
});

Methods

run()

Starts the operation and returns a Promise with the results once completed.

await threadedOperation.run();

stop()

Stops the operation.

If option finishActiveThreadsOnStop is set to true, it will wait active threads to finish. Else, it will stop immediately all threads, and send unfinshed iterationItem to result errors.

If an operation is stopped and it has some iterated values left, it will return them in result of run() or in end event.

threadedOperation.stop();

on(event: string, listener: Function)

Attach event listeners for specific events like progress and end.

threadedOperation.on('progress', (data) => { ... });