> ## Documentation Index
> Fetch the complete documentation index at: https://www.chapterjs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Tâches

> Faire faire quelque chose à votre bot tout seul, régulièrement ou à des heures données, avec une déclaration task()

Une tâche se déclare avec `task()`, dans n’importe quel fichier de `src/`, et s’exporte. Elle dit quand tourner et quoi faire ; ChapterJS la lance une fois le bot connecté, et continue de la lancer tant que le bot est en ligne.

```ts src/tasks/report.ts theme={"theme":{"light":"github-light","dark":"vesper"}}
import { task } from 'chapterjs';

export default task({
  cron: '0 9 * * 1',
  timezone: 'Europe/Paris',
  async run({ guilds }) {
    for (const guild of guilds.values()) {
      const general = [...guild.channels.values()].find(channel => channel.name === 'general');
      if (general?.isText()) await general.send(`Bonjour ! Nous sommes ${guild.memberCount ?? '?'} ici.`);
    }
  },
});
```

C’est tout : chaque lundi à 9 h, heure de Paris, la tâche tourne avec les serveurs où se trouve le bot. Le nom de l’export (ou du fichier, pour un export par défaut) est le nom de la tâche, et rien d’autre n’est à enregistrer.

> [!NOTE]
>
> Tout ce que déclare un fichier de tâche est dans la [référence](https://www.chapterjs.org/fr/reference/task.md).

## Régulièrement

`every` est une durée : un nombre et une unité, `s`, `m`, `h` ou `d`. La tâche tourne à cet intervalle, compté à partir du moment où le bot se connecte.

```ts src/tasks/cleanup.ts theme={"theme":{"light":"github-light","dark":"vesper"}}
import { task } from 'chapterjs';

export default task({
  every: '30m',
  async run({ guilds }) {
    console.log(`Vérification de ${guilds.size} serveurs`);
  },
});
```

`'30s'`, `'10m'`, `'2h'`, `'1d'` et `'1h30m'` fonctionnent tous ; une fois par seconde est le plus rapide.

## À des heures données

`cron` est une expression cron standard : minute, heure, jour du mois, mois et jour de la semaine.

| Écrivez | Tourne |
| - | - |
| `'0 9 * * *'` | Chaque jour à 9 h |
| `'*/15 * * * *'` | Toutes les 15 minutes |
| `'0 9 * * 1-5'` | En semaine à 9 h |
| `'30 18 * * fri'` | Le vendredi à 18 h 30 |
| `'0 0 1 * *'` | Le premier de chaque mois à minuit |
| `'0 12 1,15 * *'` | Le 1er et le 15 à midi |

Sans `timezone`, la tâche suit l’horloge de la machine sur laquelle tourne le bot. Avec un fuseau (`'Europe/Paris'`, `'America/New_York'`...), elle suit cette horloge, changements d’heure compris : une heure qui n’existe pas ce jour-là est sautée, une heure qui arrive deux fois ne tourne qu’une fois.

Un cron faux, ou qui n’arrive jamais (`'0 0 31 2 *'`), est une erreur au chargement du fichier, avec quoi écrire.

## Tourner tout de suite

`onStart: true` lance aussi la tâche une fois dès que le bot est connecté, sans attendre son premier horaire :

```ts src/tasks/status.ts theme={"theme":{"light":"github-light","dark":"vesper"}}
import { task } from 'chapterjs';

export default task({
  every: '1h',
  onStart: true,
  run({ user, guilds, now }) {
    console.log(`${now.toISOString()} : ${user.username} est sur ${guilds.size} serveurs`);
  },
});
```

## Ce que reçoit run

| Champ | Ce que c’est |
| - | - |
| `user` | Le bot lui-même, un [User](https://www.chapterjs.org/fr/reference/user.md) |
| `guilds` | Les serveurs où se trouve le bot, comme les donne l’[événement `ready`](https://www.chapterjs.org/fr/reference/events#ready) |
| `now` | Le moment où ce passage était prévu, un `Date` |

## Quand un passage est long, ou échoue

Un passage encore en cours quand arrive l’horaire suivant n’est pas lancé deux fois : cet horaire est sauté, et votre terminal le dit.

```text theme={"theme":{"light":"github-light","dark":"vesper"}}
⚠ src/tasks/report.ts report was still running when its next time came (every 1s): that run was skipped.
```

Un passage qui lève une erreur est signalé avec le fichier et la ligne, et la tâche garde son prochain horaire. Rien n’arrête le bot.

Pendant que le bot se reconnecte à Discord, une tâche qui devait tourner est sautée et signalée ; elle tourne à nouveau à son prochain horaire.

## En développement, en production

Dans `chapterjs dev`, enregistrer un fichier de tâche remplace ce qu’elle fait sans changer quand : une tâche qui tourne toutes les heures garde son prochain horaire à travers le rechargement. Changer `every` ou `cron` recompte la tâche à partir de l’enregistrement. Dans `chapterjs start`, un bot réparti sur [plusieurs processus](https://www.chapterjs.org/fr/run/start.md#gros-bots) lance chaque tâche une fois, dans son premier processus.

> [card] [Référence : task()](https://www.chapterjs.org/fr/reference/task.md)
>
> Chaque champ d’un fichier de tâche, et ce que reçoit run.

> [card] [Envoyer des messages](https://www.chapterjs.org/fr/messages.md)
>
> Ce qu’une tâche peut publier, et où.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.