mongo-job-scheduler 0.1.14 → 0.1.15

package/README.md

@@ -10,6 +10,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
 - ✅ **Automatic retries** — with configurable backoff
 - ✅ **Cron scheduling** — timezone-aware, non-drifting
 - ✅ **Interval jobs** — repeated execution
@@ -178,6 +179,34 @@ 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`.
+
 ### Retries with Backoff
 
 ```typescript
@@ -246,7 +275,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 +289,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,14 @@ 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");
+            }
+        }
         // ------------------------
         // Normalize run time
         // ------------------------
@@ -50,6 +58,7 @@ class Scheduler {
             retry: options.retry,
             repeat: options.repeat,
             dedupeKey: options.dedupeKey,
+            priority: options.priority,
             createdAt: now,
             updatedAt: now,
         };
@@ -71,6 +80,14 @@ 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");
+                }
+            }
             const job = {
                 name: options.name,
                 data: options.data,
@@ -79,6 +96,7 @@ class Scheduler {
                 repeat: options.repeat,
                 retry: options.retry,
                 dedupeKey: options.dedupeKey,
+                priority: options.priority,
             };
             if (isNaN(job.nextRunAt.getTime())) {
                 throw new Error("Invalid Date provided for runAt");

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)
@@ -153,6 +162,9 @@ class InMemoryJobStore {
         if (updates.attempts !== undefined) {
             job.attempts = updates.attempts;
         }
+        if (updates.priority !== undefined) {
+            job.priority = updates.priority;
+        }
         job.updatedAt = new Date();
     }
     async findAll(query) {

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

@@ -71,4 +71,5 @@ export interface JobUpdates {
     repeat?: RepeatOptions;
     status?: JobStatus;
     attempts?: number;
+    priority?: number;
 }

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

@@ -15,8 +15,8 @@ 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
@@ -34,6 +34,7 @@ class MongoJobStore {
             ...jobWithoutId,
             status: job.status ?? "pending",
             attempts: job.attempts ?? 0,
+            priority: job.priority ?? 5,
             createdAt: now,
             updatedAt: now,
         };
@@ -57,6 +58,7 @@ class MongoJobStore {
                 ...jobWithoutId,
                 status: job.status ?? "pending",
                 attempts: job.attempts ?? 0,
+                priority: job.priority ?? 5,
                 createdAt: now,
                 updatedAt: now,
             };
@@ -95,7 +97,7 @@ class MongoJobStore {
                 updatedAt: now,
             },
         }, {
-            sort: { nextRunAt: 1 },
+            sort: { priority: 1, nextRunAt: 1 },
             returnDocument: "after",
         });
         return result;
@@ -221,6 +223,8 @@ class MongoJobStore {
             $set.status = updates.status;
         if (updates.attempts !== undefined)
             $set.attempts = updates.attempts;
+        if (updates.priority !== undefined)
+            $set.priority = updates.priority;
         await this.collection.updateOne({ _id: id }, { $set });
     }
     async findAll(query) {

package/dist/types/job.d.ts

@@ -16,6 +16,11 @@ export interface Job<Data = unknown> {
     retry?: RetryOptions | number;
     repeat?: RepeatOptions;
     dedupeKey?: string;
+    /**
+     * Job priority (1-10). Lower values = higher priority.
+     * Default: 5
+     */
+    priority?: number;
     createdAt: Date;
     updatedAt: Date;
 }

package/dist/types/schedule.d.ts

@@ -20,4 +20,9 @@ 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;
 }

package/package.json

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