@supercharge/promise-pool - npm Package Compare versions

Comparing version 2.1.0 to 2.2.0

dist/index.d.ts

 import { PromisePool } from './promise-pool';
 export default PromisePool;
+export * from './contracts';
 export * from './promise-pool';
 export * from './promise-pool-error';
 export * from './return-value';
-export * from './stoppable';
 export * from './stop-the-promise-pool-error';

dist/index.js

 'use strict';
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
@@ -15,6 +19,6 @@ if (k2 === undefined) k2 = k;
 exports.default = promise_pool_1.PromisePool;
+__exportStar(require("./contracts"), exports);
 __exportStar(require("./promise-pool"), exports);
 __exportStar(require("./promise-pool-error"), exports);
 __exportStar(require("./return-value"), exports);
-__exportStar(require("./stoppable"), exports);
 __exportStar(require("./stop-the-promise-pool-error"), exports);

dist/promise-pool-executor.d.ts

@@ -1,7 +0,8 @@
-import { Stoppable } from './stoppable';
 import { ReturnValue } from './return-value';
 import { PromisePoolError } from './promise-pool-error';
-export declare type ErrorHandler<T> = (error: Error, item: T, pool: Stoppable) => void | Promise<void>;
-export declare type ProcessHandler<T, R> = (item: T, index: number, pool: Stoppable) => R | Promise<R>;
-export declare class PromisePoolExecutor<T, R> implements Stoppable {
+import { ProcessHandler, OnProgressCallback, Statistics, Stoppable } from './contracts';
+export declare class PromisePoolExecutor<T, R> implements Stoppable, Statistics<T> {
+    /**
+     * Stores the internal properties.
+     */
     private meta;
@@ -17,2 +18,10 @@ /**
     /**
+     * The `taskStarted` handler callback functions
+     */
+    private onTaskStartedHandlers;
+    /**
+      * The `taskFinished` handler callback functions
+      */
+    private onTaskFinishedHandlers;
+    /**
      * Creates a new promise pool executer instance with a default concurrency of 10.
@@ -50,2 +59,8 @@ */
     /**
+     * Returns the number of items to process.
+     *
+     * @returns {Number}
+     */
+    itemsCount(): number;
+    /**
      * Returns the list of active tasks.
@@ -57,2 +72,24 @@ *
     /**
+     * Returns the number of currently processed tasks.
+     *
+     * @returns {Number}
+     */
+    activeTaskCount(): number;
+    /**
+     * Returns the list of processed items.
+     *
+     * @returns {T[]}
+     */
+    processedItems(): T[];
+    /**
+     * Returns the number of processed items.
+     *
+     * @returns {Number}
+     */
+    processedCount(): number;
+    /**
+     * Returns the percentage progress of items that have been processed.
+     */
+    processedPercentage(): number;
+    /**
      * Returns the list of results.
@@ -92,2 +129,18 @@ *
     /**
+     * Set the handler function to execute when started a task.
+     *
+     * @param {Function} handler
+     *
+     * @returns {this}
+     */
+    onTaskStarted(handlers: Array<OnProgressCallback<T>>): this;
+    /**
+      * Assign the given callback `handler` function to run when a task finished.
+     *
+     * @param {OnProgressCallback<T>} handlers
+     *
+     * @returns {this}
+     */
+    onTaskFinished(handlers: Array<OnProgressCallback<T>>): this;
+    /**
      * Determines whether the number of active tasks is greater or equal to the concurrency limit.
@@ -180,2 +233,3 @@ *
      *
+     * @param {Error} error
      * @param {T} item
@@ -200,2 +254,10 @@ */
     /**
+     * Run the onTaskStarted handlers.
+     */
+    runOnTaskStartedHandlers(item: T): void;
+    /**
+     * Run the onTaskFinished handlers.
+     */
+    runOnTaskFinishedHandlers(item: T): void;
+    /**
      * Rethrow the given `error` if it’s not an instance of `StopThePromisePoolError`.
@@ -202,0 +264,0 @@ *

dist/promise-pool-executor.js

@@ -17,6 +17,9 @@ 'use strict';
             stopped: false,
-            concurrency: 10
+            concurrency: 10,
+            processedItems: [],
         };
         this.handler = () => { };
         this.errorHandler = undefined;
+        this.onTaskStartedHandlers = [];
+        this.onTaskFinishedHandlers = [];
     }
@@ -62,2 +65,10 @@ /**
     /**
+     * Returns the number of items to process.
+     *
+     * @returns {Number}
+     */
+    itemsCount() {
+        return this.items().length;
+    }
+    /**
      * Returns the list of active tasks.
@@ -71,2 +82,32 @@ *
     /**
+     * Returns the number of currently processed tasks.
+     *
+     * @returns {Number}
+     */
+    activeTaskCount() {
+        return this.tasks().length;
+    }
+    /**
+     * Returns the list of processed items.
+     *
+     * @returns {T[]}
+     */
+    processedItems() {
+        return this.meta.processedItems;
+    }
+    /**
+     * Returns the number of processed items.
+     *
+     * @returns {Number}
+     */
+    processedCount() {
+        return this.processedItems().length;
+    }
+    /**
+     * Returns the percentage progress of items that have been processed.
+     */
+    processedPercentage() {
+        return (this.processedCount() / this.itemsCount()) * 100;
+    }
+    /**
      * Returns the list of results.
@@ -118,2 +159,24 @@ *
     /**
+     * Set the handler function to execute when started a task.
+     *
+     * @param {Function} handler
+     *
+     * @returns {this}
+     */
+    onTaskStarted(handlers) {
+        this.onTaskStartedHandlers = handlers;
+        return this;
+    }
+    /**
+      * Assign the given callback `handler` function to run when a task finished.
+     *
+     * @param {OnProgressCallback<T>} handlers
+     *
+     * @returns {this}
+     */
+    onTaskFinished(handlers) {
+        this.onTaskFinishedHandlers = handlers;
+        return this;
+    }
+    /**
      * Determines whether the number of active tasks is greater or equal to the concurrency limit.
@@ -186,2 +249,12 @@ *
         }
+        this.onTaskStartedHandlers.forEach(handler => {
+            if (handler && typeof handler !== 'function') {
+                throw new Error(`The onTaskStarted handler must be a function. Received ${typeof handler}`);
+            }
+        });
+        this.onTaskFinishedHandlers.forEach(handler => {
+            if (handler && typeof handler !== 'function') {
+                throw new Error(`The error handler must be a function. Received ${typeof handler}`);
+            }
+        });
         return this;
@@ -232,4 +305,8 @@ }
                 .handleErrorFor(error, item);
+        }).finally(() => {
+            this.processedItems().push(item);
+            this.runOnTaskFinishedHandlers(item);
         });
         this.tasks().push(task);
+        this.runOnTaskStartedHandlers(item);
     }
@@ -270,2 +347,3 @@ /**
      *
+     * @param {Error} error
      * @param {T} item
@@ -307,2 +385,18 @@ */
     /**
+     * Run the onTaskStarted handlers.
+     */
+    runOnTaskStartedHandlers(item) {
+        this.onTaskStartedHandlers.forEach(handler => {
+            handler(item, this);
+        });
+    }
+    /**
+     * Run the onTaskFinished handlers.
+     */
+    runOnTaskFinishedHandlers(item) {
+        this.onTaskFinishedHandlers.forEach(handler => {
+            handler(item, this);
+        });
+    }
+    /**
      * Rethrow the given `error` if it’s not an instance of `StopThePromisePoolError`.
@@ -309,0 +403,0 @@ *

dist/promise-pool.d.ts

 import { ReturnValue } from './return-value';
-import { ErrorHandler, ProcessHandler } from './promise-pool-executor';
+import { ErrorHandler, ProcessHandler, OnProgressCallback } from './contracts';
 export declare class PromisePool<T> {
@@ -17,2 +17,10 @@ /**
     /**
+     * The `taskStarted` handler callback functions
+     */
+    private readonly onTaskStartedHandlers;
+    /**
+     * The `taskFinished` handler callback functions
+     */
+    private readonly onTaskFinishedHandlers;
+    /**
      * Instantiates a new promise pool with a default `concurrency: 10` and `items: []`.
@@ -42,3 +50,3 @@ *
      *
-     * @param {Array} items
+     * @param {T[]} items
      *
@@ -51,3 +59,3 @@ * @returns {PromisePool}
      *
-     * @param {Array} items
+     * @param {T[]} items
      *
@@ -60,3 +68,3 @@ * @returns {PromisePool}
      *
-     * @param {Function} handler
+     * @param {ErrorHandler<T>} handler
      *
@@ -67,6 +75,22 @@ * @returns {PromisePool}
     /**
+     * Assign the given callback `handler` function to run when a task starts.
+     *
+     * @param {OnProgressCallback<T>} handler
+     *
+     * @returns {PromisePool}
+     */
+    onTaskStarted(handler: OnProgressCallback<T>): PromisePool<T>;
+    /**
+      * Assign the given callback `handler` function to run when a task finished.
+      *
+      * @param {OnProgressCallback<T>} handler
+      *
+      * @returns {PromisePool}
+      */
+    onTaskFinished(handler: OnProgressCallback<T>): PromisePool<T>;
+    /**
      * Starts processing the promise pool by iterating over the items
      * and running each item through the async `callback` function.
      *
-     * @param {Function} The async processing function receiving each item from the `items` array.
+     * @param {ProcessHandler} The async processing function receiving each item from the `items` array.
      *
@@ -73,0 +97,0 @@ * @returns Promise<{ results, errors }>

dist/promise-pool.js

@@ -15,2 +15,4 @@ 'use strict';
         this.errorHandler = undefined;
+        this.onTaskStartedHandlers = [];
+        this.onTaskFinishedHandlers = [];
     }
@@ -41,3 +43,3 @@ /**
      *
-     * @param {Array} items
+     * @param {T[]} items
      *
@@ -52,3 +54,3 @@ * @returns {PromisePool}
      *
-     * @param {Array} items
+     * @param {T[]} items
      *
@@ -63,3 +65,3 @@ * @returns {PromisePool}
      *
-     * @param {Function} handler
+     * @param {ErrorHandler<T>} handler
      *
@@ -73,6 +75,28 @@ * @returns {PromisePool}
     /**
+     * Assign the given callback `handler` function to run when a task starts.
+     *
+     * @param {OnProgressCallback<T>} handler
+     *
+     * @returns {PromisePool}
+     */
+    onTaskStarted(handler) {
+        this.onTaskStartedHandlers.push(handler);
+        return this;
+    }
+    /**
+      * Assign the given callback `handler` function to run when a task finished.
+      *
+      * @param {OnProgressCallback<T>} handler
+      *
+      * @returns {PromisePool}
+      */
+    onTaskFinished(handler) {
+        this.onTaskFinishedHandlers.push(handler);
+        return this;
+    }
+    /**
      * Starts processing the promise pool by iterating over the items
      * and running each item through the async `callback` function.
      *
-     * @param {Function} The async processing function receiving each item from the `items` array.
+     * @param {ProcessHandler} The async processing function receiving each item from the `items` array.
      *
@@ -86,2 +110,4 @@ * @returns Promise<{ results, errors }>
             .handleError(this.errorHandler)
+            .onTaskStarted(this.onTaskStartedHandlers)
+            .onTaskFinished(this.onTaskFinishedHandlers)
             .for(this.items)
@@ -88,0 +114,0 @@ .start();

package.json

 {
   "name": "@supercharge/promise-pool",
   "description": "Map-like, concurrent promise processing for Node.js",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "author": "Marcus Pöhls <[e-mail]>",
@@ -9,15 +9,10 @@ "bugs": {
   },
-  "dependencies": {},
   "devDependencies": {
+    "@supercharge/eslint-config-typescript": "~2.0.0",
     "@supercharge/tsconfig": "~1.0.0",
-    "@typescript-eslint/eslint-plugin": "~4.33.0",
-    "c8": "~7.10.0",
-    "eslint": "~7.32.0",
-    "eslint-config-standard-with-typescript": "~21.0.1",
-    "eslint-plugin-import": "~2.25.3",
-    "eslint-plugin-node": "~11.1.0",
-    "eslint-plugin-promise": "~5.2.0",
-    "expect": "~27.4.2",
-    "typescript": "~4.4.4",
-    "uvu": "~0.5.2"
+    "c8": "~7.11.3",
+    "eslint": "~8.15.0",
+    "expect": "~28.1.0",
+    "typescript": "~4.6.4",
+    "uvu": "~0.5.3"
   },
@@ -24,0 +19,0 @@ "engines": {

README.md

@@ -40,5 +40,6 @@ <div align="center">
 ## Docs
-Find all the [details and available methods in the extensive Supercharge docs](https://superchargejs.com/docs/promise-pool).
 
+- 📖 [Documentation](https://superchargejs.com/docs/promise-pool)
 
+
 ## Usage
@@ -156,3 +157,39 @@ Using the promise pool is pretty straightforward. The package exposes a class and you can create a promise pool instance using the fluent interface.
 
+## Callback for Started and Finished Task
+You can receive a callback when any task has started with `.onTaskStarted()` with the `item` has starting this process, with `percentage` of progress the items that has started, `activeTasks` that is processing and `finishedTasks`:
 
+
+```js
+const { PromisePool } = require('@supercharge/promise-pool')
+
+await PromisePool
+  .for(users)
+  .onTaskStarted((item, percentage, activeTasks, finishedTasks) => {
+    console.log(`Progress: ${percentage}%`)
+    console.log(`Active tasks: ${activeTasks.length}`)
+    console.log(`Finished tasks: ${finishedTasks.length}`)
+  })
+  .process(async (user, index, pool) => {
+    // processes the `user` data
+  })
+```
+
+You can also receive callback `.onTaskFinished()`, with parameter `percentage` of progress the items that has finished: 
+
+```js
+const { PromisePool } = require('@supercharge/promise-pool')
+
+await PromisePool
+  .for(users)
+  .onTaskFinished((item, percentage, activeTasks, finishedTasks) => {
+    console.log(`Progress: ${percentage}%`)
+    console.log(`Active tasks: ${activeTasks.length}`)
+    console.log(`Finished tasks: ${finishedTasks.length}`)
+  })
+  .process(async (user, index, pool) => {
+    // processes the `user` data
+  })
+```
+
+
 ## Contributing
@@ -159,0 +196,0 @@

No alert changes

Improved metrics

Total package byte prevSize

39778

increased by27.4%

Dev dependency count

7

decreased by-36.36%

Number of package files

23

increased by35.29%

Lines of code

1116

increased by30.68%

Number of lines in readme file

210

increased by21.39%

No dependency changes