Thank you for helping make JetQueue better!
diff --git a/README.md b/README.md index 3f48960..a73b6e3 100644 --- a/README.md +++ b/README.md @@ -180,10 +180,11 @@ const queue = new JetQueue({ - **SQLite** - Zero-config persistence ## 📚 Documentation - -- [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 diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..1d34ebc --- /dev/null +++ b/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') +``` diff --git a/docs/client.md b/docs/client.md new file mode 100644 index 0000000..ebb0574 --- /dev/null +++ b/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)`. \ No newline at end of file diff --git a/docs/core.md b/docs/core.md new file mode 100644 index 0000000..9bc18b1 --- /dev/null +++ b/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 +``` + diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..03aa5ef --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/server.md b/docs/server.md new file mode 100644 index 0000000..8fceaef --- /dev/null +++ b/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 | \ No newline at end of file diff --git a/examples/bun-server-demo/index.ts b/examples/bun-server-demo/index.ts index 59139f4..a9ca4d6 100644 --- a/examples/bun-server-demo/index.ts +++ b/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() {}, }, }); diff --git a/examples/split-screen-demo/README.md b/examples/split-screen-demo/README.md deleted file mode 100644 index e215bc4..0000000 --- a/examples/split-screen-demo/README.md +++ /dev/null @@ -1,36 +0,0 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). - -## Getting Started - -First, run the development server: - -```bash -npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev -``` - -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. - -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. - -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. - -## Learn More - -To learn more about Next.js, take a look at the following resources: - -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. - -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! - -## Deploy on Vercel - -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. - -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. diff --git a/package.json b/package.json index dba415d..f44f169 100644 --- a/package.json +++ b/package.json @@ -2,9 +2,15 @@ "name": "jet-queue", "version": "1.0.0", "description": "A background job processing system that lets you move heavy work out of your API's request/response cycle.", - "workspaces": ["packages/*", "examples/*"], + "workspaces": [ + "packages/*", + "examples/*" + ], "scripts": { - "dev": "turbo dev" + "dev": "turbo dev", + "build": "turbo build", + "test": "bun test", + "lint": "tsc --noEmit" }, "keywords": [], "author": "", @@ -15,5 +21,8 @@ "tsup": "^8.5.1", "turbo": "^2.9.12", "typescript": "^6.0.3" + }, + "engines": { + "node": ">=20" } -} +} \ No newline at end of file diff --git a/packages/core/tests/queue.test.ts b/packages/core/tests/queue.test.ts index d29d593..fd63b02 100644 --- a/packages/core/tests/queue.test.ts +++ b/packages/core/tests/queue.test.ts @@ -74,8 +74,9 @@ describe("JetQueue", () => { describe("Job States", () => { test("should track pending → running → completed", async () => { let stateDuringExecution = ""; - let resolveBlock1, resolveBlock2; - let resolveTrackedJob; + let resolveBlock1: (value?: unknown) => void = () => {}; + let resolveBlock2: (value?: unknown) => void = () => {}; + let resolveTrackedJob: (value?: unknown) => void = () => {}; const blockPromise1 = new Promise((resolve) => { resolveBlock1 = resolve; diff --git a/packages/core/tsconfig.json b/packages/core/tsconfig.json index 83880ca..a9b50ad 100644 --- a/packages/core/tsconfig.json +++ b/packages/core/tsconfig.json @@ -4,6 +4,7 @@ "outDir": "./dist", "types": ["bun"], "baseUrl": ".", + "rootDir": ".", "paths": { "@/*": ["./src/*"] } diff --git a/packages/dashboard/README.md b/packages/dashboard/README.md deleted file mode 100644 index e215bc4..0000000 --- a/packages/dashboard/README.md +++ /dev/null @@ -1,36 +0,0 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). - -## Getting Started - -First, run the development server: - -```bash -npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev -``` - -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. - -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. - -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. - -## Learn More - -To learn more about Next.js, take a look at the following resources: - -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. - -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! - -## Deploy on Vercel - -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. - -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. diff --git a/packages/dashboard/app/page.tsx b/packages/dashboard/app/page.tsx index 1e4b0db..7127d71 100644 --- a/packages/dashboard/app/page.tsx +++ b/packages/dashboard/app/page.tsx @@ -4,6 +4,7 @@ import ConnectionBadge from "@/components/ConnectionBadge"; import JobRow from "@/components/JobRow"; import StatsCard from "@/components/StatsCard"; import { useDashboard } from "@/hooks/useDashboard"; +import { JobWithDuration } from "@/types/type"; export default function Home() { const { stats, recentJobs, connected, error, refresh } = useDashboard(); @@ -126,7 +127,7 @@ export default function Home() { No jobs processed yet. Add jobs via the SDK or API. ) : ( - recentJobs.map((job, i) => ( + recentJobs.map((job: any, i: number) => (