Deno.cron() é uma API de runtime do Deno para agendar código JavaScript ou TypeScript para rodar em uma programação recorrente, expressa usando sintaxe cron. Ela é distribuída com o próprio Deno, então o mesmo código que roda localmente pode ser implantado sem mudanças.

Deno.cron atualmente é uma API instável. Para usá-la localmente com deno run, ative a flag --unstable-cron (ou adicione "cron" ao array unstable em deno.json).

deno run --unstable-cron main.ts

Referência da API Deno.cron

Definindo um cron job

Deno.cron() recebe um nome legível por humanos, uma programação e uma função handler. O nome identifica o cron job nos logs, a programação determina quando o handler dispara, e todos os horários são em UTC.

Deno.cron("log-a-message", "* * * * *", () => {
  console.log("This runs once a minute.");
});

Uma expressão cron de 5 campos tem um campo por unidade de tempo, separados por espaços:

┌──────────── minute (0-59)
│ ┌────────── hour (0-23)
│ │ ┌──────── day of month (1-31)
│ │ │ ┌────── month (1-12 or JAN-DEC)
│ │ │ │ ┌──── day of week (0-6 or SUN-SAT, where 0 is Sunday)
│ │ │ │ │
* * * * *

Cada campo aceita um valor exato, * (qualquer valor), um intervalo (1-5), uma lista (1,3,5) ou um passo (*/15 para cada décima quinta unidade). Por exemplo, 0 9 * * MON-FRI roda às 09:00 UTC em dias úteis.

A programação pode ser uma expressão cron padrão de 5 campos ou um objeto estruturado:

Deno.cron("hourly-task", { hour: { every: 1 } }, () => {
  console.log("This runs once an hour.");
});

Cron jobs devem ser registrados no nível superior de um módulo, antes de qualquer servidor iniciar. Definições aninhadas dentro de request handlers, condicionais ou callbacks não serão coletadas.

Retries e backoff

Por padrão, invocações de handler que falham não são tentadas novamente. Passe um backoffSchedule (um array de atrasos em milissegundos) para tentar de novo em caso de falha:

Deno.cron(
  "retry-example",
  "* * * * *",
  { backoffSchedule: [1000, 5000, 10000] },
  () => {
    throw new Error("Will be retried up to three times.");
  },
);

Rodando cron jobs em produção

Deno.cron mantém o estado de execução em memória na Deno CLI, o que significa que cada processo mantém seu próprio conjunto independente de cron tasks. Para cargas de trabalho em produção, Deno Deploy é construído sobre essa API de runtime: ele descobre suas definições Deno.cron() no momento do deployment, agenda e invoca essas definições, lida com retries e mostra execuções em um dashboard — então você não precisa manter um processo de longa duração rodando por conta própria.

OpenTelemetry

Quando OpenTelemetry está ativado (OTEL_DENO=true), cada invocação de Deno.cron() produz automaticamente um span OpenTelemetry. Isso permite rastrear a execução do cron junto com o restante do seu código instrumentado:

OTEL_DENO=true deno run --unstable-cron main.ts

Cada invocação cron cria um span nomeado a partir do cron job. O span cobre a duração da função handler, e quaisquer spans criados dentro do handler ficam aninhados abaixo dele como filhos.