feat: add setWorkers() method chain, benchmarks.js, updated docs

- Add setWorkers(n) to turbo executor for customizing worker count
- Add benchmarks.js for reproducible performance testing (10 runs avg)
- Update README with benchmark results (Bun 1.83x speedup, Node non-blocking)
- Show blocking vs non-blocking status for each mode
- Add tests for setWorkers() validation

Author: samsantosb

README.md

@@ -503,6 +503,68 @@ const stream = beeThreads
 
 ---
 
+## Benchmarks
+
+Run the benchmark yourself:
+
+```bash
+bun benchmarks.js   # Bun
+node benchmarks.js  # Node
+```
+
+### Results (1M items, heavy function, 12 CPUs, 10 runs avg)
+
+**Bun** - Real parallel speedup:
+
+| Mode | Time (±std) | Speedup | Main Thread |
+|------|-------------|---------|-------------|
+| main | 285±5ms | 1.00x | ❌ blocked |
+| bee | 1138±51ms | 0.25x | ✅ free |
+| turbo(4) | 255±7ms | 1.12x | ✅ free |
+| turbo(8) | 180±8ms | **1.58x** | ✅ free |
+| **turbo(12)** | **156±12ms** | **1.83x** | ✅ free |
+| turbo(16) | 204±28ms | 1.40x | ✅ free |
+
+**Node** - Non-blocking I/O (slower, but frees main thread):
+
+| Mode | Time (±std) | Speedup | Main Thread |
+|------|-------------|---------|-------------|
+| main | 368±13ms | 1.00x | ❌ blocked |
+| bee | 5569±203ms | 0.07x | ✅ free |
+| turbo(4) | 1793±85ms | 0.21x | ✅ free |
+| turbo(8) | 1052±22ms | 0.35x | ✅ free |
+| **turbo(12)** | **1017±57ms** | **0.36x** | ✅ free |
+| turbo(16) | 1099±98ms | 0.34x | ✅ free |
+
+### Key Insights
+
+- **Bun + turbo(cpus)**: Up to **1.83x faster** than main thread
+- **bee/turbo**: Non-blocking - main thread stays **free for HTTP/I/O**
+- **Node + turbo**: Slower, but useful for keeping servers responsive
+- **bee vs turbo**: turbo is **7x faster** than bee for large arrays
+- **Default workers**: `cpus - 1` (safe for all systems)
+
+### Customize Workers
+
+```js
+// Method chain
+await beeThreads.turbo(data).setWorkers(12).map(fn)
+
+// Or via options
+await beeThreads.turbo(data, { workers: 12 }).map(fn)
+```
+
+### When to Use
+
+| Scenario | Recommendation |
+|----------|----------------|
+| Bun + heavy function | `turbo(cpus)` → real speedup |
+| Node + HTTP server | `turbo()` → non-blocking I/O |
+| Light function (`x*x`) | Main thread → overhead not worth it |
+| CLI/batch processing | `turbo(cpus + 4)` → max throughput |
+
+---
+
 ## Why bee-threads?
 
 - **Zero dependencies** - Lightweight and secure

benchmarks.js

@@ -0,0 +1,174 @@
+/**
+ * 🐝 bee-threads Benchmark Suite
+ * 
+ * Run with:
+ *   bun benchmarks.js
+ *   node benchmarks.js
+ * 
+ * Compares: main thread vs turbo
+ * Measures: execution time, CPU usage
+ */
+
+const os = require('os');
+const { bee, beeThreads } = require('./dist/index.js');
+
+const cpus = os.cpus().length;
+const runtime = typeof Bun !== 'undefined' ? 'Bun' : 'Node';
+
+// Config - Adjust based on your system
+const SIZE = 1_000_000;
+const RUNS = 10; // Number of runs for averaging
+
+// Heavy function (CPU intensive)
+const heavyFn = (x) => {
+  let v = x;
+  for (let i = 0; i < 10; i++) {
+    v = Math.sqrt(Math.abs(Math.sin(v) * 1000));
+  }
+  return v;
+};
+
+// CPU usage measurement
+function getCpuUsage() {
+  const usage = process.cpuUsage();
+  return {
+    user: usage.user / 1000,
+    system: usage.system / 1000
+  };
+}
+
+async function benchmark(name, fn) {
+  const times = [];
+  const cpuTimes = [];
+  
+  // Warmup run
+  await fn();
+  
+  // Measured runs
+  for (let run = 0; run < RUNS; run++) {
+    const cpuStart = getCpuUsage();
+    const start = performance.now();
+    
+    await fn();
+    
+    const elapsed = performance.now() - start;
+    const cpuEnd = getCpuUsage();
+    const cpuUsed = (cpuEnd.user - cpuStart.user) + (cpuEnd.system - cpuStart.system);
+    
+    times.push(elapsed);
+    cpuTimes.push(cpuUsed);
+  }
+  
+  // Calculate stats
+  const avg = arr => arr.reduce((a, b) => a + b, 0) / arr.length;
+  const stdDev = arr => {
+    const mean = avg(arr);
+    return Math.sqrt(arr.reduce((sum, x) => sum + (x - mean) ** 2, 0) / arr.length);
+  };
+  
+  const ms = avg(times);
+  const msStd = stdDev(times);
+  const cpu = avg(cpuTimes);
+  // CPU usage as percentage: (total CPU time / elapsed time) * 100
+  // >100% means multiple cores were used
+  const cpuUsage = (cpu / ms) * 100;
+  
+  return { name, ms, msStd, cpu, cpuUsage };
+}
+
+async function main() {
+  console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║           🐝 bee-threads Benchmark Suite                      ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Runtime: ${runtime.padEnd(10)} │ CPUs: ${String(cpus).padEnd(4)} │ Array: ${(SIZE/1e6).toFixed(1)}M items   ║
+║  Function: Heavy (Math.sqrt + Math.sin × 10 iterations)       ║
+╚═══════════════════════════════════════════════════════════════╝
+`);
+
+  const arr = new Array(SIZE).fill(0).map((_, i) => i);
+  const results = [];
+
+  // 1) Main thread
+  console.log('⏳ Testing main thread...');
+  results.push(await benchmark('main', () => {
+    arr.map(heavyFn);
+  }));
+
+  // 2) bee() - single worker
+  console.log('⏳ Testing bee()...');
+  try {
+    const beeResult = await Promise.race([
+      benchmark('bee', async () => {
+        await bee((data) => {
+          return data.map(x => {
+            let v = x;
+            for (let i = 0; i < 10; i++) v = Math.sqrt(Math.abs(Math.sin(v) * 1000));
+            return v;
+          });
+        })(arr);
+      }),
+      new Promise((_, rej) => setTimeout(() => rej(new Error('timeout')), 120000))
+    ]);
+    results.push(beeResult);
+  } catch (e) {
+    console.log('   ⚠️ bee() timed out or failed');
+    results.push({ name: 'bee', ms: Infinity, msStd: 0, cpu: 0, cpuUsage: 0 });
+  }
+
+  // 3) turbo with different worker counts
+  const workerConfigs = [4, 8, cpus];
+  if (cpus > 8) workerConfigs.push(cpus + 4);
+  for (const workers of workerConfigs) {
+    console.log(`⏳ Testing turbo(${workers})...`);
+    try {
+      const result = await Promise.race([
+        benchmark(`turbo(${workers})`, async () => {
+          await beeThreads.turbo(arr, { workers, force: true }).map(heavyFn);
+        }),
+        new Promise((_, rej) => setTimeout(() => rej(new Error('timeout')), 60000))
+      ]);
+      results.push(result);
+    } catch (e) {
+      console.log(`   ⚠️ turbo(${workers}) timed out`);
+      results.push({ name: `turbo(${workers})`, ms: Infinity, msStd: 0, cpu: 0, cpuUsage: 0 });
+    }
+  }
+
+  // Print results
+  const mainMs = results[0].ms;
+  
+  console.log(`
+┌─────────────┬────────────────┬─────────┬─────────────┐
+│    Mode     │  Time (±std)   │ vs Main │ Main Thread │
+├─────────────┼────────────────┼─────────┼─────────────┤`);
+
+  for (const r of results) {
+    const speedup = (mainMs / r.ms).toFixed(2);
+    const marker = parseFloat(speedup) >= 1 ? '✅' : '  ';
+    const timeStr = `${r.ms.toFixed(0)}±${r.msStd.toFixed(0)}ms`;
+    const blocking = r.name === 'main' ? '❌ blocked' : '✅ free';
+    console.log(`│ ${r.name.padEnd(11)} │ ${timeStr.padStart(14)} │ ${speedup.padStart(5)}x ${marker}│ ${blocking.padEnd(11)} │`);
+  }
+
+  console.log(`└─────────────┴────────────────┴─────────┴─────────────┘`);
+  console.log(`\n   📈 Stats: ${RUNS} runs per config (+ 1 warmup)`);
+
+  // Summary
+  const best = results.slice(1).reduce((a, b) => a.ms < b.ms ? a : b);
+  const bestSpeedup = (mainMs / best.ms).toFixed(2);
+
+  console.log(`
+📊 Summary:
+   • Best turbo config: ${best.name} (${bestSpeedup}x vs main)
+   • Recommended: turbo(${cpus}) for this system
+   
+💡 Customize workers:
+   beeThreads.turbo(arr).setWorkers(${cpus}).map(fn)
+`);
+
+  await beeThreads.shutdown();
+}
+
+main().catch(console.error);
+

src/turbo.ts

@@ -106,6 +106,8 @@ function isTypedArray(value: unknown): value is NumericTypedArray {
 // ============================================================================
 
 export interface TurboExecutor<TItem> {
+  /** Set the number of workers to use. Returns a new executor. */
+  setWorkers(count: number): TurboExecutor<TItem>;
   map<TResult>(fn: (item: TItem, index: number) => TResult): Promise<TResult[]>;
   mapWithStats<TResult>(fn: (item: TItem, index: number) => TResult): Promise<TurboResult<TResult>>;
   filter(fn: (item: TItem, index: number) => boolean): Promise<TItem[]>;
@@ -132,6 +134,13 @@ export function createTurboExecutor<TItem>(
 ): TurboExecutor<TItem> {
   // V8: Monomorphic object shape - all methods declared upfront
   const executor: TurboExecutor<TItem> = {
+    setWorkers(count: number): TurboExecutor<TItem> {
+      if (!Number.isInteger(count) || count < 1) {
+        throw new TypeError('setWorkers() requires a positive integer');
+      }
+      return createTurboExecutor<TItem>(data, { ...options, workers: count });
+    },
+
     map<TResult>(fn: (item: TItem, index: number) => TResult): Promise<TResult[]> {
       const fnString = fn.toString();
       return executeTurboMap<TResult>(fnString, data as unknown[], options);
@@ -897,6 +906,13 @@ export function createMaxExecutor<TItem>(
 ): TurboExecutor<TItem> {
   // V8: Monomorphic object shape
   const executor: TurboExecutor<TItem> = {
+    setWorkers(count: number): TurboExecutor<TItem> {
+      if (!Number.isInteger(count) || count < 1) {
+        throw new TypeError('setWorkers() requires a positive integer');
+      }
+      return createMaxExecutor<TItem>(data, { ...options, workers: count });
+    },
+
     map<TResult>(fn: (item: TItem, index: number) => TResult): Promise<TResult[]> {
       const fnString = fn.toString();
       return executeMaxMap<TResult>(fnString, data as unknown[], options);

test.ts

@@ -3246,6 +3246,29 @@ async function runTests(): Promise<void> {
     assert.deepStrictEqual(result, data, 'Order must be preserved');
   });
 
+  await test('turbo().setWorkers(n) customizes worker count', async () => {
+    const data = [1, 2, 3, 4, 5];
+    const result = await beeThreads.turbo(data, { force: true }).setWorkers(2).map((x: number) => x * 2);
+    
+    assert.deepStrictEqual(result, [2, 4, 6, 8, 10], 'setWorkers should work');
+  });
+
+  await test('turbo().setWorkers() throws for invalid input', () => {
+    const data = [1, 2, 3];
+    
+    assert.throws(() => {
+      beeThreads.turbo(data).setWorkers(0);
+    }, TypeError);
+    
+    assert.throws(() => {
+      beeThreads.turbo(data).setWorkers(-1);
+    }, TypeError);
+    
+    assert.throws(() => {
+      beeThreads.turbo(data).setWorkers(1.5);
+    }, TypeError);
+  });
+
   // ---------- TURBO BENCHMARKS ----------
   section('Turbo Mode - Benchmarks');