bunqueue-client 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -5,6 +5,72 @@ 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.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
+the "client drops a wire-supported field" class (#111).
+
+### Added
+
+- **Typed Worker events.** `worker.on('completed', (job, result) => ...)` now
+  gets typed `Job<T>`/`R`/`Error` parameters in strict mode instead of
+  `unknown[]` (TS18046). The new `WorkerEventMap<T, R>` covers `ready`,
+  `active`, `completed`, `failed`, `progress`, `error`, `drained`, `cancelled`
+  and `closed`; unknown event names keep a generic overload, so existing code
+  compiles unchanged. (H1)
+- `"prepublishOnly": "bun run build"` so a publish can never ship a stale
+  `dist/`. (H3)
+
+### Fixed
+
+- **Bunqueue constructor crash vector.** `new Bunqueue(..., { dlq })` fired
+  `setDlqConfig` with no rejection handler: an unreachable server at
+  construction time killed the process with an unhandled rejection. The
+  failure now routes to the worker's `'error'` event (swallowed when no
+  listener is attached, matching `pause()`/`resume()`). (H2)
+- **ACK/completed asymmetry.** In the non-batched path the worker emitted
+  `'completed'` and incremented `processed` even when the ACK never reached
+  the server. Both the ACK and FAIL paths now mirror the batched semantics:
+  on a wire failure only `'error'` fires, with no counter increment. Errors
+  emitted on `'error'` are now always `Error` instances. (M1)
+- **Not-found swallowing.** `getJobScheduler`, `getJob` and
+  `getJobByCustomId` caught every error (including `ConnectionClosedError`
+  and `CommandTimeoutError`) and returned `null`. The catch is narrowed to a
+  `CommandError` matching `/not found/i`; everything else rethrows. (M2)
+- **Scheduler template priority/deduplication dropped.**
+  `upsertJobScheduler` put `priority` inside `jobOptions`, where the server's
+  `CronJobOptions` ignores it, and never sent the template's deduplication.
+  Both now travel as the top-level `priority`/`uniqueKey`/`dedup` Cron fields
+  the handler reads, matching the reference client. (#111 class, F3)
+- **moveJobToFailed lost the stack and the unrecoverable flag.** It sent only
+  `error.message`; when given an `Error` it now sends the leading stack lines
+  and `unrecoverable: true` for `UnrecoverableError`, mirroring the worker
+  FAIL path. (#111 class, F4)
+
 ## [0.1.6] - 2026-07-09
 
 Enterprise-grade hardening. All additive and backward-compatible; defaults are
@@ -33,8 +99,8 @@ unchanged (observability is silent, backpressure unbounded, ACK batching off).
 ### CI
 
 - GitHub Actions runs both SDK suites on every `sdk/`/`src/` change (TypeScript
-  on Bun + Node, Python 3.10/3.12); an npm release workflow publishes with
-  build provenance.
+  on Bun + Node + Deno, Python 3.10/3.12); an npm release workflow publishes
+  with build provenance, gated on the e2e suite.
 
 ## [0.1.5] - 2026-07-08
 

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, 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 |
+| 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/bunqueue/bunqueue.js

@@ -76,8 +76,18 @@ export class Bunqueue {
         });
         // DLQ & rate limit manager
         this.dlqrl = new DlqRateLimitManager(this.queue);
-        if (opts.dlq)
-            void this.dlqrl.setDlqConfig(opts.dlq);
+        // Fire-and-forget config push: without the catch, an unreachable server at
+        // construction time becomes an unhandled rejection that kills the process.
+        // Route the failure to the worker's 'error' event (the channel every other
+        // background command failure uses); with no listener attached, swallow it
+        // like pause()/resume() do — an unlistened 'error' emit would itself throw.
+        if (opts.dlq) {
+            void this.dlqrl.setDlqConfig(opts.dlq).catch((err) => {
+                if (this.worker.listenerCount('error') > 0) {
+                    this.worker.emit('error', err instanceof Error ? err : new Error(String(err)));
+                }
+            });
+        }
         // Subsystems
         this.cb = opts.circuitBreaker
             ? new WorkerCircuitBreaker(opts.circuitBreaker, this.worker)

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/index.d.ts

@@ -23,5 +23,5 @@ export type { SchedulerOptions } from './queue-admin.js';
 export type { BatchResponse, CountResponse, DataResponse, JobCountsResponse, JobResponse, JobsResponse, OkResponse, PausedResponse, ProgressResponse, PulledJobResponse, PulledJobsResponse, ResultResponse, StateResponse, WaitJobResponse, } from './responses.js';
 export type { BackoffOptions, DeduplicationOptions, JobCounts, JobOptions, JobStateName, RepeatOptions, } from './types.js';
 export { Worker } from './worker.js';
-export type { AckBatchOptions, Processor, WorkerOptions } from './worker-types.js';
-export declare const __version__ = "0.1.6";
+export type { AckBatchOptions, Processor, WorkerEventMap, WorkerOptions, } from './worker-types.js';
+export declare const __version__ = "0.1.7";

package/dist/index.js

@@ -13,4 +13,4 @@ export { Job } from './job.js';
 export { consoleLogger, noopLogger } from './observability.js';
 export { Queue } from './queue.js';
 export { Worker } from './worker.js';
-export const __version__ = '0.1.6';
+export const __version__ = '0.1.7';

package/dist/queue-admin.js

@@ -2,6 +2,7 @@
  * Queue admin surface: DLQ, stall/DLQ configs, rate limits, schedulers,
  * monitoring and webhooks. Merged onto Queue.prototype by queue.ts.
  */
+import { CommandError } from './errors.js';
 import { compact } from './frame.js';
 import { jobPayload, wireJobOptions } from './types.js';
 export const adminMethods = {
@@ -50,6 +51,10 @@ export const adminMethods = {
     // ---------------------------------------------------------------- scheduler
     /** Create/update a recurring job scheduler (cron pattern or fixed interval). */
     async upsertJobScheduler(schedulerId, repeat, template = {}) {
+        // Priority and deduplication of spawned jobs travel as TOP-LEVEL Cron
+        // fields (the handler reads cmd.priority/uniqueKey/dedup); inside
+        // jobOptions the server's CronJobOptions silently ignores them.
+        const dedup = template.opts?.deduplication;
         await this.call(compact({
             cmd: 'Cron',
             name: schedulerId,
@@ -57,9 +62,14 @@ export const adminMethods = {
             data: jobPayload(template.name ?? schedulerId, template.data ?? {}),
             schedule: repeat.pattern,
             repeatEvery: repeat.every,
+            priority: template.opts?.priority,
             timezone: repeat.tz,
             immediately: repeat.immediately,
             maxLimit: repeat.limit,
+            uniqueKey: dedup?.id,
+            dedup: dedup
+                ? compact({ ttl: dedup.ttl, extend: dedup.extend, replace: dedup.replace })
+                : undefined,
             skipMissedOnRestart: repeat.skipMissedOnRestart,
             skipIfNoWorker: repeat.skipIfNoWorker,
             preventOverlap: repeat.preventOverlap,
@@ -74,8 +84,12 @@ export const adminMethods = {
             const response = await this.call({ cmd: 'CronGet', name: schedulerId });
             return (response.cron ?? response.data ?? null);
         }
-        catch {
-            return null; // not-found surfaces as a CommandError
+        catch (err) {
+            // Only 'Cron job not found' maps to null; connection loss, timeouts and
+            // real server errors must surface, not masquerade as a missing scheduler.
+            if (err instanceof CommandError && /not found/i.test(err.message))
+                return null;
+            throw err;
         }
     },
     async getJobSchedulers() {

package/dist/queue-control.d.ts

@@ -38,6 +38,11 @@ export declare const controlMethods: {
     moveJobToDelayed(this: Ctx, id: string, delayMs: number): Promise<void>;
     extendJobLock(this: Ctx, id: string, token: string, durationMs: number): Promise<void>;
     moveJobToCompleted(this: Ctx, id: string, returnValue: unknown, token?: string): Promise<void>;
+    /**
+     * Explicit failure path: mirrors the worker's FAIL wire so the stacktrace
+     * and the UnrecoverableError "do not retry" intent are persisted (#111
+     * silent-loss class), not just the message.
+     */
     moveJobToFailed(this: Ctx, id: string, error: Error | string, token?: string): Promise<void>;
 };
 export type QueueControlApi = typeof controlMethods;

package/dist/queue-control.js

@@ -2,7 +2,9 @@
  * Queue control surface: pause/drain/clean, promotion, retry and per-job
  * mutations. Methods are merged onto Queue.prototype by queue.ts.
  */
+import { UnrecoverableError } from './errors.js';
 import { compact } from './frame.js';
+import { MAX_STACK_LINES } from './worker-types.js';
 export const controlMethods = {
     async pause() {
         await this.call({ cmd: 'Pause', queue: this.name });
@@ -47,9 +49,9 @@ export const controlMethods = {
             await this.call({ cmd: 'RetryCompleted', queue: this.name });
             return;
         }
-        // `count` is accepted for API parity but not sent: the server has no
-        // partial RetryDlq — it retries the whole DLQ (BullMQ semantics).
-        await this.call({ cmd: 'RetryDlq', queue: this.name });
+        // `count` caps how many DLQ entries are retried (server >= 2.8.29). Older
+        // servers ignore the field and retry the whole DLQ — forward-compatible.
+        await this.call(compact({ cmd: 'RetryDlq', queue: this.name, count: opts.count }));
     },
     async retryCompleted(id) {
         await this.call(compact({ cmd: 'RetryCompleted', queue: this.name, id }));
@@ -79,8 +81,25 @@ export const controlMethods = {
     async moveJobToCompleted(id, returnValue, token) {
         await this.call(compact({ cmd: 'ACK', id, result: returnValue, token }));
     },
+    /**
+     * Explicit failure path: mirrors the worker's FAIL wire so the stacktrace
+     * and the UnrecoverableError "do not retry" intent are persisted (#111
+     * silent-loss class), not just the message.
+     */
     async moveJobToFailed(id, error, token) {
-        const message = typeof error === 'string' ? error : error.message;
-        await this.call(compact({ cmd: 'FAIL', id, error: message, token }));
+        const err = typeof error === 'string' ? undefined : error;
+        const message = err ? err.message || err.name : error;
+        // Keep the FIRST lines (message + throw site), like the worker path.
+        const stack = err
+            ? (err.stack ?? err.message).split('\n').slice(0, MAX_STACK_LINES)
+            : undefined;
+        await this.call(compact({
+            cmd: 'FAIL',
+            id,
+            error: message,
+            stack,
+            unrecoverable: err instanceof UnrecoverableError ? true : undefined,
+            token,
+        }));
     },
 };

package/dist/queue-query.js

@@ -16,8 +16,10 @@ export const queryMethods = {
             return response.job ? new Job(response.job, this.connection) : null;
         }
         catch (err) {
-            if (err instanceof CommandError)
-                return null; // server: 'Job not found'
+            // Only the server's 'Job not found' maps to null; connection loss,
+            // timeouts and other server errors must surface.
+            if (err instanceof CommandError && /not found/i.test(err.message))
+                return null;
             throw err;
         }
     },
@@ -27,7 +29,7 @@ export const queryMethods = {
             return response.job ? new Job(response.job, this.connection) : null;
         }
         catch (err) {
-            if (err instanceof CommandError)
+            if (err instanceof CommandError && /not found/i.test(err.message))
                 return null;
             throw err;
         }
@@ -104,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.d.ts

@@ -4,8 +4,8 @@
  */
 import { EventEmitter } from 'node:events';
 import { Connection } from './connection.js';
-import { type WorkerOptions } from './worker-types.js';
-export declare class WorkerBase extends EventEmitter {
+import { type WorkerEventMap, type WorkerOptions } from './worker-types.js';
+export declare class WorkerBase<T = unknown, R = unknown> extends EventEmitter {
     readonly queue: string;
     readonly concurrency: number;
     readonly batchSize: number;
@@ -41,9 +41,16 @@ export declare class WorkerBase extends EventEmitter {
      * 'ready' is replayed to listeners attached after it fired: with autorun the
      * loop starts inside the constructor, so a plain once-only event could be
      * missed by `new Worker(...).on('ready', ...)` patterns.
+     *
+     * The overloads give the known worker events typed parameters (see
+     * WorkerEventMap); unknown event names keep the generic signature.
      */
+    on<E extends keyof WorkerEventMap<T, R>>(event: E, listener: WorkerEventMap<T, R>[E]): this;
     on(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    once<E extends keyof WorkerEventMap<T, R>>(event: E, listener: WorkerEventMap<T, R>[E]): this;
     once(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    off<E extends keyof WorkerEventMap<T, R>>(event: E, listener: WorkerEventMap<T, R>[E]): this;
+    off(event: string | symbol, listener: (...args: unknown[]) => void): this;
     /**
      * Cooperative cancel of a locally active job (mirrors the official client):
      * marks the job and emits 'cancelled'; the processor is expected to check
@@ -56,9 +63,12 @@ export declare class WorkerBase extends EventEmitter {
      * With `force` the wait for in-flight jobs is skipped (parity with the
      * official client's `close(force)`). */
     close(force?: boolean): Promise<void>;
+    /** Dispatch a command, routing failures to 'error'. Returns whether the
+     * command reached the server — callers gate success-only side effects
+     * ('completed'/'failed' emits, counters) on it. */
     protected safeCall(command: Record<string, unknown> & {
         cmd: string;
-    }): Promise<void>;
+    }): Promise<boolean>;
     /** Hook run during close() before draining in-flight jobs (see Worker). */
     protected beforeClose(): Promise<void>;
 }

package/dist/worker-base.js

@@ -6,7 +6,7 @@ import { randomBytes } from 'node:crypto';
 import { EventEmitter } from 'node:events';
 import { hostname } from 'node:os';
 import { Connection } from './connection.js';
-import { MAX_POLL_TIMEOUT_MS, sleep } from './worker-types.js';
+import { MAX_POLL_TIMEOUT_MS, sleep, } from './worker-types.js';
 export class WorkerBase extends EventEmitter {
     queue;
     concurrency;
@@ -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;
@@ -74,11 +78,6 @@ export class WorkerBase extends EventEmitter {
     async waitUntilReady() {
         await this.readyPromise;
     }
-    /**
-     * 'ready' is replayed to listeners attached after it fired: with autorun the
-     * loop starts inside the constructor, so a plain once-only event could be
-     * missed by `new Worker(...).on('ready', ...)` patterns.
-     */
     on(event, listener) {
         if (event === 'ready' && this.readyFired)
             listener();
@@ -91,6 +90,9 @@ export class WorkerBase extends EventEmitter {
         }
         return super.once(event, listener);
     }
+    off(event, listener) {
+        return super.off(event, listener);
+    }
     /**
      * Cooperative cancel of a locally active job (mirrors the official client):
      * marks the job and emits 'cancelled'; the processor is expected to check
@@ -139,12 +141,17 @@ export class WorkerBase extends EventEmitter {
         this.running = false;
         this.emit('closed');
     }
+    /** Dispatch a command, routing failures to 'error'. Returns whether the
+     * command reached the server — callers gate success-only side effects
+     * ('completed'/'failed' emits, counters) on it. */
     async safeCall(command) {
         try {
             await this.connection.call(command);
+            return true;
         }
         catch (err) {
-            this.emit('error', err);
+            this.emit('error', err instanceof Error ? err : new Error(String(err)));
+            return false;
         }
     }
     /** Hook run during close() before draining in-flight jobs (see Worker). */

package/dist/worker-types.d.ts

@@ -3,6 +3,34 @@ import type { TlsOption } from './connection.js';
 import type { Job } from './job.js';
 import type { Observability } from './observability.js';
 export type Processor<T = unknown, R = unknown> = (job: Job<T>) => R | Promise<R>;
+/**
+ * Typed Worker event map: listeners registered via `on`/`once`/`off` for these
+ * names get typed job/result/error parameters in strict mode. Unknown event
+ * names fall back to a generic `(...args: unknown[])` overload.
+ */
+export interface WorkerEventMap<T = unknown, R = unknown> {
+    /** Worker registered and pull loop started (replayed to late listeners). */
+    ready: () => void;
+    /** A job was pulled and handed to the processor. */
+    active: (job: Job<T>) => void;
+    /** Processor resolved AND the ACK reached the server. */
+    completed: (job: Job<T>, result: R) => void;
+    /** Processor threw AND the FAIL reached the server. */
+    failed: (job: Job<T>, error: Error) => void;
+    /** job.updateProgress() was called from the processor. */
+    progress: (job: Job<T>, progress: number) => void;
+    /** Connection/command error (pull loop, ACK/FAIL, heartbeat, ...). */
+    error: (error: Error) => void;
+    /** The queue went from busy to empty (no active jobs, nothing pulled). */
+    drained: () => void;
+    /** Cooperative cancel was requested for a locally active job. */
+    cancelled: (info: {
+        jobId: string;
+        reason: string;
+    }) => void;
+    /** close() finished. */
+    closed: () => void;
+}
 export interface AckBatchOptions {
     /** Batch ACKs into ACKB round-trips (default false; opt-in for throughput). */
     enabled?: boolean;
@@ -23,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.d.ts

@@ -7,7 +7,7 @@
  */
 import { WorkerBase } from './worker-base.js';
 import { type Processor, type WorkerOptions } from './worker-types.js';
-export declare class Worker<T = unknown, R = unknown> extends WorkerBase {
+export declare class Worker<T = unknown, R = unknown> extends WorkerBase<T, R> {
     private readonly processor;
     private readonly ackBatcher;
     constructor(queue: string, processor: Processor<T, R>, opts?: WorkerOptions);

package/dist/worker.js

@@ -36,7 +36,7 @@ export class Worker extends WorkerBase {
             return;
         this.running = true;
         this.loopPromise = this.loop().catch((err) => {
-            this.emit('error', err);
+            this.emit('error', err instanceof Error ? err : new Error(String(err)));
         });
     }
     // -------------------------------------------------------------------- loop
@@ -57,7 +57,7 @@ export class Worker extends WorkerBase {
                 backoffIdx = 0;
             }
             catch (err) {
-                this.emit('error', err);
+                this.emit('error', err instanceof Error ? err : new Error(String(err)));
                 if (err instanceof ConnectionClosedError || err instanceof CommandTimeoutError) {
                     const delay = RECONNECT_BACKOFF_MS[Math.min(backoffIdx, RECONNECT_BACKOFF_MS.length - 1)];
                     backoffIdx += 1;
@@ -123,7 +123,7 @@ export class Worker extends WorkerBase {
                     onSettled: (err) => {
                         this.finishJob(job.id);
                         if (err) {
-                            this.emit('error', err);
+                            this.emit('error', err instanceof Error ? err : new Error(String(err)));
                         }
                         else {
                             this.processed += 1;
@@ -133,20 +133,23 @@ export class Worker extends WorkerBase {
                 });
                 return;
             }
-            this.processed += 1;
-            await this.safeCall(compact({ cmd: 'ACK', id: job.id, token, result: result ?? undefined }));
+            const acked = await this.safeCall(compact({ cmd: 'ACK', id: job.id, token, result: result ?? undefined }));
             // Free the slot BEFORE emitting: a throwing 'completed' listener must
             // not leak the active slot (same rationale as the batched path).
             this.finishJob(job.id);
-            this.emit('completed', job, result);
+            // Mirror the batched path: a failed ACK already emitted 'error' — do not
+            // also claim completion (no 'completed', no processed++).
+            if (acked) {
+                this.processed += 1;
+                this.emit('completed', job, result);
+            }
         }
         catch (err) {
-            this.failedCount += 1;
             const error = err instanceof Error ? err : new Error(String(err));
             // Keep the FIRST lines: in a JS stack the message + throw site lead, so
             // slice(0,N) preserves them (slice(-N) would drop them on long stacks).
             const stack = (error.stack ?? error.message).split('\n').slice(0, MAX_STACK_LINES);
-            await this.safeCall(compact({
+            const failed = await this.safeCall(compact({
                 cmd: 'FAIL',
                 id: job.id,
                 token,
@@ -155,7 +158,12 @@ export class Worker extends WorkerBase {
                 unrecoverable: err instanceof UnrecoverableError ? true : undefined,
             }));
             this.finishJob(job.id);
-            this.emit('failed', job, error);
+            // Same asymmetry guard as the ACK path: if the FAIL never reached the
+            // server, only 'error' fires (the lock expiry will retry the job).
+            if (failed) {
+                this.failedCount += 1;
+                this.emit('failed', job, error);
+            }
         }
     }
     finishJob(id) {
@@ -164,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.6",
+  "version": "0.1.8",
   "description": "Cross-runtime TypeScript client for the bunqueue job queue server — Node.js, Bun, Deno and Cloudflare Workers",
   "license": "MIT",
   "type": "module",
@@ -25,6 +25,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "bun run build",
     "test": "bun tests/e2e.ts",
     "test:integration": "bun tests/integration.ts",
     "lint": "biome lint src tests",

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/bunqueue/bunqueue.ts

@@ -90,7 +90,18 @@ export class Bunqueue<T = unknown, R = unknown> {
 
     // DLQ & rate limit manager
     this.dlqrl = new DlqRateLimitManager<T>(this.queue);
-    if (opts.dlq) void this.dlqrl.setDlqConfig(opts.dlq);
+    // Fire-and-forget config push: without the catch, an unreachable server at
+    // construction time becomes an unhandled rejection that kills the process.
+    // Route the failure to the worker's 'error' event (the channel every other
+    // background command failure uses); with no listener attached, swallow it
+    // like pause()/resume() do — an unlistened 'error' emit would itself throw.
+    if (opts.dlq) {
+      void this.dlqrl.setDlqConfig(opts.dlq).catch((err: unknown) => {
+        if (this.worker.listenerCount('error') > 0) {
+          this.worker.emit('error', err instanceof Error ? err : new Error(String(err)));
+        }
+      });
+    }
 
     // Subsystems
     this.cb = opts.circuitBreaker

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/index.ts

@@ -83,6 +83,11 @@ export type {
   RepeatOptions,
 } from './types.js';
 export { Worker } from './worker.js';
-export type { AckBatchOptions, Processor, WorkerOptions } from './worker-types.js';
+export type {
+  AckBatchOptions,
+  Processor,
+  WorkerEventMap,
+  WorkerOptions,
+} from './worker-types.js';
 
-export const __version__ = '0.1.6';
+export const __version__ = '0.1.7';

package/src/queue-admin.ts

@@ -3,6 +3,7 @@
  * monitoring and webhooks. Merged onto Queue.prototype by queue.ts.
  */
 
+import { CommandError } from './errors.js';
 import { compact } from './frame.js';
 import type { Queue } from './queue.js';
 import { type JobOptions, jobPayload, wireJobOptions } from './types.js';
@@ -95,6 +96,10 @@ export const adminMethods = {
     repeat: SchedulerOptions,
     template: { name?: string; data?: unknown; opts?: JobOptions } = {}
   ): Promise<void> {
+    // Priority and deduplication of spawned jobs travel as TOP-LEVEL Cron
+    // fields (the handler reads cmd.priority/uniqueKey/dedup); inside
+    // jobOptions the server's CronJobOptions silently ignores them.
+    const dedup = template.opts?.deduplication;
     await this.call(
       compact({
         cmd: 'Cron',
@@ -103,9 +108,14 @@ export const adminMethods = {
         data: jobPayload(template.name ?? schedulerId, template.data ?? {}),
         schedule: repeat.pattern,
         repeatEvery: repeat.every,
+        priority: template.opts?.priority,
         timezone: repeat.tz,
         immediately: repeat.immediately,
         maxLimit: repeat.limit,
+        uniqueKey: dedup?.id,
+        dedup: dedup
+          ? compact({ ttl: dedup.ttl, extend: dedup.extend, replace: dedup.replace })
+          : undefined,
         skipMissedOnRestart: repeat.skipMissedOnRestart,
         skipIfNoWorker: repeat.skipIfNoWorker,
         preventOverlap: repeat.preventOverlap,
@@ -122,8 +132,11 @@ export const adminMethods = {
     try {
       const response = await this.call({ cmd: 'CronGet', name: schedulerId });
       return (response.cron ?? response.data ?? null) as Raw | null;
-    } catch {
-      return null; // not-found surfaces as a CommandError
+    } catch (err) {
+      // Only 'Cron job not found' maps to null; connection loss, timeouts and
+      // real server errors must surface, not masquerade as a missing scheduler.
+      if (err instanceof CommandError && /not found/i.test(err.message)) return null;
+      throw err;
     }
   },
 

package/src/queue-control.ts

@@ -3,10 +3,12 @@
  * mutations. Methods are merged onto Queue.prototype by queue.ts.
  */
 
+import { UnrecoverableError } from './errors.js';
 import { compact } from './frame.js';
 import type { Queue } from './queue.js';
 import type { CountResponse, PausedResponse } from './responses.js';
 import type { JobStateName } from './types.js';
+import { MAX_STACK_LINES } from './worker-types.js';
 
 type Ctx = Queue<unknown>;
 
@@ -72,9 +74,11 @@ export const controlMethods = {
       await this.call({ cmd: 'RetryCompleted', queue: this.name });
       return;
     }
-    // `count` is accepted for API parity but not sent: the server has no
-    // partial RetryDlq — it retries the whole DLQ (BullMQ semantics).
-    await this.call({ cmd: 'RetryDlq', queue: this.name });
+    // `count` caps how many DLQ entries are retried (server >= 2.8.29). Older
+    // servers ignore the field and retry the whole DLQ — forward-compatible.
+    await this.call(
+      compact({ cmd: 'RetryDlq', queue: this.name, count: opts.count }) as { cmd: string }
+    );
   },
 
   async retryCompleted(this: Ctx, id?: string): Promise<void> {
@@ -129,14 +133,33 @@ export const controlMethods = {
     await this.call(compact({ cmd: 'ACK', id, result: returnValue, token }) as { cmd: string });
   },
 
+  /**
+   * Explicit failure path: mirrors the worker's FAIL wire so the stacktrace
+   * and the UnrecoverableError "do not retry" intent are persisted (#111
+   * silent-loss class), not just the message.
+   */
   async moveJobToFailed(
     this: Ctx,
     id: string,
     error: Error | string,
     token?: string
   ): Promise<void> {
-    const message = typeof error === 'string' ? error : error.message;
-    await this.call(compact({ cmd: 'FAIL', id, error: message, token }) as { cmd: string });
+    const err = typeof error === 'string' ? undefined : error;
+    const message = err ? err.message || err.name : (error as string);
+    // Keep the FIRST lines (message + throw site), like the worker path.
+    const stack = err
+      ? (err.stack ?? err.message).split('\n').slice(0, MAX_STACK_LINES)
+      : undefined;
+    await this.call(
+      compact({
+        cmd: 'FAIL',
+        id,
+        error: message,
+        stack,
+        unrecoverable: err instanceof UnrecoverableError ? true : undefined,
+        token,
+      }) as { cmd: string }
+    );
   },
 };
 

package/src/queue-query.ts

@@ -34,7 +34,9 @@ export const queryMethods = {
       const response = await this.call<JobResponse>({ cmd: 'GetJob', id });
       return response.job ? new Job<T>(response.job, this.connection) : null;
     } catch (err) {
-      if (err instanceof CommandError) return null; // server: 'Job not found'
+      // Only the server's 'Job not found' maps to null; connection loss,
+      // timeouts and other server errors must surface.
+      if (err instanceof CommandError && /not found/i.test(err.message)) return null;
       throw err;
     }
   },
@@ -44,7 +46,7 @@ export const queryMethods = {
       const response = await this.call<JobResponse>({ cmd: 'GetJobByCustomId', customId });
       return response.job ? new Job<T>(response.job, this.connection) : null;
     } catch (err) {
-      if (err instanceof CommandError) return null;
+      if (err instanceof CommandError && /not found/i.test(err.message)) return null;
       throw err;
     }
   },
@@ -146,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

@@ -7,9 +7,14 @@ import { randomBytes } from 'node:crypto';
 import { EventEmitter } from 'node:events';
 import { hostname } from 'node:os';
 import { Connection } from './connection.js';
-import { MAX_POLL_TIMEOUT_MS, sleep, type WorkerOptions } from './worker-types.js';
-
-export class WorkerBase extends EventEmitter {
+import {
+  MAX_POLL_TIMEOUT_MS,
+  sleep,
+  type WorkerEventMap,
+  type WorkerOptions,
+} from './worker-types.js';
+
+export class WorkerBase<T = unknown, R = unknown> extends EventEmitter {
   readonly queue: string;
   readonly concurrency: number;
   readonly batchSize: number;
@@ -41,7 +46,11 @@ export class WorkerBase 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;
@@ -88,18 +97,40 @@ export class WorkerBase extends EventEmitter {
    * 'ready' is replayed to listeners attached after it fired: with autorun the
    * loop starts inside the constructor, so a plain once-only event could be
    * missed by `new Worker(...).on('ready', ...)` patterns.
+   *
+   * The overloads give the known worker events typed parameters (see
+   * WorkerEventMap); unknown event names keep the generic signature.
    */
-  override on(event: string | symbol, listener: (...args: unknown[]) => void): this {
-    if (event === 'ready' && this.readyFired) listener();
-    return super.on(event, listener);
+  override on<E extends keyof WorkerEventMap<T, R>>(
+    event: E,
+    listener: WorkerEventMap<T, R>[E]
+  ): this;
+  override on(event: string | symbol, listener: (...args: unknown[]) => void): this;
+  override on(event: string | symbol, listener: (...args: never[]) => void): this {
+    if (event === 'ready' && this.readyFired) (listener as () => void)();
+    return super.on(event, listener as (...args: unknown[]) => void);
   }
 
-  override once(event: string | symbol, listener: (...args: unknown[]) => void): this {
+  override once<E extends keyof WorkerEventMap<T, R>>(
+    event: E,
+    listener: WorkerEventMap<T, R>[E]
+  ): this;
+  override once(event: string | symbol, listener: (...args: unknown[]) => void): this;
+  override once(event: string | symbol, listener: (...args: never[]) => void): this {
     if (event === 'ready' && this.readyFired) {
-      listener();
+      (listener as () => void)();
       return this;
     }
-    return super.once(event, listener);
+    return super.once(event, listener as (...args: unknown[]) => void);
+  }
+
+  override off<E extends keyof WorkerEventMap<T, R>>(
+    event: E,
+    listener: WorkerEventMap<T, R>[E]
+  ): this;
+  override off(event: string | symbol, listener: (...args: unknown[]) => void): this;
+  override off(event: string | symbol, listener: (...args: never[]) => void): this {
+    return super.off(event, listener as (...args: unknown[]) => void);
   }
 
   /**
@@ -151,11 +182,16 @@ export class WorkerBase extends EventEmitter {
     this.emit('closed');
   }
 
-  protected async safeCall(command: Record<string, unknown> & { cmd: string }): Promise<void> {
+  /** Dispatch a command, routing failures to 'error'. Returns whether the
+   * command reached the server — callers gate success-only side effects
+   * ('completed'/'failed' emits, counters) on it. */
+  protected async safeCall(command: Record<string, unknown> & { cmd: string }): Promise<boolean> {
     try {
       await this.connection.call(command);
+      return true;
     } catch (err) {
-      this.emit('error', err);
+      this.emit('error', err instanceof Error ? err : new Error(String(err)));
+      return false;
     }
   }
 

package/src/worker-types.ts

@@ -6,6 +6,32 @@ import type { Observability } from './observability.js';
 
 export type Processor<T = unknown, R = unknown> = (job: Job<T>) => R | Promise<R>;
 
+/**
+ * Typed Worker event map: listeners registered via `on`/`once`/`off` for these
+ * names get typed job/result/error parameters in strict mode. Unknown event
+ * names fall back to a generic `(...args: unknown[])` overload.
+ */
+export interface WorkerEventMap<T = unknown, R = unknown> {
+  /** Worker registered and pull loop started (replayed to late listeners). */
+  ready: () => void;
+  /** A job was pulled and handed to the processor. */
+  active: (job: Job<T>) => void;
+  /** Processor resolved AND the ACK reached the server. */
+  completed: (job: Job<T>, result: R) => void;
+  /** Processor threw AND the FAIL reached the server. */
+  failed: (job: Job<T>, error: Error) => void;
+  /** job.updateProgress() was called from the processor. */
+  progress: (job: Job<T>, progress: number) => void;
+  /** Connection/command error (pull loop, ACK/FAIL, heartbeat, ...). */
+  error: (error: Error) => void;
+  /** The queue went from busy to empty (no active jobs, nothing pulled). */
+  drained: () => void;
+  /** Cooperative cancel was requested for a locally active job. */
+  cancelled: (info: { jobId: string; reason: string }) => void;
+  /** close() finished. */
+  closed: () => void;
+}
+
 export interface AckBatchOptions {
   /** Batch ACKs into ACKB round-trips (default false; opt-in for throughput). */
   enabled?: boolean;
@@ -27,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

@@ -21,7 +21,7 @@ import {
   type WorkerOptions,
 } from './worker-types.js';
 
-export class Worker<T = unknown, R = unknown> extends WorkerBase {
+export class Worker<T = unknown, R = unknown> extends WorkerBase<T, R> {
   private readonly processor: Processor<T, R>;
   private readonly ackBatcher: AckBatcher | null;
 
@@ -44,8 +44,8 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase {
   run(): void {
     if (this.running || this.closedFlag) return;
     this.running = true;
-    this.loopPromise = this.loop().catch((err) => {
-      this.emit('error', err);
+    this.loopPromise = this.loop().catch((err: unknown) => {
+      this.emit('error', err instanceof Error ? err : new Error(String(err)));
     });
   }
 
@@ -68,7 +68,7 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase {
         await this.pollOnce();
         backoffIdx = 0;
       } catch (err) {
-        this.emit('error', err);
+        this.emit('error', err instanceof Error ? err : new Error(String(err)));
         if (err instanceof ConnectionClosedError || err instanceof CommandTimeoutError) {
           const delay = RECONNECT_BACKOFF_MS[Math.min(backoffIdx, RECONNECT_BACKOFF_MS.length - 1)];
           backoffIdx += 1;
@@ -143,7 +143,7 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase {
           onSettled: (err) => {
             this.finishJob(job.id);
             if (err) {
-              this.emit('error', err);
+              this.emit('error', err instanceof Error ? err : new Error(String(err)));
             } else {
               this.processed += 1;
               this.emit('completed', job, result);
@@ -152,21 +152,24 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase {
         });
         return;
       }
-      this.processed += 1;
-      await this.safeCall(
+      const acked = await this.safeCall(
         compact({ cmd: 'ACK', id: job.id, token, result: result ?? undefined }) as { cmd: string }
       );
       // Free the slot BEFORE emitting: a throwing 'completed' listener must
       // not leak the active slot (same rationale as the batched path).
       this.finishJob(job.id);
-      this.emit('completed', job, result);
+      // Mirror the batched path: a failed ACK already emitted 'error' — do not
+      // also claim completion (no 'completed', no processed++).
+      if (acked) {
+        this.processed += 1;
+        this.emit('completed', job, result);
+      }
     } catch (err) {
-      this.failedCount += 1;
       const error = err instanceof Error ? err : new Error(String(err));
       // Keep the FIRST lines: in a JS stack the message + throw site lead, so
       // slice(0,N) preserves them (slice(-N) would drop them on long stacks).
       const stack = (error.stack ?? error.message).split('\n').slice(0, MAX_STACK_LINES);
-      await this.safeCall(
+      const failed = await this.safeCall(
         compact({
           cmd: 'FAIL',
           id: job.id,
@@ -177,7 +180,12 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase {
         }) as { cmd: string }
       );
       this.finishJob(job.id);
-      this.emit('failed', job, error);
+      // Same asymmetry guard as the ACK path: if the FAIL never reached the
+      // server, only 'error' fires (the lock expiry will retry the job).
+      if (failed) {
+        this.failedCount += 1;
+        this.emit('failed', job, error);
+      }
     }
   }
 
@@ -189,6 +197,10 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase {
   // --------------------------------------------------------------- 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({