Agendador de tarefas TypeScript: cron, temporizadores e…

Agendador de tarefas em TypeScript: guia completo

Um agendador de tarefas (task scheduler) é uma ferramenta que permite executar funções ou scripts em um horário específico ou com uma periodicidade definida. No ecossistema TypeScript, existem várias bibliotecas maduras para implementar esses cenários: desde temporizadores simples até poderosos sistemas cron. Neste artigo, vamos explorar as principais abordagens e mostrar como usá-las em projetos reais.

Por que preciso de um agendador de tarefas?

A automação de ações repetitivas é uma tarefa essencial para qualquer aplicação de servidor. Cenários típicos:

Envio de notificações por email a cada hora.
Limpeza de arquivos temporários todas as noites.
Coleta de análises no final do dia.
Atualização de cache conforme agendamento.

Em TypeScript (e JavaScript), existe um mecanismo básico embutido — setInterval e setTimeout, mas para agendamentos complexos, é mais conveniente usar bibliotecas especializadas.

Ferramentas embutidas: setInterval e setTimeout

A maneira mais simples é usar funções globais:

// Exemplo: executar a cada 5 segundosconst intervalId = setInterval(() => {  console.log('Tarefa executada em', new Date().toISOString());}, 5000);

// Parar após 30 segundossetTimeout(() => {  clearInterval(intervalId);  console.log('Agendador parado');}, 30000);

Prós: não requer instalação, funciona em qualquer ambiente. Contras: não suporta expressões cron, difícil gerenciar tarefas perdidas.

Biblioteca node-cron

Uma das bibliotecas mais populares para Node.js. Funciona com o formato cron clássico (5 campos): minutos, horas, dia do mês, mês, dia da semana.

Instalação

npm install node-cronnpm install @types/node-cron

Exemplo de uso

import * as cron from 'node-cron';

// Tarefa: a cada minutocron.schedule('* * * * *', () => {  console.log('Executando a cada minuto');});

// Tarefa: todos os dias às 9:30 da manhãcron.schedule('30 9 * * *', () => {  console.log('Tarefa diária às 9:30');});

// Tarefa: dias úteis às 18:00cron.schedule('0 18 * * 1-5', () => {  console.log('Dias úteis às 18:00');});

Gerenciamento de tarefas

import * as cron from 'node-cron';

const task = cron.schedule('*/5 * * * *', () => {  console.log('A cada 5 minutos');});

// Parar a tarefatask.stop();

// Retomartask.start();

// Verificar statusconsole.log(task.isActive()); // true ou false

Biblioteca croner

Uma alternativa mais moderna, escrita em TypeScript do zero. Suporta sintaxe estendida (segundos, nomes de meses) e funciona tanto no Node.js quanto no navegador.

Instalação

npm install croner

Exemplo com segundos

import Cron from 'croner';

// A cada 10 segundosconst job = new Cron('*/10 * * * * *', () => {  console.log('Executando a cada 10 segundos');});

// Tarefa: toda segunda-feira às 8:30 da manhãconst weeklyJob = new Cron('30 8 * * 1', () => {  console.log('Segunda-feira, 8:30');});

// Parar após 1 minutosetTimeout(() => {  job.stop();  console.log('Tarefa parada');}, 60000);

Recursos avançados

import Cron from 'croner';

// Tarefa com nome e fuso horárioconst job = new Cron('0 9 * * *', {   name: 'morning-report',  timezone: 'Europe/Moscow'}, () => {  console.log('Relatório matinal de Moscou');});

// Obter próximo horário de execuçãoconst nextRun = job.nextRun();console.log('Próxima execução:', nextRun.toISOString());

// Lista de todas as tarefas ativasconst activeJobs = Cron.getJobs();console.log('Tarefas ativas:', activeJobs.length);