mongo-job-scheduler 0.1.14 → 0.1.16

package/README.md

@@ -10,6 +10,8 @@ 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
@@ -178,6 +180,55 @@ await scheduler.cancel(jobId);
 
 ## Advanced Features
 
+### Job Priority
+
+Process important jobs first using priority levels (1-10, where 1 is highest priority):
+
+```typescript
+// High priority job - runs first
+await scheduler.schedule({
+  name: "urgent-alert",
+  priority: 1,
+});
+
+// Normal priority (default is 5)
+await scheduler.schedule({
+  name: "regular-task",
+});
+
+// Low priority job - runs last
+await scheduler.schedule({
+  name: "background-cleanup",
+  priority: 10,
+});
+
+// Update priority of existing job
+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
@@ -246,7 +297,7 @@ await scheduler.stop({
 
 The library creates three indexes in background mode:
 
-- `{ status: 1, nextRunAt: 1 }` — for job polling (critical)
+- `{ status: 1, priority: 1, nextRunAt: 1 }` — for priority-based job polling (critical)
 - `{ dedupeKey: 1 }` — for deduplication (unique)
 - `{ lockedAt: 1 }` — for stale lock recovery
 
@@ -260,8 +311,6 @@ Run **multiple scheduler instances** (different servers, pods, or processes) con
 - **Concurrency Control** — only one worker executes a job instance
 - **Horizontally Scalable** — supports MongoDB sharding
 
-- **Horizontally Scalable** — supports MongoDB sharding
-
 ---
 
 ## Documentation

package/dist/core/scheduler.js

@@ -34,6 +34,20 @@ class Scheduler {
         if (options.repeat?.cron && options.repeat?.every != null) {
             throw new Error("Use either cron or every, not both");
         }
+        // Priority validation
+        if (options.priority !== undefined) {
+            if (!Number.isInteger(options.priority) ||
+                options.priority < 1 ||
+                options.priority > 10) {
+                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
         // ------------------------
@@ -50,6 +64,8 @@ class Scheduler {
             retry: options.retry,
             repeat: options.repeat,
             dedupeKey: options.dedupeKey,
+            priority: options.priority,
+            concurrency: options.concurrency,
             createdAt: now,
             updatedAt: now,
         };
@@ -71,6 +87,20 @@ class Scheduler {
             if (options.repeat?.cron && options.repeat.every) {
                 throw new Error("Cannot specify both cron and every");
             }
+            // Priority validation
+            if (options.priority !== undefined) {
+                if (!Number.isInteger(options.priority) ||
+                    options.priority < 1 ||
+                    options.priority > 10) {
+                    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,
@@ -79,6 +109,8 @@ class Scheduler {
                 repeat: options.repeat,
                 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

@@ -23,6 +23,7 @@ class InMemoryJobStore {
         const stored = {
             ...job,
             _id: id,
+            priority: job.priority ?? 5,
             createdAt: job.createdAt ?? new Date(),
             updatedAt: job.updatedAt ?? new Date(),
         };
@@ -35,7 +36,15 @@ class InMemoryJobStore {
     async findAndLockNext({ now, workerId, lockTimeoutMs, }) {
         const release = await this.mutex.acquire();
         try {
-            for (const job of this.jobs.values()) {
+            // Sort jobs by priority (ascending), then nextRunAt (ascending)
+            const sortedJobs = Array.from(this.jobs.values()).sort((a, b) => {
+                const priorityA = a.priority ?? 5;
+                const priorityB = b.priority ?? 5;
+                if (priorityA !== priorityB)
+                    return priorityA - priorityB;
+                return a.nextRunAt.getTime() - b.nextRunAt.getTime();
+            });
+            for (const job of sortedJobs) {
                 if (job.status !== "pending")
                     continue;
                 if (job.nextRunAt > now)
@@ -45,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;
@@ -153,8 +170,17 @@ class InMemoryJobStore {
         if (updates.attempts !== undefined) {
             job.attempts = updates.attempts;
         }
+        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";
@@ -71,4 +75,6 @@ export interface JobUpdates {
     repeat?: RepeatOptions;
     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

@@ -15,12 +15,14 @@ class MongoJobStore {
      */
     async ensureIndexes() {
         await Promise.all([
-            // Primary index for job polling (findAndLockNext)
-            this.collection.createIndex({ status: 1, nextRunAt: 1 }, { background: true }),
+            // Primary index for job polling (findAndLockNext) with priority
+            this.collection.createIndex({ status: 1, priority: 1, nextRunAt: 1 }, { background: true }),
             // Index for deduplication
             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 }),
         ]);
     }
     // --------------------------------------------------
@@ -34,6 +36,7 @@ class MongoJobStore {
             ...jobWithoutId,
             status: job.status ?? "pending",
             attempts: job.attempts ?? 0,
+            priority: job.priority ?? 5,
             createdAt: now,
             updatedAt: now,
         };
@@ -57,6 +60,7 @@ class MongoJobStore {
                 ...jobWithoutId,
                 status: job.status ?? "pending",
                 attempts: job.attempts ?? 0,
+                priority: job.priority ?? 5,
                 createdAt: now,
                 updatedAt: now,
             };
@@ -74,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: { 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
@@ -221,8 +262,21 @@ class MongoJobStore {
             $set.status = updates.status;
         if (updates.attempts !== undefined)
             $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

@@ -16,6 +16,16 @@ export interface Job<Data = unknown> {
     retry?: RetryOptions | number;
     repeat?: RepeatOptions;
     dedupeKey?: string;
+    /**
+     * Job priority (1-10). Lower values = higher priority.
+     * 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

@@ -20,4 +20,14 @@ export interface ScheduleOptions<T = unknown> {
      * Idempotency key to prevent duplicate jobs
      */
     dedupeKey?: string;
+    /**
+     * Job priority (1-10). Lower values = higher priority.
+     * 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.14",
+  "version": "0.1.16",
   "description": "Production-grade MongoDB-backed job scheduler with retries, cron, timezone support, and crash recovery",
   "license": "MIT",
   "author": "Darshan Bhut",