Quick Start

After installing Monque and MongoDB, create a server entrypoint with a worker and an initial job:

import { Monque } from "@monque/core";
import { MongoClient } from "mongodb";

const client = await MongoClient.connect("mongodb://localhost:27017");
const monque = new Monque(client.db("my-app"));

monque.register<{ message: string }>("print-message", async (job) => {
  console.log(job.data.message);
});

monque.on("job:complete", ({ job, duration }) => {
  console.log(`${job.name} completed in ${duration}ms`);
});
monque.on("job:fail", ({ job, error, willRetry }) => {
  console.error(job._id, error.message, { willRetry });
});
monque.on("job:error", ({ error }) => {
  console.error("Scheduler error:", error.message);
});

await monque.initialize();
monque.start();

await monque.now("print-message", { message: "Hello from Monque" });

async function shutdown() {
  await monque.stop();
  await client.close();
}

process.once("SIGINT", shutdown);
process.once("SIGTERM", shutdown);

initialize() creates indexes and prepares the scheduler. start() begins processing. The handler receives the persisted job, including its MongoDB _id and data payload. Replace console.log with the work your application needs to perform.

Worker failures

If a handler throws or returns a rejected promise, Monque applies its retry policy. Successful one-time jobs become completed; jobs that exhaust retries become failed. See Retry & Backoff to configure delays and limits.

Jobs may run more than once after retries or crash recovery. Make workers idempotent: repeating a job should not repeat an unwanted side effect, such as charging an order twice. See Idempotent operations.

Delay a job

await monque.enqueue(
  "print-message",
  { message: "One minute later" },
  {
    runAt: new Date(Date.now() + 60_000),
    uniqueKey: "delayed-message",
  },
);

uniqueKey prevents another pending or processing job with the same name and key from being created. It does not prevent a later job after the earlier one completes or fails.

Schedule recurring work

await monque.schedule(
  "0 * * * *",
  "print-message",
  { message: "Hourly message" },
  { uniqueKey: "hourly-message" },
);

The same registered worker handles recurring jobs. After a successful run, the job returns to pending with the next cron time. See Scheduling for cron expressions, timezone behavior, and cancellation.

Inspect jobs

const page = await monque.getJobSummariesWithCursor({
  filter: { name: "print-message" },
  limit: 20,
});
console.log(page.jobs);

Use Job Management for queries and actions in server code, or add the dashboard to your Express application.

Handle Graceful Shutdown

Call stop() before closing your MongoDB client. It waits for running handlers up to shutdownTimeout. If that limit is reached, jobs remain available for stale recovery.

Set scheduler options in your application’s code:

const monque = new Monque(db, {
  workerConcurrency: 5,
  instanceConcurrency: 20,
  maxRetries: 10,
  shutdownTimeout: 30_000,
});

See MonqueOptions for all options and defaults, and the Production Checklist before deployment.