⏰cron-and-intervals
- プラグイン
- valtown
- ソース
- GitHub で見る ↗
説明
次のような場合に使用: スケジュールで実行するvalを構築する場合 — 定期ジョブ、繰り返しタスク、ポーリング、cronジョブ、監視、アラート通知。 インターバルハンドラーのシグネチャ、cron式、UTCタイムゾーン制約、および前回の実行以降の新規アイテムを検出するための `lastRunAt` パターンについて説明します。
原文を表示
Use when building a val that runs on a schedule — periodic jobs, recurring tasks, polling, cron jobs, monitoring, alerting. Covers the interval handler signature, cron expressions, the UTC timezone constraint, and the `lastRunAt` pattern for detecting new items since the previous run.
ユースケース
- ✓定期ジョブを実行するとき
- ✓繰り返しタスクをスケジュール化するとき
- ✓ポーリングを自動実行するとき
- ✓cronジョブを構築するとき
- ✓監視やアラート通知を設定するとき
本文（日本語訳）
Cron / インターバル Val
インターバル val（fileType: "interval"）は、cron 式で定義された定期スケジュールに従って実行されます。
外部 API のポーリング、リマインダーの送信、クリーンアップ処理、レポート生成など、
リクエストへの応答ではなくタイマーベースで行うべき処理に使用します。
基本ハンドラー
// 詳細: https://docs.val.town/vals/cron/
export default async function (interval: Interval) {
// interval.lastRunAt: Date | undefined
console.log(interval);
}
ファイルには必ず export が必要です — ハンドラーには export default を使用します。
タイムゾーン
Cron 式は UTC で実行されます。 人間が読みやすい形式のスケジュール（例：「東部時間の午前9時」）は、 cron 式を書く前に UTC に変換してください。 サマータイム（夏時間）は考慮されないため、年間を通じて許容できる UTC 時刻を選択してください。
lastRunAt パターン
interval.lastRunAt は直前の正常実行時のタイムスタンプです（初回実行時は undefined）。
全件を再スキャンする代わりに、直前の実行以降に作成されたアイテムだけを取得するために活用できます:
export default async function (interval: Interval) {
const since = interval.lastRunAt ?? new Date(Date.now() - 24 * 60 * 60 * 1000);
const newItems = await fetchItemsSince(since);
for (const item of newItems) {
await handle(item);
}
}
このパターンにより、実行が抜けた場合でも冪等性が保たれ、 同じデータの二重処理を防ぐことができます。
スケジュールの読み取りと更新
read_interval_settings— インターバルファイルの現在の cron 式と有効状態を取得します。write_interval_settings— cron 式の変更、またはインターバルの一時停止・再開を行います。
テンプレートを使わない場合
シンプルなスケジュールジョブであれば、interval タイプのファイルを1つ持つ新しい val を
直接作成すれば十分です — テンプレートは不要です。
テンプレートは、ダッシュボード・AI agent・Webhook と UI の組み合わせなど、
より複雑な構成に向いています。
変更の確認
インターバル val を編集した後は、次回のスケジュール実行を待たずに、
run_file を使ってハンドラーを手動で呼び出して動作確認を行いましょう。
原文（English）を表示
Cron / Interval Vals
Interval vals (fileType: "interval") run on a recurring schedule defined by a cron expression. Use them for polling external APIs, sending reminders, running cleanups, generating reports, or any work that should happen on a clock rather than in response to a request.
Basic handler
// Learn more: https://docs.val.town/vals/cron/
export default async function (interval: Interval) {
// interval.lastRunAt: Date | undefined
console.log(interval);
}
The file must have an export — export default for the handler.
Timezone
Cron expressions run in UTC. Convert any human-readable schedule (e.g. "9am Eastern") to UTC before writing the cron expression. Daylight savings is not handled — pick a UTC time that's close enough year-round.
The lastRunAt pattern
interval.lastRunAt is the timestamp of the previous successful run (or undefined on the first run). Use it to fetch only items created since the last run, instead of re-scanning everything:
export default async function (interval: Interval) {
const since = interval.lastRunAt ?? new Date(Date.now() - 24 * 60 * 60 * 1000);
const newItems = await fetchItemsSince(since);
for (const item of newItems) {
await handle(item);
}
}
This makes the val idempotent against missed runs and avoids reprocessing.
Reading and updating the schedule
read_interval_settings— fetch the current cron expression and active state of an interval file.write_interval_settings— change the cron expression or pause/resume an interval.
When to skip a template
For simple scheduled jobs, create a new val with a single interval-type file directly — no template needed. Templates are for more complex shapes (dashboards, AI agents, webhook + UI combos).
Verifying changes
After editing an interval val, use run_file to invoke the handler manually instead of waiting for the next scheduled run.
原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。