Agendador de tarefas em TypeScript: biblioteca node-schedule

Biblioteca node-schedule: agendador de tarefas flexível em TypeScript

No desenvolvimento web moderno, surge frequentemente a necessidade de executar determinadas ações em um horário específico ou de acordo com uma programação. Para o ecossistema Node.js e TypeScript, existem várias soluções, mas o node-schedule se destaca pela sua flexibilidade e simplicidade. Esta biblioteca permite criar tanto tarefas únicas para uma data exata quanto tarefas recorrentes usando expressões cron ou intervalos legíveis por humanos.

Principais recursos do node-schedule

• Horário de execução preciso – iniciar uma tarefa em um momento específico (data + hora)
• Expressões cron – sintaxe clássica para tarefas periódicas (a cada minuto, a cada hora, etc.)
• Regras recorrentes – configuração flexível de repetições usando o objeto RecurrenceRule
• Cancelamento e pausa – gerenciamento de tarefas ativas
• Suporte a fusos horários – trabalho com horário local

Instalação e configuração

Para começar, instale o pacote via npm:

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

Importação no arquivo TypeScript:

import * as schedule from 'node-schedule';

Exemplo 1: Tarefa para uma data exata

Vamos criar uma tarefa que será executada em 31 de dezembro de 2024 às 23:59:59:

const date = new Date(2024, 11, 31, 23, 59, 59);

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

// Cancelamento da tarefa (se necessário)// job.cancel();

Exemplo 2: Tarefa periódica com expressão cron

Executar a tarefa a cada 5 minutos:

const job = schedule.scheduleJob('*/5 * * * *', () => {    console.log('Executando tarefa a cada 5 minutos');});

Formato da expressão cron: segundo minuto hora dia_do_mês mês dia_da_semana. No node-schedule, todos os 6 campos são suportados (ao contrário do cron clássico com 5 campos).

Exemplo 3: Usando RecurrenceRule

Vamos criar uma tarefa que é executada toda terça e quinta-feira às 10:30 da manhã:

const rule = new schedule.RecurrenceRule();rule.dayOfWeek = [2, 4]; // terça e quinta-feirarule.hour = 10;rule.minute = 30;

const job = schedule.scheduleJob(rule, () => {    console.log('Envio do relatório semanal');});

RecurrenceRule suporta os seguintes campos:

• year – ano ou array de anos
• month – mês (0-11) ou array
• date – dia do mês (1-31)
• dayOfWeek – dia da semana (0-6, onde 0 é domingo)
• hour – hora (0-23)
• minute – minuto (0-59)
• second – segundo (0-59)

Exemplo 4: Regras combinadas

Tarefa que é executada no último dia de cada mês às 23:59:

const rule = new schedule.RecurrenceRule();rule.month = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]; // todos os mesesrule.date = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]; // últimos dias de cada mêsrule.hour = 23;rule.minute = 59;rule.second = 59;

const job = schedule.scheduleJob(rule, () => {    console.log('Execução no último dia do mês');});

Gerenciamento de tarefas

A biblioteca fornece métodos para controle total sobre as tarefas:

// Criando uma tarefaconst job = schedule.scheduleJob('*/10 * * * * *', () => {    console.log('A cada 10 segundos');});

// Cancelando a tarefajob.cancel();

// Verificando se a tarefa está ativaconsole.log(job.pending()); // true ou false

// Cancelando todas as tarefasschedule.gracefulShutdow