bunqueue-client 0.1.4 → 0.1.6

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). */
@@ -50,10 +57,18 @@ export class Queue {
     }
     /** Add many jobs in one round-trip; returns Job stubs. */
     async addBulk(jobs) {
-        const inputs = jobs.map((entry) => ({
-            data: jobPayload(entry.name, entry.data),
-            ...wireJobOptions(entry.opts),
-        }));
+        const inputs = jobs.map((entry) => {
+            const opts = wireJobOptions(entry.opts);
+            // PUSHB entries are JobInput, whose custom-id field is `customId` —
+            // unlike single PUSH which renames `jobId`->`customId` server-side.
+            // Without this the batch custom id is silently dropped (idempotency /
+            // getJobByCustomId broken).
+            if (opts.jobId !== undefined) {
+                opts.customId = opts.jobId;
+                delete opts.jobId;
+            }
+            return { data: jobPayload(entry.name, entry.data), ...opts };
+        });
         const response = await this.call({ cmd: 'PUSHB', queue: this.name, jobs: inputs });
         const ids = (response.ids ?? []);
         return ids.map((id, i) => new Job({ id, queue: this.name, data: inputs[i].data }, this.connection));

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

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,12 +14,22 @@ 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)
@@ -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,14 +111,41 @@ export class Worker extends WorkerBase {
         this.emit('active', job);
         try {
             const result = await this.processor(job);
+            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);
+                        }
+                        else {
+                            this.processed += 1;
+                            this.emit('completed', job, result);
+                        }
+                    },
+                });
+                return;
+            }
             this.processed += 1;
             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);
         }
         catch (err) {
             this.failedCount += 1;
             const error = err instanceof Error ? err : new Error(String(err));
-            const stack = (error.stack ?? error.message).split('\n').slice(-MAX_STACK_LINES);
+            // 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({
                 cmd: 'FAIL',
                 id: job.id,
@@ -116,12 +154,13 @@ export class Worker extends WorkerBase {
                 stack,
                 unrecoverable: err instanceof UnrecoverableError ? true : undefined,
             }));
+            this.finishJob(job.id);
             this.emit('failed', job, error);
         }
-        finally {
-            this.active.delete(job.id);
-            this.cancelledJobs.delete(job.id);
-        }
+    }
+    finishJob(id) {
+        this.active.delete(id);
+        this.cancelledJobs.delete(id);
     }
     // --------------------------------------------------------------- heartbeat
     startHeartbeat() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue-client",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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": {

package/src/ack-batcher.ts

@@ -0,0 +1,76 @@
+/**
+ * Batches completed-job ACKs into ACKB round-trips for higher throughput.
+ *
+ * Opt-in (see WorkerOptions.ackBatch). Items flush when the buffer reaches
+ * `maxSize` or after `maxDelayMs`, whichever comes first; `flush()` drains the
+ * rest on shutdown. Each item's `onSettled` fires after the batch is acked
+ * (or errored), so the worker keeps a job "active" — and its lock renewed —
+ * until the server has confirmed the ack.
+ */
+
+import type { Connection } from './connection.js';
+import { compact } from './frame.js';
+
+export interface AckItem {
+  id: string;
+  token: string;
+  result: unknown;
+  /** Called once the batch settles: `err` set on failure, undefined on ack. */
+  onSettled: (err?: unknown) => void;
+}
+
+export class AckBatcher {
+  private buffer: AckItem[] = [];
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    private readonly connection: Connection,
+    private readonly maxSize: number,
+    private readonly maxDelayMs: number
+  ) {}
+
+  add(item: AckItem): void {
+    this.buffer.push(item);
+    if (this.buffer.length >= this.maxSize) {
+      void this.flush();
+    } else if (!this.timer) {
+      this.timer = setTimeout(() => void this.flush(), this.maxDelayMs);
+      this.timer.unref?.(); // don't keep the process alive for a pending flush
+    }
+  }
+
+  /** Send the buffered ACKs as one ACKB (no-op when empty). */
+  async flush(): Promise<void> {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (this.buffer.length === 0) return;
+    const batch = this.buffer;
+    this.buffer = [];
+    // Capture the wire outcome first; settle callbacks run OUTSIDE the try so
+    // a throwing callback can neither be re-invoked with an error (double
+    // settle) nor starve the remaining items of their callback.
+    let error: unknown;
+    try {
+      await this.connection.call(
+        compact({
+          cmd: 'ACKB',
+          ids: batch.map((b) => b.id),
+          tokens: batch.map((b) => b.token),
+          results: batch.map((b) => b.result),
+        }) as { cmd: string }
+      );
+    } catch (err) {
+      error = err ?? new Error('ACKB failed');
+    }
+    for (const item of batch) {
+      try {
+        item.onSettled(error);
+      } catch {
+        // A callback error (e.g. an unhandled 'error' emit in the worker)
+        // must never prevent the other items from settling.
+      }
+    }
+  }
+}

package/src/backpressure.ts

@@ -0,0 +1,40 @@
+/**
+ * Backpressure gate: bounds the number of in-flight commands on a connection.
+ *
+ * When the in-flight count reaches `max`, `acquire()` parks the caller until a
+ * slot frees (a pending command settles). This turns unbounded memory growth
+ * under a fast producer / slow server into cooperative flow control. `max <= 0`
+ * disables the gate (unbounded, the default).
+ */
+export class Backpressure {
+  private readonly waiters: Array<() => void> = [];
+
+  constructor(
+    private readonly max: number,
+    private readonly onWait?: () => void
+  ) {}
+
+  /** Resolve immediately if under the limit, else park until a slot frees. */
+  acquire(inFlight: number): Promise<void> | void {
+    if (this.max <= 0 || inFlight < this.max) return;
+    this.onWait?.();
+    return new Promise<void>((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+
+  /** Release one parked caller (call when a pending command settles). */
+  release(): void {
+    this.waiters.shift()?.();
+  }
+
+  /** Release every parked caller (call on teardown so none hang forever). */
+  clear(): void {
+    while (this.waiters.length > 0) this.waiters.shift()?.();
+  }
+
+  /** Number of callers currently parked. */
+  get waiting(): number {
+    return this.waiters.length;
+  }
+}

package/src/connection-pool.ts

@@ -0,0 +1,71 @@
+/**
+ * A round-robin pool of TCP connections for producer-side throughput.
+ *
+ * Each `call()` is dispatched to the next connection, so independent commands
+ * (PUSH, queries, control) fan out across N sockets instead of head-of-lining
+ * on one. Use it for {@link Queue} / {@link FlowProducer}; NOT for a Worker,
+ * whose pull→ack flow is bound to a single connection's lock ownership and
+ * reconnect/registration lifecycle.
+ *
+ * Satisfies {@link ConnectionLike}, so it is a drop-in for a single Connection.
+ * Lifecycle events from every member connection are re-emitted here.
+ */
+
+import { EventEmitter } from 'node:events';
+import { Connection } from './connection.js';
+import type { Command, ConnectionLike, ConnectionOptions, Response } from './connection-types.js';
+import { LIFECYCLE_EVENTS } from './observability.js';
+
+export class ConnectionPool extends EventEmitter implements ConnectionLike {
+  private readonly connections: Connection[];
+  private cursor = 0;
+
+  constructor(size: number, options: ConnectionOptions = {}) {
+    super();
+    const n = Math.max(1, Math.floor(size));
+    this.connections = Array.from({ length: n }, () => {
+      const conn = new Connection(options);
+      for (const event of LIFECYCLE_EVENTS) {
+        conn.on(event, (payload) => this.emit(event, payload));
+      }
+      return conn;
+    });
+  }
+
+  /** How many connections back this pool. */
+  get size(): number {
+    return this.connections.length;
+  }
+
+  private next(): Connection {
+    const conn = this.connections[this.cursor];
+    this.cursor = (this.cursor + 1) % this.connections.length;
+    return conn;
+  }
+
+  call<R = Response>(command: Command, timeoutMs?: number): Promise<R> {
+    return this.next().call<R>(command, timeoutMs);
+  }
+
+  ping(): Promise<boolean> {
+    return this.connections[0].ping();
+  }
+
+  async connect(): Promise<void> {
+    await Promise.all(this.connections.map((conn) => conn.connect()));
+  }
+
+  close(): void {
+    for (const conn of this.connections) conn.close();
+  }
+
+  /** True while at least one member connection is up. */
+  get isConnected(): boolean {
+    return this.connections.some((conn) => conn.isConnected);
+  }
+
+  /** Representative generation (first connection); pools are producer-side. */
+  get generation(): number {
+    return this.connections[0].generation;
+  }
+}

package/src/connection-types.ts

@@ -1,19 +1,41 @@
 /** Connection option and message types. */
 
+import type { Observability } from './observability.js';
+
 export type TlsOption = boolean | { caFile?: string; rejectUnauthorized?: boolean } | undefined;
 
-export interface ConnectionOptions {
+export interface ConnectionOptions extends Observability {
   host?: string;
   port?: number;
   token?: string;
   tls?: TlsOption;
   connectTimeoutMs?: number;
   commandTimeoutMs?: number;
+  /**
+   * Max in-flight commands before {@link Connection.call} applies backpressure
+   * (awaits a free slot). 0 / undefined = unbounded. Bounds memory under load.
+   */
+  maxInFlight?: number;
 }
 
 export type Command = Record<string, unknown> & { cmd: string };
 export type Response = Record<string, unknown> & { ok: boolean };
 
+/**
+ * The connection surface consumers (Queue, FlowProducer, Job) depend on.
+ * Both {@link Connection} and a round-robin ConnectionPool satisfy it, so a
+ * pool can be dropped in transparently for producer-side throughput.
+ */
+export interface ConnectionLike {
+  call<R = Response>(command: Command, timeoutMs?: number): Promise<R>;
+  ping(): Promise<boolean>;
+  connect(): Promise<void>;
+  close(): void;
+  readonly isConnected: boolean;
+  readonly generation: number;
+  on(event: string, listener: (...args: unknown[]) => void): this;
+}
+
 export interface Pending {
   resolve: (response: Response) => void;
   reject: (error: Error) => void;