bunqueue-client 0.1.2 → 0.1.3

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;
+}

package/dist/bunqueue/triggers.js

@@ -0,0 +1,42 @@
+/**
+ * Bunqueue Simple Mode — event triggers.
+ * 1:1 port of src/client/bunqueue/triggers.ts: when a job completes/fails,
+ * automatically create another job.
+ */
+export class TriggerManager {
+    rules = [];
+    active = false;
+    queue;
+    worker;
+    constructor(queue, worker) {
+        this.queue = queue;
+        this.worker = worker;
+    }
+    add(rule) {
+        this.rules.push(rule);
+        this.ensureActive();
+    }
+    ensureActive() {
+        if (this.active)
+            return;
+        this.active = true;
+        this.worker.on('completed', (job, result) => {
+            this.fire('completed', job, result);
+        });
+        this.worker.on('failed', (job, error) => {
+            this.fire('failed', job, error);
+        });
+    }
+    fire(event, job, resultOrError) {
+        for (const rule of this.rules) {
+            if (rule.on !== job.name)
+                continue;
+            if ((rule.event ?? 'completed') !== event)
+                continue;
+            if (rule.condition && !rule.condition(resultOrError, job))
+                continue;
+            const data = rule.data(resultOrError, job);
+            void this.queue.add(rule.create, data, rule.opts);
+        }
+    }
+}

package/dist/bunqueue/ttl.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Bunqueue Simple Mode — job TTL (time to live).
+ * 1:1 port of src/client/bunqueue/ttl.ts: expire unprocessed jobs, checked
+ * when the worker picks the job up. Resolution: perName -> defaultTtl -> 0.
+ */
+import type { JobTtlConfig } from './types.js';
+export declare class TtlChecker {
+    private readonly config;
+    constructor(config: JobTtlConfig);
+    /** Get TTL for a specific job name. */
+    getTtl(jobName: string): number;
+    /** Check if a job has expired. */
+    isExpired(jobName: string, jobTimestamp: number): boolean;
+    /** Set default TTL. */
+    setDefaultTtl(ttlMs: number): void;
+    /** Set TTL for a specific job name. */
+    setNameTtl(jobName: string, ttlMs: number): void;
+}

package/dist/bunqueue/ttl.js

@@ -0,0 +1,31 @@
+/**
+ * Bunqueue Simple Mode — job TTL (time to live).
+ * 1:1 port of src/client/bunqueue/ttl.ts: expire unprocessed jobs, checked
+ * when the worker picks the job up. Resolution: perName -> defaultTtl -> 0.
+ */
+export class TtlChecker {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Get TTL for a specific job name. */
+    getTtl(jobName) {
+        return this.config.perName?.[jobName] ?? this.config.defaultTtl ?? 0;
+    }
+    /** Check if a job has expired. */
+    isExpired(jobName, jobTimestamp) {
+        const ttl = this.getTtl(jobName);
+        if (ttl <= 0)
+            return false;
+        return Date.now() - jobTimestamp > ttl;
+    }
+    /** Set default TTL. */
+    setDefaultTtl(ttlMs) {
+        this.config.defaultTtl = ttlMs;
+    }
+    /** Set TTL for a specific job name. */
+    setNameTtl(jobName, ttlMs) {
+        this.config.perName ??= {};
+        this.config.perName[jobName] = ttlMs;
+    }
+}