bunqueue 1.2.2 → 1.3.1

package/README.md

@@ -10,254 +10,241 @@
 
 <p align="center">
   <a href="#features">Features</a> •
-  <a href="#sdk">SDK</a> •
   <a href="#quick-start">Quick Start</a> •
-  <a href="#installation">Installation</a> •
+  <a href="#embedded-mode">Embedded</a> •
+  <a href="#server-mode">Server</a> •
   <a href="#api-reference">API</a> •
   <a href="#docker">Docker</a>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/bunqueue"><img src="https://img.shields.io/npm/v/bunqueue?label=bunqueue" alt="bunqueue npm"></a>
-  <a href="https://www.npmjs.com/package/flashq"><img src="https://img.shields.io/npm/v/flashq?label=flashq" alt="flashq npm"></a>
-  <a href="https://www.npmjs.com/package/flashq"><img src="https://img.shields.io/npm/dm/flashq" alt="npm downloads"></a>
+  <a href="https://www.npmjs.com/package/bunqueue"><img src="https://img.shields.io/npm/dm/bunqueue" alt="npm downloads"></a>
 </p>
 
 ---
 
-## Quick Install
+## Why bunqueue?
 
-bunqueue requires two packages: the **server** and the **SDK**.
+> ⚠️ **Bun only** — bunqueue requires [Bun](https://bun.sh) runtime. Node.js is not supported.
 
-```bash
-# Install both packages
-bun add bunqueue flashq
-```
+**Every other job queue requires external infrastructure.** bunqueue doesn't.
 
-| Package | Description |
-|---------|-------------|
-| [bunqueue](https://www.npmjs.com/package/bunqueue) | Job queue server |
-| [flashq](https://www.npmjs.com/package/flashq) | TypeScript SDK for clients |
+| Library | Requires |
+|---------|----------|
+| BullMQ | ❌ Redis |
+| Agenda | ❌ MongoDB |
+| Bee-Queue | ❌ Redis |
+| pg-boss | ❌ PostgreSQL |
+| Celery | ❌ Redis/RabbitMQ |
+| **bunqueue** | ✅ **Nothing. Zero. Nada.** |
 
-### Start Server
+bunqueue is the **only** job queue with:
+- **BullMQ-compatible API** — Same `Queue`, `Worker`, `QueueEvents` you know
+- **Zero external dependencies** — No Redis, no MongoDB, no nothing
+- **Persistent storage** — SQLite survives restarts, no data loss
+- **100K+ jobs/sec** — Faster than Redis-based queues
+- **Single file deployment** — Just your app, that's it
 
 ```bash
-# Option 1: Run via npx (recommended)
-npx bunqueue
+# Others: Install Redis, configure connection, manage infrastructure...
+# bunqueue:
+bun add bunqueue
+```
 
-# Option 2: Run via bun
-bunx bunqueue
+```typescript
+import { Queue, Worker } from 'bunqueue/client';
+// That's it. You're done. Start queuing.
+```
 
-# Option 3: Run locally after install
-./node_modules/.bin/bunqueue
+---
 
-# Option 4: Global install
-bun add -g bunqueue
-bunqueue
+## Quick Install
 
-# Option 5: Docker
-docker run -p 6789:6789 -p 6790:6790 ghcr.io/egeominotti/bunqueue
+```bash
+# Requires Bun runtime (https://bun.sh)
+bun add bunqueue
 ```
 
-<img src=".github/terminal.png" alt="bunqueue server running" width="600" />
+bunqueue works in **two modes**:
 
-### Production Setup
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| **Embedded** | In-process, no server needed | Monolith, scripts, serverless |
+| **Server** | Standalone TCP/HTTP server | Microservices, multi-process |
 
-For production, enable **persistence** and **authentication**:
+---
 
-```bash
-# With environment variables
-DATA_PATH=./data/bunqueue.db AUTH_TOKENS=your-secret-token bunqueue
+## Quick Start
 
-# Or with custom ports
-TCP_PORT=6789 HTTP_PORT=6790 DATA_PATH=./data/bunqueue.db AUTH_TOKENS=token1,token2 bunqueue
-```
+### Embedded Mode (Recommended)
 
-Or create a `.env` file:
+No server required. BullMQ-compatible API.
 
-```env
-# Server ports
-TCP_PORT=6789
-HTTP_PORT=6790
-HOST=0.0.0.0
+```typescript
+import { Queue, Worker } from 'bunqueue/client';
 
-# Persistence (required for production)
-DATA_PATH=./data/bunqueue.db
+// Create queue
+const queue = new Queue('emails');
 
-# Authentication (recommended for production)
-AUTH_TOKENS=your-secret-token-1,your-secret-token-2
+// Create worker
+const worker = new Worker('emails', async (job) => {
+  console.log('Sending email to:', job.data.to);
+  await job.updateProgress(50);
+  return { sent: true };
+}, { concurrency: 5 });
 
-# Optional: Protect metrics endpoint
-METRICS_AUTH=true
-```
+// Handle events
+worker.on('completed', (job, result) => {
+  console.log(`Job ${job.id} completed:`, result);
+});
 
-Then run:
+worker.on('failed', (job, err) => {
+  console.error(`Job ${job.id} failed:`, err.message);
+});
 
-```bash
-bunqueue
+// Add jobs
+await queue.add('send-welcome', { to: 'user@example.com' });
 ```
 
-Output:
-```
-bunqueue server running
+### Server Mode
+
+For multi-process or microservice architectures.
 
-TCP:  0.0.0.0:6789
-HTTP: 0.0.0.0:6790
-Data: ./data/bunqueue.db
-Auth: enabled (2 tokens)
+**Terminal 1 - Start server:**
+```bash
+bunqueue start
 ```
 
-### Use SDK
+<img src=".github/terminal.png" alt="bunqueue server running" width="600" />
 
+**Terminal 2 - Producer:**
 ```typescript
-import { Queue, Worker } from 'flashq';
-
-// Producer: add jobs
-const queue = new Queue('emails');
-await queue.add('send-welcome', { to: 'user@example.com' });
-
-// Consumer: process jobs
-const worker = new Worker('emails', async (job) => {
-  console.log('Sending email to:', job.data.to);
-  return { sent: true };
+const res = await fetch('http://localhost:6790/push', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    queue: 'emails',
+    data: { to: 'user@example.com' }
+  })
 });
 ```
 
+**Terminal 3 - Consumer:**
+```typescript
+while (true) {
+  const res = await fetch('http://localhost:6790/pull', {
+    method: 'POST',
+    body: JSON.stringify({ queue: 'emails', timeout: 5000 })
+  });
+
+  const job = await res.json();
+  if (job.id) {
+    console.log('Processing:', job.data);
+    await fetch('http://localhost:6790/ack', {
+      method: 'POST',
+      body: JSON.stringify({ id: job.id })
+    });
+  }
+}
+```
+
 ---
 
 ## Features
 
-- **Blazing Fast** — Built on Bun runtime with native SQLite, optimized for maximum throughput
-- **Persistent Storage** — SQLite with WAL mode for durability and concurrent access
-- **Priority Queues** — FIFO, LIFO, and priority-based job ordering
-- **Delayed Jobs** — Schedule jobs to run at specific times
-- **Cron Scheduling** — Recurring jobs with cron expressions or fixed intervals
+- **Blazing Fast** — 500K+ jobs/sec, built on Bun runtime
+- **Dual Mode** — Embedded (in-process) or Server (TCP/HTTP)
+- **BullMQ-Compatible API** — Easy migration with `Queue`, `Worker`, `QueueEvents`
+- **Persistent Storage** — SQLite with WAL mode
+- **Priority Queues** — FIFO, LIFO, and priority-based ordering
+- **Delayed Jobs** — Schedule jobs for later
+- **Cron Scheduling** — Recurring jobs with cron expressions
 - **Retry & Backoff** — Automatic retries with exponential backoff
-- **Dead Letter Queue** — Failed jobs preserved for inspection and retry
-- **Job Dependencies** — Define parent-child relationships and execution order
-- **Progress Tracking** — Real-time progress updates for long-running jobs
-- **Rate Limiting** — Per-queue rate limits and concurrency control
+- **Dead Letter Queue** — Failed jobs preserved for inspection
+- **Job Dependencies** — Parent-child relationships
+- **Progress Tracking** — Real-time progress updates
+- **Rate Limiting** — Per-queue rate limits
 - **Webhooks** — HTTP callbacks on job events
-- **Real-time Events** — WebSocket and Server-Sent Events (SSE) support
-- **Prometheus Metrics** — Built-in metrics endpoint for monitoring
-- **Authentication** — Token-based auth for secure access
-- **Dual Protocol** — TCP (high performance) and HTTP/REST (compatibility)
-- **Full-Featured CLI** — Manage queues, jobs, cron, and more from the command line
-
-## CLI
+- **Real-time Events** — WebSocket and SSE support
+- **Prometheus Metrics** — Built-in monitoring
+- **Full CLI** — Manage queues from command line
 
-bunqueue includes a powerful CLI for managing the server and executing commands.
-
-### Server Mode
-
-```bash
-# Start server with defaults
-bunqueue
-
-# Start with options
-bunqueue start --tcp-port 6789 --http-port 6790 --data-path ./data/queue.db
-```
+---
 
-### Client Commands
+## Embedded Mode
 
-```bash
-# Push a job
-bunqueue push emails '{"to":"user@test.com","subject":"Hello"}'
-bunqueue push tasks '{"action":"sync"}' --priority 10 --delay 5000
-
-# Pull and process jobs
-bunqueue pull emails --timeout 5000
-bunqueue ack 12345 --result '{"sent":true}'
-bunqueue fail 12345 --error "SMTP timeout"
+### Queue API
 
-# Job management
-bunqueue job get 12345
-bunqueue job progress 12345 50 --message "Processing..."
-bunqueue job cancel 12345
-
-# Queue control
-bunqueue queue list
-bunqueue queue pause emails
-bunqueue queue resume emails
-bunqueue queue drain emails
+```typescript
+import { Queue } from 'bunqueue/client';
 
-# Cron jobs
-bunqueue cron list
-bunqueue cron add hourly-cleanup -q maintenance -d '{"task":"cleanup"}' -s "0 * * * *"
-bunqueue cron delete hourly-cleanup
+const queue = new Queue('my-queue');
 
-# DLQ management
-bunqueue dlq list emails
-bunqueue dlq retry emails
-bunqueue dlq purge emails
+// Add job
+const job = await queue.add('task-name', { data: 'value' });
 
-# Monitoring
-bunqueue stats
-bunqueue metrics
-bunqueue health
-```
+// Add with options
+await queue.add('task', { data: 'value' }, {
+  priority: 10,        // Higher = processed first
+  delay: 5000,         // Delay in ms
+  attempts: 3,         // Max retries
+  backoff: 1000,       // Backoff base (ms)
+  timeout: 30000,      // Processing timeout
+  jobId: 'unique-id',  // Custom ID
+  removeOnComplete: true,
+  removeOnFail: false,
+});
 
-### Global Options
+// Bulk add
+await queue.addBulk([
+  { name: 'task1', data: { id: 1 } },
+  { name: 'task2', data: { id: 2 } },
+]);
 
-```bash
--H, --host <host>    # Server host (default: localhost)
--p, --port <port>    # TCP port (default: 6789)
--t, --token <token>  # Authentication token
---json               # Output as JSON
---help               # Show help
---version            # Show version
-```
+// Get job
+const job = await queue.getJob('job-id');
 
-## SDK (flashq)
+// Remove job
+await queue.remove('job-id');
 
-The [flashq](https://www.npmjs.com/package/flashq) SDK provides a type-safe TypeScript interface for bunqueue.
+// Get counts
+const counts = await queue.getJobCounts();
+// { waiting: 10, active: 2, completed: 100, failed: 5 }
 
-```bash
-bun add flashq
+// Queue control
+await queue.pause();
+await queue.resume();
+await queue.drain();      // Remove waiting jobs
+await queue.obliterate(); // Remove ALL data
 ```
 
-> **Prerequisites:** A running bunqueue server (see [Quick Install](#quick-install))
-
-### Basic Usage
+### Worker API
 
 ```typescript
-import { Queue, Worker } from 'flashq';
+import { Worker } from 'bunqueue/client';
 
-// Create a queue
-const queue = new Queue('my-queue', {
-  connection: { host: 'localhost', port: 6789 }
-});
-
-// Add a job
-await queue.add('process-data', { userId: 123, action: 'sync' });
-
-// Add with options
-await queue.add('send-email',
-  { to: 'user@example.com', subject: 'Hello' },
-  {
-    priority: 10,
-    delay: 5000,        // 5 seconds
-    attempts: 3,
-    backoff: { type: 'exponential', delay: 1000 }
-  }
-);
-
-// Create a worker
 const worker = new Worker('my-queue', async (job) => {
   console.log('Processing:', job.name, job.data);
 
   // Update progress
-  await job.updateProgress(50);
+  await job.updateProgress(50, 'Halfway done');
 
-  // Do work...
+  // Add log
+  await job.log('Processing step completed');
 
+  // Return result
   return { success: true };
 }, {
-  connection: { host: 'localhost', port: 6789 },
-  concurrency: 5
+  concurrency: 10,  // Parallel jobs
+  autorun: true,    // Start automatically
+});
+
+// Events
+worker.on('active', (job) => {
+  console.log(`Job ${job.id} started`);
 });
 
-// Handle events
 worker.on('completed', (job, result) => {
   console.log(`Job ${job.id} completed:`, result);
 });
@@ -265,667 +252,336 @@ worker.on('completed', (job, result) => {
 worker.on('failed', (job, err) => {
   console.error(`Job ${job.id} failed:`, err.message);
 });
-```
-
-### Cron Jobs
 
-```typescript
-import { Queue } from 'flashq';
+worker.on('progress', (job, progress) => {
+  console.log(`Job ${job.id} progress:`, progress);
+});
 
-const queue = new Queue('scheduled', {
-  connection: { host: 'localhost', port: 6789 }
+worker.on('error', (err) => {
+  console.error('Worker error:', err);
 });
 
-// Every hour
-await queue.upsertJobScheduler('hourly-report',
-  { pattern: '0 * * * *' },
-  { name: 'generate-report', data: { type: 'hourly' } }
-);
-
-// Every 5 minutes
-await queue.upsertJobScheduler('health-check',
-  { every: 300000 },
-  { name: 'ping', data: {} }
-);
+// Control
+worker.pause();
+worker.resume();
+await worker.close();       // Graceful shutdown
+await worker.close(true);   // Force close
 ```
 
-### Job Dependencies (Flows)
+### QueueEvents
+
+Listen to queue events without processing jobs.
 
 ```typescript
-import { FlowProducer } from 'flashq';
+import { QueueEvents } from 'bunqueue/client';
 
-const flow = new FlowProducer({
-  connection: { host: 'localhost', port: 6789 }
-});
+const events = new QueueEvents('my-queue');
 
-// Create a flow with parent-child dependencies
-await flow.add({
-  name: 'final-step',
-  queueName: 'pipeline',
-  data: { step: 'aggregate' },
-  children: [
-    {
-      name: 'step-1',
-      queueName: 'pipeline',
-      data: { step: 'fetch' }
-    },
-    {
-      name: 'step-2',
-      queueName: 'pipeline',
-      data: { step: 'transform' }
-    }
-  ]
+events.on('waiting', ({ jobId }) => {
+  console.log(`Job ${jobId} waiting`);
 });
-```
-
-### Real-time Events
-
-```typescript
-import { QueueEvents } from 'flashq';
 
-const events = new QueueEvents('my-queue', {
-  connection: { host: 'localhost', port: 6789 }
+events.on('active', ({ jobId }) => {
+  console.log(`Job ${jobId} active`);
 });
 
 events.on('completed', ({ jobId, returnvalue }) => {
-  console.log(`Job ${jobId} completed with:`, returnvalue);
+  console.log(`Job ${jobId} completed:`, returnvalue);
 });
 
 events.on('failed', ({ jobId, failedReason }) => {
-  console.error(`Job ${jobId} failed:`, failedReason);
+  console.log(`Job ${jobId} failed:`, failedReason);
 });
 
 events.on('progress', ({ jobId, data }) => {
   console.log(`Job ${jobId} progress:`, data);
 });
-```
-
-For more examples, see the [SDK documentation](https://www.npmjs.com/package/flashq).
-
-## Quick Start
 
-### Start the Server
-
-```bash
-# Using Bun directly
-bun run src/main.ts
-
-# Or with Docker
-docker run -p 6789:6789 -p 6790:6790 ghcr.io/egeominotti/bunqueue
-```
-
-### Push a Job (HTTP)
-
-```bash
-curl -X POST http://localhost:6790/queues/emails/jobs \
-  -H "Content-Type: application/json" \
-  -d '{"data": {"to": "user@example.com", "subject": "Hello"}}'
-```
-
-### Pull a Job (HTTP)
-
-```bash
-curl http://localhost:6790/queues/emails/jobs
-```
-
-### Acknowledge Completion
-
-```bash
-curl -X POST http://localhost:6790/jobs/1/ack \
-  -H "Content-Type: application/json" \
-  -d '{"result": {"sent": true}}'
+await events.close();
 ```
 
-## Installation
-
-### Server + SDK
-
-bunqueue is composed of two packages:
-
-| Package | Description | Install |
-|---------|-------------|---------|
-| **bunqueue** | Job queue server | `bun add bunqueue` |
-| **flashq** | TypeScript SDK | `bun add flashq` |
-
-```bash
-# Install both
-bun add bunqueue flashq
-```
-
-### Quick Setup
-
-```bash
-# 1. Start the server
-bunqueue
-
-# 2. Use the SDK in your app
-```
+### Shutdown
 
 ```typescript
-import { Queue, Worker } from 'flashq';
-
-const queue = new Queue('tasks');
-await queue.add('my-job', { data: 'hello' });
+import { shutdownManager } from 'bunqueue/client';
 
-const worker = new Worker('tasks', async (job) => {
-  console.log(job.data);
-  return { done: true };
-});
+// Cleanup when done
+shutdownManager();
 ```
 
-### From Source
-
-```bash
-git clone https://github.com/egeominotti/bunqueue.git
-cd bunqueue
-bun install
-bun run start
-```
-
-### Build Binary
+---
 
-```bash
-bun run build
-./dist/bunqueue
-```
+## Server Mode
 
-### Docker
+### Start Server
 
 ```bash
-docker pull ghcr.io/egeominotti/bunqueue
-docker run -d \
-  -p 6789:6789 \
-  -p 6790:6790 \
-  -v bunqueue-data:/app/data \
-  ghcr.io/egeominotti/bunqueue
-```
-
-### Docker Compose
+# Basic
+bunqueue start
 
-```yaml
-version: "3.8"
-services:
-  bunqueue:
-    image: ghcr.io/egeominotti/bunqueue
-    ports:
-      - "6789:6789"
-      - "6790:6790"
-    volumes:
-      - bunqueue-data:/app/data
-    environment:
-      - AUTH_TOKENS=your-secret-token
+# With options
+bunqueue start --tcp-port 6789 --http-port 6790 --data-path ./data/queue.db
 
-volumes:
-  bunqueue-data:
+# With environment variables
+DATA_PATH=./data/bunqueue.db AUTH_TOKENS=secret bunqueue start
 ```
 
-## Usage
-
-### TCP Protocol (High Performance)
-
-Connect via TCP for maximum throughput. Commands are newline-delimited JSON.
-
-```bash
-# Connect with netcat
-nc localhost 6789
-
-# Push a job
-{"cmd":"PUSH","queue":"tasks","data":{"action":"process"}}
-
-# Pull a job
-{"cmd":"PULL","queue":"tasks"}
+### Environment Variables
 
-# Acknowledge
-{"cmd":"ACK","id":"1"}
+```env
+TCP_PORT=6789
+HTTP_PORT=6790
+HOST=0.0.0.0
+DATA_PATH=./data/bunqueue.db
+AUTH_TOKENS=token1,token2
 ```
 
-### HTTP REST API
+### HTTP API
 
 ```bash
 # Push job
-curl -X POST http://localhost:6790/queues/tasks/jobs \
+curl -X POST http://localhost:6790/push \
   -H "Content-Type: application/json" \
-  -d '{
-    "data": {"action": "process"},
-    "priority": 10,
-    "delay": 5000,
-    "maxAttempts": 5
-  }'
+  -d '{"queue":"emails","data":{"to":"user@test.com"},"priority":10}'
 
-# Pull job (with timeout)
-curl "http://localhost:6790/queues/tasks/jobs?timeout=30000"
+# Pull job
+curl -X POST http://localhost:6790/pull \
+  -H "Content-Type: application/json" \
+  -d '{"queue":"emails","timeout":5000}'
 
-# Get job by ID
-curl http://localhost:6790/jobs/123
+# Acknowledge
+curl -X POST http://localhost:6790/ack \
+  -H "Content-Type: application/json" \
+  -d '{"id":"job-id","result":{"sent":true}}'
 
-# Fail a job
-curl -X POST http://localhost:6790/jobs/123/fail \
+# Fail
+curl -X POST http://localhost:6790/fail \
   -H "Content-Type: application/json" \
-  -d '{"error": "Processing failed"}'
+  -d '{"id":"job-id","error":"Failed to send"}'
 
-# Get stats
+# Stats
 curl http://localhost:6790/stats
-```
-
-### WebSocket (Real-time)
-
-```javascript
-const ws = new WebSocket('ws://localhost:6790/ws');
-
-ws.onmessage = (event) => {
-  const job = JSON.parse(event.data);
-  console.log('Job event:', job);
-};
-
-// Subscribe to specific queue
-const wsQueue = new WebSocket('ws://localhost:6790/ws/queues/emails');
-```
-
-### Server-Sent Events (SSE)
-
-```javascript
-const events = new EventSource('http://localhost:6790/events');
 
-events.onmessage = (event) => {
-  const data = JSON.parse(event.data);
-  console.log('Event:', data);
-};
-
-// Filter by queue
-const queueEvents = new EventSource('http://localhost:6790/events/queues/emails');
-```
-
-### Job Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `data` | any | required | Job payload |
-| `priority` | number | 0 | Higher = processed first |
-| `delay` | number | 0 | Delay in milliseconds |
-| `maxAttempts` | number | 3 | Max retry attempts |
-| `backoff` | number | 1000 | Initial backoff (ms), doubles each retry |
-| `ttl` | number | null | Time-to-live in milliseconds |
-| `timeout` | number | null | Job processing timeout |
-| `uniqueKey` | string | null | Deduplication key |
-| `jobId` | string | null | Custom job identifier |
-| `dependsOn` | string[] | [] | Job IDs that must complete first |
-| `tags` | string[] | [] | Tags for filtering |
-| `groupId` | string | null | Group identifier |
-| `lifo` | boolean | false | Last-in-first-out ordering |
-| `removeOnComplete` | boolean | false | Auto-delete on completion |
-| `removeOnFail` | boolean | false | Auto-delete on failure |
-
-### Cron Jobs
-
-```bash
-# Cron expression (every hour)
-curl -X POST http://localhost:6790/cron \
-  -d '{"cmd":"Cron","name":"hourly-cleanup","queue":"maintenance","data":{"task":"cleanup"},"schedule":"0 * * * *"}'
-
-# Fixed interval (every 5 minutes)
-curl -X POST http://localhost:6790/cron \
-  -d '{"cmd":"Cron","name":"health-check","queue":"monitoring","data":{"check":"ping"},"repeatEvery":300000}'
+# Health
+curl http://localhost:6790/health
 
-# With execution limit
-curl -X POST http://localhost:6790/cron \
-  -d '{"cmd":"Cron","name":"one-time-migration","queue":"migrations","data":{},"repeatEvery":0,"maxLimit":1}'
+# Prometheus metrics
+curl http://localhost:6790/prometheus
 ```
 
-## API Reference
-
-### Core Operations
-
-| Command | Description |
-|---------|-------------|
-| `PUSH` | Add a job to a queue |
-| `PUSHB` | Batch push multiple jobs |
-| `PULL` | Get the next job from a queue |
-| `PULLB` | Batch pull multiple jobs |
-| `ACK` | Mark job as completed |
-| `ACKB` | Batch acknowledge jobs |
-| `FAIL` | Mark job as failed |
-
-### Query Operations
-
-| Command | Description |
-|---------|-------------|
-| `GetJob` | Get job by ID |
-| `GetState` | Get job state |
-| `GetResult` | Get job result |
-| `GetJobs` | List jobs with filters |
-| `GetJobCounts` | Count jobs by state |
-| `GetJobByCustomId` | Find job by custom ID |
-| `GetProgress` | Get job progress |
-| `GetLogs` | Get job logs |
-
-### Job Management
-
-| Command | Description |
-|---------|-------------|
-| `Cancel` | Cancel a pending job |
-| `Progress` | Update job progress |
-| `Update` | Update job data |
-| `ChangePriority` | Change job priority |
-| `Promote` | Move delayed job to waiting |
-| `MoveToDelayed` | Delay a waiting job |
-| `Discard` | Discard a job |
-| `Heartbeat` | Send job heartbeat |
-| `AddLog` | Add log entry to job |
-
-### Queue Control
-
-| Command | Description |
-|---------|-------------|
-| `Pause` | Pause queue processing |
-| `Resume` | Resume queue processing |
-| `IsPaused` | Check if queue is paused |
-| `Drain` | Remove all waiting jobs |
-| `Obliterate` | Remove all queue data |
-| `Clean` | Remove old jobs |
-| `ListQueues` | List all queues |
-| `RateLimit` | Set queue rate limit |
-| `SetConcurrency` | Set max concurrent jobs |
-
-### Dead Letter Queue
-
-| Command | Description |
-|---------|-------------|
-| `Dlq` | Get failed jobs |
-| `RetryDlq` | Retry failed jobs |
-| `PurgeDlq` | Clear failed jobs |
-
-### Scheduling
-
-| Command | Description |
-|---------|-------------|
-| `Cron` | Create/update cron job |
-| `CronDelete` | Delete cron job |
-| `CronList` | List all cron jobs |
-
-### Workers & Webhooks
-
-| Command | Description |
-|---------|-------------|
-| `RegisterWorker` | Register a worker |
-| `UnregisterWorker` | Unregister a worker |
-| `ListWorkers` | List active workers |
-| `AddWebhook` | Add webhook endpoint |
-| `RemoveWebhook` | Remove webhook |
-| `ListWebhooks` | List webhooks |
-
-### Monitoring
-
-| Command | Description |
-|---------|-------------|
-| `Stats` | Get server statistics |
-| `Metrics` | Get job metrics |
-| `Prometheus` | Prometheus format metrics |
-
-## Configuration
-
-### Environment Variables
+### TCP Protocol
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `TCP_PORT` | 6789 | TCP protocol port |
-| `HTTP_PORT` | 6790 | HTTP/WebSocket port |
-| `HOST` | 0.0.0.0 | Bind address |
-| `AUTH_TOKENS` | - | Comma-separated auth tokens |
-| `DATA_PATH` | - | SQLite database path (in-memory if not set) |
-| `CORS_ALLOW_ORIGIN` | * | Allowed CORS origins |
-
-### S3 Backup Configuration
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `S3_BACKUP_ENABLED` | 0 | Enable automated S3 backups (1/true) |
-| `S3_ACCESS_KEY_ID` | - | S3 access key |
-| `S3_SECRET_ACCESS_KEY` | - | S3 secret key |
-| `S3_BUCKET` | - | S3 bucket name |
-| `S3_REGION` | us-east-1 | S3 region |
-| `S3_ENDPOINT` | - | Custom endpoint for S3-compatible services |
-| `S3_BACKUP_INTERVAL` | 21600000 | Backup interval in ms (default: 6 hours) |
-| `S3_BACKUP_RETENTION` | 7 | Number of backups to retain |
-| `S3_BACKUP_PREFIX` | backups/ | Prefix for backup files |
-
-**Supported S3 Providers:**
-- AWS S3
-- Cloudflare R2: `S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com`
-- MinIO: `S3_ENDPOINT=http://localhost:9000`
-- DigitalOcean Spaces: `S3_ENDPOINT=https://<region>.digitaloceanspaces.com`
-
-**CLI Commands:**
 ```bash
-# Create backup immediately
-bunqueue backup now
-
-# List available backups
-bunqueue backup list
-
-# Restore from backup (requires --force)
-bunqueue backup restore backups/bunqueue-2024-01-15.db --force
+nc localhost 6789
 
-# Show backup status
-bunqueue backup status
+# Commands (JSON)
+{"cmd":"PUSH","queue":"tasks","data":{"action":"process"}}
+{"cmd":"PULL","queue":"tasks","timeout":5000}
+{"cmd":"ACK","id":"1","result":{"done":true}}
+{"cmd":"FAIL","id":"1","error":"Something went wrong"}
 ```
 
-### Authentication
-
-Enable authentication by setting `AUTH_TOKENS`:
+---
 
-```bash
-AUTH_TOKENS=token1,token2 bun run start
-```
+## CLI
 
-**HTTP:**
 ```bash
-curl -H "Authorization: Bearer token1" http://localhost:6790/stats
-```
+# Server
+bunqueue start
+bunqueue start --tcp-port 6789 --http-port 6790
 
-**TCP:**
-```json
-{"cmd":"Auth","token":"token1"}
-```
-
-**WebSocket:**
-```json
-{"cmd":"Auth","token":"token1"}
-```
-
-## Monitoring
-
-### Health Check
+# Jobs
+bunqueue push emails '{"to":"user@test.com"}'
+bunqueue push tasks '{"action":"sync"}' --priority 10 --delay 5000
+bunqueue pull emails --timeout 5000
+bunqueue ack <job-id>
+bunqueue fail <job-id> --error "Failed"
 
-```bash
-curl http://localhost:6790/health
-# {"ok":true,"status":"healthy"}
-```
+# Job management
+bunqueue job get <id>
+bunqueue job progress <id> 50 --message "Processing"
+bunqueue job cancel <id>
 
-### Prometheus Metrics
+# Queue control
+bunqueue queue list
+bunqueue queue pause emails
+bunqueue queue resume emails
+bunqueue queue drain emails
 
-```bash
-curl http://localhost:6790/prometheus
-```
+# Cron
+bunqueue cron list
+bunqueue cron add cleanup -q maintenance -d '{}' -s "0 * * * *"
+bunqueue cron delete cleanup
 
-Metrics include:
-- `bunqueue_jobs_total{queue,state}` — Job counts by state
-- `bunqueue_jobs_processed_total{queue}` — Total processed jobs
-- `bunqueue_jobs_failed_total{queue}` — Total failed jobs
-- `bunqueue_queue_latency_seconds{queue}` — Processing latency
+# DLQ
+bunqueue dlq list emails
+bunqueue dlq retry emails
+bunqueue dlq purge emails
 
-### Statistics
+# Monitoring
+bunqueue stats
+bunqueue metrics
+bunqueue health
 
-```bash
-curl http://localhost:6790/stats
+# Backup (S3)
+bunqueue backup now
+bunqueue backup list
+bunqueue backup restore <key> --force
 ```
 
-```json
-{
-  "ok": true,
-  "stats": {
-    "waiting": 150,
-    "active": 10,
-    "delayed": 25,
-    "completed": 10000,
-    "failed": 50,
-    "dlq": 5,
-    "totalPushed": 10235,
-    "totalPulled": 10085,
-    "totalCompleted": 10000,
-    "totalFailed": 50
-  }
-}
-```
+---
 
 ## Docker
 
-### Build
-
 ```bash
-docker build -t bunqueue .
-```
-
-### Run
-
-```bash
-# Basic
-docker run -p 6789:6789 -p 6790:6790 bunqueue
+# Run
+docker run -p 6789:6789 -p 6790:6790 ghcr.io/egeominotti/bunqueue
 
 # With persistence
 docker run -p 6789:6789 -p 6790:6790 \
   -v bunqueue-data:/app/data \
   -e DATA_PATH=/app/data/bunqueue.db \
-  bunqueue
+  ghcr.io/egeominotti/bunqueue
 
-# With authentication
+# With auth
 docker run -p 6789:6789 -p 6790:6790 \
-  -e AUTH_TOKENS=secret1,secret2 \
-  bunqueue
+  -e AUTH_TOKENS=secret \
+  ghcr.io/egeominotti/bunqueue
 ```
 
 ### Docker Compose
 
-```bash
-# Production
-docker compose up -d
+```yaml
+version: "3.8"
+services:
+  bunqueue:
+    image: ghcr.io/egeominotti/bunqueue
+    ports:
+      - "6789:6789"
+      - "6790:6790"
+    volumes:
+      - bunqueue-data:/app/data
+    environment:
+      - DATA_PATH=/app/data/bunqueue.db
+      - AUTH_TOKENS=your-secret-token
 
-# Development (hot reload)
-docker compose --profile dev up bunqueue-dev
+volumes:
+  bunqueue-data:
 ```
 
-## Deployment
+---
 
-bunqueue requires a **persistent server** with filesystem access for SQLite. It is **not compatible** with serverless platforms like Vercel or Cloudflare Workers.
+## S3 Backup
 
-### Compatible Platforms
+```env
+S3_BACKUP_ENABLED=1
+S3_ACCESS_KEY_ID=your-key
+S3_SECRET_ACCESS_KEY=your-secret
+S3_BUCKET=my-bucket
+S3_REGION=us-east-1
+S3_BACKUP_INTERVAL=21600000  # 6 hours
+S3_BACKUP_RETENTION=7
+```
 
-| Platform | Bun | SQLite | TCP | Notes |
-|----------|:---:|:------:|:---:|-------|
-| [Fly.io](https://fly.io) | ✅ | ✅ | ✅ | Recommended - persistent volumes, global deployment |
-| [Railway](https://railway.app) | ✅ | ✅ | ✅ | Easy deploy from GitHub |
-| [Render](https://render.com) | ✅ | ✅ | ✅ | Docker support, persistent disks |
-| [DigitalOcean](https://digitalocean.com) | ✅ | ✅ | ✅ | App Platform or Droplets |
-| Any VPS | ✅ | ✅ | ✅ | Full control |
+Supported providers: AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces.
 
-### Fly.io (Recommended)
+---
 
-```bash
-# Install flyctl
-curl -L https://fly.io/install.sh | sh
+## When to Use What?
 
-# Launch (uses existing Dockerfile)
-fly launch
+| Scenario | Mode |
+|----------|------|
+| Single app, monolith | **Embedded** |
+| Scripts, CLI tools | **Embedded** |
+| Serverless (with persistence) | **Embedded** |
+| Microservices | **Server** |
+| Multiple languages | **Server** (HTTP API) |
+| Horizontal scaling | **Server** |
 
-# Create persistent volume for SQLite
-fly volumes create bunqueue_data --size 1
+### Server Mode SDK
 
-# Set secrets
-fly secrets set AUTH_TOKENS=your-secret-token
+For communicating with bunqueue server from **separate processes**, use the [flashq](https://www.npmjs.com/package/flashq) SDK:
 
-# Deploy
-fly deploy
+```bash
+bun add flashq
 ```
 
-Add to `fly.toml`:
-```toml
-[mounts]
-  source = "bunqueue_data"
-  destination = "/app/data"
-
-[env]
-  DATA_PATH = "/app/data/bunqueue.db"
-```
+```typescript
+import { FlashQ } from 'flashq';
 
-### Railway
+const client = new FlashQ({ host: 'localhost', port: 6789 });
 
-[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template)
+// Push job
+await client.push('emails', { to: 'user@test.com' });
 
-```bash
-# Or via CLI
-railway login
-railway init
-railway up
+// Pull and process
+const job = await client.pull('emails');
+if (job) {
+  console.log('Processing:', job.data);
+  await client.ack(job.id);
+}
 ```
 
-### Not Compatible
+| Package | Use Case |
+|---------|----------|
+| `bunqueue/client` | Same process (embedded) |
+| `flashq` | Different process (TCP client) |
 
-| Platform | Reason |
-|----------|--------|
-| Vercel | Serverless functions, no persistent filesystem, no TCP |
-| Cloudflare Workers | V8 isolates (not Bun), no filesystem, no TCP |
-| AWS Lambda | Serverless, no persistent storage |
-| Netlify Functions | Serverless, no filesystem |
+```
+┌─────────────────┐          ┌─────────────────┐
+│   Your App      │          │   Your App      │
+│                 │          │                 │
+│  bunqueue/client│          │     flashq      │
+│  (embedded)     │          │   (TCP client)  │
+└────────┬────────┘          └────────┬────────┘
+         │                            │
+         │                            ▼
+         │                   ┌─────────────────┐
+         │                   │ bunqueue server │
+         │                   │   (port 6789)   │
+         │                   └─────────────────┘
+         │
+    Same process              Different process
+```
+
+---
 
 ## Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                        bunqueue Server                          │
+│                        bunqueue                              │
 ├─────────────────────────────────────────────────────────────┤
-│   HTTP/WS (Bun.serve)    │    TCP Protocol (Bun.listen)    │
+│   Embedded Mode          │    Server Mode                   │
+│   (bunqueue/client)      │    (bunqueue start)              │
+│                          │                                  │
+│   Queue, Worker          │    TCP (6789) + HTTP (6790)      │
+│   in-process             │    multi-process                 │
 ├─────────────────────────────────────────────────────────────┤
-│                      Core Engine                            │
-│  ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐     │
-│  │  Queues  │ │ Workers  │ │ Scheduler │ │   DLQ    │     │
-│  │ (32 shards) │          │ │  (Cron)   │ │          │     │
-│  └──────────┘ └──────────┘ └───────────┘ └──────────┘     │
+│                      Core Engine                             │
+│  ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐      │
+│  │  Queues  │ │ Workers  │ │ Scheduler │ │   DLQ    │      │
+│  │(32 shards)│ │          │ │  (Cron)   │ │          │      │
+│  └──────────┘ └──────────┘ └───────────┘ └──────────┘      │
 ├─────────────────────────────────────────────────────────────┤
-│               SQLite (WAL mode, 256MB mmap)                 │
+│               SQLite (WAL mode, 256MB mmap)                  │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-### Performance Optimizations
-
-- **32 Shards** — Lock contention minimized with FNV-1a hash distribution
-- **WAL Mode** — Concurrent reads during writes
-- **Memory-mapped I/O** — 256MB mmap for fast access
-- **Batch Operations** — Bulk inserts and updates
-- **Bounded Collections** — Automatic memory cleanup
+---
 
 ## Contributing
 
-Contributions are welcome! Please read our contributing guidelines before submitting PRs.
-
 ```bash
-# Install dependencies
 bun install
-
-# Run tests
 bun test
-
-# Run linter
 bun run lint
-
-# Format code
 bun run format
-
-# Type check
-bun run typecheck
-
-# Run all checks
 bun run check
 ```
 
+---
+
 ## License
 
 MIT License — see [LICENSE](LICENSE) for details.