GitHub - bradymholt/cRonstrue: JavaScript library that translates Cron expressions into human readable descriptions (original) (raw)

Would you take a quick second and ⭐️ my repo?

cRonstrue is a JavaScript library that parses a cron expression and outputs a human readable description of the cron schedule. For example, given the expression "*/5 * * * *" it will output "Every 5 minutes".

This library was ported from the original C# implementation called cron-expression-descriptor and is also available in a few other languages.

Features

Demo

A demo is available here.

Installation

cRonstrue is exported as an UMD module so it will work in an AMD, CommonJS or browser global context.

First, install the module:

Then, depending upon your usage context, add a reference to it:

Node / CommonJS

const cronstrue = require('cronstrue');

ESM / webpack / TypeScript

import cronstrue from 'cronstrue';

Browser

The cronstrue.min.js file from the /dist folder in the npm package should be served to the browser. There are no dependencies so you can simply include the library in a <script> tag.

CDN

A simple way to load the library in a browser is by using the unpkg CDN, which is a "fast, global content delivery network for everything on npm". To use it, include a script tag like this in your file:

Using the "latest" tag will result in a 302 redirect to the latest version tag so it is recommended to use a specific version tag such as https://unpkg.com/cronstrue@1.48.0/dist/cronstrue.min.js to avoid this redirect.

Usage

cronstrue.toString("* * * * *");

"Every minute"

cronstrue.toString("0 23 ? * MON-FRI");

"At 11:00 PM, Monday through Friday"

cronstrue.toString("0 23 * * *", { verbose: true });

"At 11:00 PM, every day"

cronstrue.toString("23 12 * * SUN#2");

"At 12:23 PM, on the second Sunday of the month"

cronstrue.toString("23 14 * * SUN#2", { use24HourTimeFormat: true });

"At 14:23, on the second Sunday of the month"

cronstrue.toString("* * * ? * 2-6/2", { dayOfWeekStartIndexZero: false });

"Every second, every 2 days of the week, Monday through Friday"

cronstrue.toString("* * * 6-8 *", { monthStartIndexZero: true });

"Every minute, July through September"

cronstrue.toString("@monthly");

"At 12:00 AM, on day 1 of the month"

For more usage examples, including a demonstration of how cRonstrue can handle some very complex cron expressions, you can reference the unit tests.

i18n

By default, only the English translation (en) is included when you import and use cRonstrue. To use other languages, please see the i18n section below.

CLI Usage

❯ npx cronstrue "*/5 * * * *" Every 5 minutes

Options

An options object can be passed as the second parameter to cronstrue.toString. The following options are available:

i18n

To use the i18n support cRonstrue provides, you can either import all the supported locales at once (using cronstrue/i18n) or import individual locales (using cronstrue/locales/[locale]). Then, when calling toString you pass in the name of the locale you want to use. For example, for the es (Spanish) locale, you would use: cronstrue.toString("* * * * *", { locale: "es" }).

All Locales

You can import all locales at once with cronstrue/i18n. This approach has the advantage of only having to load one module and having access to all supported locales. The tradeoff with this approach is a larger module (~130k, minified) that will take longer to load, particularly when sending down to a browser.

// Node / CommonJS const cronstrue = require('cronstrue/i18n');

// ESM / webpack / TypeScript import cronstrue from 'cronstrue/i18n';

// Browser

cronstrue.toString("*/5 * * * ", { locale: "fr" }); // => Toutes les 5 minutes cronstrue.toString("/5 * * * *", { locale: "es" }); // => Cada 5 minutos

Individual Locales

You can also load the main cronstrue module and then load individual locale modules you want to have access to. This works well when you have one or more locales you know you need access to and want to minimize load time, particularly when sending down to a browser. The main cronstrue module is about 42k (minified) and each locale is about 4k (minified) in size.

// Node / CommonJS const cronstrue = require('cronstrue'); require('cronstrue/locales/fr'); require('cronstrue/locales/es');

// ESM / webpack / TypeScript import cronstrue from 'cronstrue'; import 'cronstrue/locales/fr'; import 'cronstrue/locales/es';

// Browser

cronstrue.toString("*/5 * * * ", { locale: "fr" }); // => Toutes les 5 minutes cronstrue.toString("/5 * * * *", { locale: "es" }); // => Cada 5 minutos

Supported Locales

The following locales can be passed in for the locale option. Thank you to the author (shown below) of each translation!

Frequently Asked Questions

  1. The cron expression I am passing in is not valid and this library is giving strange output. What should I do?
    This library does not do full validation of cron expressions and assumes the expression passed in is valid. If you need to validate an expression consider using a library like cron-parser. Example validation with cron-parser:
    import { CronExpressionParser } from "cron-parser";
    import cronstrue from "cronstrue";
    const expression = "* * * * * *";
    const isCronValid = (() => {
    try {
    CronExpressionParser.parse(expression);
    return true;
    } catch {
    return false;
    }
    })();
    if (isCronValid) {
    console.log(cronstrue.toString(expression));
    }
  2. Can cRonstrue output the next occurrence of the cron expression?
    No, cRonstrue does not support this. This library simply describes a cron expression that is passed in. You can do with with a library like croner. Example:
    import { Cron } from 'croner';
    const job = new Cron('0 9 * * 1-5');
    console.log(job.nextRun()); // next Date
    console.log(job.nextRuns(5)); // next 5 Dates

Sponsors

Thank you to the following sponsors of this project!

robjtede robjtede robjtede robjtede robjtede robjtede

License

cRonstrue is freely distributable under the terms of the MIT license.