@monque/core 1.1.2 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@monque/core",
-	"version": "1.1.2",
+	"version": "1.3.0",
 	"description": "MongoDB-backed job scheduler with atomic locking, exponential backoff, and cron scheduling",
 	"author": "Maurice de Bruyn <debruyn.maurice@gmail.com>",
 	"repository": {
@@ -53,7 +53,7 @@
 		"test:watch": "vitest",
 		"test:watch:unit": "vitest --config vitest.unit.config.ts",
 		"test:watch:integration": "vitest integration/",
-		"lint": "biome check src/"
+		"lint": "biome check ."
 	},
 	"keywords": [
 		"job",
@@ -72,21 +72,17 @@
 		"cron-parser": "^5.5.0"
 	},
 	"peerDependencies": {
-		"mongodb": "^7.0.0"
+		"mongodb": "^7.1.0"
 	},
 	"devDependencies": {
-		"@arethetypeswrong/cli": "^0.18.2",
-		"@faker-js/faker": "^10.2.0",
-		"@testcontainers/mongodb": "^11.11.0",
+		"@faker-js/faker": "^10.3.0",
+		"@testcontainers/mongodb": "^11.12.0",
 		"@total-typescript/ts-reset": "^0.6.1",
-		"@types/bun": "^1.3.6",
+		"@types/node": "^22.19.11",
 		"@vitest/coverage-v8": "^4.0.18",
 		"fishery": "^2.4.0",
-		"mongodb": "^7.0.0",
-		"publint": "^0.3.17",
-		"tsdown": "^0.20.1",
-		"typescript": "^5.9.3",
-		"unplugin-unused": "^0.5.7",
+		"mongodb": "^7.1.0",
+		"tsdown": "^0.20.3",
 		"vitest": "^4.0.18"
 	}
 }

package/src/scheduler/monque.ts

@@ -41,7 +41,7 @@ const DEFAULTS = {
 	maxRetries: 10,
 	baseRetryInterval: 1000,
 	shutdownTimeout: 30000,
-	defaultConcurrency: 5,
+	workerConcurrency: 5,
 	lockTimeout: 1_800_000, // 30 minutes
 	recoverStaleJobs: true,
 	heartbeatInterval: 30000, // 30 seconds
@@ -139,10 +139,12 @@ export class Monque extends 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 ?? randomUUID(),
 			heartbeatInterval: options.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
 			jobRetention: options.jobRetention,
@@ -918,7 +920,7 @@ export class Monque extends EventEmitter {
 	 * ```
 	 */
 	register<T>(name: string, handler: JobHandler<T>, options: WorkerOptions = {}): void {
-		const concurrency = options.concurrency ?? this.options.defaultConcurrency;
+		const concurrency = options.concurrency ?? this.options.workerConcurrency;
 
 		// Check for existing worker and throw unless replace is explicitly true
 		if (this.workers.has(name) && options.replace !== true) {

package/src/scheduler/services/job-processor.ts

@@ -13,36 +13,109 @@ import type { SchedulerContext } from './types.js';
  * @internal Not part of public API.
  */
 export class JobProcessor {
+	/** Guard flag to prevent concurrent poll() execution */
+	private _isPolling = false;
+
 	constructor(private readonly ctx: SchedulerContext) {}
 
+	/**
+	 * Get the total number of active jobs across all workers.
+	 *
+	 * Used for instance-level throttling when `instanceConcurrency` is configured.
+	 */
+	private getTotalActiveJobs(): number {
+		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
+	 */
+	private getGloballyAvailableSlots(workerAvailableSlots: number): number {
+		const { instanceConcurrency } = this.ctx.options;
+
+		if (instanceConcurrency === undefined) {
+			return workerAvailableSlots;
+		}
+
+		const totalActive = this.getTotalActiveJobs();
+		const globalAvailable = instanceConcurrency - totalActive;
+
+		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(): Promise<void> {
-		if (!this.ctx.isRunning()) {
+		if (!this.ctx.isRunning() || this._isPolling) {
+			return;
+		}
+
+		this._isPolling = true;
+
+		try {
+			await this._doPoll();
+		} finally {
+			this._isPolling = false;
+		}
+	}
+
+	/**
+	 * Internal poll implementation.
+	 */
+	private async _doPoll(): Promise<void> {
+		// Early exit if global instanceConcurrency is reached
+		const { instanceConcurrency } = this.ctx.options;
+
+		if (instanceConcurrency !== undefined && this.getTotalActiveJobs() >= instanceConcurrency) {
 			return;
 		}
 
 		for (const [name, worker] of this.ctx.workers) {
 			// Check if worker has capacity
-			const availableSlots = worker.concurrency - worker.activeJobs.size;
+			const workerAvailableSlots = worker.concurrency - worker.activeJobs.size;
 
-			if (availableSlots <= 0) {
+			if (workerAvailableSlots <= 0) {
 				continue;
 			}
 
+			// Apply global concurrency limit
+			const availableSlots = this.getGloballyAvailableSlots(workerAvailableSlots);
+
+			if (availableSlots <= 0) {
+				// Global limit reached, stop processing all workers
+				return;
+			}
+
 			// Try to acquire jobs up to available slots
 			for (let i = 0; i < availableSlots; i++) {
 				if (!this.ctx.isRunning()) {
 					return;
 				}
+
+				// Re-check global limit before each acquisition
+				if (instanceConcurrency !== undefined && this.getTotalActiveJobs() >= instanceConcurrency) {
+					return;
+				}
+
 				const job = await this.acquireJob(name);
 
 				if (job) {
+					// Add to activeJobs immediately to correctly track concurrency
+					worker.activeJobs.set(job._id.toString(), job);
+
 					this.processJob(job, worker).catch((error: unknown) => {
 						this.ctx.emit('job:error', { error: error as Error, job });
 					});
@@ -121,8 +194,6 @@ export class JobProcessor {
 	 */
 	async processJob(job: PersistedJob, worker: WorkerRegistration): Promise<void> {
 		const jobId = job._id.toString();
-		worker.activeJobs.set(jobId, job);
-
 		const startTime = Date.now();
 		this.ctx.emit('job:start', job);
 

package/src/scheduler/services/types.ts

@@ -10,11 +10,23 @@ import type { MonqueOptions } from '../types.js';
  * Resolved Monque options with all defaults applied.
  *
  * Required options have their defaults filled in, while truly optional
- * options (`maxBackoffDelay`, `jobRetention`) remain optional.
+ * options (`maxBackoffDelay`, `jobRetention`, `instanceConcurrency`) remain optional.
  */
 export interface ResolvedMonqueOptions
-	extends Required<Omit<MonqueOptions, 'maxBackoffDelay' | 'jobRetention'>>,
-		Pick<MonqueOptions, 'maxBackoffDelay' | 'jobRetention'> {}
+	extends Required<
+			Omit<
+				MonqueOptions,
+				| 'maxBackoffDelay'
+				| 'jobRetention'
+				| 'instanceConcurrency'
+				| 'defaultConcurrency'
+				| 'maxConcurrency'
+			>
+		>,
+		Pick<MonqueOptions, 'maxBackoffDelay' | 'jobRetention' | 'instanceConcurrency'> {
+	// Ensure resolved options use the new naming convention
+	workerConcurrency: number;
+}
 /**
  * Shared context provided to all internal Monque services.
  *

package/src/scheduler/types.ts

@@ -9,7 +9,8 @@
  *   maxRetries: 10,
  *   baseRetryInterval: 1000,
  *   shutdownTimeout: 30000,
- *   defaultConcurrency: 5,
+ *   workerConcurrency: 5,      // Per-worker default
+ *   instanceConcurrency: 20,   // Global instance limit
  * });
  * ```
  */
@@ -56,7 +57,19 @@ export interface MonqueOptions {
 
 	/**
 	 * Default number of concurrent jobs per worker.
+	 *
+	 * This is the per-worker concurrency limit applied when a worker is registered
+	 * without specifying its own `concurrency` option.
+	 *
+	 * @default 5
+	 */
+	workerConcurrency?: number;
+
+	/**
+	 * Default number of concurrent jobs per worker.
+	 *
 	 * @default 5
+	 * @deprecated Use `workerConcurrency` instead. Will be removed in a future major version.
 	 */
 	defaultConcurrency?: number;
 
@@ -120,4 +133,33 @@ export interface MonqueOptions {
 				interval?: number;
 		  }
 		| undefined;
+
+	/**
+	 * Maximum number of concurrent jobs processed by this instance across all registered workers.
+	 *
+	 * If reached, the scheduler will stop claiming new jobs until active jobs complete.
+	 * Use this to prevent a single instance from overwhelming system resources.
+	 *
+	 * Note: This is an instance-level limit. Each worker still respects its own `concurrency`
+	 * setting, but the total across all workers cannot exceed this limit.
+	 *
+	 * @example
+	 * ```typescript
+	 * const monque = new Monque(db, {
+	 *   instanceConcurrency: 10, // Instance processes max 10 jobs total
+	 *   workerConcurrency: 5,    // Each worker defaults to 5 concurrent jobs
+	 * });
+	 *
+	 * // With 3 workers at concurrency 5, normally 15 jobs could run.
+	 * // With instanceConcurrency: 10, only 10 jobs run at any time.
+	 * ```
+	 */
+	instanceConcurrency?: number | undefined;
+
+	/**
+	 * Maximum number of concurrent jobs processed by this instance across all registered workers.
+	 *
+	 * @deprecated Use `instanceConcurrency` instead. Will be removed in a future major version.
+	 */
+	maxConcurrency?: number | undefined;
 }