bunqueue-client 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to `bunqueue-client` (TypeScript SDK) are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.9] - 2026-07-14
+
+Conformance-suite driven: the SDK is now certified by the cross-language
+conformance kit (`sdk/conformance`, 17/17) against the formal wire spec
+(`docs/protocol.md`).
+
+### Fixed
+
+- **`drain()` now returns the number of removed jobs** (was `void`,
+  silently discarding the wire `count` — the "discarded return value"
+  class the conformance suite checks for).
+
+## [0.1.8] - 2026-07-14
+
+Spec-alignment audit against the core protocol. Every fix ships with a repro
+test in `tests/e2e-spec-align.ts`.
+
+### Fixed
+
+- **`heartbeatIntervalS: 0` now disables heartbeats.** Previously it armed
+  `setInterval(fn, 0)`, flooding the server with hundreds of `Heartbeat`
+  commands per second. `0` (or negative) now matches the official client's
+  "0 = disabled" semantics.
+- **`batchSize` is clamped to the server maximum (1000).** The server rejects
+  `PULLB` with `count > 1000`; an unclamped `batchSize` combined with
+  `concurrency > 1000` wedged the pull loop in a permanent error cycle.
+- **Simple Mode `cron()`/`every()` forward the execution `limit`.** The option
+  was silently dropped (the "client drops a wire-supported field" class,
+  #111); it now reaches the scheduler as wire `maxLimit`, matching the
+  official client's signature.
+- **`waitForJob()` clamps `ttlMs` to the server cap (600000).** Larger values
+  were rejected by the server with "timeout must be at most 600000" instead
+  of waiting.
+- **`PROTOCOL_VERSION` bumped to 2**, matching the version the server
+  advertises in `Hello`.
+
 ## [0.1.7] - 2026-07-10
 
 Audit fixes: typed worker events, error-path hygiene and two more members of

package/README.md

@@ -1,16 +1,43 @@
+<div align="center">
+
+<a href="https://bunqueue.dev">
+  <img src="https://raw.githubusercontent.com/egeominotti/bunqueue/main/.github/logo.png" alt="bunqueue logo" width="110" />
+</a>
+
 # bunqueue-client
 
-Official TypeScript client for [bunqueue](https://github.com/egeominotti/bunqueue), the high performance job queue server. The client implements the native TCP protocol (msgpack, pipelined) and provides full feature parity with the built in Bun client, while running on every modern JavaScript runtime.
+**The official TypeScript client for [bunqueue](https://bunqueue.dev), the high performance job queue server.**
+
+Native TCP protocol (msgpack, pipelined), full parity with the built in Bun client, one runtime dependency.
+Runs everywhere: Node.js, Bun, Deno and Cloudflare Workers.
+
+[![npm version](https://img.shields.io/npm/v/bunqueue-client?color=d3156d&label=npm)](https://www.npmjs.com/package/bunqueue-client)
+[![npm downloads](https://img.shields.io/npm/dm/bunqueue-client?color=ff4f9f)](https://www.npmjs.com/package/bunqueue-client)
+[![license](https://img.shields.io/npm/l/bunqueue-client?color=1a1a2e)](https://github.com/egeominotti/bunqueue/blob/main/sdk/typescript/LICENSE)
+[![runtimes](https://img.shields.io/badge/runtimes-node%20%7C%20bun%20%7C%20deno%20%7C%20workers-2ea44f)](#compatibility)
+
+[Documentation](https://bunqueue.dev/guide/sdks/) · [Server](https://github.com/egeominotti/bunqueue) · [Changelog](https://github.com/egeominotti/bunqueue/blob/main/sdk/typescript/CHANGELOG.md) · [Python SDK](https://github.com/egeominotti/bunqueue/tree/main/sdk/python)
+
+</div>
+
+---
 
 The bunqueue server runs on Bun, distributed as a binary or a Docker image. This client allows any Node.js, Bun, Deno, or Cloudflare Workers service to produce and consume jobs against it: one queue, any language, any runtime.
 
+## Why bunqueue-client
+
+- **Full API surface.** Queues, workers, flows (parent/children trees), schedulers, DLQ, rate limits, webhooks, Simple Mode: 110+ public methods, each covered by an e2e test against a real server.
+- **Cross runtime by design.** Only `node:*` builtins, zero `Bun.*` globals, a single dependency (`msgpackr`). The same package runs on Node 20+, Bun, Deno 2 and Cloudflare Workers (`nodejs_compat`).
+- **Production semantics.** Lock leasing with heartbeat renewal, at least once delivery with retries and backoff, unrecoverable failures straight to the DLQ, reconnection with half open detection, opt in ACK batching and connection pooling.
+- **Typed end to end.** Generic `Queue<T>` / `Worker<T, R>`, typed worker events, structured telemetry hooks for your metrics stack.
+
 ## Compatibility
 
 | Runtime | Status | Notes |
 |---|---|---|
-| Node.js 20 or later | Supported, 100/100 e2e and 8/8 integration tests | ESM. TypeScript files run directly on Node 22 or later via `--experimental-strip-types` |
-| Bun | Supported, 100/100 e2e and 8/8 integration tests | No additional configuration required |
-| Deno 2 or later | Supported, 100/100 e2e and 8/8 integration tests | Uses `node:` builtins and the npm `msgpackr` package |
+| Node.js 20 or later | Supported, 110/110 e2e and 8/8 integration tests | ESM. TypeScript files run directly on Node 22 or later via `--experimental-strip-types` |
+| Bun | Supported, 110/110 e2e and 8/8 integration tests | No additional configuration required |
+| Deno 2 or later | Supported, 110/110 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, 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 |

package/dist/bunqueue/bunqueue-api.d.ts

@@ -13,9 +13,11 @@ type Ctx = Bunqueue<any, any>;
 export declare const bunqueueApi: {
     cron(this: Ctx, id: string, pattern: string, data?: unknown, opts?: {
         timezone?: string;
+        limit?: number;
         jobOpts?: JobOptions;
     }): Promise<Raw | null>;
     every(this: Ctx, id: string, intervalMs: number, data?: unknown, opts?: {
+        limit?: number;
         jobOpts?: JobOptions;
     }): Promise<Raw | null>;
     removeCron(this: Ctx, id: string): Promise<void>;
@@ -50,9 +52,11 @@ export declare const bunqueueApi: {
 export interface BunqueueApi<T = unknown, R = unknown> {
     cron(id: string, pattern: string, data?: T, opts?: {
         timezone?: string;
+        limit?: number;
         jobOpts?: JobOptions;
     }): Promise<Raw | null>;
     every(id: string, intervalMs: number, data?: T, opts?: {
+        limit?: number;
         jobOpts?: JobOptions;
     }): Promise<Raw | null>;
     removeCron(id: string): Promise<void>;

package/dist/bunqueue/bunqueue-api.js

@@ -6,11 +6,11 @@
 export const bunqueueApi = {
     // --------------------------------------------------------------------- cron
     async cron(id, pattern, data, opts) {
-        await this.queue.upsertJobScheduler(id, { pattern, tz: opts?.timezone }, { name: id, data, opts: opts?.jobOpts });
+        await this.queue.upsertJobScheduler(id, { pattern, tz: opts?.timezone, limit: opts?.limit }, { name: id, data, opts: opts?.jobOpts });
         return this.queue.getJobScheduler(id);
     },
     async every(id, intervalMs, data, opts) {
-        await this.queue.upsertJobScheduler(id, { every: intervalMs }, { name: id, data, opts: opts?.jobOpts });
+        await this.queue.upsertJobScheduler(id, { every: intervalMs, limit: opts?.limit }, { name: id, data, opts: opts?.jobOpts });
         return this.queue.getJobScheduler(id);
     },
     removeCron(id) {

package/dist/frame.d.ts

@@ -2,7 +2,7 @@
  * Wire framing for the bunqueue TCP protocol: 4-byte big-endian length
  * prefix + msgpack payload. Runtime-neutral (plain Buffer operations).
  */
-export declare const PROTOCOL_VERSION = 1;
+export declare const PROTOCOL_VERSION = 2;
 export declare const MAX_FRAME_SIZE: number;
 /** Drop undefined-valued keys so the msgpack frame stays minimal. */
 export declare function compact<T extends Record<string, unknown>>(obj: T): T;

package/dist/frame.js

@@ -3,7 +3,7 @@
  * prefix + msgpack payload. Runtime-neutral (plain Buffer operations).
  */
 import { ConnectionClosedError } from './errors.js';
-export const PROTOCOL_VERSION = 1;
+export const PROTOCOL_VERSION = 2;
 export const MAX_FRAME_SIZE = 64 * 1024 * 1024; // mirror server-side limit
 /** Drop undefined-valued keys so the msgpack frame stays minimal. */
 export function compact(obj) {

package/dist/queue-control.d.ts

@@ -9,7 +9,8 @@ export declare const controlMethods: {
     pause(this: Ctx): Promise<void>;
     resume(this: Ctx): Promise<void>;
     isPaused(this: Ctx): Promise<boolean>;
-    drain(this: Ctx): Promise<void>;
+    /** Remove all waiting/delayed jobs; returns how many were dropped. */
+    drain(this: Ctx): Promise<number>;
     obliterate(this: Ctx): Promise<void>;
     /** Remove old jobs; returns how many were removed. */
     clean(this: Ctx, graceMs: number, limit?: number, state?: JobStateName): Promise<number>;

package/dist/queue-control.js

@@ -15,8 +15,10 @@ export const controlMethods = {
     async isPaused() {
         return (await this.call({ cmd: 'IsPaused', queue: this.name })).paused === true;
     },
+    /** Remove all waiting/delayed jobs; returns how many were dropped. */
     async drain() {
-        await this.call({ cmd: 'Drain', queue: this.name });
+        const response = await this.call({ cmd: 'Drain', queue: this.name });
+        return response.count ?? 0;
     },
     async obliterate() {
         await this.call({ cmd: 'Obliterate', queue: this.name });

package/dist/queue-query.js

@@ -106,6 +106,8 @@ export const queryMethods = {
      * will not complete), everything else throws CommandTimeoutError.
      */
     async waitForJob(id, ttlMs = 30_000) {
+        // The server validates 0 <= timeout <= 600000: clamp instead of erroring.
+        ttlMs = Math.min(Math.max(ttlMs, 0), 600_000);
         const response = await this.call({ cmd: 'WaitJob', id, timeout: ttlMs }, ttlMs + 5000);
         if (response.completed !== true) {
             let state;

package/dist/worker-base.js

@@ -38,7 +38,11 @@ export class WorkerBase extends EventEmitter {
             throw new Error('concurrency must be >= 1');
         this.queue = queue;
         this.concurrency = opts.concurrency ?? 4;
-        this.batchSize = Math.max(1, opts.batchSize ?? 10);
+        // The server rejects PULLB count > 1000 (handlers/core.ts) — an unclamped
+        // batchSize would wedge the pull loop in a permanent error cycle. The
+        // finite-guard also catches NaN, which would otherwise pass both bounds.
+        const rawBatch = opts.batchSize ?? 10;
+        this.batchSize = Number.isFinite(rawBatch) ? Math.min(Math.max(1, rawBatch), 1000) : 10;
         this.pollTimeoutMs = Math.min(opts.pollTimeoutMs ?? 5000, MAX_POLL_TIMEOUT_MS);
         this.lockTtlMs = opts.lockTtlMs ?? 30_000;
         this.heartbeatIntervalS = opts.heartbeatIntervalS ?? 10;

package/dist/worker-types.d.ts

@@ -51,13 +51,13 @@ export interface WorkerOptions extends Observability {
     ackBatch?: AckBatchOptions;
     /** Max jobs processed in parallel (default 4). */
     concurrency?: number;
-    /** Max jobs fetched per PULLB (default 10, capped by free slots). */
+    /** Max jobs fetched per PULLB (default 10, capped by free slots and the server max 1000). */
     batchSize?: number;
     /** Server-side long-poll timeout in ms (default 5000, max 30000). */
     pollTimeoutMs?: number;
     /** Job lock TTL in ms (default 30000). */
     lockTtlMs?: number;
-    /** Worker + job heartbeat interval in seconds (default 10). */
+    /** Worker + job heartbeat interval in seconds (default 10, 0 = disabled). */
     heartbeatIntervalS?: number;
     /** Start the loop at construction (default true, mirrors the TS client). */
     autorun?: boolean;

package/dist/worker.js

@@ -172,6 +172,11 @@ export class Worker extends WorkerBase {
     }
     // --------------------------------------------------------------- heartbeat
     startHeartbeat() {
+        // 0, negative or non-finite (NaN coerces to interval 0) disables
+        // heartbeats — setInterval(fn, 0) would fire every macrotask and flood
+        // the server with Heartbeat commands.
+        if (!(Number.isFinite(this.heartbeatIntervalS) && this.heartbeatIntervalS > 0))
+            return;
         this.heartbeatTimer = setInterval(() => {
             void (async () => {
                 await this.safeCall({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue-client",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Cross-runtime TypeScript client for the bunqueue job queue server — Node.js, Bun, Deno and Cloudflare Workers",
   "license": "MIT",
   "type": "module",

package/src/bunqueue/bunqueue-api.ts

@@ -22,11 +22,11 @@ export const bunqueueApi = {
     id: string,
     pattern: string,
     data?: unknown,
-    opts?: { timezone?: string; jobOpts?: JobOptions }
+    opts?: { timezone?: string; limit?: number; jobOpts?: JobOptions }
   ): Promise<Raw | null> {
     await this.queue.upsertJobScheduler(
       id,
-      { pattern, tz: opts?.timezone },
+      { pattern, tz: opts?.timezone, limit: opts?.limit },
       { name: id, data, opts: opts?.jobOpts }
     );
     return this.queue.getJobScheduler(id);
@@ -37,11 +37,11 @@ export const bunqueueApi = {
     id: string,
     intervalMs: number,
     data?: unknown,
-    opts?: { jobOpts?: JobOptions }
+    opts?: { limit?: number; jobOpts?: JobOptions }
   ): Promise<Raw | null> {
     await this.queue.upsertJobScheduler(
       id,
-      { every: intervalMs },
+      { every: intervalMs, limit: opts?.limit },
       { name: id, data, opts: opts?.jobOpts }
     );
     return this.queue.getJobScheduler(id);
@@ -173,13 +173,13 @@ export interface BunqueueApi<T = unknown, R = unknown> {
     id: string,
     pattern: string,
     data?: T,
-    opts?: { timezone?: string; jobOpts?: JobOptions }
+    opts?: { timezone?: string; limit?: number; jobOpts?: JobOptions }
   ): Promise<Raw | null>;
   every(
     id: string,
     intervalMs: number,
     data?: T,
-    opts?: { jobOpts?: JobOptions }
+    opts?: { limit?: number; jobOpts?: JobOptions }
   ): Promise<Raw | null>;
   removeCron(id: string): Promise<void>;
   listCrons(): Promise<Raw[]>;

package/src/frame.ts

@@ -5,7 +5,7 @@
 
 import { ConnectionClosedError } from './errors.js';
 
-export const PROTOCOL_VERSION = 1;
+export const PROTOCOL_VERSION = 2;
 export const MAX_FRAME_SIZE = 64 * 1024 * 1024; // mirror server-side limit
 
 /** Drop undefined-valued keys so the msgpack frame stays minimal. */

package/src/queue-control.ts

@@ -25,8 +25,10 @@ export const controlMethods = {
     return (await this.call<PausedResponse>({ cmd: 'IsPaused', queue: this.name })).paused === true;
   },
 
-  async drain(this: Ctx): Promise<void> {
-    await this.call({ cmd: 'Drain', queue: this.name });
+  /** Remove all waiting/delayed jobs; returns how many were dropped. */
+  async drain(this: Ctx): Promise<number> {
+    const response = await this.call<{ count?: number }>({ cmd: 'Drain', queue: this.name });
+    return response.count ?? 0;
   },
 
   async obliterate(this: Ctx): Promise<void> {

package/src/queue-query.ts

@@ -148,6 +148,8 @@ export const queryMethods = {
    * will not complete), everything else throws CommandTimeoutError.
    */
   async waitForJob<R = unknown>(this: Ctx, id: string, ttlMs = 30_000): Promise<R> {
+    // The server validates 0 <= timeout <= 600000: clamp instead of erroring.
+    ttlMs = Math.min(Math.max(ttlMs, 0), 600_000);
     const response = await this.call<WaitJobResponse<R>>(
       { cmd: 'WaitJob', id, timeout: ttlMs },
       ttlMs + 5000

package/src/worker-base.ts

@@ -46,7 +46,11 @@ export class WorkerBase<T = unknown, R = unknown> extends EventEmitter {
     if ((opts.concurrency ?? 4) < 1) throw new Error('concurrency must be >= 1');
     this.queue = queue;
     this.concurrency = opts.concurrency ?? 4;
-    this.batchSize = Math.max(1, opts.batchSize ?? 10);
+    // The server rejects PULLB count > 1000 (handlers/core.ts) — an unclamped
+    // batchSize would wedge the pull loop in a permanent error cycle. The
+    // finite-guard also catches NaN, which would otherwise pass both bounds.
+    const rawBatch = opts.batchSize ?? 10;
+    this.batchSize = Number.isFinite(rawBatch) ? Math.min(Math.max(1, rawBatch), 1000) : 10;
     this.pollTimeoutMs = Math.min(opts.pollTimeoutMs ?? 5000, MAX_POLL_TIMEOUT_MS);
     this.lockTtlMs = opts.lockTtlMs ?? 30_000;
     this.heartbeatIntervalS = opts.heartbeatIntervalS ?? 10;

package/src/worker-types.ts

@@ -53,13 +53,13 @@ export interface WorkerOptions extends Observability {
   ackBatch?: AckBatchOptions;
   /** Max jobs processed in parallel (default 4). */
   concurrency?: number;
-  /** Max jobs fetched per PULLB (default 10, capped by free slots). */
+  /** Max jobs fetched per PULLB (default 10, capped by free slots and the server max 1000). */
   batchSize?: number;
   /** Server-side long-poll timeout in ms (default 5000, max 30000). */
   pollTimeoutMs?: number;
   /** Job lock TTL in ms (default 30000). */
   lockTtlMs?: number;
-  /** Worker + job heartbeat interval in seconds (default 10). */
+  /** Worker + job heartbeat interval in seconds (default 10, 0 = disabled). */
   heartbeatIntervalS?: number;
   /** Start the loop at construction (default true, mirrors the TS client). */
   autorun?: boolean;

package/src/worker.ts

@@ -197,6 +197,10 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase<T, R> {
   // --------------------------------------------------------------- heartbeat
 
   private startHeartbeat(): void {
+    // 0, negative or non-finite (NaN coerces to interval 0) disables
+    // heartbeats — setInterval(fn, 0) would fire every macrotask and flood
+    // the server with Heartbeat commands.
+    if (!(Number.isFinite(this.heartbeatIntervalS) && this.heartbeatIntervalS > 0)) return;
     this.heartbeatTimer = setInterval(() => {
       void (async () => {
         await this.safeCall({