poolctl 0.1.0 → 0.1.1

package/README.md

@@ -1,28 +1,293 @@
-a simple task queue for javascript which ensures maximum concurrent tasks are
-less than the pool size it is mostly useful for requesting thousands of
-resources concurrently but avoid and keep maximum connections behind a boundary
-example :
+# poolctl
 
-### example
+> A tiny, dependency-free concurrency pool for JavaScript and TypeScript.
+> Run at most _N_ async tasks at once — call `pool.exec(task)` from anywhere, anytime.
+
+[![npm version](https://img.shields.io/npm/v/poolctl)](https://www.npmjs.com/package/poolctl)
+[![license](https://img.shields.io/npm/l/poolctl)](./LICENSE)
+
+Most concurrency helpers want your work bundled into an array or an iterator up
+front. `poolctl` doesn't. You create one pool with a hard limit and call
+`exec(task)` wherever the work happens to originate — now, later, or from ten
+different files. Everything that goes through the same pool shares one budget.
+
+## Table of contents
+
+- [Why poolctl?](#why-poolctl)
+- [Install](#install)
+- [Examples](#examples)
+  - [Quick start](#quick-start)
+  - [One pool, many sources](#one-pool-many-sources)
+  - [Tasks that arrive over time](#tasks-that-arrive-over-time)
+  - [Errors are just rejections](#errors-are-just-rejections)
+  - [Watching the pool](#watching-the-pool)
+- [API](#api)
+- [How it compares](#how-it-compares)
+- [When to use something else](#when-to-reach-for-something-else)
+- [How it works](#how-it-works)
+- [License](#license)
+
+## Why poolctl?
+
+- **Ad-hoc, not array-bound.** You don't collect tasks into an array or wire up
+  an iterator. Just `await pool.exec(() => doWork())` at the call site — even
+  for tasks that arrive over time (requests, events, streams, a message loop)
+  where you don't know the full set of work ahead of time.
+- **One pool, many sources, one limit.** A single `Pool` instance enforces one
+  global concurrency budget. Import it anywhere; every caller — wherever it
+  lives — draws from the same limit. No coordination, no manual counting.
+- **It's just `await`.** `exec` returns the task's resolved value, and a thrown
+  error propagates to the `await`er. Composes with plain `try/catch` and
+  `Promise.all` — no events to subscribe to, no result arrays to drain.
+- **Error-safe by construction.** A task's slot is released in a `finally`
+  block, so a thrown error can never leak a slot or stall the pool.
+- **Live introspection.** `getSize()`, `getWorkingCount()`, and
+  `getPendingCount()` tell you exactly how full the pool is — handy for
+  backpressure decisions and monitoring.
+- **Fair FIFO ordering.** When the pool is full, waiters are released in the
+  order they arrived — predictable, starvation-free scheduling.
+- **Tiny and dependency-free.** Roughly 60 lines of source, **0 runtime
+  dependencies**, ~3 kB published. Easy to read in full, easy to audit.
+- **Runs everywhere.** Pure Promise logic with no platform APIs, so it works in
+  Deno, Node, browsers, and workers. Ships full TypeScript types and supports
+  both **ESM and CommonJS** consumers.
+
+## Install
+
+```bash
+npm install poolctl
+```
+
+```ts
+import { Pool } from "poolctl";
+```
+
+**Deno:**
+
+```ts
+import { Pool } from "https://raw.githubusercontent.com/dev-a-loper/task-pool/main/mod.ts";
+```
+
+## Examples
+
+### Quick start
+
+Cap concurrent requests without collecting them by hand:
+
+```ts
+import { Pool } from "poolctl";
+
+const pool = new Pool(5); // at most 5 tasks run at once
 
-```typescript
-const pool = new Pool(5);
 const urls = [
-  "https://www.google.com/1",
-  "https://www.google.com/2",
-  "https://www.google.com/3",
-  "https://www.google.com/4",
-  "https://www.google.com/5",
-  "https://www.google.com/6",
-  "https://www.google.com/7",
+  "https://example.com/1",
+  "https://example.com/2",
+  "https://example.com/3",
+  // ...thousands more
 ];
-// here maximum concurrent url being fetched is 5
-await Promise.all(urls.map((u) => pool.exec(() => fetch(u))));
+
+// Never more than 5 requests in flight, no matter how long `urls` is.
+await Promise.all(urls.map((url) => pool.exec(() => fetch(url))));
+```
+
+> Pass a **function** (`() => fetch(url)`), not the promise. `poolctl` invokes
+> the function only once a slot is free — that's what keeps concurrency bounded.
+
+### One pool, many sources
+
+Different parts of your code, even different modules, can funnel through one
+limit. A single import gives you an app-wide budget:
+
+```ts
+// dbPool.ts — one budget for database calls, process-wide
+import { Pool } from "poolctl";
+export const dbPool = new Pool(10);
+```
+
+```ts
+// anywhere in your app — both calls count against the same limit of 10
+import { dbPool } from "./dbPool";
+
+await dbPool.exec(() => query("SELECT ..."));
+await dbPool.exec(() => query("INSERT ..."));
+```
+
+You get a global "no more than 10 DB operations at once" guarantee across the
+entire process, with no shared state to wire up.
+
+### Tasks that arrive over time
+
+This is where `poolctl` pulls away from iterable-based tools like Deno's
+`pooledMap` or `p-map`. When work shows up as **events or requests** — not a
+known array — you still get a hard concurrency limit:
+
+```ts
+import { Pool } from "poolctl";
+
+// At most 5 expensive operations run at once across ALL incoming requests,
+// even under heavy concurrent traffic. Extra requests simply queue.
+const pool = new Pool(5);
+
+server.on("request", async (req, res) => {
+  try {
+    const data = await pool.exec(() => expensiveWork(req));
+    res.send(data);
+  } catch (err) {
+    res.status(500).send(String(err));
+  }
+});
+```
+
+There's no "add everything to an array first" step — each request schedules
+itself as it arrives, and the pool does the rest.
+
+### Errors are just rejections
+
+A throwing task rejects the `exec` promise like any normal async call, and its
+slot is **always** released — so one failure can't clog the pool:
+
+```ts
+import { Pool } from "poolctl";
+
+const pool = new Pool(2);
+
+try {
+  await pool.exec(async () => {
+    throw new Error("boom");
+  });
+} catch (err) {
+  console.error(err); // Error: boom
+}
+
+// The slot was freed despite the throw — the pool is still fully usable.
+console.log(pool.getWorkingCount()); // 0
+console.log(pool.getPendingCount()); // 0
+```
+
+Mix it with `Promise.allSettled` to run a batch and collect every outcome,
+successful or not:
+
+```ts
+const results = await Promise.allSettled(
+  items.map((item) => pool.exec(() => process(item))),
+);
+
+const ok = results.filter((r) => r.status === "fulfilled");
+const failed = results.filter((r) => r.status === "rejected");
+```
+
+### Watching the pool
+
+The live counters make backpressure and progress monitoring trivial:
+
+```ts
+import { Pool } from "poolctl";
+
+const pool = new Pool(8);
+const items = Array.from({ length: 500 }, (_, i) => i);
+
+const tick = setInterval(() => {
+  console.log(
+    `running ${pool.getWorkingCount()}/${pool.getSize()} · queued ${pool.getPendingCount()}`,
+  );
+}, 100);
+
+await Promise.all(items.map((i) => pool.exec(() => fetch(`https://example.com/${i}`))));
+
+clearInterval(tick);
+console.log("done");
+```
+
+## API
+
+### `new Pool(size)`
+
+Create a pool that runs at most `size` tasks concurrently.
+
+- **`size: number`** — maximum concurrent tasks. Throws if `< 1`.
+
+### `pool.exec(task)`
+
+Run a task within the pool's limit. If the pool is full, the call waits (FIFO)
+until a slot frees up.
+
+- **`task: () => Promise<T>`** — a function returning the work to do.
+- **Returns** `Promise<T>` — resolves with the task's result, or rejects with
+  its error. The slot is released in a `finally` block, so it's always freed —
+  even when the task throws.
+
+In TypeScript, the return type is inferred from the task, so results stay
+typed end-to-end:
+
+```ts
+const id = await pool.exec(async () => 42);    // number
+const name = await pool.exec(async () => "x"); // string
 ```
 
-### Api Docs
+### `pool.getSize()`
+
+The configured maximum concurrency (`size`).
+
+### `pool.getWorkingCount()`
+
+How many tasks are running right now.
+
+### `pool.getPendingCount()`
+
+How many tasks are queued, waiting for a slot.
+
+Full generated type docs: https://doc.deno.land/https://raw.githubusercontent.com/dev-a-loper/task-pool/main/mod.ts
+
+## How it compares
+
+| Capability | **poolctl** | Deno `pooledMap` | `p-limit` | `p-queue` |
+|---|:---:|:---:|:---:|:---:|
+| Usage style | ad-hoc `pool.exec(fn)` | one-shot map over an iterable | `limit(fn)` wrapper | ad-hoc `queue.add(fn)` |
+| Call from anywhere; tasks arrive over time | ✅ | ❌ needs all inputs up front | ✅ | ✅ |
+| One shared budget across many sources | ✅ | ➖ per single call | ✅ | ✅ |
+| Get each result via `await` | ✅ | async iterable (input order) | ✅ | ✅ |
+| Live working / pending counts | ✅ | ❌ | ✅ | ✅ |
+| Priority · timeout · pause · rate-limit · events | ❌ | ❌ | ❌ | ✅ |
+| Runtime dependencies | 0 | 0 (std) | 0 | `EventEmitter3` |
+| ESM **and** CommonJS | ✅ | ESM | ESM only | ESM only |
+| First-class Deno | ✅ | ✅ | via `npm:` | via `npm:` |
+| Footprint | ~3 kB | bundled with Deno | ~2 kB | larger |
+
+A few honest notes:
+
+- **`pooledMap` and `p-map`** are excellent when you have a **known collection**
+  to transform with bounded concurrency and want results in order. They're not
+  designed to be a long-lived pool you call into from arbitrary places over
+  time — that's `poolctl`'s job.
+- **`p-limit`** is the closest in spirit to `poolctl`: ad-hoc, shared budget,
+  with introspection. Pick `poolctl` if you prefer a class-based API, want dual
+  ESM/CommonJS output, or want a Deno-first origin. They're peers, not rivals.
+- **`p-queue`** is far more capable — priority, per-task timeout, pause/resume,
+  rate limiting, events. It's also larger, ESM-only, and has a dependency.
+
+## When to reach for something else
+
+`poolctl` is intentionally minimal. Use a different tool if you need:
+
+- **Priority ordering** or a **custom queue** → `p-queue`
+- **Per-task timeouts**, **pause/resume**, or **rate limiting** (N per second) → `p-queue`
+- **Events** or **AbortSignal-based cancellation** → `p-queue`
+- A bounded **map over a known array/iterable** → Deno `pooledMap` or `p-map`
+
+If "at most _N_ at once, from anywhere, with zero fuss" is all you need — that's
+`poolctl`.
+
+## How it works
+
+`poolctl` keeps a running count of in-flight tasks and a FIFO queue of waiters
+(a hand-rolled linked list, so `enqueue`/`dequeue` are O(1)). When `exec` is
+called on a full pool, it creates a deferred promise, parks it at the back of
+the queue, and awaits it. When a running task finishes, the waiter at the front
+of the queue is resolved and starts running. Because the slot is released in a
+`finally` block, it's always freed — even if the task throws.
+
+The whole thing is ~60 lines; the source is the best documentation.
 
-https://doc.deno.land/https://raw.githubusercontent.com/ehsan2003/task-pool/main/mod.ts
+## License
 
-the code is simple so if you confused about anything read the code its most of
-the time best way to understand things or just open an issue
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poolctl",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A simple concurrency-limiting task pool for JavaScript. Runs at most N async tasks at a time.",
   "repository": {
     "type": "git",