@monque/core 1.1.2 → 1.3.0

package/README.md

@@ -8,12 +8,31 @@
   <a href="https://www.npmjs.com/package/@monque/core">
     <img src="https://img.shields.io/npm/v/%40monque%2Fcore?style=for-the-badge&label=%40monque%2Fcore" alt="@monque/core version" />
   </a>
+  <a href="https://github.com/ueberBrot/monque/actions/workflows/ci.yml">
+    <img src="https://img.shields.io/github/actions/workflow/status/ueberBrot/monque/ci.yml?branch=main&style=for-the-badge&logo=github" alt="CI Status" />
+  </a>
   <a href="https://codecov.io/gh/ueberBrot/monque">
     <img src="https://img.shields.io/codecov/c/github/ueberBrot/monque?style=for-the-badge&logo=codecov&logoColor=white" alt="Codecov" />
   </a>
+  <a href="https://opensource.org/licenses/ISC">
+    <img src="https://img.shields.io/badge/License-ISC-blue.svg?style=for-the-badge" alt="License: ISC" />
+  </a>
+  <a href="https://bun.sh">
+    <img src="https://img.shields.io/badge/Built%20with-Bun-fbf0df?style=for-the-badge&logo=bun&logoColor=black" alt="Built with Bun" />
+  </a>
 </p>
 
-<p align="center">MongoDB-backed job scheduler with atomic locking, exponential backoff, and cron scheduling.</p>
+A **robust, type-safe MongoDB job queue** for TypeScript with atomic locking, exponential backoff, and cron scheduling.
+
+## Features
+
+- **Atomic Locking**: Mandatory `findOneAndUpdate` for safe job acquisition in distributed environments.
+- **Exponential Backoff**: Built-in retry logic with configurable backoff strategies.
+- **Cron Scheduling**: Native support for recurring jobs using standard cron syntax.
+- **Type Safety**: Fully typed job payloads and worker definitions.
+- **Event-Driven**: Comprehensive event system for monitoring and logging.
+- **Native Driver**: Uses the native MongoDB driver for maximum performance and compatibility.
+- **Graceful Shutdown**: Ensures all in-progress jobs finish or are safely released before stopping.
 
 ## Installation
 

package/dist/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @monque/core
 
+## 1.3.0
+
+### Minor Changes
+
+- [#158](https://github.com/ueberBrot/monque/pull/158) [`2f83396`](https://github.com/ueberBrot/monque/commit/2f833966d7798307deaa7a1e655e0623cfb42a3e) Thanks [@renovate](https://github.com/apps/renovate)! - mongodb (^7.0.0 → ^7.1.0)
+
+### Patch Changes
+
+- [#160](https://github.com/ueberBrot/monque/pull/160) [`b5fcaf8`](https://github.com/ueberBrot/monque/commit/b5fcaf8be2a49fb1ba97b8d3d9f28f00850f77a1) Thanks [@ueberBrot](https://github.com/ueberBrot)! - Fix race condition where concurrent poll cycles could exceed workerConcurrency limit. Added a guard to prevent overlapping poll() execution from setInterval and change stream triggers.
+
+## 1.2.0
+
+### Minor Changes
+
+- [#112](https://github.com/ueberBrot/monque/pull/112) [`9b7f44f`](https://github.com/ueberBrot/monque/commit/9b7f44f5c1f6b4aa4215e571189cc03cbaa49865) Thanks [@ueberBrot](https://github.com/ueberBrot)! - Add instance-level concurrency throttling and deprecated old naming conventions.
+
+  - Added `instanceConcurrency` option (formerly `maxConcurrency`) to limit the total number of jobs processed concurrently across all workers on a single Monque instance.
+  - Added `workerConcurrency` as a clearer alias for `defaultConcurrency`.
+  - Deprecated `maxConcurrency` and `defaultConcurrency` in favor of the new explicit names. They will be removed in the next major version.
+
 ## 1.1.2
 
 ### Patch Changes

package/dist/README.md

@@ -8,12 +8,31 @@
   <a href="https://www.npmjs.com/package/@monque/core">
     <img src="https://img.shields.io/npm/v/%40monque%2Fcore?style=for-the-badge&label=%40monque%2Fcore" alt="@monque/core version" />
   </a>
+  <a href="https://github.com/ueberBrot/monque/actions/workflows/ci.yml">
+    <img src="https://img.shields.io/github/actions/workflow/status/ueberBrot/monque/ci.yml?branch=main&style=for-the-badge&logo=github" alt="CI Status" />
+  </a>
   <a href="https://codecov.io/gh/ueberBrot/monque">
     <img src="https://img.shields.io/codecov/c/github/ueberBrot/monque?style=for-the-badge&logo=codecov&logoColor=white" alt="Codecov" />
   </a>
+  <a href="https://opensource.org/licenses/ISC">
+    <img src="https://img.shields.io/badge/License-ISC-blue.svg?style=for-the-badge" alt="License: ISC" />
+  </a>
+  <a href="https://bun.sh">
+    <img src="https://img.shields.io/badge/Built%20with-Bun-fbf0df?style=for-the-badge&logo=bun&logoColor=black" alt="Built with Bun" />
+  </a>
 </p>
 
-<p align="center">MongoDB-backed job scheduler with atomic locking, exponential backoff, and cron scheduling.</p>
+A **robust, type-safe MongoDB job queue** for TypeScript with atomic locking, exponential backoff, and cron scheduling.
+
+## Features
+
+- **Atomic Locking**: Mandatory `findOneAndUpdate` for safe job acquisition in distributed environments.
+- **Exponential Backoff**: Built-in retry logic with configurable backoff strategies.
+- **Cron Scheduling**: Native support for recurring jobs using standard cron syntax.
+- **Type Safety**: Fully typed job payloads and worker definitions.
+- **Event-Driven**: Comprehensive event system for monitoring and logging.
+- **Native Driver**: Uses the native MongoDB driver for maximum performance and compatibility.
+- **Graceful Shutdown**: Ensures all in-progress jobs finish or are safely released before stopping.
 
 ## Installation
 

package/dist/index.cjs

@@ -1,3 +1,4 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 let mongodb = require("mongodb");
 let cron_parser = require("cron-parser");
 let node_crypto = require("node:crypto");
@@ -1110,31 +1111,74 @@ var JobManager = class {
 * @internal Not part of public API.
 */
 var JobProcessor = class {
+	/** Guard flag to prevent concurrent poll() execution */
+	_isPolling = false;
 	constructor(ctx) {
 		this.ctx = ctx;
 	}
 	/**
+	* Get the total number of active jobs across all workers.
+	*
+	* Used for instance-level throttling when `instanceConcurrency` is configured.
+	*/
+	getTotalActiveJobs() {
+		let total = 0;
+		for (const worker of this.ctx.workers.values()) total += worker.activeJobs.size;
+		return total;
+	}
+	/**
+	* Get the number of available slots considering the global instanceConcurrency limit.
+	*
+	* @param workerAvailableSlots - Available slots for the specific worker
+	* @returns Number of slots available after applying global limit
+	*/
+	getGloballyAvailableSlots(workerAvailableSlots) {
+		const { instanceConcurrency } = this.ctx.options;
+		if (instanceConcurrency === void 0) return workerAvailableSlots;
+		const globalAvailable = instanceConcurrency - this.getTotalActiveJobs();
+		return Math.min(workerAvailableSlots, globalAvailable);
+	}
+	/**
 	* Poll for available jobs and process them.
 	*
 	* Called at regular intervals (configured by `pollInterval`). For each registered worker,
 	* attempts to acquire jobs up to the worker's available concurrency slots.
-	* Aborts early if the scheduler is stopping (`isRunning` is false).
+	* Aborts early if the scheduler is stopping (`isRunning` is false) or if
+	* the instance-level `instanceConcurrency` limit is reached.
 	*/
 	async poll() {
-		if (!this.ctx.isRunning()) return;
+		if (!this.ctx.isRunning() || this._isPolling) return;
+		this._isPolling = true;
+		try {
+			await this._doPoll();
+		} finally {
+			this._isPolling = false;
+		}
+	}
+	/**
+	* Internal poll implementation.
+	*/
+	async _doPoll() {
+		const { instanceConcurrency } = this.ctx.options;
+		if (instanceConcurrency !== void 0 && this.getTotalActiveJobs() >= instanceConcurrency) return;
 		for (const [name, worker] of this.ctx.workers) {
-			const availableSlots = worker.concurrency - worker.activeJobs.size;
-			if (availableSlots <= 0) continue;
+			const workerAvailableSlots = worker.concurrency - worker.activeJobs.size;
+			if (workerAvailableSlots <= 0) continue;
+			const availableSlots = this.getGloballyAvailableSlots(workerAvailableSlots);
+			if (availableSlots <= 0) return;
 			for (let i = 0; i < availableSlots; i++) {
 				if (!this.ctx.isRunning()) return;
+				if (instanceConcurrency !== void 0 && this.getTotalActiveJobs() >= instanceConcurrency) return;
 				const job = await this.acquireJob(name);
-				if (job) this.processJob(job, worker).catch((error) => {
-					this.ctx.emit("job:error", {
-						error,
-						job
+				if (job) {
+					worker.activeJobs.set(job._id.toString(), job);
+					this.processJob(job, worker).catch((error) => {
+						this.ctx.emit("job:error", {
+							error,
+							job
+						});
 					});
-				});
-				else break;
+				} else break;
 			}
 		}
 	}
@@ -1187,7 +1231,6 @@ var JobProcessor = class {
 	*/
 	async processJob(job, worker) {
 		const jobId = job._id.toString();
-		worker.activeJobs.set(jobId, job);
 		const startTime = Date.now();
 		this.ctx.emit("job:start", job);
 		try {
@@ -1817,7 +1860,7 @@ const DEFAULTS = {
 	maxRetries: 10,
 	baseRetryInterval: 1e3,
 	shutdownTimeout: 3e4,
-	defaultConcurrency: 5,
+	workerConcurrency: 5,
 	lockTimeout: 18e5,
 	recoverStaleJobs: true,
 	heartbeatInterval: 3e4,
@@ -1911,10 +1954,11 @@ var Monque = class extends node_events.EventEmitter {
 			maxRetries: options.maxRetries ?? DEFAULTS.maxRetries,
 			baseRetryInterval: options.baseRetryInterval ?? DEFAULTS.baseRetryInterval,
 			shutdownTimeout: options.shutdownTimeout ?? DEFAULTS.shutdownTimeout,
-			defaultConcurrency: options.defaultConcurrency ?? DEFAULTS.defaultConcurrency,
+			workerConcurrency: options.workerConcurrency ?? options.defaultConcurrency ?? DEFAULTS.workerConcurrency,
 			lockTimeout: options.lockTimeout ?? DEFAULTS.lockTimeout,
 			recoverStaleJobs: options.recoverStaleJobs ?? DEFAULTS.recoverStaleJobs,
 			maxBackoffDelay: options.maxBackoffDelay,
+			instanceConcurrency: options.instanceConcurrency ?? options.maxConcurrency,
 			schedulerInstanceId: options.schedulerInstanceId ?? (0, node_crypto.randomUUID)(),
 			heartbeatInterval: options.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
 			jobRetention: options.jobRetention
@@ -2577,7 +2621,7 @@ var Monque = class extends node_events.EventEmitter {
 	* ```
 	*/
 	register(name, handler, options = {}) {
-		const concurrency = options.concurrency ?? this.options.defaultConcurrency;
+		const concurrency = options.concurrency ?? this.options.workerConcurrency;
 		if (this.workers.has(name) && options.replace !== true) throw new WorkerRegistrationError(`Worker already registered for job name "${name}". Use { replace: true } to replace.`, name);
 		this.workers.set(name, {
 			handler,