mongodb-cron

library1.9.0jsnpmunverified

MongoDB collection as a crontab / job queue. Current stable version is 1.9.0, released under ISC license, actively maintained. It uses the official MongoDB Node.js driver (v6) and atomic MongoDB commands to ensure safe job processing in clustered environments. Key differentiator: simple document-based scheduling using a `sleepUntil` field, with built-in lock and retry mechanisms. TypeScript types included. Note: not to be confused with Agenda or similar libraries.

database devops

npm install mongodb-cron

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGODB-CRON

mongodb-cron

databasejavascriptv1.9.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MongoCron

✓ import { MongoCron } from 'mongodb-cron'

✗ const { MongoCron } = require('mongodb-cron')

ESM default export not available; named import only. TypeScript types are included.

MongoCron

✓ const { MongoCron } = require('mongodb-cron')

✗ const MongoCron = require('mongodb-cron')

CJS require must destructure the named export; default require returns an object with MongoCron property.

Options

✓ import type { Options } from 'mongodb-cron'

✗ import { Options } from 'mongodb-cron'

Options is a TypeScript interface; use `import type` to avoid runtime import.

Connects to MongoDB, creates a cron worker that processes jobs from a collection, inserts a job, and stops after 10 seconds.

import { MongoClient } from 'mongodb'; import { MongoCron } from 'mongodb-cron'; const mongo = await MongoClient.connect('mongodb://localhost:27017'); const db = mongo.db('test'); const collection = db.collection('jobs'); const cron = new MongoCron({ collection, onDocument: async (doc) => { console.log('Processing job:', doc._id); // your job logic here }, onError: async (err) => { console.error('Job error:', err.message); }, }); cron.start(); // Insert a job await collection.insertOne({ sleepUntil: new Date() }); // After 10 seconds, stop setTimeout(() => cron.stop(), 10000);

Debug

Known issues

gotchaThe `collection` option must be a MongoDB Collection instance, not a Db or a string. Passing an invalid type will cause cryptic errors.

fix

Ensure you pass a valid collection object: `db.collection('jobs')`.

affects: >=1.0.0

gotchaThe `onDocument` handler must return a Promise (or be async) because the cron waits for it to resolve before updating the job. If the callback is synchronous, the job lock may not be released correctly.

fix

Always use async functions: `onDocument: async (doc) => { ... }`

affects: >=1.0.0

breakingVersion 2.x (if released) may drop support for MongoDB <6. Currently requires mongodb@^6.1.0 peer.

fix

Keep mongodb-cron at ~1.9.0 if you must use older MongoDB driver versions.

affects: >=2.0.0

deprecatedThe `sleepUntil` field is the only required field for a job; other scheduling fields like `cron` or `interval` are not supported. If you need cron expressions, consider another package.

fix

Use `sleepUntil` with a Date object for one-time or deferred jobs. For recurring jobs, re-insert a new job after completion.

affects: >=1.0.0

gotchaIf `sleepUntil` is set to a past date, the job will be processed immediately on next poll. This is by design but can cause immediate processing if not intended.

fix

Explicitly set `sleepUntil` to a future date or null to avoid immediate processing.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: collection.insert is not a function

Using `.insert()` instead of `.insertOne()` or `.insertMany()`. The MongoDB driver v6 deprecated `.insert()`.

fix

Use `collection.insertOne(doc)` or `collection.insertMany([doc])`.

Error: MongoCron requires a MongoDB collection instance

Passing a `db` object or a string instead of a collection instance.

fix

Ensure you pass `db.collection('yourCollectionName')` to the `collection` option.

ReferenceError: require is not defined

Using CommonJS `require` in an ESM environment without correct configuration.

fix

Use `import { MongoCron } from 'mongodb-cron'` in ESM, or switch to CommonJS (`type: commonjs` in package.json).

Upgrade

Version history

1.9.0latest on npm

Audit

Dependencies

mongodbrequiredPeer dependency: v^6.1.0 required for MongoDB driver operations

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/xpepermint/mongodb-cron ↗

packagemongodb-cron ↗

homepagehttps://github.com/xpepermint/mongodb-cron#readme ↗