bunqueue-client 0.1.9 → 0.2.0

package/dist/bunqueue/batch.js

@@ -1,60 +0,0 @@
-/**
- * Bunqueue Simple Mode — batch processing.
- * 1:1 port of src/client/bunqueue/batch.ts: accumulates jobs and processes
- * them in groups; flushes on size, on timeout, and on destroy (close).
- */
-export class BatchAccumulator {
-    buffer = [];
-    timer = null;
-    config;
-    constructor(config) {
-        this.config = config;
-    }
-    /** Build a Processor that buffers jobs into batches. */
-    buildProcessor() {
-        return (job) => {
-            return new Promise((resolve, reject) => {
-                this.buffer.push({ job, resolve, reject });
-                if (this.buffer.length >= this.config.size) {
-                    this.flush();
-                }
-                else if (!this.timer) {
-                    const timeout = this.config.timeout ?? 5000;
-                    this.timer = setTimeout(() => {
-                        this.flush();
-                    }, timeout);
-                }
-            });
-        };
-    }
-    flush() {
-        if (this.timer) {
-            clearTimeout(this.timer);
-            this.timer = null;
-        }
-        const batch = this.buffer.splice(0);
-        if (batch.length === 0)
-            return;
-        const jobs = batch.map((b) => b.job);
-        this.config.processor(jobs).then((results) => {
-            for (let i = 0; i < batch.length; i++) {
-                batch[i].resolve(results[i] ?? undefined);
-            }
-        }, (err) => {
-            const error = err instanceof Error ? err : new Error(String(err));
-            for (const b of batch) {
-                b.reject(error);
-            }
-        });
-    }
-    destroy() {
-        if (this.timer) {
-            clearTimeout(this.timer);
-            this.timer = null;
-        }
-        // Flush remaining
-        if (this.buffer.length > 0) {
-            this.flush();
-        }
-    }
-}

package/dist/bunqueue/bunqueue-api.js

@@ -1,116 +0,0 @@
-/**
- * Bunqueue Simple Mode — delegation API surface (cron, cancellation, circuit
- * breaker, TTL, DLQ, rate limit, events, control). Merged onto the Bunqueue
- * prototype by bunqueue.ts; split out to keep files small.
- */
-export const bunqueueApi = {
-    // --------------------------------------------------------------------- cron
-    async cron(id, pattern, data, opts) {
-        await this.queue.upsertJobScheduler(id, { pattern, tz: opts?.timezone, limit: opts?.limit }, { name: id, data, opts: opts?.jobOpts });
-        return this.queue.getJobScheduler(id);
-    },
-    async every(id, intervalMs, data, opts) {
-        await this.queue.upsertJobScheduler(id, { every: intervalMs, limit: opts?.limit }, { name: id, data, opts: opts?.jobOpts });
-        return this.queue.getJobScheduler(id);
-    },
-    removeCron(id) {
-        return this.queue.removeJobScheduler(id);
-    },
-    listCrons() {
-        return this.queue.getJobSchedulers();
-    },
-    // ------------------------------------------------------------- cancellation
-    cancel(jobId, gracePeriodMs = 0) {
-        this.cancellation.cancel(jobId, gracePeriodMs);
-    },
-    isCancelled(jobId) {
-        return this.cancellation.isCancelled(jobId);
-    },
-    getSignal(jobId) {
-        return this.cancellation.getSignal(jobId);
-    },
-    // ---------------------------------------------------------- circuit breaker
-    getCircuitState() {
-        return this.cb?.currentState ?? 'closed';
-    },
-    resetCircuit() {
-        this.cb?.reset();
-    },
-    // ----------------------------------------------------------------- triggers
-    trigger(rule) {
-        this.triggerMgr.add(rule);
-        return this;
-    },
-    // ---------------------------------------------------------------------- ttl
-    setDefaultTtl(ttlMs) {
-        this.ttlChecker?.setDefaultTtl(ttlMs);
-    },
-    setNameTtl(name, ttlMs) {
-        this.ttlChecker?.setNameTtl(name, ttlMs);
-    },
-    // ---------------------------------------------------------------------- dlq
-    setDlqConfig(config) {
-        return this.dlqrl.setDlqConfig(config);
-    },
-    getDlqConfig() {
-        return this.dlqrl.getDlqConfig();
-    },
-    getDlq(filter) {
-        return this.dlqrl.getDlq(filter);
-    },
-    getDlqStats() {
-        return this.dlqrl.getDlqStats();
-    },
-    retryDlq(id) {
-        return this.dlqrl.retryDlq(id);
-    },
-    purgeDlq() {
-        return this.dlqrl.purgeDlq();
-    },
-    // ------------------------------------------------------------ rate limiting
-    setGlobalRateLimit(max, duration) {
-        return this.dlqrl.setGlobalRateLimit(max, duration);
-    },
-    removeGlobalRateLimit() {
-        return this.dlqrl.removeGlobalRateLimit();
-    },
-    // ------------------------------------------------------------------- events
-    on(event, listener) {
-        this.worker.on(event, listener);
-        return this;
-    },
-    once(event, listener) {
-        this.worker.once(event, listener);
-        return this;
-    },
-    off(event, listener) {
-        this.worker.off(event, listener);
-        return this;
-    },
-    // ------------------------------------------------------------------ control
-    pause() {
-        void this.queue.pause().catch(() => { });
-        this.worker.pause();
-    },
-    resume() {
-        void this.queue.resume().catch(() => { });
-        this.worker.resume();
-    },
-    async close(force = false) {
-        this.ager?.destroy();
-        this.cb?.destroy();
-        this.batchAcc?.destroy();
-        this.cancellation.destroyAll();
-        await this.worker.close(force);
-        this.queue.close();
-    },
-    isRunning() {
-        return this.worker.isRunning();
-    },
-    isPaused() {
-        return this.worker.isPaused();
-    },
-    isClosed() {
-        return this.worker.isClosed();
-    },
-};

package/dist/bunqueue/bunqueue.js

@@ -1,194 +0,0 @@
-/**
- * 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);
-        // Fire-and-forget config push: without the catch, an unreachable server at
-        // construction time becomes an unhandled rejection that kills the process.
-        // Route the failure to the worker's 'error' event (the channel every other
-        // background command failure uses); with no listener attached, swallow it
-        // like pause()/resume() do — an unlistened 'error' emit would itself throw.
-        if (opts.dlq) {
-            void this.dlqrl.setDlqConfig(opts.dlq).catch((err) => {
-                if (this.worker.listenerCount('error') > 0) {
-                    this.worker.emit('error', err instanceof Error ? err : new Error(String(err)));
-                }
-            });
-        }
-        // 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) {
-            this.rateGate.prune(); // evict fully-expired groups (high-cardinality groupKey)
-            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.js

@@ -1,48 +0,0 @@
-/**
- * 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.js

@@ -1,69 +0,0 @@
-/**
- * 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.js

@@ -1,37 +0,0 @@
-/**
- * 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.js

@@ -1,65 +0,0 @@
-/**
- * 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.js

@@ -1,61 +0,0 @@
-/**
- * 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));
-        }
-    }
-    /**
-     * Drop groups whose window is fully expired. Called on each acquire cycle
-     * boundary by the owner; without it a high-cardinality groupKey (e.g. one
-     * group per user id) grows the map forever.
-     */
-    prune() {
-        const now = Date.now();
-        for (const [group, window] of this.windows) {
-            if (window.length === 0 || now - window[window.length - 1] >= this.duration) {
-                this.windows.delete(group);
-            }
-        }
-    }
-}