mongo-job-scheduler 0.1.2 → 0.1.4

package/README.md

@@ -21,8 +21,17 @@ Designed for distributed systems that need:
 - **Interval jobs**
 - **Resume on restart**
 - **Stale lock recovery**
+- **Automatic Lock Renewal** (Heartbeats): Long-running jobs automatically extend their lock.
 - **Sharding-safe design**
 
+## Distributed Systems
+
+This library is designed for distributed environments. You can run **multiple scheduler instances** (on different servers, pods, or processes) connected to the same MongoDB.
+
+- **Atomic Locking**: Uses `findOneAndUpdate` to safe-guard against race conditions.
+- **Concurrency**: Only one worker will execute a given job instance.
+- **Scalable**: Horizontal scaling is supported via MongoDB sharding.
+
 ---
 
 ## Install
@@ -68,6 +77,89 @@ await scheduler.schedule(
 );
 ```
 
+## Interval Scheduling
+
+Run a job repeatedly with a fixed delay between executions (e.g., every 5 minutes).
+
+```typescript
+await scheduler.schedule({
+  name: "cleanup-logs",
+  data: {},
+  repeat: {
+    every: 5 * 60 * 1000, // 5 minutes in milliseconds
+  },
+});
+```
+
+## Job Deduplication
+
+Prevent duplicate jobs using `dedupeKey`. If a job with the same key exists, it returns the existing job instead of creating a new one.
+
+```typescript
+await scheduler.schedule({
+  name: "email",
+  data: { userId: 123 },
+  dedupeKey: "email:user:123",
+});
+```
+
+## Job Cancellation
+
+```typescript
+// Cancel a pending or running job
+await scheduler.cancel(jobId);
+```
+
+## Job Querying
+
+```typescript
+const job = await scheduler.getJob(jobId);
+```
+
+## Bulk Scheduling
+
+For high-performance ingestion, use `scheduleBulk` to insert multiple jobs in a single database operation:
+
+```typescript
+const jobs = await scheduler.scheduleBulk([
+  { name: "email", data: { userId: 1 } },
+  { name: "email", data: { userId: 2 } },
+]);
+```
+
+## Events
+
+The scheduler emits typed events for lifecycle monitoring.
+
+```typescript
+// Scheduler events
+scheduler.on("scheduler:start", () => console.log("Scheduler started"));
+scheduler.on("scheduler:stop", () => console.log("Scheduler stopped"));
+scheduler.on("scheduler:error", (err) =>
+  console.error("Scheduler error:", err)
+);
+
+// Worker events
+scheduler.on("worker:start", (workerId) =>
+  console.log("Worker started:", workerId)
+);
+scheduler.on("worker:stop", (workerId) =>
+  console.log("Worker stopped:", workerId)
+);
+
+// Job events
+scheduler.on("job:created", (job) => console.log("Job created:", job._id));
+scheduler.on("job:start", (job) => console.log("Job processing:", job._id));
+scheduler.on("job:success", (job) => console.log("Job done:", job._id));
+scheduler.on("job:fail", ({ job, error }) =>
+  console.error("Job failed:", job._id, error)
+);
+scheduler.on("job:retry", (job) =>
+  console.warn("Job retrying:", job._id, job.attempts)
+);
+scheduler.on("job:cancel", (job) => console.log("Job cancelled:", job._id));
+```
+
 ## Documentation
 
 See `ARCHITECTURE.md` for:
@@ -78,6 +170,14 @@ See `ARCHITECTURE.md` for:
 - sharding strategy
 - production checklist
 
+## Graceful Shutdown
+
+Stop the scheduler and wait for in-flight jobs to complete:
+
+```typescript
+await scheduler.stop({ graceful: true, timeoutMs: 30000 });
+```
+
 ## Status
 
 **Early-stage but production-tested.**

package/dist/core/scheduler.d.ts

@@ -25,8 +25,23 @@ export declare class Scheduler {
     constructor(options?: SchedulerOptions);
     on<K extends keyof SchedulerEventMap>(event: K, listener: (payload: SchedulerEventMap[K]) => void): this;
     schedule<T = unknown>(options: ScheduleOptions<T>): Promise<Job<T>>;
+    /**
+     * Schedule multiple jobs in bulk
+     */
+    scheduleBulk<T = any>(optionsList: ScheduleOptions<T>[]): Promise<Job<T>[]>;
+    /**
+     * Get a job by ID
+     */
+    getJob(jobId: unknown): Promise<Job | null>;
+    /**
+     * Cancel a job
+     */
+    cancel(jobId: unknown): Promise<void>;
     start(): Promise<void>;
-    stop(): Promise<void>;
+    stop(options?: {
+        graceful?: boolean;
+        timeoutMs?: number;
+    }): Promise<void>;
     isRunning(): boolean;
     getId(): string;
 }

package/dist/core/scheduler.js

@@ -46,12 +46,68 @@ class Scheduler {
             nextRunAt,
             retry: options.retry,
             repeat: options.repeat,
+            dedupeKey: options.dedupeKey,
             createdAt: now,
             updatedAt: now,
         };
         const created = await this.store.create(job);
+        this.emitter.emitSafe("job:created", created);
         return created;
     }
+    /**
+     * Schedule multiple jobs in bulk
+     */
+    async scheduleBulk(optionsList) {
+        if (!this.store) {
+            throw new Error("Scheduler not started or no store configured");
+        }
+        const jobs = optionsList.map((options) => {
+            if (!options.name) {
+                throw new Error("Job name is required");
+            }
+            if (options.repeat?.cron && options.repeat.every) {
+                throw new Error("Cannot specify both cron and every");
+            }
+            return {
+                name: options.name,
+                data: options.data,
+                status: "pending",
+                nextRunAt: options.runAt ?? new Date(),
+                repeat: options.repeat,
+                retry: options.retry,
+                dedupeKey: options.dedupeKey,
+            };
+        });
+        const createdJobs = await this.store.createBulk(jobs);
+        // Emit events for all created jobs
+        for (const job of createdJobs) {
+            this.emitter.emitSafe("job:created", job);
+        }
+        return createdJobs;
+    }
+    /**
+     * Get a job by ID
+     */
+    async getJob(jobId) {
+        if (!this.store) {
+            throw new Error("Scheduler has no JobStore configured");
+        }
+        return this.store.findById(jobId);
+    }
+    /**
+     * Cancel a job
+     */
+    async cancel(jobId) {
+        if (!this.store) {
+            throw new Error("Scheduler has no JobStore configured");
+        }
+        const job = await this.store.findById(jobId);
+        await this.store.cancel(jobId);
+        if (job) {
+            const cancelledJob = { ...job, status: "cancelled" };
+            this.emitter.emitSafe("job:cancel", cancelledJob);
+        }
+    }
     async start() {
         if (this.started)
             return;
@@ -81,13 +137,11 @@ class Scheduler {
             await worker.start();
         }
     }
-    async stop() {
+    async stop(options) {
         if (!this.started)
             return;
         this.started = false;
-        for (const worker of this.workers) {
-            await worker.stop();
-        }
+        await Promise.all(this.workers.map((w) => w.stop(options)));
         this.workers.length = 0;
         this.emitter.emitSafe("scheduler:stop", undefined);
     }

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

@@ -5,6 +5,7 @@ export declare class InMemoryJobStore implements JobStore {
     private mutex;
     private generateId;
     create(job: Job): Promise<Job>;
+    createBulk(jobs: Job[]): Promise<Job[]>;
     findAndLockNext({ now, workerId, lockTimeoutMs, }: {
         now: Date;
         workerId: string;
@@ -20,4 +21,6 @@ export declare class InMemoryJobStore implements JobStore {
         lockTimeoutMs: number;
     }): Promise<number>;
     cancel(jobId: unknown): Promise<void>;
+    findById(jobId: unknown): Promise<Job | null>;
+    renewLock(jobId: unknown, workerId: string): Promise<void>;
 }

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

@@ -12,6 +12,13 @@ class InMemoryJobStore {
         return Math.random().toString(36).slice(2);
     }
     async create(job) {
+        if (job.dedupeKey) {
+            for (const existing of this.jobs.values()) {
+                if (existing.dedupeKey === job.dedupeKey) {
+                    return existing;
+                }
+            }
+        }
         const id = this.generateId();
         const stored = {
             ...job,
@@ -22,6 +29,9 @@ class InMemoryJobStore {
         this.jobs.set(id, stored);
         return stored;
     }
+    async createBulk(jobs) {
+        return Promise.all(jobs.map((job) => this.create(job)));
+    }
     async findAndLockNext({ now, workerId, lockTimeoutMs, }) {
         const release = await this.mutex.acquire();
         try {
@@ -102,6 +112,24 @@ class InMemoryJobStore {
             throw new store_errors_1.JobNotFoundError();
         job.status = "cancelled";
         job.updatedAt = new Date();
+        job.lockedAt = undefined;
+        job.lockedBy = undefined;
+    }
+    async findById(jobId) {
+        const job = this.jobs.get(String(jobId));
+        return job ? { ...job } : null;
+    }
+    async renewLock(jobId, workerId) {
+        const job = this.jobs.get(String(jobId));
+        if (!job)
+            throw new store_errors_1.JobNotFoundError();
+        if (job.status === "running" && job.lockedBy === workerId) {
+            job.lockedAt = new Date();
+            job.updatedAt = new Date();
+        }
+        else {
+            throw new Error("Job lock lost or owner changed");
+        }
     }
 }
 exports.InMemoryJobStore = InMemoryJobStore;

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

@@ -4,6 +4,10 @@ export interface JobStore {
      * Insert a new job
      */
     create(job: Job): Promise<Job>;
+    /**
+     * Create multiple jobs in bulk
+     */
+    createBulk(jobs: Job[]): Promise<Job[]>;
     /**
      * Find and lock the next runnable job.
      * Must be atomic.
@@ -39,4 +43,12 @@ export interface JobStore {
      * Cancel job explicitly
      */
     cancel(jobId: unknown): Promise<void>;
+    /**
+     * Get job by ID
+     */
+    findById(jobId: unknown): Promise<Job | null>;
+    /**
+     * Renew the lock for a running job (heartbeat)
+     */
+    renewLock(jobId: unknown, workerId: string): Promise<void>;
 }

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

@@ -10,6 +10,7 @@ export declare class MongoJobStore implements JobStore {
     private readonly defaultLockTimeoutMs;
     constructor(db: Db, options?: MongoJobStoreOptions);
     create(job: Job): Promise<Job>;
+    createBulk(jobs: Job[]): Promise<Job[]>;
     findAndLockNext(options: {
         now: Date;
         workerId: string;
@@ -22,8 +23,10 @@ export declare class MongoJobStore implements JobStore {
         lastError?: string;
     }): Promise<void>;
     cancel(id: ObjectId): Promise<void>;
+    findById(id: ObjectId): Promise<Job | null>;
     recoverStaleJobs(options: {
         now: Date;
         lockTimeoutMs: number;
     }): Promise<number>;
+    renewLock(id: ObjectId, workerId: string): Promise<void>;
 }

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

@@ -20,9 +20,35 @@ class MongoJobStore {
             createdAt: now,
             updatedAt: now,
         };
+        if (job.dedupeKey) {
+            // Idempotent insert
+            const result = await this.collection.findOneAndUpdate({ dedupeKey: job.dedupeKey }, { $setOnInsert: doc }, { upsert: true, returnDocument: "after" });
+            return result;
+        }
         const result = await this.collection.insertOne(doc);
         return { ...doc, _id: result.insertedId };
     }
+    async createBulk(jobs) {
+        const now = new Date();
+        const docs = jobs.map((job) => {
+            // IMPORTANT: strip _id completely
+            const { _id, ...jobWithoutId } = job;
+            return {
+                ...jobWithoutId,
+                status: job.status ?? "pending",
+                attempts: job.attempts ?? 0,
+                createdAt: now,
+                updatedAt: now,
+            };
+        });
+        if (docs.length === 0)
+            return [];
+        const result = await this.collection.insertMany(docs);
+        return docs.map((doc, index) => ({
+            ...doc,
+            _id: result.insertedIds[index],
+        }));
+    }
     // --------------------------------------------------
     // ATOMIC FIND & LOCK
     // --------------------------------------------------
@@ -104,7 +130,7 @@ class MongoJobStore {
     async cancel(id) {
         await this.collection.updateOne({ _id: id }, {
             $set: {
-                status: "failed",
+                status: "cancelled",
                 updatedAt: new Date(),
             },
             $unset: {
@@ -113,6 +139,12 @@ class MongoJobStore {
             },
         });
     }
+    async findById(id) {
+        const doc = await this.collection.findOne({ _id: id });
+        if (!doc)
+            return null;
+        return doc;
+    }
     // --------------------------------------------------
     // RECOVER STALE JOBS
     // --------------------------------------------------
@@ -133,5 +165,21 @@ class MongoJobStore {
         });
         return result.modifiedCount;
     }
+    async renewLock(id, workerId) {
+        const now = new Date();
+        const result = await this.collection.updateOne({
+            _id: id,
+            lockedBy: workerId,
+            status: "running",
+        }, {
+            $set: {
+                lockedAt: now,
+                updatedAt: now,
+            },
+        });
+        if (result.matchedCount === 0) {
+            throw new Error("Job lock lost or owner changed");
+        }
+    }
 }
 exports.MongoJobStore = MongoJobStore;

package/dist/types/job.d.ts

@@ -15,6 +15,7 @@ export interface Job<Data = unknown> {
     lastError?: string;
     retry?: RetryOptions;
     repeat?: RepeatOptions;
+    dedupeKey?: string;
     createdAt: Date;
     updatedAt: Date;
 }

package/dist/types/schedule.d.ts

@@ -16,4 +16,8 @@ export interface ScheduleOptions<T = unknown> {
      * Repeat configuration (cron or every)
      */
     repeat?: RepeatOptions;
+    /**
+     * Idempotency key to prevent duplicate jobs
+     */
+    dedupeKey?: string;
 }

package/dist/worker/worker.d.ts

@@ -11,8 +11,12 @@ export declare class Worker {
     private readonly workerId;
     private readonly defaultTimezone?;
     constructor(store: JobStore, emitter: SchedulerEmitter, handler: JobHandler, options?: WorkerOptions);
+    private loopPromise?;
     start(): Promise<void>;
-    stop(): Promise<void>;
+    stop(options?: {
+        graceful?: boolean;
+        timeoutMs?: number;
+    }): Promise<void>;
     private loop;
     private execute;
     private sleep;

package/dist/worker/worker.js

@@ -20,13 +20,27 @@ class Worker {
             return;
         this.running = true;
         this.emitter.emitSafe("worker:start", this.workerId);
-        this.loop().catch((err) => {
+        this.loopPromise = this.loop();
+        this.loopPromise.catch((err) => {
             this.emitter.emitSafe("worker:error", err);
         });
     }
-    async stop() {
+    async stop(options) {
         this.running = false;
         this.emitter.emitSafe("worker:stop", this.workerId);
+        if (options?.graceful && this.loopPromise) {
+            const timeoutMs = options.timeoutMs ?? 30000; // default 30s
+            const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error("Worker stop timed out")), timeoutMs));
+            try {
+                await Promise.race([this.loopPromise, timeout]);
+            }
+            catch (err) {
+                if (err instanceof Error && err.message === "Worker stop timed out") {
+                    return;
+                }
+                throw err;
+            }
+        }
     }
     async loop() {
         while (this.running) {
@@ -66,7 +80,37 @@ class Worker {
             job.lastScheduledAt = next;
             await this.store.reschedule(job._id, next);
         }
+        // ---------------------------
+        // HEARTBEAT
+        // ---------------------------
+        const heartbeatIntervalMs = Math.max(50, this.lockTimeout / 2);
+        const heartbeatParams = {
+            jobId: job._id,
+            workerId: this.workerId,
+        };
+        let stopHeartbeat = false;
+        const heartbeatLoop = async () => {
+            while (!stopHeartbeat) {
+                await this.sleep(heartbeatIntervalMs);
+                if (stopHeartbeat)
+                    break;
+                try {
+                    await this.store.renewLock(heartbeatParams.jobId, heartbeatParams.workerId);
+                }
+                catch (err) {
+                    this.emitter.emitSafe("worker:error", new Error(`Heartbeat failed for job ${heartbeatParams.jobId}: ${err}`));
+                    break;
+                }
+            }
+        };
+        const heartbeatPromise = heartbeatLoop();
         try {
+            const current = await this.store.findById(job._id);
+            if (current && current.status === "cancelled") {
+                this.emitter.emitSafe("job:complete", job);
+                stopHeartbeat = true; // stop fast
+                return;
+            }
             await this.handler(job);
             // ---------------------------
             // INTERVAL: schedule AFTER execution
@@ -93,10 +137,14 @@ class Worker {
                     attempts,
                     lastError: error.message,
                 });
-                return;
             }
-            await this.store.markFailed(job._id, error.message);
-            this.emitter.emitSafe("job:fail", { job, error });
+            else {
+                await this.store.markFailed(job._id, error.message);
+                this.emitter.emitSafe("job:fail", { job, error });
+            }
+        }
+        finally {
+            stopHeartbeat = true;
         }
     }
     sleep(ms) {

package/package.json

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