cronli5

DISCLAIMER: IN PROGRESS

This is a work in progress and does not yet work in all intended cases. DO NOT USE until this discalimer has been removed. If you need something like this now, use prettycron.

Cron Like I'm Five: A Cron to English Utility

Generate English language descriptions of schedules from cron patterns. Accepts classic (five-part) cron patterns, or extended (six-part) cron patterns, where the first field is assumed to refer to seconds. Accepts the standard allowed values and the following operators: asterisks (*), commas (,), hyphens (-), and slashes (/).

cronli5 is a good library to use if you need to display an English language interpretation of a cron pattern in a Node or in a browser environment. If you need to do other things with cron patterns, consider a library like [Later.js] later. If you want an alternative to cronli5, prettycron may also meet your needs as an interpreter.

Installation

Install using npm:

# If you plan to use the cli:
npm install -g cronli5

# For a Node project:
npm install --save cronli5

Browser (script tag):

<script src="cronli5.min.js" type="text/javascript"></script>

When included in a script tag, the cronli5 function will be available as a global in the scripts that follow.
Unsolicited advice: rather than including cronli5 in its own script tag, consider using a bundler like Browserify browserify, Rollup, or Webpack and include or require instead. See below.

Usage

As a command line tool:

$ cronli5 "* * * * *"
Runs every minute.

Including cronli5.min.js in a script tag will expose cronli5 as a global object.

Import with require:

var cronli5 = require('cronli5');

Import as an ESNext module:

import cronli5 from 'cronli5';

Programmatic usage (ES5):

// Cron patterns can be represented as strings
var cronString = '*/5 * * * *';

// Cron patterns can be represented as arrays of cron fields
var cronArray = ['*/5', '*', '*', '*', '*'];

// Cron patterns can be represented as objects
var cronObject = {
  minute: '*/5',
  hour: '*',
  date: '*',
  month: '*',
  weekday: '*',
};

var expectedOutput = 'every five minutes';

expect(cronli5(cronString)).to.equal(expectedOutput);
expect(cronli5(cronArray)).to.equal(expectedOutput);
expect(cronli5(cronObject)).to.equal(expectedOutput);

Options

The cronli5 function takes an options object as its second parameter with several boolean flag properties supported:

• ampm — Default true: Use 12-hour time if true, 24-hour time if false.
• short — Default false. Use abbreviatted forms if true.
• seconds — Default false. Always treat the first field of strings and of arrays as the second field if true.
• years — Default false. Treat six field string or array patterns as if the last field is the year field if true.

On Timezones

cronli5 always describes the pattern in whatever timezone the cron pattern is being run. This utility does not, nor does it ever intend to, deal with timezone conversions because, firstly, that functionality would require some non-trivial dependencies (like moment with moment-timezone moment-timezone) to even approximate correctness and, secondly, the output would still be wrong anyways because timezones are problematic. To be accurate, associate the description with a timezone (e.g. America/Phoenix).

About

The project name is a reference to the phrase [Explain Like I'm Five (ELI5)] eli5, which is used to ask for a friendly, simplified, and layman-accessible summary of material that may be hard to understand without some background.

cronli5 was partially inspired by prettycron, which itself is based on code from a gist by dunse. Although prettycron was close to meeting my needs, I wasn't fully satisfied with the output and was limited by the lack of support for extended cron patterns. cronli5 tries to render as many cron patterns in as direct and idiomatic English as possible.

cronli5 was written from scratch and has no production dependencies. Its source does not borrow code, in whole or in part, from prettycron prettycron, Stack Overflow answers, or any other project. Any resemblance to other code, living or dead, is purely coincidental.

License

MIT License
Copyright © 2016 Andrew Broz