bunqueue-client 0.1.9 → 0.2.1

package/dist/flow.js

@@ -1,212 +0,0 @@
-/**
- * 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 { CommandError } from './errors.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,
-                    logger: opts.logger,
-                    onTelemetry: opts.onTelemetry,
-                });
-        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, new Set());
-    }
-    /** 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,
-                });
-                // Connection.call compacts internally, so no outer compact() is needed
-                // (nesting it confused generic inference of `data`/`response`).
-                const response = await this.connection.call({
-                    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, visited) {
-        if (visited.has(id))
-            return null; // cycle guard: id already on the current path
-        visited.add(id);
-        // A missing job — the root, or a child removed via removeOnComplete/cancel
-        // (childrenIds is a static push-time list, never pruned) — yields null and
-        // is skipped, returning the surviving partial tree instead of throwing.
-        let response;
-        try {
-            response = await this.connection.call({ cmd: 'GetJob', id });
-        }
-        catch (err) {
-            // Only 'Job not found' means a removed node; a real server error must not
-            // masquerade as a missing child and yield a misleading partial tree.
-            if (err instanceof CommandError && /not found/i.test(err.message))
-                return null;
-            throw err;
-        }
-        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, visited);
-            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/job.js

@@ -1,155 +0,0 @@
-/**
- * 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);
-    }
-    /** Creation time in epoch ms (BullMQ-parity alias of createdAt). */
-    get timestamp() {
-        return this.createdAt ?? Date.now();
-    }
-    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/observability.js

@@ -1,110 +0,0 @@
-/**
- * Observability primitives: a pluggable structured logger and a telemetry
- * sink. Zero hard dependencies — wire your own OpenTelemetry / Prometheus /
- * logging stack through these interfaces. Defaults are no-ops, so the SDK is
- * silent unless you opt in.
- */
-/** Silent logger (the default). */
-export const noopLogger = {
-    debug() { },
-    info() { },
-    warn() { },
-    error() { },
-};
-const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
-/**
- * A console-backed logger. Levels below `min` are dropped. Opt-in — pass it as
- * `logger` when you want the SDK to log to the console.
- */
-export function consoleLogger(min = 'info') {
-    const floor = LEVELS[min];
-    const line = (lvl, msg, meta) => {
-        if (LEVELS[lvl] < floor)
-            return;
-        const suffix = meta && Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : '';
-        const sink = lvl === 'debug' ? console.log : console[lvl];
-        sink(`[bunqueue] ${lvl} ${msg}${suffix}`);
-    };
-    return {
-        debug: (m, meta) => line('debug', m, meta),
-        info: (m, meta) => line('info', m, meta),
-        warn: (m, meta) => line('warn', m, meta),
-        error: (m, meta) => line('error', m, meta),
-    };
-}
-/** Lifecycle telemetry types that are ALSO emitted as EventEmitter events. */
-export const LIFECYCLE_EVENTS = ['connect', 'disconnect', 'reconnect_scheduled'];
-/** High-resolution monotonic clock (Node/Bun/Deno all expose `performance`). */
-export const nowMs = () => performance.now();
-/**
- * Fans a telemetry event out to (1) the telemetry sink, (2) the logger, and
- * (3) — for lifecycle events — the owning EventEmitter, so users can both
- * scrape metrics and attach imperative `connection.on('connect', …)` handlers.
- */
-export class Telemetry {
-    logger;
-    sink;
-    emit;
-    constructor(obs, emit) {
-        // Wrap the user logger so a throwing logger can never break the transport
-        // hot path (dispatch runs inside socket 'data' handlers and connect).
-        const inner = obs?.logger ?? noopLogger;
-        this.logger =
-            inner === noopLogger
-                ? inner
-                : {
-                    debug: (m, meta) => Telemetry.safely(() => inner.debug(m, meta)),
-                    info: (m, meta) => Telemetry.safely(() => inner.info(m, meta)),
-                    warn: (m, meta) => Telemetry.safely(() => inner.warn(m, meta)),
-                    error: (m, meta) => Telemetry.safely(() => inner.error(m, meta)),
-                };
-        this.sink = obs?.onTelemetry;
-        this.emit = emit;
-    }
-    /** Observability must never break the client: swallow consumer errors. */
-    static safely(fn) {
-        try {
-            fn();
-        }
-        catch {
-            /* consumer logging/telemetry error — intentionally ignored */
-        }
-    }
-    get log() {
-        return this.logger;
-    }
-    /** Record a completed command's latency and outcome. */
-    command(cmd, reqId, startMs, ok) {
-        this.dispatch({ type: 'command', cmd, reqId, durationMs: nowMs() - startMs, ok });
-    }
-    timeout(cmd, reqId) {
-        this.logger.warn('command timed out', { cmd, reqId });
-        this.dispatch({ type: 'command_timeout', cmd, reqId });
-    }
-    connected(host, port, generation, startMs) {
-        this.logger.info('connected', { host, port, generation });
-        this.dispatch({ type: 'connect', host, port, generation, durationMs: nowMs() - startMs });
-    }
-    disconnected(host, port, generation) {
-        this.logger.info('disconnected', { host, port, generation });
-        this.dispatch({ type: 'disconnect', host, port, generation });
-    }
-    reconnectScheduled(host, port, attempt, delayMs) {
-        this.logger.warn('reconnect scheduled', { host, port, attempt, delayMs });
-        this.dispatch({ type: 'reconnect_scheduled', host, port, attempt, delayMs });
-    }
-    auth(ok) {
-        this.dispatch({ type: 'auth', ok });
-    }
-    backpressure(inFlight, maxInFlight) {
-        this.dispatch({ type: 'backpressure', inFlight, maxInFlight });
-    }
-    dispatch(event) {
-        // A throwing sink or lifecycle listener must never break the transport:
-        // dispatch runs inside socket 'data' handlers and the connect path.
-        Telemetry.safely(() => this.sink?.(event));
-        if (LIFECYCLE_EVENTS.includes(event.type)) {
-            Telemetry.safely(() => this.emit(event.type, event));
-        }
-    }
-}

package/dist/queue-admin.js

@@ -1,158 +0,0 @@
-/**
- * Queue admin surface: DLQ, stall/DLQ configs, rate limits, schedulers,
- * monitoring and webhooks. Merged onto Queue.prototype by queue.ts.
- */
-import { CommandError } from './errors.js';
-import { compact } from './frame.js';
-import { jobPayload, wireJobOptions } from './types.js';
-export const adminMethods = {
-    // ---------------------------------------------------------------------- dlq
-    async getDlq(count) {
-        const response = await this.call(compact({ cmd: 'Dlq', queue: this.name, count }));
-        return (response.jobs ?? response.data ?? []);
-    },
-    async retryDlq(jobId) {
-        const response = await this.call(compact({ cmd: 'RetryDlq', queue: this.name, jobId }));
-        return Number(response.count ?? 0);
-    },
-    async purgeDlq() {
-        const response = await this.call({ cmd: 'PurgeDlq', queue: this.name });
-        return Number(response.count ?? 0);
-    },
-    async setDlqConfig(config) {
-        await this.call({ cmd: 'SetDlqConfig', queue: this.name, config });
-    },
-    async getDlqConfig() {
-        const response = await this.call({ cmd: 'GetDlqConfig', queue: this.name });
-        return (response.config ?? response.data ?? {});
-    },
-    // -------------------------------------------------------------------- stall
-    async setStallConfig(config) {
-        await this.call({ cmd: 'SetStallConfig', queue: this.name, config });
-    },
-    async getStallConfig() {
-        const response = await this.call({ cmd: 'GetStallConfig', queue: this.name });
-        return (response.config ?? response.data ?? {});
-    },
-    // -------------------------------------------------- rate limit / concurrency
-    /** `duration` accepted for signature parity; the TCP wire carries only `limit`. */
-    async setGlobalRateLimit(max, _duration) {
-        await this.call({ cmd: 'RateLimit', queue: this.name, limit: max });
-    },
-    async removeGlobalRateLimit() {
-        await this.call({ cmd: 'RateLimitClear', queue: this.name });
-    },
-    async setGlobalConcurrency(concurrency) {
-        await this.call({ cmd: 'SetConcurrency', queue: this.name, limit: concurrency });
-    },
-    async removeGlobalConcurrency() {
-        await this.call({ cmd: 'ClearConcurrency', queue: this.name });
-    },
-    // ---------------------------------------------------------------- scheduler
-    /** Create/update a recurring job scheduler (cron pattern or fixed interval). */
-    async upsertJobScheduler(schedulerId, repeat, template = {}) {
-        // Priority and deduplication of spawned jobs travel as TOP-LEVEL Cron
-        // fields (the handler reads cmd.priority/uniqueKey/dedup); inside
-        // jobOptions the server's CronJobOptions silently ignores them.
-        const dedup = template.opts?.deduplication;
-        await this.call(compact({
-            cmd: 'Cron',
-            name: schedulerId,
-            queue: this.name,
-            data: jobPayload(template.name ?? schedulerId, template.data ?? {}),
-            schedule: repeat.pattern,
-            repeatEvery: repeat.every,
-            priority: template.opts?.priority,
-            timezone: repeat.tz,
-            immediately: repeat.immediately,
-            maxLimit: repeat.limit,
-            uniqueKey: dedup?.id,
-            dedup: dedup
-                ? compact({ ttl: dedup.ttl, extend: dedup.extend, replace: dedup.replace })
-                : undefined,
-            skipMissedOnRestart: repeat.skipMissedOnRestart,
-            skipIfNoWorker: repeat.skipIfNoWorker,
-            preventOverlap: repeat.preventOverlap,
-            jobOptions: template.opts ? wireJobOptions(template.opts) : undefined,
-        }));
-    },
-    async removeJobScheduler(schedulerId) {
-        await this.call({ cmd: 'CronDelete', name: schedulerId });
-    },
-    async getJobScheduler(schedulerId) {
-        try {
-            const response = await this.call({ cmd: 'CronGet', name: schedulerId });
-            return (response.cron ?? response.data ?? null);
-        }
-        catch (err) {
-            // Only 'Cron job not found' maps to null; connection loss, timeouts and
-            // real server errors must surface, not masquerade as a missing scheduler.
-            if (err instanceof CommandError && /not found/i.test(err.message))
-                return null;
-            throw err;
-        }
-    },
-    async getJobSchedulers() {
-        const response = await this.call({ cmd: 'CronList' });
-        const crons = (response.crons ?? []);
-        return crons.filter((cron) => cron.queue === this.name);
-    },
-    async getJobSchedulersCount() {
-        return (await this.getJobSchedulers()).length;
-    },
-    /** Helper: run `name` on a cron `schedule`. */
-    addCron(name, schedule, data, opts) {
-        return this.upsertJobScheduler(name, { pattern: schedule }, { name, data, opts });
-    },
-    /** Helper: run `name` every `intervalMs` milliseconds. */
-    every(name, intervalMs, data, opts) {
-        return this.upsertJobScheduler(name, { every: intervalMs }, { name, data, opts });
-    },
-    // --------------------------------------------------------------- monitoring
-    async getWorkers() {
-        const response = await this.call({ cmd: 'ListWorkers' });
-        const data = (response.data ?? {});
-        return (data.workers ?? response.workers ?? []);
-    },
-    async getWorkersCount() {
-        return (await this.getWorkers()).length;
-    },
-    async getStats() {
-        const response = await this.call({ cmd: 'Stats' });
-        return (response.stats ?? {});
-    },
-    async getMetrics() {
-        const response = await this.call({ cmd: 'Metrics' });
-        return (response.metrics ?? {});
-    },
-    /** Server returns queue NAMES (strings). */
-    async listQueues() {
-        const response = await this.call({ cmd: 'ListQueues' });
-        const queues = (response.queues ?? []);
-        return queues.map((q) => (typeof q === 'string' ? q : String(q.name)));
-    },
-    // ----------------------------------------------------------------- webhooks
-    async addWebhook(opts) {
-        const response = await this.call(compact({
-            cmd: 'AddWebhook',
-            url: opts.url,
-            events: opts.events,
-            queue: opts.queue ?? this.name,
-            secret: opts.secret,
-        }));
-        const data = (response.data ?? {});
-        return (data.webhook ?? data);
-    },
-    async removeWebhook(webhookId) {
-        await this.call({ cmd: 'RemoveWebhook', webhookId });
-    },
-    async listWebhooks() {
-        const response = await this.call({ cmd: 'ListWebhooks' });
-        const data = (response.data ?? {});
-        return (data.webhooks ?? response.webhooks ?? []);
-    },
-    async setWebhookEnabled(webhookId, enabled) {
-        // wire field is `id` (SetWebhookEnabledCommand), unlike RemoveWebhook's `webhookId`
-        await this.call({ cmd: 'SetWebhookEnabled', id: webhookId, enabled });
-    },
-};