@boringnode/queue 0.5.1 → 0.6.0

package/build/{job-DImdhRFO.d.ts → job-C4oyCVxR.d.ts}

@@ -206,7 +206,13 @@ type Duration = number | string;
  * - `{ age?, count? }`: Keep with pruning by age and/or count
  */
 type JobRetention = boolean | {
+    /**
+     * Keep jobs newer than this duration.
+     */
     age?: Duration;
+    /**
+     * Keep at most this many jobs.
+     */
     count?: number;
 };
 /**
@@ -222,9 +228,19 @@ type JobStatus = 'pending' | 'active' | 'delayed' | 'completed' | 'failed';
  * console.log(`Dispatched job: ${jobId}`)
  * ```
  */
+/**
+ * Outcome of a dedup-enabled dispatch.
+ * - `added`: new job was inserted
+ * - `skipped`: duplicate found within TTL, skipped silently
+ * - `replaced`: duplicate found within TTL, existing job's payload was replaced
+ * - `extended`: duplicate found within TTL, TTL window was reset
+ */
+type DedupOutcome = 'added' | 'skipped' | 'replaced' | 'extended';
 interface DispatchResult {
     /** Unique identifier for this specific job instance */
     jobId: string;
+    /** Dedup outcome (only present when `.dedup()` was used). */
+    deduped?: DedupOutcome;
 }
 /**
  * Result returned when dispatching multiple jobs at once.
@@ -265,7 +281,7 @@ interface JobData {
     /**
      * Job priority (lower = higher priority).
      *
-     * @default 0
+     * @default 5
      */
     priority?: number;
     /**
@@ -291,11 +307,50 @@ interface JobData {
      * ```
      */
     groupId?: string;
+    /**
+     * Timestamp (ms) when the job was dispatched.
+     * Used to compute queue wait time in OTel instrumentation.
+     */
+    createdAt?: number;
     /**
      * Serialized trace context for distributed tracing.
      * Injected by OTel plugin at dispatch time.
      */
     traceContext?: Record<string, string>;
+    /**
+     * Deduplication configuration for this job.
+     * When set, adapters apply dedup semantics keyed on `dedup.id`.
+     * Set automatically when `.dedup()` is called on the dispatcher.
+     */
+    dedup?: {
+        /**
+         * Dedup key, prefixed with the job name (e.g. `SendInvoiceJob::order-123`).
+         * The combined `<jobName>::<id>` length is capped at 510 characters by the
+         * Knex storage column. Dispatcher validates this at `.dedup()` time.
+         */
+        id: string;
+        /**
+         * TTL in milliseconds (must be positive). When set, dedup lock auto-expires
+         * after TTL. After expiry, the same dedup id produces a brand-new job
+         * (coexists with prior). Omit `ttl` entirely for a no-expiry lock that
+         * persists until the job is removed.
+         */
+        ttl?: number;
+        /**
+         * Reset the TTL clock when a duplicate arrives within the window.
+         * The window length stays at the original ttl — passing a different
+         * `ttl` on the duplicating dispatch does not resize the window.
+         */
+        extend?: boolean;
+        /**
+         * Swap the payload of the existing pending or delayed job when a
+         * duplicate arrives within the TTL window. Active jobs and retained
+         * completed/failed jobs return `'skipped'` without mutation. Only
+         * `payload` is swapped — priority, queue, delay, and groupId of the
+         * existing job are preserved.
+         */
+        replace?: boolean;
+    };
 }
 /**
  * Record of a job's current state, including history for completed/failed jobs.
@@ -345,22 +400,28 @@ interface JobOptions {
     queue?: string;
     /**
      * Adapter name or factory to use for this job.
+     *
+     * Defaults to the queue manager's configured default adapter.
      */
     adapter?: string | (() => Adapter);
     /**
      * Maximum retry attempts before permanent failure.
      *
-     * @default 3
+     * This is a convenience alias for `retry.maxRetries`.
+     *
+     * @default 0
      */
     maxRetries?: number;
     /**
      * Job priority (lower = higher priority).
      *
-     * @default 0
+     * @default 5
      */
     priority?: number;
     /**
-     * Retry configuration (backoff strategy, delays, etc.).
+     * Retry configuration for this job.
+     *
+     * Overrides queue-level and global retry settings.
      */
     retry?: RetryConfig;
     /**
@@ -372,10 +433,22 @@ interface JobOptions {
     /**
      * Whether to mark job as failed on timeout.
      *
-     * @default true
+     * When disabled, timed out jobs follow the normal retry policy.
+     *
+     * @default false
      */
     failOnTimeout?: boolean;
+    /**
+     * Retention policy for completed jobs.
+     *
+     * By default, completed jobs are removed immediately.
+     */
     removeOnComplete?: JobRetention;
+    /**
+     * Retention policy for failed jobs.
+     *
+     * By default, failed jobs are removed immediately after the failure hooks run.
+     */
     removeOnFail?: JobRetention;
 }
 /**
@@ -443,23 +516,77 @@ type JobClass<T extends Job = Job> = (new (...args: unknown[]) => T) & {
  * ```
  */
 type JobFactory = (JobClass: JobClass) => Job | Promise<Job>;
+/**
+ * Retry policy used by jobs, queues, or the queue manager.
+ */
 interface RetryConfig {
+    /**
+     * Number of retry attempts after the first failed execution.
+     *
+     * Set to `0` to disable retries.
+     *
+     * @default 0
+     */
     maxRetries?: number;
+    /**
+     * Factory that creates the backoff strategy used between retry attempts.
+     *
+     * If omitted, failed jobs are retried as soon as the adapter makes them
+     * available again.
+     */
     backoff?: () => BackoffStrategy$1;
 }
+/**
+ * Built-in retry delay algorithms.
+ */
 type BackoffStrategy = 'exponential' | 'linear' | 'fixed';
+/**
+ * Configuration for built-in and custom retry backoff strategies.
+ */
 interface BackoffConfig {
+    /**
+     * Strategy used to compute the delay before the next retry.
+     */
     strategy: BackoffStrategy;
+    /**
+     * Initial delay used by the strategy.
+     */
     baseDelay: Duration;
+    /**
+     * Upper bound for computed retry delays.
+     */
     maxDelay?: Duration;
+    /**
+     * Growth factor for exponential backoff.
+     */
     multiplier?: number;
+    /**
+     * Whether to randomize retry delays to avoid retry bursts.
+     */
     jitter?: boolean;
 }
+/**
+ * Runtime configuration for a named queue.
+ */
 interface QueueConfig {
+    /**
+     * Adapter name used by jobs dispatched to this queue.
+     *
+     * Falls back to the queue manager's default adapter.
+     */
     adapter?: string;
+    /**
+     * Retry policy applied to jobs in this queue unless overridden by job options.
+     */
     retry?: RetryConfig;
+    /**
+     * Default job options applied to jobs in this queue unless overridden by the job.
+     */
     defaultJobOptions?: JobOptions;
 }
+/**
+ * Runtime options for workers that poll queues and execute jobs.
+ */
 interface WorkerConfig {
     /**
      * Maximum number of jobs to process concurrently.
@@ -508,22 +635,32 @@ interface WorkerConfig {
      */
     onShutdownSignal?: () => void | Promise<void>;
 }
+/**
+ * Event yielded by the low-level worker processing generator.
+ */
 type WorkerCycle = {
+    /** A job was acquired and execution started. */
     type: 'started';
     queue: string;
     job: JobData;
 } | {
+    /** A running job finished, either successfully or after failure handling. */
     type: 'completed';
     queue: string;
     job: JobData;
 } | {
+    /** No work was available. Consumers should wait before polling again. */
     type: 'idle';
     suggestedDelay: Duration;
 } | {
+    /** An unexpected worker loop error occurred. */
     type: 'error';
     error: Error;
     suggestedDelay: Duration;
 };
+/**
+ * Factory used to lazily create adapter instances.
+ */
 type AdapterFactory<T extends Adapter = Adapter> = () => T;
 /**
  * Status of a schedule.
@@ -602,13 +739,59 @@ interface ScheduleListOptions {
     status?: ScheduleStatus;
 }
 interface QueueManagerConfig {
+    /**
+     * Name of the adapter used when a job does not select one explicitly.
+     *
+     * Must match one of the keys from `adapters`.
+     */
     default: string;
+    /**
+     * Available queue adapters keyed by name.
+     *
+     * Adapters are lazy-instantiated the first time they are used.
+     */
     adapters: Record<string, AdapterFactory>;
+    /**
+     * Global retry configuration applied to all jobs unless overridden by
+     * queue-level or job-level options.
+     */
     retry?: RetryConfig;
+    /**
+     * Global job options applied to all jobs unless overridden by queue-level
+     * or job-level options.
+     */
     defaultJobOptions?: JobOptions;
+    /**
+     * Per-queue configuration keyed by queue name.
+     *
+     * Use this to select adapters or defaults for specific queues.
+     */
     queues?: Record<string, QueueConfig>;
+    /**
+     * Worker runtime options used by `Worker` instances.
+     */
     worker?: WorkerConfig;
+    /**
+     * Glob patterns used to discover and register job classes.
+     *
+     * These locations are used by `init()` when `autoLoadJobs` is enabled,
+     * and by `QueueManager.loadJobs()` when called without arguments.
+     */
     locations?: string[];
+    /**
+     * Whether `init()` should immediately register jobs from configured locations.
+     *
+     * Framework integrations may disable this to defer job loading until a
+     * command lifecycle is ready, then call `QueueManager.loadJobs()`.
+     *
+     * @default true
+     */
+    autoLoadJobs?: boolean;
+    /**
+     * Logger used by the queue runtime.
+     *
+     * Defaults to the console logger.
+     */
     logger?: Logger;
     /**
      * Custom factory function for job instantiation.
@@ -642,6 +825,16 @@ interface QueueManagerConfig {
     executionWrapper?: <T>(fn: () => Promise<T>, job: AcquiredJob, queue: string) => Promise<T>;
 }
 
+/**
+ * Result of a push operation when dedup was involved.
+ * `outcome` tells the dispatcher what happened; `jobId` is the ID of the
+ * existing job when deduped (skipped/replaced/extended).
+ */
+interface PushResult {
+    outcome: DedupOutcome;
+    /** ID of the existing job when a duplicate was detected, otherwise the newly added job's id. */
+    jobId: string;
+}
 /**
  * A job that has been acquired by a worker for processing.
  * Extends JobData with the timestamp when the job was acquired.
@@ -704,6 +897,23 @@ interface Adapter {
      * @returns Number of jobs that were recovered (not including permanently failed ones)
      */
     recoverStalledJobs(queue: string, stalledThreshold: number, maxStalledCount: number): Promise<number>;
+    /**
+     * Renew the acquired timestamp of in-flight jobs (heartbeat).
+     *
+     * A worker calls this periodically for the jobs it is actively processing
+     * so that long-running handlers are not mistaken for stalled jobs and
+     * re-delivered while they are still running. Only jobs that are still active
+     * AND still owned by the calling worker (the one set via setWorkerId) are
+     * renewed; jobs that have already been recovered/completed, or have since
+     * been re-acquired by another worker, are skipped. This prevents a slow
+     * worker from resurrecting a job or sabotaging the recovery of the worker
+     * that legitimately owns it now with a late heartbeat.
+     *
+     * @param queue - The queue the jobs belong to
+     * @param jobIds - The ids of the jobs currently being processed
+     * @returns Number of jobs whose timestamp was renewed
+     */
+    renewJobs(queue: string, jobIds: string[]): Promise<number>;
     /**
      * Mark a job as completed and remove it from the queue.
      *
@@ -741,30 +951,34 @@ interface Adapter {
      * Push a job to the default queue for immediate processing.
      *
      * @param jobData - The job data to push
+     * @returns PushResult if jobData.dedup is set, otherwise void
      */
-    push(jobData: JobData): Promise<void>;
+    push(jobData: JobData): Promise<PushResult | void>;
     /**
      * Push a job to a specific queue for immediate processing.
      *
      * @param queue - The queue name to push to
      * @param jobData - The job data to push
+     * @returns PushResult if jobData.dedup is set, otherwise void
      */
-    pushOn(queue: string, jobData: JobData): Promise<void>;
+    pushOn(queue: string, jobData: JobData): Promise<PushResult | void>;
     /**
      * Push a job to the default queue with a delay.
      *
      * @param jobData - The job data to push
      * @param delay - Delay in milliseconds before the job becomes available
+     * @returns PushResult if jobData.dedup is set, otherwise void
      */
-    pushLater(jobData: JobData, delay: number): Promise<void>;
+    pushLater(jobData: JobData, delay: number): Promise<PushResult | void>;
     /**
      * Push a job to a specific queue with a delay.
      *
      * @param queue - The queue name to push to
      * @param jobData - The job data to push
      * @param delay - Delay in milliseconds before the job becomes available
+     * @returns PushResult if jobData.dedup is set, otherwise void
      */
-    pushLaterOn(queue: string, jobData: JobData, delay: number): Promise<void>;
+    pushLaterOn(queue: string, jobData: JobData, delay: number): Promise<PushResult | void>;
     /**
      * Push multiple jobs to the default queue for immediate processing.
      *
@@ -871,11 +1085,12 @@ interface Adapter {
  *
  * ```
  * Job.dispatch(payload)
- *     .toQueue('emails')     // optional: target queue
- *     .priority(1)           // optional: 1-10, lower = higher priority
- *     .in('5m')              // optional: delay before processing
- *     .with('redis')         // optional: specific adapter
- *     .run()                 // dispatch the job
+ *     .toQueue('emails')              // optional: target queue
+ *     .priority(1)                    // optional: 1-10, lower = higher priority
+ *     .in('5m')                       // optional: delay before processing
+ *     .dedup({ id: 'order-123' })     // optional: deduplication
+ *     .with('redis')                  // optional: specific adapter
+ *     .run()                          // dispatch the job
  * ```
  *
  * @typeParam T - The payload type for this job
@@ -973,6 +1188,51 @@ declare class JobDispatcher<T> {
      * ```
      */
     group(groupId: string): this;
+    /**
+     * Configure deduplication for this job.
+     *
+     * Modes:
+     * - **Simple** (`{ id }`): skip duplicates while the job exists.
+     * - **Throttle** (`{ id, ttl }`): skip duplicates within a TTL window.
+     * - **Extend** (`{ id, ttl, extend: true }`): reset the TTL clock on each duplicate.
+     *   The window length stays at the original ttl from the first dispatch.
+     * - **Replace** (`{ id, ttl, replace: true }`): swap the payload of the existing
+     *   pending/delayed job on duplicate within TTL. Active jobs and retained
+     *   completed/failed jobs return `'skipped'`. Only `payload` changes —
+     *   priority/queue/delay/groupId are preserved.
+     * - **Debounce** (`{ id, ttl, replace: true, extend: true }`): replace + reset TTL.
+     *
+     * The id is automatically prefixed with the job name to prevent collisions
+     * between different job types.
+     *
+     * @param options.id - Unique deduplication key
+     * @param options.ttl - TTL as Duration ('5s', 5000). Required for extend/replace.
+     * @param options.extend - Reset the TTL clock on duplicate within window. Window
+     *   length stays at the original ttl; this option's `ttl` arg is ignored on extend.
+     * @param options.replace - Swap payload of existing pending/delayed job within
+     *   window. Active and retained jobs are not modified.
+     *
+     * @example
+     * ```typescript
+     * // Simple dedup
+     * await SendInvoiceJob.dispatch({ orderId: 123 })
+     *   .dedup({ id: 'order-123' })
+     *
+     * // Throttle: 5 second window
+     * await SendEmailJob.dispatch({ to: 'x' })
+     *   .dedup({ id: 'welcome', ttl: '5s' })
+     *
+     * // Debounce: replace payload within window
+     * await SaveDraftJob.dispatch({ content: 'latest' })
+     *   .dedup({ id: 'draft-42', ttl: '2s', replace: true, extend: true })
+     * ```
+     */
+    dedup(options: {
+        id: string;
+        ttl?: Duration;
+        extend?: boolean;
+        replace?: boolean;
+    }): this;
     /**
      * Use a specific adapter for this job.
      *
@@ -1451,4 +1711,4 @@ declare abstract class Job<Payload = any> {
     failed?(error: Error): Promise<void>;
 }
 
-export { type Adapter as A, type BackoffConfig as B, type Duration as D, type JobData as J, type Logger as L, type QueueManagerConfig as Q, type RetryConfig as R, type ScheduleConfig as S, type WorkerCycle as W, type JobClass as a, type AcquiredJob as b, type JobRetention as c, type JobRecord as d, type ScheduleData as e, type ScheduleListOptions as f, type JobOptions as g, type QueueConfig as h, type JobFactory as i, Job as j, type ScheduleStatus as k, ScheduleBuilder as l, JobBatchDispatcher as m, customBackoff as n, linearBackoff as o, exponentialBackoff as p, fixedBackoff as q, type AdapterFactory as r, type BackoffStrategy as s, type DispatchManyResult as t, type DispatchResult as u, type JobContext as v, type JobStatus as w, type ScheduleResult as x, type WorkerConfig as y };
+export { type Adapter as A, type BackoffConfig as B, type DedupOutcome as D, type JobData as J, type Logger as L, type PushResult as P, type QueueManagerConfig as Q, type RetryConfig as R, type ScheduleConfig as S, type WorkerCycle as W, type JobClass as a, type AcquiredJob as b, type JobRetention as c, type JobRecord as d, type ScheduleData as e, type ScheduleListOptions as f, type JobOptions as g, type QueueConfig as h, type Duration as i, type JobFactory as j, Job as k, type ScheduleStatus as l, JobBatchDispatcher as m, ScheduleBuilder as n, customBackoff as o, exponentialBackoff as p, fixedBackoff as q, linearBackoff as r, type AdapterFactory as s, type BackoffStrategy as t, type DispatchManyResult as u, type DispatchResult as v, type JobContext as w, type JobStatus as x, type ScheduleResult as y, type WorkerConfig as z };

package/build/src/contracts/adapter.d.ts

@@ -1 +1 @@
-export { b as AcquiredJob, A as Adapter } from '../../job-DImdhRFO.js';
+export { b as AcquiredJob, A as Adapter, P as PushResult } from '../../job-C4oyCVxR.js';

package/build/src/drivers/fake_adapter.d.ts

@@ -1,4 +1,4 @@
-import { A as Adapter, J as JobData, a as JobClass, b as AcquiredJob, c as JobRetention, d as JobRecord, S as ScheduleConfig, e as ScheduleData, f as ScheduleListOptions } from '../../job-DImdhRFO.js';
+import { A as Adapter, J as JobData, a as JobClass, P as PushResult, b as AcquiredJob, c as JobRetention, d as JobRecord, S as ScheduleConfig, e as ScheduleData, f as ScheduleListOptions } from '../../job-C4oyCVxR.js';
 
 interface FakeJobRecord {
     queue: string;
@@ -23,7 +23,12 @@ declare function fake(): () => FakeAdapter;
  */
 declare class FakeAdapter implements Adapter {
     #private;
-    setWorkerId(_workerId: string): void;
+    /**
+     * Set the function to call when the fake is disposed
+     */
+    onDispose(fn: () => void): this;
+    [Symbol.dispose](): void;
+    setWorkerId(workerId: string): void;
     getPushedJobs(): FakeJobRecord[];
     getPushedJobsOn(queue: string): FakeJobRecord[];
     findPushed(matcher: FakeJobMatcher, query?: FakeJobQuery): FakeJobRecord | undefined;
@@ -37,10 +42,10 @@ declare class FakeAdapter implements Adapter {
     assertNothingPushed(): void;
     size(): Promise<number>;
     sizeOf(queue: string): Promise<number>;
-    push(jobData: JobData): Promise<void>;
-    pushOn(queue: string, jobData: JobData): Promise<void>;
-    pushLater(jobData: JobData, delay: number): Promise<void>;
-    pushLaterOn(queue: string, jobData: JobData, delay: number): Promise<void>;
+    push(jobData: JobData): Promise<PushResult | void>;
+    pushOn(queue: string, jobData: JobData): Promise<PushResult | void>;
+    pushLater(jobData: JobData, delay: number): Promise<PushResult | void>;
+    pushLaterOn(queue: string, jobData: JobData, delay: number): Promise<PushResult | void>;
     pushMany(jobs: JobData[]): Promise<void>;
     pushManyOn(queue: string, jobs: JobData[]): Promise<void>;
     pop(): Promise<AcquiredJob | null>;
@@ -49,6 +54,7 @@ declare class FakeAdapter implements Adapter {
     failJob(jobId: string, queue: string, error?: Error, removeOnFail?: JobRetention): Promise<void>;
     retryJob(jobId: string, queue: string, retryAt?: Date): Promise<void>;
     recoverStalledJobs(queue: string, stalledThreshold: number, maxStalledCount: number): Promise<number>;
+    renewJobs(queue: string, jobIds: string[]): Promise<number>;
     getJob(jobId: string, queue: string): Promise<JobRecord | null>;
     destroy(): Promise<void>;
     upsertSchedule(config: ScheduleConfig): Promise<string>;

package/build/src/drivers/fake_adapter.js

@@ -1,7 +1,7 @@
 import {
   FakeAdapter,
   fake
-} from "../../chunk-VHN3XZDC.js";
+} from "../../chunk-AHUVTAI7.js";
 import "../../chunk-WVLSICD4.js";
 import "../../chunk-QEFYHCL7.js";
 import "../../chunk-PZ5AY32C.js";

package/build/src/drivers/knex_adapter.d.ts

@@ -1,5 +1,5 @@
 import { Knex } from 'knex';
-import { A as Adapter, b as AcquiredJob, c as JobRetention, d as JobRecord, J as JobData, S as ScheduleConfig, e as ScheduleData, f as ScheduleListOptions } from '../../job-DImdhRFO.js';
+import { A as Adapter, b as AcquiredJob, c as JobRetention, d as JobRecord, J as JobData, P as PushResult, S as ScheduleConfig, e as ScheduleData, f as ScheduleListOptions } from '../../job-C4oyCVxR.js';
 
 interface KnexAdapterOptions {
     connection: Knex;
@@ -34,15 +34,16 @@ declare class KnexAdapter implements Adapter {
     failJob(jobId: string, queue: string, error?: Error, removeOnFail?: JobRetention): Promise<void>;
     getJob(jobId: string, queue: string): Promise<JobRecord | null>;
     retryJob(jobId: string, queue: string, retryAt?: Date): Promise<void>;
-    push(jobData: JobData): Promise<void>;
-    pushOn(queue: string, jobData: JobData): Promise<void>;
-    pushLater(jobData: JobData, delay: number): Promise<void>;
-    pushLaterOn(queue: string, jobData: JobData, delay: number): Promise<void>;
+    push(jobData: JobData): Promise<PushResult | void>;
+    pushOn(queue: string, jobData: JobData): Promise<PushResult | void>;
+    pushLater(jobData: JobData, delay: number): Promise<PushResult | void>;
+    pushLaterOn(queue: string, jobData: JobData, delay: number): Promise<PushResult | void>;
     pushMany(jobs: JobData[]): Promise<void>;
     pushManyOn(queue: string, jobs: JobData[]): Promise<void>;
     size(): Promise<number>;
     sizeOf(queue: string): Promise<number>;
     recoverStalledJobs(queue: string, stalledThreshold: number, maxStalledCount: number): Promise<number>;
+    renewJobs(queue: string, jobIds: string[]): Promise<number>;
     upsertSchedule(config: ScheduleConfig): Promise<string>;
     /**
      * @deprecated Use `upsertSchedule` instead.