bunqueue-client 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+/** Shared option types + wire mapping, mirroring the official client. */
+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 declare function wireJobOptions(opts?: JobOptions): Record<string, unknown>;
+/** The job name travels inside `data`, mirroring the official client. */
+export declare function jobPayload(name: string, data: unknown): Record<string, unknown>;
+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/dist/types.js

@@ -0,0 +1,50 @@
+/** Shared option types + wire mapping, mirroring the official client. */
+import { compact } from './frame.js';
+/** Map SDK JobOptions to the PUSH/PUSHB wire fields (undefined keys dropped). */
+export function wireJobOptions(opts = {}) {
+    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, data) {
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        return { name, ...data };
+    }
+    return data === undefined || data === null ? { name } : { name, payload: data };
+}

package/dist/worker-base.d.ts

@@ -0,0 +1,51 @@
+/**
+ * WorkerBase: lifecycle state, cooperative cancellation and safe command
+ * dispatch shared by the Worker pull loop (worker.ts).
+ */
+import { EventEmitter } from 'node:events';
+import { Connection } from './connection.js';
+import { type WorkerOptions } from './worker-types.js';
+export declare 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: Map<string, string>;
+    protected readonly cancelledJobs: Set<string>;
+    protected stopped: boolean;
+    protected paused: boolean;
+    protected closedFlag: boolean;
+    protected running: boolean;
+    protected wasBusy: boolean;
+    protected processed: number;
+    protected failedCount: number;
+    protected readyPromise: Promise<void>;
+    protected readyResolve: (() => void) | null;
+    protected loopPromise: Promise<void> | null;
+    protected heartbeatTimer: ReturnType<typeof setInterval> | null;
+    constructor(queue: string, opts?: WorkerOptions);
+    pause(): void;
+    resume(): void;
+    isRunning(): boolean;
+    isPaused(): boolean;
+    isClosed(): boolean;
+    waitUntilReady(): Promise<void>;
+    /**
+     * 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;
+    cancelAllJobs(reason?: string): void;
+    isJobCancelled(jobId: string): boolean;
+    /** Graceful shutdown: stop pulling, wait for in-flight jobs. */
+    close(): Promise<void>;
+    protected safeCall(command: Record<string, unknown> & {
+        cmd: string;
+    }): Promise<void>;
+}

package/dist/worker-base.js

@@ -0,0 +1,122 @@
+/**
+ * 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 } from './worker-types.js';
+export class WorkerBase extends EventEmitter {
+    queue;
+    concurrency;
+    batchSize;
+    pollTimeoutMs;
+    lockTtlMs;
+    heartbeatIntervalS;
+    workerId;
+    name;
+    connection;
+    active = new Map(); // job id -> lock token
+    cancelledJobs = new Set();
+    stopped = false;
+    paused = false;
+    closedFlag = false;
+    running = false;
+    wasBusy = false;
+    processed = 0;
+    failedCount = 0;
+    readyPromise;
+    readyResolve = null;
+    loopPromise = null;
+    heartbeatTimer = null;
+    constructor(queue, opts = {}) {
+        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() {
+        this.paused = true;
+    }
+    resume() {
+        this.paused = false;
+    }
+    isRunning() {
+        return this.running && !this.closedFlag;
+    }
+    isPaused() {
+        return this.paused;
+    }
+    isClosed() {
+        return this.closedFlag;
+    }
+    async waitUntilReady() {
+        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, reason) {
+        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) {
+        for (const jobId of this.active.keys()) {
+            this.cancelledJobs.add(jobId);
+            this.emit('cancelled', { jobId, reason: reason ?? 'All jobs cancelled' });
+        }
+    }
+    isJobCancelled(jobId) {
+        return this.cancelledJobs.has(jobId);
+    }
+    /** Graceful shutdown: stop pulling, wait for in-flight jobs. */
+    async close() {
+        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');
+    }
+    async safeCall(command) {
+        try {
+            await this.connection.call(command);
+        }
+        catch (err) {
+            this.emit('error', err);
+        }
+    }
+}

package/dist/worker-types.d.ts

@@ -0,0 +1,27 @@
+/** 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 declare const MAX_POLL_TIMEOUT_MS = 30000;
+export declare const MAX_STACK_LINES = 20;
+export declare const RECONNECT_BACKOFF_MS: number[];
+export declare const sleep: (ms: number) => Promise<void>;

package/dist/worker-types.js

@@ -0,0 +1,5 @@
+/** Worker option types and shared constants. */
+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) => new Promise((resolve) => setTimeout(resolve, ms));

package/dist/worker.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Worker: pulls jobs over TCP and runs a processor with bounded concurrency.
+ *
+ * All queue semantics (retry, backoff, DLQ, stall detection, priorities)
+ * live in the bunqueue server — the worker pulls, heartbeats and acks/fails.
+ * Lifecycle state and cooperative cancel live in WorkerBase.
+ */
+import { WorkerBase } from './worker-base.js';
+import { type Processor, type WorkerOptions } from './worker-types.js';
+export declare class Worker<T = unknown, R = unknown> extends WorkerBase {
+    private readonly processor;
+    constructor(queue: string, processor: Processor<T, R>, opts?: WorkerOptions);
+    /** Start the pull loop (no-op if already running). */
+    run(): void;
+    private loop;
+    private pollOnce;
+    private runJob;
+    private startHeartbeat;
+    private register;
+}

package/dist/worker.js

@@ -0,0 +1,151 @@
+/**
+ * Worker: pulls jobs over TCP and runs a processor with bounded concurrency.
+ *
+ * All queue semantics (retry, backoff, DLQ, stall detection, priorities)
+ * live in the bunqueue server — the worker pulls, heartbeats and acks/fails.
+ * Lifecycle state and cooperative cancel live in WorkerBase.
+ */
+import { hostname } from 'node:os';
+import { CommandTimeoutError, ConnectionClosedError, UnrecoverableError } from './errors.js';
+import { compact } from './frame.js';
+import { Job } from './job.js';
+import { WorkerBase } from './worker-base.js';
+import { MAX_STACK_LINES, RECONNECT_BACKOFF_MS, sleep, } from './worker-types.js';
+export class Worker extends WorkerBase {
+    processor;
+    constructor(queue, processor, opts = {}) {
+        super(queue, opts);
+        this.processor = processor;
+        if (opts.autorun !== false)
+            this.run();
+    }
+    /** Start the pull loop (no-op if already running). */
+    run() {
+        if (this.running || this.closedFlag)
+            return;
+        this.running = true;
+        this.loopPromise = this.loop().catch((err) => {
+            this.emit('error', err);
+        });
+    }
+    // -------------------------------------------------------------------- loop
+    async loop() {
+        await this.register();
+        this.readyResolve?.();
+        this.emit('ready');
+        this.startHeartbeat();
+        let backoffIdx = 0;
+        while (!this.stopped) {
+            if (this.paused) {
+                await sleep(50);
+                continue;
+            }
+            try {
+                await this.pollOnce();
+                backoffIdx = 0;
+            }
+            catch (err) {
+                this.emit('error', err);
+                if (err instanceof ConnectionClosedError || err instanceof CommandTimeoutError) {
+                    const delay = RECONNECT_BACKOFF_MS[Math.min(backoffIdx, RECONNECT_BACKOFF_MS.length - 1)];
+                    backoffIdx += 1;
+                    await sleep(delay);
+                }
+                else {
+                    await sleep(200);
+                }
+            }
+        }
+    }
+    async pollOnce() {
+        const free = this.concurrency - this.active.size;
+        if (free <= 0) {
+            await sleep(20);
+            return;
+        }
+        const response = await this.connection.call({
+            cmd: 'PULLB',
+            queue: this.queue,
+            count: Math.min(free, this.batchSize),
+            timeout: this.pollTimeoutMs,
+            owner: this.workerId,
+            lockTtl: this.lockTtlMs,
+        }, this.pollTimeoutMs + 10_000);
+        const jobs = (response.jobs ?? []);
+        const tokens = (response.tokens ?? []);
+        if (jobs.length === 0) {
+            if (this.wasBusy && this.active.size === 0) {
+                this.wasBusy = false;
+                this.emit('drained');
+            }
+            return;
+        }
+        this.wasBusy = true;
+        for (let i = 0; i < jobs.length; i++) {
+            const jobId = String(jobs[i].id);
+            this.active.set(jobId, tokens[i]);
+            // fire-and-forget: bounded by the free-slot accounting above
+            void this.runJob(jobs[i], tokens[i]);
+        }
+    }
+    async runJob(raw, token) {
+        const job = new Job(raw, this.connection, token, (j, p) => this.emit('progress', j, p));
+        this.emit('active', job);
+        try {
+            const result = await this.processor(job);
+            this.processed += 1;
+            await this.safeCall(compact({ cmd: 'ACK', id: job.id, token, result: result ?? undefined }));
+            this.emit('completed', job, result);
+        }
+        catch (err) {
+            this.failedCount += 1;
+            const error = err instanceof Error ? err : new Error(String(err));
+            const stack = (error.stack ?? error.message).split('\n').slice(-MAX_STACK_LINES);
+            await this.safeCall(compact({
+                cmd: 'FAIL',
+                id: job.id,
+                token,
+                error: error.message || error.name,
+                stack,
+                unrecoverable: err instanceof UnrecoverableError ? true : undefined,
+            }));
+            this.emit('failed', job, error);
+        }
+        finally {
+            this.active.delete(job.id);
+            this.cancelledJobs.delete(job.id);
+        }
+    }
+    // --------------------------------------------------------------- heartbeat
+    startHeartbeat() {
+        this.heartbeatTimer = setInterval(() => {
+            void (async () => {
+                await this.safeCall({
+                    cmd: 'Heartbeat',
+                    id: this.workerId,
+                    activeJobs: this.active.size,
+                    processed: this.processed,
+                    failed: this.failedCount,
+                });
+                if (this.active.size > 0) {
+                    const ids = [...this.active.keys()];
+                    const tokens = ids.map((id) => this.active.get(id));
+                    await this.safeCall({ cmd: 'JobHeartbeatB', ids, tokens });
+                }
+            })();
+        }, this.heartbeatIntervalS * 1000);
+        this.heartbeatTimer.unref?.(); // don't keep the process alive for heartbeats
+    }
+    async register() {
+        await this.safeCall({
+            cmd: 'RegisterWorker',
+            name: this.name,
+            queues: [this.queue],
+            concurrency: this.concurrency,
+            workerId: this.workerId,
+            hostname: hostname(),
+            pid: process.pid,
+            startedAt: Date.now(),
+        });
+    }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "bunqueue-client",
+  "version": "0.1.0",
+  "description": "Cross-runtime TypeScript client for the bunqueue job queue server — Node.js, Bun, Deno and Cloudflare Workers",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "bun tests/e2e.ts",
+    "test:integration": "bun tests/integration.ts",
+    "lint": "biome lint src tests",
+    "format": "biome format --write src tests",
+    "check": "biome check src tests",
+    "test:workers": "cd tests/workers && node run.mjs"
+  },
+  "keywords": [
+    "queue",
+    "jobs",
+    "worker",
+    "bunqueue",
+    "task-queue",
+    "background-jobs",
+    "nodejs",
+    "deno",
+    "bun",
+    "cloudflare-workers"
+  ],
+  "dependencies": {
+    "msgpackr": "^1.11.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  },
+  "author": "Egeo Minotti",
+  "homepage": "https://bunqueue.dev/guide/sdks/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/egeominotti/bunqueue.git",
+    "directory": "sdk/typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/egeominotti/bunqueue/issues"
+  },
+  "sideEffects": false
+}

package/src/connection-types.ts

@@ -0,0 +1,21 @@
+/** Connection option and message types. */
+
+export type TlsOption = boolean | { caFile?: string; rejectUnauthorized?: boolean } | undefined;
+
+export interface ConnectionOptions {
+  host?: string;
+  port?: number;
+  token?: string;
+  tls?: TlsOption;
+  connectTimeoutMs?: number;
+  commandTimeoutMs?: number;
+}
+
+export type Command = Record<string, unknown> & { cmd: string };
+export type Response = Record<string, unknown> & { ok: boolean };
+
+export interface Pending {
+  resolve: (response: Response) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}