@boringnode/queue 0.5.1 → 0.6.0

package/build/{chunk-VHN3XZDC.js → chunk-AHUVTAI7.js}

@@ -275,6 +275,7 @@ var QueueManagerSingleton = class {
   #internalOperationWrapper;
   #executionWrapper;
   #configResolver = new QueueConfigResolver({});
+  #locations = [];
   #fakeState;
   /**
    * Initialize the queue system with the given configuration.
@@ -311,17 +312,43 @@ var QueueManagerSingleton = class {
     this.#internalOperationWrapper = config.internalOperationWrapper;
     this.#executionWrapper = config.executionWrapper;
     this.#configResolver = QueueConfigResolver.from(config);
-    if (config.locations && config.locations.length > 0) {
-      const registered = await Locator.registerFromGlob(config.locations);
-      if (registered === 0) {
-        this.#logger.warn(
-          `No jobs found for locations: ${config.locations.join(", ")}. Verify your glob patterns match your job files.`
-        );
-      }
+    this.#locations = config.locations ?? [];
+    if (config.autoLoadJobs ?? true) {
+      await this.loadJobs();
     }
     this.#initialized = true;
     return this;
   }
+  /**
+   * Load and register job classes from configured or explicit locations.
+   *
+   * This low-level API is useful for framework integrations that need to
+   * register jobs at a precise moment in their command lifecycle.
+   *
+   * @param locations - Optional glob patterns. Defaults to the configured locations.
+   * @returns Number of jobs successfully registered.
+   *
+   * @example
+   * ```typescript
+   * await QueueManager.init(config)
+   * await QueueManager.loadJobs()
+   *
+   * // Or with explicit locations
+   * await QueueManager.loadJobs(['./app/jobs/**\/*.js'])
+   * ```
+   */
+  async loadJobs(locations = this.#locations) {
+    if (locations.length === 0) {
+      return 0;
+    }
+    const registered = await Locator.registerFromGlob(locations);
+    if (registered === 0) {
+      this.#logger.warn(
+        `No jobs found for locations: ${locations.join(", ")}. Verify your glob patterns match your job files.`
+      );
+    }
+    return registered;
+  }
   /**
    * Destroy any materialized adapters from the current configuration before
    * replacing it with a new one.
@@ -406,19 +433,18 @@ var QueueManagerSingleton = class {
    * Replace all adapters with a fake adapter for testing.
    *
    * The fake adapter records pushed jobs and exposes assertion helpers.
-   * Call `restore()` to return to the previous configuration.
-   *
-   * @returns The fake adapter instance for assertions
-   * @throws {E_QUEUE_NOT_INITIALIZED} If `init()` hasn't been called
+   * Use the `using` keyword to automatically restore the previous
+   * configuration when the variable goes out of scope, or call
+   * `restore()` manually.
    *
    * @example
    * ```typescript
-   * const fake = QueueManager.fake()
+   * using fake = QueueManager.fake()
    *
    * await SendEmailJob.dispatch({ to: 'user@example.com' })
    *
    * fake.assertPushed(SendEmailJob)
-   * QueueManager.restore()
+   * // Automatically restored at end of scope
    * ```
    */
   fake() {
@@ -429,6 +455,7 @@ var QueueManagerSingleton = class {
       return this.#fakeState.fakeAdapter;
     }
     const fakeAdapter = new FakeAdapter();
+    fakeAdapter.onDispose(() => this.restore());
     this.#fakeState = {
       defaultAdapter: this.#defaultAdapter,
       adapters: this.#adapters,
@@ -438,6 +465,7 @@ var QueueManagerSingleton = class {
       internalOperationWrapper: this.#internalOperationWrapper,
       executionWrapper: this.#executionWrapper,
       configResolver: this.#configResolver,
+      locations: this.#locations,
       fakeAdapter
     };
     const fakeFactory = () => fakeAdapter;
@@ -470,6 +498,7 @@ var QueueManagerSingleton = class {
     this.#internalOperationWrapper = state.internalOperationWrapper;
     this.#executionWrapper = state.executionWrapper;
     this.#configResolver = state.configResolver;
+    this.#locations = state.locations;
   }
   /**
    * Get the configured job factory for custom instantiation.
@@ -559,6 +588,7 @@ var QueueManagerSingleton = class {
     this.#internalOperationWrapper = void 0;
     this.#executionWrapper = void 0;
     this.#configResolver = new QueueConfigResolver({});
+    this.#locations = [];
     this.#fakeState = void 0;
   }
 };
@@ -573,6 +603,7 @@ var JobDispatcher = class {
   #delay;
   #priority;
   #groupId;
+  #dedup;
   /**
    * Create a new job dispatcher.
    *
@@ -664,6 +695,76 @@ var JobDispatcher = class {
     this.#groupId = groupId;
     return 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) {
+    if (!options.id) {
+      throw new Error("Dedup ID must be a non-empty string");
+    }
+    if (options.id.length > 400) {
+      throw new Error("Dedup ID must be 400 characters or less");
+    }
+    const prefixedLength = this.#name.length + 2 + options.id.length;
+    if (prefixedLength > 510) {
+      throw new Error(
+        `Dedup ID combined with job name exceeds 510 characters (got ${prefixedLength}). Shorten either the job name or the dedup id.`
+      );
+    }
+    if ((options.extend || options.replace) && options.ttl === void 0) {
+      throw new Error("dedup.ttl is required when extend or replace is set");
+    }
+    let parsedTtl;
+    if (options.ttl !== void 0) {
+      parsedTtl = parse(options.ttl);
+      if (!Number.isFinite(parsedTtl) || parsedTtl <= 0) {
+        throw new Error("dedup.ttl must be a positive duration");
+      }
+    }
+    this.#dedup = {
+      id: options.id,
+      ttl: parsedTtl,
+      extend: options.extend,
+      replace: options.replace
+    };
+    return this;
+  }
   /**
    * Use a specific adapter for this job.
    *
@@ -696,6 +797,7 @@ var JobDispatcher = class {
    */
   async run() {
     const id = randomUUID();
+    const dedupId = this.#dedup ? `${this.#name}::${this.#dedup.id}` : void 0;
     debug_default("dispatching job %s with id %s using payload %s", this.#name, id, this.#payload);
     const adapter = this.#getAdapterInstance();
     const wrapInternal = QueueManager.getInternalOperationWrapper();
@@ -706,16 +808,32 @@ var JobDispatcher = class {
       payload: this.#payload,
       attempts: 0,
       priority: this.#priority,
-      groupId: this.#groupId
+      groupId: this.#groupId,
+      createdAt: Date.now(),
+      ...dedupId ? {
+        dedup: {
+          id: dedupId,
+          ttl: this.#dedup.ttl,
+          extend: this.#dedup.extend,
+          replace: this.#dedup.replace
+        }
+      } : {}
     };
     const message = { jobs: [jobData], queue: this.#queue, delay: parsedDelay };
+    let pushResult;
     await dispatchChannel.tracePromise(async () => {
-      if (parsedDelay !== void 0) {
-        await wrapInternal(() => adapter.pushLaterOn(this.#queue, jobData, parsedDelay));
-      } else {
-        await wrapInternal(() => adapter.pushOn(this.#queue, jobData));
+      const result = parsedDelay !== void 0 ? await wrapInternal(() => adapter.pushLaterOn(this.#queue, jobData, parsedDelay)) : await wrapInternal(() => adapter.pushOn(this.#queue, jobData));
+      if (result && typeof result === "object" && "outcome" in result) {
+        pushResult = { outcome: result.outcome, jobId: result.jobId };
+        message.dedupOutcome = result.outcome;
       }
     }, message);
+    if (pushResult && this.#dedup) {
+      return {
+        jobId: pushResult.jobId,
+        deduped: pushResult.outcome
+      };
+    }
     return { jobId: id };
   }
   /**
@@ -845,13 +963,15 @@ var JobBatchDispatcher = class {
     debug_default("dispatching %d jobs of type %s", this.#payloads.length, this.#name);
     const adapter = this.#getAdapterInstance();
     const wrapInternal = QueueManager.getInternalOperationWrapper();
+    const now = Date.now();
     const jobs = this.#payloads.map((payload) => ({
       id: randomUUID2(),
       name: this.#name,
       payload,
       attempts: 0,
       priority: this.#priority,
-      groupId: this.#groupId
+      groupId: this.#groupId,
+      createdAt: now
     }));
     const message = { jobs, queue: this.#queue };
     await dispatchChannel.tracePromise(async () => {
@@ -1264,7 +1384,21 @@ var FakeAdapter = class {
   #pendingTimeouts = /* @__PURE__ */ new Set();
   #schedules = /* @__PURE__ */ new Map();
   #pushedJobs = [];
-  setWorkerId(_workerId) {
+  #dedupIndex = /* @__PURE__ */ new Map();
+  #onDispose;
+  #workerId = "";
+  /**
+   * Set the function to call when the fake is disposed
+   */
+  onDispose(fn) {
+    this.#onDispose = fn;
+    return this;
+  }
+  [Symbol.dispose]() {
+    this.#onDispose?.();
+  }
+  setWorkerId(workerId) {
+    this.#workerId = workerId;
   }
   getPushedJobs() {
     return [...this.#pushedJobs];
@@ -1290,6 +1424,7 @@ var FakeAdapter = class {
     this.#failedJobs.clear();
     this.#schedules.clear();
     this.#pushedJobs = [];
+    this.#dedupIndex.clear();
   }
   assertPushed(matcher, query) {
     const record = this.findPushed(matcher, query);
@@ -1322,21 +1457,33 @@ var FakeAdapter = class {
     return this.pushOn("default", jobData);
   }
   async pushOn(queue, jobData) {
+    const deduped = await this.#applyDedup(queue, jobData);
+    if (deduped) return deduped;
     this.#recordPush(queue, jobData);
     this.#enqueue(queue, jobData);
+    if (jobData.dedup) {
+      return { outcome: "added", jobId: jobData.id };
+    }
   }
   async pushLater(jobData, delay) {
     return this.pushLaterOn("default", jobData, delay);
   }
-  pushLaterOn(queue, jobData, delay) {
+  async pushLaterOn(queue, jobData, delay) {
+    const deduped = await this.#applyDedup(queue, jobData);
+    if (deduped) return deduped;
     this.#recordPush(queue, jobData, delay);
     this.#schedulePush(queue, jobData, delay);
-    return Promise.resolve();
+    if (jobData.dedup) {
+      return { outcome: "added", jobId: jobData.id };
+    }
   }
   async pushMany(jobs) {
     return this.pushManyOn("default", jobs);
   }
   async pushManyOn(queue, jobs) {
+    if (jobs.some((j) => j.dedup)) {
+      throw new Error("dedup is not supported in batch dispatch; use single dispatch");
+    }
     for (const job of jobs) {
       await this.pushOn(queue, job);
     }
@@ -1363,7 +1510,7 @@ var FakeAdapter = class {
       return null;
     }
     const acquiredAt = Date.now();
-    this.#activeJobs.set(job.id, { job, acquiredAt, queue });
+    this.#activeJobs.set(job.id, { job, acquiredAt, queue, workerId: this.#workerId });
     return { ...job, acquiredAt };
   }
   async completeJob(jobId, queue, removeOnComplete) {
@@ -1371,6 +1518,7 @@ var FakeAdapter = class {
     if (!active) return;
     this.#activeJobs.delete(jobId);
     if (removeOnComplete === void 0 || removeOnComplete === true) {
+      this.#cleanupDedupForJob(queue, active.job);
       return;
     }
     this.#storeHistory(queue, "completed", active.job, removeOnComplete);
@@ -1380,6 +1528,7 @@ var FakeAdapter = class {
     if (!active) return;
     this.#activeJobs.delete(jobId);
     if (removeOnFail === void 0 || removeOnFail === true) {
+      this.#cleanupDedupForJob(queue, active.job);
       return;
     }
     this.#storeHistory(queue, "failed", active.job, removeOnFail, error);
@@ -1415,6 +1564,7 @@ var FakeAdapter = class {
       const currentStalledCount = active.job.stalledCount ?? 0;
       if (currentStalledCount >= maxStalledCount) {
         this.#activeJobs.delete(jobId);
+        this.#cleanupDedupForJob(active.queue, active.job);
         continue;
       }
       this.#activeJobs.delete(jobId);
@@ -1427,6 +1577,18 @@ var FakeAdapter = class {
     }
     return recovered;
   }
+  async renewJobs(queue, jobIds) {
+    const now = Date.now();
+    let renewed = 0;
+    for (const jobId of jobIds) {
+      const active = this.#activeJobs.get(jobId);
+      if (active && active.queue === queue && active.workerId === this.#workerId) {
+        active.acquiredAt = now;
+        renewed++;
+      }
+    }
+    return renewed;
+  }
   async getJob(jobId, queue) {
     const active = this.#activeJobs.get(jobId);
     if (active && active.queue === queue) {
@@ -1583,23 +1745,110 @@ var FakeAdapter = class {
     const records = store.get(queue);
     records.push(record);
     if (retention && retention !== true) {
-      this.#applyRetention(records, retention);
+      this.#applyRetention(records, retention, queue);
     }
   }
-  #applyRetention(records, retention) {
+  #applyRetention(records, retention, queue) {
     if (retention === false || retention === true) {
       return;
     }
+    const pruned = [];
     if (retention.age !== void 0) {
       const maxAgeMs = parse(retention.age);
       if (maxAgeMs > 0) {
         const cutoff = Date.now() - maxAgeMs;
-        const filtered = records.filter((record) => (record.finishedAt ?? 0) >= cutoff);
-        records.splice(0, records.length, ...filtered);
+        const kept = [];
+        for (const record of records) {
+          if ((record.finishedAt ?? 0) >= cutoff) {
+            kept.push(record);
+          } else {
+            pruned.push(record);
+          }
+        }
+        records.splice(0, records.length, ...kept);
       }
     }
     if (retention.count !== void 0 && retention.count > 0 && records.length > retention.count) {
-      records.splice(0, records.length - retention.count);
+      const excess = records.length - retention.count;
+      pruned.push(...records.slice(0, excess));
+      records.splice(0, excess);
+    }
+    for (const record of pruned) {
+      this.#cleanupDedupForJob(queue, record.data);
+    }
+  }
+  #applyDedup(queue, jobData) {
+    if (!jobData.dedup) return null;
+    const dedupId = jobData.dedup.id;
+    const now = Date.now();
+    const entry = this.#getDedupEntry(queue, dedupId);
+    if (entry) {
+      const withinTtl = !entry.ttl || now - entry.createdAt < entry.ttl;
+      if (withinTtl) {
+        const existing = this.#findJobById(queue, entry.jobId);
+        if (existing) {
+          const replaceable = existing.location === "pending" || existing.location === "delayed";
+          if (jobData.dedup.replace && replaceable) {
+            existing.job.payload = structuredClone(jobData.payload);
+            if (jobData.dedup.extend && entry.ttl) {
+              entry.createdAt = now;
+            }
+            return { outcome: "replaced", jobId: entry.jobId };
+          }
+          if (jobData.dedup.extend && entry.ttl) {
+            entry.createdAt = now;
+            return { outcome: "extended", jobId: entry.jobId };
+          }
+          return { outcome: "skipped", jobId: entry.jobId };
+        }
+      }
+    }
+    this.#setDedupEntry(queue, dedupId, {
+      jobId: jobData.id,
+      createdAt: now,
+      ttl: jobData.dedup.ttl,
+      replace: jobData.dedup.replace,
+      extend: jobData.dedup.extend
+    });
+    return null;
+  }
+  #findJobById(queue, jobId) {
+    const active = this.#activeJobs.get(jobId);
+    if (active && active.queue === queue) {
+      return { job: active.job, location: "active" };
+    }
+    const pending = this.#queues.get(queue)?.find((j) => j.id === jobId);
+    if (pending) {
+      return { job: pending, location: "pending" };
+    }
+    const delayed = this.#delayedJobs.get(queue)?.get(jobId);
+    if (delayed) {
+      return { job: delayed.job, location: "delayed" };
+    }
+    const completed = this.#findHistory(this.#completedJobs, queue, jobId);
+    if (completed) {
+      return { job: completed.data, location: "completed" };
+    }
+    const failed = this.#findHistory(this.#failedJobs, queue, jobId);
+    if (failed) {
+      return { job: failed.data, location: "failed" };
+    }
+    return null;
+  }
+  #getDedupEntry(queue, dedupId) {
+    return this.#dedupIndex.get(queue)?.get(dedupId);
+  }
+  #setDedupEntry(queue, dedupId, entry) {
+    if (!this.#dedupIndex.has(queue)) {
+      this.#dedupIndex.set(queue, /* @__PURE__ */ new Map());
+    }
+    this.#dedupIndex.get(queue).set(dedupId, entry);
+  }
+  #cleanupDedupForJob(queue, job) {
+    if (!job.dedup) return;
+    const entry = this.#getDedupEntry(queue, job.dedup.id);
+    if (entry && entry.jobId === job.id) {
+      this.#dedupIndex.get(queue)?.delete(job.dedup.id);
     }
   }
   #findHistory(store, queue, jobId) {
@@ -1677,4 +1926,4 @@ export {
   ScheduleBuilder,
   Job
 };
-//# sourceMappingURL=chunk-VHN3XZDC.js.map
+//# sourceMappingURL=chunk-AHUVTAI7.js.map