bunqueue-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Egeo Minotti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# bunqueue-client — TypeScript SDK (Node / Bun / Deno)
+
+Cross-runtime TypeScript client for [bunqueue](https://github.com/egeominotti/bunqueue),
+the high-performance job queue server. Talks the native TCP protocol
+(msgpack, pipelined, port 6789) — feature parity with the built-in Bun client,
+but runs on **any** modern JS/TS runtime.
+
+The bunqueue **server** runs on Bun (binary or Docker). This SDK lets any
+Node, Bun, or Deno service produce and consume jobs on it: *one queue, any
+language, any runtime*.
+
+## Runtime support
+
+| Runtime | Status | Notes |
+|---|---|---|
+| Node.js ≥ 20 | ✅ tested (58/58 e2e + 8/8 integration) | ESM; TS files run directly on Node ≥ 22 via `--experimental-strip-types` |
+| Bun | ✅ tested (58/58 e2e + 8/8 integration) | works out of the box |
+| Deno ≥ 2 | ✅ tested (58/58 e2e + 8/8 integration) | `node:` builtins + npm `msgpackr` |
+| tsx / ts-node / vitest / jest | ✅ | they run on Node underneath |
+| Cloudflare Workers | ✅ tested (11/11 e2e inside workerd) | needs `nodejs_compat` flag; no long-lived worker loops (request-scoped runtime) — consume via Cron Triggers / Durable Object alarms with batch pulls (covered by the suite); TLS requires a publicly trusted cert |
+| Browser | ❌ | no raw TCP sockets — use the server's HTTP API instead |
+
+The rule that makes this possible: the SDK uses **only `node:*` builtins**
+(`net`, `tls`, `events`, `crypto`, `os`) — no `Bun.*` globals, no
+`bun:`/`deno:` imports. Single runtime dependency: `msgpackr`.
+
+## Install
+
+```bash
+npm install bunqueue-client    # or: bun add / pnpm add / deno add npm:bunqueue-client
+```
+
+## Producer
+
+```typescript
+import { Queue } from 'bunqueue-client';
+
+const queue = new Queue('emails', { host: 'localhost', port: 6789 });
+
+await queue.add('send', { to: 'user@example.com' }, { priority: 5, attempts: 3 });
+await queue.addBulk([
+  { name: 'send', data: { to: 'a@b.c' } },
+  { name: 'send', data: { to: 'x@y.z' }, opts: { delay: 5000 } },
+]);
+
+const counts = await queue.getJobCounts();
+queue.close();
+```
+
+## Worker
+
+```typescript
+import { Worker, UnrecoverableError } from 'bunqueue-client';
+
+const worker = new Worker(
+  'emails',
+  async (job) => {
+    await job.updateProgress(50);
+    if (job.data.invalid) throw new UnrecoverableError('bad payload'); // no retries → DLQ
+    return { sent: true };
+  },
+  { host: 'localhost', port: 6789, concurrency: 10 }
+);
+
+worker.on('completed', (job, result) => console.log(job.id, result));
+worker.on('failed', (job, err) => console.error(job.id, err.message));
+
+// later: await worker.close();  // graceful — waits for in-flight jobs
+```
+
+Retry, backoff, DLQ, stall detection, priorities and rate limiting all run
+**server-side** — the worker only pulls, heartbeats and acks.
+
+## Flows
+
+```typescript
+import { FlowProducer } from 'bunqueue-client';
+
+const flow = new FlowProducer({ host: 'localhost', port: 6789 });
+
+// sequential chain: step1 → step2 → step3
+await flow.addChain([
+  { name: 'step1', queueName: 'pipeline' },
+  { name: 'step2', queueName: 'pipeline' },
+  { name: 'step3', queueName: 'pipeline' },
+]);
+
+// fan-in: parallel jobs converge into a final job that reads their results
+const { finalId } = await flow.addBulkThen(
+  [
+    { name: 'part1', queueName: 'pipeline' },
+    { name: 'part2', queueName: 'pipeline' },
+  ],
+  { name: 'merge', queueName: 'pipeline' }
+);
+// inside the 'merge' processor: await job.getChildrenValues()
+
+// parent/child tree (children run BEFORE the parent)
+const node = await flow.add({
+  name: 'assemble', queueName: 'orders',
+  children: [
+    { name: 'reserve-stock', queueName: 'orders' },
+    { name: 'charge-card', queueName: 'orders' },
+  ],
+});
+```
+
+## Schedulers (cron)
+
+```typescript
+await queue.addCron('daily-report', '0 9 * * *', { type: 'report' });
+await queue.every('health-ping', 30_000, { type: 'ping' });
+await queue.removeJobScheduler('daily-report');
+```
+
+## TLS + Auth
+
+```typescript
+const queue = new Queue('emails', {
+  host: 'queue.example.com',
+  port: 6789,
+  token: process.env.BUNQUEUE_TOKEN,
+  tls: { caFile: './ca.pem' }, // or `true` for system CAs
+});
+```
+
+## Feature surface
+
+- **Queue** — add/addBulk with full `JobOptions` (priority, delay, attempts,
+  backoff, ttl, timeout, jobId, deduplication, dependsOn, tags, groupId, lifo,
+  removeOnComplete/Fail, durable, repeat, debounce, …)
+- **Query** — getJob, getJobByCustomId, getJobs + per-state helpers, state,
+  result, progress, waitForJob, counts (+ per priority), children values, logs
+- **Control** — pause/resume/drain/obliterate/clean, remove, discard, promote,
+  retryJob/retryJobs, move to wait/delayed, change priority/delay, update
+  data, extend lock
+- **DLQ** — getDlq, retryDlq, purgeDlq, DLQ config
+- **Admin** — rate limit, global concurrency, stall config, webhooks,
+  stats/metrics/listQueues/getWorkers
+- **Worker events** — `ready`, `active`, `completed`, `failed`, `progress`,
+  `drained`, `error`, `closed`; automatic lock heartbeats (jobs longer than
+  the lock TTL survive)
+
+Not applicable outside Bun (by design): embedded mode, sandboxed workers,
+`QueueEvents` (in-process subscription — use webhooks or the HTTP SSE/WS
+endpoints instead).
+
+## Development
+
+```bash
+bun install
+bun run build          # tsc → dist/
+bun run check          # biome check
+
+# Test suites (each spawns a real bunqueue server from the repo root)
+bun tests/integration.ts                            # smoke
+bun tests/e2e.ts                                    # full surface + edge cases + realistic load
+node --experimental-strip-types tests/e2e.ts        # same file on Node ≥22
+deno run -A tests/e2e.ts                            # same file on Deno ≥2
+bun run test:workers                                # full suite INSIDE workerd (Cloudflare Workers)
+```
+
+Style rules: Biome, max 250 lines per file, relative imports with explicit
+`.js` extension (NodeNext resolution — required for Node ESM). See `CLAUDE.md`
+for the full development guide and wire-protocol gotchas.

package/dist/connection-types.d.ts

@@ -0,0 +1,24 @@
+/** 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>;
+}

package/dist/connection-types.js

@@ -0,0 +1,2 @@
+/** Connection option and message types. */
+export {};

package/dist/connection.d.ts

@@ -0,0 +1,44 @@
+/**
+ * TCP connection to a bunqueue server — cross-runtime (Node.js, Bun, Deno).
+ *
+ * Requests carry a `reqId` string; the server echoes it back, enabling
+ * pipelining (many in-flight commands per socket). Uses only `node:`
+ * builtins (net/tls), which Node, Bun and Deno all support.
+ */
+import type { Command, ConnectionOptions, Response, TlsOption } from './connection-types.js';
+export type { Command, ConnectionOptions, Response, TlsOption } from './connection-types.js';
+/** A single pipelined TCP connection to a bunqueue server. */
+export declare class Connection {
+    readonly host: string;
+    readonly port: number;
+    readonly token: string | undefined;
+    readonly tls: TlsOption;
+    readonly connectTimeoutMs: number;
+    readonly commandTimeoutMs: number;
+    private socket;
+    private connected;
+    private closed;
+    private connecting;
+    private pending;
+    private reqCounter;
+    private parser;
+    constructor(options?: ConnectionOptions);
+    get isConnected(): boolean;
+    /** Open the socket (and authenticate) if not already connected. */
+    connect(): Promise<void>;
+    private doConnect;
+    private openSocket;
+    /**
+     * Send a command and await its response. Rejects with CommandError when
+     * the server answers ok=false. Reconnects lazily if the link was lost.
+     */
+    call(command: Command, timeoutMs?: number): Promise<Response>;
+    /** Ping the server; returns true when it answers pong. */
+    ping(): Promise<boolean>;
+    /** Protocol negotiation; returns server name/version/protocolVersion. */
+    hello(): Promise<Response>;
+    /** Close permanently; in-flight commands reject. */
+    close(): void;
+    private handleData;
+    private teardown;
+}

package/dist/connection.js

@@ -0,0 +1,229 @@
+/**
+ * TCP connection to a bunqueue server — cross-runtime (Node.js, Bun, Deno).
+ *
+ * Requests carry a `reqId` string; the server echoes it back, enabling
+ * pipelining (many in-flight commands per socket). Uses only `node:`
+ * builtins (net/tls), which Node, Bun and Deno all support.
+ */
+import { readFileSync } from 'node:fs';
+import { connect as netConnect } from 'node:net';
+import { connect as tlsConnect } from 'node:tls';
+import { pack, unpack } from 'msgpackr';
+import { AuthError, CommandError, CommandTimeoutError, ConnectionClosedError } from './errors.js';
+import { compact, FrameParser, frame, PROTOCOL_VERSION } from './frame.js';
+/** A single pipelined TCP connection to a bunqueue server. */
+export class Connection {
+    host;
+    port;
+    token;
+    tls;
+    connectTimeoutMs;
+    commandTimeoutMs;
+    socket = null;
+    connected = false;
+    closed = false;
+    connecting = null;
+    pending = new Map();
+    reqCounter = 0;
+    parser = new FrameParser();
+    constructor(options = {}) {
+        this.host = options.host ?? 'localhost';
+        this.port = options.port ?? 6789;
+        this.token = options.token;
+        this.tls = options.tls;
+        this.connectTimeoutMs = options.connectTimeoutMs ?? 5000;
+        this.commandTimeoutMs = options.commandTimeoutMs ?? 10_000;
+    }
+    get isConnected() {
+        return this.connected;
+    }
+    /** Open the socket (and authenticate) if not already connected. */
+    async connect() {
+        if (this.connected)
+            return;
+        if (this.closed)
+            throw new ConnectionClosedError('connection closed by client');
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = this.doConnect().finally(() => {
+            this.connecting = null;
+        });
+        return this.connecting;
+    }
+    async doConnect() {
+        const socket = await this.openSocket();
+        socket.setNoDelay(true);
+        this.parser.clear();
+        this.socket = socket;
+        socket.on('data', (chunk) => this.handleData(chunk));
+        socket.on('error', () => this.teardown());
+        socket.on('close', () => this.teardown());
+        this.connected = true;
+        if (this.token) {
+            try {
+                await this.call({ cmd: 'Auth', token: this.token });
+            }
+            catch (err) {
+                this.teardown();
+                if (err instanceof CommandError)
+                    throw new AuthError(err.message);
+                throw err;
+            }
+        }
+    }
+    openSocket() {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                socket.destroy();
+                reject(new ConnectionClosedError(`connect timeout to ${this.host}:${this.port}`));
+            }, this.connectTimeoutMs);
+            const onError = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(new ConnectionClosedError(`connect failed: ${err.message}`));
+            };
+            const onReady = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                socket.off('error', onError);
+                resolve(socket);
+            };
+            let socket;
+            if (this.tls) {
+                const tlsOpts = { host: this.host, port: this.port };
+                if (typeof this.tls === 'object') {
+                    if (this.tls.caFile)
+                        tlsOpts.ca = readFileSync(this.tls.caFile);
+                    if (this.tls.rejectUnauthorized === false)
+                        tlsOpts.rejectUnauthorized = false;
+                }
+                socket = tlsConnect(tlsOpts, onReady);
+            }
+            else {
+                socket = netConnect({ host: this.host, port: this.port }, onReady);
+            }
+            socket.on('error', onError);
+        });
+    }
+    /**
+     * Send a command and await its response. Rejects with CommandError when
+     * the server answers ok=false. Reconnects lazily if the link was lost.
+     */
+    async call(command, timeoutMs) {
+        if (!this.connected)
+            await this.connect();
+        const socket = this.socket;
+        if (!socket)
+            throw new ConnectionClosedError('not connected');
+        this.reqCounter = (this.reqCounter + 1) & 0x7fffffff;
+        const reqId = String(this.reqCounter);
+        const payload = pack({ ...compact(command), reqId });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(reqId);
+                reject(new CommandTimeoutError(`no response for ${command.cmd} within timeout`));
+            }, timeoutMs ?? this.commandTimeoutMs);
+            this.pending.set(reqId, {
+                resolve: (response) => {
+                    clearTimeout(timer);
+                    if (!response.ok) {
+                        reject(new CommandError(String(response.error ?? 'unknown server error')));
+                    }
+                    else {
+                        resolve(response);
+                    }
+                },
+                reject: (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                },
+                timer,
+            });
+            socket.write(frame(payload), (err) => {
+                if (err) {
+                    const entry = this.pending.get(reqId);
+                    this.pending.delete(reqId);
+                    entry?.reject(new ConnectionClosedError(`send failed: ${err.message}`));
+                    this.teardown();
+                }
+            });
+        });
+    }
+    /** Ping the server; returns true when it answers pong. */
+    async ping() {
+        try {
+            const response = await this.call({ cmd: 'Ping' });
+            const data = response.data;
+            return data?.pong === true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Protocol negotiation; returns server name/version/protocolVersion. */
+    hello() {
+        return this.call({
+            cmd: 'Hello',
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: ['pipelining'],
+        });
+    }
+    /** Close permanently; in-flight commands reject. */
+    close() {
+        this.closed = true;
+        this.teardown();
+    }
+    handleData(chunk) {
+        let frames;
+        try {
+            frames = this.parser.addData(chunk);
+        }
+        catch {
+            this.teardown();
+            return;
+        }
+        for (const framePayload of frames) {
+            let message;
+            try {
+                message = unpack(framePayload);
+            }
+            catch {
+                continue; // skip unparseable frame; a desynced stream dies via socket error
+            }
+            if (typeof message !== 'object' || message === null)
+                continue;
+            const response = message;
+            const reqId = response.reqId;
+            if (reqId === undefined || reqId === null)
+                continue; // server-push unsupported
+            const entry = this.pending.get(String(reqId));
+            if (entry) {
+                this.pending.delete(String(reqId));
+                entry.resolve(response);
+            }
+        }
+    }
+    teardown() {
+        this.connected = false;
+        const socket = this.socket;
+        this.socket = null;
+        if (socket) {
+            socket.removeAllListeners();
+            socket.destroy();
+        }
+        const pending = this.pending;
+        this.pending = new Map();
+        for (const entry of pending.values()) {
+            clearTimeout(entry.timer);
+            entry.reject(new ConnectionClosedError('connection lost'));
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+/** Exception hierarchy for the bunqueue cross-runtime SDK. */
+export declare class BunqueueError extends Error {
+    constructor(message: string);
+}
+/** The TCP connection is closed or was lost mid-command. */
+export declare class ConnectionClosedError extends BunqueueError {
+}
+/** No response received for a command within the timeout. */
+export declare class CommandTimeoutError extends BunqueueError {
+}
+/** The server answered ok=false; message carries the server error. */
+export declare class CommandError extends BunqueueError {
+}
+/** Authentication with the server failed. */
+export declare class AuthError extends BunqueueError {
+}
+/**
+ * Throw inside a Worker processor to fail the job terminally: skips all
+ * remaining retry attempts and sends the job straight to the DLQ.
+ */
+export declare class UnrecoverableError extends BunqueueError {
+}

package/dist/errors.js

@@ -0,0 +1,25 @@
+/** Exception hierarchy for the bunqueue cross-runtime SDK. */
+export class BunqueueError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** The TCP connection is closed or was lost mid-command. */
+export class ConnectionClosedError extends BunqueueError {
+}
+/** No response received for a command within the timeout. */
+export class CommandTimeoutError extends BunqueueError {
+}
+/** The server answered ok=false; message carries the server error. */
+export class CommandError extends BunqueueError {
+}
+/** Authentication with the server failed. */
+export class AuthError extends BunqueueError {
+}
+/**
+ * Throw inside a Worker processor to fail the job terminally: skips all
+ * remaining retry attempts and sends the job straight to the DLQ.
+ */
+export class UnrecoverableError extends BunqueueError {
+}

package/dist/flow-types.d.ts

@@ -0,0 +1,34 @@
+/** FlowProducer types. */
+import type { Connection, TlsOption } from './connection.js';
+import type { Job } from './job.js';
+import type { JobOptions } from './types.js';
+export interface FlowJob<T = unknown> {
+    name: string;
+    queueName: string;
+    data?: T;
+    opts?: JobOptions;
+    children?: FlowJob<T>[];
+}
+export interface JobNode<T = unknown> {
+    job: Job<T>;
+    children?: JobNode<T>[];
+}
+export interface FlowStep<T = unknown> {
+    name: string;
+    queueName: string;
+    data?: T;
+    opts?: JobOptions;
+}
+export interface FlowProducerOptions {
+    host?: string;
+    port?: number;
+    token?: string;
+    tls?: TlsOption;
+    connection?: Connection;
+}
+export interface GetFlowOptions {
+    id: string;
+    queueName?: string;
+    depth?: number;
+    maxChildren?: number;
+}

package/dist/flow-types.js

@@ -0,0 +1,2 @@
+/** FlowProducer types. */
+export {};

package/dist/flow.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 type { FlowJob, FlowProducerOptions, FlowStep, GetFlowOptions, JobNode } from './flow-types.js';
+export declare class FlowProducer {
+    readonly connection: Connection;
+    private readonly ownsConnection;
+    constructor(opts?: FlowProducerOptions);
+    /** Add a flow tree. Children are created (and processed) BEFORE their parent. */
+    add<T = unknown>(flow: FlowJob<T>): Promise<JobNode<T>>;
+    addBulk<T = unknown>(flows: FlowJob<T>[]): Promise<JobNode<T>[]>;
+    /** Fetch a flow tree starting from a job id (recursive over childrenIds). */
+    getFlow<T = unknown>(opts: GetFlowOptions): Promise<JobNode<T> | null>;
+    /** Add a sequential chain: step[0] → step[1] → ... via dependsOn. */
+    addChain<T = unknown>(steps: FlowStep<T>[]): Promise<{
+        jobIds: string[];
+    }>;
+    /** Parallel jobs converging into a final fan-in job. */
+    addBulkThen<T = unknown>(parallel: FlowStep<T>[], final: FlowStep<T>): Promise<{
+        parallelIds: string[];
+        finalId: string;
+    }>;
+    close(): void;
+    private addNode;
+    private pushWithParent;
+    private fetchNode;
+    private rollback;
+}