bunqueue-client 0.1.0

package/src/job.ts

@@ -0,0 +1,194 @@
+/**
+ * Job wrapper: read view over the server job record + per-job operations.
+ * Mirrors the official TS client's Job surface (TCP mode).
+ */
+
+import type { Connection, Response } from './connection.js';
+
+export type JobRaw = Record<string, unknown>;
+
+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 onProgress: ProgressHook | undefined;
+
+  constructor(raw: JobRaw, connection?: Connection, token?: string, onProgress?: ProgressHook) {
+    this.raw = raw;
+    this.conn = connection;
+    this.token = token;
+    this.onProgress = onProgress;
+  }
+
+  // ------------------------------------------------------------- properties
+
+  get id(): string {
+    return String(this.raw.id);
+  }
+
+  get queue(): string {
+    return String(this.raw.queue);
+  }
+
+  get data(): T {
+    return this.raw.data as T;
+  }
+
+  /** Job name (stored inside `data.name`, mirroring the official client). */
+  get name(): string | undefined {
+    const data = this.raw.data;
+    if (data && typeof data === 'object' && 'name' in data) {
+      const name = (data as Record<string, unknown>).name;
+      return name === undefined || name === null ? undefined : String(name);
+    }
+    return undefined;
+  }
+
+  get priority(): number {
+    return Number(this.raw.priority ?? 0);
+  }
+
+  get attempts(): number {
+    return Number(this.raw.attempts ?? 0);
+  }
+
+  get maxAttempts(): number {
+    return Number(this.raw.maxAttempts ?? 0);
+  }
+
+  get createdAt(): number | undefined {
+    return this.raw.createdAt === undefined ? undefined : Number(this.raw.createdAt);
+  }
+
+  get startedAt(): number | null {
+    return this.raw.startedAt === undefined || this.raw.startedAt === null
+      ? null
+      : Number(this.raw.startedAt);
+  }
+
+  get completedAt(): number | null {
+    return this.raw.completedAt === undefined || this.raw.completedAt === null
+      ? null
+      : Number(this.raw.completedAt);
+  }
+
+  get customId(): string | null {
+    return this.raw.customId === undefined || this.raw.customId === null
+      ? null
+      : String(this.raw.customId);
+  }
+
+  get tags(): string[] {
+    return Array.isArray(this.raw.tags) ? this.raw.tags.map(String) : [];
+  }
+
+  get groupId(): string | null {
+    return this.raw.groupId === undefined || this.raw.groupId === null
+      ? null
+      : String(this.raw.groupId);
+  }
+
+  get parentId(): string | null {
+    return this.raw.parentId === undefined || this.raw.parentId === null
+      ? null
+      : String(this.raw.parentId);
+  }
+
+  get childrenIds(): string[] {
+    return Array.isArray(this.raw.childrenIds) ? this.raw.childrenIds.map(String) : [];
+  }
+
+  get dependsOn(): string[] {
+    return Array.isArray(this.raw.dependsOn) ? this.raw.dependsOn.map(String) : [];
+  }
+
+  get progress(): number {
+    return Number(this.raw.progress ?? 0);
+  }
+
+  get stacktrace(): string[] | null {
+    return Array.isArray(this.raw.stacktrace) ? this.raw.stacktrace.map(String) : null;
+  }
+
+  get state(): string | undefined {
+    return this.raw.state === undefined ? undefined : String(this.raw.state);
+  }
+
+  // ------------------------------------------------------------- operations
+
+  private call(command: Record<string, unknown> & { cmd: string }): Promise<Response> {
+    if (!this.conn) return Promise.reject(new Error('Job is not bound to a connection'));
+    return this.conn.call(command);
+  }
+
+  /** Report processing progress (0-100) to the server. */
+  async updateProgress(progress: number, message?: string): Promise<void> {
+    await this.call({ cmd: 'Progress', id: this.id, progress, message });
+    this.onProgress?.(this, progress);
+  }
+
+  /** Append a log row to the job. */
+  async log(message: string, level?: 'info' | 'warn' | 'error'): Promise<void> {
+    await this.call({ cmd: 'AddLog', id: this.id, message, level });
+  }
+
+  /** Renew this job's lock (stall detection). */
+  async heartbeat(): Promise<void> {
+    await this.call({ cmd: 'JobHeartbeat', id: this.id, token: this.token });
+  }
+
+  async extendLock(durationMs: number): Promise<void> {
+    await this.call({ cmd: 'ExtendLock', id: this.id, token: this.token, duration: durationMs });
+  }
+
+  async getState(): Promise<string> {
+    const response = await this.call({ cmd: 'GetState', id: this.id });
+    return String(response.state);
+  }
+
+  async getChildrenValues<R = unknown>(): Promise<Record<string, R>> {
+    const response = await this.call({ cmd: 'GetChildrenValues', id: this.id });
+    const data = (response.data ?? {}) as Record<string, unknown>;
+    return (data.values ?? response.values ?? {}) as Record<string, R>;
+  }
+
+  async remove(): Promise<void> {
+    await this.call({ cmd: 'Cancel', id: this.id });
+  }
+
+  async discard(): Promise<void> {
+    await this.call({ cmd: 'Discard', id: this.id });
+  }
+
+  async promote(): Promise<void> {
+    await this.call({ cmd: 'Promote', id: this.id });
+  }
+
+  /** failed → waiting (BullMQ contract; MoveToWait over TCP). */
+  async retry(): Promise<void> {
+    await this.call({ cmd: 'MoveToWait', id: this.id });
+  }
+
+  async updateData(data: unknown): Promise<void> {
+    await this.call({ cmd: 'Update', id: this.id, data });
+  }
+
+  async changePriority(opts: { priority: number; lifo?: boolean }): Promise<void> {
+    await this.call({
+      cmd: 'ChangePriority',
+      id: this.id,
+      priority: opts.priority,
+      lifo: opts.lifo,
+    });
+  }
+
+  async changeDelay(delayMs: number): Promise<void> {
+    await this.call({ cmd: 'ChangeDelay', id: this.id, delay: delayMs });
+  }
+
+  async moveToDelayed(delayMs: number): Promise<void> {
+    await this.call({ cmd: 'MoveToDelayed', id: this.id, delay: delayMs });
+  }
+}

package/src/queue-admin.ts

@@ -0,0 +1,213 @@
+/**
+ * Queue admin surface: DLQ, stall/DLQ configs, rate limits, schedulers,
+ * monitoring and webhooks. Merged onto Queue.prototype by queue.ts.
+ */
+
+import { compact } from './frame.js';
+import type { Queue } from './queue.js';
+import { type JobOptions, jobPayload, wireJobOptions } from './types.js';
+
+type Ctx = Queue<unknown>;
+type Raw = Record<string, unknown>;
+
+export interface SchedulerOptions {
+  pattern?: string;
+  every?: number;
+  tz?: string;
+  immediately?: boolean;
+  limit?: number;
+  skipMissedOnRestart?: boolean;
+  skipIfNoWorker?: boolean;
+  preventOverlap?: boolean;
+}
+
+export const adminMethods = {
+  // ---------------------------------------------------------------------- dlq
+
+  async getDlq(this: Ctx, count?: number): Promise<Raw[]> {
+    const response = await this.call(
+      compact({ cmd: 'Dlq', queue: this.name, count }) as {
+        cmd: string;
+      }
+    );
+    return (response.jobs ?? response.data ?? []) as Raw[];
+  },
+
+  async retryDlq(this: Ctx, jobId?: string): Promise<number> {
+    const response = await this.call(
+      compact({ cmd: 'RetryDlq', queue: this.name, jobId }) as {
+        cmd: string;
+      }
+    );
+    return Number(response.count ?? 0);
+  },
+
+  async purgeDlq(this: Ctx): Promise<number> {
+    const response = await this.call({ cmd: 'PurgeDlq', queue: this.name });
+    return Number(response.count ?? 0);
+  },
+
+  async setDlqConfig(this: Ctx, config: Raw): Promise<void> {
+    await this.call({ cmd: 'SetDlqConfig', queue: this.name, config });
+  },
+
+  async getDlqConfig(this: Ctx): Promise<Raw> {
+    const response = await this.call({ cmd: 'GetDlqConfig', queue: this.name });
+    return (response.config ?? response.data ?? {}) as Raw;
+  },
+
+  // -------------------------------------------------------------------- stall
+
+  async setStallConfig(this: Ctx, config: Raw): Promise<void> {
+    await this.call({ cmd: 'SetStallConfig', queue: this.name, config });
+  },
+
+  async getStallConfig(this: Ctx): Promise<Raw> {
+    const response = await this.call({ cmd: 'GetStallConfig', queue: this.name });
+    return (response.config ?? response.data ?? {}) as Raw;
+  },
+
+  // -------------------------------------------------- rate limit / concurrency
+
+  /** `duration` accepted for signature parity; the TCP wire carries only `limit`. */
+  async setGlobalRateLimit(this: Ctx, max: number, _duration?: number): Promise<void> {
+    await this.call({ cmd: 'RateLimit', queue: this.name, limit: max });
+  },
+
+  async removeGlobalRateLimit(this: Ctx): Promise<void> {
+    await this.call({ cmd: 'RateLimitClear', queue: this.name });
+  },
+
+  async setGlobalConcurrency(this: Ctx, concurrency: number): Promise<void> {
+    await this.call({ cmd: 'SetConcurrency', queue: this.name, limit: concurrency });
+  },
+
+  async removeGlobalConcurrency(this: Ctx): Promise<void> {
+    await this.call({ cmd: 'ClearConcurrency', queue: this.name });
+  },
+
+  // ---------------------------------------------------------------- scheduler
+
+  /** Create/update a recurring job scheduler (cron pattern or fixed interval). */
+  async upsertJobScheduler(
+    this: Ctx,
+    schedulerId: string,
+    repeat: SchedulerOptions,
+    template: { name?: string; data?: unknown; opts?: JobOptions } = {}
+  ): Promise<void> {
+    await this.call(
+      compact({
+        cmd: 'Cron',
+        name: schedulerId,
+        queue: this.name,
+        data: jobPayload(template.name ?? schedulerId, template.data ?? {}),
+        schedule: repeat.pattern,
+        repeatEvery: repeat.every,
+        timezone: repeat.tz,
+        immediately: repeat.immediately,
+        maxLimit: repeat.limit,
+        skipMissedOnRestart: repeat.skipMissedOnRestart,
+        skipIfNoWorker: repeat.skipIfNoWorker,
+        preventOverlap: repeat.preventOverlap,
+        jobOptions: template.opts ? wireJobOptions(template.opts) : undefined,
+      }) as { cmd: string }
+    );
+  },
+
+  async removeJobScheduler(this: Ctx, schedulerId: string): Promise<void> {
+    await this.call({ cmd: 'CronDelete', name: schedulerId });
+  },
+
+  async getJobScheduler(this: Ctx, schedulerId: string): Promise<Raw | null> {
+    try {
+      const response = await this.call({ cmd: 'CronGet', name: schedulerId });
+      return (response.cron ?? response.data ?? null) as Raw | null;
+    } catch {
+      return null; // not-found surfaces as a CommandError
+    }
+  },
+
+  async getJobSchedulers(this: Ctx): Promise<Raw[]> {
+    const response = await this.call({ cmd: 'CronList' });
+    const crons = (response.crons ?? []) as Raw[];
+    return crons.filter((cron) => cron.queue === this.name);
+  },
+
+  async getJobSchedulersCount(this: Ctx): Promise<number> {
+    return (await this.getJobSchedulers()).length;
+  },
+
+  /** Helper: run `name` on a cron `schedule`. */
+  addCron(this: Ctx, name: string, schedule: string, data?: unknown, opts?: JobOptions) {
+    return this.upsertJobScheduler(name, { pattern: schedule }, { name, data, opts });
+  },
+
+  /** Helper: run `name` every `intervalMs` milliseconds. */
+  every(this: Ctx, name: string, intervalMs: number, data?: unknown, opts?: JobOptions) {
+    return this.upsertJobScheduler(name, { every: intervalMs }, { name, data, opts });
+  },
+
+  // --------------------------------------------------------------- monitoring
+
+  async getWorkers(this: Ctx): Promise<Raw[]> {
+    const response = await this.call({ cmd: 'ListWorkers' });
+    const data = (response.data ?? {}) as Raw;
+    return (data.workers ?? response.workers ?? []) as Raw[];
+  },
+
+  async getWorkersCount(this: Ctx): Promise<number> {
+    return (await this.getWorkers()).length;
+  },
+
+  async getStats(this: Ctx): Promise<Raw> {
+    const response = await this.call({ cmd: 'Stats' });
+    return (response.stats ?? {}) as Raw;
+  },
+
+  async getMetrics(this: Ctx): Promise<Raw> {
+    const response = await this.call({ cmd: 'Metrics' });
+    return (response.metrics ?? {}) as Raw;
+  },
+
+  /** Server returns queue NAMES (strings). */
+  async listQueues(this: Ctx): Promise<string[]> {
+    const response = await this.call({ cmd: 'ListQueues' });
+    const queues = (response.queues ?? []) as unknown[];
+    return queues.map((q) => (typeof q === 'string' ? q : String((q as Raw).name)));
+  },
+
+  // ----------------------------------------------------------------- webhooks
+
+  async addWebhook(
+    this: Ctx,
+    opts: { url: string; events: string[]; queue?: string; secret?: string }
+  ): Promise<Raw> {
+    const response = await this.call(
+      compact({
+        cmd: 'AddWebhook',
+        url: opts.url,
+        events: opts.events,
+        queue: opts.queue ?? this.name,
+        secret: opts.secret,
+      }) as { cmd: string }
+    );
+    const data = (response.data ?? {}) as Raw;
+    return (data.webhook ?? data) as Raw;
+  },
+
+  async removeWebhook(this: Ctx, webhookId: string): Promise<void> {
+    await this.call({ cmd: 'RemoveWebhook', webhookId });
+  },
+
+  async listWebhooks(this: Ctx): Promise<Raw[]> {
+    const response = await this.call({ cmd: 'ListWebhooks' });
+    const data = (response.data ?? {}) as Raw;
+    return (data.webhooks ?? response.webhooks ?? []) as Raw[];
+  },
+
+  async setWebhookEnabled(this: Ctx, webhookId: string, enabled: boolean): Promise<void> {
+    await this.call({ cmd: 'SetWebhookEnabled', webhookId, enabled });
+  },
+};
+
+export type QueueAdminApi = typeof adminMethods;

package/src/queue-control.ts

@@ -0,0 +1,145 @@
+/**
+ * Queue control surface: pause/drain/clean, promotion, retry and per-job
+ * mutations. Methods are merged onto Queue.prototype by queue.ts.
+ */
+
+import { compact } from './frame.js';
+import type { Queue } from './queue.js';
+import type { JobStateName } from './types.js';
+
+type Ctx = Queue<unknown>;
+
+export const controlMethods = {
+  async pause(this: Ctx): Promise<void> {
+    await this.call({ cmd: 'Pause', queue: this.name });
+  },
+
+  async resume(this: Ctx): Promise<void> {
+    await this.call({ cmd: 'Resume', queue: this.name });
+  },
+
+  async isPaused(this: Ctx): Promise<boolean> {
+    const response = await this.call({ cmd: 'IsPaused', queue: this.name });
+    return response.paused === true;
+  },
+
+  async drain(this: Ctx): Promise<void> {
+    await this.call({ cmd: 'Drain', queue: this.name });
+  },
+
+  async obliterate(this: Ctx): Promise<void> {
+    await this.call({ cmd: 'Obliterate', queue: this.name });
+  },
+
+  /** 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(
+      compact({ cmd: 'Clean', queue: this.name, grace: graceMs, limit, state }) as { cmd: string }
+    );
+    return Number(response.count ?? 0);
+  },
+
+  async remove(this: Ctx, id: string): Promise<void> {
+    await this.call({ cmd: 'Cancel', id });
+  },
+
+  async discard(this: Ctx, id: string): Promise<void> {
+    await this.call({ cmd: 'Discard', id });
+  },
+
+  async promoteJob(this: Ctx, id: string): Promise<void> {
+    await this.call({ cmd: 'Promote', id });
+  },
+
+  /** Promote delayed jobs to waiting; returns how many were promoted. */
+  async promoteJobs(this: Ctx, opts: { count?: number } = {}): Promise<number> {
+    const response = await this.call(
+      compact({ cmd: 'PromoteJobs', queue: this.name, count: opts.count }) as { cmd: string }
+    );
+    return Number(response.count ?? 0);
+  },
+
+  /** BullMQ contract: failed → waiting. */
+  async retryJob(this: Ctx, id: string): Promise<void> {
+    await this.call({ cmd: 'MoveToWait', id });
+  },
+
+  async retryJobs(
+    this: Ctx,
+    opts: { state?: 'failed' | 'completed'; count?: number } = {}
+  ): Promise<void> {
+    if (opts.state === 'completed') {
+      await this.call({ cmd: 'RetryCompleted', queue: this.name });
+      return;
+    }
+    await this.call(
+      compact({ cmd: 'RetryDlq', queue: this.name, count: opts.count }) as {
+        cmd: string;
+      }
+    );
+  },
+
+  async retryCompleted(this: Ctx, id?: string): Promise<void> {
+    await this.call(compact({ cmd: 'RetryCompleted', queue: this.name, id }) as { cmd: string });
+  },
+
+  // ----------------------------------------------------------- job mutations
+
+  async updateJobProgress(
+    this: Ctx,
+    id: string,
+    progress: number,
+    message?: string
+  ): Promise<void> {
+    await this.call(compact({ cmd: 'Progress', id, progress, message }) as { cmd: string });
+  },
+
+  async updateJobData(this: Ctx, id: string, data: unknown): Promise<void> {
+    await this.call({ cmd: 'Update', id, data });
+  },
+
+  async changeJobPriority(
+    this: Ctx,
+    id: string,
+    opts: { priority: number; lifo?: boolean }
+  ): Promise<void> {
+    await this.call({ cmd: 'ChangePriority', id, priority: opts.priority, lifo: opts.lifo });
+  },
+
+  async changeJobDelay(this: Ctx, id: string, delayMs: number): Promise<void> {
+    await this.call({ cmd: 'ChangeDelay', id, delay: delayMs });
+  },
+
+  async moveJobToWait(this: Ctx, id: string): Promise<void> {
+    await this.call({ cmd: 'MoveToWait', id });
+  },
+
+  async moveJobToDelayed(this: Ctx, id: string, delayMs: number): Promise<void> {
+    await this.call({ cmd: 'MoveToDelayed', id, delay: delayMs });
+  },
+
+  async extendJobLock(this: Ctx, id: string, token: string, durationMs: number): Promise<void> {
+    await this.call({ cmd: 'ExtendLock', id, token, duration: durationMs });
+  },
+
+  async moveJobToCompleted(
+    this: Ctx,
+    id: string,
+    returnValue: unknown,
+    token?: string
+  ): Promise<void> {
+    await this.call(compact({ cmd: 'ACK', id, result: returnValue, token }) as { cmd: string });
+  },
+
+  async moveJobToFailed(
+    this: Ctx,
+    id: string,
+    error: Error | string,
+    token?: string
+  ): Promise<void> {
+    const message = typeof error === 'string' ? error : error.message;
+    await this.call(compact({ cmd: 'FAIL', id, error: message, token }) as { cmd: string });
+  },
+};
+
+export type QueueControlApi = typeof controlMethods;