bunqueue-client 0.1.1 → 0.1.3

package/dist/bunqueue/bunqueue.js

@@ -0,0 +1,182 @@
+/**
+ * Bunqueue — simplified all-in-one Queue + Worker (Simple Mode).
+ * 1:1 port of src/client/bunqueue.ts from the official client, TCP mode only
+ * (the embedded mode requires the in-process Bun runtime). The delegation
+ * API (cron, DLQ, events, control, …) lives in bunqueue-api.ts and is merged
+ * onto the prototype below.
+ */
+import { Queue } from '../queue.js';
+import { Worker } from '../worker.js';
+import { PriorityAger } from './aging.js';
+import { BatchAccumulator } from './batch.js';
+import { bunqueueApi } from './bunqueue-api.js';
+import { CancellationManager } from './cancellation.js';
+import { WorkerCircuitBreaker } from './circuit-breaker.js';
+import { DedupDebounceMerger } from './dedup-debounce.js';
+import { DlqRateLimitManager } from './dlq-rate-limit.js';
+import { RateGate } from './rate-gate.js';
+import { executeWithRetry } from './retry.js';
+import { TriggerManager } from './triggers.js';
+import { TtlChecker } from './ttl.js';
+// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: prototype-mixin composition — Object.assign below installs exactly the methods BunqueueApi declares
+export class Bunqueue {
+    name;
+    queue;
+    worker;
+    /** @internal */ cancellation = new CancellationManager();
+    /** @internal */ cb;
+    /** @internal */ triggerMgr;
+    /** @internal */ ager;
+    /** @internal */ ttlChecker;
+    /** @internal */ batchAcc;
+    /** @internal */ dlqrl;
+    middlewares = [];
+    baseProcessor;
+    retryConfig;
+    merger;
+    rateGate;
+    defaultJobOptions;
+    constructor(name, opts) {
+        if (opts.embedded || opts.dataPath) {
+            throw new Error('Bunqueue (bunqueue-client) is TCP-only: embedded mode requires the Bun runtime — use the official "bunqueue" package on Bun instead');
+        }
+        const modes = [opts.processor, opts.routes, opts.batch].filter(Boolean).length;
+        if (modes === 0)
+            throw new Error('Bunqueue requires "processor", "routes", or "batch"');
+        if (modes > 1)
+            throw new Error('Bunqueue: use only one of "processor", "routes", or "batch"');
+        this.name = (opts.prefixKey ?? '') + name;
+        this.retryConfig = opts.retry ?? null;
+        this.ttlChecker = opts.ttl ? new TtlChecker(opts.ttl) : null;
+        this.merger = new DedupDebounceMerger(opts.deduplication ?? null, opts.debounce ?? null);
+        const limiter = opts.rateLimit ?? opts.limiter;
+        this.rateGate = limiter ? new RateGate(limiter) : null;
+        this.defaultJobOptions = this.buildDefaultJobOptions(opts);
+        // Build base processor
+        if (opts.batch) {
+            this.batchAcc = new BatchAccumulator(opts.batch);
+            this.baseProcessor = this.batchAcc.buildProcessor();
+        }
+        else {
+            this.batchAcc = null;
+            this.baseProcessor = opts.routes
+                ? this.buildRouteProcessor(opts.routes)
+                : opts.processor;
+        }
+        const wrappedProcessor = (job) => this.processJob(job);
+        const conn = opts.connection ?? {};
+        this.queue = new Queue(this.name, conn);
+        this.worker = new Worker(this.name, wrappedProcessor, {
+            ...conn,
+            concurrency: opts.concurrency,
+            autorun: opts.autorun,
+            heartbeatIntervalS: opts.heartbeatInterval !== undefined ? opts.heartbeatInterval / 1000 : undefined,
+            batchSize: opts.batchSize,
+            pollTimeoutMs: opts.pollTimeout,
+        });
+        // DLQ & rate limit manager
+        this.dlqrl = new DlqRateLimitManager(this.queue);
+        if (opts.dlq)
+            void this.dlqrl.setDlqConfig(opts.dlq);
+        // Subsystems
+        this.cb = opts.circuitBreaker
+            ? new WorkerCircuitBreaker(opts.circuitBreaker, this.worker)
+            : null;
+        this.triggerMgr = new TriggerManager(this.queue, this.worker);
+        this.ager = opts.priorityAging ? new PriorityAger(opts.priorityAging, this.queue) : null;
+        this.ager?.start();
+    }
+    buildRouteProcessor(routes) {
+        const routeMap = routes;
+        return (job) => {
+            const handler = routeMap[job.name ?? ''];
+            if (!handler)
+                throw new Error(`No route for job "${job.name}" in queue "${this.name}"`);
+            return handler(job);
+        };
+    }
+    buildDefaultJobOptions(opts) {
+        const base = { ...opts.defaultJobOptions };
+        if (opts.removeOnComplete !== undefined)
+            base.removeOnComplete ??= opts.removeOnComplete;
+        if (opts.removeOnFail !== undefined)
+            base.removeOnFail ??= opts.removeOnFail;
+        return Object.keys(base).length > 0 ? base : undefined;
+    }
+    // ------------------------------------------------- core processing pipeline
+    async processJob(job) {
+        if (this.rateGate)
+            await this.rateGate.acquire(this.rateGate.groupFor(job.data));
+        // Circuit breaker check
+        if (this.cb?.isOpen()) {
+            throw new Error('Circuit breaker is open');
+        }
+        // TTL check
+        if (this.ttlChecker?.isExpired(job.name ?? '', job.timestamp)) {
+            throw new Error(`Job expired (age: ${Date.now() - job.timestamp}ms)`);
+        }
+        // Register cancellation
+        const ac = this.cancellation.register(job.id);
+        const runChain = () => this.runMiddlewareChain(job, ac);
+        const execute = this.retryConfig ? executeWithRetry(runChain, this.retryConfig) : runChain();
+        return execute.then((result) => {
+            this.cb?.onSuccess();
+            this.cancellation.unregister(job.id);
+            return result;
+        }, (err) => {
+            this.cb?.onFailure();
+            this.cancellation.unregister(job.id);
+            throw err;
+        });
+    }
+    runMiddlewareChain(job, ac) {
+        if (this.middlewares.length === 0) {
+            const result = this.baseProcessor(job);
+            return result instanceof Promise ? result : Promise.resolve(result);
+        }
+        let index = 0;
+        const mws = this.middlewares;
+        const base = this.baseProcessor;
+        const next = () => {
+            if (ac.signal.aborted)
+                return Promise.reject(new Error('Job cancelled'));
+            if (index < mws.length)
+                return mws[index++](job, next);
+            const result = base(job);
+            return result instanceof Promise ? result : Promise.resolve(result);
+        };
+        return next();
+    }
+    // --------------------------------------------------------------- middleware
+    use(middleware) {
+        this.middlewares.push(middleware);
+        return this;
+    }
+    // --------------------------------------------------------- queue operations
+    add(name, data, opts) {
+        const merged = { ...this.defaultJobOptions, ...opts };
+        return this.queue.add(name, data, this.merger.merge(name, merged, data));
+    }
+    addBulk(jobs) {
+        return this.queue.addBulk(jobs.map((j) => ({
+            ...j,
+            opts: this.merger.merge(j.name, { ...this.defaultJobOptions, ...j.opts }, j.data),
+        })));
+    }
+    getJob(id) {
+        return this.queue.getJob(id);
+    }
+    getJobCounts() {
+        return this.queue.getJobCounts();
+    }
+    getJobCountsAsync() {
+        return this.queue.getJobCounts();
+    }
+    count() {
+        return this.queue.count();
+    }
+    countAsync() {
+        return this.queue.count();
+    }
+}
+Object.assign(Bunqueue.prototype, bunqueueApi);

package/dist/bunqueue/cancellation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Bunqueue Simple Mode — graceful job cancellation.
+ * 1:1 port of src/client/bunqueue/cancellation.ts: AbortController-based
+ * cancellation with optional grace period.
+ */
+export declare class CancellationManager {
+    private readonly controllers;
+    /** Register a new AbortController for a job. */
+    register(jobId: string): AbortController;
+    /** Remove a job's controller (on completion). */
+    unregister(jobId: string): void;
+    /** Cancel a job with optional grace period. */
+    cancel(jobId: string, gracePeriodMs?: number): void;
+    /** Check if a job is cancelled. */
+    isCancelled(jobId: string): boolean;
+    /** Get the AbortSignal for a job. */
+    getSignal(jobId: string): AbortSignal | null;
+    /** Cancel all and clear. */
+    destroyAll(): void;
+}

package/dist/bunqueue/cancellation.js

@@ -0,0 +1,48 @@
+/**
+ * Bunqueue Simple Mode — graceful job cancellation.
+ * 1:1 port of src/client/bunqueue/cancellation.ts: AbortController-based
+ * cancellation with optional grace period.
+ */
+export class CancellationManager {
+    controllers = new Map();
+    /** Register a new AbortController for a job. */
+    register(jobId) {
+        const ac = new AbortController();
+        this.controllers.set(jobId, ac);
+        return ac;
+    }
+    /** Remove a job's controller (on completion). */
+    unregister(jobId) {
+        this.controllers.delete(jobId);
+    }
+    /** Cancel a job with optional grace period. */
+    cancel(jobId, gracePeriodMs = 0) {
+        const ac = this.controllers.get(jobId);
+        if (!ac)
+            return;
+        if (gracePeriodMs > 0) {
+            setTimeout(() => {
+                ac.abort();
+            }, gracePeriodMs);
+        }
+        else {
+            ac.abort();
+        }
+    }
+    /** Check if a job is cancelled. */
+    isCancelled(jobId) {
+        const ac = this.controllers.get(jobId);
+        return ac ? ac.signal.aborted : false;
+    }
+    /** Get the AbortSignal for a job. */
+    getSignal(jobId) {
+        return this.controllers.get(jobId)?.signal ?? null;
+    }
+    /** Cancel all and clear. */
+    destroyAll() {
+        for (const ac of this.controllers.values()) {
+            ac.abort();
+        }
+        this.controllers.clear();
+    }
+}

package/dist/bunqueue/circuit-breaker.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Bunqueue Simple Mode — circuit breaker for worker protection.
+ * 1:1 port of src/client/bunqueue/circuitBreaker.ts.
+ */
+import type { WorkerBase } from '../worker-base.js';
+import type { CircuitBreakerConfig, CircuitState } from './types.js';
+export declare class WorkerCircuitBreaker {
+    private state;
+    private failures;
+    private timer;
+    private readonly config;
+    private readonly worker;
+    constructor(config: CircuitBreakerConfig, worker: WorkerBase);
+    get currentState(): CircuitState;
+    isOpen(): boolean;
+    onSuccess(): void;
+    onFailure(): void;
+    private open;
+    reset(): void;
+    destroy(): void;
+}

package/dist/bunqueue/circuit-breaker.js

@@ -0,0 +1,69 @@
+/**
+ * Bunqueue Simple Mode — circuit breaker for worker protection.
+ * 1:1 port of src/client/bunqueue/circuitBreaker.ts.
+ */
+export class WorkerCircuitBreaker {
+    state = 'closed';
+    failures = 0;
+    timer = null;
+    config;
+    worker;
+    constructor(config, worker) {
+        this.config = config;
+        this.worker = worker;
+    }
+    get currentState() {
+        return this.state;
+    }
+    isOpen() {
+        return this.state === 'open';
+    }
+    onSuccess() {
+        if (this.state === 'half-open') {
+            this.state = 'closed';
+            this.failures = 0;
+            this.config.onClose?.();
+        }
+        else if (this.state === 'closed') {
+            this.failures = 0;
+        }
+    }
+    onFailure() {
+        this.failures++;
+        const threshold = this.config.threshold ?? 5;
+        if (this.state === 'half-open' || this.failures >= threshold) {
+            this.open();
+        }
+    }
+    open() {
+        this.state = 'open';
+        this.config.onOpen?.(this.failures);
+        this.worker.pause();
+        const resetTimeout = this.config.resetTimeout ?? 30000;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.state = 'half-open';
+            this.config.onHalfOpen?.();
+            this.worker.resume();
+        }, resetTimeout);
+        this.timer.unref?.();
+    }
+    reset() {
+        this.state = 'closed';
+        this.failures = 0;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.worker.isPaused()) {
+            this.worker.resume();
+        }
+    }
+    destroy() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+}

package/dist/bunqueue/dedup-debounce.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Bunqueue Simple Mode — deduplication and debounce defaults merger.
+ * 1:1 port of src/client/bunqueue/dedupDebounce.ts, including the dedup id
+ * derivation algorithm: `${name}:${JSON.stringify(data)}`.
+ */
+import type { JobOptions } from '../types.js';
+import type { BunqueueDebounceConfig, BunqueueDeduplicationConfig } from './types.js';
+export declare class DedupDebounceMerger {
+    private readonly dedup;
+    private readonly debounce;
+    constructor(dedup: BunqueueDeduplicationConfig | null, debounce: BunqueueDebounceConfig | null);
+    get active(): boolean;
+    merge(name: string, opts?: JobOptions, data?: unknown): JobOptions | undefined;
+}

package/dist/bunqueue/dedup-debounce.js

@@ -0,0 +1,37 @@
+/**
+ * Bunqueue Simple Mode — deduplication and debounce defaults merger.
+ * 1:1 port of src/client/bunqueue/dedupDebounce.ts, including the dedup id
+ * derivation algorithm: `${name}:${JSON.stringify(data)}`.
+ */
+export class DedupDebounceMerger {
+    dedup;
+    debounce;
+    constructor(dedup, debounce) {
+        this.dedup = dedup;
+        this.debounce = debounce;
+    }
+    get active() {
+        return this.dedup !== null || this.debounce !== null;
+    }
+    merge(name, opts, data) {
+        if (!this.active)
+            return opts;
+        const merged = { ...opts };
+        if (this.dedup && !merged.deduplication) {
+            const dataKey = data !== undefined ? JSON.stringify(data) : '';
+            merged.deduplication = {
+                id: `${name}:${dataKey}`,
+                ttl: this.dedup.ttl ?? 3600000,
+                extend: this.dedup.extend,
+                replace: this.dedup.replace,
+            };
+        }
+        if (this.debounce && !merged.debounce) {
+            merged.debounce = {
+                id: name,
+                ttl: this.debounce.ttl,
+            };
+        }
+        return merged;
+    }
+}

package/dist/bunqueue/dlq-rate-limit.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Bunqueue Simple Mode — DLQ and rate limit helpers.
+ * Port of src/client/bunqueue/dlqRateLimit.ts. Delegates to the TCP Queue;
+ * the DLQ filter and stats are computed client-side from the fetched entries
+ * (the embedded original reads them in-process).
+ */
+import type { Queue } from '../queue.js';
+import type { BunqueueDlqConfig } from './types.js';
+type Raw = Record<string, unknown>;
+/** Filter for DLQ queries (mirrors the official DlqFilter). */
+export interface DlqFilter {
+    reason?: string;
+    jobName?: string;
+    since?: number;
+}
+/** Aggregate DLQ statistics (mirrors the official DlqStats). */
+export interface DlqStats {
+    total: number;
+    byReason: Record<string, number>;
+}
+export declare class DlqRateLimitManager<T = unknown> {
+    private readonly queue;
+    constructor(queue: Queue<T>);
+    setDlqConfig(config: BunqueueDlqConfig): Promise<void>;
+    getDlqConfig(): Promise<Raw>;
+    getDlq(filter?: DlqFilter): Promise<Raw[]>;
+    getDlqStats(): Promise<DlqStats>;
+    retryDlq(id?: string): Promise<number>;
+    purgeDlq(): Promise<number>;
+    setGlobalRateLimit(max: number, duration?: number): Promise<void>;
+    removeGlobalRateLimit(): Promise<void>;
+}
+export {};

package/dist/bunqueue/dlq-rate-limit.js

@@ -0,0 +1,65 @@
+/**
+ * Bunqueue Simple Mode — DLQ and rate limit helpers.
+ * Port of src/client/bunqueue/dlqRateLimit.ts. Delegates to the TCP Queue;
+ * the DLQ filter and stats are computed client-side from the fetched entries
+ * (the embedded original reads them in-process).
+ */
+function entryReason(entry) {
+    return String(entry.reason ?? entry.entry?.reason ?? 'unknown');
+}
+function entryName(entry) {
+    const data = (entry.data ?? entry.entry?.data);
+    return data?.name === undefined ? undefined : String(data.name);
+}
+export class DlqRateLimitManager {
+    queue;
+    constructor(queue) {
+        this.queue = queue;
+    }
+    // ------------------------------------------------------------------- dlq
+    async setDlqConfig(config) {
+        await this.queue.setDlqConfig(config);
+    }
+    getDlqConfig() {
+        return this.queue.getDlqConfig();
+    }
+    async getDlq(filter) {
+        const entries = await this.queue.getDlq();
+        if (!filter)
+            return entries;
+        return entries.filter((entry) => {
+            if (filter.reason && entryReason(entry) !== filter.reason)
+                return false;
+            if (filter.jobName && entryName(entry) !== filter.jobName)
+                return false;
+            if (filter.since !== undefined) {
+                const at = Number(entry.enteredAt ?? entry.failedAt ?? 0);
+                if (at < filter.since)
+                    return false;
+            }
+            return true;
+        });
+    }
+    async getDlqStats() {
+        const entries = await this.queue.getDlq();
+        const byReason = {};
+        for (const entry of entries) {
+            const reason = entryReason(entry);
+            byReason[reason] = (byReason[reason] ?? 0) + 1;
+        }
+        return { total: entries.length, byReason };
+    }
+    retryDlq(id) {
+        return this.queue.retryDlq(id);
+    }
+    purgeDlq() {
+        return this.queue.purgeDlq();
+    }
+    // ----------------------------------------------------------- rate limiting
+    async setGlobalRateLimit(max, duration) {
+        await this.queue.setGlobalRateLimit(max, duration);
+    }
+    async removeGlobalRateLimit() {
+        await this.queue.removeGlobalRateLimit();
+    }
+}

package/dist/bunqueue/rate-gate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Bunqueue Simple Mode — client-side rate limiter for the worker.
+ *
+ * The official client passes `rateLimit`/`limiter` to the embedded Worker,
+ * which throttles job starts to `max` per `duration` window, optionally per
+ * group (`groupKey` names a field of job.data). This SDK reproduces the same
+ * semantics as a gate awaited before each job runs: a job whose window is
+ * full waits (holding its concurrency slot) until the window frees.
+ */
+import type { RateLimiterOptions } from './types.js';
+export declare class RateGate {
+    private readonly max;
+    private readonly duration;
+    private readonly groupKey;
+    private readonly windows;
+    constructor(options: RateLimiterOptions);
+    /** Resolve the rate-limit group for a job's data. */
+    groupFor(data: unknown): string;
+    /** Wait until the group's window has room, then record the start. */
+    acquire(group: string): Promise<void>;
+}

package/dist/bunqueue/rate-gate.js

@@ -0,0 +1,48 @@
+/**
+ * Bunqueue Simple Mode — client-side rate limiter for the worker.
+ *
+ * The official client passes `rateLimit`/`limiter` to the embedded Worker,
+ * which throttles job starts to `max` per `duration` window, optionally per
+ * group (`groupKey` names a field of job.data). This SDK reproduces the same
+ * semantics as a gate awaited before each job runs: a job whose window is
+ * full waits (holding its concurrency slot) until the window frees.
+ */
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class RateGate {
+    max;
+    duration;
+    groupKey;
+    windows = new Map();
+    constructor(options) {
+        this.max = options.max;
+        this.duration = options.duration;
+        this.groupKey = options.groupKey;
+    }
+    /** Resolve the rate-limit group for a job's data. */
+    groupFor(data) {
+        if (!this.groupKey)
+            return '';
+        if (typeof data === 'object' && data !== null) {
+            const value = data[this.groupKey];
+            if (value !== undefined && value !== null)
+                return String(value);
+        }
+        return '';
+    }
+    /** Wait until the group's window has room, then record the start. */
+    async acquire(group) {
+        for (;;) {
+            const now = Date.now();
+            const window = this.windows.get(group) ?? [];
+            const fresh = window.filter((t) => now - t < this.duration);
+            if (fresh.length < this.max) {
+                fresh.push(now);
+                this.windows.set(group, fresh);
+                return;
+            }
+            this.windows.set(group, fresh);
+            const oldest = fresh[0];
+            await sleep(Math.max(oldest + this.duration - now, 10));
+        }
+    }
+}

package/dist/bunqueue/retry.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Bunqueue Simple Mode — advanced in-process retry with backoff strategies.
+ * 1:1 port of src/client/bunqueue/retry.ts (identical formulas).
+ */
+import type { RetryConfig, RetryStrategy } from './types.js';
+/** Calculate backoff delay based on strategy. */
+export declare function calculateBackoff(strategy: RetryStrategy, attempt: number, baseDelay: number, error: Error, config: RetryConfig): number;
+/** Execute a function with retry logic (the job stays active throughout). */
+export declare function executeWithRetry<R>(fn: () => Promise<R>, config: RetryConfig): Promise<R>;

package/dist/bunqueue/retry.js

@@ -0,0 +1,56 @@
+/**
+ * Bunqueue Simple Mode — advanced in-process retry with backoff strategies.
+ * 1:1 port of src/client/bunqueue/retry.ts (identical formulas).
+ */
+/** Calculate backoff delay based on strategy. */
+export function calculateBackoff(strategy, attempt, baseDelay, error, config) {
+    switch (strategy) {
+        case 'fixed':
+            return baseDelay;
+        case 'exponential':
+            return baseDelay * 2 ** (attempt - 1);
+        case 'jitter': {
+            const exp = baseDelay * 2 ** (attempt - 1);
+            return Math.floor(exp * (0.5 + Math.random()));
+        }
+        case 'fibonacci': {
+            let a = 1;
+            let b = 1;
+            for (let i = 0; i < attempt - 1; i++) {
+                const next = a + b;
+                a = b;
+                b = next;
+            }
+            return baseDelay * b;
+        }
+        case 'custom':
+            if (config.customBackoff) {
+                return config.customBackoff(attempt, error);
+            }
+            return baseDelay;
+        default:
+            return baseDelay;
+    }
+}
+/** Execute a function with retry logic (the job stays active throughout). */
+export function executeWithRetry(fn, config) {
+    const maxAttempts = config.maxAttempts ?? 3;
+    const baseDelay = config.delay ?? 1000;
+    const strategy = config.strategy ?? 'exponential';
+    const attempt = (n) => {
+        return fn().catch((err) => {
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (n >= maxAttempts)
+                throw error;
+            if (config.retryIf && !config.retryIf(error, n))
+                throw error;
+            const delay = calculateBackoff(strategy, n, baseDelay, error, config);
+            return new Promise((resolve) => {
+                setTimeout(() => {
+                    resolve(attempt(n + 1));
+                }, delay);
+            });
+        });
+    };
+    return attempt(1);
+}

package/dist/bunqueue/triggers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Bunqueue Simple Mode — event triggers.
+ * 1:1 port of src/client/bunqueue/triggers.ts: when a job completes/fails,
+ * automatically create another job.
+ */
+import type { Queue } from '../queue.js';
+import type { Worker } from '../worker.js';
+import type { TriggerRule } from './types.js';
+export declare class TriggerManager<T = unknown, R = unknown> {
+    private readonly rules;
+    private active;
+    private readonly queue;
+    private readonly worker;
+    constructor(queue: Queue<T>, worker: Worker<T, R>);
+    add(rule: TriggerRule<T>): void;
+    private ensureActive;
+    private fire;
+}