Cronnor

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

Cronnor est publiée dans npm (ses CDN : esm.sh, jsDelivr, UNPKG) et Deno.

// Node.js et Bun (après `npm install cronnor`) :
import Cron from "cronnor";

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

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

API

• Cron
  • new Cron(cronex, func, [options])
  • Cron.active
  • Cron.run()
  • Cron.start()
  • Cron.stop()
  • Cron.test([date])
  • Cron.next([start])
• CronExp
  • new CronExp(pattern)
  • CronExp.test([date])
  • CronExp.next([start])
• At
  • new At(date, func, [options])
  • At.run()
  • At.abort()

Cron

import Cron from "cronnor/cron";
// import Cron from "https://esm.sh/cronnor@2/cron";
// import { Cron } from "https://deno.land/x/cronnor/mod.js";

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 croné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

import CronExp from "cronnor/cronexp";
// import CronExp from "https://esm.sh/cronnor@2/cronexp";
// import { CronExp } from "https://deno.land/x/cronnor/mod.js";

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

import At from "cronnor/at";
// import At from "https://esm.sh/cronnor@2/at";
// import { At } from "https://deno.land/x/cronnor/mod.js";

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 ou six éléments séparés par une espace. Les éléments représentent :

1. les secondes (optionnel ; 0 par défaut) : 0 à 59 ;
2. les minutes : 0 à 59 ;
3. les heures : 0 à 23 ;
4. le jour du mois : 1 à 31 ;
5. le mois : 1 ou jan, 2 ou feb, …, 12 ou dec ;
6. 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) ;
• ? : affecter l'unité courante à la création (pour une expression cron créée à 13h37, la valeur 13 sera utilisée pour les heures et 37 pour les minutes) ;
• ~ : générer un nombre aléatoire.

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.