puru - GitLite

KO | EN

gitlite — search

#javascript #python #hacktoberfest #typescript #llm #deep-learning #linux #docker #nodejs #java #windows #cli #ios #mcp

puru

(★ 55)

Go-style concurrency and parallelism for JavaScript. Works on Node.js and Bun.

File Explorer

Download Latest Version (.zip)

- config.json
- README.md
- - bug_report.yml
  - feature_request.yml
- - ci.yml
  - docs.yml
  - publish.yml
- dependabot.yml
- pull_request_template.md
- pre-commit
- settings.json
- 01-fibonacci.ts
- 02-primes.ts
- 03-matrix.ts
- 04-data-processing.ts
- 05-overhead.ts
- 06-channels-pipeline.ts
- 07-concurrent-async.ts
- 08-mutex.ts
- 09-errgroup.ts
- 10-select-default.ts
- 11-once-ticker.ts
- run-all.ts
- utils.ts
- API.md
- BENCHMARKS.md
- CHOOSING-PRIMITIVES.md
- HOW-IT-WORKS.md
- PURU-VS-PISCINA.md
- USE-CASES.md
- 01-spawn.ts
- 02-waitgroup.ts
- 03-errgroup.ts
- 04-channels.ts
- 05-mutex-once.ts
- 06-select-timers.ts
- 07-task.ts
- 08-configure-stats.ts
- 09-file-hashing.ts
- 10-log-pipeline.ts
- 11-health-check.ts
- 12-json-processing.ts
- 13-dashboard-aggregation.ts
- 14-context.ts
- 15-rwmutex-timer-cond.ts
- - base.ts
  - bun-worker.d.ts
  - bun.ts
  - inline.ts
  - node.ts
- after.ts
- bootstrap.ts
- channel.ts
- cond.ts
- configure.ts
- context.ts
- errgroup.ts
- index.ts
- mutex.ts
- once.ts
- pool.ts
- queue.ts
- registry.ts
- runtime.ts
- select.ts
- semaphore.ts
- serialize.ts
- spawn.ts
- ticker.ts
- timer.ts
- types.ts
- waitgroup.ts
- after.test.ts
- channel-worker.test.ts
- channel.test.ts
- concurrent.test.ts
- cond.test.ts
- configure.test.ts
- context.test.ts
- errgroup.test.ts
- inline.test.ts
- mutex.test.ts
- once.test.ts
- pool.test.ts
- queue.test.ts
- registry.test.ts
- select.test.ts
- semaphore.test.ts
- serialize.test.ts
- spawn.test.ts
- stats.test.ts
- ticker.test.ts
- timer.test.ts
- waitgroup.test.ts
- work-stealing.test.ts
- - benchmarks.md
  - intro.md
- - .nojekyll
- .gitignore
- docusaurus.config.ts
- package-lock.json
- package.json
- sidebars.ts
- tsconfig.json
- typedoc.tsconfig.json
.gitignore
.oxfmtrc.json
.oxlintrc.json
AGENTS.md
CHANGELOG.md
CONTRIBUTING.md
LICENSE
llms-full.txt
llms.txt
package-lock.json
package.json
README.md
SECURITY.md
tsconfig.check.json
tsconfig.json
tsup.config.ts
typedoc.json
vitest.config.ts

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# puru (プール)

[![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)
[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/@dmop/puru?activeTab=dependencies)
[![license](https://img.shields.io/npm/l/@dmop/puru)](https://raw.githubusercontent.com/dmop/puru/main/LICENSE)

**Go-style concurrency and parallelism for JavaScript.** Worker threads deliver true CPU **parallelism** across cores. Go-style `chan`, `WaitGroup`, `ErrGroup`, `select`, and `context` manage **concurrency** — zero dependencies, no worker files, no boilerplate.

```ts
import { spawn } from '@dmop/puru'

const { result } = spawn(() => {
  let sum = 0
  for (let i = 0; i < 100_000_000; i++) sum += i
  return sum
})

console.log(await result) // runs off the main thread
```

## Before / After

<table>
<tr><th>Raw worker_threads</th><th>puru</th></tr>
<tr>
<td>

```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)

// worker.js (separate file)
const { parentPort } = require('worker_threads')
parentPort.on('message', ({ n }) => {
  parentPort.postMessage(fibonacci(n))
})
```

</td>
<td>

```ts
import { spawn } from '@dmop/puru'

const { result } = spawn(() => {
  function fibonacci(n: number): number {
    if (n <= 1) return n
    return fibonacci(n - 1) + fibonacci(n - 2)
  }
  return fibonacci(40)
})

try {
  console.log(await result)
} catch (err) {
  console.error(err)
}
```

</td>
</tr>
</table>

One file. No message plumbing. Automatic pooling.

## Install

Zero runtime dependencies — just the library itself.

```bash
npm install @dmop/puru
# or
bun add @dmop/puru
```

## Quick Start

```ts
import { spawn, WaitGroup, chan, task } from '@dmop/puru'

// CPU work on a dedicated worker
const { result } = spawn(() => {
  function fibonacci(n: number): number {
    if (n <= 1) return n
    return fibonacci(n - 1) + fibonacci(n - 2)
  }
  return fibonacci(40)
})

// Reusable worker logic with explicit arguments
const crunch = task((n: number) => {
  let sum = 0
  for (let i = 0; i < n; i++) sum += i
  return sum
})

// Parallel batch — wait for all
const wg = new WaitGroup()
wg.spawn(() => 21 * 2)
wg.spawn(() => 6 * 7)
const [a, b] = await wg.wait()

const bigNumber = await result
const heavySum = await crunch(1_000_000)
console.log({ a, b, bigNumber, heavySum })

// 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)
```

## Performance

Measured on Apple M1 Pro (8 cores). Full results in [BENCHMARKS.md](docs/BENCHMARKS.md).

| 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** |

Spawn overhead: ~0.1-0.5ms. Use for tasks above ~5ms.

## Two Modes

| Mode | Kind | Use it for | What happens |
| --- | --- | --- | --- |
| `spawn(fn)` | **Parallelism** | CPU-bound work | Dedicated worker thread — runs on a separate CPU core |
| `spawn(fn, { concurrent: true })` | **Concurrency** | Async / I/O work | Shares a worker's event loop (M:N scheduling) |

## When To Use What

| Situation | Tool |
| --- | --- |
| 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()` |

## The Big Rule

> **Functions passed to `spawn()` cannot capture outer variables.** They are serialized as text and sent to a worker — closures don't survive.

```ts
const x = 42
spawn(() => x + 1)          // ReferenceError at runtime

spawn(() => {
  const x = 42               // define inside
  return x + 1
})                            // works
```

Use `task(fn)` to pass arguments to reusable worker functions.

## What's Included

**Coordination:** `chan()` &middot; `WaitGroup` &middot; `ErrGroup` &middot; `select()` &middot; `context`

**Synchronization:** `Mutex` &middot; `RWMutex` &middot; `Once` &middot; `Cond`

**Timing:** `after()` &middot; `ticker()` &middot; `Timer`

**Ergonomics:** `task()` &middot; `configure()` &middot; `stats()` &middot; directional channels &middot; channel `len`/`cap`

All modeled after Go's concurrency primitives. Full API in [docs/API.md](docs/API.md).

## Why Not Just Use...

**`Promise.all()`** — Great for cheap async work. Use puru when work is CPU-heavy or you need the main thread to stay responsive.

**`worker_threads`** — Powerful but low-level: separate files, manual messaging, manual pooling, no channels/WaitGroup/select. puru keeps the power, removes the ceremony.

**Cluster** — Cluster adds processes for request throughput. puru offloads heavy work inside each process. They compose well together.

## Runtimes

| Runtime | Status |
| --- | --- |
| Node.js >= 20 | Full support |
| Bun | Full support |
| Deno | Planned |

## Testing

```ts
import { configure } from '@dmop/puru'
configure({ adapter: 'inline' }) // runs on main thread, no real workers
```

## Docs

- [Choosing the right primitive](docs/CHOOSING-PRIMITIVES.md)
- [API reference](docs/API.md)
- [How it works](docs/HOW-IT-WORKS.md)
- [Benchmarks](docs/BENCHMARKS.md)
- [Production use cases](docs/USE-CASES.md)
- [Examples](examples)
- [AI assistant guide](AGENTS.md)

## Limitations

- `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

## License

MIT