スケジューラー

Zeltは指定した間隔またはcron式でタスクを実行するための宣言的スケジューリングデコレータを提供します。

概要

スケジューラーAPIは以下で構成されます：

• @Scheduled — クラスをスケジューラーとしてマークするクラスデコレータ
• @Cron(expression) — 特定のcron式で実行
• @Daily({ hour, minute? }) — 1日1回実行
• @Hourly({ minute? }) — 1時間1回実行
• @Weekly({ day, hour, minute? }) — 週1回実行
• @Every({ minutes | seconds }) — 固定間隔で実行

基本的な使い方

スケジューラーの作成

import { Scheduled, Cron, Daily, Hourly } from '@zeltjs/core';

@Scheduled()
class ReportScheduler {
  @Daily({ hour: 9 })
  async sendDailyReport() {
    console.log('Sending daily report...');
  }

  @Hourly()
  async checkHealth() {
    console.log('Health check...');
  }
}

スケジューラーの登録

createHttpApp()にスケジューラークラスを渡します：

import { createHttpApp } from '@zeltjs/core';

const app = createHttpApp({
  controllers: [UserController],
  schedulers: [ReportScheduler],
});

スケジューラーの開始

startScheduler()を呼び出してスケジュールされたタスクの実行を開始：

app.startScheduler();

スケジューラーを正常に停止するには：

await app.stopScheduler();

デコレータリファレンス

@Cron

特定のcron式で実行：

@Scheduled()
class BackupScheduler {
  @Cron('0 2 * * *')
  async runBackup() {
    // 毎日午前2時に実行
  }

  @Cron('*/5 * * * *')
  async quickCheck() {
    // 5分ごとに実行
  }
}

タイムゾーン指定：

@Cron('0 9 * * *', { tz: 'Asia/Tokyo' })
async morningTask() {
  // 日本時間午前9時に実行
}

@Daily

指定した時間に1日1回実行：

@Scheduled()
class DailyTasks {
  @Daily({ hour: 6 })
  async earlyMorning() {
    // 午前6時に実行
  }

  @Daily({ hour: 23, minute: 30 })
  async lateNight() {
    // 午後11時30分に実行
  }

  @Daily({ hour: 9, tz: 'America/New_York' })
  async newYorkMorning() {
    // EST/EDT午前9時に実行
  }
}

@Hourly

1時間に1回実行：

@Scheduled()
class HourlyTasks {
  @Hourly()
  async everyHour() {
    // 毎時0分に実行
  }

  @Hourly({ minute: 30 })
  async halfPast() {
    // 毎時30分に実行
  }
}

@Weekly

週1回実行：

@Scheduled()
class WeeklyTasks {
  @Weekly({ day: 'monday', hour: 9 })
  async mondayMeeting() {
    // 毎週月曜日午前9時に実行
  }

  @Weekly({ day: 'friday', hour: 17, minute: 30 })
  async weeklyReport() {
    // 毎週金曜日午後5時30分に実行
  }
}

使用可能な曜日: 'sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'

@Every

固定間隔で実行：

@Scheduled()
class PollingTasks {
  @Every({ minutes: 5 })
  async pollApi() {
    // 5分ごとに実行
  }

  @Every({ seconds: 30 })
  async frequentCheck() {
    // 30秒ごとに実行
  }
}

依存性注入

スケジューラーはコントローラーと同様に依存性注入をサポート：

import { Scheduled, Daily, inject } from '@zeltjs/core';

@Scheduled()
class NotificationScheduler {
  constructor(
    private emailService = inject(EmailService),
    private userRepo = inject(UserRepository),
  ) {}

  @Daily({ hour: 8 })
  async sendReminders() {
    const users = await this.userRepo.findWithPendingReminders();
    for (const user of users) {
      await this.emailService.send(user.email, 'Reminder', '...');
    }
  }
}

Node.jsエントリーポイント

Node.jsアプリケーションでは、エントリーポイントでスケジューラーを開始：

import { listen } from '@zeltjs/adapter-node';
import { app } from './app';

listen(app, { port: 3000 });
app.startScheduler();

process.on('SIGTERM', async () => {
  await app.stopScheduler();
  process.exit(0);
});

Cron式フォーマット

Zeltはオプションの秒を含む標準cron形式を使用：

┌──────────── 秒（オプション、0-59）
│ ┌────────── 分（0-59）
│ │ ┌──────── 時（0-23）
│ │ │ ┌────── 日（1-31）
│ │ │ │ ┌──── 月（1-12）
│ │ │ │ │ ┌── 曜日（0-6、日曜日=0）
│ │ │ │ │ │
* * * * * *

一般的なパターン：

パターン	説明
* * * * *	毎分
0 * * * *	毎時
0 0 * * *	毎日深夜
0 9 * * 1	毎週月曜日午前9時
*/15 * * * *	15分ごと
0 0 1 * *	毎月1日