@altano/tiny-async-pool 1.0.0

package/LICENSE-MIT

@@ -0,0 +1,23 @@
+Copyright (c) 2017 Rafael Xavier de Souza http://rafael.xavier.blog.br
+Copyright (c) 2022 Alan Norbauer https://alan.norbauer.com
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# tiny-async-pool
+
+## Why?
+
+The goal of this library is to use the native async iterator (ES9), native async functions, and native Promise to implement concurrent/batched work.
+
+## What?
+
+`doWorkAndYield` runs multiple promise-returning & async functions in a limited concurrency pool. It rejects immediately as soon as one of the promises rejects. It calls the iterator function as soon as possible (under concurrency limit). It returns an async iterator that yields as soon as a promise completes (under concurrency limit). For example:
+
+```js
+const timeout = (ms) =>
+  new Promise((resolve) => setTimeout(() => resolve(ms), ms));
+
+for await (const ms of doWorkAndYield(2, [1000, 5000, 3000, 2000], timeout)) {
+  console.log(ms);
+}
+// Call iterator timeout(1000)
+// Call iterator timeout(5000)
+// Concurrency limit of 2 reached, wait for the quicker one to complete...
+// 1000 finishes
+// for await...of outputs "1000"
+// Call iterator timeout(3000)
+// Concurrency limit of 2 reached, wait for the quicker one to complete...
+// 3000 finishes
+// for await...of outputs "3000"
+// Call iterator timeout(2000)
+// Itaration is complete, wait until running ones complete...
+// 5000 finishes
+// for await...of outputs "5000"
+// 2000 finishes
+// for await...of outputs "2000"
+```
+
+## Usage
+
+```
+$ npm install @altano/tiny-async-pool
+```
+
+```js
+import { doWorkAndYield } from "@altano/tiny-async-pool";
+```
+
+### ES9 for await...of
+
+```js
+for await (const value of doWorkAndYield(concurrency, iterable, iteratorFn)) {
+  console.log(value);
+}
+```
+
+## API
+
+### `doWorkAndYield(concurrency, iterable, iteratorFn)`
+
+Runs multiple promise-returning & async functions in a limited concurrency pool. It rejects immediately as soon as one of the promises rejects. It calls the iterator function as soon as possible (under concurrency limit). It returns an async iterator that yields as soon as a promise completes (under concurrency limit).
+
+#### concurrency
+
+The concurrency limit number (>= 1).
+
+#### iterable
+
+An input [iterable object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), such as [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String), [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array), [`TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), and [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).
+
+#### iteratorFn
+
+Iterator function that takes two arguments: the value of each iteration and the iterable object itself. The iterator function should either return a promise or be an async function.
+
+### `doWork(concurrency, iterable, iteratorFn)`
+
+The same as `doWorkAndYield(...)` but just returns a Promise that resolves when all work resolves/rejects, e.g.:
+
+```js
+const timeout = (ms) =>
+  new Promise((resolve) => setTimeout(() => resolve(ms), ms));
+
+await doWork(2, [1000, 5000, 3000, 2000], timeout);
+```
+
+## License
+
+This project is a fork of `async-pool` by Rafael Xavier de Souza. It modernizes (as of 2022) the library by being a first-class TypeScript and ESM module.
+
+MIT © [Rafael Xavier de Souza](http://rafael.xavier.blog.br)
+MIT © [Alan Norbauer](https://alan.norbauer.com)

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+declare type IterableItem<T> = T extends Iterable<infer R> ? R : never;
+/**
+ * Process items from `iterable` in batches and yield the result of each call to
+ * `iteratorFn`
+ */
+declare function doWorkAndYield<TIn, TOut, TIterable extends Iterable<TIn>>(
+/**
+ * The size of the batch of work, or, how many times `iteratorFn` will be
+ * called in parallel.
+ */
+concurrentCount: number, 
+/**
+ * An iterable that contains the items that should be passed to `iteratorFn`.
+ */
+iterable: TIterable, 
+/**
+ * The async callback function that does the work. Will be passed items from
+ * `iterable`.
+ */
+iteratorFn: (item: IterableItem<TIterable>, Iterable: TIterable) => Promise<TOut>): AsyncGenerator<Awaited<TOut>, void, unknown>;
+
+/**
+ * Process items from `iterable` in batches.
+ */
+declare function doWork<TIn, TOut, TIterable extends Iterable<TIn>>(...args: Parameters<typeof doWorkAndYield<TIn, TOut, TIterable>>): Promise<void>;
+
+export { doWork, doWorkAndYield };

package/dist/index.js

@@ -0,0 +1,33 @@
+// src/doWorkAndYield.ts
+async function* doWorkAndYield(concurrentCount, iterable, iteratorFn) {
+  const executing = /* @__PURE__ */ new Set();
+  async function consume() {
+    const [promise, value] = await Promise.race(executing);
+    executing.delete(promise);
+    return value;
+  }
+  for (const item of iterable) {
+    const result = iteratorFn(item, iterable);
+    const promise = result.then((value) => [
+      promise,
+      value
+    ]);
+    executing.add(promise);
+    if (executing.size >= concurrentCount) {
+      yield await consume();
+    }
+  }
+  while (executing.size) {
+    yield await consume();
+  }
+}
+
+// src/doWork.ts
+async function doWork(...args) {
+  for await (const _result of doWorkAndYield(...args)) {
+  }
+}
+export {
+  doWork,
+  doWorkAndYield
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@altano/tiny-async-pool",
+  "version": "1.0.0",
+  "description": "Run multiple promise-returning & async functions with limited concurrency using native ES9",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "LICENSE-MIT",
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --watch --format esm --dts",
+    "format": "prettier --write src",
+    "lint": "TIMING=1 eslint src/**/*.ts* --fix",
+    "clean": "rm -rf .turbo && rm -rf .tsbuildinfo && rm -rf node_modules && rm -rf dist",
+    "test": "vitest --run",
+    "test:watch": "vitest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:altano/async-pool.git"
+  },
+  "keywords": [
+    "race",
+    "concurrency",
+    "promise",
+    "async",
+    "async iterator",
+    "async iteration",
+    "async generator",
+    "es9"
+  ],
+  "author": {
+    "name": "Alan Norbauer",
+    "email": "altano@gmail.com",
+    "url": "https://alan.norbauer.com"
+  },
+  "contributors": [
+    "Rafael Xavier de Souza"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@altano/tsconfig": "*",
+    "@types/node": "^18.6.4",
+    "@types/prettier": "^2.7.0",
+    "@typescript-eslint/eslint-plugin": "^5.36.1",
+    "@typescript-eslint/parser": "^5.36.1",
+    "@vitest/ui": "^0.21.0",
+    "chai-as-promised": "^7.1.1",
+    "chai": "^4.3.6",
+    "eslint-config-altano": "*",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-prettier": "^4.2.1",
+    "eslint": "^8.23.0",
+    "mocha": "^10.0.0",
+    "prettier": "^2.7.1",
+    "tsup": "^6.2.3",
+    "typescript": "^4.8.2",
+    "vitest": "^0.21.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}