bunqueue-client 0.1.0

package/src/queue-query.ts

@@ -0,0 +1,220 @@
+/**
+ * Queue query surface: job lookup, state, results, counts, logs, children.
+ * Methods are merged onto Queue.prototype by queue.ts.
+ */
+
+import { CommandError } from './errors.js';
+import { compact } from './frame.js';
+import { Job } from './job.js';
+import type { Queue } from './queue.js';
+import type { JobCounts } from './types.js';
+
+type Ctx = Queue<unknown>;
+type Raw = Record<string, unknown>;
+
+function unwrapValues<R>(response: Raw): Record<string, R> {
+  const data = (response.data ?? {}) as Raw;
+  return (data.values ?? response.values ?? data ?? {}) as 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;
+    } catch (err) {
+      if (err instanceof CommandError) return null; // server: 'Job not found'
+      throw err;
+    }
+  },
+
+  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;
+    } catch (err) {
+      if (err instanceof CommandError) return null;
+      throw err;
+    }
+  },
+
+  /** BullMQ v5: resolve the job id registered under a deduplication id. */
+  async getDeduplicationJobId(this: Ctx, deduplicationId: string): Promise<string | null> {
+    const job = await this.getJobByCustomId(deduplicationId);
+    return job ? job.id : null;
+  },
+
+  async getJobs<T = unknown>(
+    this: Ctx,
+    opts: { state?: string | string[]; start?: number; end?: number } = {}
+  ): Promise<Job<T>[]> {
+    const start = opts.start ?? 0;
+    const end = opts.end !== undefined && opts.end >= 0 ? opts.end : 1000;
+    const response = await this.call(
+      compact({
+        cmd: 'GetJobs',
+        queue: this.name,
+        state: opts.state,
+        offset: start,
+        limit: end - start,
+      }) as { cmd: string }
+    );
+    const jobs = (response.jobs ?? []) as Raw[];
+    return 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 });
+  },
+
+  getDelayed<T = unknown>(this: Ctx, start?: number, end?: number): Promise<Job<T>[]> {
+    return this.getJobs({ state: 'delayed', start, end });
+  },
+
+  getActive<T = unknown>(this: Ctx, start?: number, end?: number): Promise<Job<T>[]> {
+    return this.getJobs({ state: 'active', start, end });
+  },
+
+  getCompleted<T = unknown>(this: Ctx, start?: number, end?: number): Promise<Job<T>[]> {
+    return this.getJobs({ state: 'completed', start, end });
+  },
+
+  getFailed<T = unknown>(this: Ctx, start?: number, end?: number): Promise<Job<T>[]> {
+    return this.getJobs({ state: 'failed', start, end });
+  },
+
+  getPrioritized<T = unknown>(this: Ctx, start?: number, end?: number): Promise<Job<T>[]> {
+    return this.getJobs({ state: 'prioritized', start, end });
+  },
+
+  getWaitingChildren<T = unknown>(this: Ctx, start?: number, end?: number): Promise<Job<T>[]> {
+    return this.getJobs({ state: 'waiting-children', start, end });
+  },
+
+  async getJobState(this: Ctx, id: string): Promise<string> {
+    const response = await this.call({ cmd: 'GetState', id });
+    return String(response.state);
+  },
+
+  async getResult<R = unknown>(this: Ctx, id: string): Promise<R> {
+    const response = await this.call({ cmd: 'GetResult', id });
+    return response.result as R;
+  },
+
+  async getChildrenValues<R = unknown>(this: Ctx, id: string): Promise<Record<string, R>> {
+    return unwrapValues<R>(await this.call({ cmd: 'GetChildrenValues', id }));
+  },
+
+  async getFailedChildrenValues(this: Ctx, id: string): Promise<Record<string, string>> {
+    return unwrapValues<string>(await this.call({ cmd: 'GetFailedChildrenValues', id }));
+  },
+
+  async getIgnoredChildrenFailures(this: Ctx, id: string): Promise<Record<string, string>> {
+    return unwrapValues<string>(await this.call({ cmd: 'GetIgnoredChildrenFailures', id }));
+  },
+
+  /** Detach a child job from its parent's dependency list. */
+  async removeChildDependency(this: Ctx, id: string): Promise<void> {
+    await this.call({ cmd: 'RemoveChildDependency', id });
+  },
+
+  /** Remove all still-unprocessed children of a parent job. */
+  async removeUnprocessedChildren(this: Ctx, id: string): Promise<void> {
+    await this.call({ cmd: 'RemoveUnprocessedChildren', id });
+  },
+
+  /** Block until the job finishes; returns its result. */
+  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);
+    return response.result as R;
+  },
+
+  /** BullMQ v5 alias for waitForJob (queueEvents param unused over TCP). */
+  waitJobUntilFinished<R = unknown>(
+    this: Ctx,
+    id: string,
+    _queueEvents?: unknown,
+    ttlMs?: number
+  ): Promise<R> {
+    return this.waitForJob<R>(id, ttlMs);
+  },
+
+  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,
+    };
+  },
+
+  // ------------------------------------------------------------------- counts
+
+  async getJobCounts(this: Ctx): Promise<JobCounts> {
+    const response = await this.call({ cmd: 'GetJobCounts', queue: this.name });
+    return response.counts as JobCounts;
+  },
+
+  async getWaitingCount(this: Ctx): Promise<number> {
+    const counts = await this.getJobCounts();
+    return counts.waiting + counts.prioritized;
+  },
+
+  async getActiveCount(this: Ctx): Promise<number> {
+    return (await this.getJobCounts()).active;
+  },
+
+  async getCompletedCount(this: Ctx): Promise<number> {
+    return (await this.getJobCounts()).completed;
+  },
+
+  async getFailedCount(this: Ctx): Promise<number> {
+    return (await this.getJobCounts()).failed;
+  },
+
+  async getDelayedCount(this: Ctx): Promise<number> {
+    return (await this.getJobCounts()).delayed;
+  },
+
+  async getPrioritizedCount(this: Ctx): Promise<number> {
+    return (await this.getJobCounts()).prioritized;
+  },
+
+  async getWaitingChildrenCount(this: Ctx): Promise<number> {
+    return (await this.getJobCounts())['waiting-children'];
+  },
+
+  async count(this: Ctx): Promise<number> {
+    const response = await this.call({ cmd: 'Count', queue: this.name });
+    return Number(response.count ?? 0);
+  },
+
+  async getCountsPerPriority(this: Ctx): Promise<Record<string, number>> {
+    const response = await this.call({ cmd: 'GetCountsPerPriority', queue: this.name });
+    return (response.counts ?? response.data ?? {}) as Record<string, number>;
+  },
+
+  // --------------------------------------------------------------------- logs
+
+  async addJobLog(this: Ctx, id: string, message: string): Promise<void> {
+    await this.call({ cmd: 'AddLog', id, message });
+  },
+
+  async getJobLogs(this: Ctx, id: string, start?: number, end?: number): Promise<string[]> {
+    const response = await this.call(
+      compact({ cmd: 'GetLogs', id, start, end }) as {
+        cmd: string;
+      }
+    );
+    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)));
+  },
+
+  async clearJobLogs(this: Ctx, id: string, keepLogs?: number): Promise<void> {
+    await this.call(compact({ cmd: 'ClearLogs', id, keepLogs }) as { cmd: string });
+  },
+};
+
+export type QueueQueryApi = typeof queryMethods;

package/src/queue.ts

@@ -0,0 +1,112 @@
+/**
+ * Queue: producer + management API over the bunqueue TCP protocol.
+ * Method surface mirrors the official TS client (TCP mode).
+ *
+ * The class is composed from area modules kept under 250 lines each:
+ * queue-query.ts (query/counts/logs), queue-control.ts (state control,
+ * job mutations) and queue-admin.ts (DLQ, configs, schedulers, webhooks,
+ * monitoring). Methods are merged onto the prototype; declaration merging
+ * exposes them on the type.
+ */
+
+import { Connection, type Response, type TlsOption } from './connection.js';
+import { Job } from './job.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 {
+  host?: string;
+  port?: number;
+  token?: string;
+  tls?: TlsOption;
+  connection?: Connection;
+  commandTimeoutMs?: number;
+}
+
+export interface BulkJobEntry<T = unknown> {
+  name: string;
+  data: T;
+  opts?: JobOptions;
+}
+
+// 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;
+  private readonly ownsConnection: boolean;
+
+  constructor(name: string, opts: QueueOptions = {}) {
+    this.name = name;
+    this.connection =
+      opts.connection ??
+      new Connection({
+        host: opts.host,
+        port: opts.port,
+        token: opts.token,
+        tls: opts.tls,
+        commandTimeoutMs: opts.commandTimeoutMs,
+      });
+    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);
+  }
+
+  // ------------------------------------------------------------------ produce
+
+  /** Add a job; returns a Job stub carrying the assigned id. */
+  async add(name: string, data: T, opts?: JobOptions): Promise<Job<T>> {
+    const payload = jobPayload(name, data);
+    const response = await this.call({
+      cmd: 'PUSH',
+      queue: this.name,
+      data: payload,
+      ...wireJobOptions(opts),
+    });
+    return new Job<T>({ id: response.id, queue: this.name, data: payload }, this.connection);
+  }
+
+  /** 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 response = await this.call({ cmd: 'PUSHB', queue: this.name, jobs: inputs });
+    const ids = (response.ids ?? []) as string[];
+    return ids.map(
+      (id, i) => new Job<T>({ id, queue: this.name, data: inputs[i].data }, this.connection)
+    );
+  }
+
+  // ---------------------------------------------------------------- lifecycle
+
+  ping(): Promise<boolean> {
+    return this.connection.ping();
+  }
+
+  async waitUntilReady(): Promise<void> {
+    await this.connection.connect();
+  }
+
+  close(): void {
+    if (this.ownsConnection) this.connection.close();
+  }
+
+  /** BullMQ v5 alias for close(). */
+  async disconnect(): Promise<void> {
+    this.close();
+  }
+}
+
+/* Merge the area-module methods into the class (runtime + type level).
+ * The declaration merging is intentional and safe: Object.assign below
+ * installs exactly the methods the interface declares. The unused type
+ * parameter is required — merged interfaces must repeat the class generics. */
+// biome-ignore lint/correctness/noUnusedVariables: generic must match the class declaration
+export interface Queue<T = unknown> extends QueueQueryApi, QueueControlApi, QueueAdminApi {}
+Object.assign(Queue.prototype, queryMethods, controlMethods, adminMethods);

package/src/types.ts

@@ -0,0 +1,133 @@
+/** Shared option types + wire mapping, mirroring the official client. */
+
+import { compact } from './frame.js';
+
+export interface BackoffOptions {
+  type: 'fixed' | 'exponential';
+  delay: number;
+  maxDelay?: number;
+}
+
+export interface DeduplicationOptions {
+  id: string;
+  ttl?: number;
+  extend?: boolean;
+  replace?: boolean;
+}
+
+export interface RepeatOptions {
+  every?: number;
+  limit?: number;
+  pattern?: string;
+  count?: number;
+  startDate?: number;
+  endDate?: number;
+  tz?: string;
+  immediately?: boolean;
+  offset?: number;
+  jobId?: string;
+}
+
+export interface JobOptions {
+  priority?: number;
+  delay?: number;
+  /** Max attempts (server name: maxAttempts). */
+  attempts?: number;
+  backoff?: number | BackoffOptions;
+  ttl?: number;
+  timeout?: number;
+  /** Custom job id (idempotent add). */
+  jobId?: string;
+  deduplication?: DeduplicationOptions;
+  dependsOn?: string[];
+  parentId?: string;
+  childrenIds?: string[];
+  tags?: string[];
+  groupId?: string;
+  lifo?: boolean;
+  removeOnComplete?: boolean;
+  removeOnFail?: boolean;
+  stallTimeout?: number;
+  durable?: boolean;
+  repeat?: RepeatOptions;
+  debounce?: { id: string; ttl?: number };
+  stackTraceLimit?: number;
+  keepLogs?: number;
+  sizeLimit?: number;
+  timestamp?: number;
+  failParentOnFailure?: boolean;
+  removeDependencyOnFailure?: boolean;
+  ignoreDependencyOnFailure?: boolean;
+  continueParentOnFailure?: boolean;
+}
+
+/** Map SDK JobOptions to the PUSH/PUSHB wire fields (undefined keys dropped). */
+export function wireJobOptions(opts: JobOptions = {}): Record<string, unknown> {
+  return compact({
+    priority: opts.priority,
+    delay: opts.delay,
+    maxAttempts: opts.attempts,
+    backoff: opts.backoff,
+    ttl: opts.ttl,
+    timeout: opts.timeout,
+    jobId: opts.jobId,
+    uniqueKey: opts.deduplication?.id,
+    dedup: opts.deduplication
+      ? compact({
+          ttl: opts.deduplication.ttl,
+          extend: opts.deduplication.extend,
+          replace: opts.deduplication.replace,
+        })
+      : undefined,
+    dependsOn: opts.dependsOn,
+    parentId: opts.parentId,
+    childrenIds: opts.childrenIds,
+    tags: opts.tags,
+    groupId: opts.groupId,
+    lifo: opts.lifo,
+    removeOnComplete:
+      typeof opts.removeOnComplete === 'boolean' ? opts.removeOnComplete : undefined,
+    removeOnFail: typeof opts.removeOnFail === 'boolean' ? opts.removeOnFail : undefined,
+    stallTimeout: opts.stallTimeout,
+    durable: opts.durable,
+    repeat: opts.repeat,
+    debounceId: opts.debounce?.id,
+    debounceTtl: opts.debounce?.ttl,
+    stackTraceLimit: opts.stackTraceLimit,
+    keepLogs: opts.keepLogs,
+    sizeLimit: opts.sizeLimit,
+    timestamp: opts.timestamp,
+    failParentOnFailure: opts.failParentOnFailure,
+    removeDependencyOnFailure: opts.removeDependencyOnFailure,
+    ignoreDependencyOnFailure: opts.ignoreDependencyOnFailure,
+    continueParentOnFailure: opts.continueParentOnFailure,
+  });
+}
+
+/** The job name travels inside `data`, mirroring the official client. */
+export function jobPayload(name: string, data: unknown): Record<string, unknown> {
+  if (data && typeof data === 'object' && !Array.isArray(data)) {
+    return { name, ...(data as Record<string, unknown>) };
+  }
+  return data === undefined || data === null ? { name } : { name, payload: data };
+}
+
+export interface JobCounts {
+  waiting: number;
+  prioritized: number;
+  delayed: number;
+  active: number;
+  completed: number;
+  failed: number;
+  'waiting-children': number;
+  paused: number;
+}
+
+export type JobStateName =
+  | 'waiting'
+  | 'prioritized'
+  | 'delayed'
+  | 'active'
+  | 'completed'
+  | 'failed'
+  | 'waiting-children';

package/src/worker-base.ts

@@ -0,0 +1,132 @@
+/**
+ * WorkerBase: lifecycle state, cooperative cancellation and safe command
+ * dispatch shared by the Worker pull loop (worker.ts).
+ */
+
+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 {
+  readonly queue: string;
+  readonly concurrency: number;
+  readonly batchSize: number;
+  readonly pollTimeoutMs: number;
+  readonly lockTtlMs: number;
+  readonly heartbeatIntervalS: number;
+  readonly workerId: string;
+  readonly name: string;
+  readonly connection: Connection;
+
+  protected readonly active = new Map<string, string>(); // job id -> lock token
+  protected readonly cancelledJobs = new Set<string>();
+  protected stopped = false;
+  protected paused = false;
+  protected closedFlag = false;
+  protected running = false;
+  protected wasBusy = false;
+  protected processed = 0;
+  protected failedCount = 0;
+  protected readyPromise: Promise<void>;
+  protected readyResolve: (() => void) | null = null;
+  protected loopPromise: Promise<void> | null = null;
+  protected heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(queue: string, opts: WorkerOptions = {}) {
+    super();
+    if ((opts.concurrency ?? 4) < 1) throw new Error('concurrency must be >= 1');
+    this.queue = queue;
+    this.concurrency = opts.concurrency ?? 4;
+    this.batchSize = Math.max(1, opts.batchSize ?? 10);
+    this.pollTimeoutMs = Math.min(opts.pollTimeoutMs ?? 5000, MAX_POLL_TIMEOUT_MS);
+    this.lockTtlMs = opts.lockTtlMs ?? 30_000;
+    this.heartbeatIntervalS = opts.heartbeatIntervalS ?? 10;
+    this.workerId = `ts-${hostname()}-${process.pid}-${randomBytes(4).toString('hex')}`;
+    this.name = opts.name ?? this.workerId;
+    this.connection = new Connection({
+      host: opts.host,
+      port: opts.port,
+      token: opts.token,
+      tls: opts.tls,
+    });
+    this.readyPromise = new Promise((resolve) => {
+      this.readyResolve = resolve;
+    });
+  }
+
+  pause(): void {
+    this.paused = true;
+  }
+
+  resume(): void {
+    this.paused = false;
+  }
+
+  isRunning(): boolean {
+    return this.running && !this.closedFlag;
+  }
+
+  isPaused(): boolean {
+    return this.paused;
+  }
+
+  isClosed(): boolean {
+    return this.closedFlag;
+  }
+
+  async waitUntilReady(): Promise<void> {
+    await this.readyPromise;
+  }
+
+  /**
+   * Cooperative cancel of a locally active job (mirrors the official client):
+   * marks the job and emits 'cancelled'; the processor is expected to check
+   * isJobCancelled() and abort. Returns false if the job is not active here.
+   */
+  cancelJob(jobId: string, reason?: string): boolean {
+    if (this.active.has(jobId)) {
+      this.cancelledJobs.add(jobId);
+      this.emit('cancelled', { jobId, reason: reason ?? 'Job cancelled by worker' });
+      return true;
+    }
+    return false;
+  }
+
+  cancelAllJobs(reason?: string): void {
+    for (const jobId of this.active.keys()) {
+      this.cancelledJobs.add(jobId);
+      this.emit('cancelled', { jobId, reason: reason ?? 'All jobs cancelled' });
+    }
+  }
+
+  isJobCancelled(jobId: string): boolean {
+    return this.cancelledJobs.has(jobId);
+  }
+
+  /** Graceful shutdown: stop pulling, wait for in-flight jobs. */
+  async close(): Promise<void> {
+    if (this.closedFlag) return;
+    this.stopped = true;
+    if (this.loopPromise) await this.loopPromise;
+    while (this.active.size > 0) await sleep(20);
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    await this.safeCall({ cmd: 'UnregisterWorker', workerId: this.workerId });
+    this.connection.close();
+    this.closedFlag = true;
+    this.running = false;
+    this.emit('closed');
+  }
+
+  protected async safeCall(command: Record<string, unknown> & { cmd: string }): Promise<void> {
+    try {
+      await this.connection.call(command);
+    } catch (err) {
+      this.emit('error', err);
+    }
+  }
+}

package/src/worker-types.ts

@@ -0,0 +1,32 @@
+/** Worker option types and shared constants. */
+
+import type { TlsOption } from './connection.js';
+import type { Job } from './job.js';
+
+export type Processor<T = unknown, R = unknown> = (job: Job<T>) => R | Promise<R>;
+
+export interface WorkerOptions {
+  host?: string;
+  port?: number;
+  token?: string;
+  tls?: TlsOption;
+  /** Max jobs processed in parallel (default 4). */
+  concurrency?: number;
+  /** Max jobs fetched per PULLB (default 10, capped by free slots). */
+  batchSize?: number;
+  /** Server-side long-poll timeout in ms (default 5000, max 30000). */
+  pollTimeoutMs?: number;
+  /** Job lock TTL in ms (default 30000). */
+  lockTtlMs?: number;
+  /** Worker + job heartbeat interval in seconds (default 10). */
+  heartbeatIntervalS?: number;
+  /** Start the loop at construction (default true, mirrors the TS client). */
+  autorun?: boolean;
+  name?: string;
+}
+
+export const MAX_POLL_TIMEOUT_MS = 30_000;
+export const MAX_STACK_LINES = 20;
+export const RECONNECT_BACKOFF_MS = [500, 1000, 2000, 5000];
+
+export const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));