@dmop/puru 0.1.1 → 0.1.3

package/README.md

@@ -1,8 +1,8 @@
 # puru (プール)
 
-Goroutine-style concurrency for JavaScript with an **M:N scheduler** — multiplexes thousands of tasks onto a small pool of OS threads, just like Go.
+A thread pool with Go-style concurrency primitives for JavaScript — spawn tasks off the main thread with channels, WaitGroup, select, and more. No worker files, no boilerplate.
 
-Works on **Node.js** and **Bun**. No separate worker files, no manual message passing.
+Works on **Node.js** and **Bun**. Deno support coming soon.
 
 *puru (プール) means "pool" in Japanese.*
 
@@ -10,6 +10,8 @@ Works on **Node.js** and **Bun**. No separate worker files, no manual message pa
 
 ```bash
 npm install @dmop/puru
+# or
+bun add @dmop/puru
 ```
 
 ## Quick Start
@@ -21,7 +23,7 @@ import { spawn, chan, WaitGroup, select, after } from '@dmop/puru'
 const { result } = spawn(() => fibonacci(40))
 console.log(await result)
 
-// I/O work — many tasks share worker threads (M:N scheduling)
+// I/O work — many tasks share worker threads
 const wg = new WaitGroup()
 for (const url of urls) {
   wg.spawn(() => fetch(url).then(r => r.json()), { concurrent: true })
@@ -31,10 +33,10 @@ const results = await wg.wait()
 
 ## How It Works
 
-puru uses an **M:N scheduler** — M tasks are multiplexed onto N OS threads:
+puru manages a **thread pool** — tasks are dispatched onto a fixed set of worker threads:
 
 ```text
-              puru scheduler
+              puru thread pool
     ┌──────────────────────────────┐
     │                              │
     │   Task 1 ─┐                  │
@@ -58,7 +60,7 @@ puru uses an **M:N scheduler** — M tasks are multiplexed onto N OS threads:
 | **Exclusive** (default) | `spawn(fn)` | CPU-bound work | 1 task per thread, full core usage |
 | **Concurrent** | `spawn(fn, { concurrent: true })` | I/O-bound / async work | Many tasks share a thread's event loop |
 
-This is the same model Go uses: goroutines (M) are scheduled onto OS threads (N). CPU-bound work gets a dedicated thread. I/O-bound work shares threads efficiently.
+CPU-bound work gets a dedicated thread. I/O-bound work shares threads efficiently. The API is inspired by Go's concurrency primitives (channels, WaitGroup, select), but the underlying mechanism is a thread pool — not a green thread scheduler.
 
 ## Why puru
 
@@ -122,7 +124,7 @@ const results = await wg.wait()
 | --- | --- | --- | --- | --- |
 | Separate worker file | Required | Required | Required | **Not needed** |
 | Inline functions | No | No | No | **Yes** |
-| M:N scheduler | No | No | No | **Yes** |
+| Managed thread pool | No | No | No | **Yes** |
 | Concurrent mode (I/O) | No | No | No | **Yes** |
 | Channels (cross-thread) | No | No | No | **Yes** |
 | Cancellation | No | No | No | **Yes** |
@@ -188,7 +190,7 @@ for await (const value of ch) {
 }
 ```
 
-**Channels in workers** — pass channels to `spawn()` and use them from worker threads, just like Go:
+**Channels in workers** — pass channels to `spawn()` and use them across worker threads:
 
 ```typescript
 const ch = chan<number>(10)
@@ -356,7 +358,7 @@ npm run bench          # all benchmarks (Node.js)
 npm run bench:bun      # all benchmarks (Bun)
 ```
 
-### CPU-Bound Parallelism (Node.js)
+### CPU-Bound Parallelism
 
 | Benchmark | Without puru | With puru | Speedup |
 | --- | --: | --: | --: |
@@ -365,7 +367,19 @@ npm run bench:bun      # all benchmarks (Bun)
 | Matrix multiply (200x200 x8) | 140 ms | 39 ms | **3.6x** |
 | Data processing (100K items x8) | 221 ms | 67 ms | **3.3x** |
 
-### Channels Fan-Out Pipeline (Node.js)
+<details>
+<summary>Bun results</summary>
+
+| Benchmark | Without puru | With puru | Speedup |
+| --- | --: | --: | --: |
+| Fibonacci (fib(38) x8) | 2,208 ms | 380 ms | **5.8x** |
+| Prime counting (2M range) | 201 ms | 50 ms | **4.0x** |
+| Matrix multiply (200x200 x8) | 197 ms | 57 ms | **3.5x** |
+| Data processing (100K items x8) | 214 ms | 109 ms | **2.0x** |
+
+</details>
+
+### Channels Fan-Out Pipeline
 
 200 items with CPU-heavy transform, 4 parallel transform workers:
 
@@ -375,7 +389,18 @@ npm run bench:bun      # all benchmarks (Bun)
 | Main-thread channels only | 174 ms | 1.0x |
 | **puru fan-out (4 workers)** | **51 ms** | **3.4x faster** |
 
-### M:N Concurrent Async (Node.js)
+<details>
+<summary>Bun results</summary>
+
+| Approach | Time | vs Sequential |
+| --- | --: | --: |
+| Sequential (no channels) | 59 ms | baseline |
+| Main-thread channels only | 60 ms | 1.0x |
+| **puru fan-out (4 workers)** | **22 ms** | **2.7x faster** |
+
+</details>
+
+### Concurrent Async
 
 100 async tasks with simulated I/O + CPU:
 
@@ -383,7 +408,18 @@ npm run bench:bun      # all benchmarks (Bun)
 | --- | --: | --: |
 | Sequential | 1,140 ms | baseline |
 | Promise.all (main thread) | 20 ms | 58x faster |
-| **puru concurrent (M:N)** | **16 ms** | **73x faster** |
+| **puru concurrent** | **16 ms** | **73x faster** |
+
+<details>
+<summary>Bun results</summary>
+
+| Approach | Time | vs Sequential |
+| --- | --: | --: |
+| Sequential | 1,110 ms | baseline |
+| Promise.all (main thread) | 16 ms | 68x faster |
+| **puru concurrent** | **13 ms** | **87x faster** |
+
+</details>
 
 Both Promise.all and puru concurrent are fast — but puru runs everything **off the main thread**, keeping your server responsive under load.
 
@@ -395,6 +431,7 @@ Both Promise.all and puru concurrent are fast — but puru runs everything **off
 | --- | --- | --- |
 | Node.js >= 18 | Full | `worker_threads` |
 | Bun | Full | Web Workers (file-based) |
+| Deno | Planned | — |
 | Cloudflare Workers | Error | No thread support |
 | Vercel Edge | Error | No thread support |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dmop/puru",
-  "version": "0.1.1",
-  "description": "puru (プール) — Goroutine-style concurrency for JavaScript",
+  "version": "0.1.3",
+  "description": "puru (プール) — A thread pool with Go-style concurrency primitives for JavaScript",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",