mongo-job-scheduler 0.1.15 → 0.1.16

package/README.md

@@ -11,6 +11,7 @@ A production-grade MongoDB-backed job scheduler for Node.js with distributed loc
 - ✅ **Distributed locking** — safe for multiple instances
 - ✅ **Atomic job execution** — no double processing
 - ✅ **Job priority** — process important jobs first
+- ✅ **Concurrency limits** — rate-limit job execution
 - ✅ **Automatic retries** — with configurable backoff
 - ✅ **Cron scheduling** — timezone-aware, non-drifting
 - ✅ **Interval jobs** — repeated execution
@@ -207,6 +208,27 @@ await scheduler.updateJob(jobId, { priority: 2 });
 
 > **Priority Scale**: 1 (highest) → 10 (lowest). Jobs with equal priority run in FIFO order by `nextRunAt`.
 
+### Concurrency Limits
+
+Limit how many instances of a job type can run simultaneously (useful for rate-limiting API calls):
+
+```typescript
+// Max 5 concurrent "api-sync" jobs globally
+await scheduler.schedule({
+  name: "api-sync",
+  concurrency: 5,
+});
+
+// Max 2 concurrent "webhook" jobs
+await scheduler.schedule({
+  name: "webhook",
+  data: { url: "https://..." },
+  concurrency: 2,
+});
+```
+
+> **Note**: Concurrency is enforced globally across all workers. Jobs exceeding the limit wait until a slot frees up.
+
 ### Retries with Backoff
 
 ```typescript

package/dist/core/scheduler.js

@@ -42,6 +42,12 @@ class Scheduler {
                 throw new Error("Priority must be an integer between 1 and 10");
             }
         }
+        // Concurrency validation
+        if (options.concurrency !== undefined) {
+            if (!Number.isInteger(options.concurrency) || options.concurrency < 1) {
+                throw new Error("Concurrency must be a positive integer");
+            }
+        }
         // ------------------------
         // Normalize run time
         // ------------------------
@@ -59,6 +65,7 @@ class Scheduler {
             repeat: options.repeat,
             dedupeKey: options.dedupeKey,
             priority: options.priority,
+            concurrency: options.concurrency,
             createdAt: now,
             updatedAt: now,
         };
@@ -88,6 +95,12 @@ class Scheduler {
                     throw new Error("Priority must be an integer between 1 and 10");
                 }
             }
+            // Concurrency validation
+            if (options.concurrency !== undefined) {
+                if (!Number.isInteger(options.concurrency) || options.concurrency < 1) {
+                    throw new Error("Concurrency must be a positive integer");
+                }
+            }
             const job = {
                 name: options.name,
                 data: options.data,
@@ -97,6 +110,7 @@ class Scheduler {
                 retry: options.retry,
                 dedupeKey: options.dedupeKey,
                 priority: options.priority,
+                concurrency: options.concurrency,
             };
             if (isNaN(job.nextRunAt.getTime())) {
                 throw new Error("Invalid Date provided for runAt");

package/dist/store/in-memory-job-store.d.ts

@@ -25,5 +25,6 @@ export declare class InMemoryJobStore implements JobStore {
     findById(jobId: unknown): Promise<Job | null>;
     renewLock(jobId: unknown, workerId: string): Promise<void>;
     update(jobId: unknown, updates: JobUpdates): Promise<void>;
+    countRunning(jobName: string): Promise<number>;
     findAll(query: JobQuery): Promise<Job[]>;
 }

package/dist/store/in-memory-job-store.js

@@ -54,6 +54,14 @@ class InMemoryJobStore {
                     now.getTime() - job.lockedAt.getTime() < lockTimeoutMs) {
                     continue;
                 }
+                // Check concurrency limit if defined
+                if (job.concurrency !== undefined && job.concurrency > 0) {
+                    const runningCount = Array.from(this.jobs.values()).filter((j) => j.name === job.name && j.status === "running").length;
+                    if (runningCount >= job.concurrency) {
+                        // At concurrency limit, skip this job
+                        continue;
+                    }
+                }
                 job.status = "running";
                 job.lockedAt = now;
                 job.lockedBy = workerId;
@@ -165,8 +173,14 @@ class InMemoryJobStore {
         if (updates.priority !== undefined) {
             job.priority = updates.priority;
         }
+        if (updates.concurrency !== undefined) {
+            job.concurrency = updates.concurrency;
+        }
         job.updatedAt = new Date();
     }
+    async countRunning(jobName) {
+        return Array.from(this.jobs.values()).filter((j) => j.name === jobName && j.status === "running").length;
+    }
     async findAll(query) {
         let jobs = Array.from(this.jobs.values());
         // Filter

package/dist/store/job-store.d.ts

@@ -60,6 +60,10 @@ export interface JobStore {
      * Find all jobs matching query
      */
     findAll(query: JobQuery): Promise<Job[]>;
+    /**
+     * Count running jobs by name (for concurrency limits)
+     */
+    countRunning(jobName: string): Promise<number>;
 }
 import { RetryOptions } from "../types/retry";
 import { RepeatOptions } from "../types/repeat";
@@ -72,4 +76,5 @@ export interface JobUpdates {
     status?: JobStatus;
     attempts?: number;
     priority?: number;
+    concurrency?: number;
 }

package/dist/store/mongo/mongo-job-store.d.ts

@@ -35,5 +35,6 @@ export declare class MongoJobStore implements JobStore {
     }): Promise<number>;
     renewLock(id: ObjectId, workerId: string): Promise<void>;
     update(id: ObjectId, updates: JobUpdates): Promise<void>;
+    countRunning(jobName: string): Promise<number>;
     findAll(query: JobQuery): Promise<Job[]>;
 }

package/dist/store/mongo/mongo-job-store.js

@@ -21,6 +21,8 @@ class MongoJobStore {
             this.collection.createIndex({ dedupeKey: 1 }, { unique: true, sparse: true, background: true }),
             // Index for stale lock recovery
             this.collection.createIndex({ lockedAt: 1 }, { sparse: true, background: true }),
+            // Index for concurrency counting
+            this.collection.createIndex({ name: 1, status: 1 }, { background: true }),
         ]);
     }
     // --------------------------------------------------
@@ -76,31 +78,68 @@ class MongoJobStore {
         }));
     }
     // --------------------------------------------------
-    // ATOMIC FIND & LOCK
+    // ATOMIC FIND & LOCK (with concurrency support)
     // --------------------------------------------------
     async findAndLockNext(options) {
         const { now, workerId, lockTimeoutMs } = options;
         const lockExpiry = new Date(now.getTime() - lockTimeoutMs);
-        const result = await this.collection.findOneAndUpdate({
+        // Base query for runnable jobs
+        const baseQuery = {
             status: "pending",
             nextRunAt: { $lte: now },
             $or: [
                 { lockedAt: { $exists: false } },
                 { lockedAt: { $lte: lockExpiry } },
             ],
-        }, {
-            $set: {
-                lockedAt: now,
-                lockedBy: workerId,
-                status: "running",
-                lastRunAt: now,
-                updatedAt: now,
-            },
-        }, {
-            sort: { priority: 1, nextRunAt: 1 },
-            returnDocument: "after",
-        });
-        return result;
+        };
+        // Try to find and lock a job, respecting concurrency limits
+        // We use a loop to handle cases where a job has a concurrency limit
+        const maxAttempts = 10; // Prevent infinite loops
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            // Find candidate without locking first
+            const candidate = await this.collection.findOne(baseQuery, {
+                sort: { priority: 1, nextRunAt: 1 },
+                skip: attempt, // Skip previously checked candidates
+            });
+            if (!candidate) {
+                return null; // No more candidates
+            }
+            // Check concurrency limit if defined
+            if (candidate.concurrency !== undefined && candidate.concurrency > 0) {
+                const runningCount = await this.collection.countDocuments({
+                    name: candidate.name,
+                    status: "running",
+                });
+                if (runningCount >= candidate.concurrency) {
+                    // At concurrency limit, skip this job and try next
+                    continue;
+                }
+            }
+            // Attempt atomic lock on this specific job
+            const result = await this.collection.findOneAndUpdate({
+                _id: candidate._id,
+                status: "pending", // Re-verify status
+                $or: [
+                    { lockedAt: { $exists: false } },
+                    { lockedAt: { $lte: lockExpiry } },
+                ],
+            }, {
+                $set: {
+                    lockedAt: now,
+                    lockedBy: workerId,
+                    status: "running",
+                    lastRunAt: now,
+                    updatedAt: now,
+                },
+            }, {
+                returnDocument: "after",
+            });
+            if (result) {
+                return result;
+            }
+            // Job was taken by another worker, try next
+        }
+        return null;
     }
     // --------------------------------------------------
     // MARK COMPLETED
@@ -225,8 +264,19 @@ class MongoJobStore {
             $set.attempts = updates.attempts;
         if (updates.priority !== undefined)
             $set.priority = updates.priority;
+        if (updates.concurrency !== undefined)
+            $set.concurrency = updates.concurrency;
         await this.collection.updateOne({ _id: id }, { $set });
     }
+    // --------------------------------------------------
+    // COUNT RUNNING (for concurrency limits)
+    // --------------------------------------------------
+    async countRunning(jobName) {
+        return this.collection.countDocuments({
+            name: jobName,
+            status: "running",
+        });
+    }
     async findAll(query) {
         const filter = {};
         if (query.name) {

package/dist/types/job.d.ts

@@ -21,6 +21,11 @@ export interface Job<Data = unknown> {
      * Default: 5
      */
     priority?: number;
+    /**
+     * Max concurrent running jobs with this name.
+     * undefined = no limit.
+     */
+    concurrency?: number;
     createdAt: Date;
     updatedAt: Date;
 }

package/dist/types/schedule.d.ts

@@ -25,4 +25,9 @@ export interface ScheduleOptions<T = unknown> {
      * Default: 5
      */
     priority?: number;
+    /**
+     * Max concurrent running jobs with this name.
+     * Useful for rate-limiting external API calls.
+     */
+    concurrency?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mongo-job-scheduler",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Production-grade MongoDB-backed job scheduler with retries, cron, timezone support, and crash recovery",
   "license": "MIT",
   "author": "Darshan Bhut",