CronstrueEx

CronstrueEx is an Elixir library that converts cron expressions into clear, human-readable descriptions.

It follows the behavior and public options of the npm package cRonstrue as closely as practical, while providing an idiomatic Elixir API and no runtime dependencies.

[!IMPORTANT] CronstrueEx is under active development. The current release implements a useful subset of cRonstrue, but compatibility is not complete and the API may change before the first stable release. The package is not published on Hex yet.

Current functionality

• Standard five-field cron expressions: minute, hour, day of month, month, and day of week.
• Numeric values, wildcards, lists, ranges, and increments.
• Case-insensitive three-letter English month and weekday names such as JAN and MON.
• Human-readable descriptions in English and Spanish.
• Locale-specific clock defaults: English uses 12 hours and Spanish uses 24 hours.
• Concise and verbose descriptions.
• Configurable hour formatting and parse-error handling.
• Validation of the syntax and ranges currently supported by the parser.

Usage

English is the default locale:

CronstrueEx.to_string("* * * * *")
# => "Every minute"

CronstrueEx.to_string("*/5 * * * *")
# => "Every 5 minutes"

CronstrueEx.to_string("30 11 * * 1-5")
# => "At 11:30 AM, Monday through Friday"

CronstrueEx.to_string("23 12 15 Jan-Mar *")
# => "At 12:23 PM, on day 15 of the month, January through March"

Select Spanish with locale: "es" or locale: :es:

CronstrueEx.to_string("*/5 * * * *", locale: "es")
# => "Cada 5 minutos"

CronstrueEx.to_string("30 23 * * MON-FRI", locale: :es)
# => "A las 23:30, de lunes a viernes"

Supported syntax

Names are accepted only in English in the cron expression, regardless of the output locale. For example, use MON-FRI when requesting either English or Spanish output.

Options

Options are passed as a keyword list to CronstrueEx.to_string/2:

For example:

CronstrueEx.to_string("30 22 * * *", use_24_hour_time_format: true)
# => "At 22:30"

CronstrueEx.to_string("* * * * *", verbose: true)
# => "Every minute, every hour, every day"

Invalid expressions raise CronstrueEx.ParseError by default. A localized generic message can be returned instead:

CronstrueEx.to_string("invalid", locale: "es", throw_exception_on_parse_error: false)
# => "Ocurrió un error mientras se generaba la descripción de la expresión. Revise la sintaxis de la expresión de cron."

Current limitations

• Only five-field expressions are supported.
• Seconds and year fields are not supported.
• Quartz syntax such as ?, L, W, and # is not supported.
• Cron nicknames such as @daily, @weekly, and @reboot are not supported.
• Some complex combinations may not yet produce exactly the same description as cRonstrue.
• CronstrueEx describes schedules; it does not calculate future executions or run scheduled jobs.

Roadmap

Planned work includes broader parity for five-field expressions, six- and seven-field expressions, cron nicknames, Quartz syntax, additional formatting options, and more locales. Features will be added incrementally with compatibility tests derived from cRonstrue v3.24.0.

Requirements

• Elixir 1.14 or later

Installation

CronstrueEx is not available on Hex yet. Once published, it is expected to be installed by adding it to the dependencies in mix.exs:

def deps do
  [
    {:cronstrue_ex, "~> 0.1.0"}
  ]
end

Until then, clone the repository to try or contribute to the project.

Development

Run the test suite:

mix test

Check formatting and compile with warnings treated as errors:

mix format --check-formatted
mix compile --warnings-as-errors

License

CronstrueEx is released under the MIT License. See LICENSE for details. Its behavior and parts of its locale wording are based on the MIT-licensed cRonstrue project.