@mystogab/promise-pool 1.0.0

package/README.md

@@ -0,0 +1,87 @@
+# @mystogab/promise-pool 🚀
+
+A lightweight, high-performance, and memory-efficient asynchronous pool for JavaScript and TypeScript. Designed for **modern Node.js** environments (20+).
+
+[![npm version](https://img.shields.io)](https://www.npmjs.com)
+[![License: MIT](https://img.shields.io)](https://opensource.org)
+![Bundle Size](https://img.shields.io)
+
+## Why Promise Pool?
+
+Unlike other libraries that use "batching" (waiting for the slowest task in a group to finish), **@mystogab/promise-pool** uses a **Dynamic Worker Queue**. As soon as a task finishes, a worker picks up the next one immediately.
+
+- **Stream-Friendly:** Supports `Iterable` and `AsyncIterable`. Process millions of items without loading them all into memory.
+- **Smart Control:** Stop execution gracefully using `POOL_STOP_SIGNAL`.
+- **Dual Build:** Native support for ESM and CommonJS.
+- **Zero Dependencies:** Ultra-light footprint for your project.
+
+---
+
+## Installation
+
+```bash
+npm i @mystogab/promise-pool
+```
+## Quick Start
+## Basic Usage
+```typescript
+import { promisePool } from '@mystogab/promise-pool';
+
+const items = [1, 2, 3, 4, 5];
+const task = async (id) => {
+  await new Promise(r => setTimeout(r, 100));
+  return `Result ${id}`;
+};
+
+const { results } = await promisePool(items, task, 2);
+console.log(results);
+```
+
+## Advanced Error Handling & Early Stop
+You can stop the entire pool if a critical error occurs (e.g., Auth Token expired) using the `POOL_STOP_SIGNAL`.
+
+```typescript
+import { promisePool, POOL_STOP_SIGNAL } from '@mystogab/promise-pool';
+
+const { results, stoppedPrematurely } = await promisePool(
+  hugeDataset,
+  processData,
+  5, // Concurrency
+  async (error, item) => {
+    if (error.status === 401) {
+      console.error("Critical error! Stopping pool...");
+      return POOL_STOP_SIGNAL;
+    }
+    console.warn(`Failed item ${item.id}: ${error.message}`);
+  }
+);
+```
+## Performance Comparison
+
+| Feature | Standard Promise.all | Common "Batch" Pools | @mystogab/promise-pool |
+|---------|----------------------|----------------------|--------------------|
+| Memory Usage | High (loads everything) | Medium | Ultra Low (Worker-based) |
+| Idle Time | None | High (waits for slowest) | Zero (Continuous flow) |
+| Async Iterators | No | Limited | Native Support |
+| Stop Signal | No | Manual/Complex | Elegant Symbol Signal |
+
+## API Reference
+`promisePool<T, R>(input, iteratorFn, concurrency?, errorHandler?)`
+
+Parameters:
+- `input`: `Iterable<T> | AsyncIterable<T>` - The data to process.
+- `iteratorFn`: `(item: T) => Promise<R>` - The async function to run for each item.
+- `concurrency`: `number` (Default: `2`) - Max number of simultaneous tasks.
+- `errorHandler`: `(error: any, item: T) => void | Promise<void> | typeof POOL_STOP_SIGNAL` - Optional handler for custom logic on failure.
+
+## Benchmarking
+You can measure the performance in your own environment:
+
+```javascript
+console.time('Pool Speed');
+await promisePool(data, tasks, 10);
+console.timeEnd('Pool Speed');
+```
+
+## License
+MIT © [@Mystogab]

package/dist/index.d.mts

@@ -0,0 +1,10 @@
+declare const POOL_STOP_SIGNAL: unique symbol;
+type ErrorHandler<T, E = any> = (error: E, item: T) => void | Promise<void> | typeof POOL_STOP_SIGNAL;
+declare const promisePool: <T, R>(input: Iterable<T> | AsyncIterable<T>, iteratorFn: (input: T) => Promise<R>, concurrency?: number, errorHandler?: ErrorHandler<T>) => Promise<{
+    results: R[];
+    errors: Error[];
+    failedItems: T[];
+    stoppedPrematurely: boolean;
+}>;
+
+export { POOL_STOP_SIGNAL, promisePool };

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+declare const POOL_STOP_SIGNAL: unique symbol;
+type ErrorHandler<T, E = any> = (error: E, item: T) => void | Promise<void> | typeof POOL_STOP_SIGNAL;
+declare const promisePool: <T, R>(input: Iterable<T> | AsyncIterable<T>, iteratorFn: (input: T) => Promise<R>, concurrency?: number, errorHandler?: ErrorHandler<T>) => Promise<{
+    results: R[];
+    errors: Error[];
+    failedItems: T[];
+    stoppedPrematurely: boolean;
+}>;
+
+export { POOL_STOP_SIGNAL, promisePool };

package/dist/index.js

@@ -0,0 +1,2 @@
+'use strict';var P=Symbol("POOL_STOP_SIGNAL"),p=async(t,i,l=2,s)=>{let a=[],n=[],c=[],r=false,y=t[Symbol.asyncIterator]?t[Symbol.asyncIterator]():t[Symbol.iterator](),m=Array.from({length:l},async()=>{for(;!r;){let{value:T,done:b}=await y.next();if(b||r)break;let o=T;try{let e=await i(o);r||a.push(e);}catch(e){c.push(e),n.push(o),s&&await s(e,o)===P&&(r=true);}}});return await Promise.all(m),{results:a,errors:c,failedItems:n,stoppedPrematurely:r}};exports.POOL_STOP_SIGNAL=P;exports.promisePool=p;//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["POOL_STOP_SIGNAL","promisePool","input","iteratorFn","concurrency","errorHandler","results","failedItems","errors","isAborted","iterable","workers","value","done","item","res","err"],"mappings":"aAAO,IAAMA,CAAAA,CAAmB,MAAA,CAAO,kBAAkB,CAAA,CAI5CC,CAAAA,CAAc,MACzBC,CAAAA,CACAC,CAAAA,CACAC,CAAAA,CAAc,CAAA,CACdC,CAAAA,GACG,CACH,IAAMC,CAAAA,CAAe,EAAC,CAChBC,CAAAA,CAAmB,EAAC,CACpBC,CAAAA,CAAkB,EAAC,CACrBC,CAAAA,CAAY,KAAA,CAGVC,CAAAA,CAAYR,CAAAA,CAAc,MAAA,CAAO,aAAa,CAAA,CAC/CA,EAA2B,MAAA,CAAO,aAAa,CAAA,EAAE,CACjDA,CAAAA,CAAsB,MAAA,CAAO,QAAQ,CAAA,EAAE,CAwBtCS,CAAAA,CAAU,KAAA,CAAM,IAAA,CAAK,CAAE,MAAA,CAAQP,CAAY,CAAA,CAtBlC,SAAY,CACzB,KAAO,CAACK,CAAAA,EAAW,CACjB,GAAM,CAAE,KAAA,CAAAG,CAAAA,CAAO,IAAA,CAAAC,CAAK,CAAA,CAAI,MAAMH,EAAS,IAAA,EAAK,CAE5C,GAAIG,CAAAA,EAAQJ,CAAAA,CAAW,MACvB,IAAMK,CAAAA,CAAOF,CAAAA,CAEb,GAAI,CACF,IAAMG,CAAAA,CAAM,MAAMZ,CAAAA,CAAWW,CAAI,CAAA,CAC5BL,CAAAA,EAAWH,CAAAA,CAAQ,IAAA,CAAKS,CAAG,EAClC,CAAA,MAASC,CAAAA,CAAK,CACZR,CAAAA,CAAO,IAAA,CAAKQ,CAAY,CAAA,CACxBT,CAAAA,CAAY,IAAA,CAAKO,CAAI,CAAA,CACjBT,CAAAA,EACa,MAAMA,CAAAA,CAAaW,CAAAA,CAAKF,CAAI,CAAA,GAC5Bd,CAAAA,GAAkBS,CAAAA,CAAY,IAAA,EAEjD,CACF,CACF,CAG0D,CAAA,CAC1D,OAAA,MAAM,OAAA,CAAQ,GAAA,CAAIE,CAAO,CAAA,CAElB,CAAE,OAAA,CAAAL,CAAAA,CAAS,MAAA,CAAAE,CAAAA,CAAQ,WAAA,CAAAD,CAAAA,CAAa,kBAAA,CAAoBE,CAAU,CACvE","file":"index.js","sourcesContent":["export const POOL_STOP_SIGNAL = Symbol('POOL_STOP_SIGNAL');\n\ntype ErrorHandler<T, E = any> = (error: E, item: T) => void | Promise<void> | typeof POOL_STOP_SIGNAL;\n\nexport const promisePool = async <T, R>(\n  input: Iterable<T> | AsyncIterable<T>,\n  iteratorFn: (input: T) => Promise<R>,\n  concurrency = 2,\n  errorHandler?: ErrorHandler<T>\n) => {\n  const results: R[] = [];\n  const failedItems: T[] = [];\n  const errors: Error[] = [];\n  let isAborted = false;\n\n  // Convert to an iterator (sync or async)\n  const iterable = (input as any)[Symbol.asyncIterator] \n    ? (input as AsyncIterable<T>)[Symbol.asyncIterator]()\n    : (input as Iterable<T>)[Symbol.iterator]();\n\n  const worker = async () => {\n    while (!isAborted) {\n      const { value, done } = await iterable.next();\n      \n      if (done || isAborted) break;\n      const item = value;\n\n      try {\n        const res = await iteratorFn(item);\n        if (!isAborted) results.push(res);\n      } catch (err) {\n        errors.push(err as Error);\n        failedItems.push(item);\n        if (errorHandler) {\n          const action = await errorHandler(err, item);\n          if (action === POOL_STOP_SIGNAL) isAborted = true;\n        }\n      }\n    }\n  };\n\n  // Lunch workers up to the concurrency limit\n  const workers = Array.from({ length: concurrency }, worker);\n  await Promise.all(workers);\n\n  return { results, errors, failedItems, stoppedPrematurely: isAborted };\n};\n"]}

package/dist/index.mjs

@@ -0,0 +1,2 @@
+var P=Symbol("POOL_STOP_SIGNAL"),p=async(t,i,l=2,s)=>{let a=[],n=[],c=[],r=false,y=t[Symbol.asyncIterator]?t[Symbol.asyncIterator]():t[Symbol.iterator](),m=Array.from({length:l},async()=>{for(;!r;){let{value:T,done:b}=await y.next();if(b||r)break;let o=T;try{let e=await i(o);r||a.push(e);}catch(e){c.push(e),n.push(o),s&&await s(e,o)===P&&(r=true);}}});return await Promise.all(m),{results:a,errors:c,failedItems:n,stoppedPrematurely:r}};export{P as POOL_STOP_SIGNAL,p as promisePool};//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["POOL_STOP_SIGNAL","promisePool","input","iteratorFn","concurrency","errorHandler","results","failedItems","errors","isAborted","iterable","workers","value","done","item","res","err"],"mappings":"AAAO,IAAMA,CAAAA,CAAmB,MAAA,CAAO,kBAAkB,CAAA,CAI5CC,CAAAA,CAAc,MACzBC,CAAAA,CACAC,CAAAA,CACAC,CAAAA,CAAc,CAAA,CACdC,CAAAA,GACG,CACH,IAAMC,CAAAA,CAAe,EAAC,CAChBC,CAAAA,CAAmB,EAAC,CACpBC,CAAAA,CAAkB,EAAC,CACrBC,CAAAA,CAAY,KAAA,CAGVC,CAAAA,CAAYR,CAAAA,CAAc,MAAA,CAAO,aAAa,CAAA,CAC/CA,EAA2B,MAAA,CAAO,aAAa,CAAA,EAAE,CACjDA,CAAAA,CAAsB,MAAA,CAAO,QAAQ,CAAA,EAAE,CAwBtCS,CAAAA,CAAU,KAAA,CAAM,IAAA,CAAK,CAAE,MAAA,CAAQP,CAAY,CAAA,CAtBlC,SAAY,CACzB,KAAO,CAACK,CAAAA,EAAW,CACjB,GAAM,CAAE,KAAA,CAAAG,CAAAA,CAAO,IAAA,CAAAC,CAAK,CAAA,CAAI,MAAMH,EAAS,IAAA,EAAK,CAE5C,GAAIG,CAAAA,EAAQJ,CAAAA,CAAW,MACvB,IAAMK,CAAAA,CAAOF,CAAAA,CAEb,GAAI,CACF,IAAMG,CAAAA,CAAM,MAAMZ,CAAAA,CAAWW,CAAI,CAAA,CAC5BL,CAAAA,EAAWH,CAAAA,CAAQ,IAAA,CAAKS,CAAG,EAClC,CAAA,MAASC,CAAAA,CAAK,CACZR,CAAAA,CAAO,IAAA,CAAKQ,CAAY,CAAA,CACxBT,CAAAA,CAAY,IAAA,CAAKO,CAAI,CAAA,CACjBT,CAAAA,EACa,MAAMA,CAAAA,CAAaW,CAAAA,CAAKF,CAAI,CAAA,GAC5Bd,CAAAA,GAAkBS,CAAAA,CAAY,IAAA,EAEjD,CACF,CACF,CAG0D,CAAA,CAC1D,OAAA,MAAM,OAAA,CAAQ,GAAA,CAAIE,CAAO,CAAA,CAElB,CAAE,OAAA,CAAAL,CAAAA,CAAS,MAAA,CAAAE,CAAAA,CAAQ,WAAA,CAAAD,CAAAA,CAAa,kBAAA,CAAoBE,CAAU,CACvE","file":"index.mjs","sourcesContent":["export const POOL_STOP_SIGNAL = Symbol('POOL_STOP_SIGNAL');\n\ntype ErrorHandler<T, E = any> = (error: E, item: T) => void | Promise<void> | typeof POOL_STOP_SIGNAL;\n\nexport const promisePool = async <T, R>(\n  input: Iterable<T> | AsyncIterable<T>,\n  iteratorFn: (input: T) => Promise<R>,\n  concurrency = 2,\n  errorHandler?: ErrorHandler<T>\n) => {\n  const results: R[] = [];\n  const failedItems: T[] = [];\n  const errors: Error[] = [];\n  let isAborted = false;\n\n  // Convert to an iterator (sync or async)\n  const iterable = (input as any)[Symbol.asyncIterator] \n    ? (input as AsyncIterable<T>)[Symbol.asyncIterator]()\n    : (input as Iterable<T>)[Symbol.iterator]();\n\n  const worker = async () => {\n    while (!isAborted) {\n      const { value, done } = await iterable.next();\n      \n      if (done || isAborted) break;\n      const item = value;\n\n      try {\n        const res = await iteratorFn(item);\n        if (!isAborted) results.push(res);\n      } catch (err) {\n        errors.push(err as Error);\n        failedItems.push(item);\n        if (errorHandler) {\n          const action = await errorHandler(err, item);\n          if (action === POOL_STOP_SIGNAL) isAborted = true;\n        }\n      }\n    }\n  };\n\n  // Lunch workers up to the concurrency limit\n  const workers = Array.from({ length: concurrency }, worker);\n  await Promise.all(workers);\n\n  return { results, errors, failedItems, stoppedPrematurely: isAborted };\n};\n"]}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@mystogab/promise-pool",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "node --test src/index.test.ts",
+    "lint": "tsc",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  },
+  "author": {
+    "name": "Gabriel Desimone",
+    "email": "gabriel.desimone@mail.com",
+    "url": "https://github.com/Mystogab"
+  },
+  "license": "MIT"
+}