@dmop/puru 0.1.3 → 0.1.5

package/llms-full.txt

@@ -0,0 +1,286 @@
+# puru (プール) — Full Documentation
+
+> A thread pool with Go-style concurrency primitives for JavaScript
+
+puru manages a pool of worker threads and provides a simple API to run functions off the main thread. No separate worker files, no manual message passing.
+
+Works on Node.js and Bun. Deno support coming soon.
+
+puru (プール) means "pool" in Japanese.
+
+## Install
+
+npm install @dmop/puru
+bun add @dmop/puru
+
+## Quick Start
+
+```typescript
+import { spawn, chan, WaitGroup, select, after } from '@dmop/puru'
+
+// CPU work — runs in a dedicated worker thread
+const { result } = spawn(() => fibonacci(40))
+console.log(await result)
+
+// 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 })
+}
+const results = await wg.wait()
+```
+
+## How It Works
+
+puru manages a thread pool — tasks are dispatched onto a fixed set of worker threads.
+
+Two modes:
+
+- Exclusive (default): 1 task per thread, full core usage. Best for CPU-bound work.
+- Concurrent ({ concurrent: true }): many tasks share a thread's event loop. Best for I/O-bound / async work.
+
+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.
+
+## API Reference
+
+### spawn(fn, opts?)
+
+Run a function in a worker thread. Returns { result: Promise<T>, cancel: () => void }.
+
+```typescript
+// CPU-bound — exclusive mode (default)
+const { result } = spawn(() => fibonacci(40))
+
+// I/O-bound — concurrent mode (many tasks per thread)
+const { result } = spawn(() => fetch(url), { concurrent: true })
+
+// With priority
+const { result } = spawn(() => criticalWork(), { priority: 'high' })
+
+// Cancel
+const { result, cancel } = spawn(() => longTask())
+setTimeout(cancel, 5000)
+```
+
+Options:
+- priority: 'low' | 'normal' | 'high' (default: 'normal')
+- concurrent: boolean (default: false)
+- channels: Record<string, Channel<unknown>> — pass channels to the worker
+
+Exclusive mode (default): the function gets a dedicated thread. Use for CPU-heavy work.
+Concurrent mode ({ concurrent: true }): multiple tasks share a thread's event loop. Use for async/I/O work.
+
+Functions must be self-contained — they cannot capture variables from the enclosing scope:
+
+```typescript
+const x = 42
+spawn(() => x + 1)   // ReferenceError: x is not defined
+spawn(() => 42 + 1)  // works
+```
+
+### chan(capacity?)
+
+Create a channel for communicating between async tasks — including across worker threads.
+
+```typescript
+const ch = chan<number>(10) // buffered, capacity 10
+const ch = chan<string>()   // unbuffered, capacity 0
+
+await ch.send(42)
+const value = await ch.recv() // 42
+
+ch.close()
+await ch.recv() // null (closed)
+
+// Async iteration
+for await (const value of ch) {
+  process(value)
+}
+```
+
+Channels in workers — pass channels to spawn() and use them across worker threads:
+
+```typescript
+const ch = chan<number>(10)
+
+// Producer worker
+spawn(async ({ ch }) => {
+  for (let i = 0; i < 100; i++) await ch.send(i)
+  ch.close()
+}, { channels: { ch } })
+
+// Consumer worker
+spawn(async ({ ch }) => {
+  for await (const item of ch) process(item)
+}, { channels: { ch } })
+
+// Fan-out: multiple workers pulling from the same channel
+const input = chan<Job>(50)
+const output = chan<Result>(50)
+
+for (let i = 0; i < 4; i++) {
+  spawn(async ({ input, output }) => {
+    for await (const job of input) {
+      await output.send(processJob(job))
+    }
+  }, { channels: { input, output } })
+}
+```
+
+### WaitGroup
+
+Structured concurrency. Spawn multiple tasks, wait for all.
+
+```typescript
+const wg = new WaitGroup()
+wg.spawn(() => cpuWork())                          // exclusive
+wg.spawn(() => fetchData(), { concurrent: true })  // concurrent
+
+const results = await wg.wait()       // like Promise.all
+const settled = await wg.waitSettled() // like Promise.allSettled
+
+wg.cancel() // cancel all tasks
+```
+
+### ErrGroup
+
+Like WaitGroup, but cancels all remaining tasks on first error (modeled after Go's golang.org/x/sync/errgroup).
+
+```typescript
+const eg = new ErrGroup()
+eg.spawn(() => fetchUser(id))
+eg.spawn(() => fetchOrders(id))
+eg.spawn(() => fetchAnalytics(id))
+
+try {
+  const [user, orders, analytics] = await eg.wait()
+} catch (err) {
+  // First error — all other tasks were cancelled
+  console.error('Failed:', err)
+}
+```
+
+### Mutex
+
+Async mutual exclusion. Serialize access to shared resources under concurrency.
+
+```typescript
+const mu = new Mutex()
+
+// withLock — recommended (auto-unlocks on error)
+const result = await mu.withLock(async () => {
+  return await db.query('UPDATE ...')
+})
+
+// Manual lock/unlock
+await mu.lock()
+try { /* critical section */ }
+finally { mu.unlock() }
+```
+
+### Once<T>
+
+Run a function exactly once, even if called concurrently. All callers get the same result.
+
+```typescript
+const once = new Once<DBConnection>()
+const conn = await once.do(() => createExpensiveConnection())
+// Subsequent calls return the cached result
+```
+
+### select(cases, opts?)
+
+Wait for the first of multiple promises to resolve, like Go's select.
+
+```typescript
+// Blocking — waits for first ready
+await select([
+  [ch.recv(), (value) => console.log('received', value)],
+  [after(5000), () => console.log('timeout')],
+])
+
+// Non-blocking — returns immediately if nothing is ready (Go's select with default)
+await select(
+  [[ch.recv(), (value) => process(value)]],
+  { default: () => console.log('channel not ready') },
+)
+```
+
+### after(ms) / ticker(ms)
+
+Timers for use with select and async iteration.
+
+```typescript
+await after(1000) // one-shot: resolves after 1 second
+
+// Repeating: tick every 500ms
+const t = ticker(500)
+for await (const _ of t) {
+  console.log('tick')
+  if (shouldStop) t.stop()
+}
+```
+
+### register(name, fn) / run(name, ...args)
+
+Named task registry. Register functions by name, call them by name.
+
+```typescript
+register('resize', (buffer, w, h) => sharp(buffer).resize(w, h).toBuffer())
+const resized = await run('resize', imageBuffer, 800, 600)
+```
+
+### configure(opts?)
+
+Optional global configuration. Must be called before the first spawn().
+
+```typescript
+configure({
+  maxThreads: 4,        // default: os.availableParallelism()
+  concurrency: 64,      // max concurrent tasks per shared worker (default: 64)
+  idleTimeout: 30_000,  // kill idle workers after 30s (default)
+  adapter: 'auto',      // 'auto' | 'node' | 'bun' | 'inline'
+})
+```
+
+### stats() / resize(n)
+
+```typescript
+const s = stats()  // { totalWorkers, idleWorkers, busyWorkers, queuedTasks, ... }
+resize(8)          // scale pool up/down at runtime
+```
+
+### detectRuntime() / detectCapability()
+
+```typescript
+detectRuntime()     // 'node' | 'bun' | 'deno' | 'browser'
+detectCapability()  // 'full-threads' | 'single-thread'
+```
+
+## Runtimes
+
+- Node.js >= 18: Full support via worker_threads
+- Bun: Full support via Web Workers (file-based)
+- Deno: Planned
+- Cloudflare Workers: Not supported (no thread support)
+- Vercel Edge: Not supported (no thread support)
+
+## Testing
+
+```typescript
+import { configure } from '@dmop/puru'
+configure({ adapter: 'inline' }) // runs tasks in main thread, no real workers
+```
+
+## Limitations
+
+- Functions passed to spawn() cannot capture variables from the enclosing scope
+- Channel values must be structured-cloneable (no functions, symbols, or WeakRefs)
+- null cannot be sent through a channel (it's the "closed" sentinel)
+- register()/run() args must be JSON-serializable
+- Channel operations from workers have ~0.1-0.5ms RPC overhead per send/recv (fine for coarse-grained coordination, not for per-item micro-operations)
+- Spawn overhead is ~0.1-0.5ms — use spawn for tasks > 5ms; for trivial operations, call directly
+
+## License
+
+MIT

package/llms.txt

@@ -0,0 +1,45 @@
+# puru (プール)
+
+> A thread pool with Go-style concurrency primitives for JavaScript
+
+puru manages a pool of worker threads and provides a simple API to run functions off the main thread. No separate worker files, no manual message passing.
+
+Works on Node.js and Bun. Deno support coming soon.
+
+## Install
+
+npm install @dmop/puru
+bun add @dmop/puru
+
+## Core API
+
+- spawn(fn, opts?) — run a function in a worker thread, returns { result: Promise<T>, cancel() }
+- chan(capacity?) — Go-style channels for cross-thread communication
+- WaitGroup — spawn multiple tasks, wait for all (like Promise.all but off main thread)
+- ErrGroup — like WaitGroup but cancels all on first error
+- select(cases, opts?) — wait for first of multiple promises (like Go's select)
+- Mutex — async mutual exclusion
+- Once<T> — run a function exactly once, all callers get same result
+- after(ms) / ticker(ms) — timers for use with select and async iteration
+- register(name, fn) / run(name, ...args) — named task registry
+- configure(opts?) — global config (maxThreads, concurrency, idleTimeout, adapter)
+- stats() / resize(n) — pool introspection and runtime scaling
+
+## Two Modes
+
+- Exclusive (default): 1 task per thread, for CPU-bound work — spawn(() => heavyWork())
+- Concurrent: many tasks share a thread's event loop, for I/O-bound work — spawn(() => fetch(url), { concurrent: true })
+
+## Key Constraints
+
+- Functions passed to spawn() must be self-contained (no closure captures)
+- Channel values must be structured-cloneable (no functions, symbols, WeakRefs)
+- null cannot be sent through channels (it's the "closed" sentinel)
+- register()/run() args must be JSON-serializable
+- Spawn overhead is ~0.1-0.5ms, use for tasks > 5ms
+
+## Links
+
+- Docs: https://github.com/dmop/puru#readme
+- Full docs for LLMs: https://raw.githubusercontent.com/dmop/puru/main/llms-full.txt
+- AI assistant guide (AGENTS.md): https://raw.githubusercontent.com/dmop/puru/main/AGENTS.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmop/puru",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "puru (プール) — A thread pool with Go-style concurrency primitives for JavaScript",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -19,7 +19,10 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "llms.txt",
+    "llms-full.txt",
+    "AGENTS.md"
   ],
   "engines": {
     "node": ">=18.0.0"