MonqueOptions

Defined in: packages/core/src/scheduler/types.ts:17

Configuration options for the Monque scheduler.

Example

const monque = new Monque(db, {
  collectionName: 'jobs',
  pollInterval: 1000,
  maxRetries: 10,
  baseRetryInterval: 1000,
  shutdownTimeout: 30000,
  workerConcurrency: 5,      // Per-worker default
  instanceConcurrency: 20,   // Global instance limit
});

Properties

baseRetryInterval?

optional baseRetryInterval?: number;

Defined in: packages/core/src/scheduler/types.ts:38

Base interval in milliseconds for exponential backoff calculation. Actual delay = 2^failCount * baseRetryInterval

Default

1000

---

collectionName?

optional collectionName?: string;

Defined in: packages/core/src/scheduler/types.ts:22

Name of the MongoDB collection for storing jobs.

Default

'monque_jobs'

---

defaultConcurrency?

optional defaultConcurrency?: number;

Defined in: packages/core/src/scheduler/types.ts:67

Default number of concurrent jobs per worker.

Deprecated

Use workerConcurrency instead. Will be removed in a future major version.

Default

5

---

heartbeatInterval?

optional heartbeatInterval?: number;

Defined in: packages/core/src/scheduler/types.ts:99

Interval in milliseconds for heartbeat updates during job processing. The scheduler periodically updates lastHeartbeat for all jobs it is processing to indicate liveness for monitoring/debugging.

With leaseDuration, each heartbeat also extends the claim’s lease. Otherwise, recovery uses lockedAt + lockTimeout, not lastHeartbeat.

Default

30000 (30 seconds)

---

instanceConcurrency?

optional instanceConcurrency?: number;

Defined in: packages/core/src/scheduler/types.ts:155

Maximum number of concurrent jobs processed by this instance across all registered workers.

If reached, the scheduler will stop claiming new jobs until active jobs complete. Use this to prevent a single instance from overwhelming system resources.

Note: This is an instance-level limit. Each worker still respects its own concurrency setting, but the total across all workers cannot exceed this limit.

Example

const monque = new Monque(db, {
  instanceConcurrency: 10, // Instance processes max 10 jobs total
  workerConcurrency: 5,    // Each worker defaults to 5 concurrent jobs
});

// With 3 workers at concurrency 5, normally 15 jobs could run.
// With instanceConcurrency: 10, only 10 jobs run at any time.

---

jobRetention?

optional jobRetention?: object;

Defined in: packages/core/src/scheduler/types.ts:111

Configuration for automatic cleanup of completed, failed, and cancelled jobs. If undefined, no cleanup is performed.

cancelled?

optional cancelled?: number;

Age in milliseconds after which cancelled jobs are deleted. Based on ‘updatedAt’. Omit to retain cancelled jobs indefinitely.

completed?

optional completed?: number;

Age in milliseconds after which completed jobs are deleted. Cleaned up based on ‘updatedAt’ timestamp.

failed?

optional failed?: number;

Age in milliseconds after which failed jobs are deleted. Cleaned up based on ‘updatedAt’ timestamp.

interval?

optional interval?: number;

Interval in milliseconds for running the cleanup job.

Default

3600000 (1 hour)

---

leaseDuration?

optional leaseDuration?: number;

Defined in: packages/core/src/scheduler/types.ts:82

Opt into renewable claims and periodic stale recovery, in milliseconds. Must exceed heartbeatInterval. Upgrade all schedulers sharing the collection before enabling this option. Omit to keep absolute lockTimeout behavior.

---

lockTimeout?

optional lockTimeout?: number;

Defined in: packages/core/src/scheduler/types.ts:76

Maximum time in milliseconds a job can be in ‘processing’ status before being considered stale and eligible for recovery.

Applies to claims without a renewable lease. This is an absolute time locked limit based on lockedAt, not a heartbeat timeout.

Default

1800000 (30 minutes)

---

maxBackoffDelay?

optional maxBackoffDelay?: number;

Defined in: packages/core/src/scheduler/types.ts:46

Maximum delay in milliseconds for exponential backoff. If calculated delay exceeds this value, it will be capped.

Defaults to 24 hours to prevent unbounded delays.

Default

86400000 (24 hours)

---

maxConcurrency?

optional maxConcurrency?: number;

Defined in: packages/core/src/scheduler/types.ts:161

Maximum number of concurrent jobs processed by this instance across all registered workers.

Deprecated

Use instanceConcurrency instead. Will be removed in a future major version.

---

maxPayloadSize?

optional maxPayloadSize?: number;

Defined in: packages/core/src/scheduler/types.ts:181

Maximum allowed BSON byte size for job data payloads.

When set, enqueue(), enqueueMany(), now(), and schedule() validate the payload size using BSON.calculateObjectSize() before insertion. Jobs exceeding this limit throw PayloadTooLargeError.

When undefined, no size validation occurs.

---

maxRetries?

optional maxRetries?: number;

Defined in: packages/core/src/scheduler/types.ts:32

Maximum number of retry attempts before marking a job as permanently failed.

Default

10

---

pollInterval?

optional pollInterval?: number;

Defined in: packages/core/src/scheduler/types.ts:27

Interval in milliseconds between polling for new jobs.

Default

1000

---

recoverStaleJobs?

optional recoverStaleJobs?: boolean;

Defined in: packages/core/src/scheduler/types.ts:106

Whether to recover stale processing jobs on startup and, with leaseDuration, after each heartbeat. Expired leases and unleased claims older than lockTimeout are reset to pending.

Default

true

---

safetyPollInterval?

optional safetyPollInterval?: number;

Defined in: packages/core/src/scheduler/types.ts:205

Interval in milliseconds between safety polls when change streams are active.

When change streams are connected, the scheduler uses them as the primary notification mechanism and only polls at this longer interval as a safety net to catch any missed events. When change streams are unavailable, the scheduler falls back to the standard pollInterval.

This is separate from heartbeatInterval, which updates job liveness signals.

Default

30000 (30 seconds)

---

schedulerInstanceId?

optional schedulerInstanceId?: string;

Defined in: packages/core/src/scheduler/types.ts:89

Unique identifier for this scheduler instance. Used for atomic job claiming - each instance uses this ID to claim jobs. Defaults to a randomly generated UUID v4.

Default

crypto.randomUUID()

---

shutdownTimeout?

optional shutdownTimeout?: number;

Defined in: packages/core/src/scheduler/types.ts:51

Timeout in milliseconds for graceful shutdown.

Default

30000

---

skipIndexCreation?

optional skipIndexCreation?: boolean;

Defined in: packages/core/src/scheduler/types.ts:171

Skip automatic index creation during initialization.

When true, initialize() will not create MongoDB indexes. Use this in production environments where indexes are managed externally (e.g., via migration scripts or DBA tooling). See the production checklist for the full list of required indexes.

Default

false

---

statsCacheTtlMs?

optional statsCacheTtlMs?: number;

Defined in: packages/core/src/scheduler/types.ts:192

TTL in milliseconds for getQueueStats() and getQueueViewSummaries() counts.

When set to a positive value, repeated getQueueStats() calls with the same filter return cached results instead of re-executing the aggregation pipeline. Each unique filter (job name) maintains its own cache entry.

Set to 0 to disable cached snapshots. Concurrent reads still share one query.

Default

5000

---

workerConcurrency?

optional workerConcurrency?: number;

Defined in: packages/core/src/scheduler/types.ts:60

Default number of concurrent jobs per worker.

This is the per-worker concurrency limit applied when a worker is registered without specifying its own concurrency option.

Default

5