src — scheduler

Module: src-scheduler Cohesion: 0.80 Members: 0

src — scheduler

The src/scheduler module provides robust and flexible mechanisms for managing and executing asynchronous operations within the application. It encapsulates two distinct scheduling systems, each tailored for different use cases:

  1. Scheduler: An in-memory, priority-based task scheduler designed for managing immediate or short-term tasks with fine-grained control over concurrency, dependencies, and retries.
  2. CronScheduler: A persistent, event-driven job scheduler capable of handling long-running, recurring tasks defined by at, every, or standard cron expressions, with built-in persistence and error handling.

This module is crucial for automating background processes, managing user-defined scheduled actions, and ensuring efficient resource utilization for various asynchronous workloads.

1. Core Concepts

Before diving into the specifics of each scheduler, it's helpful to understand some common terminology:

2. Scheduler (In-Memory Task Scheduler)

The Scheduler class (src/scheduler/scheduler.ts) provides a powerful, in-memory task management system. It's ideal for orchestrating internal application logic where tasks need to be prioritized, executed concurrently, or depend on the completion of other tasks.

2.1. Purpose and Use Cases

The Scheduler is designed for:

Since it's an in-memory scheduler, tasks are not persisted across application restarts.

2.2. Key Features

2.3. Architecture and Execution Flow

The Scheduler operates on a periodic "tick" mechanism.

  1. Initialization: When start() is called, it sets up a tickTimer and an optional agingTimer.
  2. Tick Cycle (tick()):

  1. Task Execution (executeTask()):

  1. Priority Aging (applyPriorityAging()):

graph TD
    A[Scheduler.start()] --> B(tickTimer interval)
    B --> C{Scheduler.tick()}
    C --> D{getRunningCount() < maxConcurrent?}
    D -- Yes --> E{getNextTask()}
    E -- Task found --> F[executeTask(task)]
    F --> G{Task handler execution}
    G -- Success --> H[task:completed]
    G -- Failure --> I[task:retry / task:failed]
    H --> J[Update task status]
    I --> J
    E -- No task --> C
    D -- No --> C
    B --> K(agingTimer interval)
    K --> L[applyPriorityAging()]

2.4. API Overview

The Scheduler class exposes a comprehensive API for task management:

2.5. Configuration (SchedulerConfig)

The Scheduler is configured via the SchedulerConfig interface, with DEFAULT_SCHEDULER_CONFIG providing sensible defaults: 

export interface SchedulerConfig {
  maxConcurrent: number; class="hl-cmt">// Max tasks running simultaneously
  defaultPriority: TaskPriority;
  defaultTimeout: number; class="hl-cmt">// Default task timeout in ms
  defaultMaxRetries: number;
  tickInterval: number; class="hl-cmt">// How often the scheduler checks for new tasks in ms
  enablePriorityAging: boolean;
  agingRate: number; class="hl-cmt">// How much priority increases per aging interval
  agingInterval: number; class="hl-cmt">// How often priority aging is applied in ms
}

2.6. Events (EventEmitter)

The Scheduler extends EventEmitter and emits various events throughout the task lifecycle, allowing external components to react to task state changes:

3. CronScheduler (Persistent Job Scheduler)

The CronScheduler class (src/scheduler/cron-scheduler.ts) provides a robust, persistent, and event-driven system for managing scheduled jobs. It's Advanced enterprise architecture for scheduling system and is designed for long-running, recurring operations that need to survive application restarts.

3.1. Purpose and Use Cases

The CronScheduler is designed for:

3.2. Key Features

3.3. Architecture and Execution Flow

The CronScheduler manages jobs through a combination of file persistence, internal timers, and a periodic tick.

  1. Initialization (constructor, start()):

  1. Job Management (addJob, updateJob, removeJob):

  1. Scheduling (scheduleJob, calculateNextRun):

  1. Tick Cycle (tick()):

  1. Job Execution (executeJob()):

  1. Persistence (loadJobs, persistJobs, saveRunHistory, pruneRunHistory):

graph TD
    A[CronScheduler.start()] --> B(Load Jobs from Disk)
    B --> C(Schedule all active jobs)
    C --> D(tickTimer interval)
    D --> E{CronScheduler.tick()}
    E --> F{For each job in jobs:}
    F --> G{Is job due? (nextRunAt <= now)}
    G -- Yes --> H[executeJob(job)]
    H --> I(Update job state, persist, save history)
    I --> J{Calculate nextRunAt}
    J --> F
    G -- No --> F
    H -- Error --> K[Apply backoff, update nextRetryAt]
    K --> I

3.4. API Overview

The CronScheduler class provides methods for managing jobs and their lifecycle:

3.5. Configuration (CronSchedulerConfig)

The CronScheduler is configured via the CronSchedulerConfig interface, with DEFAULT_CRON_SCHEDULER_CONFIG providing sensible defaults: 

export interface CronSchedulerConfig {
  persistPath: string; class="hl-cmt">// Path to jobs.json
  historyPath: string; class="hl-cmt">// Directory for job run history files
  maxHistoryPerJob: number; class="hl-cmt">// Max entries in a job&#39;s history file
  tickIntervalMs: number; class="hl-cmt">// How often the scheduler checks for due cron jobs
  defaultTimezone: string; class="hl-cmt">// Default IANA timezone for cron expressions
}

3.6. Events (EventEmitter)

The CronScheduler extends EventEmitter and emits events related to job lifecycle and execution:

3.7. Cron Parser

The cron-scheduler.ts file includes internal functions (parseCronExpression, parseField, getNextCronTime) to handle 5-field cron expressions. These functions parse the cron string into a structured CronFields object and then calculate the next matching date and time.

4. Singleton Access

Both Scheduler and CronScheduler provide singleton access patterns to ensure a single, globally managed instance of each scheduler type. This is crucial for maintaining consistent state across the application.

5. Types (src/scheduler/types.ts)

The src/scheduler/types.ts file defines common interfaces and types used by the Scheduler class, ensuring type safety and clarity:

The src/scheduler/cron-scheduler.ts file defines its own specific types for CronJob, JobRun, CronSchedulerConfig, and CronSchedulerEvents.

6. Connections to the Rest of the Codebase

CronScheduler Integrations:

Scheduler Integrations: