mongo-job-scheduler 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Darshan Bhut
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# Mongo Job Scheduler
+
+A production-grade MongoDB-backed job scheduler for Node.js.
+
+Designed for distributed systems that need:
+
+- reliable background jobs
+- retries with backoff
+- cron & interval scheduling
+- crash recovery
+- MongoDB sharding safety
+
+---
+
+## Features
+
+- **Distributed locking** using MongoDB
+- **Multiple workers** support
+- **Retry with backoff**
+- **Cron jobs** (timezone-aware, non-drifting)
+- **Interval jobs**
+- **Resume on restart**
+- **Stale lock recovery**
+- **Sharding-safe design**
+
+---
+
+## Install
+
+```bash
+npm install mongo-job-scheduler
+```
+
+## Basic Usage
+
+```typescript
+import { Scheduler, MongoJobStore } from "mongo-job-scheduler";
+import { MongoClient } from "mongodb";
+
+// ... connect to mongo ...
+const client = new MongoClient("mongodb://localhost:27017");
+await client.connect();
+const db = client.db("my-app");
+
+const scheduler = new Scheduler({
+  store: new MongoJobStore(db),
+  handler: async (job) => {
+    console.log("Running job:", job.name);
+  },
+  workers: 3, // default is 1
+});
+
+await scheduler.start();
+```
+
+## Cron with Timezone
+
+```typescript
+await scheduler.schedule({
+  name: "daily-report",
+  repeat: {
+    cron: "0 9 * * *",
+    timezone: "Asia/Kolkata", // default is UTC
+  },
+});
+```
+
+## Documentation
+
+See `ARCHITECTURE.md` for:
+
+- job lifecycle
+- retry & repeat semantics
+- MongoDB indexes
+- sharding strategy
+- production checklist
+
+## Status
+
+**Early-stage but production-tested.**
+API may evolve before 1.0.0.

package/dist/core/scheduler.d.ts

@@ -0,0 +1,30 @@
+import { SchedulerEventMap } from "../types/events";
+import { JobStore } from "../store";
+import { Job } from "../types/job";
+export interface SchedulerOptions {
+    id?: string;
+    store?: JobStore;
+    handler?: (job: Job) => Promise<void>;
+    workers?: number;
+    pollIntervalMs?: number;
+    lockTimeoutMs?: number;
+    defaultTimezone?: string;
+}
+export declare class Scheduler {
+    private readonly emitter;
+    private readonly workers;
+    private started;
+    private readonly id;
+    private readonly store?;
+    private readonly handler?;
+    private readonly workerCount;
+    private readonly pollInterval;
+    private readonly lockTimeout;
+    private readonly defaultTimezone?;
+    constructor(options?: SchedulerOptions);
+    on<K extends keyof SchedulerEventMap>(event: K, listener: (payload: SchedulerEventMap[K]) => void): this;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    isRunning(): boolean;
+    getId(): string;
+}

package/dist/core/scheduler.js

@@ -0,0 +1,65 @@
+import { SchedulerEmitter } from "../events";
+import { Worker } from "../worker";
+export class Scheduler {
+    constructor(options = {}) {
+        this.emitter = new SchedulerEmitter();
+        this.workers = [];
+        this.started = false;
+        this.id = options.id ?? `scheduler-${Math.random().toString(36).slice(2)}`;
+        this.store = options.store;
+        this.handler = options.handler;
+        this.workerCount = options.workers ?? 1;
+        this.pollInterval = options.pollIntervalMs ?? 500;
+        this.lockTimeout = options.lockTimeoutMs ?? 30000;
+        this.defaultTimezone = options.defaultTimezone;
+    }
+    on(event, listener) {
+        this.emitter.on(event, listener);
+        return this;
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.emitter.emitSafe("scheduler:start", undefined);
+        if (this.store && typeof this.store.recoverStaleJobs === "function") {
+            await this.store.recoverStaleJobs({
+                now: new Date(),
+                lockTimeoutMs: this.lockTimeout,
+            });
+        }
+        // lifecycle-only mode (used by tests)
+        if (!this.store || !this.handler) {
+            return;
+        }
+        // -------------------------------
+        // start workers
+        // -------------------------------
+        for (let i = 0; i < this.workerCount; i++) {
+            const worker = new Worker(this.store, this.emitter, this.handler, {
+                pollIntervalMs: this.pollInterval,
+                lockTimeoutMs: this.lockTimeout,
+                workerId: `${this.id}-w${i}`,
+                defaultTimezone: this.defaultTimezone,
+            });
+            this.workers.push(worker);
+            await worker.start();
+        }
+    }
+    async stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        for (const worker of this.workers) {
+            await worker.stop();
+        }
+        this.workers.length = 0;
+        this.emitter.emitSafe("scheduler:stop", undefined);
+    }
+    isRunning() {
+        return this.started;
+    }
+    getId() {
+        return this.id;
+    }
+}

package/dist/events/emitter.d.ts

@@ -0,0 +1,5 @@
+import { TypedEventEmitter } from "./typed-emitter";
+import { SchedulerEventMap } from "../types/events";
+export declare class SchedulerEmitter extends TypedEventEmitter<SchedulerEventMap> {
+    emitSafe<K extends keyof SchedulerEventMap>(event: K, payload: SchedulerEventMap[K]): void;
+}

package/dist/events/emitter.js

@@ -0,0 +1,17 @@
+import { TypedEventEmitter } from "./typed-emitter";
+export class SchedulerEmitter extends TypedEventEmitter {
+    emitSafe(event, payload) {
+        try {
+            this.emitUnsafe(event, payload);
+        }
+        catch (err) {
+            // never allow listener failure to crash core
+            try {
+                this.emitUnsafe("scheduler:error", err);
+            }
+            catch {
+                // absolute last guard
+            }
+        }
+    }
+}

package/dist/events/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./emitter";
+export * from "./typed-emitter";

package/dist/events/index.js

@@ -0,0 +1,2 @@
+export * from "./emitter";
+export * from "./typed-emitter";

package/dist/events/typed-emitter.d.ts

@@ -0,0 +1,8 @@
+export type EventMap = Record<string, any>;
+export declare class TypedEventEmitter<T extends EventMap> {
+    private emitter;
+    on<K extends keyof T>(event: K, listener: (payload: T[K]) => void): this;
+    once<K extends keyof T>(event: K, listener: (payload: T[K]) => void): this;
+    off<K extends keyof T>(event: K, listener: (payload: T[K]) => void): this;
+    protected emitUnsafe<K extends keyof T>(event: K, payload: T[K]): void;
+}

package/dist/events/typed-emitter.js

@@ -0,0 +1,21 @@
+import { EventEmitter } from "events";
+export class TypedEventEmitter {
+    constructor() {
+        this.emitter = new EventEmitter();
+    }
+    on(event, listener) {
+        this.emitter.on(event, listener);
+        return this;
+    }
+    once(event, listener) {
+        this.emitter.once(event, listener);
+        return this;
+    }
+    off(event, listener) {
+        this.emitter.off(event, listener);
+        return this;
+    }
+    emitUnsafe(event, payload) {
+        this.emitter.emit(event, payload);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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";

package/dist/index.js

@@ -0,0 +1,6 @@
+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";

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

@@ -0,0 +1,23 @@
+import { Job } from "../types/job";
+import { JobStore } from "./job-store";
+export declare class InMemoryJobStore implements JobStore {
+    private jobs;
+    private mutex;
+    private generateId;
+    create(job: Job): Promise<Job>;
+    findAndLockNext({ now, workerId, lockTimeoutMs, }: {
+        now: Date;
+        workerId: string;
+        lockTimeoutMs: number;
+    }): Promise<Job | null>;
+    markCompleted(jobId: unknown): Promise<void>;
+    markFailed(jobId: unknown, error: string): Promise<void>;
+    reschedule(jobId: unknown, nextRunAt: Date, updates?: {
+        attempts?: number;
+    }): Promise<void>;
+    recoverStaleJobs({ now, lockTimeoutMs, }: {
+        now: Date;
+        lockTimeoutMs: number;
+    }): Promise<number>;
+    cancel(jobId: unknown): Promise<void>;
+}

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

@@ -0,0 +1,103 @@
+import { JobNotFoundError } from "./store-errors";
+import { Mutex } from "./mutex";
+export class InMemoryJobStore {
+    constructor() {
+        this.jobs = new Map();
+        this.mutex = new Mutex();
+    }
+    generateId() {
+        return Math.random().toString(36).slice(2);
+    }
+    async create(job) {
+        const id = this.generateId();
+        const stored = {
+            ...job,
+            _id: id,
+            createdAt: job.createdAt ?? new Date(),
+            updatedAt: job.updatedAt ?? new Date(),
+        };
+        this.jobs.set(id, stored);
+        return stored;
+    }
+    async findAndLockNext({ now, workerId, lockTimeoutMs, }) {
+        const release = await this.mutex.acquire();
+        try {
+            for (const job of this.jobs.values()) {
+                if (job.status !== "pending")
+                    continue;
+                if (job.nextRunAt > now)
+                    continue;
+                // lock expired?
+                if (job.lockedAt &&
+                    now.getTime() - job.lockedAt.getTime() < lockTimeoutMs) {
+                    continue;
+                }
+                job.status = "running";
+                job.lockedAt = now;
+                job.lockedBy = workerId;
+                job.updatedAt = new Date();
+                job.lastRunAt = now;
+                return { ...job };
+            }
+            return null;
+        }
+        finally {
+            release();
+        }
+    }
+    async markCompleted(jobId) {
+        const job = this.jobs.get(String(jobId));
+        if (!job)
+            throw new JobNotFoundError();
+        job.status = "completed";
+        job.lastRunAt = new Date();
+        job.updatedAt = new Date();
+    }
+    async markFailed(jobId, error) {
+        const job = this.jobs.get(String(jobId));
+        if (!job)
+            throw new JobNotFoundError();
+        job.status = "failed";
+        job.lastError = error;
+        job.updatedAt = new Date();
+    }
+    async reschedule(jobId, nextRunAt, updates) {
+        const job = this.jobs.get(String(jobId));
+        if (!job)
+            throw new JobNotFoundError();
+        job.status = "pending";
+        job.nextRunAt = nextRunAt;
+        if (updates?.attempts != null) {
+            job.attempts = updates.attempts;
+        }
+        else {
+            job.attempts = (job.attempts ?? 0) + 1;
+        }
+        job.lockedAt = undefined;
+        job.lockedBy = undefined;
+        job.updatedAt = new Date();
+        job.lastScheduledAt = nextRunAt;
+    }
+    async recoverStaleJobs({ now, lockTimeoutMs, }) {
+        let recovered = 0;
+        for (const job of this.jobs.values()) {
+            if (job.status === "running" &&
+                job.lockedAt &&
+                now.getTime() - job.lockedAt.getTime() > lockTimeoutMs) {
+                job.status = "pending";
+                job.lockedAt = undefined;
+                job.lockedBy = undefined;
+                job.updatedAt = new Date();
+                recovered++;
+            }
+        }
+        return recovered;
+    }
+    async cancel(jobId) {
+        const job = this.jobs.get(String(jobId));
+        if (!job)
+            throw new JobNotFoundError();
+        job.status = "cancelled";
+        job.updatedAt = new Date();
+    }
+}

package/dist/store/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./job-store";
+export * from "./store-errors";
+export * from "./in-memory-job-store";

package/dist/store/index.js

@@ -0,0 +1,3 @@
+export * from "./job-store";
+export * from "./store-errors";
+export * from "./in-memory-job-store";

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

@@ -0,0 +1,42 @@
+import { Job } from "../types/job";
+export interface JobStore {
+    /**
+     * Insert a new job
+     */
+    create(job: Job): Promise<Job>;
+    /**
+     * Find and lock the next runnable job.
+     * Must be atomic.
+     */
+    findAndLockNext(options: {
+        now: Date;
+        workerId: string;
+        lockTimeoutMs: number;
+    }): Promise<Job | null>;
+    /**
+     * Mark job as completed
+     */
+    markCompleted(jobId: unknown): Promise<void>;
+    /**
+     * Mark job as failed
+     */
+    markFailed(jobId: unknown, error: string): Promise<void>;
+    /**
+     * Reschedule job (used for retry or repeat)
+     */
+    reschedule(jobId: unknown, nextRunAt: Date, updates?: {
+        attempts?: number;
+        lastError?: string;
+    }): Promise<void>;
+    /**
+     * Recover jobs stuck in running state
+     */
+    recoverStaleJobs(options: {
+        now: Date;
+        lockTimeoutMs: number;
+    }): Promise<number>;
+    /**
+     * Cancel job explicitly
+     */
+    cancel(jobId: unknown): Promise<void>;
+}

package/dist/store/job-store.js

@@ -0,0 +1 @@
+export {};

package/dist/store/mongo/connect.d.ts

@@ -0,0 +1,6 @@
+import { Db } from "mongodb";
+export interface MongoConnectionOptions {
+    uri: string;
+    dbName: string;
+}
+export declare function connectMongo(options: MongoConnectionOptions): Promise<Db>;

package/dist/store/mongo/connect.js

@@ -0,0 +1,6 @@
+import { MongoClient } from "mongodb";
+export async function connectMongo(options) {
+    const client = new MongoClient(options.uri);
+    await client.connect();
+    return client.db(options.dbName);
+}

package/dist/store/mongo/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./mongo-job-store";
+export * from "./connect";

package/dist/store/mongo/index.js

@@ -0,0 +1,2 @@
+export * from "./mongo-job-store";
+export * from "./connect";

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

@@ -0,0 +1,29 @@
+import { Db, ObjectId } from "mongodb";
+import { JobStore } from "../job-store";
+import { Job } from "../../types/job";
+export interface MongoJobStoreOptions {
+    collectionName?: string;
+    lockTimeoutMs?: number;
+}
+export declare class MongoJobStore implements JobStore {
+    private readonly collection;
+    private readonly defaultLockTimeoutMs;
+    constructor(db: Db, options?: MongoJobStoreOptions);
+    create(job: Job): Promise<Job>;
+    findAndLockNext(options: {
+        now: Date;
+        workerId: string;
+        lockTimeoutMs: number;
+    }): Promise<Job | null>;
+    markCompleted(id: ObjectId): Promise<void>;
+    markFailed(id: ObjectId, error: string): Promise<void>;
+    reschedule(id: ObjectId, nextRunAt: Date, updates?: {
+        attempts?: number;
+        lastError?: string;
+    }): Promise<void>;
+    cancel(id: ObjectId): Promise<void>;
+    recoverStaleJobs(options: {
+        now: Date;
+        lockTimeoutMs: number;
+    }): Promise<number>;
+}

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

@@ -0,0 +1,133 @@
+export class MongoJobStore {
+    constructor(db, options = {}) {
+        this.collection = db.collection(options.collectionName ?? "scheduler_jobs");
+        this.defaultLockTimeoutMs = options.lockTimeoutMs ?? 30000;
+    }
+    // --------------------------------------------------
+    // CREATE
+    // --------------------------------------------------
+    async create(job) {
+        const now = new Date();
+        // IMPORTANT: strip _id completely
+        const { _id, ...jobWithoutId } = job;
+        const doc = {
+            ...jobWithoutId,
+            status: job.status ?? "pending",
+            attempts: job.attempts ?? 0,
+            createdAt: now,
+            updatedAt: now,
+        };
+        const result = await this.collection.insertOne(doc);
+        return { ...doc, _id: result.insertedId };
+    }
+    // --------------------------------------------------
+    // ATOMIC FIND & LOCK
+    // --------------------------------------------------
+    async findAndLockNext(options) {
+        const { now, workerId, lockTimeoutMs } = options;
+        const lockExpiry = new Date(now.getTime() - lockTimeoutMs);
+        const result = await this.collection.findOneAndUpdate({
+            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;
+    }
+    // --------------------------------------------------
+    // MARK COMPLETED
+    // --------------------------------------------------
+    async markCompleted(id) {
+        await this.collection.updateOne({ _id: id }, {
+            $set: {
+                status: "completed",
+                updatedAt: new Date(),
+            },
+            $unset: {
+                lockedAt: "",
+                lockedBy: "",
+            },
+        });
+    }
+    // --------------------------------------------------
+    // MARK FAILED
+    // --------------------------------------------------
+    async markFailed(id, error) {
+        await this.collection.updateOne({ _id: id }, {
+            $set: {
+                status: "failed",
+                lastError: error,
+                updatedAt: new Date(),
+            },
+            $unset: {
+                lockedAt: "",
+                lockedBy: "",
+            },
+        });
+    }
+    // --------------------------------------------------
+    // RESCHEDULE
+    // --------------------------------------------------
+    async reschedule(id, nextRunAt, updates) {
+        await this.collection.updateOne({ _id: id }, {
+            $set: {
+                status: "pending",
+                nextRunAt,
+                updatedAt: new Date(),
+                ...(updates ?? {}),
+            },
+            $unset: {
+                lockedAt: "",
+                lockedBy: "",
+            },
+        });
+    }
+    // --------------------------------------------------
+    // CANCEL
+    // --------------------------------------------------
+    async cancel(id) {
+        await this.collection.updateOne({ _id: id }, {
+            $set: {
+                status: "failed",
+                updatedAt: new Date(),
+            },
+            $unset: {
+                lockedAt: "",
+                lockedBy: "",
+            },
+        });
+    }
+    // --------------------------------------------------
+    // RECOVER STALE JOBS
+    // --------------------------------------------------
+    async recoverStaleJobs(options) {
+        const { now, lockTimeoutMs } = options;
+        const expiry = new Date(now.getTime() - lockTimeoutMs);
+        const result = await this.collection.updateMany({
+            lockedAt: { $lte: expiry },
+        }, {
+            $set: {
+                status: "pending",
+                updatedAt: now,
+            },
+            $unset: {
+                lockedAt: "",
+                lockedBy: "",
+            },
+        });
+        return result.modifiedCount;
+    }
+}

package/dist/store/mutex.d.ts

@@ -0,0 +1,5 @@
+export declare class Mutex {
+    private locked;
+    private waiting;
+    acquire(): Promise<() => void>;
+}

package/dist/store/mutex.js

@@ -0,0 +1,24 @@
+export class Mutex {
+    constructor() {
+        this.locked = false;
+        this.waiting = [];
+    }
+    async acquire() {
+        return new Promise((resolve) => {
+            const release = () => {
+                const next = this.waiting.shift();
+                if (next)
+                    next();
+                else
+                    this.locked = false;
+            };
+            if (!this.locked) {
+                this.locked = true;
+                resolve(release);
+            }
+            else {
+                this.waiting.push(() => resolve(release));
+            }
+        });
+    }
+}

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

@@ -0,0 +1,6 @@
+export declare class JobNotFoundError extends Error {
+    constructor(message?: string);
+}
+export declare class JobLockError extends Error {
+    constructor(message?: string);
+}

package/dist/store/store-errors.js

@@ -0,0 +1,12 @@
+export class JobNotFoundError extends Error {
+    constructor(message = "Job not found") {
+        super(message);
+        this.name = "JobNotFoundError";
+    }
+}
+export class JobLockError extends Error {
+    constructor(message = "Failed to acquire job lock") {
+        super(message);
+        this.name = "JobLockError";
+    }
+}

package/dist/types/events.d.ts

@@ -0,0 +1,23 @@
+import { Job } from "./job";
+export type SchedulerEventMap = {
+    "scheduler:start": void;
+    "scheduler:stop": void;
+    "scheduler:error": Error;
+    "job:created": Job;
+    "job:queued": Job;
+    "job:start": Job;
+    "job:success": Job;
+    "job:fail": {
+        job: Job;
+        error: Error;
+    };
+    "job:retry": Job;
+    "job:complete": Job;
+    "job:cancel": Job;
+    "resume:start": void;
+    "resume:jobRecovered": Job;
+    "resume:complete": void;
+    "worker:start": string;
+    "worker:stop": string;
+    "worker:error": Error;
+};

package/dist/types/events.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./job";
+export * from "./retry";
+export * from "./repeat";
+export * from "./lifecycle";
+export * from "./events";

package/dist/types/index.js

@@ -0,0 +1,5 @@
+export * from "./job";
+export * from "./retry";
+export * from "./repeat";
+export * from "./lifecycle";
+export * from "./events";

package/dist/types/job.d.ts

@@ -0,0 +1,20 @@
+import { JobStatus } from "./lifecycle";
+import { RetryOptions } from "./retry";
+import { RepeatOptions } from "./repeat";
+export interface Job<Data = unknown> {
+    _id?: unknown;
+    name: string;
+    data: Data;
+    status: JobStatus;
+    nextRunAt: Date;
+    lastRunAt?: Date;
+    lastScheduledAt?: Date;
+    lockedAt?: Date;
+    lockedBy?: string;
+    attempts: number;
+    lastError?: string;
+    retry?: RetryOptions;
+    repeat?: RepeatOptions;
+    createdAt: Date;
+    updatedAt: Date;
+}

package/dist/types/job.js

@@ -0,0 +1 @@
+export {};

package/dist/types/lifecycle.d.ts

@@ -0,0 +1 @@
+export type JobStatus = "pending" | "running" | "completed" | "failed" | "cancelled";

package/dist/types/lifecycle.js

@@ -0,0 +1 @@
+export {};

package/dist/types/repeat.d.ts

@@ -0,0 +1,14 @@
+export interface RepeatOptions {
+    /**
+     * Run every N milliseconds
+     */
+    every?: number;
+    /**
+     * Cron expression (optional)
+     */
+    cron?: string;
+    /**
+     * Timezone for cron
+     */
+    timezone?: string;
+}

package/dist/types/repeat.js

@@ -0,0 +1 @@
+export {};

package/dist/types/retry.d.ts

@@ -0,0 +1,12 @@
+export interface RetryOptions {
+    /**
+     * Total allowed attempts (including first)
+     */
+    maxAttempts: number;
+    /**
+     * Backoff strategy:
+     * - number = fixed delay (ms)
+     * - function = dynamic delay
+     */
+    delay: number | ((attempt: number) => number);
+}

package/dist/types/retry.js

@@ -0,0 +1 @@
+export {};

package/dist/worker/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./worker";
+export * from "./types";

package/dist/worker/index.js

@@ -0,0 +1,2 @@
+export * from "./worker";
+export * from "./types";

package/dist/worker/repeat.d.ts

@@ -0,0 +1,2 @@
+import { RepeatOptions } from "../types/repeat";
+export declare function getNextRunAt(repeat: RepeatOptions, base: Date, defaultTimezone?: string): Date;

package/dist/worker/repeat.js

@@ -0,0 +1,14 @@
+import { parseExpression } from "cron-parser";
+export function getNextRunAt(repeat, base, defaultTimezone) {
+    if (repeat.every != null) {
+        return new Date(base.getTime() + repeat.every);
+    }
+    if (repeat.cron) {
+        const interval = parseExpression(repeat.cron, {
+            currentDate: base,
+            tz: repeat.timezone ?? defaultTimezone ?? "UTC",
+        });
+        return interval.next().toDate();
+    }
+    throw new Error("Invalid repeat configuration");
+}

package/dist/worker/retry.d.ts

@@ -0,0 +1,2 @@
+import { RetryOptions } from "../types/retry";
+export declare function getRetryDelay(retry: RetryOptions, attempt: number): number;

package/dist/worker/retry.js

@@ -0,0 +1,6 @@
+export function getRetryDelay(retry, attempt) {
+    if (typeof retry.delay === "function") {
+        return retry.delay(attempt);
+    }
+    return retry.delay;
+}

package/dist/worker/types.d.ts

@@ -0,0 +1,20 @@
+import { Job } from "../types/job";
+export type JobHandler<T = any> = (job: Job<T>) => Promise<void>;
+export interface WorkerOptions {
+    /**
+     * Interval between polling attempts (ms)
+     */
+    pollIntervalMs?: number;
+    /**
+     * Lock timeout for stale job recovery
+     */
+    lockTimeoutMs?: number;
+    /**
+     * Worker id (used for locking)
+     */
+    workerId?: string;
+    /**
+     * Default timezone for cron scheduling
+     */
+    defaultTimezone?: string;
+}

package/dist/worker/types.js

@@ -0,0 +1 @@
+export {};

package/dist/worker/worker.d.ts

@@ -0,0 +1,19 @@
+import { JobStore } from "../store";
+import { SchedulerEmitter } from "../events";
+import { WorkerOptions, JobHandler } from "./types";
+export declare class Worker {
+    private readonly store;
+    private readonly emitter;
+    private readonly handler;
+    private running;
+    private readonly pollInterval;
+    private readonly lockTimeout;
+    private readonly workerId;
+    private readonly defaultTimezone?;
+    constructor(store: JobStore, emitter: SchedulerEmitter, handler: JobHandler, options?: WorkerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private loop;
+    private execute;
+    private sleep;
+}

package/dist/worker/worker.js

@@ -0,0 +1,102 @@
+import { getRetryDelay } from "./retry";
+import { getNextRunAt } from "./repeat";
+export class Worker {
+    constructor(store, emitter, handler, options = {}) {
+        this.store = store;
+        this.emitter = emitter;
+        this.handler = handler;
+        this.running = false;
+        this.pollInterval = options.pollIntervalMs ?? 500;
+        this.lockTimeout = options.lockTimeoutMs ?? 30000;
+        this.workerId =
+            options.workerId ?? `worker-${Math.random().toString(36).slice(2)}`;
+        this.defaultTimezone = options.defaultTimezone;
+    }
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.emitter.emitSafe("worker:start", this.workerId);
+        this.loop().catch((err) => {
+            this.emitter.emitSafe("worker:error", err);
+        });
+    }
+    async stop() {
+        this.running = false;
+        this.emitter.emitSafe("worker:stop", this.workerId);
+    }
+    async loop() {
+        while (this.running) {
+            // stop requested before poll
+            if (!this.running)
+                break;
+            const job = await this.store.findAndLockNext({
+                now: new Date(),
+                workerId: this.workerId,
+                lockTimeoutMs: this.lockTimeout,
+            });
+            // stop requested after polling
+            if (!this.running)
+                break;
+            if (!job) {
+                await this.sleep(this.pollInterval);
+                continue;
+            }
+            await this.execute(job);
+        }
+    }
+    async execute(job) {
+        this.emitter.emitSafe("job:start", job);
+        const now = Date.now();
+        // ---------------------------
+        // CRON: pre-schedule BEFORE execution
+        // ---------------------------
+        if (job.repeat?.cron) {
+            let base = job.lastScheduledAt ?? job.nextRunAt ?? new Date(now);
+            let next = getNextRunAt(job.repeat, base, this.defaultTimezone);
+            // skip missed cron slots
+            while (next.getTime() <= now) {
+                base = next;
+                next = getNextRunAt(job.repeat, base, this.defaultTimezone);
+            }
+            // persist schedule immediately
+            job.lastScheduledAt = next;
+            await this.store.reschedule(job._id, next);
+        }
+        try {
+            await this.handler(job);
+            // ---------------------------
+            // INTERVAL: schedule AFTER execution
+            // ---------------------------
+            if (job.repeat?.every != null) {
+                const next = new Date(Date.now() + Math.max(job.repeat.every, 100));
+                await this.store.reschedule(job._id, next);
+            }
+            if (!job.repeat) {
+                await this.store.markCompleted(job._id);
+                this.emitter.emitSafe("job:success", job);
+            }
+            this.emitter.emitSafe("job:complete", job);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            const attempts = (job.attempts ?? 0) + 1;
+            const retry = job.retry;
+            if (retry && attempts < retry.maxAttempts) {
+                const nextRunAt = new Date(Date.now() + getRetryDelay(retry, attempts));
+                await this.store.reschedule(job._id, nextRunAt, { attempts });
+                this.emitter.emitSafe("job:retry", {
+                    ...job,
+                    attempts,
+                    lastError: error.message,
+                });
+                return;
+            }
+            await this.store.markFailed(job._id, error.message);
+            this.emitter.emitSafe("job:fail", { job, error });
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "mongo-job-scheduler",
+  "version": "0.1.0",
+  "description": "Production-grade MongoDB-backed job scheduler with retries, cron, timezone support, and crash recovery",
+  "license": "MIT",
+  "author": "Darshan Bhut",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/darshanpatel14/mongo-job-scheduler.git"
+  },
+  "homepage": "https://github.com/darshanpatel14/mongo-job-scheduler#readme",
+  "bugs": {
+    "url": "https://github.com/darshanpatel14/mongo-job-scheduler/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "keywords": [
+    "job-scheduler",
+    "mongodb",
+    "mongo",
+    "cron",
+    "cron-jobs",
+    "background-jobs",
+    "task-scheduler",
+    "distributed-jobs",
+    "queue",
+    "retry",
+    "backoff",
+    "worker",
+    "agenda",
+    "bull",
+    "node-cron",
+    "timezone",
+    "scheduler"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:mongo": "jest tests/mongo",
+    "test:stress": "jest tests/stress",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "cron-parser": "^4.9.0",
+    "mongodb": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}