bunqueue-client 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -5,6 +5,48 @@ 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.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 +75,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

@@ -8,9 +8,9 @@ The bunqueue server runs on Bun, distributed as a binary or a Docker image. This
 
 | 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, 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 |
 | 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.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/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;
         }

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;
@@ -74,11 +74,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 +86,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 +137,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;

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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue-client",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "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.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/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;
     }
   },

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;
@@ -88,18 +93,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 +178,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;

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);
+      }
     }
   }