@dmop/puru 0.1.10 → 0.1.11

package/AGENTS.md

@@ -1,6 +1,6 @@
 # puru — Guide for AI Assistants
 
-puru is a thread pool library for JavaScript with Go-style concurrency primitives (channels, WaitGroup, select). It runs functions off the main thread with no worker files and no boilerplate.
+puru is a thread pool library for JavaScript with Go-style concurrency primitives (channels, WaitGroup, ErrGroup, select, context, Mutex, RWMutex, Cond, Timer). It runs functions off the main thread with no worker files and no boilerplate.
 
 Full API reference: https://raw.githubusercontent.com/dmop/puru/main/llms-full.txt
 
@@ -120,6 +120,141 @@ eg.spawn(() => fetch('https://api.example.com/users/1/orders').then((r) => r.jso
 const [user, orders] = await eg.wait() // throws on first error, cancels the rest
 ```
 
+### ErrGroup with concurrency limit
+
+```typescript
+import { ErrGroup } from '@dmop/puru'
+
+const eg = new ErrGroup()
+eg.setLimit(4) // max 4 tasks in flight at once
+
+for (const url of urls) {
+  eg.spawn(() => fetch(url).then(r => r.json()), { concurrent: true })
+}
+
+const results = await eg.wait()
+```
+
+### Context-integrated spawn (auto-cancel)
+
+```typescript
+import { spawn, background, withTimeout } from '@dmop/puru'
+
+// Task auto-cancels when context expires — no manual wiring needed
+const [ctx, cancel] = withTimeout(background(), 5000)
+const { result } = spawn(() => heavyWork(), { ctx })
+
+try {
+  console.log(await result)
+} finally {
+  cancel()
+}
+```
+
+### Context with WaitGroup / ErrGroup
+
+```typescript
+import { background, withTimeout, WaitGroup } from '@dmop/puru'
+
+const [ctx, cancel] = withTimeout(background(), 5000)
+
+// Pass context to WaitGroup — all tasks auto-cancel when ctx expires
+const wg = new WaitGroup(ctx)
+wg.spawn(() => { /* CPU work */ return 42 })
+wg.spawn(() => fetch('https://api.example.com/data').then(r => r.json()), { concurrent: true })
+
+try {
+  const results = await wg.wait()
+} catch {
+  console.log('timed out or cancelled')
+} finally {
+  cancel()
+}
+```
+
+### RWMutex (read-write lock)
+
+```typescript
+import { RWMutex } from '@dmop/puru'
+
+const rw = new RWMutex()
+
+// Many readers can run concurrently
+const data = await rw.withRLock(() => cache.get('config'))
+
+// Writers get exclusive access
+await rw.withLock(() => cache.set('config', newValue))
+```
+
+### Timer (resettable one-shot)
+
+```typescript
+import { Timer, select } from '@dmop/puru'
+
+const t = new Timer(5000)
+
+// Use with select for cancellable timeouts
+await select([
+  [ch.recv(), (v) => { t.stop(); handle(v) }],
+  [t.channel, () => console.log('timed out')],
+])
+
+// Reset for debounce patterns
+t.reset(300)
+```
+
+### Cond (condition variable)
+
+```typescript
+import { Mutex, Cond } from '@dmop/puru'
+
+const mu = new Mutex()
+const cond = new Cond(mu)
+let ready = false
+
+// Waiter
+await mu.lock()
+while (!ready) await cond.wait()
+mu.unlock()
+
+// Signaler
+await mu.lock()
+ready = true
+cond.broadcast() // wake all waiters
+mu.unlock()
+```
+
+### Directional channels
+
+```typescript
+import { chan } from '@dmop/puru'
+import type { SendOnly, RecvOnly } from '@dmop/puru'
+
+const ch = chan<number>(10)
+
+function producer(out: SendOnly<number>) {
+  await out.send(42)
+  out.close()
+}
+
+function consumer(inp: RecvOnly<number>) {
+  for await (const v of inp) console.log(v)
+}
+
+producer(ch.sendOnly())
+consumer(ch.recvOnly())
+```
+
+### Channel inspection
+
+```typescript
+const ch = chan<number>(100)
+await ch.send(1)
+await ch.send(2)
+console.log(ch.len) // 2 (buffered values)
+console.log(ch.cap) // 100 (buffer capacity)
+```
+
 ### Cross-thread channels (fan-out)
 
 ```typescript

package/README.md

@@ -1,44 +1,55 @@
 # puru (プール)
 
-> A thread pool for JavaScript with Go-style concurrency primitives.
->
-> Run work off the main thread with inline functions, channels, `WaitGroup`, `ErrGroup`, `select`, `Mutex`, `Once`, and more. No worker files. No boilerplate.
+[![npm version](https://img.shields.io/npm/v/@dmop/puru)](https://www.npmjs.com/package/@dmop/puru)
+[![npm downloads](https://img.shields.io/npm/dm/@dmop/puru)](https://www.npmjs.com/package/@dmop/puru)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@dmop/puru)](https://bundlephobia.com/package/@dmop/puru)
+[![license](https://img.shields.io/npm/l/@dmop/puru)](LICENSE)
 
-`puru` is for the moment when `Promise.all()` is no longer enough, but raw `worker_threads` feels too low-level.
+**Go-style concurrency for JavaScript.** Worker threads with channels, WaitGroup, select, and context — no worker files, no boilerplate.
 
-- CPU-heavy work: use dedicated worker threads
-- Async / I/O-heavy work: share worker threads efficiently with `concurrent: true`
-- Coordination: use channels, `WaitGroup`, `ErrGroup`, `select`, `Mutex`, `Once`, and `ticker`
-- Ergonomics: write worker logic inline or define reusable typed tasks
-
-Works on **Node.js >= 20** and **Bun**.
+```ts
+import { spawn } from '@dmop/puru'
 
-## Why This Exists
+const { result } = spawn(() => {
+  let sum = 0
+  for (let i = 0; i < 100_000_000; i++) sum += i
+  return sum
+})
 
-JavaScript apps usually hit one of these walls:
+console.log(await result) // runs off the main thread
+```
 
-- A request handler does 200ms of CPU work and stalls the event loop
-- You want worker threads, but you do not want separate worker files and message plumbing
-- You need more than raw parallelism: cancellation, fan-out, backpressure, coordination
-- You like Go's concurrency model and want something similar in JavaScript
+## Before / After
 
-`puru` gives you a managed worker pool with a much nicer programming model.
+<table>
+<tr><th>Raw worker_threads</th><th>puru</th></tr>
+<tr>
+<td>
 
-## Install
+```ts
+const { Worker } = require('worker_threads')
+const worker = new Worker('./worker.js')
+worker.postMessage({ n: 40 })
+worker.on('message', (result) => {
+  console.log(result)
+  worker.terminate()
+})
+worker.on('error', reject)
 
-```bash
-npm install @dmop/puru
-# or
-bun add @dmop/puru
+// worker.js (separate file)
+const { parentPort } = require('worker_threads')
+parentPort.on('message', ({ n }) => {
+  parentPort.postMessage(fibonacci(n))
+})
 ```
 
-## 30-Second Tour
+</td>
+<td>
 
 ```ts
-import { spawn, task, WaitGroup, chan } from '@dmop/puru'
+import { spawn } from '@dmop/puru'
 
-// 1. One CPU-heavy task on a dedicated worker
-const { result: fib } = spawn(() => {
+const { result } = spawn(() => {
   function fibonacci(n: number): number {
     if (n <= 1) return n
     return fibonacci(n - 1) + fibonacci(n - 2)
@@ -46,162 +57,126 @@ const { result: fib } = spawn(() => {
   return fibonacci(40)
 })
 
-// 2. Reusable typed worker function
-const resize = task((width: number, height: number) => {
-  return { width, height, pixels: width * height }
-})
-
-// 3. Structured concurrency
-const wg = new WaitGroup()
-wg.spawn(() => {
-  let sum = 0
-  for (let i = 0; i < 1_000_000; i++) sum += i
-  return sum
-})
-wg.spawn(
-  () => fetch('https://api.example.com/users/1').then((r) => r.json()),
-  { concurrent: true },
-)
-
-// 4. Channels for coordination
-const jobs = chan<number>(10)
-spawn(async ({ jobs }) => {
-  for (let i = 0; i < 10; i++) await jobs.send(i)
-  jobs.close()
-}, { channels: { jobs }, concurrent: true })
-
-console.log(await fib)
-console.log(await resize(800, 600))
-console.log(await wg.wait())
+console.log(await result)
 ```
 
-## The Big Rule
-
-Functions passed to `spawn()` are serialized with `.toString()` and executed in a worker.
+</td>
+</tr>
+</table>
 
-That means they **cannot capture variables from the enclosing scope**.
+One file. No message plumbing. Automatic pooling.
 
-```ts
-const x = 42
-
-spawn(() => x + 1) // ReferenceError at runtime
+## Install
 
-spawn(() => {
-  const x = 42
-  return x + 1
-}) // works
+```bash
+npm install @dmop/puru
 ```
 
-If you need to pass arguments repeatedly, prefer `task(fn)`.
-
-## Why People Reach for puru
-
-### Inline worker code
-
-No separate worker file in the normal case.
+## Quick Start
 
 ```ts
-import { spawn } from '@dmop/puru'
+import { spawn, WaitGroup, chan } from '@dmop/puru'
 
-const { result } = spawn(() => {
-  let sum = 0
-  for (let i = 0; i < 10_000_000; i++) sum += i
-  return sum
-})
-```
+// CPU work on a dedicated worker
+const { result } = spawn(() => fibonacci(40))
 
-### Two execution modes
+// Parallel batch — wait for all
+const wg = new WaitGroup()
+wg.spawn(() => crunchData())
+wg.spawn(() => crunchMoreData())
+const [a, b] = await wg.wait()
+
+// Cross-thread channels
+const ch = chan<number>(10)
+spawn(async ({ ch }) => {
+  for (let i = 0; i < 10; i++) await ch.send(i)
+  ch.close()
+}, { channels: { ch } })
+
+for await (const item of ch) console.log(item)
+```
 
-| Mode | Use it for | What happens |
-| --- | --- | --- |
-| `spawn(fn)` | CPU-bound work | The task gets a dedicated worker |
-| `spawn(fn, { concurrent: true })` | Async / I/O-heavy work | Multiple tasks share a worker's event loop |
+## Performance
 
-This is the key distinction:
+Measured on Apple M1 Pro (8 cores). Full results in [BENCHMARKS.md](docs/BENCHMARKS.md).
 
-- `exclusive` mode is for actual CPU parallelism
-- `concurrent` mode is for lots of tasks that mostly `await`
+| Benchmark | Single-threaded | puru | Speedup |
+| --- | --: | --: | --: |
+| Fibonacci (fib(38) x8) | 4,345 ms | 2,131 ms | **2.0x** |
+| Prime counting (2M range) | 335 ms | 77 ms | **4.4x** |
+| 100 concurrent async tasks | 1,140 ms | 16 ms | **73x** |
+| Fan-out pipeline (4 workers) | 176 ms | 51 ms | **3.4x** |
 
-### More than a worker pool
+Spawn overhead: ~0.1-0.5ms. Use for tasks above ~5ms.
 
-`puru` is not just `spawn()`.
+## Two Modes
 
-- `chan()` for cross-thread coordination and backpressure
-- `WaitGroup` for “run many, wait for all”
-- `ErrGroup` for “fail fast, cancel the rest”
-- `select()` for first-ready coordination
-- `Mutex` for shared resource protection
-- `Once` for one-time initialization under concurrency
-- `task()` for reusable typed worker functions
+| Mode | Use it for | What happens |
+| --- | --- | --- |
+| `spawn(fn)` | CPU-bound work | Dedicated worker thread |
+| `spawn(fn, { concurrent: true })` | Async / I/O work | Shares a worker's event loop |
 
 ## When To Use What
 
-| Situation | Best tool |
+| Situation | Tool |
 | --- | --- |
-| One heavy synchronous task | `spawn(fn)` |
-| Same worker logic called many times with different inputs | `task(fn)` |
-| Many async tasks that mostly wait on I/O | `spawn(fn, { concurrent: true })` |
-| Parallel batch with “wait for everything” | `WaitGroup` |
-| Parallel batch where the first failure should cancel the rest | `ErrGroup` |
-| Producer/consumer or fan-out/fan-in pipeline | `chan()` |
-| Non-blocking coordination between async operations | `select()` |
+| One heavy CPU task | `spawn(fn)` |
+| Same logic, many inputs | `task(fn)` |
+| Wait for all tasks | `WaitGroup` |
+| Fail-fast, cancel the rest | `ErrGroup` (with `setLimit()` for throttling) |
+| Timeouts and cancellation | `context` + `spawn(fn, { ctx })` |
+| Producer/consumer pipelines | `chan()` + `select()` |
 
-## Why Not Just Use...
+## The Big Rule
 
-### `Promise.all()`
+> **Functions passed to `spawn()` cannot capture outer variables.** They are serialized as text and sent to a worker — closures don't survive.
 
-Use `Promise.all()` when work is already cheap and async.
+```ts
+const x = 42
+spawn(() => x + 1)          // ReferenceError at runtime
 
-Use `puru` when:
+spawn(() => {
+  const x = 42               // define inside
+  return x + 1
+})                            // works
+```
 
-- work is CPU-heavy
-- you need the main thread to stay responsive under load
-- you want worker coordination primitives, not just promise aggregation
+Use `task(fn)` to pass arguments to reusable worker functions.
 
-### `worker_threads`
+## What's Included
 
-Raw `worker_threads` are powerful, but they are low-level:
+**Coordination:** `chan()` &middot; `WaitGroup` &middot; `ErrGroup` &middot; `select()` &middot; `context`
 
-- separate worker entry files
-- manual message passing
-- manual pooling
-- no built-in channels, `WaitGroup`, `ErrGroup`, or `select`
+**Synchronization:** `Mutex` &middot; `RWMutex` &middot; `Once` &middot; `Cond`
 
-`puru` keeps the power and removes most of the ceremony.
+**Timing:** `after()` &middot; `ticker()` &middot; `Timer`
 
-### Cluster
+**Ergonomics:** `task()` &middot; `configure()` &middot; `stats()` &middot; directional channels &middot; channel `len`/`cap`
 
-Cluster solves a different problem.
+All modeled after Go's concurrency primitives. Full API in [docs/API.md](docs/API.md).
 
-- Cluster: more processes, better request throughput
-- `puru`: offload heavy work inside each process
+## Why Not Just Use...
 
-They work well together.
+**`Promise.all()`** — Great for cheap async work. Use puru when work is CPU-heavy or you need the main thread to stay responsive.
 
-## Feature Snapshot
+**`worker_threads`** — Powerful but low-level: separate files, manual messaging, manual pooling, no channels/WaitGroup/select. puru keeps the power, removes the ceremony.
 
-| Feature | `puru` |
-| --- | --- |
-| Inline worker functions | Yes |
-| Dedicated CPU workers | Yes |
-| Shared-worker async mode | Yes |
-| Channels across workers | Yes |
-| WaitGroup / ErrGroup | Yes |
-| `select` / timers | Yes |
-| Mutex / Once | Yes |
-| Bun support | Yes |
-| TypeScript support | Yes |
+**Cluster** — Cluster adds processes for request throughput. puru offloads heavy work inside each process. They compose well together.
 
-## Performance
+## Runtimes
 
-`puru` is designed for real work, not micro-bench tricks.
+| Runtime | Status |
+| --- | --- |
+| Node.js >= 20 | Full support |
+| Bun | Full support |
+| Deno | Planned |
 
-- Spawn overhead is roughly `0.1-0.5ms`
-- As a rule of thumb, use worker threads for tasks above `~5ms`
-- CPU-bound benchmarks show real speedups from multi-core execution
-- Concurrent async benchmarks show large gains when many tasks mostly wait on I/O off the main thread
+## Testing
 
-Full benchmark tables live in [docs/BENCHMARKS.md](docs/BENCHMARKS.md).
+```ts
+import { configure } from '@dmop/puru'
+configure({ adapter: 'inline' }) // runs on main thread, no real workers
+```
 
 ## Docs
 
@@ -210,33 +185,13 @@ Full benchmark tables live in [docs/BENCHMARKS.md](docs/BENCHMARKS.md).
 - [Production use cases](USE-CASES.md)
 - [Examples](examples)
 - [AI assistant guide](AGENTS.md)
-- [Full LLM reference](llms-full.txt)
-
-## Runtimes
-
-| Runtime | Support | Notes |
-| --- | --- | --- |
-| Node.js >= 20 | Full | Uses `worker_threads` |
-| Bun | Full | Uses Web Workers |
-| Deno | Planned | Not yet implemented |
-
-## Testing
-
-Use the inline adapter to run tasks on the main thread in tests:
-
-```ts
-import { configure } from '@dmop/puru'
-
-configure({ adapter: 'inline' })
-```
 
 ## Limitations
 
-- `spawn()` functions cannot capture outer variables
-- Channel values must be structured-cloneable
-- `null` is reserved as the channel closed sentinel
+- `spawn()` functions cannot capture outer variables (see [The Big Rule](#the-big-rule))
+- Channel values must be structured-cloneable (no functions, symbols, WeakRefs)
+- `null` is reserved as the channel-closed sentinel
 - `task()` arguments must be JSON-serializable
-- Channel ops from workers have RPC overhead, so use them for coordination, not ultra-fine-grained inner loops
 
 ## License