bunqueue-client 0.1.5 → 0.1.7

package/src/worker-base.ts

@@ -7,9 +7,14 @@ import { randomBytes } from 'node:crypto';
 import { EventEmitter } from 'node:events';
 import { hostname } from 'node:os';
 import { Connection } from './connection.js';
-import { MAX_POLL_TIMEOUT_MS, sleep, type WorkerOptions } from './worker-types.js';
-
-export class WorkerBase extends EventEmitter {
+import {
+  MAX_POLL_TIMEOUT_MS,
+  sleep,
+  type WorkerEventMap,
+  type WorkerOptions,
+} from './worker-types.js';
+
+export class WorkerBase<T = unknown, R = unknown> extends EventEmitter {
   readonly queue: string;
   readonly concurrency: number;
   readonly batchSize: number;
@@ -52,6 +57,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;
@@ -86,18 +93,40 @@ export class WorkerBase extends EventEmitter {
    * 'ready' is replayed to listeners attached after it fired: with autorun the
    * loop starts inside the constructor, so a plain once-only event could be
    * missed by `new Worker(...).on('ready', ...)` patterns.
+   *
+   * The overloads give the known worker events typed parameters (see
+   * WorkerEventMap); unknown event names keep the generic signature.
    */
-  override on(event: string | symbol, listener: (...args: unknown[]) => void): this {
-    if (event === 'ready' && this.readyFired) listener();
-    return super.on(event, listener);
+  override on<E extends keyof WorkerEventMap<T, R>>(
+    event: E,
+    listener: WorkerEventMap<T, R>[E]
+  ): this;
+  override on(event: string | symbol, listener: (...args: unknown[]) => void): this;
+  override on(event: string | symbol, listener: (...args: never[]) => void): this {
+    if (event === 'ready' && this.readyFired) (listener as () => void)();
+    return super.on(event, listener as (...args: unknown[]) => void);
   }
 
-  override once(event: string | symbol, listener: (...args: unknown[]) => void): this {
+  override once<E extends keyof WorkerEventMap<T, R>>(
+    event: E,
+    listener: WorkerEventMap<T, R>[E]
+  ): this;
+  override once(event: string | symbol, listener: (...args: unknown[]) => void): this;
+  override once(event: string | symbol, listener: (...args: never[]) => void): this {
     if (event === 'ready' && this.readyFired) {
-      listener();
+      (listener as () => void)();
       return this;
     }
-    return super.once(event, listener);
+    return super.once(event, listener as (...args: unknown[]) => void);
+  }
+
+  override off<E extends keyof WorkerEventMap<T, R>>(
+    event: E,
+    listener: WorkerEventMap<T, R>[E]
+  ): this;
+  override off(event: string | symbol, listener: (...args: unknown[]) => void): this;
+  override off(event: string | symbol, listener: (...args: never[]) => void): this {
+    return super.off(event, listener as (...args: unknown[]) => void);
   }
 
   /**
@@ -132,6 +161,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);
@@ -148,11 +178,19 @@ export class WorkerBase extends EventEmitter {
     this.emit('closed');
   }
 
-  protected async safeCall(command: Record<string, unknown> & { cmd: string }): Promise<void> {
+  /** Dispatch a command, routing failures to 'error'. Returns whether the
+   * command reached the server — callers gate success-only side effects
+   * ('completed'/'failed' emits, counters) on it. */
+  protected async safeCall(command: Record<string, unknown> & { cmd: string }): Promise<boolean> {
     try {
       await this.connection.call(command);
+      return true;
     } catch (err) {
-      this.emit('error', err);
+      this.emit('error', err instanceof Error ? err : new Error(String(err)));
+      return false;
     }
   }
+
+  /** Hook run during close() before draining in-flight jobs (see Worker). */
+  protected async beforeClose(): Promise<void> {}
 }

package/src/worker-types.ts

@@ -2,14 +2,55 @@
 
 import type { TlsOption } from './connection.js';
 import type { Job } from './job.js';
+import type { Observability } from './observability.js';
 
 export type Processor<T = unknown, R = unknown> = (job: Job<T>) => R | Promise<R>;
 
-export interface WorkerOptions {
+/**
+ * Typed Worker event map: listeners registered via `on`/`once`/`off` for these
+ * names get typed job/result/error parameters in strict mode. Unknown event
+ * names fall back to a generic `(...args: unknown[])` overload.
+ */
+export interface WorkerEventMap<T = unknown, R = unknown> {
+  /** Worker registered and pull loop started (replayed to late listeners). */
+  ready: () => void;
+  /** A job was pulled and handed to the processor. */
+  active: (job: Job<T>) => void;
+  /** Processor resolved AND the ACK reached the server. */
+  completed: (job: Job<T>, result: R) => void;
+  /** Processor threw AND the FAIL reached the server. */
+  failed: (job: Job<T>, error: Error) => void;
+  /** job.updateProgress() was called from the processor. */
+  progress: (job: Job<T>, progress: number) => void;
+  /** Connection/command error (pull loop, ACK/FAIL, heartbeat, ...). */
+  error: (error: Error) => void;
+  /** The queue went from busy to empty (no active jobs, nothing pulled). */
+  drained: () => void;
+  /** Cooperative cancel was requested for a locally active job. */
+  cancelled: (info: { jobId: string; reason: string }) => void;
+  /** close() finished. */
+  closed: () => void;
+}
+
+export interface AckBatchOptions {
+  /** Batch ACKs into ACKB round-trips (default false; opt-in for throughput). */
+  enabled?: boolean;
+  /** Max ACKs per batch (default 50). */
+  maxSize?: number;
+  /** Max ms to hold a partial batch before flushing (default 5). */
+  maxDelayMs?: number;
+}
+
+export interface WorkerOptions extends Observability {
   host?: string;
   port?: number;
   token?: string;
   tls?: TlsOption;
+  /**
+   * Batch completed-job ACKs into ACKB commands for higher throughput under
+   * load. Opt-in: the default (individual ACK per job) is unchanged.
+   */
+  ackBatch?: AckBatchOptions;
   /** Max jobs processed in parallel (default 4). */
   concurrency?: number;
   /** Max jobs fetched per PULLB (default 10, capped by free slots). */

package/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,
@@ -19,21 +21,31 @@ import {
   type WorkerOptions,
 } from './worker-types.js';
 
-export class Worker<T = unknown, R = unknown> extends WorkerBase {
+export class Worker<T = unknown, R = unknown> extends WorkerBase<T, R> {
   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;
     this.running = true;
-    this.loopPromise = this.loop().catch((err) => {
-      this.emit('error', err);
+    this.loopPromise = this.loop().catch((err: unknown) => {
+      this.emit('error', err instanceof Error ? err : new Error(String(err)));
     });
   }
 
@@ -56,7 +68,7 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase {
         await this.pollOnce();
         backoffIdx = 0;
       } catch (err) {
-        this.emit('error', err);
+        this.emit('error', err instanceof Error ? err : new Error(String(err)));
         if (err instanceof ConnectionClosedError || err instanceof CommandTimeoutError) {
           const delay = RECONNECT_BACKOFF_MS[Math.min(backoffIdx, RECONNECT_BACKOFF_MS.length - 1)];
           backoffIdx += 1;
@@ -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,18 +131,45 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase {
     this.emit('active', job);
     try {
       const result = await this.processor(job);
-      this.processed += 1;
-      await this.safeCall(
+      if (this.ackBatcher) {
+        // Defer the ACK into a batch; the job stays active (lock renewed) until
+        // the ACKB settles. onSettled frees the slot FIRST — a throwing
+        // listener (e.g. an unhandled 'error' emit) must never leak the slot
+        // and permanently shrink the worker's effective concurrency.
+        this.ackBatcher.add({
+          id: job.id,
+          token,
+          result: result ?? undefined,
+          onSettled: (err) => {
+            this.finishJob(job.id);
+            if (err) {
+              this.emit('error', err instanceof Error ? err : new Error(String(err)));
+            } else {
+              this.processed += 1;
+              this.emit('completed', job, result);
+            }
+          },
+        });
+        return;
+      }
+      const acked = await this.safeCall(
         compact({ cmd: 'ACK', id: job.id, token, result: result ?? undefined }) as { cmd: string }
       );
-      this.emit('completed', job, result);
+      // Free the slot BEFORE emitting: a throwing 'completed' listener must
+      // not leak the active slot (same rationale as the batched path).
+      this.finishJob(job.id);
+      // Mirror the batched path: a failed ACK already emitted 'error' — do not
+      // also claim completion (no 'completed', no processed++).
+      if (acked) {
+        this.processed += 1;
+        this.emit('completed', job, result);
+      }
     } catch (err) {
-      this.failedCount += 1;
       const error = err instanceof Error ? err : new Error(String(err));
       // Keep the FIRST lines: in a JS stack the message + throw site lead, so
       // slice(0,N) preserves them (slice(-N) would drop them on long stacks).
       const stack = (error.stack ?? error.message).split('\n').slice(0, MAX_STACK_LINES);
-      await this.safeCall(
+      const failed = await this.safeCall(
         compact({
           cmd: 'FAIL',
           id: job.id,
@@ -140,13 +179,21 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase {
           unrecoverable: err instanceof UnrecoverableError ? true : undefined,
         }) as { cmd: string }
       );
-      this.emit('failed', job, error);
-    } finally {
-      this.active.delete(job.id);
-      this.cancelledJobs.delete(job.id);
+      this.finishJob(job.id);
+      // Same asymmetry guard as the ACK path: if the FAIL never reached the
+      // server, only 'error' fires (the lock expiry will retry the job).
+      if (failed) {
+        this.failedCount += 1;
+        this.emit('failed', job, error);
+      }
     }
   }
 
+  private finishJob(id: string): void {
+    this.active.delete(id);
+    this.cancelledJobs.delete(id);
+  }
+
   // --------------------------------------------------------------- heartbeat
 
   private startHeartbeat(): void {