cronnor

Bibliothèque JavaScript implémentant un programme cron.

Usage no npm install needed!

<script type="module">
  import cronnor from 'https://cdn.skypack.dev/cronnor';
</script>

README

Cronnor

Bibliothèque JavaScript implémentant un programme cron.

npm jsdelivr build coverage semver

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";

Navigateurs

Elle est aussi accessible directement avec le CDN jsDelivr (ou Skypack, UNPKG) :

import Cron from "https://cdn.jsdelivr.net/npm/cronnor@1";

API

Cron

new Cron(cronex, func, [active])

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. Avec un tableau vide, la tâche ne sera jamais exécutée.
    • func (Function) : La fonction appelée à chaque horaire indiqué dans les expressions cron.
    • active (boolean) : true (par défaut) pour activer la tâche ; sinon false.
  • Exceptions :
    • Error : Si la syntaxe d'une expession 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

Est l'état de la tâche (active ou non).

Cron.bind(thisArg, ...args)

Définit le this et les paramètres passés à la fonction.

  • Paramètres :
    • thisArg (any) : Le this utilisé pour la fonction.
    • args (...any) : Les paramètres passés à la fonction.
  • Valeur retournée : La tâche elle-même.

Cron.unbind()

Remet les valeurs par défaut pour le this et les paramètres passés à la fonction.

  • Valeur retournée : La tâche elle-même.

Cron.withArguments(...args)

Définit les paramètres passés à la fonction.

  • Paramètres :
    • args (...any) : Les paramètres passés à la fonction.
  • Valeur retournée : La tâche elle-même.

Cron.withoutArguments()

Enlève les paramètres passés à la fonction.

  • Valeur retournée : La tâche elle-même.

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 ou undefined s'il n'y a pas de prochaine date (car il n'y a aucune expression cron).

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([date])

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.

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.