bunqueue-client 0.1.4 → 0.1.6

package/src/queue-query.ts

@@ -3,16 +3,27 @@
  * Methods are merged onto Queue.prototype by queue.ts.
  */
 
-import { CommandError } from './errors.js';
+import { CommandError, CommandTimeoutError } from './errors.js';
 import { compact } from './frame.js';
 import { Job } from './job.js';
 import type { Queue } from './queue.js';
+import type {
+  CountResponse,
+  DataResponse,
+  JobCountsResponse,
+  JobResponse,
+  JobsResponse,
+  ProgressResponse,
+  ResultResponse,
+  StateResponse,
+  WaitJobResponse,
+} from './responses.js';
 import type { JobCounts } from './types.js';
 
 type Ctx = Queue<unknown>;
 type Raw = Record<string, unknown>;
 
-function unwrapValues<R>(response: Raw): Record<string, R> {
+function unwrapValues<R>(response: { data?: unknown; values?: unknown }): Record<string, R> {
   const data = (response.data ?? {}) as Raw;
   return (data.values ?? response.values ?? data ?? {}) as Record<string, R>;
 }
@@ -20,9 +31,8 @@ function unwrapValues<R>(response: Raw): Record<string, R> {
 export const queryMethods = {
   async getJob<T = unknown>(this: Ctx, id: string): Promise<Job<T> | null> {
     try {
-      const response = await this.call({ cmd: 'GetJob', id });
-      const raw = response.job as Raw | null;
-      return raw ? new Job<T>(raw, this.connection) : null;
+      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'
       throw err;
@@ -31,9 +41,8 @@ export const queryMethods = {
 
   async getJobByCustomId<T = unknown>(this: Ctx, customId: string): Promise<Job<T> | null> {
     try {
-      const response = await this.call({ cmd: 'GetJobByCustomId', customId });
-      const raw = response.job as Raw | null;
-      return raw ? new Job<T>(raw, this.connection) : null;
+      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;
       throw err;
@@ -52,7 +61,7 @@ export const queryMethods = {
   ): Promise<Job<T>[]> {
     const start = opts.start ?? 0;
     const end = opts.end !== undefined && opts.end >= 0 ? opts.end : 1000;
-    const response = await this.call(
+    const response = await this.call<JobsResponse>(
       compact({
         cmd: 'GetJobs',
         queue: this.name,
@@ -61,12 +70,13 @@ export const queryMethods = {
         limit: end - start,
       }) as { cmd: string }
     );
-    const jobs = (response.jobs ?? []) as Raw[];
-    return jobs.map((raw) => new Job<T>(raw, this.connection));
+    return (response.jobs ?? []).map((raw) => new Job<T>(raw, this.connection));
   },
 
   getWaiting<T = unknown>(this: Ctx, start?: number, end?: number): Promise<Job<T>[]> {
-    return this.getJobs({ state: ['waiting', 'prioritized'], start, end });
+    // Only the 'waiting' bucket — prioritized jobs live in a separate bucket
+    // (getPrioritized), matching BullMQ and the Python SDK / reference client.
+    return this.getJobs({ state: 'waiting', start, end });
   },
 
   getDelayed<T = unknown>(this: Ctx, start?: number, end?: number): Promise<Job<T>[]> {
@@ -94,25 +104,27 @@ export const queryMethods = {
   },
 
   async getJobState(this: Ctx, id: string): Promise<string> {
-    const response = await this.call({ cmd: 'GetState', id });
-    return String(response.state);
+    return (await this.call<StateResponse>({ cmd: 'GetState', id })).state;
   },
 
   async getResult<R = unknown>(this: Ctx, id: string): Promise<R> {
-    const response = await this.call({ cmd: 'GetResult', id });
-    return response.result as R;
+    return (await this.call<ResultResponse<R>>({ cmd: 'GetResult', id })).result;
   },
 
   async getChildrenValues<R = unknown>(this: Ctx, id: string): Promise<Record<string, R>> {
-    return unwrapValues<R>(await this.call({ cmd: 'GetChildrenValues', id }));
+    return unwrapValues<R>(await this.call<DataResponse>({ cmd: 'GetChildrenValues', id }));
   },
 
   async getFailedChildrenValues(this: Ctx, id: string): Promise<Record<string, string>> {
-    return unwrapValues<string>(await this.call({ cmd: 'GetFailedChildrenValues', id }));
+    return unwrapValues<string>(
+      await this.call<DataResponse>({ cmd: 'GetFailedChildrenValues', id })
+    );
   },
 
   async getIgnoredChildrenFailures(this: Ctx, id: string): Promise<Record<string, string>> {
-    return unwrapValues<string>(await this.call({ cmd: 'GetIgnoredChildrenFailures', id }));
+    return unwrapValues<string>(
+      await this.call<DataResponse>({ cmd: 'GetIgnoredChildrenFailures', id })
+    );
   },
 
   /** Detach a child job from its parent's dependency list. */
@@ -125,9 +137,29 @@ export const queryMethods = {
     await this.call({ cmd: 'RemoveUnprocessedChildren', id });
   },
 
-  /** Block until the job finishes; returns its result. */
+  /**
+   * Block until the job completes; returns its result.
+   * The server's WaitJob waiter resolves only on completion, replying
+   * `{ok:true, completed:false}` (no result) otherwise — so returning undefined
+   * would be indistinguishable from a genuine undefined result. On
+   * non-completion we probe the state: a `failed` job throws CommandError (it
+   * will not complete), everything else throws CommandTimeoutError.
+   */
   async waitForJob<R = unknown>(this: Ctx, id: string, ttlMs = 30_000): Promise<R> {
-    const response = await this.call({ cmd: 'WaitJob', id, timeout: ttlMs }, ttlMs + 5000);
+    const response = await this.call<WaitJobResponse<R>>(
+      { cmd: 'WaitJob', id, timeout: ttlMs },
+      ttlMs + 5000
+    );
+    if (response.completed !== true) {
+      let state: string | undefined;
+      try {
+        state = await this.getJobState(id);
+      } catch {
+        /* ignore probe failure; fall through to timeout */
+      }
+      if (state === 'failed') throw new CommandError(`job ${id} failed before completion`);
+      throw new CommandTimeoutError(`waitUntilFinished timed out after ${ttlMs}ms`);
+    }
     return response.result as R;
   },
 
@@ -142,23 +174,20 @@ export const queryMethods = {
   },
 
   async getProgress(this: Ctx, id: string): Promise<{ progress: number; message: string | null }> {
-    const response = await this.call({ cmd: 'GetProgress', id });
-    return {
-      progress: Number(response.progress ?? 0),
-      message: (response.message as string | null) ?? null,
-    };
+    const response = await this.call<ProgressResponse>({ cmd: 'GetProgress', id });
+    return { progress: response.progress ?? 0, message: response.message ?? null };
   },
 
   // ------------------------------------------------------------------- counts
 
   async getJobCounts(this: Ctx): Promise<JobCounts> {
-    const response = await this.call({ cmd: 'GetJobCounts', queue: this.name });
-    return response.counts as JobCounts;
+    return (await this.call<JobCountsResponse>({ cmd: 'GetJobCounts', queue: this.name })).counts;
   },
 
   async getWaitingCount(this: Ctx): Promise<number> {
-    const counts = await this.getJobCounts();
-    return counts.waiting + counts.prioritized;
+    // 'waiting' only — prioritized jobs are counted by getPrioritizedCount,
+    // matching BullMQ and the Python SDK / reference client.
+    return (await this.getJobCounts()).waiting;
   },
 
   async getActiveCount(this: Ctx): Promise<number> {
@@ -186,8 +215,7 @@ export const queryMethods = {
   },
 
   async count(this: Ctx): Promise<number> {
-    const response = await this.call({ cmd: 'Count', queue: this.name });
-    return Number(response.count ?? 0);
+    return (await this.call<CountResponse>({ cmd: 'Count', queue: this.name })).count ?? 0;
   },
 
   async getCountsPerPriority(this: Ctx): Promise<Record<string, number>> {
@@ -197,8 +225,13 @@ export const queryMethods = {
 
   // --------------------------------------------------------------------- logs
 
-  async addJobLog(this: Ctx, id: string, message: string): Promise<void> {
-    await this.call({ cmd: 'AddLog', id, message });
+  async addJobLog(
+    this: Ctx,
+    id: string,
+    message: string,
+    level?: 'info' | 'warn' | 'error'
+  ): Promise<void> {
+    await this.call(compact({ cmd: 'AddLog', id, message, level }) as { cmd: string });
   },
 
   async getJobLogs(this: Ctx, id: string, start?: number, end?: number): Promise<string[]> {
@@ -209,7 +242,12 @@ export const queryMethods = {
     );
     const data = (response.data ?? {}) as Raw;
     const logs = (data.logs ?? response.logs ?? []) as unknown[];
-    return logs.map((row) => (typeof row === 'string' ? row : String((row as Raw).message ?? row)));
+    // Format as `[level] message` (reference client parity); never drop level.
+    return logs.map((row) => {
+      if (typeof row === 'string') return row;
+      const r = row as Raw;
+      return r.level ? `[${r.level}] ${r.message}` : String(r.message ?? row);
+    });
   },
 
   async clearJobLogs(this: Ctx, id: string, keepLogs?: number): Promise<void> {

package/src/queue.ts

@@ -10,19 +10,29 @@
  */
 
 import { Connection, type Response, type TlsOption } from './connection.js';
+import { ConnectionPool } from './connection-pool.js';
+import type { ConnectionLike } from './connection-types.js';
 import { Job } from './job.js';
+import type { Observability } from './observability.js';
 import { adminMethods, type QueueAdminApi } from './queue-admin.js';
 import { controlMethods, type QueueControlApi } from './queue-control.js';
 import { type QueueQueryApi, queryMethods } from './queue-query.js';
 import { type JobOptions, jobPayload, wireJobOptions } 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> {
@@ -34,26 +44,35 @@ export interface BulkJobEntry<T = unknown> {
 // biome-ignore lint/suspicious/noUnsafeDeclarationMerging: prototype-mixin composition — Object.assign at the bottom installs exactly the methods the merged interface declares
 export class Queue<T = unknown> {
   readonly name: string;
-  readonly connection: Connection;
+  readonly connection: ConnectionLike;
   private readonly ownsConnection: boolean;
 
   constructor(name: string, opts: QueueOptions = {}) {
     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). */
-  call(command: Record<string, unknown> & { cmd: string }, timeoutMs?: number): Promise<Response> {
-    return this.connection.call(command, timeoutMs);
+  call<R = Response>(
+    command: Record<string, unknown> & { cmd: string },
+    timeoutMs?: number
+  ): Promise<R> {
+    return this.connection.call<R>(command, timeoutMs);
   }
 
   // ------------------------------------------------------------------ produce
@@ -72,10 +91,18 @@ export class Queue<T = unknown> {
 
   /** Add many jobs in one round-trip; returns Job stubs. */
   async addBulk(jobs: BulkJobEntry<T>[]): Promise<Job<T>[]> {
-    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 ?? []) as string[];
     return ids.map(

package/src/responses.ts

@@ -0,0 +1,96 @@
+/**
+ * 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;
+  // Index signature so these satisfy the loose transport `Response`
+  // (Record<string, unknown> & { ok }). Named fields still win for reads.
+  [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;
+}

package/src/worker-base.ts

@@ -52,6 +52,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;
@@ -132,6 +134,7 @@ export class WorkerBase extends EventEmitter {
     if (this.closedFlag) return;
     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) {
       clearInterval(this.heartbeatTimer);
@@ -155,4 +158,7 @@ export class WorkerBase extends EventEmitter {
       this.emit('error', err);
     }
   }
+
+  /** Hook run during close() before draining in-flight jobs (see Worker). */
+  protected async beforeClose(): Promise<void> {}
 }

package/src/worker-types.ts

@@ -2,14 +2,29 @@
 
 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/src/worker.ts

@@ -7,9 +7,11 @@
  */
 
 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';
+import type { PulledJobsResponse } from './responses.js';
 import { WorkerBase } from './worker-base.js';
 import {
   MAX_STACK_LINES,
@@ -21,13 +23,23 @@ import {
 
 export class Worker<T = unknown, R = unknown> extends WorkerBase {
   private readonly processor: Processor<T, R>;
+  private readonly ackBatcher: AckBatcher | null;
 
   constructor(queue: string, processor: Processor<T, R>, opts: WorkerOptions = {}) {
     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. */
+  protected override async beforeClose(): Promise<void> {
+    if (this.ackBatcher) await this.ackBatcher.flush();
+  }
+
   /** Start the pull loop (no-op if already running). */
   run(): void {
     if (this.running || this.closedFlag) return;
@@ -82,7 +94,7 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase {
       await this.register();
     }
 
-    const response = await this.connection.call(
+    const response = await this.connection.call<PulledJobsResponse>(
       {
         cmd: 'PULLB',
         queue: this.queue,
@@ -94,8 +106,8 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase {
       this.pollTimeoutMs + 10_000
     );
 
-    const jobs = (response.jobs ?? []) as Record<string, unknown>[];
-    const tokens = (response.tokens ?? []) as string[];
+    const jobs = response.jobs ?? [];
+    const tokens = response.tokens ?? [];
 
     if (jobs.length === 0) {
       if (this.wasBusy && this.active.size === 0) {
@@ -119,15 +131,41 @@ export class Worker<T = unknown, R = unknown> 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 }) 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);
     } 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',
@@ -138,13 +176,16 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase {
           unrecoverable: err instanceof UnrecoverableError ? true : undefined,
         }) as { cmd: string }
       );
+      this.finishJob(job.id);
       this.emit('failed', job, error);
-    } finally {
-      this.active.delete(job.id);
-      this.cancelledJobs.delete(job.id);
     }
   }
 
+  private finishJob(id: string): void {
+    this.active.delete(id);
+    this.cancelledJobs.delete(id);
+  }
+
   // --------------------------------------------------------------- heartbeat
 
   private startHeartbeat(): void {