bunqueue-client 0.1.5 → 0.1.6

package/dist/index.d.ts

@@ -7,16 +7,21 @@ export type { DlqFilter, DlqStats } from './bunqueue/dlq-rate-limit.js';
 export type { BatchConfig, BatchProcessor, BunqueueConnection, BunqueueDebounceConfig, BunqueueDeduplicationConfig, BunqueueDlqConfig, BunqueueMiddleware, BunqueueOptions, CircuitBreakerConfig, CircuitState, JobTtlConfig, PriorityAgingConfig, RateLimiterOptions, RetryConfig, RetryStrategy, TriggerRule, } from './bunqueue/types.js';
 export type { Command, ConnectionOptions, Response, TlsOption } from './connection.js';
 export { Connection } from './connection.js';
+export { ConnectionPool } from './connection-pool.js';
+export type { ConnectionLike } from './connection-types.js';
 export { AuthError, BunqueueError, CommandError, CommandTimeoutError, ConnectionClosedError, UnrecoverableError, } from './errors.js';
 export { FlowProducer } from './flow.js';
 export type { FlowJob, FlowProducerOptions, FlowStep, GetFlowOptions, JobNode, } from './flow-types.js';
 export { MAX_FRAME_SIZE, PROTOCOL_VERSION } from './frame.js';
 export type { JobRaw } from './job.js';
 export { Job } from './job.js';
+export type { Logger, LogLevel, Observability, TelemetryEvent, TelemetryHandler, } from './observability.js';
+export { consoleLogger, noopLogger } from './observability.js';
 export type { BulkJobEntry, QueueOptions } from './queue.js';
 export { Queue } from './queue.js';
 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 { Processor, WorkerOptions } from './worker-types.js';
-export declare const __version__ = "0.1.2";
+export type { AckBatchOptions, Processor, WorkerOptions } from './worker-types.js';
+export declare const __version__ = "0.1.6";

package/dist/index.js

@@ -5,10 +5,12 @@
 // Simple Mode (Bunqueue): all-in-one Queue + Worker, 1:1 with the official client
 export { Bunqueue } from './bunqueue/bunqueue.js';
 export { Connection } from './connection.js';
+export { ConnectionPool } from './connection-pool.js';
 export { AuthError, BunqueueError, CommandError, CommandTimeoutError, ConnectionClosedError, UnrecoverableError, } from './errors.js';
 export { FlowProducer } from './flow.js';
 export { MAX_FRAME_SIZE, PROTOCOL_VERSION } from './frame.js';
 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.2';
+export const __version__ = '0.1.6';

package/dist/job.d.ts

@@ -2,7 +2,7 @@
  * Job wrapper: read view over the server job record + per-job operations.
  * Mirrors the official TS client's Job surface (TCP mode).
  */
-import type { Connection } from './connection.js';
+import type { ConnectionLike } from './connection-types.js';
 export type JobRaw = Record<string, unknown>;
 export type ProgressHook = (job: Job, progress: number) => void;
 export declare class Job<T = unknown> {
@@ -10,7 +10,7 @@ export declare class Job<T = unknown> {
     readonly token: string | undefined;
     private readonly conn;
     private readonly onProgress;
-    constructor(raw: JobRaw, connection?: Connection, token?: string, onProgress?: ProgressHook);
+    constructor(raw: JobRaw, connection?: ConnectionLike, token?: string, onProgress?: ProgressHook);
     get id(): string;
     get queue(): string;
     get data(): T;

package/dist/observability.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Observability primitives: a pluggable structured logger and a telemetry
+ * sink. Zero hard dependencies — wire your own OpenTelemetry / Prometheus /
+ * logging stack through these interfaces. Defaults are no-ops, so the SDK is
+ * silent unless you opt in.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface Logger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/** Silent logger (the default). */
+export declare const noopLogger: Logger;
+/**
+ * A console-backed logger. Levels below `min` are dropped. Opt-in — pass it as
+ * `logger` when you want the SDK to log to the console.
+ */
+export declare function consoleLogger(min?: LogLevel): Logger;
+/** A single telemetry data point. A discriminated union keyed on `type`. */
+export type TelemetryEvent = {
+    type: 'command';
+    cmd: string;
+    reqId: string;
+    durationMs: number;
+    ok: boolean;
+} | {
+    type: 'command_timeout';
+    cmd: string;
+    reqId: string;
+} | {
+    type: 'connect';
+    host: string;
+    port: number;
+    generation: number;
+    durationMs: number;
+} | {
+    type: 'disconnect';
+    host: string;
+    port: number;
+    generation: number;
+} | {
+    type: 'reconnect_scheduled';
+    host: string;
+    port: number;
+    attempt: number;
+    delayMs: number;
+} | {
+    type: 'auth';
+    ok: boolean;
+} | {
+    type: 'backpressure';
+    inFlight: number;
+    maxInFlight: number;
+};
+export type TelemetryHandler = (event: TelemetryEvent) => void;
+/** Lifecycle telemetry types that are ALSO emitted as EventEmitter events. */
+export declare const LIFECYCLE_EVENTS: readonly ["connect", "disconnect", "reconnect_scheduled"];
+export interface Observability {
+    /** Structured logger; defaults to {@link noopLogger}. */
+    logger?: Logger;
+    /**
+     * Telemetry sink for metrics and tracing. Receives every command's latency,
+     * connect/disconnect/reconnect, auth and backpressure events. Bridge it to
+     * OpenTelemetry spans or Prometheus counters without the SDK depending on
+     * either.
+     */
+    onTelemetry?: TelemetryHandler;
+}
+/** High-resolution monotonic clock (Node/Bun/Deno all expose `performance`). */
+export declare const nowMs: () => number;
+/**
+ * Fans a telemetry event out to (1) the telemetry sink, (2) the logger, and
+ * (3) — for lifecycle events — the owning EventEmitter, so users can both
+ * scrape metrics and attach imperative `connection.on('connect', …)` handlers.
+ */
+export declare class Telemetry {
+    private readonly logger;
+    private readonly sink;
+    private readonly emit;
+    constructor(obs: Observability | undefined, emit: (event: string, payload: unknown) => void);
+    /** Observability must never break the client: swallow consumer errors. */
+    private static safely;
+    get log(): Logger;
+    /** Record a completed command's latency and outcome. */
+    command(cmd: string, reqId: string, startMs: number, ok: boolean): void;
+    timeout(cmd: string, reqId: string): void;
+    connected(host: string, port: number, generation: number, startMs: number): void;
+    disconnected(host: string, port: number, generation: number): void;
+    reconnectScheduled(host: string, port: number, attempt: number, delayMs: number): void;
+    auth(ok: boolean): void;
+    backpressure(inFlight: number, maxInFlight: number): void;
+    private dispatch;
+}

package/dist/observability.js

@@ -0,0 +1,110 @@
+/**
+ * Observability primitives: a pluggable structured logger and a telemetry
+ * sink. Zero hard dependencies — wire your own OpenTelemetry / Prometheus /
+ * logging stack through these interfaces. Defaults are no-ops, so the SDK is
+ * silent unless you opt in.
+ */
+/** Silent logger (the default). */
+export const noopLogger = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+/**
+ * A console-backed logger. Levels below `min` are dropped. Opt-in — pass it as
+ * `logger` when you want the SDK to log to the console.
+ */
+export function consoleLogger(min = 'info') {
+    const floor = LEVELS[min];
+    const line = (lvl, msg, meta) => {
+        if (LEVELS[lvl] < floor)
+            return;
+        const suffix = meta && Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : '';
+        const sink = lvl === 'debug' ? console.log : console[lvl];
+        sink(`[bunqueue] ${lvl} ${msg}${suffix}`);
+    };
+    return {
+        debug: (m, meta) => line('debug', m, meta),
+        info: (m, meta) => line('info', m, meta),
+        warn: (m, meta) => line('warn', m, meta),
+        error: (m, meta) => line('error', m, meta),
+    };
+}
+/** Lifecycle telemetry types that are ALSO emitted as EventEmitter events. */
+export const LIFECYCLE_EVENTS = ['connect', 'disconnect', 'reconnect_scheduled'];
+/** High-resolution monotonic clock (Node/Bun/Deno all expose `performance`). */
+export const nowMs = () => performance.now();
+/**
+ * Fans a telemetry event out to (1) the telemetry sink, (2) the logger, and
+ * (3) — for lifecycle events — the owning EventEmitter, so users can both
+ * scrape metrics and attach imperative `connection.on('connect', …)` handlers.
+ */
+export class Telemetry {
+    logger;
+    sink;
+    emit;
+    constructor(obs, emit) {
+        // Wrap the user logger so a throwing logger can never break the transport
+        // hot path (dispatch runs inside socket 'data' handlers and connect).
+        const inner = obs?.logger ?? noopLogger;
+        this.logger =
+            inner === noopLogger
+                ? inner
+                : {
+                    debug: (m, meta) => Telemetry.safely(() => inner.debug(m, meta)),
+                    info: (m, meta) => Telemetry.safely(() => inner.info(m, meta)),
+                    warn: (m, meta) => Telemetry.safely(() => inner.warn(m, meta)),
+                    error: (m, meta) => Telemetry.safely(() => inner.error(m, meta)),
+                };
+        this.sink = obs?.onTelemetry;
+        this.emit = emit;
+    }
+    /** Observability must never break the client: swallow consumer errors. */
+    static safely(fn) {
+        try {
+            fn();
+        }
+        catch {
+            /* consumer logging/telemetry error — intentionally ignored */
+        }
+    }
+    get log() {
+        return this.logger;
+    }
+    /** Record a completed command's latency and outcome. */
+    command(cmd, reqId, startMs, ok) {
+        this.dispatch({ type: 'command', cmd, reqId, durationMs: nowMs() - startMs, ok });
+    }
+    timeout(cmd, reqId) {
+        this.logger.warn('command timed out', { cmd, reqId });
+        this.dispatch({ type: 'command_timeout', cmd, reqId });
+    }
+    connected(host, port, generation, startMs) {
+        this.logger.info('connected', { host, port, generation });
+        this.dispatch({ type: 'connect', host, port, generation, durationMs: nowMs() - startMs });
+    }
+    disconnected(host, port, generation) {
+        this.logger.info('disconnected', { host, port, generation });
+        this.dispatch({ type: 'disconnect', host, port, generation });
+    }
+    reconnectScheduled(host, port, attempt, delayMs) {
+        this.logger.warn('reconnect scheduled', { host, port, attempt, delayMs });
+        this.dispatch({ type: 'reconnect_scheduled', host, port, attempt, delayMs });
+    }
+    auth(ok) {
+        this.dispatch({ type: 'auth', ok });
+    }
+    backpressure(inFlight, maxInFlight) {
+        this.dispatch({ type: 'backpressure', inFlight, maxInFlight });
+    }
+    dispatch(event) {
+        // A throwing sink or lifecycle listener must never break the transport:
+        // dispatch runs inside socket 'data' handlers and the connect path.
+        Telemetry.safely(() => this.sink?.(event));
+        if (LIFECYCLE_EVENTS.includes(event.type)) {
+            Telemetry.safely(() => this.emit(event.type, event));
+        }
+    }
+}

package/dist/queue-control.js

@@ -11,8 +11,7 @@ export const controlMethods = {
         await this.call({ cmd: 'Resume', queue: this.name });
     },
     async isPaused() {
-        const response = await this.call({ cmd: 'IsPaused', queue: this.name });
-        return response.paused === true;
+        return (await this.call({ cmd: 'IsPaused', queue: this.name })).paused === true;
     },
     async drain() {
         await this.call({ cmd: 'Drain', queue: this.name });
@@ -23,7 +22,7 @@ export const controlMethods = {
     /** Remove old jobs; returns how many were removed. */
     async clean(graceMs, limit, state) {
         const response = await this.call(compact({ cmd: 'Clean', queue: this.name, grace: graceMs, limit, state }));
-        return Number(response.count ?? 0);
+        return response.count ?? 0;
     },
     async remove(id) {
         await this.call({ cmd: 'Cancel', id });
@@ -37,7 +36,7 @@ export const controlMethods = {
     /** Promote delayed jobs to waiting; returns how many were promoted. */
     async promoteJobs(opts = {}) {
         const response = await this.call(compact({ cmd: 'PromoteJobs', queue: this.name, count: opts.count }));
-        return Number(response.count ?? 0);
+        return response.count ?? 0;
     },
     /** BullMQ contract: failed → waiting. */
     async retryJob(id) {

package/dist/queue-query.js

@@ -13,8 +13,7 @@ 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)
@@ -25,8 +24,7 @@ export const queryMethods = {
     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)
@@ -49,8 +47,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 +73,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 +125,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 +155,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

@@ -59,4 +59,6 @@ export declare class WorkerBase extends EventEmitter {
     protected safeCall(command: Record<string, unknown> & {
         cmd: string;
     }): Promise<void>;
+    /** Hook run during close() before draining in-flight jobs (see Worker). */
+    protected beforeClose(): Promise<void>;
 }

package/dist/worker-base.js

@@ -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;
@@ -120,6 +122,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) {
@@ -144,4 +147,6 @@ export class WorkerBase extends EventEmitter {
             this.emit('error', err);
         }
     }
+    /** Hook run during close() before draining in-flight jobs (see Worker). */
+    async beforeClose() { }
 }

package/dist/worker-types.d.ts

@@ -1,12 +1,26 @@
 /** 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 {
+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

@@ -9,12 +9,16 @@ 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 {
     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;
 }