feat(worker): add optional worker pool for CPU-bound work ⚡

- Add Worker Pool docs (en, id) and sidebar; CHANGELOG and README
- Add Worker pool (createPool, run), export and Types (WorkerPoolOptions, WorkerRunHandle)
- Add benchmark main-worker, test-cpu and test-worker routes; update benchmark README
- Handler sets ctx.state.worker when configured; Router forwards worker option
- Add Worker tests and echo/error fixtures; Handler/Router worker tests; reorder validateModule tests
- Remove bench task from deno.json; sort Types.ts A–Z, JSDoc on Worker.ts

Author: NeaByteLab

CHANGELOG.md

@@ -8,7 +8,17 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
-(Nothing yet.)
+### Added
+
+- **feat(worker):** Worker pool for CPU-bound tasks; optional `worker` option on Router with `scriptURL` and `poolSize`; `ctx.state.worker.run(payload)` in routes when enabled
+- **docs(worker):** Worker Pool docs (en + id) under Core Concepts, marked Unreleased; VitePress sidebar updated
+- **benchmark(worker):** `main-worker.ts`, `/test-worker` and `/test-cpu` routes, benchmark README in English
+- **test(worker):** Worker pool tests and fixtures (`echo_worker.ts`, `error_worker.ts`)
+
+### Changed
+
+- **refactor(src):** Clear naming and A–Z sort in `Worker.ts`; JSDoc (ts-js-jsdoc) and constructor docs; Types.ts interfaces/properties sorted A–Z
+- **docs(benchmark):** Benchmark README — one Indonesian sentence translated to English
 
 ---
 

README.md

@@ -16,6 +16,7 @@ Build HTTP server effortlessly with zero configuration for productivity.
 - **Middleware** — Global, path-specific. CORS, SecHeaders, Body Limit, Basic Auth, Session, WebSocket.
 - **Static Files** — `router.static(urlPath, options)` with optional etag and cache-control.
 - **Error Handling** — Pluggable error response builder and error middleware; default HTML/JSON by `Accept`.
+- **Worker Pool** — Optional worker pool for CPU-bound work; enable via `worker: { scriptURL, poolSize }`.
 - **Frontend Optional** — Use any stack (Vite, React, etc.); Deserve stays the server.
 
 ## Installation
@@ -40,6 +41,12 @@ import { Router } from 'jsr:@neabyte/deserve'
 // Create router and point to your routes directory
 const router = new Router({ routesDir: './routes' })
 
+// Optional: enable worker pool for CPU-bound work (ctx.state.worker.run(payload) in routes)
+// const router = new Router({
+//   routesDir: './routes',
+//   worker: { scriptURL: import.meta.resolve('./worker.ts'), poolSize: 4 }
+// })
+
 // Start server on port 8000
 await router.serve(8000)
 ```

benchmark/README.md

@@ -7,17 +7,18 @@
 
 ## How to Run
 
-**1. Start the server** (from repo root):
+**1. Start the server** (from repo root). Pick one:
 
-```bash
-deno task bench
-```
+- **Without worker** — `/test` and `/test-cpu` only; `/test-worker` returns 503:
 
-Or:
+  ```bash
+  deno run --allow-net --allow-read benchmark/main.ts
+  ```
 
-```bash
-deno run --allow-net --allow-read benchmark/main.ts
-```
+- **With worker** — all routes including `/test-worker`:
+  ```bash
+  deno run --allow-net --allow-read benchmark/main-worker.ts
+  ```
 
 **2. Run autocannon** (in another terminal; requires Node/npx):
 
@@ -27,95 +28,59 @@ npx autocannon http://localhost:8000/test -c 500 -p 10 -d 30
 
 ## Files
 
-- **`benchmark/main.ts`** — Router with `routesDir: 'benchmark/routes'`, serves on port 8000.
-- **`benchmark/routes/test.ts`** — GET handler returning `{ hello: 'world!' }` via `ctx.send.json()`.
+- **`benchmark/main.ts`** — Router without worker. Serves `/test`, `/test-cpu`.
+- **`benchmark/main-worker.ts`** — Router with worker pool (inline CPU loop).
+- **`benchmark/routes/test.ts`** — GET `/test`: baseline, JSON only (no CPU work).
+- **`benchmark/routes/test-cpu.ts`** — GET `/test-cpu`: same CPU work (50k sqrt loop) on **main thread**.
+- **`benchmark/routes/test-worker.ts`** — GET `/test-worker`: same CPU work offloaded to **worker**.
 
-## Test Behavior
+## Routes for comparison
 
-- **Method:** GET
-- **Route:** `/test`
-- **Response:** `{ "hello": "world!" }` (JSON)
-- **File-based routing:** `benchmark/routes/test.ts` → pattern `/test`
-- **API:** `Context` + `ctx.send.json()`
+| Route          | Description                  | Use case             |
+| -------------- | ---------------------------- | -------------------- |
+| `/test`        | JSON only, no CPU            | Baseline throughput  |
+| `/test-cpu`    | 50k sqrt loop on main thread | Main-thread CPU cost |
+| `/test-worker` | Same loop in worker pool     | Worker offload cost  |
 
-## Previous Benchmark Results
+Run autocannon against each route (in another terminal):
 
-Below: autocannon runs with the older API (MacBook Pro M3 Pro, 11 cores, 18GB RAM). Re-run with the steps above to get numbers for the current codebase.
+```bash
+# Baseline (no CPU)
+npx autocannon http://localhost:8000/test -c 500 -p 10 -d 30
 
-### Test Run 1
+# CPU on main thread (blocks event loop)
+npx autocannon http://localhost:8000/test-cpu -c 500 -p 10 -d 30
 
-```
-Running 30s test @ http://localhost:8000/test
-500 connections with 10 pipelining factor
-
-
-┌─────────┬───────┬───────┬───────┬───────┬──────────┬─────────┬────────┐
-│ Stat    │ 2.5%  │ 50%   │ 97.5% │ 99%   │ Avg      │ Stdev   │ Max    │
-├─────────┼───────┼───────┼───────┼───────┼──────────┼─────────┼────────┤
-│ Latency │ 13 ms │ 24 ms │ 33 ms │ 42 ms │ 24.77 ms │ 5.78 ms │ 138 ms │
-└─────────┴───────┴───────┴───────┴───────┴──────────┴─────────┴────────┘
-┌───────────┬─────────┬─────────┬─────────┬─────────┬────────────┬───────────┬─────────┐
-│ Stat      │ 1%      │ 2.5%    │ 50%     │ 97.5%   │ Avg        │ Stdev     │ Min     │
-├───────────┼─────────┼─────────┼─────────┼─────────┼────────────┼───────────┼─────────┤
-│ Req/Sec   │ 166,527 │ 166,527 │ 203,519 │ 208,127 │ 199,249.07 │ 10,504.62 │ 166,415 │
-├───────────┼─────────┼─────────┼─────────┼─────────┼────────────┼───────────┼─────────┤
-│ Bytes/Sec │ 24.8 MB │ 24.8 MB │ 30.3 MB │ 31 MB   │ 29.7 MB    │ 1.56 MB   │ 24.8 MB │
-└───────────┴─────────┴─────────┴─────────┴─────────┴────────────┴───────────┴─────────┘
-
-Req/Bytes counts sampled once per second.
-# of samples: 30
-
-5983k requests in 30.23s, 891 MB read
+# CPU in worker (non-blocking)
+npx autocannon http://localhost:8000/test-worker -c 500 -p 10 -d 30
 ```
 
-### Test Run 2
+## Latest benchmark results (30s, 500 conn, pipelining 10)
 
-```
-Running 30s test @ http://localhost:8000/test
-500 connections with 10 pipelining factor
-
-
-┌─────────┬───────┬───────┬───────┬───────┬──────────┬─────────┬────────┐
-│ Stat    │ 2.5%  │ 50%   │ 97.5% │ 99%   │ Avg      │ Stdev   │ Max    │
-├─────────┼───────┼───────┼───────┼───────┼──────────┼─────────┼────────┤
-│ Latency │ 18 ms │ 23 ms │ 38 ms │ 42 ms │ 24.92 ms │ 6.56 ms │ 158 ms │
-└─────────┴───────┴───────┴───────┴───────┴──────────┴─────────┴────────┘
-┌───────────┬─────────┬─────────┬─────────┬─────────┬────────────┬───────────┬─────────┐
-│ Stat      │ 1%      │ 2.5%    │ 50%     │ 97.5%   │ Avg        │ Stdev     │ Min     │
-├───────────┼─────────┼─────────┼─────────┼─────────┼────────────┼───────────┼─────────┤
-│ Req/Sec   │ 162,431 │ 162,431 │ 200,063 │ 208,127 │ 197,789.87 │ 10,004.33 │ 162,409 │
-├───────────┼─────────┼─────────┼─────────┼─────────┼────────────┼───────────┼─────────┤
-│ Bytes/Sec │ 24.2 MB │ 24.2 MB │ 29.8 MB │ 31 MB   │ 29.5 MB    │ 1.49 MB   │ 24.2 MB │
-└───────────┴─────────┴─────────┴─────────┴─────────┴────────────┴───────────┴─────────┘
-
-Req/Bytes counts sampled once per second.
-# of samples: 30
-
-5939k requests in 30.2s, 884 MB read
-```
+**Non-worker** — `main.ts`:
 
-### Test Run 3
+| Route          | Test 1  | Test 2  | Test 3  | Req/Sec (avg) | Latency (avg) | Total (avg) |
+| -------------- | ------- | ------- | ------- | ------------- | ------------- | ----------- |
+| `/test`        | 175,343 | 170,567 | 164,515 | 170,142       | 29 ms         | 5109k       |
+| `/test-cpu`    | 25,009  | 24,949  | 24,927  | 24,962        | 199 ms        | 754k        |
+| `/test-worker` | 150,151 | 148,683 | 148,061 | 148,965       | 33 ms         | 4474k       |
 
-```
-Running 30s test @ http://localhost:8000/test
-500 connections with 10 pipelining factor
-
-
-┌─────────┬───────┬───────┬───────┬───────┬──────────┬─────────┬────────┐
-│ Stat    │ 2.5%  │ 50%   │ 97.5% │ 99%   │ Avg      │ Stdev   │ Max    │
-├─────────┼───────┼───────┼───────┼───────┼──────────┼─────────┼────────┤
-│ Latency │ 18 ms │ 23 ms │ 37 ms │ 40 ms │ 24.35 ms │ 5.94 ms │ 160 ms │
-└─────────┴───────┴───────┴───────┴───────┴──────────┴─────────┴────────┘
-┌───────────┬─────────┬─────────┬─────────┬─────────┬────────────┬──────────┬─────────┐
-│ Stat      │ 1%      │ 2.5%    │ 50%     │ 97.5%   │ Avg        │ Stdev    │ Min     │
-├───────────┼─────────┼─────────┼─────────┼─────────┼────────────┼──────────┼─────────┤
-│ Req/Sec   │ 184,191 │ 184,191 │ 203,391 │ 211,199 │ 202,628.27 │ 5,672.56 │ 184,142 │
-├───────────┼─────────┼─────────┼─────────┼─────────┼────────────┼──────────┼─────────┤
-│ Bytes/Sec │ 27.4 MB │ 27.4 MB │ 30.3 MB │ 31.5 MB │ 30.2 MB    │ 846 kB   │ 27.4 MB │
-└───────────┴─────────┴─────────┴─────────┴─────────┴────────────┴──────────┴─────────┘
-
-Req/Bytes counts sampled once per second.
-# of samples: 30
-
-6083k requests in 30.24s, 906 MB read
-```
+`/test-worker` without worker returns 503 (no pool).
+
+**With worker** — `main-worker.ts` (worker pool, poolSize 4).
+
+| Route          | Test 1  | Test 2  | Test 3  | Req/Sec (avg) | Latency (avg) | Total (avg) |
+| -------------- | ------- | ------- | ------- | ------------- | ------------- | ----------- |
+| `/test`        | 174,259 | 178,487 | 170,834 | 174,527       | 28 ms         | 5.24M       |
+| `/test-cpu`    | 25,133  | 24,833  | 24,773  | 24,912        | 199 ms        | 752k        |
+| `/test-worker` | 69,265  | 69,063  | 68,810  | 69,046        | 72 ms         | 2076k       |
+
+**Conclusion (test-cpu vs test-worker).** Both routes run the same CPU-bound workload (50k sqrt loop). `/test-cpu` runs it on the main thread and blocks the event loop (~25k req/s, ~199 ms). `/test-worker` offloads the work to a worker pool (~69k req/s, ~72 ms). For CPU-bound tasks, using the worker yields roughly 2.8× higher throughput and ~2.8× lower latency because the main thread stays free to accept and dispatch requests.
+
+## Test Behavior (baseline)
+
+- **Method:** GET
+- **Route:** `/test`
+- **Response:** `{ "hello": "world!" }` (JSON)
+- **File-based routing:** `benchmark/routes/test.ts` → pattern `/test`
+- **API:** `Context` + `ctx.send.json()`

benchmark/main-worker.ts

@@ -0,0 +1,24 @@
+import { Router } from '@app/index.ts'
+
+const workerCode = `
+const defaultIterations = 50000
+self.onmessage = (e) => {
+  const data = e.data || {}
+  const n = Math.max(0, Number(data.iterations) || defaultIterations)
+  let value = 0
+  for (let i = 0; i < n; i++) value += Math.sqrt(i)
+  self.postMessage({ done: true, value })
+}
+export {}
+`
+
+const workerScriptUrl = URL.createObjectURL(
+  new Blob([workerCode], { type: 'application/javascript' })
+)
+
+const router = new Router({
+  routesDir: 'benchmark/routes',
+  worker: { scriptURL: workerScriptUrl, poolSize: 4 }
+})
+
+await router.serve(8000)

benchmark/routes/test-cpu.ts

@@ -0,0 +1,9 @@
+import type { Context } from '@app/index.ts'
+
+export function GET(_ctx: Context) {
+  let value = 0
+  for (let i = 0; i < 50_000; i++) {
+    value += Math.sqrt(i)
+  }
+  return _ctx.send.json({ hello: 'cpu', value })
+}

benchmark/routes/test-worker.ts

@@ -0,0 +1,10 @@
+import type { Context } from '@app/index.ts'
+
+export async function GET(ctx: Context) {
+  const worker = ctx.state['worker'] as { run: <T>(p: unknown) => Promise<T> } | undefined
+  if (!worker?.run) {
+    return ctx.send.json({ error: 'worker not enabled' }, { status: 503 })
+  }
+  const result = await worker.run<{ done: boolean; value: number }>({ iterations: 50_000 })
+  return ctx.send.json({ hello: 'worker', value: result?.value })
+}

deno.json

@@ -58,7 +58,6 @@
   "lock": true,
   "nodeModulesDir": "auto",
   "tasks": {
-    "bench": "deno run --allow-net --allow-read benchmark/main.ts",
     "check": "deno fmt src/ && deno lint src/ && deno check src/",
     "test": "deno test tests/ --allow-read"
   },

docs/.vitepress/config.ts

@@ -76,7 +76,8 @@ export default withMermaid(
                   { text: 'File-based Routing', link: '/en/core-concepts/file-based-routing' },
                   { text: 'Route Patterns', link: '/en/core-concepts/route-patterns' },
                   { text: 'Context Object', link: '/en/core-concepts/context-object' },
-                  { text: 'Request Handling', link: '/en/core-concepts/request-handling' }
+                  { text: 'Request Handling', link: '/en/core-concepts/request-handling' },
+                  { text: 'Worker Pool', link: '/en/core-concepts/worker-pool' }
                 ]
               },
               {
@@ -149,7 +150,8 @@ export default withMermaid(
                   { text: 'File-based Routing', link: '/en/core-concepts/file-based-routing' },
                   { text: 'Route Patterns', link: '/en/core-concepts/route-patterns' },
                   { text: 'Context Object', link: '/en/core-concepts/context-object' },
-                  { text: 'Request Handling', link: '/en/core-concepts/request-handling' }
+                  { text: 'Request Handling', link: '/en/core-concepts/request-handling' },
+                  { text: 'Worker Pool', link: '/en/core-concepts/worker-pool' }
                 ]
               },
               {
@@ -274,7 +276,8 @@ export default withMermaid(
                   },
                   { text: 'Pola Rute', link: '/id/core-concepts/route-patterns' },
                   { text: 'Objek Konteks', link: '/id/core-concepts/context-object' },
-                  { text: 'Penanganan Request', link: '/id/core-concepts/request-handling' }
+                  { text: 'Penanganan Request', link: '/id/core-concepts/request-handling' },
+                  { text: 'Worker Pool', link: '/id/core-concepts/worker-pool' }
                 ]
               },
               {