bunqueue-client 0.1.5 → 0.1.6

package/src/job.ts

@@ -3,7 +3,7 @@
  * Mirrors the official TS client's Job surface (TCP mode).
  */
 
-import type { Connection, Response } from './connection.js';
+import type { ConnectionLike, Response } from './connection-types.js';
 
 export type JobRaw = Record<string, unknown>;
 
@@ -12,10 +12,10 @@ export type ProgressHook = (job: Job, progress: number) => void;
 export class Job<T = unknown> {
   readonly raw: JobRaw;
   readonly token: string | undefined;
-  private readonly conn: Connection | undefined;
+  private readonly conn: ConnectionLike | undefined;
   private readonly onProgress: ProgressHook | undefined;
 
-  constructor(raw: JobRaw, connection?: Connection, token?: string, onProgress?: ProgressHook) {
+  constructor(raw: JobRaw, connection?: ConnectionLike, token?: string, onProgress?: ProgressHook) {
     this.raw = raw;
     this.conn = connection;
     this.token = token;

package/src/observability.ts

@@ -0,0 +1,158 @@
+/**
+ * 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 const noopLogger: Logger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {},
+};
+
+const LEVELS: Record<LogLevel, number> = { 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: LogLevel = 'info'): Logger {
+  const floor = LEVELS[min];
+  const line = (lvl: LogLevel, msg: string, meta?: Record<string, unknown>) => {
+    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),
+  };
+}
+
+/** 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 const LIFECYCLE_EVENTS = ['connect', 'disconnect', 'reconnect_scheduled'] as const;
+
+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 const nowMs = (): number => 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 {
+  private readonly logger: Logger;
+  private readonly sink: TelemetryHandler | undefined;
+  private readonly emit: (event: string, payload: unknown) => void;
+
+  constructor(obs: Observability | undefined, emit: (event: string, payload: unknown) => void) {
+    // 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. */
+  private static safely(fn: () => void): void {
+    try {
+      fn();
+    } catch {
+      /* consumer logging/telemetry error — intentionally ignored */
+    }
+  }
+
+  get log(): Logger {
+    return this.logger;
+  }
+
+  /** Record a completed command's latency and outcome. */
+  command(cmd: string, reqId: string, startMs: number, ok: boolean): void {
+    this.dispatch({ type: 'command', cmd, reqId, durationMs: nowMs() - startMs, ok });
+  }
+
+  timeout(cmd: string, reqId: string): void {
+    this.logger.warn('command timed out', { cmd, reqId });
+    this.dispatch({ type: 'command_timeout', cmd, reqId });
+  }
+
+  connected(host: string, port: number, generation: number, startMs: number): void {
+    this.logger.info('connected', { host, port, generation });
+    this.dispatch({ type: 'connect', host, port, generation, durationMs: nowMs() - startMs });
+  }
+
+  disconnected(host: string, port: number, generation: number): void {
+    this.logger.info('disconnected', { host, port, generation });
+    this.dispatch({ type: 'disconnect', host, port, generation });
+  }
+
+  reconnectScheduled(host: string, port: number, attempt: number, delayMs: number): void {
+    this.logger.warn('reconnect scheduled', { host, port, attempt, delayMs });
+    this.dispatch({ type: 'reconnect_scheduled', host, port, attempt, delayMs });
+  }
+
+  auth(ok: boolean): void {
+    this.dispatch({ type: 'auth', ok });
+  }
+
+  backpressure(inFlight: number, maxInFlight: number): void {
+    this.dispatch({ type: 'backpressure', inFlight, maxInFlight });
+  }
+
+  private dispatch(event: TelemetryEvent): void {
+    // 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 as readonly string[]).includes(event.type)) {
+      Telemetry.safely(() => this.emit(event.type, event));
+    }
+  }
+}

package/src/queue-control.ts

@@ -5,6 +5,7 @@
 
 import { compact } from './frame.js';
 import type { Queue } from './queue.js';
+import type { CountResponse, PausedResponse } from './responses.js';
 import type { JobStateName } from './types.js';
 
 type Ctx = Queue<unknown>;
@@ -19,8 +20,7 @@ export const controlMethods = {
   },
 
   async isPaused(this: Ctx): Promise<boolean> {
-    const response = await this.call({ cmd: 'IsPaused', queue: this.name });
-    return response.paused === true;
+    return (await this.call<PausedResponse>({ cmd: 'IsPaused', queue: this.name })).paused === true;
   },
 
   async drain(this: Ctx): Promise<void> {
@@ -33,10 +33,10 @@ export const controlMethods = {
 
   /** Remove old jobs; returns how many were removed. */
   async clean(this: Ctx, graceMs: number, limit?: number, state?: JobStateName): Promise<number> {
-    const response = await this.call(
+    const response = await this.call<CountResponse>(
       compact({ cmd: 'Clean', queue: this.name, grace: graceMs, limit, state }) as { cmd: string }
     );
-    return Number(response.count ?? 0);
+    return response.count ?? 0;
   },
 
   async remove(this: Ctx, id: string): Promise<void> {
@@ -53,10 +53,10 @@ export const controlMethods = {
 
   /** Promote delayed jobs to waiting; returns how many were promoted. */
   async promoteJobs(this: Ctx, opts: { count?: number } = {}): Promise<number> {
-    const response = await this.call(
+    const response = await this.call<CountResponse>(
       compact({ cmd: 'PromoteJobs', queue: this.name, count: opts.count }) as { cmd: string }
     );
-    return Number(response.count ?? 0);
+    return response.count ?? 0;
   },
 
   /** BullMQ contract: failed → waiting. */

package/src/queue-query.ts

@@ -7,12 +7,23 @@ 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,8 +70,7 @@ 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>[]> {
@@ -96,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. */
@@ -136,7 +146,10 @@ export const queryMethods = {
    * 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 {
@@ -161,18 +174,14 @@ 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> {
@@ -206,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>> {

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

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). */