mongo-job-scheduler 0.1.1 → 0.1.3

package/README.md

@@ -23,6 +23,14 @@ Designed for distributed systems that need:
 - **Stale lock recovery**
 - **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 +76,75 @@ await scheduler.schedule(
 );
 ```
 
+## 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 +155,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

@@ -1,8 +1,11 @@
-import { SchedulerEmitter } from "../events";
-import { Worker } from "../worker";
-export class Scheduler {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scheduler = void 0;
+const events_1 = require("../events");
+const worker_1 = require("../worker");
+class Scheduler {
     constructor(options = {}) {
-        this.emitter = new SchedulerEmitter();
+        this.emitter = new events_1.SchedulerEmitter();
         this.workers = [];
         this.started = false;
         this.id = options.id ?? `scheduler-${Math.random().toString(36).slice(2)}`;
@@ -43,12 +46,68 @@ export 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;
@@ -68,7 +127,7 @@ export class Scheduler {
         // start workers
         // -------------------------------
         for (let i = 0; i < this.workerCount; i++) {
-            const worker = new Worker(this.store, this.emitter, this.handler, {
+            const worker = new worker_1.Worker(this.store, this.emitter, this.handler, {
                 pollIntervalMs: this.pollInterval,
                 lockTimeoutMs: this.lockTimeout,
                 workerId: `${this.id}-w${i}`,
@@ -78,13 +137,11 @@ export 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);
     }
@@ -95,3 +152,4 @@ export class Scheduler {
         return this.id;
     }
 }
+exports.Scheduler = Scheduler;

package/dist/events/emitter.js

@@ -1,5 +1,8 @@
-import { TypedEventEmitter } from "./typed-emitter";
-export class SchedulerEmitter extends TypedEventEmitter {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchedulerEmitter = void 0;
+const typed_emitter_1 = require("./typed-emitter");
+class SchedulerEmitter extends typed_emitter_1.TypedEventEmitter {
     emitSafe(event, payload) {
         try {
             this.emitUnsafe(event, payload);
@@ -15,3 +18,4 @@ export class SchedulerEmitter extends TypedEventEmitter {
         }
     }
 }
+exports.SchedulerEmitter = SchedulerEmitter;

package/dist/events/index.js

@@ -1,2 +1,18 @@
-export * from "./emitter";
-export * from "./typed-emitter";
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./emitter"), exports);
+__exportStar(require("./typed-emitter"), exports);

package/dist/events/typed-emitter.js

@@ -1,7 +1,10 @@
-import { EventEmitter } from "events";
-export class TypedEventEmitter {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypedEventEmitter = void 0;
+const events_1 = require("events");
+class TypedEventEmitter {
     constructor() {
-        this.emitter = new EventEmitter();
+        this.emitter = new events_1.EventEmitter();
     }
     on(event, listener) {
         this.emitter.on(event, listener);
@@ -19,3 +22,4 @@ export class TypedEventEmitter {
         this.emitter.emit(event, payload);
     }
 }
+exports.TypedEventEmitter = TypedEventEmitter;

package/dist/index.js

@@ -1,6 +1,26 @@
-export { Scheduler } from "./core/scheduler";
-export { MongoJobStore } from "./store/mongo/mongo-job-store";
-export { InMemoryJobStore } from "./store/in-memory-job-store";
-export * from "./types/job";
-export * from "./types/retry";
-export * from "./types/repeat";
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryJobStore = exports.MongoJobStore = exports.Scheduler = void 0;
+var scheduler_1 = require("./core/scheduler");
+Object.defineProperty(exports, "Scheduler", { enumerable: true, get: function () { return scheduler_1.Scheduler; } });
+var mongo_job_store_1 = require("./store/mongo/mongo-job-store");
+Object.defineProperty(exports, "MongoJobStore", { enumerable: true, get: function () { return mongo_job_store_1.MongoJobStore; } });
+var in_memory_job_store_1 = require("./store/in-memory-job-store");
+Object.defineProperty(exports, "InMemoryJobStore", { enumerable: true, get: function () { return in_memory_job_store_1.InMemoryJobStore; } });
+__exportStar(require("./types/job"), exports);
+__exportStar(require("./types/retry"), exports);
+__exportStar(require("./types/repeat"), exports);

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,5 @@ export declare class InMemoryJobStore implements JobStore {
         lockTimeoutMs: number;
     }): Promise<number>;
     cancel(jobId: unknown): Promise<void>;
+    findById(jobId: unknown): Promise<Job | null>;
 }

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

@@ -1,14 +1,24 @@
-import { JobNotFoundError } from "./store-errors";
-import { Mutex } from "./mutex";
-export class InMemoryJobStore {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryJobStore = void 0;
+const store_errors_1 = require("./store-errors");
+const mutex_1 = require("./mutex");
+class InMemoryJobStore {
     constructor() {
         this.jobs = new Map();
-        this.mutex = new Mutex();
+        this.mutex = new mutex_1.Mutex();
     }
     generateId() {
         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,
@@ -19,6 +29,9 @@ export 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 {
@@ -48,7 +61,7 @@ export class InMemoryJobStore {
     async markCompleted(jobId) {
         const job = this.jobs.get(String(jobId));
         if (!job)
-            throw new JobNotFoundError();
+            throw new store_errors_1.JobNotFoundError();
         job.status = "completed";
         job.lastRunAt = new Date();
         job.updatedAt = new Date();
@@ -56,7 +69,7 @@ export class InMemoryJobStore {
     async markFailed(jobId, error) {
         const job = this.jobs.get(String(jobId));
         if (!job)
-            throw new JobNotFoundError();
+            throw new store_errors_1.JobNotFoundError();
         job.status = "failed";
         job.lastError = error;
         job.updatedAt = new Date();
@@ -64,7 +77,7 @@ export class InMemoryJobStore {
     async reschedule(jobId, nextRunAt, updates) {
         const job = this.jobs.get(String(jobId));
         if (!job)
-            throw new JobNotFoundError();
+            throw new store_errors_1.JobNotFoundError();
         job.status = "pending";
         job.nextRunAt = nextRunAt;
         if (updates?.attempts != null) {
@@ -96,8 +109,15 @@ export class InMemoryJobStore {
     async cancel(jobId) {
         const job = this.jobs.get(String(jobId));
         if (!job)
-            throw new JobNotFoundError();
+            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;
     }
 }
+exports.InMemoryJobStore = InMemoryJobStore;

package/dist/store/index.js

@@ -1,3 +1,19 @@
-export * from "./job-store";
-export * from "./store-errors";
-export * from "./in-memory-job-store";
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./job-store"), exports);
+__exportStar(require("./store-errors"), exports);
+__exportStar(require("./in-memory-job-store"), exports);

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,8 @@ export interface JobStore {
      * Cancel job explicitly
      */
     cancel(jobId: unknown): Promise<void>;
+    /**
+     * Get job by ID
+     */
+    findById(jobId: unknown): Promise<Job | null>;
 }

package/dist/store/job-store.js

@@ -1 +1,2 @@
-export {};
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/store/mongo/connect.js

@@ -1,6 +1,9 @@
-import { MongoClient } from "mongodb";
-export async function connectMongo(options) {
-    const client = new MongoClient(options.uri);
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectMongo = connectMongo;
+const mongodb_1 = require("mongodb");
+async function connectMongo(options) {
+    const client = new mongodb_1.MongoClient(options.uri);
     await client.connect();
     return client.db(options.dbName);
 }

package/dist/store/mongo/index.js

@@ -1,2 +1,18 @@
-export * from "./mongo-job-store";
-export * from "./connect";
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./mongo-job-store"), exports);
+__exportStar(require("./connect"), exports);

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,6 +23,7 @@ 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;

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

@@ -1,4 +1,7 @@
-export class MongoJobStore {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MongoJobStore = void 0;
+class MongoJobStore {
     constructor(db, options = {}) {
         this.collection = db.collection(options.collectionName ?? "scheduler_jobs");
         this.defaultLockTimeoutMs = options.lockTimeoutMs ?? 30000;
@@ -17,9 +20,35 @@ export 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
     // --------------------------------------------------
@@ -101,7 +130,7 @@ export class MongoJobStore {
     async cancel(id) {
         await this.collection.updateOne({ _id: id }, {
             $set: {
-                status: "failed",
+                status: "cancelled",
                 updatedAt: new Date(),
             },
             $unset: {
@@ -110,6 +139,12 @@ export class MongoJobStore {
             },
         });
     }
+    async findById(id) {
+        const doc = await this.collection.findOne({ _id: id });
+        if (!doc)
+            return null;
+        return doc;
+    }
     // --------------------------------------------------
     // RECOVER STALE JOBS
     // --------------------------------------------------
@@ -131,3 +166,4 @@ export class MongoJobStore {
         return result.modifiedCount;
     }
 }
+exports.MongoJobStore = MongoJobStore;

package/dist/store/mutex.js

@@ -1,4 +1,7 @@
-export class Mutex {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Mutex = void 0;
+class Mutex {
     constructor() {
         this.locked = false;
         this.waiting = [];
@@ -22,3 +25,4 @@ export class Mutex {
         });
     }
 }
+exports.Mutex = Mutex;

package/dist/store/store-errors.js

@@ -1,12 +1,17 @@
-export class JobNotFoundError extends Error {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobLockError = exports.JobNotFoundError = void 0;
+class JobNotFoundError extends Error {
     constructor(message = "Job not found") {
         super(message);
         this.name = "JobNotFoundError";
     }
 }
-export class JobLockError extends Error {
+exports.JobNotFoundError = JobNotFoundError;
+class JobLockError extends Error {
     constructor(message = "Failed to acquire job lock") {
         super(message);
         this.name = "JobLockError";
     }
 }
+exports.JobLockError = JobLockError;

package/dist/types/events.js

@@ -1 +1,2 @@
-export {};
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/index.js

@@ -1,6 +1,22 @@
-export * from "./job";
-export * from "./retry";
-export * from "./repeat";
-export * from "./lifecycle";
-export * from "./events";
-export * from "./schedule";
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./job"), exports);
+__exportStar(require("./retry"), exports);
+__exportStar(require("./repeat"), exports);
+__exportStar(require("./lifecycle"), exports);
+__exportStar(require("./events"), exports);
+__exportStar(require("./schedule"), exports);

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/job.js

@@ -1 +1,2 @@
-export {};
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/lifecycle.js

@@ -1 +1,2 @@
-export {};
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/repeat.js

@@ -1 +1,2 @@
-export {};
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/retry.js

@@ -1 +1,2 @@
-export {};
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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/types/schedule.js

@@ -1 +1,2 @@
-export {};
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/worker/index.js

@@ -1,2 +1,18 @@
-export * from "./worker";
-export * from "./types";
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./worker"), exports);
+__exportStar(require("./types"), exports);

package/dist/worker/repeat.js

@@ -1,10 +1,13 @@
-import { parseExpression } from "cron-parser";
-export function getNextRunAt(repeat, base, defaultTimezone) {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNextRunAt = getNextRunAt;
+const cron_parser_1 = require("cron-parser");
+function getNextRunAt(repeat, base, defaultTimezone) {
     if (repeat.every != null) {
         return new Date(base.getTime() + repeat.every);
     }
     if (repeat.cron) {
-        const interval = parseExpression(repeat.cron, {
+        const interval = (0, cron_parser_1.parseExpression)(repeat.cron, {
             currentDate: base,
             tz: repeat.timezone ?? defaultTimezone ?? "UTC",
         });

package/dist/worker/retry.js

@@ -1,4 +1,7 @@
-export function getRetryDelay(retry, attempt) {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRetryDelay = getRetryDelay;
+function getRetryDelay(retry, attempt) {
     if (typeof retry.delay === "function") {
         return retry.delay(attempt);
     }

package/dist/worker/types.js

@@ -1 +1,2 @@
-export {};
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,6 +1,9 @@
-import { getRetryDelay } from "./retry";
-import { getNextRunAt } from "./repeat";
-export class Worker {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Worker = void 0;
+const retry_1 = require("./retry");
+const repeat_1 = require("./repeat");
+class Worker {
     constructor(store, emitter, handler, options = {}) {
         this.store = store;
         this.emitter = emitter;
@@ -17,13 +20,27 @@ export 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) {
@@ -53,17 +70,22 @@ export class Worker {
         // ---------------------------
         if (job.repeat?.cron) {
             let base = job.lastScheduledAt ?? job.nextRunAt ?? new Date(now);
-            let next = getNextRunAt(job.repeat, base, this.defaultTimezone);
+            let next = (0, repeat_1.getNextRunAt)(job.repeat, base, this.defaultTimezone);
             // skip missed cron slots
             while (next.getTime() <= now) {
                 base = next;
-                next = getNextRunAt(job.repeat, base, this.defaultTimezone);
+                next = (0, repeat_1.getNextRunAt)(job.repeat, base, this.defaultTimezone);
             }
             // persist schedule immediately
             job.lastScheduledAt = next;
             await this.store.reschedule(job._id, next);
         }
         try {
+            const current = await this.store.findById(job._id);
+            if (current && current.status === "cancelled") {
+                this.emitter.emitSafe("job:complete", job);
+                return;
+            }
             await this.handler(job);
             // ---------------------------
             // INTERVAL: schedule AFTER execution
@@ -83,7 +105,7 @@ export class Worker {
             const attempts = (job.attempts ?? 0) + 1;
             const retry = job.retry;
             if (retry && attempts < retry.maxAttempts) {
-                const nextRunAt = new Date(Date.now() + getRetryDelay(retry, attempts));
+                const nextRunAt = new Date(Date.now() + (0, retry_1.getRetryDelay)(retry, attempts));
                 await this.store.reschedule(job._id, nextRunAt, { attempts });
                 this.emitter.emitSafe("job:retry", {
                     ...job,
@@ -100,3 +122,4 @@ export class Worker {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }
 }
+exports.Worker = Worker;

package/package.json

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