cronstrue

What is cronstrue?

The cronstrue npm package is used to convert cron expressions into human-readable strings. This can be particularly useful for displaying cron schedules in a more understandable format for users who may not be familiar with cron syntax.

What are cronstrue's main functionalities?

Basic Conversion

This feature converts a basic cron expression into a human-readable string. For example, the cron expression '*/5 * * * *' is converted to 'Every 5 minutes'.

const cronstrue = require('cronstrue');
console.log(cronstrue.toString('*/5 * * * *'));

Localized Conversion

This feature allows for the conversion of cron expressions into human-readable strings in different languages. For example, the cron expression '*/5 * * * *' is converted to 'Cada 5 minutos' in Spanish.

const cronstrue = require('cronstrue');
console.log(cronstrue.toString('*/5 * * * *', { locale: 'es' }));

Verbose Conversion

This feature provides a more detailed, verbose description of the cron expression. For example, the cron expression '*/5 * * * *' is converted to 'Every 5 minutes, every hour, every day, every month, every day of the week'.

const cronstrue = require('cronstrue');
console.log(cronstrue.toString('*/5 * * * *', { verbose: true }));

Other packages similar to cronstrue

cron-parser

The cron-parser package is used for parsing and manipulating cron expressions. Unlike cronstrue, which focuses on converting cron expressions to human-readable strings, cron-parser provides more functionality for working with cron expressions programmatically, such as finding the next execution time.

later

The later package is a scheduling library that supports both cron and other types of schedules. It can be used to parse, manipulate, and execute schedules. While cronstrue focuses on converting cron expressions to human-readable strings, later provides a more comprehensive set of tools for working with schedules.

README

cRonstrue

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

• Zero dependencies
• Supports all cron expression special characters including * / , - ? L W, #
• Supports 5, 6 (w/ seconds or year), or 7 (w/ seconds and year) part cron expressions
• Supports Quartz Job Scheduler cron expressions
• i18n support with 27 languages

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:

npm install cronstrue

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

Node

var 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.

<script src="cronstrue.min.js" type="text/javascript"></script>
<script>
  var cronstrue = window.cronstrue;
</script>

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:

<script src="https://unpkg.com/cronstrue@latest/dist/cronstrue.min.js" async></script>

Using the "latest" tag will result in a 302 redirect to the latest version tag so it is highly 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"

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

Options

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

• throwExceptionOnParseError: boolean - If exception occurs when trying to parse expression and generate description, whether to throw or catch and output the Exception message as the description. (Default: true)
• verbose: boolean - Whether to use a verbose description (Default: false)
• dayOfWeekStartIndexZero: boolean - Whether to interpret cron expression DOW 1 as Sunday or Monday. (Default: true)
• monthStartIndexZero: boolean - Wether to interpret January as 0 or 1. (Default: false)
• use24HourTimeFormat: boolean - If true, descriptions will use a 24-hour clock (Default: false but some translations will default to true)
• locale: string - The locale to use (Default: "en")

i18n

To use the i18n support cRonstrue provides, you can import a specific locale and then call toString(). For example, for the es (Spanish) locale:

import cronstrue from 'cronstrue/locales/es';
cronstrue.toString("*/5 * * * *");

Browser

A locale file from the /locales folder in the npm package should be served to the browser.

<script src="https://unpkg.com/cronstrue@latest/locales/es.min.js" async></script>
<script>
  cronstrue.toString("*/5 * * * *");
</script>

All Locales

Alternatively you can import all locales and then pass in the locale option:

import cronstrue from 'cronstrue/i18n';
cronstrue.toString("*/5 * * * *", { locale: "es" });

Frequently Asked Questions

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-validator or cron-parser.

Can cRonstrue output the next occurrence of the cron expression?

No, cRonstrue does not support this. It simply describes a cron expression. You could use another library to get the next occurrence of a cron expression and then pass that expression into cRonstrue, to achieve this.

Supported Locales

• en - English (Brady Holt)
• ca - Catalan (Francisco Javier Barrena)
• cs - Czech (hanbar)
• es - Spanish (Ivan Santos)
• da - Danish (Rasmus Melchior Jacobsen)
• de - German (Michael Schuler)
• fi - Finnish (Mikael Rosenberg)
• fr - French (Arnaud TAMAILLON)
• fa - Farsi (A. Bahrami)
• he - Hebrew (Ilan Firsov)
• it - Italian (rinaldihno)
• id - Indonesia (Hasan Basri)
• ja - Japanese (Alin Sarivan)
• ko - Korean (Ion Mincu)
• nb - Norwegian (Siarhei Khalipski)
• nl - Dutch (TotalMace)
• pl - Polish (foka)
• pt_BR - Portuguese (Brazil) (Renato Lima)
• ro - Romanian (Illegitimis)
• ru - Russian (LbISS)
• sk - Slovakian (hanbar)
• sl - Slovenian (Jani Bevk)
• sw - Swahili (Leylow Lujuo)
• sv - Swedish (roobin)
• tr - Turkish (Mustafa SADEDİL)
• uk - Ukrainian (Taras)
• zh_CN - Chinese (Simplified) (Star Peng)
• zh_TW - Chinese (Traditional) (Ricky Chiang)
• be - Belarusian (Kirill Mikulich)

License

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