bunqueue-client 0.1.0

package/dist/flow.js

@@ -0,0 +1,186 @@
+/**
+ * FlowProducer: parent/children job trees, chains and fan-in flows.
+ * Mirrors the official client's TCP flow logic (bottom-up creation,
+ * UpdateParent fix-up, rollback via Cancel on failure).
+ */
+import { Connection } from './connection.js';
+import { compact } from './frame.js';
+import { Job } from './job.js';
+import { jobPayload, wireJobOptions } from './types.js';
+export class FlowProducer {
+    connection;
+    ownsConnection;
+    constructor(opts = {}) {
+        this.connection =
+            opts.connection ??
+                new Connection({ host: opts.host, port: opts.port, token: opts.token, tls: opts.tls });
+        this.ownsConnection = opts.connection === undefined;
+    }
+    /** Add a flow tree. Children are created (and processed) BEFORE their parent. */
+    async add(flow) {
+        const created = [];
+        try {
+            return await this.addNode(flow, null, created);
+        }
+        catch (err) {
+            await this.rollback(created);
+            throw err;
+        }
+    }
+    async addBulk(flows) {
+        const created = [];
+        const results = [];
+        try {
+            for (const flow of flows) {
+                results.push(await this.addNode(flow, null, created));
+            }
+            return results;
+        }
+        catch (err) {
+            await this.rollback(created);
+            throw err;
+        }
+    }
+    /** Fetch a flow tree starting from a job id (recursive over childrenIds). */
+    getFlow(opts) {
+        return this.fetchNode(opts.id, opts.depth ?? Number.POSITIVE_INFINITY, opts.maxChildren);
+    }
+    /** Add a sequential chain: step[0] → step[1] → ... via dependsOn. */
+    async addChain(steps) {
+        if (steps.length === 0)
+            return { jobIds: [] };
+        const jobIds = [];
+        let prevId = null;
+        try {
+            for (const step of steps) {
+                const data = compact({
+                    ...jobPayload(step.name, step.data),
+                    __flowParentId: prevId ?? undefined,
+                });
+                const response = await this.connection.call(compact({
+                    cmd: 'PUSH',
+                    queue: step.queueName,
+                    data,
+                    ...wireJobOptions(step.opts),
+                    dependsOn: prevId ? [prevId] : undefined,
+                }));
+                const id = String(response.id);
+                jobIds.push(id);
+                prevId = id;
+            }
+            return { jobIds };
+        }
+        catch (err) {
+            await this.rollback(jobIds);
+            throw err;
+        }
+    }
+    /** Parallel jobs converging into a final fan-in job. */
+    async addBulkThen(parallel, final) {
+        const parallelIds = [];
+        try {
+            const results = await Promise.allSettled(parallel.map(async (step) => {
+                const response = await this.connection.call(compact({
+                    cmd: 'PUSH',
+                    queue: step.queueName,
+                    data: jobPayload(step.name, step.data),
+                    ...wireJobOptions(step.opts),
+                }));
+                return String(response.id);
+            }));
+            const errors = [];
+            for (const r of results) {
+                if (r.status === 'fulfilled')
+                    parallelIds.push(r.value);
+                else
+                    errors.push(r.reason);
+            }
+            if (errors.length > 0) {
+                await this.rollback(parallelIds);
+                throw errors[0] instanceof Error ? errors[0] : new Error(String(errors[0]));
+            }
+            const finalData = {
+                ...jobPayload(final.name, final.data),
+                __flowParentIds: parallelIds,
+            };
+            const finalId = await this.pushWithParent(final.queueName, finalData, final.opts, null, parallelIds);
+            return { parallelIds, finalId };
+        }
+        catch (err) {
+            await this.rollback(parallelIds);
+            throw err;
+        }
+    }
+    close() {
+        if (this.ownsConnection)
+            this.connection.close();
+    }
+    // ----------------------------------------------------------------- internals
+    async addNode(node, parentRef, created) {
+        const childNodes = [];
+        const childIds = [];
+        if (node.children && node.children.length > 0) {
+            const tempParent = { id: 'pending', queue: node.queueName };
+            const results = await Promise.all(node.children.map((child) => this.addNode(child, tempParent, created)));
+            for (const childNode of results) {
+                childNodes.push(childNode);
+                childIds.push(childNode.job.id);
+            }
+        }
+        const jobData = jobPayload(node.name, node.data);
+        if (parentRef) {
+            jobData.__parentId = parentRef.id;
+            jobData.__parentQueue = parentRef.queue;
+        }
+        if (childIds.length > 0)
+            jobData.__childrenIds = childIds;
+        const id = await this.pushWithParent(node.queueName, jobData, node.opts, parentRef, childIds);
+        created.push(id);
+        const job = new Job({ id, queue: node.queueName, data: jobData }, this.connection);
+        return { job, children: childNodes.length > 0 ? childNodes : undefined };
+    }
+    async pushWithParent(queue, data, opts, parentRef, childIds) {
+        const response = await this.connection.call(compact({
+            cmd: 'PUSH',
+            queue,
+            data,
+            ...wireJobOptions(opts),
+            parentId: parentRef?.id,
+            childrenIds: childIds.length > 0 ? childIds : undefined,
+            dependsOn: childIds.length > 0 ? childIds : undefined,
+        }));
+        const parentJobId = String(response.id);
+        // fix up children with the real parent id (like the official client)
+        for (const childId of childIds) {
+            await this.connection.call({ cmd: 'UpdateParent', childId, parentId: parentJobId });
+        }
+        return parentJobId;
+    }
+    async fetchNode(id, depth, maxChildren) {
+        const response = await this.connection.call({ cmd: 'GetJob', id });
+        const raw = response.job;
+        if (!raw)
+            return null;
+        const job = new Job(raw, this.connection);
+        if (depth <= 0 || job.childrenIds.length === 0)
+            return { job };
+        const limit = maxChildren ?? job.childrenIds.length;
+        const children = [];
+        for (const childId of job.childrenIds.slice(0, limit)) {
+            const child = await this.fetchNode(childId, depth - 1, maxChildren);
+            if (child)
+                children.push(child);
+        }
+        return { job, children: children.length > 0 ? children : undefined };
+    }
+    async rollback(jobIds) {
+        await Promise.all(jobIds.map(async (id) => {
+            try {
+                await this.connection.call({ cmd: 'Cancel', id });
+            }
+            catch {
+                // ignore cleanup errors
+            }
+        }));
+    }
+}

package/dist/frame.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Wire framing for the bunqueue TCP protocol: 4-byte big-endian length
+ * prefix + msgpack payload. Runtime-neutral (plain Buffer operations).
+ */
+export declare const PROTOCOL_VERSION = 1;
+export declare const MAX_FRAME_SIZE: number;
+/** Drop undefined-valued keys so the msgpack frame stays minimal. */
+export declare function compact<T extends Record<string, unknown>>(obj: T): T;
+/** Frame a msgpack payload with the 4-byte big-endian length prefix. */
+export declare function frame(payload: Uint8Array): Buffer;
+/** Incremental length-prefixed frame parser (O(total bytes) via offset cursor). */
+export declare class FrameParser {
+    private buffer;
+    addData(data: Buffer): Buffer[];
+    clear(): void;
+}

package/dist/frame.js

@@ -0,0 +1,57 @@
+/**
+ * Wire framing for the bunqueue TCP protocol: 4-byte big-endian length
+ * prefix + msgpack payload. Runtime-neutral (plain Buffer operations).
+ */
+import { ConnectionClosedError } from './errors.js';
+export const PROTOCOL_VERSION = 1;
+export const MAX_FRAME_SIZE = 64 * 1024 * 1024; // mirror server-side limit
+/** Drop undefined-valued keys so the msgpack frame stays minimal. */
+export function compact(obj) {
+    const out = {};
+    for (const key in obj) {
+        if (obj[key] !== undefined)
+            out[key] = obj[key];
+    }
+    return out;
+}
+/** Frame a msgpack payload with the 4-byte big-endian length prefix. */
+export function frame(payload) {
+    const framed = Buffer.allocUnsafe(4 + payload.length);
+    framed.writeUInt32BE(payload.length, 0);
+    framed.set(payload, 4);
+    return framed;
+}
+/** Incremental length-prefixed frame parser (O(total bytes) via offset cursor). */
+export class FrameParser {
+    buffer = Buffer.alloc(0);
+    addData(data) {
+        const buffer = this.buffer.length === 0 ? data : Buffer.concat([this.buffer, data]);
+        const frames = [];
+        let offset = 0;
+        while (buffer.length - offset >= 4) {
+            const length = buffer.readUInt32BE(offset);
+            if (length > MAX_FRAME_SIZE) {
+                this.buffer = Buffer.alloc(0);
+                throw new ConnectionClosedError(`frame size ${length} exceeds maximum`);
+            }
+            if (buffer.length - offset < 4 + length)
+                break;
+            // explicit copy so frames never alias the retained tail
+            frames.push(Buffer.from(buffer.subarray(offset + 4, offset + 4 + length)));
+            offset += 4 + length;
+        }
+        if (offset >= buffer.length) {
+            this.buffer = Buffer.alloc(0);
+        }
+        else if (offset === 0) {
+            this.buffer = buffer;
+        }
+        else {
+            this.buffer = Buffer.from(buffer.subarray(offset));
+        }
+        return frames;
+    }
+    clear() {
+        this.buffer = Buffer.alloc(0);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * bunqueue-client — cross-runtime TypeScript SDK for bunqueue (TCP mode).
+ * Works on Node.js ≥20, Bun and Deno ≥2 (uses only node: builtins + msgpackr).
+ */
+export type { Command, ConnectionOptions, Response, TlsOption } from './connection.js';
+export { Connection } from './connection.js';
+export { AuthError, BunqueueError, CommandError, CommandTimeoutError, ConnectionClosedError, UnrecoverableError, } from './errors.js';
+export { FlowProducer } from './flow.js';
+export type { FlowJob, FlowProducerOptions, FlowStep, GetFlowOptions, JobNode, } from './flow-types.js';
+export { MAX_FRAME_SIZE, PROTOCOL_VERSION } from './frame.js';
+export type { JobRaw } from './job.js';
+export { Job } from './job.js';
+export type { BulkJobEntry, QueueOptions } from './queue.js';
+export { Queue } from './queue.js';
+export type { SchedulerOptions } from './queue-admin.js';
+export type { BackoffOptions, DeduplicationOptions, JobCounts, JobOptions, JobStateName, RepeatOptions, } from './types.js';
+export { Worker } from './worker.js';
+export type { Processor, WorkerOptions } from './worker-types.js';
+export declare const __version__ = "0.1.0";

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * bunqueue-client — cross-runtime TypeScript SDK for bunqueue (TCP mode).
+ * Works on Node.js ≥20, Bun and Deno ≥2 (uses only node: builtins + msgpackr).
+ */
+export { Connection } from './connection.js';
+export { AuthError, BunqueueError, CommandError, CommandTimeoutError, ConnectionClosedError, UnrecoverableError, } from './errors.js';
+export { FlowProducer } from './flow.js';
+export { MAX_FRAME_SIZE, PROTOCOL_VERSION } from './frame.js';
+export { Job } from './job.js';
+export { Queue } from './queue.js';
+export { Worker } from './worker.js';
+export const __version__ = '0.1.0';

package/dist/job.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 } from './connection.js';
+export type JobRaw = Record<string, unknown>;
+export type ProgressHook = (job: Job, progress: number) => void;
+export declare class Job<T = unknown> {
+    readonly raw: JobRaw;
+    readonly token: string | undefined;
+    private readonly conn;
+    private readonly onProgress;
+    constructor(raw: JobRaw, connection?: Connection, token?: string, onProgress?: ProgressHook);
+    get id(): string;
+    get queue(): string;
+    get data(): T;
+    /** Job name (stored inside `data.name`, mirroring the official client). */
+    get name(): string | undefined;
+    get priority(): number;
+    get attempts(): number;
+    get maxAttempts(): number;
+    get createdAt(): number | undefined;
+    get startedAt(): number | null;
+    get completedAt(): number | null;
+    get customId(): string | null;
+    get tags(): string[];
+    get groupId(): string | null;
+    get parentId(): string | null;
+    get childrenIds(): string[];
+    get dependsOn(): string[];
+    get progress(): number;
+    get stacktrace(): string[] | null;
+    get state(): string | undefined;
+    private call;
+    /** Report processing progress (0-100) to the server. */
+    updateProgress(progress: number, message?: string): Promise<void>;
+    /** Append a log row to the job. */
+    log(message: string, level?: 'info' | 'warn' | 'error'): Promise<void>;
+    /** Renew this job's lock (stall detection). */
+    heartbeat(): Promise<void>;
+    extendLock(durationMs: number): Promise<void>;
+    getState(): Promise<string>;
+    getChildrenValues<R = unknown>(): Promise<Record<string, R>>;
+    remove(): Promise<void>;
+    discard(): Promise<void>;
+    promote(): Promise<void>;
+    /** failed → waiting (BullMQ contract; MoveToWait over TCP). */
+    retry(): Promise<void>;
+    updateData(data: unknown): Promise<void>;
+    changePriority(opts: {
+        priority: number;
+        lifo?: boolean;
+    }): Promise<void>;
+    changeDelay(delayMs: number): Promise<void>;
+    moveToDelayed(delayMs: number): Promise<void>;
+}

package/dist/job.js

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

package/dist/queue-admin.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Queue admin surface: DLQ, stall/DLQ configs, rate limits, schedulers,
+ * monitoring and webhooks. Merged onto Queue.prototype by queue.ts.
+ */
+import type { Queue } from './queue.js';
+import { type JobOptions } 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 declare const adminMethods: {
+    getDlq(this: Ctx, count?: number): Promise<Raw[]>;
+    retryDlq(this: Ctx, jobId?: string): Promise<number>;
+    purgeDlq(this: Ctx): Promise<number>;
+    setDlqConfig(this: Ctx, config: Raw): Promise<void>;
+    getDlqConfig(this: Ctx): Promise<Raw>;
+    setStallConfig(this: Ctx, config: Raw): Promise<void>;
+    getStallConfig(this: Ctx): Promise<Raw>;
+    /** `duration` accepted for signature parity; the TCP wire carries only `limit`. */
+    setGlobalRateLimit(this: Ctx, max: number, _duration?: number): Promise<void>;
+    removeGlobalRateLimit(this: Ctx): Promise<void>;
+    setGlobalConcurrency(this: Ctx, concurrency: number): Promise<void>;
+    removeGlobalConcurrency(this: Ctx): Promise<void>;
+    /** Create/update a recurring job scheduler (cron pattern or fixed interval). */
+    upsertJobScheduler(this: Ctx, schedulerId: string, repeat: SchedulerOptions, template?: {
+        name?: string;
+        data?: unknown;
+        opts?: JobOptions;
+    }): Promise<void>;
+    removeJobScheduler(this: Ctx, schedulerId: string): Promise<void>;
+    getJobScheduler(this: Ctx, schedulerId: string): Promise<Raw | null>;
+    getJobSchedulers(this: Ctx): Promise<Raw[]>;
+    getJobSchedulersCount(this: Ctx): Promise<number>;
+    /** Helper: run `name` on a cron `schedule`. */
+    addCron(this: Ctx, name: string, schedule: string, data?: unknown, opts?: JobOptions): Promise<void>;
+    /** Helper: run `name` every `intervalMs` milliseconds. */
+    every(this: Ctx, name: string, intervalMs: number, data?: unknown, opts?: JobOptions): Promise<void>;
+    getWorkers(this: Ctx): Promise<Raw[]>;
+    getWorkersCount(this: Ctx): Promise<number>;
+    getStats(this: Ctx): Promise<Raw>;
+    getMetrics(this: Ctx): Promise<Raw>;
+    /** Server returns queue NAMES (strings). */
+    listQueues(this: Ctx): Promise<string[]>;
+    addWebhook(this: Ctx, opts: {
+        url: string;
+        events: string[];
+        queue?: string;
+        secret?: string;
+    }): Promise<Raw>;
+    removeWebhook(this: Ctx, webhookId: string): Promise<void>;
+    listWebhooks(this: Ctx): Promise<Raw[]>;
+    setWebhookEnabled(this: Ctx, webhookId: string, enabled: boolean): Promise<void>;
+};
+export type QueueAdminApi = typeof adminMethods;
+export {};