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:41

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:74

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:102

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.

Note: stale recovery is based on lockedAt + lockTimeout, not lastHeartbeat.

Default

30000 (30 seconds)

---

instanceConcurrency?

optional instanceConcurrency?: number;

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

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:115

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

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)

---

lockTimeout?

optional lockTimeout?: number;

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

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

Stale recovery uses lockedAt as the source of truth; this is an absolute “time locked” limit, not a heartbeat timeout.

Default

1800000 (30 minutes)

---

maxBackoffDelay?

optional maxBackoffDelay?: number;

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

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:164

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:186

Maximum allowed BSON byte size for job data payloads.

When set, enqueue(), 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:34

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:28

Interval in milliseconds between polling for new jobs.

Default

1000

---

recoverStaleJobs?

optional recoverStaleJobs?: boolean;

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

Whether to recover stale processing jobs on scheduler startup. When true, jobs with lockedAt older than lockTimeout will be reset to pending.

Default

true

---

safetyPollInterval?

optional safetyPollInterval?: number;

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

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:92

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:56

Timeout in milliseconds for graceful shutdown.

Default

30000

---

skipIndexCreation?

optional skipIndexCreation?: boolean;

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

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:198

TTL in milliseconds for getQueueStats() result caching.

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 caching entirely.

Default

5000

---

workerConcurrency?

optional workerConcurrency?: number;

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

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