bunqueue 2.8.37 → 2.8.39

package/README.md

@@ -19,24 +19,13 @@
 
 <p align="center">
   <a href="https://bunqueue.dev/">Documentation</a> &middot;
+  <a href="https://bunqueue.dev/guide/quickstart/">Quick Start</a> &middot;
   <a href="https://bunqueue.dev/guide/benchmarks/">Benchmarks</a> &middot;
   <a href="https://www.npmjs.com/package/bunqueue">npm</a>
 </p>
 
 ---
 
-## Requirements
-
-The bunqueue **server** (and the embedded mode) is **Bun-only** (`bun >= 1.3.9`):
-persistence and transport rely on Bun's runtime APIs. Install Bun from
-[bun.sh](https://bun.sh) and run with `bun`. Importing the `bunqueue` package from
-Node fails fast with a clear error rather than a cryptic resolver crash.
-
-**Your producers and workers don't have to run on Bun.** Official client SDKs
-connect to the server from **Node.js, Deno, Cloudflare Workers**
-([`bunqueue-client`](https://www.npmjs.com/package/bunqueue-client) on npm) and
-**Python** (`bunqueue-client`, PyPI coming soon) — see [One Queue, Any Language](#one-queue-any-language-sdks).
-
 ## Quickstart
 
 ```bash
@@ -48,6 +37,7 @@ import { Bunqueue } from 'bunqueue/client';
 
 const app = new Bunqueue('emails', {
   embedded: true,
+  dataPath: './data/emails.db', // omit to run in-memory (lost on restart)
   processor: async (job) => {
     console.log(`Sending to ${job.data.to}`);
     return { sent: true };
@@ -57,458 +47,190 @@ const app = new Bunqueue('emails', {
 await app.add('send', { to: 'alice@example.com' });
 ```
 
-That's it. Queue + Worker in one object. No Redis, no config, no setup.
-
----
-
-## 🪶 Featherweight install
+That's it. Queue + Worker in one object, persisted to a single SQLite file.
+No Redis, no config, no setup. The install is 5.5 MB, 7 packages, 2 runtime
+dependencies (`croner` + `msgpackr`) — SQLite, S3, HTTP and WebSocket are Bun
+built-ins.
 
-`bun add bunqueue` pulls **7 packages and 5.5 MB** — and that includes the binary
-queue server, the CLI, and the MCP server. Most queue libraries pull a Redis
-client and its dependency tree before you've queued a single job.
-
-| | Before (2.7.x) | Now | |
-| --- | --- | --- | --- |
-| **`node_modules`** | 93 MB | **5.5 MB** | **−94%** |
-| **packages** | 117 | **7** | **−110** |
-| **cold install** | ~6 s | **~1.7 s** | **~3.5× faster** |
-
-Just **2 runtime dependencies** (`croner` + `msgpackr`). SQLite, S3, HTTP and
-WebSocket are all Bun built-ins. The MCP SDK is an optional peer dependency —
-queue users never download it. ([details →](https://bunqueue.dev/changelog/))
-
----
-
-## Simple Mode
+### Not on Bun? Run the server, connect from anywhere
 
-Simple Mode gives you a Queue and a Worker in a single object. Add jobs, process them, add middleware, schedule crons — all from one place.
+The queue also runs as a standalone server — one command, nothing else to
+operate:
 
-Use `Bunqueue` when producer and consumer are in the same process. For distributed systems, use `Queue` + `Worker` separately. For AI agent workflows, use the [MCP Server](#built-for-ai-agents-mcp-server) instead — agents control queues via natural language without writing code.
-
-<details>
-<summary><b>Architecture</b></summary>
-
-```
-new Bunqueue('emails', opts)
-    │
-    ├── this.queue  = new Queue('emails', ...)
-    ├── this.worker = new Worker('emails', ...)
-    │
-    └── Subsystems (all optional):
-        ├── RetryEngine         ── jitter, fibonacci, exponential, custom
-        ├── CircuitBreaker      ── pauses worker after N failures
-        ├── BatchAccumulator    ── groups N jobs into one call
-        ├── TriggerManager      ── "on complete → create job B"
-        ├── TtlChecker          ── rejects expired jobs
-        ├── PriorityAger        ── boosts old jobs' priority
-        ├── CancellationManager ── AbortController per job
-        └── DedupDebounceMerger ── deduplication & debounce
-```
-
-Processing pipeline per job:
+```bash
+# in-memory without --data-path; pass it to persist jobs to SQLite
+bunx bunqueue start --data-path ./data/bunq.db   # TCP :6789, HTTP :6790
 
+# or, with no runtime at all (the volume persists /app/data):
+docker run -d -p 6789:6789 -p 6790:6790 \
+  -v bunqueue-data:/app/data \
+  ghcr.io/egeominotti/bunqueue:latest
 ```
-Job → Circuit Breaker → TTL check → AbortController → Retry → Middleware → Processor
-```
-
-</details>
 
-### Routes
+Then produce and process from the language you already use:
 
-Route jobs to different handlers by name:
-
-```typescript
-const app = new Bunqueue('notifications', {
-  embedded: true,
-  routes: {
-    'send-email': async (job) => {
-      await sendEmail(job.data.to);
-      return { channel: 'email' };
-    },
-    'send-sms': async (job) => {
-      await sendSMS(job.data.to);
-      return { channel: 'sms' };
-    },
-  },
-});
-
-await app.add('send-email', { to: 'alice' });
-await app.add('send-sms', { to: 'bob' });
+```bash
+npm install bunqueue-client    # Node.js ≥ 20, Deno ≥ 2, Bun, Cloudflare Workers
 ```
 
-> **Note:** Use one of `processor`, `routes`, or `batch`. Passing multiple or none throws an error.
-
-### Middleware
-
-Wraps every job execution. Execution order is onion-style: `mw1 → mw2 → processor → mw2 → mw1`. When no middleware is added, zero overhead.
-
 ```typescript
-// Timing middleware
-app.use(async (job, next) => {
-  const start = Date.now();
-  const result = await next();
-  console.log(`${job.name}: ${Date.now() - start}ms`);
-  return result;
-});
-
-// Error recovery middleware
-app.use(async (job, next) => {
-  try {
-    return await next();
-  } catch (err) {
-    return { recovered: true, error: err.message };
-  }
-});
-```
-
-### Batch Processing
+import { Queue, Worker } from 'bunqueue-client';
 
-Accumulates N jobs and processes them together. Flushes when buffer reaches `size` or `timeout` expires. On `close()`, remaining jobs are flushed.
+const queue = new Queue('emails');                       // localhost:6789 by default
+await queue.add('welcome', { to: 'user@example.com' });
 
-```typescript
-const app = new Bunqueue('db-inserts', {
-  embedded: true,
-  batch: {
-    size: 50,
-    timeout: 2000,
-    processor: async (jobs) => {
-      const rows = jobs.map(j => j.data.row);
-      await db.insertMany('table', rows);
-      return jobs.map(() => ({ inserted: true }));
-    },
-  },
-});
+new Worker('emails', async (job) => ({ sent: true }), { concurrency: 10 });
 ```
 
-### Advanced Retry
+Python, PHP, Go, Rust and Elixir clients speak the same protocol — see
+[One Queue, Any Language](#one-queue-any-language-sdks).
 
-5 strategies + retry predicate:
+> Only the server and embedded mode are **Bun-only** (`bun >= 1.3.9`,
+> [bun.sh](https://bun.sh)); producers and workers can run anywhere.
 
-```typescript
-const app = new Bunqueue('api-calls', {
-  embedded: true,
-  processor: async (job) => {
-    const res = await fetch(job.data.url);
-    if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    return { status: res.status };
-  },
-  retry: {
-    maxAttempts: 5,
-    delay: 1000,
-    strategy: 'jitter',
-    retryIf: (error) => error.message.includes('503'),
-  },
-});
-```
+[Quick Start guide →](https://bunqueue.dev/guide/quickstart/)
 
-| Strategy | Formula | Use case |
-| --- | --- | --- |
-| `fixed` | `delay` every time | Rate-limited APIs |
-| `exponential` | `delay × 2^attempt` | General purpose |
-| `jitter` | `delay × 2^attempt × random(0.5-1.0)` | Thundering herd prevention |
-| `fibonacci` | `delay × fib(attempt)` | Gradual backoff |
-| `custom` | `customBackoff(attempt, error) → ms` | Anything |
+## Why bunqueue?
 
-> This is in-process retry — the job stays active. Different from core `attempts`/`backoff` which re-queues.
+| Library      | Requires    | AI-native |
+| ------------ | ----------- | --------- |
+| BullMQ       | Redis       | No        |
+| Agenda       | MongoDB     | No        |
+| pg-boss      | PostgreSQL  | No        |
+| **bunqueue** | **Nothing** | **Yes**   |
 
-### Graceful Cancellation
+- **Zero external infrastructure** — one process, one SQLite file. `cp` to back up
+- **BullMQ-compatible API** — same `Queue`, `Worker`, `QueueEvents`; [migrating takes minutes](https://bunqueue.dev/guide/migration/)
+- **MCP server included** — 73 tools; AI agents get full queue control out of the box
+- **Everything server-side** — retries with backoff, priorities, cron, rate limits, dead letter queue
+- **Up to 630K ops/sec** — [verified benchmarks](https://bunqueue.dev/guide/benchmarks/) with methodology
 
-Cancel running jobs with AbortController:
+**Great for:** single-server deployments, AI agents that need a scheduler,
+prototypes and MVPs, embedded use cases (CLI tools, edge, serverless), teams
+that don't want to operate Redis.
 
-```typescript
-const app = new Bunqueue('encoding', {
-  embedded: true,
-  processor: async (job) => {
-    const signal = app.getSignal(job.id);
-    for (const chunk of chunks) {
-      if (signal?.aborted) throw new Error('Cancelled');
-      await encode(chunk);
-    }
-    return { done: true };
-  },
-});
+**Not ideal for:** multi-region distributed systems requiring HA or automatic
+failover today. If you already run Redis and BullMQ works for you, keep it.
 
-const job = await app.add('video', { file: 'big.mp4' });
-app.cancel(job.id);        // cancel immediately
-app.cancel(job.id, 5000);  // cancel after 5s grace period
-```
+[When to choose bunqueue →](https://bunqueue.dev/guide/comparison/)
 
-The signal works with `fetch` too: `await fetch(url, { signal })`.
+## Two Modes
 
-### Circuit Breaker
+|                  | Embedded                              | Server (TCP)                                 |
+| ---------------- | ------------------------------------- | -------------------------------------------- |
+| **How it works** | Queue runs inside your process        | Standalone server, clients connect via TCP   |
+| **Setup**        | `bun add bunqueue`                    | `docker run` or `bunqueue start`             |
+| **Performance**  | 630K ops/sec (bulk push)              | 90K ops/sec (push)                           |
+| **Best for**     | Single-process apps, CLIs, serverless | Multiple workers, separate producer/consumer |
+| **Scaling**      | Same process only                     | Multiple clients across machines             |
 
-Pauses the worker after too many consecutive failures:
+### Embedded
 
-```
-CLOSED ──→ failures ≥ threshold ──→ OPEN (worker paused)
-                                       │
-              ←── success ──── HALF-OPEN ←── timeout expires
-```
+Everything in your process. Without a data path the queue is in-memory: pass
+`dataPath` (or set `BUNQUEUE_DATA_PATH`) to persist jobs.
 
 ```typescript
-const app = new Bunqueue('payments', {
-  embedded: true,
-  processor: async (job) => paymentGateway.charge(job.data),
-  circuitBreaker: {
-    threshold: 5,
-    resetTimeout: 30000,
-    onOpen: () => alert('Gateway down!'),
-    onClose: () => alert('Gateway recovered'),
-  },
-});
-
-app.getCircuitState();  // 'closed' | 'open' | 'half-open'
-app.resetCircuit();     // force close + resume worker
-```
-
-### Event Triggers
+import { Queue, Worker } from 'bunqueue/client';
 
-Create follow-up jobs automatically when a job completes or fails:
+const queue = new Queue('emails', { embedded: true, dataPath: './data/app.db' });
 
-```typescript
-const app = new Bunqueue('orders', {
-  embedded: true,
-  routes: {
-    'place-order': async (job) => ({ orderId: job.data.id, total: 99 }),
-    'send-receipt': async (job) => ({ sent: true }),
-    'fraud-alert': async (job) => ({ alerted: true }),
+const worker = new Worker(
+  'emails',
+  async (job) => {
+    return { sent: true };
   },
-});
-
-app.trigger({
-  on: 'place-order',
-  create: 'send-receipt',
-  data: (result, job) => ({ id: job.data.id }),
-});
-
-// Conditional trigger (only for large orders)
-app.trigger({
-  on: 'place-order',
-  create: 'fraud-alert',
-  data: (result) => ({ amount: result.total }),
-  condition: (result) => result.total > 1000,
-});
+  { embedded: true }
+);
 
-// Chain triggers
-app
-  .trigger({ on: 'step-1', create: 'step-2', data: (r) => r })
-  .trigger({ on: 'step-2', create: 'step-3', data: (r) => r });
+await queue.add('welcome', { to: 'user@example.com' });
 ```
 
-### Job TTL
-
-Expire unprocessed jobs. Checked when the worker picks up the job:
-
-```typescript
-const app = new Bunqueue('otp', {
-  embedded: true,
-  processor: async (job) => verifyOTP(job.data.code),
-  ttl: {
-    defaultTtl: 300000,
-    perName: {
-      'verify-otp': 60000,
-      'daily-report': 0,
-    },
-  },
-});
+### Server (TCP)
 
-app.setDefaultTtl(120000);
-app.setNameTtl('flash-sale', 30000);
+```bash
+docker run -d -p 6789:6789 -p 6790:6790 \
+  -v bunqueue-data:/app/data \
+  ghcr.io/egeominotti/bunqueue:latest
 ```
 
-Resolution: `perName[job.name]` → `defaultTtl` → `0` (no TTL).
-
-### Priority Aging
-
-Automatically boosts priority of old waiting jobs to prevent starvation:
-
 ```typescript
-const app = new Bunqueue('tasks', {
-  embedded: true,
-  processor: async (job) => ({ done: true }),
-  priorityAging: {
-    interval: 60000,
-    minAge: 300000,
-    boost: 2,
-    maxPriority: 100,
-    maxScan: 200,
-  },
-});
-```
-
-A job with priority 1 becomes eligible after 5 min, then gains +2 on every 60s tick: 3, 5, 7, … capped at 100.
-
-### Deduplication
+import { Queue, Worker } from 'bunqueue/client';
 
-Prevent duplicate jobs. Jobs with the same name + data get the same dedup ID:
+const queue = new Queue('tasks', { connection: { host: 'localhost', port: 6789 } });
 
-```typescript
-const app = new Bunqueue('webhooks', {
-  embedded: true,
-  processor: async (job) => processWebhook(job.data),
-  deduplication: {
-    ttl: 60000,
-    extend: false,
-    replace: false,
+const worker = new Worker(
+  'tasks',
+  async (job) => {
+    return { done: true };
   },
-});
-
-await app.add('hook', { event: 'user.created', userId: '123' });
-await app.add('hook', { event: 'user.created', userId: '123' }); // deduplicated!
-await app.add('hook', { event: 'user.updated', userId: '123' }); // different data → new job
-```
-
-Override per-job: `await app.add('task', data, { deduplication: { id: 'my-id', ttl: 5000 } })`.
-
-### Debouncing
-
-Attach a default debounce id to same-name jobs. Each job gets `debounce: { id: jobName, ttl }` unless the per-job options already set one:
-
-```typescript
-const app = new Bunqueue('search', {
-  embedded: true,
-  processor: async (job) => executeSearch(job.data.query),
-  debounce: { ttl: 500 },
-});
-
-await app.add('search', { query: 'h' });
-await app.add('search', { query: 'he' });
-await app.add('search', { query: 'hello' });  // all three share the debounce id 'search'
-```
-
-The debounce id and TTL are stored on the job (BullMQ v5 compatible metadata, visible via `job.opts.debounce`), but they do not suppress duplicates by themselves in the current engine. To actually coalesce rapid duplicates, use [Deduplication](#deduplication) with `replace: true`: a duplicate arriving within the TTL window replaces the pending job, giving last-write-wins semantics.
-
-### Rate Limiting
-
-```typescript
-const app = new Bunqueue('api', {
-  embedded: true,
-  processor: async (job) => callExternalAPI(job.data),
-  rateLimit: { max: 100, duration: 1000 },
-});
+  { connection: { host: 'localhost', port: 6789 } }
+);
 
-// Per-group cap (e.g., per customer): with groupKey set, max limits
-// concurrently active jobs per group (duration is not applied in this mode)
-const app2 = new Bunqueue('api', {
-  embedded: true,
-  processor: async (job) => callAPI(job.data),
-  rateLimit: { max: 10, duration: 1000, groupKey: 'customerId' },
-});
+await queue.add('process', { data: 'hello' });
 ```
 
-### DLQ (Dead Letter Queue)
+[Running the server →](https://bunqueue.dev/guide/server/) ·
+[Deployment guide →](https://bunqueue.dev/guide/deployment/)
 
-```typescript
-const app = new Bunqueue('critical', {
-  embedded: true,
-  processor: async (job) => riskyOperation(job.data),
-  dlq: {
-    autoRetry: true,
-    autoRetryInterval: 3600000,
-    maxAutoRetries: 3,
-    maxAge: 604800000,
-    maxEntries: 10000,
-  },
-});
-
-app.getDlq();                        // all entries
-app.getDlqStats();                   // { total, byReason, ... }
-app.getDlq({ reason: 'timeout' });   // filter by reason
-app.retryDlq();                      // retry all
-app.purgeDlq();                      // clear all
-```
+## One Queue, Any Language (SDKs)
 
-Failure reasons: `explicit_fail`, `max_attempts_exceeded`, `timeout`, `stalled`, `ttl_expired`, `worker_lost`, `unknown`.
+The server does all the heavy lifting. Official client SDKs speak the native
+TCP protocol with full feature parity, so producers and workers can live
+anywhere in your stack — add a job from TypeScript, process it from Python:
 
-### Cron Jobs
+| Where your code runs | Install |
+| -------------------- | ------- |
+| **Node.js ≥ 20, Deno ≥ 2, Bun, Cloudflare Workers** | [`npm install bunqueue-client`](https://www.npmjs.com/package/bunqueue-client) |
+| **Python ≥ 3.9** | PyPI coming soon — today: `pip install "git+https://github.com/egeominotti/bunqueue.git#subdirectory=sdk/python"` |
+| **PHP ≥ 8.1** | Packagist coming soon — today: use [`sdk/php`](./sdk/php) |
+| **Go ≥ 1.26.5** | `go get github.com/egeominotti/bunqueue/sdk/go` |
+| **Rust ≥ 1.85** | crates.io coming soon — today: use [`sdk/rust`](./sdk/rust) as a path dependency |
+| **Elixir ≥ 1.15** | Hex coming soon — today: use [`sdk/elixir`](./sdk/elixir) as a path dependency |
 
 ```typescript
-await app.cron('daily-report', '0 9 * * *', { type: 'report' });
-await app.cron('eu-digest', '0 8 * * 1', { type: 'weekly' }, { timezone: 'Europe/Rome' });
-await app.every('healthcheck', 30000, { type: 'ping' });
-
-await app.listCrons();
-await app.removeCron('healthcheck');
-```
+// Node.js / Deno / Cloudflare Workers
+import { Queue, Worker } from 'bunqueue-client';
 
-### Events
+const queue = new Queue('emails', { host: 'localhost', port: 6789 });
+await queue.add('welcome', { to: 'user@example.com' });
 
-```typescript
-app.on('completed', (job, result) => { });
-app.on('failed', (job, error) => { });
-app.on('active', (job) => { });
-app.on('progress', (job, progress) => { });
-app.on('stalled', (jobId, reason) => { });
-app.on('error', (error) => { });
-app.on('ready', () => { });
-app.on('drained', () => { });
-app.on('closed', () => { });
+new Worker('emails', async (job) => ({ sent: true }), { concurrency: 10 });
 ```
 
-### Adding Jobs
-
-```typescript
-await app.add('task', { key: 'value' });
-await app.add('urgent', data, { priority: 10, delay: 5000, attempts: 5, durable: true });
-await app.addBulk([
-  { name: 'email', data: { to: 'alice' } },
-  { name: 'email', data: { to: 'bob' }, opts: { priority: 10 } },
-]);
-```
+```python
+# Python
+from bunqueue import Queue, Worker
 
-### Control
+queue = Queue("emails", host="localhost", port=6789)
+queue.add("welcome", {"to": "user@example.com"})
 
-```typescript
-app.pause();           // pause queue + worker
-app.resume();          // resume both
-await app.close();     // graceful shutdown
-await app.close(true); // force shutdown
+Worker("emails", lambda job: {"sent": True}, concurrency=10).run()
 ```
 
-### Inspecting jobs & counts
+Every SDK is certified against the same public
+[wire protocol](https://github.com/egeominotti/bunqueue/blob/main/docs/protocol.md) and conformance suite.
 
-`getJobCounts()` and the per-state lists follow BullMQ semantics:
+[SDK guide (all six languages) →](https://bunqueue.dev/guide/sdks/)
 
-```typescript
-const counts = await queue.getJobCountsAsync();
-// { waiting, prioritized, active, completed, failed, delayed,
-//   'waiting-children', paused }
-
-// Failed jobs (those that exhausted their attempts) are enumerable by state —
-// the failed list reflects the same jobs that `failed` counts.
-const failed = await queue.getFailedAsync(0, 50);
-const alsoFailed = await queue.getJobsAsync({ state: 'failed', start: 0, end: 50 });
-
-// Paused queue: ready jobs are reported under `paused`, never double-counted as
-// `waiting`. While paused, getJobCounts() returns waiting:0 / paused:N, and the
-// jobs are listed by `getJobsAsync({ state: 'paused' })` (not by `waiting`).
-queue.pause();
-const c = await queue.getJobCountsAsync(); // waiting: 0, paused: N
-const pausedJobs = await queue.getJobsAsync({ state: 'paused', start: 0, end: 50 });
-```
+## Simple Mode
 
-### Full Example
+`Bunqueue` bundles Queue + Worker + routes + middleware + cron in one object:
 
 ```typescript
-import { Bunqueue, shutdownManager } from 'bunqueue/client';
+import { Bunqueue } from 'bunqueue/client';
 
-const app = new Bunqueue<{ payload: string }>('my-app', {
+const app = new Bunqueue('notifications', {
   embedded: true,
   routes: {
-    'process': async (job) => ({ id: job.data.payload, status: 'done' }),
-    'notify': async (job) => ({ sent: true }),
-    'alert': async (job) => ({ alerted: true }),
+    'send-email': async (job) => ({ sent: true }),
+    'send-sms': async (job) => ({ sent: true }),
   },
   concurrency: 10,
-  retry: { maxAttempts: 3, delay: 1000, strategy: 'jitter' },
+  retry: { maxAttempts: 5, strategy: 'jitter' },
   circuitBreaker: { threshold: 5, resetTimeout: 30000 },
-  ttl: { defaultTtl: 600000, perName: { 'verify-otp': 60000 } },
-  priorityAging: { interval: 60000, minAge: 300000, boost: 1 },
-  deduplication: { ttl: 5000 },
-  rateLimit: { max: 100, duration: 1000 },
-  dlq: { autoRetry: true, maxAge: 604800000 },
 });
 
+// Onion middleware around every job
 app.use(async (job, next) => {
   const start = Date.now();
   const result = await next();
@@ -516,79 +238,50 @@ app.use(async (job, next) => {
   return result;
 });
 
-app
-  .trigger({ on: 'process', create: 'notify', data: (r) => ({ payload: r.id }) })
-  .trigger({ on: 'process', event: 'failed', create: 'alert', data: (_, j) => j.data });
-
-await app.cron('cleanup', '0 2 * * *', { payload: 'nightly' });
-await app.add('process', { payload: 'ORD-001' });
+await app.cron('daily-report', '0 9 * * *', { type: 'summary' });
+await app.add('send-email', { to: 'alice@example.com' });
 
-process.on('SIGINT', async () => {
-  await app.close();
-  shutdownManager();
-});
+app.on('completed', (job, result) => console.log(result));
+await app.close();
 ```
 
-[Simple Mode docs →](https://bunqueue.dev/guide/simple-mode/)
+Also included: batch processing, event triggers (job A completes → create job
+B), job TTL, priority aging, deduplication, per-group rate limiting, DLQ with
+auto-retry, graceful cancellation via `AbortController`.
 
----
+[Simple Mode reference →](https://bunqueue.dev/guide/simple-mode/)
 
 ## Workflow Engine
 
-Orchestrate multi-step business processes with branching, saga compensation, and human-in-the-loop signals. Built on top of bunqueue — no new infrastructure.
+Multi-step orchestration with saga compensation, branching, parallel steps and
+human-in-the-loop signals — built on bunqueue, no new infrastructure:
 
 ```typescript
 import { Workflow, Engine } from 'bunqueue/workflow';
 
 const orderFlow = new Workflow('order-pipeline')
-  .step('validate', async (ctx) => {
-    const { orderId, amount } = ctx.input as { orderId: string; amount: number };
-    if (amount <= 0) throw new Error('Invalid amount');
-    return { orderId };
-  })
   .step('reserve-stock', async () => {
     await inventory.reserve();
     return { reserved: true };
   }, {
-    compensate: async () => await inventory.release(), // Auto-rollback on failure
+    compensate: async () => await inventory.release(), // auto-rollback on failure
   })
   .step('charge', async () => {
     return { txId: await payments.charge() };
   }, {
     compensate: async () => await payments.refund(),
   })
+  .waitFor('manager-approval', { timeout: 86_400_000 }) // human-in-the-loop
   .step('confirm', async (ctx) => {
-    const { txId } = ctx.steps['charge'] as { txId: string };
-    return { emailSent: true, txId };
+    return { txId: (ctx.steps['charge'] as { txId: string }).txId };
   });
 
 const engine = new Engine({ embedded: true });
 engine.register(orderFlow);
-await engine.start('order-pipeline', { orderId: 'ORD-1', amount: 99.99 });
+const run = await engine.start('order-pipeline', { orderId: 'ORD-1' });
+await engine.signal(run.id, 'manager-approval', { approved: true });
 ```
 
-**Features:**
-
-- **Saga pattern** — Compensation handlers run in reverse when a step fails
-- **Branching** — Route to different paths based on runtime conditions
-- **Parallel steps** — Run independent steps concurrently with `.parallel()`
-- **Human-in-the-loop** — `waitFor('event')` pauses execution, `engine.signal()` resumes it
-- **Signal timeout** — `waitFor('event', { timeout })` fails if signal doesn't arrive in time
-- **Step retry** — Automatic retry with exponential backoff and jitter
-- **Nested workflows** — Compose workflows with `.subWorkflow()`, child results passed back
-- **Loops** — `doUntil()` and `doWhile()` for conditional iteration with safety limits
-- **forEach** — Iterate over dynamic item lists with indexed step results (`step:0`, `step:1`, ...)
-- **Map** — Synchronous data transforms between steps with `.map()`
-- **Schema validation** — Validate step input/output with Zod, ArkType, Valibot, or any `.parse()` schema
-- **Subscribe** — `engine.subscribe(id, callback)` to monitor a specific execution's events
-- **Observability** — Typed event emitter with 11 event types (`engine.on/onAny`)
-- **Cleanup & archival** — `engine.cleanup()` / `engine.archive()` for execution history management
-- **Step timeouts** — Prevent steps from running indefinitely
-- **Context passing** — Each step accesses input and all previous step results
-- **SQLite persistence** — Execution state survives restarts
-
-**vs Competitors:**
-
 | | **bunqueue** | **Temporal** | **Inngest** | **Trigger.dev** |
 |---|---|---|---|---|
 | **Infrastructure** | None (embedded) | PostgreSQL + 7 services | Cloud-only | Redis + PostgreSQL |
@@ -597,111 +290,26 @@ await engine.start('order-pipeline', { orderId: 'ORD-1', amount: 99.99 });
 | **Self-hosted** | Zero-config | Complex | No | Complex |
 | **Pricing** | Free (MIT) | Free / Cloud $$ | Per-execution | Free tier, then $50/mo+ |
 
-```typescript
-// Branching
-const flow = new Workflow('tiered')
-  .step('classify', async (ctx) => {
-    const { amount } = ctx.input as { amount: number };
-    return { tier: amount > 1000 ? 'vip' : 'basic' };
-  })
-  .branch((ctx) => (ctx.steps['classify'] as { tier: string }).tier)
-  .path('vip', (w) => w.step('vip-handler', async () => ({ discount: 20 })))
-  .path('basic', (w) => w.step('basic-handler', async () => ({ discount: 0 })))
-  .step('done', async () => ({ processed: true }));
-
-// Human-in-the-loop
-const approvalFlow = new Workflow('expense')
-  .step('submit', async (ctx) => {
-    const { amount } = ctx.input as { amount: number };
-    return { amount };
-  })
-  .waitFor('manager-approval')
-  .step('reimburse', async (ctx) => {
-    const decision = ctx.signals['manager-approval'] as { approved: boolean };
-    return { status: decision.approved ? 'paid' : 'rejected' };
-  });
-
-// Signal a waiting workflow
-await engine.signal(run.id, 'manager-approval', { approved: true });
-```
-
-[Workflow Engine docs →](https://bunqueue.dev/guide/workflow/)
-
----
-
-<p align="center">
-  <strong>bunqueue Dashboard</strong><br/>
-  <sub>A web dashboard that fully drives your bunqueue server &mdash; queues, jobs, DLQ, cron, webhooks, workers, live activity, SQLite inspector, and an AI Copilot. Open source, currently in beta. Requires Bun.</sub>
-</p>
-
-https://github.com/user-attachments/assets/e8a8d38e-b4a6-4dc8-8360-876c0f24d116
-
-```bash
-bunx bunqueue-dashboard
-```
-
-<p align="center">
-  <sub>
-    <a href="https://egeominotti.github.io/bunqueue-dashboard/">Live demo</a> &middot;
-    <a href="https://egeominotti.github.io/bunqueue-dashboard/docs/user-guide">User guide</a> &middot;
-    <a href="https://github.com/egeominotti/bunqueue-dashboard">GitHub</a> &middot;
-    <a href="https://www.npmjs.com/package/bunqueue-dashboard">npm: bunqueue-dashboard</a>
-  </sub>
-</p>
-
----
-
-## Why bunqueue?
-
-| Library      | Requires    | AI-native |
-| ------------ | ----------- | --------- |
-| BullMQ       | Redis       | No        |
-| Agenda       | MongoDB     | No        |
-| pg-boss      | PostgreSQL  | No        |
-| **bunqueue** | **Nothing** | **Yes**   |
+Also included: nested workflows, `doUntil`/`doWhile` loops, `forEach` over
+dynamic lists, schema validation (Zod, ArkType, Valibot or any `.parse()`),
+step timeouts, typed events, SQLite-persisted execution state.
 
-- **MCP server included** — 73 tools, 5 resources, 3 prompts. AI agents get full control out of the box
-- **BullMQ-compatible API** — Same `Queue`, `Worker`, `QueueEvents`
-- **Zero external infrastructure** — No Redis, no MongoDB
-- **Tiny footprint** — 5.5 MB installed, 7 packages (just 2 runtime deps: `croner` + `msgpackr`)
-- **SQLite persistence** — Survives restarts, WAL mode for concurrent access
-- **Up to 630K ops/sec** — [Verified benchmarks](https://bunqueue.dev/guide/benchmarks/)
+[Workflow Engine guide →](https://bunqueue.dev/guide/workflow/)
 
 ## Built for AI Agents (MCP Server)
 
-<p align="center">
-  <img src=".github/mcp-flow.svg" alt="HTTP Handler Flow: Cron/Add Job → Queue → Embedded Worker → HTTP API → Job Result" width="700" />
-</p>
-
-bunqueue is the **first job queue with native MCP support**. AI agents get a full-featured scheduler, task queue, and monitoring system — no glue code needed.
-
-**HTTP Handlers** solve a fundamental problem: an AI agent can schedule jobs and manage queues, but it cannot run a persistent worker. When the agent registers an HTTP handler, bunqueue spawns an embedded Worker that continuously pulls jobs and calls your HTTP endpoint. Responses are saved as results. Failed calls retry automatically via DLQ.
-
-**What AI agents can do with bunqueue:**
-
-- **Schedule tasks** — cron jobs, delayed execution, recurring workflows
-- **Manage job pipelines** — push jobs, monitor progress, retry failures
-- **Full pull/ack/fail cycle** — agents can consume and process jobs directly
-- **Monitor everything** — stats, memory, Prometheus metrics, logs, DLQ
-- **Control flow** — pause/resume queues, set rate limits, manage concurrency
-- **73 MCP tools + 5 resources + 3 prompts** — complete control over every feature
-- **HTTP handlers** — register a URL, bunqueue auto-processes jobs via HTTP calls
+bunqueue ships a native MCP server: 73 tools, 5 resources, 3 prompts. Agents
+schedule cron jobs, push and process jobs, retry failures, set rate limits,
+and read stats — no glue code. HTTP handlers let an agent register a URL and
+have an embedded worker call it for every job.
 
 ```bash
-# bunqueue-mcp is a binary bundled inside the bunqueue package (not a standalone npm package),
-# so install bunqueue first, then connect Claude Code:
-bun add bunqueue
-# Since v2.8.1 the MCP SDK is an optional peer dependency. Queue-only users skip it entirely:
-# a clean install drops from 93 MB / 117 packages to 5.5 MB / 7 packages (−94%, ~3.5× faster on a cold install).
-# bunx --package=bunqueue does NOT auto-install optional peers, so install the SDK once to run the MCP server:
-bun add @modelcontextprotocol/sdk
+bun add bunqueue @modelcontextprotocol/sdk   # the MCP SDK is an optional peer
 claude mcp add bunqueue -- bunx bunqueue-mcp
 ```
 
 ```json
-// Claude Desktop / Cursor / Windsurf — --package=bunqueue lets bunx resolve the bundled
-// bunqueue-mcp binary without a separate install (the @modelcontextprotocol/sdk optional
-// peer dependency must still be installed once: bun add @modelcontextprotocol/sdk):
+// Claude Desktop / Cursor / Windsurf
 {
   "mcpServers": {
     "bunqueue": {
@@ -712,246 +320,50 @@ claude mcp add bunqueue -- bunx bunqueue-mcp
 }
 ```
 
-**Example agent interactions:**
-
-- *"Schedule a cleanup job every day at 3 AM"*
-- *"Add 500 email jobs to the queue with priority 10"*
-- *"Show me all failed jobs and retry them"*
-- *"Set rate limit to 50/sec on the api-calls queue"*
-- *"What's the memory usage and queue throughput?"*
-
-**Plugin ecosystem** — bunqueue ships with auto-discovery (`.mcp.json`), a custom Claude Code agent for bunqueue tasks, and installable skills for setup, API reference, and real-world patterns. Drop bunqueue into any project and your AI tools discover it automatically.
-
-Supports **embedded** (local SQLite) and **TCP** (remote server) modes. [Full MCP documentation →](https://bunqueue.dev/guide/mcp/)
-
-## When to use bunqueue
-
-**Great for:**
-
-- **AI agents that need a scheduler** — cron jobs, delayed tasks, retries, all via MCP
-- **Agentic workflows** — agents push jobs, workers process, agents monitor results
-- Single-server deployments
-- Prototypes and MVPs
-- Moderate to high workloads (up to 630K ops/sec)
-- Teams that want to avoid Redis operational overhead
-- Embedded use cases (CLI tools, edge functions, serverless)
-
-**Not ideal for:**
-
-- Multi-region distributed systems requiring HA
-- Workloads that need automatic failover today
-- Systems already running Redis with existing infrastructure
-
-## Why not just use BullMQ?
-
-If you're already running Redis, BullMQ is great — battle-tested and feature-rich.
-
-bunqueue is for when you **don't want to run Redis**. SQLite with WAL mode handles surprisingly high throughput for single-node deployments (tested up to 630K ops/sec on bulk push). You get persistence, priorities, delays, retries, cron jobs, and DLQ — without the operational overhead of another service.
-
-## Install
-
-```bash
-bun add bunqueue
-```
-
-> The server and embedded mode require the [Bun](https://bun.sh) runtime. To
-> connect **clients** from Node.js, Deno, Cloudflare Workers or Python, use the
-> [SDKs](#one-queue-any-language-sdks) instead.
-
-## Two Modes
-
-bunqueue runs in two modes depending on your architecture:
-
-|                  | Embedded                              | Server (TCP)                                 |
-| ---------------- | ------------------------------------- | -------------------------------------------- |
-| **How it works** | Queue runs inside your process        | Standalone server, clients connect via TCP   |
-| **Setup**        | `bun add bunqueue`                    | `docker run` or `bunqueue start`             |
-| **Performance**  | 630K ops/sec (bulk push)              | 90K ops/sec (push)                           |
-| **Best for**     | Single-process apps, CLIs, serverless | Multiple workers, separate producer/consumer |
-| **Scaling**      | Same process only                     | Multiple clients across machines             |
-
-### Embedded Mode
-
-Everything runs in your process. No server, no network, no setup. Without a
-data path the queue is in-memory and lost on restart: pass
-`dataPath: './data/app.db'` (or set `BUNQUEUE_DATA_PATH`) to persist jobs.
-
-```typescript
-import { Queue, Worker } from 'bunqueue/client';
-
-const queue = new Queue('emails', { embedded: true });
-
-const worker = new Worker(
-  'emails',
-  async (job) => {
-    console.log('Processing:', job.data);
-    return { sent: true };
-  },
-  { embedded: true }
-);
+Then just ask: *"Schedule a cleanup job every day at 3 AM"* · *"Show me all
+failed jobs and retry them"* · *"Set rate limit to 50/sec on api-calls"*.
 
-await queue.add('welcome', { to: 'user@example.com' });
-```
+[MCP guide →](https://bunqueue.dev/guide/mcp/)
 
-### Server Mode (TCP)
+## Dashboard
 
-Run bunqueue as a standalone server. Multiple workers and producers connect via TCP.
+A web dashboard that fully drives your server — queues, jobs, DLQ, cron,
+webhooks, workers, live activity, SQLite inspector and an AI copilot. Open
+source, currently in beta:
 
 ```bash
-# Start with persistent data
-docker run -d -p 6789:6789 -p 6790:6790 \
-  -v bunqueue-data:/app/data \
-  ghcr.io/egeominotti/bunqueue:latest
-```
-
-Connect from your app:
-
-```typescript
-import { Queue, Worker } from 'bunqueue/client';
-
-const queue = new Queue('tasks', { connection: { host: 'localhost', port: 6789 } });
-
-const worker = new Worker(
-  'tasks',
-  async (job) => {
-    return { done: true };
-  },
-  { connection: { host: 'localhost', port: 6789 } }
-);
-
-await queue.add('process', { data: 'hello' });
-```
-
-## One Queue, Any Language (SDKs)
-
-The server does all the heavy lifting — retries, priorities, scheduling, DLQ.
-Official client SDKs speak the native TCP protocol (msgpack, pipelined) with
-full feature parity, so producers and workers can live anywhere in your stack:
-
-| Where your code runs | Install | Status |
-| -------------------- | ------- | ------ |
-| **Node.js ≥ 20, Deno ≥ 2, Bun, Cloudflare Workers** | [`npm install bunqueue-client`](https://www.npmjs.com/package/bunqueue-client) | Native integration/e2e + protocol conformance |
-| **Python ≥ 3.9** | PyPI coming soon — today: `pip install "git+https://github.com/egeominotti/bunqueue.git#subdirectory=sdk/python"` | Native integration/e2e + protocol conformance |
-| **PHP ≥ 8.1** | Packagist coming soon — today: use [`sdk/php`](./sdk/php) | Native e2e + protocol conformance |
-| **Go 1.26.5** | `go get github.com/egeominotti/bunqueue/sdk/go` | Native tests + protocol conformance |
-| **Rust ≥ 1.85** | crates.io coming soon — today: use [`sdk/rust`](./sdk/rust) as a path dependency | Native unit/integration + protocol conformance |
-| **Elixir ≥ 1.15** | Hex coming soon — today: use [`sdk/elixir`](./sdk/elixir) as a path dependency | ExUnit integration + protocol conformance |
-
-All six SDKs run the same production hardening matrix: independent-connection
-idempotency and single-lease races, generated payload invariants,
-malformed-input fuzz corpora, broker SIGKILL/reconnect durability, bounded
-spikes, structured telemetry, and 17 shared protocol checks. Weekly CI adds
-runtime compatibility, live dependency advisories, native Go race/fuzz checks,
-and a 15-minute sustained profile per SDK. See
-[`docs/testing.md`](./docs/testing.md#sdk-hardening-matrix).
-
-```typescript
-// Node.js / Deno / Cloudflare Workers
-import { Queue, Worker } from 'bunqueue-client';
-
-const queue = new Queue('emails', { host: 'localhost', port: 6789 });
-await queue.add('welcome', { to: 'user@example.com' });
-
-new Worker('emails', async (job) => ({ sent: true }), { concurrency: 10 });
-```
-
-```python
-# Python
-from bunqueue import Queue, Worker
-
-queue = Queue("emails", host="localhost", port=6789)
-queue.add("welcome", {"to": "user@example.com"})
-
-Worker("emails", lambda job: {"sent": True}, concurrency=10).run()
+bunx bunqueue-dashboard
 ```
 
-Mix and match: a Next.js API adds jobs, a Python service processes them.
-Docs: [bunqueue.dev/guide/sdks](https://bunqueue.dev/guide/sdks/) · Sources: [`sdk/`](./sdk/)
-
-### Simple Mode
-
-One object. Queue + Worker + Routes + Middleware + Cron. Zero boilerplate.
-
-```typescript
-import { Bunqueue } from 'bunqueue/client';
-
-const app = new Bunqueue('notifications', {
-  embedded: true,
-
-  // Route jobs by name
-  routes: {
-    'send-email': async (job) => {
-      console.log(`Email to ${job.data.to}`);
-      return { sent: true };
-    },
-    'send-sms': async (job) => {
-      console.log(`SMS to ${job.data.to}`);
-      return { sent: true };
-    },
-  },
-  concurrency: 10,
-});
-
-// Middleware — wraps every job (logging, timing, error recovery)
-app.use(async (job, next) => {
-  const start = Date.now();
-  const result = await next();
-  console.log(`${job.name} took ${Date.now() - start}ms`);
-  return result;
-});
-
-// Cron — scheduled jobs
-await app.cron('daily-report', '0 9 * * *', { type: 'summary' });
-await app.every('healthcheck', 30000, { type: 'ping' });
-
-// Events
-app.on('completed', (job, result) => console.log(result));
-app.on('failed', (job, err) => console.error(err));
-
-// Add jobs
-await app.add('send-email', { to: 'alice@example.com' });
-await app.add('send-sms', { to: '+1234567890' });
-
-// Graceful shutdown
-await app.close();
-```
+https://github.com/user-attachments/assets/e8a8d38e-b4a6-4dc8-8360-876c0f24d116
 
-Works with both embedded and TCP mode. [Simple Mode docs →](https://bunqueue.dev/guide/simple-mode/)
+[Live demo](https://egeominotti.github.io/bunqueue-dashboard/) ·
+[User guide](https://egeominotti.github.io/bunqueue-dashboard/docs/user-guide) ·
+[GitHub](https://github.com/egeominotti/bunqueue-dashboard)
 
 ## Performance
 
-SQLite handles surprisingly high throughput for single-node deployments:
-
-| Mode     | Peak Throughput | Use Case            |
-| -------- | --------------- | ------------------- |
+| Mode     | Peak Throughput          | Use Case            |
+| -------- | ------------------------ | ------------------- |
 | Embedded | 630K ops/sec (bulk push) | Same process        |
 | TCP      | 90K ops/sec (push)       | Distributed workers |
 
-> Run `bun run bench` to verify on your hardware. [Full benchmark methodology →](https://bunqueue.dev/guide/benchmarks/)
-
-## Monitoring
-
-```bash
-# Start with Prometheus + Grafana
-docker compose --profile monitoring up -d
-```
-
-- **Grafana**: http://localhost:3000 (admin/bunqueue)
-- **Prometheus**: http://localhost:9090
+Run `bun run bench` to verify on your hardware.
+[Benchmark methodology →](https://bunqueue.dev/guide/benchmarks/)
 
 ## Documentation
 
-**[Read the full documentation →](https://bunqueue.dev/)**
-
-- [Quick Start](https://bunqueue.dev/guide/quickstart/)
-- [Workflow Engine](https://bunqueue.dev/guide/workflow/)
-- [MCP Server (AI Agents)](https://bunqueue.dev/guide/mcp/)
-- [Simple Mode](https://bunqueue.dev/guide/simple-mode/)
-- [Queue API](https://bunqueue.dev/guide/queue/)
-- [Worker API](https://bunqueue.dev/guide/worker/)
-- [Server Mode](https://bunqueue.dev/guide/server/)
-- [Benchmarks](https://bunqueue.dev/guide/benchmarks/)
-- [CLI Reference](https://bunqueue.dev/guide/cli/)
+**[bunqueue.dev →](https://bunqueue.dev/)**
+
+- [Quick Start](https://bunqueue.dev/guide/quickstart/) — install to working queue in under a minute
+- [Queue API](https://bunqueue.dev/guide/queue/) · [Worker API](https://bunqueue.dev/guide/worker/) — every option explained
+- [Simple Mode](https://bunqueue.dev/guide/simple-mode/) — routes, middleware, triggers, TTL, dedup
+- [Workflow Engine](https://bunqueue.dev/guide/workflow/) — sagas, branching, signals
+- [SDKs](https://bunqueue.dev/guide/sdks/) — TypeScript, Python, PHP, Go, Rust, Elixir
+- [MCP Server](https://bunqueue.dev/guide/mcp/) — AI agent integration
+- [Server & Deployment](https://bunqueue.dev/guide/deployment/) — Docker, TLS, auth, monitoring
+- [CLI Reference](https://bunqueue.dev/guide/cli/) — run and manage from the terminal
+- [Migrate from BullMQ](https://bunqueue.dev/guide/migration/)
 
 ## License