bunqueue-client 0.1.5 → 0.1.7

package/dist/queue-query.js

@@ -13,23 +13,23 @@ export const queryMethods = {
     async getJob(id) {
         try {
             const response = await this.call({ cmd: 'GetJob', id });
-            const raw = response.job;
-            return raw ? new Job(raw, this.connection) : null;
+            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;
         }
     },
     async getJobByCustomId(customId) {
         try {
             const response = await this.call({ cmd: 'GetJobByCustomId', customId });
-            const raw = response.job;
-            return raw ? new Job(raw, this.connection) : null;
+            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;
         }
@@ -49,8 +49,7 @@ export const queryMethods = {
             offset: start,
             limit: end - start,
         }));
-        const jobs = (response.jobs ?? []);
-        return jobs.map((raw) => new Job(raw, this.connection));
+        return (response.jobs ?? []).map((raw) => new Job(raw, this.connection));
     },
     getWaiting(start, end) {
         // Only the 'waiting' bucket — prioritized jobs live in a separate bucket
@@ -76,12 +75,10 @@ export const queryMethods = {
         return this.getJobs({ state: 'waiting-children', start, end });
     },
     async getJobState(id) {
-        const response = await this.call({ cmd: 'GetState', id });
-        return String(response.state);
+        return (await this.call({ cmd: 'GetState', id })).state;
     },
     async getResult(id) {
-        const response = await this.call({ cmd: 'GetResult', id });
-        return response.result;
+        return (await this.call({ cmd: 'GetResult', id })).result;
     },
     async getChildrenValues(id) {
         return unwrapValues(await this.call({ cmd: 'GetChildrenValues', id }));
@@ -130,15 +127,11 @@ export const queryMethods = {
     },
     async getProgress(id) {
         const response = await this.call({ cmd: 'GetProgress', id });
-        return {
-            progress: Number(response.progress ?? 0),
-            message: response.message ?? null,
-        };
+        return { progress: response.progress ?? 0, message: response.message ?? null };
     },
     // ------------------------------------------------------------------- counts
     async getJobCounts() {
-        const response = await this.call({ cmd: 'GetJobCounts', queue: this.name });
-        return response.counts;
+        return (await this.call({ cmd: 'GetJobCounts', queue: this.name })).counts;
     },
     async getWaitingCount() {
         // 'waiting' only — prioritized jobs are counted by getPrioritizedCount,
@@ -164,8 +157,7 @@ export const queryMethods = {
         return (await this.getJobCounts())['waiting-children'];
     },
     async count() {
-        const response = await this.call({ cmd: 'Count', queue: this.name });
-        return Number(response.count ?? 0);
+        return (await this.call({ cmd: 'Count', queue: this.name })).count ?? 0;
     },
     async getCountsPerPriority() {
         const response = await this.call({ cmd: 'GetCountsPerPriority', queue: this.name });

package/dist/queue.d.ts

@@ -9,18 +9,27 @@
  * exposes them on the type.
  */
 import { Connection, type Response, type TlsOption } from './connection.js';
+import type { ConnectionLike } from './connection-types.js';
 import { Job } from './job.js';
+import type { Observability } from './observability.js';
 import { type QueueAdminApi } from './queue-admin.js';
 import { type QueueControlApi } from './queue-control.js';
 import { type QueueQueryApi } from './queue-query.js';
 import { type JobOptions } from './types.js';
-export interface QueueOptions {
+export interface QueueOptions extends Observability {
     host?: string;
     port?: number;
     token?: string;
     tls?: TlsOption;
     connection?: Connection;
     commandTimeoutMs?: number;
+    /** Max in-flight commands before backpressure kicks in (0 = unbounded). */
+    maxInFlight?: number;
+    /**
+     * Fan producer commands across N connections (round-robin) for throughput.
+     * >1 builds a ConnectionPool; default 1 = a single connection.
+     */
+    poolSize?: number;
 }
 export interface BulkJobEntry<T = unknown> {
     name: string;
@@ -29,13 +38,13 @@ export interface BulkJobEntry<T = unknown> {
 }
 export declare class Queue<T = unknown> {
     readonly name: string;
-    readonly connection: Connection;
+    readonly connection: ConnectionLike;
     private readonly ownsConnection;
     constructor(name: string, opts?: QueueOptions);
     /** Send a raw command on this queue's connection (used by area modules). */
-    call(command: Record<string, unknown> & {
+    call<R = Response>(command: Record<string, unknown> & {
         cmd: string;
-    }, timeoutMs?: number): Promise<Response>;
+    }, timeoutMs?: number): Promise<R>;
     /** Add a job; returns a Job stub carrying the assigned id. */
     add(name: string, data: T, opts?: JobOptions): Promise<Job<T>>;
     /** Add many jobs in one round-trip; returns Job stubs. */

package/dist/queue.js

@@ -9,6 +9,7 @@
  * exposes them on the type.
  */
 import { Connection } from './connection.js';
+import { ConnectionPool } from './connection-pool.js';
 import { Job } from './job.js';
 import { adminMethods } from './queue-admin.js';
 import { controlMethods } from './queue-control.js';
@@ -21,15 +22,21 @@ export class Queue {
     ownsConnection;
     constructor(name, opts = {}) {
         this.name = name;
+        const connOptions = {
+            host: opts.host,
+            port: opts.port,
+            token: opts.token,
+            tls: opts.tls,
+            commandTimeoutMs: opts.commandTimeoutMs,
+            maxInFlight: opts.maxInFlight,
+            logger: opts.logger,
+            onTelemetry: opts.onTelemetry,
+        };
         this.connection =
             opts.connection ??
-                new Connection({
-                    host: opts.host,
-                    port: opts.port,
-                    token: opts.token,
-                    tls: opts.tls,
-                    commandTimeoutMs: opts.commandTimeoutMs,
-                });
+                (opts.poolSize && opts.poolSize > 1
+                    ? new ConnectionPool(opts.poolSize, connOptions)
+                    : new Connection(connOptions));
         this.ownsConnection = opts.connection === undefined;
     }
     /** Send a raw command on this queue's connection (used by area modules). */

package/dist/responses.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Typed server-response shapes, mirroring the server's response builders
+ * (src/domain/types/response.ts). `Connection.call<R>()` and `Queue.call<R>()`
+ * are generic over these, so call sites read `response.job` / `response.counts`
+ * with real types instead of casting `as Record<string, unknown>`.
+ *
+ * These narrow the loose transport `Response`; the runtime value is whatever
+ * the server sent, so only assert the shape a given command actually returns.
+ */
+import type { JobRaw } from './job.js';
+import type { JobCounts, JobStateName } from './types.js';
+interface Ok {
+    ok: true;
+    reqId?: string;
+    [key: string]: unknown;
+}
+/** PUSH → id, or a bare ok ack. */
+export interface OkResponse extends Ok {
+    id?: string;
+}
+/** PUSHB → ids. */
+export interface BatchResponse extends Ok {
+    ids: string[];
+}
+/** GetJob → job (null when not found is surfaced as a CommandError instead). */
+export interface JobResponse extends Ok {
+    job: JobRaw | null;
+}
+/** PULL → job + lock token. */
+export interface PulledJobResponse extends Ok {
+    job: JobRaw | null;
+    token: string | null;
+}
+/** PULLB → jobs + lock tokens (same order). */
+export interface PulledJobsResponse extends Ok {
+    jobs: JobRaw[];
+    tokens: string[];
+}
+/** GetJobs → jobs. */
+export interface JobsResponse extends Ok {
+    jobs: JobRaw[];
+}
+/** GetState → state. */
+export interface StateResponse extends Ok {
+    id: string;
+    state: JobStateName;
+}
+/** GetResult → result. */
+export interface ResultResponse<R = unknown> extends Ok {
+    result: R;
+}
+/** WaitJob → completed flag + (on completion) result. */
+export interface WaitJobResponse<R = unknown> extends Ok {
+    completed: boolean;
+    result?: R;
+}
+/** GetJobCounts → counts. */
+export interface JobCountsResponse extends Ok {
+    counts: JobCounts;
+}
+/** GetProgress → progress + message. */
+export interface ProgressResponse extends Ok {
+    progress: number;
+    message: string | null;
+}
+/** IsPaused → paused. */
+export interface PausedResponse extends Ok {
+    paused: boolean;
+}
+/** Count / Clean / PromoteJobs / RetryDlq → count (+ optional removed ids). */
+export interface CountResponse extends Ok {
+    count: number;
+    ids?: string[];
+}
+/** Generic data-wrapped payload (logs, workers, values, webhookId, …). */
+export interface DataResponse<T = unknown> extends Ok {
+    data: T;
+}
+export {};

package/dist/responses.js

@@ -0,0 +1,10 @@
+/**
+ * Typed server-response shapes, mirroring the server's response builders
+ * (src/domain/types/response.ts). `Connection.call<R>()` and `Queue.call<R>()`
+ * are generic over these, so call sites read `response.job` / `response.counts`
+ * with real types instead of casting `as Record<string, unknown>`.
+ *
+ * These narrow the loose transport `Response`; the runtime value is whatever
+ * the server sent, so only assert the shape a given command actually returns.
+ */
+export {};

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,7 +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;
@@ -49,6 +49,8 @@ export class WorkerBase extends EventEmitter {
             port: opts.port,
             token: opts.token,
             tls: opts.tls,
+            logger: opts.logger,
+            onTelemetry: opts.onTelemetry,
         });
         this.readyPromise = new Promise((resolve) => {
             this.readyResolve = resolve;
@@ -72,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();
@@ -89,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
@@ -120,6 +120,7 @@ export class WorkerBase extends EventEmitter {
         this.stopped = true;
         if (this.loopPromise)
             await this.loopPromise;
+        await this.beforeClose(); // flush any batched ACKs before draining
         while (!force && this.active.size > 0)
             await sleep(20);
         if (this.heartbeatTimer) {
@@ -136,12 +137,19 @@ 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). */
+    async beforeClose() { }
 }

package/dist/worker-types.d.ts

@@ -1,12 +1,54 @@
 /** Worker option types and shared constants. */
 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>;
-export interface WorkerOptions {
+/**
+ * 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;
+    /** Max ACKs per batch (default 50). */
+    maxSize?: number;
+    /** Max ms to hold a partial batch before flushing (default 5). */
+    maxDelayMs?: number;
+}
+export interface WorkerOptions extends Observability {
     host?: string;
     port?: number;
     token?: string;
     tls?: TlsOption;
+    /**
+     * Batch completed-job ACKs into ACKB commands for higher throughput under
+     * load. Opt-in: the default (individual ACK per job) is unchanged.
+     */
+    ackBatch?: AckBatchOptions;
     /** Max jobs processed in parallel (default 4). */
     concurrency?: number;
     /** Max jobs fetched per PULLB (default 10, capped by free slots). */

package/dist/worker.d.ts

@@ -7,14 +7,18 @@
  */
 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);
+    /** Flush batched ACKs before the base class drains in-flight jobs. */
+    protected beforeClose(): Promise<void>;
     /** Start the pull loop (no-op if already running). */
     run(): void;
     private loop;
     private pollOnce;
     private runJob;
+    private finishJob;
     private startHeartbeat;
     private register;
 }

package/dist/worker.js

@@ -6,6 +6,7 @@
  * Lifecycle state and cooperative cancel live in WorkerBase.
  */
 import { hostname } from 'node:os';
+import { AckBatcher } from './ack-batcher.js';
 import { CommandTimeoutError, ConnectionClosedError, UnrecoverableError } from './errors.js';
 import { compact } from './frame.js';
 import { Job } from './job.js';
@@ -13,19 +14,29 @@ import { WorkerBase } from './worker-base.js';
 import { MAX_STACK_LINES, RECONNECT_BACKOFF_MS, sleep, } from './worker-types.js';
 export class Worker extends WorkerBase {
     processor;
+    ackBatcher;
     constructor(queue, processor, opts = {}) {
         super(queue, opts);
         this.processor = processor;
+        const ab = opts.ackBatch;
+        this.ackBatcher = ab?.enabled
+            ? new AckBatcher(this.connection, ab.maxSize ?? 50, ab.maxDelayMs ?? 5)
+            : null;
         if (opts.autorun !== false)
             this.run();
     }
+    /** Flush batched ACKs before the base class drains in-flight jobs. */
+    async beforeClose() {
+        if (this.ackBatcher)
+            await this.ackBatcher.flush();
+    }
     /** Start the pull loop (no-op if already running). */
     run() {
         if (this.running || this.closedFlag)
             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
@@ -46,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;
@@ -78,8 +89,8 @@ export class Worker extends WorkerBase {
             owner: this.workerId,
             lockTtl: this.lockTtlMs,
         }, this.pollTimeoutMs + 10_000);
-        const jobs = (response.jobs ?? []);
-        const tokens = (response.tokens ?? []);
+        const jobs = response.jobs ?? [];
+        const tokens = response.tokens ?? [];
         if (jobs.length === 0) {
             if (this.wasBusy && this.active.size === 0) {
                 this.wasBusy = false;
@@ -100,17 +111,45 @@ export class Worker extends WorkerBase {
         this.emit('active', job);
         try {
             const result = await this.processor(job);
-            this.processed += 1;
-            await this.safeCall(compact({ cmd: 'ACK', id: job.id, token, result: result ?? undefined }));
-            this.emit('completed', job, result);
+            if (this.ackBatcher) {
+                // Defer the ACK into a batch; the job stays active (lock renewed) until
+                // the ACKB settles. onSettled frees the slot FIRST — a throwing
+                // listener (e.g. an unhandled 'error' emit) must never leak the slot
+                // and permanently shrink the worker's effective concurrency.
+                this.ackBatcher.add({
+                    id: job.id,
+                    token,
+                    result: result ?? undefined,
+                    onSettled: (err) => {
+                        this.finishJob(job.id);
+                        if (err) {
+                            this.emit('error', err instanceof Error ? err : new Error(String(err)));
+                        }
+                        else {
+                            this.processed += 1;
+                            this.emit('completed', job, result);
+                        }
+                    },
+                });
+                return;
+            }
+            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);
+            // 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,
@@ -118,13 +157,19 @@ export class Worker extends WorkerBase {
                 stack,
                 unrecoverable: err instanceof UnrecoverableError ? true : undefined,
             }));
-            this.emit('failed', job, error);
-        }
-        finally {
-            this.active.delete(job.id);
-            this.cancelledJobs.delete(job.id);
+            this.finishJob(job.id);
+            // 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) {
+        this.active.delete(id);
+        this.cancelledJobs.delete(id);
+    }
     // --------------------------------------------------------------- heartbeat
     startHeartbeat() {
         this.heartbeatTimer = setInterval(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue-client",
-  "version": "0.1.5",
+  "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",
@@ -17,6 +17,7 @@
     "dist",
     "src",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
@@ -24,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",