Packages

@xtaskjs/scheduler

Cron, interval, and timeout decorators with lifecycle-managed job discovery and control.

npm install @xtaskjs/scheduler node-cron reflect-metadata Package path: packages/scheduler

Overview

What this package owns in the runtime

Scheduler adds recurring and delayed jobs to xtask services. It discovers decorated methods after the DI container is ready, runs boot jobs during initialization, starts recurring work on lifecycle ready, and exposes service APIs for inspection and manual execution.

What it provides

Cron(), Every(), Interval(), and Timeout() decorators declare scheduled jobs on services.
Supports runOnBoot, runOnInit, named groups, retries, and per-job retry or error hooks.
SchedulerService lists jobs and groups, and can start, stop, or run them manually.
Tracks runtime state such as run counts, failures, and the last execution error.

How it fits

Discovered automatically during CreateApplication() after the container has registered providers.
Starts recurring jobs on lifecycle ready and stops active handles during app.close().
Demonstrated by the 11-scheduler_app sample with inspection endpoints and maintenance groups.

Usage Chart

How strongly this package shapes the runtime

Bootstrap

4/5

Dependency Injection

4/5

Scheduling

5/5

Operations

5/5

Integrations

4/5

Package Flow

How this package moves through xtaskjs runtime phases

Before startup

Decorate service methods with Cron, Every, Interval, or Timeout so the scheduler can discover jobs from the DI container.

During CreateApplication()

Scheduler discovery runs after the container is ready, wiring jobs into lifecycle phases and enabling boot-time execution or grouped control.

During app.close()

Recurring timers and cron handles are stopped automatically so background work does not outlive the application process.

API Surface

Representative exports from the upstream package

Scheduling decorators

Cron
Every
Interval
Timeout

Runtime control

SchedulerService
InjectSchedulerService

Lifecycle surface

InjectSchedulerLifecycleManager
initializeSchedulerIntegration
shutdownSchedulerIntegration

Usage

Typical adoption flow

1. Decorate job methods

Choose Cron for calendar schedules, Every or Interval for repeated delays, and Timeout for one-shot post-startup work.

2. Organize jobs with options

Use names, groups, retries, timezone overrides, and runOnBoot or runOnInit to reflect operational intent in code.

3. Inspect and trigger jobs at runtime

Inject SchedulerService when operators or diagnostics endpoints need to list jobs, run one immediately, or rerun a whole group.

Example

Reference snippet

Scheduled jobs with grouped execution

import { Service } from "@xtaskjs/core";
import { Cron, InjectSchedulerService, SchedulerService, Timeout } from "@xtaskjs/scheduler";

@Service()
export class ReportsScheduler {
  constructor(
    @InjectSchedulerService()
    private readonly scheduler: SchedulerService
  ) {}

  @Cron("0 */5 * * * *", { name: "reports.flush", group: "reports", runOnBoot: true })
  flushReports() {
    console.log("flush pending reports");
  }

  @Timeout("30s", { name: "reports.warmup" })
  warmup() {
    console.log("warm cache once after startup");
  }

  async rerunReports() {
    await this.scheduler.runGroup("reports");
  }
}

Samples

Official samples to inspect next

Reference samples: 11-scheduler_app