Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Les tâches planifiées (@nestjs/schedule, @Cron)

Cette leçon présente @nestjs/schedule pour exécuter du code à intervalles réguliers : nettoyage nocturne, rapport quotidien, relances. Elle explique la syntaxe cron à six champs, les expressions prête...

0 chapitres 0 QCM Accès gratuit
Les tâches planifiées (@nestjs/schedule, @Cron)

À propos de ce cours

Cette leçon présente @nestjs/schedule pour exécuter du code à intervalles réguliers : nettoyage nocturne, rapport quotidien, relances. Elle explique la syntaxe cron à six champs, les expressions prêtes à l'emploi et le fuseau horaire. Elle couvre aussi @Interval, @Timeout et SchedulerRegistry, qui permet de lister, arrêter ou ajouter des tâches pendant l'exécution. L'exécution horodatée montre l'ordre réel des déclenchements, puis le cas d'une tâche plus longue que son intervalle : sans waitForCompletion, les exécutions se chevauchent. La leçon traite enfin du lancement sur plusieurs instances. Activités corrigées.

Objectifs de la leçon

  • Planifier une tâche avec @Cron et lire une expression cron.
  • Utiliser @Interval et @Timeout.
  • Piloter les tâches avec SchedulerRegistry.
  • Éviter les chevauchements et les exécutions en double.
À quoi servent les tâches planifiées ?

Certaines actions ne sont déclenchées par aucune requête : supprimer chaque nuit les fichiers orphelins, envoyer chaque lundi un bilan, relancer les stagiaires qui n'ont pas déposé leur dossier, purger les sessions expirées. @nestjs/schedule exécute ces méthodes à l'intérieur de l'application, selon un calendrier.

npm install @nestjs/schedule

Syntaxe cron à six champs

Le premier champ, facultatif, est la seconde ; le dernier est le jour de la semaine.

Les décorateurs

📄 src/taches/rappels.service.ts

import { Injectable } from '@nestjs/common';
import { Cron, CronExpression, Interval, SchedulerRegistry, Timeout } from '@nestjs/schedule';
import { CronJob } from 'cron';

const t0 = Date.now();
const log = (m: string) => console.log(`[+${((Date.now() - t0) / 1000).toFixed(1).padStart(4)} s] ${m}`);

@Injectable()
export class RappelsService {
  private executions = 0;
  constructor(private readonly registre: SchedulerRegistry) {}

  // Toutes les 2 secondes (6 champs : la seconde en premier). En vrai : '0 0 2 * * *' = chaque jour à 2 h
  @Cron('*/2 * * * * *', { name: 'nettoyage', timeZone: 'Africa/Tunis' })
  nettoyer() {
    this.executions++;
    log(`@Cron nettoyage n° ${this.executions}`);
  }

  // Une expression prête à l'emploi
  @Cron(CronExpression.EVERY_DAY_AT_8AM, { name: 'rapport-quotidien', timeZone: 'Africa/Tunis' })
  rapportQuotidien() {
    log('rapport quotidien envoyé');
  }

  // Toutes les 3 secondes, à partir du démarrage
  @Interval('statistiques', 3000)
  statistiques() {
    log('@Interval statistiques');
  }

  // Une seule fois, 1 seconde après le démarrage
  @Timeout(1000)
  premierDemarrage() {
    log('@Timeout : préchauffage du cache');
  }

  // Une tâche lente : que se passe-t-il si elle dure plus longtemps que son intervalle ?
  @Cron('* * * * * *', { name: 'lente', waitForCompletion: true })
  async lente() {
    log('lente : début');
    await new Promise((r) => setTimeout(r, 2500));
    log('lente : fin');
  }

  ajouterDynamique() {
    const tache = new CronJob('*/1 * * * * *', () => log('tâche dynamique'));
    this.registre.addCronJob('dynamique', tache);
    tache.start();
  }
}

📄 src/app.module.ts

import { Module } from '@nestjs/common';
import { ScheduleModule } from '@nestjs/schedule';
import { RappelsService } from './taches/rappels.service';

@Module({ imports: [ScheduleModule.forRoot()], providers: [RappelsService] })
export class AppModule {}
  • ScheduleModule.forRoot() une seule fois dans AppModule; les méthodes décorées doivent appartenir à des providers.
  • @Cron(expression, { name, timeZone }): sans timeZone, l'heure est celle du serveur, souvent UTC chez un hébergeur. 'Africa/Tunis' garantit « 8 h à Tunis ».
  • CronExpression propose des expressions prêtes : EVERY_DAY_AT_8AM, EVERY_HOUR, EVERY_WEEK…
  • @Interval(ms): toutes les N millisecondes à partir du démarrage. @Timeout(ms): une seule fois, N millisecondes après le démarrage.
  • SchedulerRegistry: lister, arrêter, supprimer ou ajouter des tâches pendant l'exécution (par exemple depuis une route d'administration).

📄 src/main.ts

import 'reflect-metadata';
import { NestFactory } from '@nestjs/core';
import { SchedulerRegistry } from '@nestjs/schedule';
import { AppModule } from './app.module';
import { RappelsService } from './taches/rappels.service';

const attendre = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function main() {
  const app = await NestFactory.createApplicationContext(AppModule, { logger: false });
  const registre = app.get(SchedulerRegistry);
  console.log('Tâches cron :', [...registre.getCronJobs().keys()].join(', '));
  const rapport = registre.getCronJob('rapport-quotidien');
  console.log('Prochain rapport quotidien :', rapport.nextDate().setZone('Africa/Tunis').toFormat("dd/MM/yyyy HH:mm (ZZZZ)"));
  console.log('Intervalles :', registre.getIntervals().join(', '));

  await attendre(6200);
  console.log('— On arrête « nettoyage » et « lente », on ajoute une tâche dynamique');
  registre.getCronJob('nettoyage').stop();
  registre.getCronJob('lente').stop();
  app.get(RappelsService).ajouterDynamique();
  await attendre(2100);
  registre.deleteCronJob('dynamique');
  registre.deleteInterval('statistiques');
  console.log('— Fin');
  await app.close();
}
main();

Résultat réellement obtenu (temps depuis le démarrage) :

Tâches cron : nettoyage, rapport-quotidien, lente
Prochain rapport quotidien : 16/11/2026 08:00 (GMT+1)
Intervalles : statistiques
[+ 0.8 s] @Cron nettoyage n° 1
[+ 0.8 s] lente : début
[+ 1.0 s] @Timeout : préchauffage du cache
[+ 2.8 s] @Cron nettoyage n° 2
[+ 3.0 s] @Interval statistiques
[+ 3.3 s] lente : fin
[+ 3.8 s] lente : début
[+ 4.8 s] @Cron nettoyage n° 3
[+ 6.0 s] @Interval statistiques
— On arrête « nettoyage » et « lente », on ajoute une tâche dynamique
[+ 6.3 s] lente : fin
[+ 6.8 s] tâche dynamique
[+ 7.8 s] tâche dynamique
— Fin
Lecture
  • « nettoyage » se déclenche aux secondes paires de l'horloge (ici à 0,8 s, 2,8 s et 4,8 s après le démarrage) : les instants dépendent de l'heure à laquelle l'application a démarré : une expression cron désigne des instants du calendrier.
  • @Interval, lui, compte depuis le démarrage (3,0 s ; 6,0 s), et @Timeout ne s'exécute qu'une fois.
  • nextDate() donne la prochaine exécution du rapport quotidien : demain à 8 h, heure de Tunis.
  • La tâche « lente » (2,5 s, déclenchée chaque seconde) a l'option waitForCompletion: true: une nouvelle exécution ne commence pas tant que la précédente n'est pas terminée.
  • Après stop(), les tâches arrêtées ne s'exécutent plus ; la tâche ajoutée dynamiquement fonctionne jusqu'à sa suppression.
Sans waitForCompletion : les exécutions se chevauchent

📄 src/taches/rappels.service.ts (variante)

import { Injectable } from '@nestjs/common';
import { Cron } from '@nestjs/schedule';

const t0 = Date.now();
const log = (m: string) => console.log(`[+${((Date.now() - t0) / 1000).toFixed(1).padStart(4)} s] ${m}`);

@Injectable()
export class RappelsService {
  private n = 0;
  @Cron('* * * * * *', { name: 'lente' })            // sans waitForCompletion
  async lente() {
    const moi = ++this.n;
    log(`lente n° ${moi} : début`);
    await new Promise((r) => setTimeout(r, 2500));
    log(`lente n° ${moi} : fin`);
  }
}

Résultat réellement obtenu :

[+ 0.5 s] lente n° 1 : début
[+ 1.5 s] lente n° 2 : début
[+ 2.5 s] lente n° 3 : début
[+ 3.0 s] lente n° 1 : fin
[+ 3.5 s] lente n° 4 : début
[+ 4.0 s] lente n° 2 : fin
[+ 5.0 s] lente n° 3 : fin
[+ 6.0 s] lente n° 4 : fin

Quatre exécutions tournent en même temps. Pour un nettoyage de fichiers ou un envoi d'e-mails, c'est dangereux : le même fichier supprimé deux fois, le même e-mail envoyé deux fois. Activez waitForCompletion pour toute tâche dont la durée peut dépasser l'intervalle.

Plusieurs instances de l'application (PM2 en mode cluster, plusieurs conteneurs, chapitre 20) : chaque instance exécute ses propres tâches cron. Le bilan du lundi partirait autant de fois qu'il y a d'instances. Solutions : n'activer les tâches que sur une instance (variable TACHES_ACTIVES=true), utiliser un verrou partagé (Redis, ou une ligne de table « verrou »), ou confier les tâches à une file comme BullMQ. Et une tâche planifiée ne doit jamais faire planter l'application : entourez son code d'un try/catch qui journalise.

Activités

Activité 1 Lire des expressions

Traduisez en français : (a) '0 30 7 * * 1-5'; (b) '0 0 0 1 * *'; (c) '0 */10 8-17 * * *'; (d) '0 0 12 * * 0'. Puis écrivez l'expression de « chaque 15 juin à 9 h ».

Voir le corrigé

(a) Du lundi au vendredi à 7 h 30. (b) Le 1er de chaque mois à minuit. (c) Toutes les 10 minutes, de 8 h à 17 h 50. (d) Chaque dimanche à midi. « Chaque 15 juin à 9 h » : '0 0 9 15 6 *'.

Activité 2 Relance des retardataires

Dans le projet du TP 8, écrivez une tâche qui, chaque vendredi à 16 h (heure de Tunis), recherche les stagiaires sans aucune note et envoie à chacun un e-mail de rappel (leçon 15.3). Elle ne doit jamais s'exécuter deux fois en parallèle.

Voir le corrigé
@Cron('0 0 16 * * 5', { name: 'relance', timeZone: 'Africa/Tunis', waitForCompletion: true })
async relancer() {
  try {
    const sansNote = await this.utilisateurs.createQueryBuilder('u')
      .leftJoin(Note, 'n', 'n.stagiaireId = u.id')
      .where('u.role = :r', { r: Role.Stagiaire }).andWhere('n.id IS NULL')
      .getMany();
    for (const u of sansNote) {
      await this.mail.envoyer({ a: u.email, sujet: 'Rappel', html: `<p>Bonjour ${echapper(u.nom)}, …</p>` })
        .catch((e) => this.logger.warn(`Relance de ${u.email} impossible : ${e.message}`));
    }
  } catch (e) {
    this.logger.error('Tâche de relance en échec', e as Error);
  }
}

Activité 3 Tester une tâche

Comment tester la tâche de relance sans attendre vendredi 16 h ? Proposez deux méthodes.

Voir le corrigé

(1) Appeler directement la méthode : await app.get(RelancesService).relancer() dans un script ou un test (chapitre 17), comme dans le TP 9. (2) Une route d'administration qui déclenche la tâche (registre.getCronJob('relance').fireOnTick()). On peut aussi lire l'expression depuis la configuration (RELANCE_CRON) pour la rendre très fréquente en développement.

Activité 4 Une route d'administration

Ajoutez GET /api/admin/taches (admin) qui renvoie, pour chaque tâche cron, son nom, si elle est active, et sa prochaine exécution ; et PATCH /api/admin/taches/:nom avec { "active": false } pour la suspendre.

Voir le corrigé
@Get('taches')
lister() {
  return [...this.registre.getCronJobs()].map(([nom, tache]) => ({
    nom,
    active: tache.isActive,
    prochaine: tache.isActive ? tache.nextDate().toISO() : null,
  }));
}

@Patch('taches/:nom')
basculer(@Param('nom') nom: string, @Body('active', ParseBoolPipe) active: boolean) {
  const tache = this.registre.getCronJob(nom);          // lève une erreur si le nom est inconnu
  active ? tache.start() : tache.stop();
  return { nom, active: tache.isActive };
}

À retenir

  • ScheduleModule.forRoot() ; @Cron, @Interval, @Timeout sur des méthodes de providers.
  • Cron à 6 champs (seconde minute heure jour mois jour-semaine) ; CronExpression pour les cas courants.
  • timeZone: 'Africa/Tunis' ; sinon l'heure du serveur (souvent UTC).
  • waitForCompletion: true pour éviter les chevauchements ; try/catch dans chaque tâche.
  • SchedulerRegistry pour piloter les tâches ; attention aux instances multiples.

Cet article vous a-t-il aidé ?