cronstrue
Advanced tools
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.
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 }));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.
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.
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.
A demo is available here.
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:
const cronstrue = require('cronstrue');
import cronstrue from 'cronstrue';
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>
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 recommended to use a specific version tag such as https://unpkg.com/cronstrue@1.48.0/dist/cronstrue.min.js to avoid this redirect.
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.
An options object can be passed as the second parameter to cronstrue.toString. The following options are available:
1 as Sunday or Monday. (Default: true)0 or 1. (Default: false)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" }).
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
<script src="https://unpkg.com/cronstrue@latest/cronstrue-i18n.min.js" async></script>
cronstrue.toString("*/5 * * * *", { locale: "fr" }); // => Toutes les 5 minutes
cronstrue.toString("*/5 * * * *", { locale: "es" }); // => Cada 5 minutos
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
<script src="https://unpkg.com/cronstrue@latest/cronstrue.min.js" async></script>
<script src="https://unpkg.com/cronstrue@latest/locales/fr.min.js" async></script>
<script src="https://unpkg.com/cronstrue@latest/locales/es.min.js" async></script>
cronstrue.toString("*/5 * * * *", { locale: "fr" }); // => Toutes les 5 minutes
cronstrue.toString("*/5 * * * *", { locale: "es" }); // => Cada 5 minutos
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. This library simply describes a cron expression that is passed in.
cRonstrue is freely distributable under the terms of the MIT license.
FAQs
Convert cron expressions into human readable descriptions
The npm package cronstrue receives a total of 842,251 weekly downloads. As such, cronstrue popularity was classified as popular.
We found that cronstrue demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.