Planejador de tarefas em TypeScript: guia detalhado sobre a biblioteca node-schedule

Planejador de tarefas TypeScript: automação com node-schedule

No desenvolvimento web moderno, surge frequentemente a necessidade de executar código em um agendamento: enviar notificações, limpar cache, gerar relatórios ou sincronizar dados. Para projetos TypeScript, uma das bibliotecas mais poderosas e flexíveis é a node-schedule. Este é um planejador de tarefas que permite definir execuções únicas ou recorrentes usando expressões cron, datas ou regras arbitrárias.

Instalação e configuração

Para instalar a biblioteca, execute o comando:

npm install node-schedulenpm install @types/node-schedule --save-dev

Após a instalação, você pode importar o módulo no seu arquivo TypeScript:

import * as schedule from 'node-schedule';

Principais recursos do node-schedule

• Agendamento por expressões cron — suporte para máscaras clássicas de 6 campos (segundos, minutos, horas, dia do mês, mês, dia da semana).
• Tarefas únicas — execução de código em um momento específico.
• Regras recorrentes — criação de intervalos personalizados usando o objeto RecurrenceRule.
• Cancelamento de tarefas — possibilidade de interromper a execução de uma tarefa agendada.
• Suporte a fusos horários — execução precisa no fuso horário especificado.

Exemplo 1: Planejador cron simples

Vamos criar uma tarefa que será executada a cada minuto:

import * as schedule from 'node-schedule';

const job = schedule.scheduleJob('*/1 * * * *', () => {  console.log('Tarefa executada:', new Date().toLocaleString());});

// Após 5 minutos, cancelaremos a tarefasetTimeout(() => {  job.cancel();  console.log('Tarefa cancelada');}, 5 * 60 * 1000);

Neste exemplo, a expressão cron '*/1 * * * *' significa "a cada minuto". Observe a ordem dos campos: segundos, minutos, horas, dia do mês, mês, dia da semana.

Exemplo 2: Tarefa com data específica

Você pode agendar a execução para um horário específico no futuro:

import * as schedule from 'node-schedule';

const date = new Date(2025, 11, 31, 23, 59, 0); // 31 de dezembro de 2025, 23:59

const job = schedule.scheduleJob(date, () => {  console.log('Ano Novo chegou!');});

// Verificamos se a tarefa está agendadaconsole.log('Tarefa ativa:', job !== null);

Exemplo 3: Regra recorrente (RecurrenceRule)

Se as expressões cron parecerem complexas, use o objeto RecurrenceRule para criar regras compreensíveis:

import * as schedule from 'node-schedule';

const rule = new schedule.RecurrenceRule();rule.hour = 9;rule.minute = 30;rule.dayOfWeek = [1, 3, 5]; // Segunda, Quarta, Sexta

const job = schedule.scheduleJob(rule, () => {  console.log('Reunião matinal às 9:30 nos dias úteis (Seg, Qua, Sex)');});

// Para cancelar após um mês:setTimeout(() => job.cancel(), 30 * 24 * 60 * 60 * 1000);

Exemplo 4: Tarefa com fuso horário

Se sua aplicação opera em diferentes fusos horários, especifique o fuso:

import * as schedule from 'node-schedule';

const job = schedule.scheduleJob(  { hour: 8, minute: 0, tz: 'Europe/Moscow' },  () => {    console.log('Manhã em Moscou: 8:00');  });

Tratamento de erros e cancelamento de tarefas

Sempre preveja o tratamento de erros dentro do callback para evitar que a aplicação falhe:

import * as schedule from 'node-schedule';

const job = schedule.scheduleJob('*/5 * * * *', async () => {  try {    // Seu código assíncrono    const data = await fetchDataFromAPI();    console.log('Dados obtidos:', data);  } catch (error) {    console.error('Erro no planejador:',