Configuration

Configure Chronos to match your application's needs with these comprehensive options.

Basic Configuration

Constructor Options

const scheduler = new Chronos({
  name: 'my-scheduler',
  defaultConcurrency: 5,
  maxConcurrency: 20,
  processEvery: '5 seconds',
  db: {
    address: 'mongodb://localhost:27017/jobs',
    collection: 'chronosJobs',
    options: {
      ssl: true,
      authSource: 'admin'
    }
  }
});

Database Configuration

Using Connection String

const scheduler = new Chronos({
  db: { 
    address: 'mongodb://localhost:27017/scheduler',
    collection: 'jobs' // optional, defaults to 'chronosJobs'
  }
});

// Or use the method
scheduler.database('mongodb://localhost:27017/scheduler', 'jobs');

Using Existing MongoDB Connection

import { MongoClient } from 'mongodb';

const client = new MongoClient('mongodb://localhost:27017');
await client.connect();

const scheduler = new Chronos({
  mongo: client.db('scheduler')
});

// Or use the method
scheduler.mongo(client.db('scheduler'), 'jobs');

Connection Options

Pass MongoDB driver options:

const scheduler = new Chronos({
  db: {
    address: 'mongodb://localhost:27017/scheduler',
    options: {
      ssl: true,
      authSource: 'admin',
      retryWrites: true,
      w: 'majority'
    }
  }
});

Processing Configuration

Process Interval

Control how often Chronos checks for new jobs:

// During initialization
const scheduler = new Chronos({
  processEvery: '30 seconds'
});

// Or using method
scheduler.processEvery('1 minute');

Accepts:

• Numbers (milliseconds): 5000
• Human readable strings: '30 seconds', '2 minutes', '1 hour'

Concurrency Limits

Global Concurrency

Maximum jobs running simultaneously across all job types:

const scheduler = new Chronos({
  maxConcurrency: 20 // Default: 20
});

scheduler.maxConcurrency(10);

Default Job Concurrency

Default concurrency for individual job types:

const scheduler = new Chronos({
  defaultConcurrency: 5 // Default: 5
});

scheduler.defaultConcurrency(3);

Lock Configuration

Lock Limits

Control how many jobs can be locked (queued) at once:

const scheduler = new Chronos({
  lockLimit: 100,        // Global lock limit
  defaultLockLimit: 10   // Per-job-type lock limit
});

scheduler.lockLimit(50);
scheduler.defaultLockLimit(5);

Lock Lifetime

How long jobs stay locked before timing out:

const scheduler = new Chronos({
  defaultLockLifetime: 600000 // 10 minutes in ms
});

scheduler.defaultLockLifetime(300000); // 5 minutes

Scheduler Naming

Useful for identifying which instance processed a job:

import os from 'os';

const scheduler = new Chronos({
  name: `${os.hostname()}-${process.pid}`
});

scheduler.name('worker-server-1');

Index Management

Auto-Index Creation

Control whether Chronos creates database indexes:

const scheduler = new Chronos({
  ensureIndex: true // Default: true
});

// Disable auto-indexing
scheduler.disableAutoIndex(true);

Custom Sort Order

Customize job processing order:

const scheduler = new Chronos({
  sort: { 
    nextRunAt: 1,    // Process jobs by scheduled time
    priority: -1     // Then by priority (high to low)
  }
});

Complete Configuration Example

import { Chronos } from 'chronos-jobs';
import os from 'os';

const scheduler = new Chronos({
  // Scheduler identification
  name: `${os.hostname()}-${process.pid}`,
  
  // Processing configuration
  processEvery: '10 seconds',
  maxConcurrency: 15,
  defaultConcurrency: 3,
  
  // Lock configuration
  lockLimit: 200,
  defaultLockLimit: 20,
  defaultLockLifetime: 300000, // 5 minutes
  
  // Job ordering
  sort: { 
    nextRunAt: 1, 
    priority: -1 
  },
  
  // Database configuration
  db: {
    address: process.env.MONGODB_URI,
    collection: 'backgroundJobs',
    options: {
      ssl: process.env.NODE_ENV === 'production',
      retryWrites: true,
      authSource: 'admin'
    }
  },
  
  // Performance
  ensureIndex: true
});

Environment-Based Configuration

Development

const scheduler = new Chronos({
  processEvery: '1 second',    // Fast processing for dev
  maxConcurrency: 5,           // Lower concurrency
  defaultLockLifetime: 30000,  // Shorter locks (30s)
  db: { 
    address: 'mongodb://localhost:27017/scheduler-dev' 
  }
});

Production

const scheduler = new Chronos({
  name: `prod-${os.hostname()}-${process.pid}`,
  processEvery: '5 seconds',
  maxConcurrency: 50,
  defaultConcurrency: 10,
  defaultLockLifetime: 600000, // 10 minutes
  lockLimit: 1000,
  db: {
    address: process.env.MONGODB_URI,
    options: {
      ssl: true,
      retryWrites: true,
      authSource: 'admin',
      readPreference: 'secondaryPreferred'
    }
  }
});

Configuration Methods

All configuration can be done via constructor or methods:

Constructor Pattern

const scheduler = new Chronos({
  maxConcurrency: 10,
  processEvery: '30 seconds'
});

Method Chaining Pattern

const scheduler = new Chronos()
  .database('mongodb://localhost:27017/scheduler')
  .processEvery('30 seconds')
  .maxConcurrency(10)
  .defaultConcurrency(5);

Validation and Defaults

Chronos validates configuration and applies sensible defaults:

// These are the default values
{
  name: undefined,
  processEvery: '5 seconds',
  maxConcurrency: 20,
  defaultConcurrency: 5,
  lockLimit: 0,              // No limit
  defaultLockLimit: 0,       // No limit  
  defaultLockLifetime: 600000, // 10 minutes
  ensureIndex: true,
  sort: { nextRunAt: 1, priority: -1 }
}

Configuration Tips

Performance Tuning

1. Adjust processEvery: Lower values = more responsive but higher DB load
2. Set appropriate concurrency: Higher values = better throughput but more resource usage
3. Use lock limits: Prevent memory issues with large job queues

Reliability

1. Set realistic lock lifetimes: Should exceed your longest job duration
2. Use meaningful names: Helps with debugging and monitoring
3. Enable indexes: Critical for performance with many jobs

Scaling

1. Different configs per environment: Dev vs staging vs production
2. Instance-specific names: Track which server processed jobs
3. Shared database: Multiple instances can share the same job queue