À propos de ce cours
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
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 dansAppModule; les méthodes décorées doivent appartenir à des providers.@Cron(expression, { name, timeZone }): sanstimeZone, l'heure est celle du serveur, souvent UTC chez un hébergeur.'Africa/Tunis'garantit « 8 h à Tunis ».CronExpressionpropose 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@Timeoutne 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é ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !