Docs/adding documentation

.github/workflows/ci.yml

@@ -11,13 +11,13 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20]
+        node-version: [22]
 
     steps:
       - uses: actions/checkout@v4
       - uses: pnpm/action-setup@v2
         with:
-          version: 8
+          version: 11
       - uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
@@ -28,5 +28,7 @@ jobs:
 
       - run: pnpm install --frozen-lockfile
       - run: bun test
-      - run: pnpm build
-      - run: bun run --bun tsc --noEmit # type check
+
+      - run: pnpm --filter=!dashboard build
+
+      - run: pnpm --filter=!dashboard exec tsc --noEmit

CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# Contributing to JetQueue
+
+Thank you for your interest in contributing!  
+JetQueue is an open‑source project and we welcome all contributions.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). Please read it before participating.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+- Check the [existing issues](https://github.com/arxja/jet-queue/issues) first.
+- Use the bug report template (if available) or include:
+  - JetQueue version
+  - Runtime (Node.js / Bun) and version
+  - Clear description of the problem
+  - Steps to reproduce
+  - Expected vs actual behavior
+  - Any relevant error logs
+
+### Suggesting Features
+
+- Open an issue with the label `enhancement`.
+- Describe the use‑case and why it would be valuable.
+- If you’re willing to implement it, mention that!
+
+### Pull Requests
+
+1. Fork the repository and create your branch from `main`.
+2. If you added code, please add tests.
+3. Ensure the test suite passes (`bun test`).
+4. Make sure your code passes type checking (`bun run --bun tsc --noEmit`).
+5. Follow the existing code style.
+6. Write a clear commit message (see below).
+7. Open a pull request against the `main` branch.
+
+## Development Setup
+
+### Prerequisites
+
+- [Bun](https://bun.sh) (latest)
+- [Node.js](https://nodejs.org) 22+ (for testing Node compatibility)
+- [pnpm](https://pnpm.io) 11+
+
+### Setup
+
+```bash
+git clone https://github.com/arxja/jet-queue.git
+cd jet-queue
+pnpm install
+```
+
+### Running Tests
+
+```bash
+bun test
+```
+
+### Building
+
+```bash
+pnpm build
+```
+
+### Running the Demo
+
+```bash
+# Terminal 1 (Bun)
+cd examples/split-screen-demo
+bun run server.ts
+
+# Terminal 2 (Next.js)
+cd examples/split-screen-demo
+npm run dev
+```
+
+## Project Structure
+
+```text
+jet-queue/
+├── packages/
+│   ├── core/        # @jet-queue/core (engine)
+│   ├── server/      # @jet-queue/server (Bun server)
+│   ├── client/      # @jet-queue/client (SDK)
+│   ├── cli/         # @jet-queue/cli (terminal dashboard)
+│   └── dashboard/   # @jet-queue/dashboard (web UI)
+├── examples/
+├── docs/
+└── scripts/
+```
+
+## Commit Message Guidelines
+
+We use [Conventional Commits](https://conventionalcommits.org):
+
+- `feat: add retry backoff strategy`
+- `fix: handle job timeout correctly`
+- `docs: update server API reference`
+- `test: add coverage for priority queue`
+- `chore: update dependencies`
+
+## Style Guide
+
+- TypeScript strict mode
+- Use `async/await` over raw promises
+- Explicit function return types for public API
+- Single responsibility per file
+- Keep core package zero‑dependencies
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+<br/>
+<p align="center">Thank you for helping make JetQueue better!</p>

README.md

@@ -180,10 +180,11 @@ const queue = new JetQueue({
 - **SQLite** - Zero-config persistence
 
 ## 📚 Documentation
-<!-- Todo: add exact path to the doc files -->
-- [Core API Reference](./docs/)
-- [Server API Reference](./docs/)
-- [Client SDK Reference](./docs/)
+- [Getting Started](./docs/getting-started.md)
+- [Core API Reference](./docs/core.md)
+- [Server API Reference](./docs/server.md)
+- [Client SDK Reference](./docs/client.md)
+- [Architecture](./docs/architecture.md)
 - [Examples](./examples/)
 
 ## 🤝 Contributing

docs/architecture.md

@@ -0,0 +1,16 @@
+# JetQueue Architecture
+
+## Packages
+
+- `@jet-queue/core` – engine (events, retries, storage)
+- `@jet-queue/server` – Bun server (REST + WebSocket)
+- `@jet-queue/client` – SDK for any environment
+- `@jet-queue/cli` – terminal dashboard
+- `@jet-queue/dashboard` – web dashboard (Next.js)
+
+## Data Flow
+
+```text
+App → client.addJob() → HTTP POST /api/jobs → server → queue.add() → process
+App ← client.onJobCompleted() ← WebSocket ← server ← queue.emit('job:completed')
+```

docs/client.md

@@ -0,0 +1,26 @@
+# @jet-queue/client SDK
+
+## Installation
+```bash
+npm install @jet-queue/client
+```
+
+## Usage
+
+```ts
+import { JetQueueClient } from '@jet-queue/client';
+const client = new JetQueueClient({ baseUrl: 'http://localhost:3001' });
+
+// Add a job
+const job = await client.addJob('send-email', { data: { to: 'user@test.com' } });
+
+// Check status
+const status = await client.getJob(job.id);
+
+// Real‑time events
+client.connect();
+client.onJobCompleted(job.id, (job) => console.log('Done!', job.result));
+```
+
+## Methods
+`addJob(handler, options?)`, `getJob(id)`, `getJobProgress(id)`, `cancelJob(id)`, `retryJob(id)`, `getStats()`, `health()`, `connect()`, `disconnect()`, `onJobCompleted(id, cb)`, `onJobFailed(id, cb)`, `onJobProgress(id, cb)`, `onEvent(type, cb)`.

docs/core.md

@@ -0,0 +1,49 @@
+# @jet-queue/core API
+
+## `new JetQueue(options?)`
+
+| Option            | Type    | Default  | Description                  |
+| ----------------- | ------- | -------- | ---------------------------- |
+| concurrency       | number  | 5        | Max simultaneous jobs        |
+| autoStart         | boolean | true     | Start processing immediately |
+| maxQueuedJobs     | number  | Infinity | Max pending jobs             |
+| defaultJobOptions | object  | {}       | Default options for all jobs |
+
+## `queue.add(taskFn, options?)`
+
+Returns job ID.
+
+```ts
+queue.add(
+  async (job) => {
+    /* work */
+  },
+  {
+    name: "send-email",
+    priority: "high", // low | normal | high | critical
+    timeout: 30000,
+    maxAttempts: 3,
+    retryOptions: { strategy: "exponential", delay: 1000 },
+    delay: 5000, // delay before first run
+    tags: ["email"],
+  },
+);
+```
+
+## Events
+
+```ts
+queue.on("job:added", ({ job }) => {});
+queue.on("job:completed", ({ job, result, duration }) => {});
+queue.on("job:failed", ({ job, error, duration }) => {});
+queue.on("job:progress", ({ job, progress }) => {});
+queue.on("queue:drain", ({ stats }) => {});
+```
+## Storage
+
+```ts
+import { MemoryStorage, SQLiteStorage } from '@jet-queue/core';
+new JetQueue({}, new MemoryStorage());                // volatile
+new JetQueue({}, new SQLiteStorage('./queue.db'));    // persistent
+```
+

docs/getting-started.md

@@ -0,0 +1,50 @@
+# Getting Started with JetQueue
+
+## Installation
+
+```bash
+npm install @jet-queue/core
+```
+
+## Your First Queue
+
+```ts
+import { JetQueue } from "@jet-queue/core";
+
+const queue = new JetQueue({ concurrency: 3 });
+
+queue.add(
+  async () => {
+    console.log("Job done!");
+  },
+  { name: "my-first-job" },
+);
+
+queue.on("queue:drain", () => {
+  console.log("All jobs finished");
+});
+```
+
+## Using the Server (Bun)
+
+```bash
+npx @jet-queue/server --port 3001
+```
+
+Then connect with the client:
+
+```bash
+npm install @jet-queue/client
+```
+
+```ts
+import { JetQueueClient } from "@jet-queue/client";
+const client = new JetQueueClient({ baseUrl: "http://localhost:3001" });
+await client.addJob("send-email", { data: { to: "user@test.com" } });
+```
+
+## Next Steps
+- [Core API](./core.md)
+- [Server API](./server.md)
+- [Client SDK](./client.md)
+- [Architecture](./architecture.md)

docs/server.md

@@ -0,0 +1,26 @@
+# @jet-queue/server API
+
+The server package provides a ready‑to‑run Bun server and building blocks for custom servers.
+
+## Quick Start (standalone)
+```bash
+bun run @jet-queue/server
+# or programmatically:
+import { initQueue, createApp } from '@jet-queue/server';
+const queue = await initQueue({ concurrency: 3 });
+queue.registerHandler('email', async (job) => { … });
+const app = createApp();
+Bun.serve({ fetch: app.fetch, port: 3001, websocket: { … } });
+```
+
+## REST Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| **POST** | `/api/jobs` | Add a job |
+| **GET** | `/api/jobs/:id` | Job details |
+| **DELETE** | `/api/jobs/:id` | Cancel job |
+| **POST** | `/api/jobs/:id/retry` | Retry failed job |
+| **GET** | `/api/queues/stats` | Queue statistics |
+| **GET** | `/api/health` | Health check |
+| **WS** | `/ws` | Real-time events |

examples/bun-server-demo/index.ts

@@ -57,9 +57,7 @@ const server = Bun.serve({
       setupWebSocket(ws);
     },
     message() {}, // not used in demo
-    close(ws) {
-      cleanupWebSocket(ws);
-    },
+    close() {},
   },
 });