bunqueue-client 0.1.3 → 0.1.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Egeo Minotti
+Copyright (c) 2026 Egeo Minotti
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -8,11 +8,11 @@ The bunqueue server runs on Bun, distributed as a binary or a Docker image. This
 
 | Runtime | Status | Notes |
 |---|---|---|
-| Node.js 20 or later | Supported, 72/72 e2e and 8/8 integration tests | ESM. TypeScript files run directly on Node 22 or later via `--experimental-strip-types` |
-| Bun | Supported, 72/72 e2e and 8/8 integration tests | No additional configuration required |
-| Deno 2 or later | Supported, 72/72 e2e and 8/8 integration tests | Uses `node:` builtins and the npm `msgpackr` package |
+| Node.js 20 or later | Supported, 81/81 e2e and 8/8 integration tests | ESM. TypeScript files run directly on Node 22 or later via `--experimental-strip-types` |
+| Bun | Supported, 81/81 e2e and 8/8 integration tests | No additional configuration required |
+| Deno 2 or later | Supported, 81/81 e2e and 8/8 integration tests | Uses `node:` builtins and the npm `msgpackr` package |
 | tsx, ts-node, vitest, jest | Supported | These environments execute on Node.js |
-| Cloudflare Workers | Supported, 11/11 e2e tests inside workerd | Requires the `nodejs_compat` compatibility flag. The runtime is request scoped, so long lived worker loops are not available: consume in batches from Cron Triggers or Durable Object alarms, a pattern covered by the test suite. TLS connections require a publicly trusted certificate |
+| Cloudflare Workers | Supported, 16/16 e2e tests inside workerd, including Simple Mode and the full API surface | Requires the `nodejs_compat` compatibility flag. The runtime is request scoped, so long lived worker loops are not available: consume in batches from Cron Triggers or Durable Object alarms, a pattern covered by the test suite. TLS connections require a publicly trusted certificate |
 | Browser | Not supported | Raw TCP sockets are unavailable. Use the server HTTP API instead |
 
 Portability is guaranteed by design: the client relies exclusively on `node:*` builtins (`net`, `tls`, `events`, `crypto`, `os`), uses no `Bun.*` globals and no runtime specific imports, and carries a single runtime dependency, `msgpackr`.
@@ -24,15 +24,37 @@ npm install bunqueue-client
 # or: bun add bunqueue-client / pnpm add bunqueue-client / deno add npm:bunqueue-client
 ```
 
-## Quick start
+## Quick start, step by step
 
-Sixty seconds from zero to a working queue. Step 1, start the server (requires [Bun](https://bun.sh), or use the Docker image):
+Every step from zero to a production ready queue.
+
+### Step 1. Run the bunqueue server
+
+The server is the only component that requires [Bun](https://bun.sh). Pick one:
 
 ```bash
+# Option A: one command, no install (requires Bun)
 bunx bunqueue start
+
+# Option B: Docker, with persistent data
+docker run -d --name bunqueue \
+  -p 6789:6789 -p 6790:6790 \
+  -v bunqueue-data:/app/data \
+  ghcr.io/egeominotti/bunqueue:latest
+```
+
+Port 6789 is the TCP protocol (what this client uses), port 6790 is the HTTP API with `/health`, `/metrics`, and dashboard endpoints.
+
+### Step 2. Install the client
+
+```bash
+npm install bunqueue-client
+# or: bun add bunqueue-client / pnpm add bunqueue-client / deno add npm:bunqueue-client
 ```
 
-Step 2, create `app.ts`: add a job and process it, in the same file for the sake of the demo:
+### Step 3. Add your first job and process it
+
+Create `app.ts`, one file for the sake of the demo:
 
 ```typescript
 import { Queue, Worker } from 'bunqueue-client';
@@ -51,7 +73,7 @@ await queue.add('greet', { name: 'world' });
 queue.close();
 ```
 
-Step 3, run it with the runtime you already use:
+Run it with the runtime you already use:
 
 ```bash
 node --experimental-strip-types app.ts    # Node 22 or later
@@ -66,7 +88,53 @@ processing { name: 'world' }
 completed 019f40a5-... { greeted: 'world' }
 ```
 
-That is the whole model: the server owns state, retries, and scheduling, your code only adds and processes. In production the producer and the worker are separate services, often in different languages: the [Python client](https://github.com/egeominotti/bunqueue/tree/main/sdk/python) speaks the same protocol against the same queue. Defaults are `host: 'localhost'`, `port: 6789`, so constructors need no options on a local setup.
+Defaults are `host: 'localhost'` and `port: 6789`, so constructors need no options on a local setup.
+
+### Step 4. Split producer and worker
+
+In production the producer and the worker are separate services, often in different languages. The producer is typically an API endpoint:
+
+```typescript
+// api-service: adds jobs, no processing
+import { Queue } from 'bunqueue-client';
+const queue = new Queue('emails', { host: 'queue.internal', port: 6789 });
+await queue.add('welcome', { to: 'user@example.com' }, { attempts: 3 });
+```
+
+The worker is a long running process:
+
+```typescript
+// worker-service: processes jobs, no HTTP
+import { Worker } from 'bunqueue-client';
+new Worker('emails', sendEmail, { host: 'queue.internal', port: 6789, concurrency: 10 });
+```
+
+The [Python client](https://github.com/egeominotti/bunqueue/tree/main/sdk/python) speaks the same protocol against the same queue, so the worker can be a Python service instead.
+
+### Step 5. Observe and operate
+
+```typescript
+await queue.getJobCounts();      // { waiting, active, completed, failed, delayed, ... }
+await queue.getDlq();            // jobs that exhausted their retries
+await queue.retryDlq();          // send them back to the queue
+await queue.getWorkers();        // connected workers
+await queue.getStats();          // throughput and totals
+```
+
+Or hit the HTTP side: `curl http://localhost:6790/health`.
+
+### Step 6. Go to production
+
+```typescript
+const queue = new Queue('emails', {
+  host: 'queue.example.com',
+  port: 6789,
+  token: process.env.BUNQUEUE_TOKEN,   // server started with AUTH_TOKENS=...
+  tls: true,                            // or { caFile: './ca.pem' }
+});
+```
+
+Checklist: set `AUTH_TOKENS` on the server, enable TLS (`TLS_CERT_FILE`/`TLS_KEY_FILE`), mount a volume for the SQLite data path, monitor `/health` and `/metrics`, and size worker `concurrency` to your workload. Full guide: [bunqueue.dev/guide/deployment](https://bunqueue.dev/guide/deployment/).
 
 ## Producing jobs
 

package/dist/bunqueue/bunqueue.js

@@ -105,8 +105,10 @@ export class Bunqueue {
     }
     // ------------------------------------------------- core processing pipeline
     async processJob(job) {
-        if (this.rateGate)
+        if (this.rateGate) {
+            this.rateGate.prune(); // evict fully-expired groups (high-cardinality groupKey)
             await this.rateGate.acquire(this.rateGate.groupFor(job.data));
+        }
         // Circuit breaker check
         if (this.cb?.isOpen()) {
             throw new Error('Circuit breaker is open');

package/dist/bunqueue/rate-gate.d.ts

@@ -18,4 +18,10 @@ export declare class RateGate {
     groupFor(data: unknown): string;
     /** Wait until the group's window has room, then record the start. */
     acquire(group: string): Promise<void>;
+    /**
+     * Drop groups whose window is fully expired. Called on each acquire cycle
+     * boundary by the owner; without it a high-cardinality groupKey (e.g. one
+     * group per user id) grows the map forever.
+     */
+    prune(): void;
 }

package/dist/bunqueue/rate-gate.js

@@ -45,4 +45,17 @@ export class RateGate {
             await sleep(Math.max(oldest + this.duration - now, 10));
         }
     }
+    /**
+     * Drop groups whose window is fully expired. Called on each acquire cycle
+     * boundary by the owner; without it a high-cardinality groupKey (e.g. one
+     * group per user id) grows the map forever.
+     */
+    prune() {
+        const now = Date.now();
+        for (const [group, window] of this.windows) {
+            if (window.length === 0 || now - window[window.length - 1] >= this.duration) {
+                this.windows.delete(group);
+            }
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue-client",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Cross-runtime TypeScript client for the bunqueue job queue server — Node.js, Bun, Deno and Cloudflare Workers",
   "license": "MIT",
   "type": "module",
@@ -29,7 +29,7 @@
     "lint": "biome lint src tests",
     "format": "biome format --write src tests",
     "check": "biome check src tests",
-    "test:workers": "bun pm pack --destination tests/workers && cd tests/workers && mv bunqueue-client-*.tgz bunqueue-client.tgz && bun install && node run.mjs"
+    "test:workers": "bun pm pack --destination tests/workers && cd tests/workers && mv bunqueue-client-*.tgz bunqueue-client.tgz && rm -rf node_modules/bunqueue-client bun.lock && bun install --force && node run.mjs"
   },
   "keywords": [
     "queue",

package/src/bunqueue/bunqueue.ts

@@ -120,7 +120,10 @@ export class Bunqueue<T = unknown, R = unknown> {
   // ------------------------------------------------- core processing pipeline
 
   private async processJob(job: Job<T>): Promise<R> {
-    if (this.rateGate) await this.rateGate.acquire(this.rateGate.groupFor(job.data));
+    if (this.rateGate) {
+      this.rateGate.prune(); // evict fully-expired groups (high-cardinality groupKey)
+      await this.rateGate.acquire(this.rateGate.groupFor(job.data));
+    }
     // Circuit breaker check
     if (this.cb?.isOpen()) {
       throw new Error('Circuit breaker is open');

package/src/bunqueue/rate-gate.ts

@@ -50,4 +50,18 @@ export class RateGate {
       await sleep(Math.max(oldest + this.duration - now, 10));
     }
   }
+
+  /**
+   * Drop groups whose window is fully expired. Called on each acquire cycle
+   * boundary by the owner; without it a high-cardinality groupKey (e.g. one
+   * group per user id) grows the map forever.
+   */
+  prune(): void {
+    const now = Date.now();
+    for (const [group, window] of this.windows) {
+      if (window.length === 0 || now - window[window.length - 1] >= this.duration) {
+        this.windows.delete(group);
+      }
+    }
+  }
 }