Back to Details

cron-and-intervals

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cron / Interval Vals

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.
Interval val（
fileType: "interval"
）按照 cron 表达式定义的重复计划运行。适用于轮询外部 API、发送提醒、执行清理、生成报告，或任何应按时间执行而非响应请求的工作。

Basic handler

基本 handler

ts
// 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.
ts
// Learn more: https://docs.val.town/vals/cron/
export default async function (interval: Interval) {
  // interval.lastRunAt: Date | undefined
  console.log(interval);
}
文件必须包含 
export
——handler 使用 
export default
。

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.
Cron 表达式以 UTC 运行。 编写 cron 表达式之前，将任何以人类可读方式表达的日程（例如 "9am Eastern"）转换为 UTC。系统不处理夏令时——请选择一个全年都足够接近的 UTC 时间。

The 
lastRunAt
pattern

lastRunAt
模式

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:
ts
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.
interval.lastRunAt
是上一次成功运行的时间戳（首次运行时为 
undefined
）。利用它可以只获取自上次运行以来创建的项，而不必重新扫描所有内容：
ts
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);
  }
}
这样即使错过某次运行，也能让 val 保持幂等，并避免重复处理。

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.
  • read_interval_settings
    ——获取 interval 文件当前的 cron 表达式和启用状态。
  • write_interval_settings
    ——修改 cron 表达式或暂停/恢复 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).
对于简单的定时作业，直接创建一个仅包含单个 
interval
类型文件的新 val 即可，无需使用模板。模板适用于更复杂的形态（仪表盘、AI agent、webhook + UI 组合）。

Verifying changes

验证更改

After editing an interval val, use 
run_file
to invoke the handler manually instead of waiting for the next scheduled run.
编辑 interval val 后，使用 
run_file
手动调用 handler，而不必等待下一次计划运行。