Skip to main content

Cronnor

npm jsdelivr build coverage semver

Bibliothèque JavaScript implémentant un programme cron.

Description

Cronnor est une bibliothèque moderne fournissant une classe Cron pour créer des tâches récurrentes. Elle est disponible pour Node.js, Deno et les navigateurs.

import Cron from "cronnor";

function task() {
    // Awesome task to be done every working day at 8am.
};

const cron = new Cron("0 8 * * mon-fri", task);

// It's holiday time!
cron.stop();

Installation

Node.js

Cronnor est publiée dans npm.

import Cron from "cronnor";

Deno

La bibliothèque est disponible dans Deno.

import Cron from "https://deno.land/x/cronnor/mod.js";

Elle est aussi accessible directement avec le CDN jsDelivr (ou UNPKG, esm.sh) :

import Cron from "https://cdn.jsdelivr.net/npm/cronnor@2/+esm";
// import Cron from "https://unpkg.com/cronnor@2";
// import Cron from "https://esm.sh/cronnor@2";

API

Cron

new Cron(cronex, func, [options])

Crée une tâche cronée.

  • Paramètres :
    • cronex (string ou string[]) : La ou les expressions cron indiquant les horaires d’exécution de la tâche.
    • func (Function) : La fonction appelée à chaque horaire indiqué dans les expressions cron.
    • options (Object) : Les options de la tâche cronnée.
      • active (boolean) : true (par défaut) pour activer la tâche ; sinon false.
      • thisArg (any) : Le this utilisé pour la fonction (la tâche cronée par défaut).
      • args (any[]) : Les paramètres passés à la fonction (aucun paramètre par défaut).
  • Exceptions :
    • Error : Si la syntaxe d’une expression cron est incorrecte.
    • RangeError : Si un intervalle d’une expression cron est invalide (hors limite ou quand la borne supérieure est plus petite que la borne inférieure).
    • TypeError : Si le constructeur est appelé sans le mot clé new ou si un des paramètres n’a pas le bon type.

Cron.active

Récupère ou définit l’état de la tâche (active ou non) :

  • true si la tâche est active ou pour l’activer.
  • false si elle est inactive ou pour la désactiver.

Cron.run()

Exécute manuellement la fonction.

Cron.start()

Active la tâche.

  • Valeur retournée : true quand la tâche a été activée ; false si elle était déjà active.

Cron.stop()

Désactive la tâche.

  • Valeur retournée : true quand la tâche a été désactivée ; false si elle était déjà inactive.

Cron.test([date])

Teste si une date respecte une des expressions cron de la tâche.

  • Paramètre :
    • date (Date) : La date qui sera testée (ou l’instant présent par défaut).
  • Valeur retournée : true si une des expressions est respectée ; sinon false.

Cron.next([start])

Calcule la prochaine date respectant une des expressions cron de la tâche.

  • Paramètre :
    • start (Date) : La date de début (ou l’instant présent par défaut).
  • Valeur retournée : La prochaine date respectant une des expressions.

CronExp

new CronExp(pattern)

Crée une expression cron.

  • Paramètre :
    • pattern (string) : Le motif de l’expression cron
  • Exceptions :
    • Error : Si la syntaxe du motif est incorrecte.
    • RangeError : Si un intervalle est invalide (hors limite ou quand la borne supérieure est plus petite que la borne inférieure).
    • TypeError : Si le constructeur est appelé sans le mot clé new ou si le motif n’est pas une chaine de caractères.

CronExp.test([date])

Teste si une date respecte l’expression.

  • Paramètre :
    • date (Date) : La date qui sera testée (ou l’instant présent par défaut).
  • Valeur retournée : true si l’expression est respectée ; sinon false.

CronExp.next([start])

Calcule la prochaine date respectant l’expression.

  • Paramètre :
    • start (Date) : La date de début (ou l’instant présent par défaut).
  • Valeur retournée : La prochaine date respectant l’expression.

At

new At(date, func, [options])

Crée une tâche planifiée.

  • Paramètres :
    • date (Date) : La date de planification de la tâche.
    • func (Function) : La fonction appelée à la date planifiée.
    • options (Object) : Les options de la planification de la tâche.
      • thisArg (any) : Le this utilisé pour la fonction (la tâche planifiée par défaut).
      • args (any[]) : Les paramètres passés à la fonction (aucun paramètre par défaut).
  • Exceptions :
    • TypeError : Si le constructeur est appelé sans le mot clé new.

At.run()

Exécute manuellement la fonction.

At.abort()

Annule la planification.

Expression cron

Les expressions cron sont des chaines de caractères composées de cinq éléments séparés par une espace. Les éléments représentent :

  1. les minutes : 0 à 59 ;
  2. les heures : 0 à 23 ;
  3. le jour du mois : 1 à 31 ;
  4. le mois : 1 ou jan, 2 ou feb, …, 12 ou dec ;
  5. le jour de la semaine : 0, 7 ou sun, 1 ou mon, …, 6 ou sat.

Pour chaque élément, des compositions sont possibles :

  • * : couvrir toutes les unités (0, 1, 2, …) ;
  • - : définir un intervalle (1-3 corresponds aux unités 1, 2 et 3) ;
  • / : indiquer le pas (2-6/2 corresponds aux unités 2, 4 et 6) ;
  • , : créer une liste (4,8 corresponds aux unités 4 et 8).

Il existe aussi des chaines spéciales :

  • "@yearly" ou "@annually" : tous les ans, le 1er janvier ("0 0 1 1 *") ;
  • "@monthly" : le 1er jour de chaque mois ("0 0 1 * *") ;
  • "@weekly" : une fois par semaine, le dimanche ("0 0 * * 0") ;
  • "@daily" ou "@midnight" : tous les jours à minuit ("0 0 * * *") ;
  • "@hourly" : toutes les heures ("0 * * * *").

Pour plus d’information, vous pouvez consulter le manuel de crontab.