@dmop/puru 0.1.5 → 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
 
@@ -80,68 +80,179 @@ const { result } = spawn(() => {
 console.log(await result)
 ```
 
-### Multiple tasks in parallel (WaitGroup)
+### Multiple tasks in parallel (`task()`)
 
 ```typescript
-import { WaitGroup } from '@dmop/puru'
+import { task } from '@dmop/puru'
 
 const items = [1, 2, 3, 4]
-const wg = new WaitGroup()
-
-for (const item of items) {
-  const value = item // capture as a literal for each iteration
-  wg.spawn(() => {
-    // `value` is NOT captured from closure — this won't work
-    // you must inline or use register()/run()
-  })
+const processItem = task((item: number) => item * 2)
+const results = await Promise.all(items.map((item) => processItem(item)))
+```
+
+### Concurrent I/O (concurrent mode)
+
+```typescript
+import { spawn } from '@dmop/puru'
+
+const user = spawn(
+  () => fetch('https://api.example.com/users/1').then((r) => r.json()),
+  { concurrent: true },
+)
+
+const orders = spawn(
+  () => fetch('https://api.example.com/users/1/orders').then((r) => r.json()),
+  { concurrent: true },
+)
+
+const results = await Promise.all([user.result, orders.result])
+```
+
+### Cancel on first error (ErrGroup)
+
+```typescript
+import { ErrGroup } from '@dmop/puru'
+
+const eg = new ErrGroup()
+eg.spawn(() => fetch('https://api.example.com/users/1').then((r) => r.json()), { concurrent: true })
+eg.spawn(() => fetch('https://api.example.com/users/1/orders').then((r) => r.json()), { concurrent: true })
+
+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()
 ```
 
-To pass per-task data, use `register`/`run`:
+### Context-integrated spawn (auto-cancel)
 
 ```typescript
-import { register, run, WaitGroup } from '@dmop/puru'
+import { spawn, background, withTimeout } from '@dmop/puru'
 
-// Register once at startup
-register('processItem', (item: number) => item * 2)
+// Task auto-cancels when context expires — no manual wiring needed
+const [ctx, cancel] = withTimeout(background(), 5000)
+const { result } = spawn(() => heavyWork(), { ctx })
 
-const items = [1, 2, 3, 4]
-const wg = new WaitGroup()
-for (const item of items) {
-  wg.spawn(() => run('processItem', item))
+try {
+  console.log(await result)
+} finally {
+  cancel()
 }
-const results = await wg.wait()
 ```
 
-### Concurrent I/O (concurrent mode)
+### Context with WaitGroup / ErrGroup
 
 ```typescript
-import { WaitGroup } from '@dmop/puru'
+import { background, withTimeout, WaitGroup } from '@dmop/puru'
 
-const urls = ['https://...', 'https://...']
-const wg = new WaitGroup()
+const [ctx, cancel] = withTimeout(background(), 5000)
 
-for (const url of urls) {
-  wg.spawn(() => run('fetchUrl', url), { concurrent: true })
+// 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'))
 
-register('fetchUrl', (url: string) => fetch(url).then(r => r.json()))
-const results = await wg.wait()
+// Writers get exclusive access
+await rw.withLock(() => cache.set('config', newValue))
 ```
 
-### Cancel on first error (ErrGroup)
+### Timer (resettable one-shot)
 
 ```typescript
-import { ErrGroup, register } from '@dmop/puru'
+import { Timer, select } from '@dmop/puru'
 
-register('fetchUser', (id: number) => fetch(`/api/users/${id}`).then(r => r.json()))
-register('fetchOrders', (id: number) => fetch(`/api/orders/${id}`).then(r => r.json()))
+const t = new Timer(5000)
 
-const eg = new ErrGroup()
-eg.spawn(() => run('fetchUser', 1))
-eg.spawn(() => run('fetchOrders', 1))
+// Use with select for cancellable timeouts
+await select([
+  [ch.recv(), (v) => { t.stop(); handle(v) }],
+  [t.channel, () => console.log('timed out')],
+])
 
-const [user, orders] = await eg.wait() // throws on first error, cancels the rest
+// 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)
@@ -202,7 +313,7 @@ configure({ adapter: 'inline' })
 
 ## Runtimes
 
-- Node.js >= 18: full support
+- Node.js >= 20: full support
 - Bun: full support
 - Deno: planned
 - Cloudflare Workers / Vercel Edge: not supported (no thread API)