Cyclium.Cron (Cyclium v0.2.0)

Copy Markdown View Source

Minimal UTC cron expression parser and next-occurrence calculator, backing the native {:cron, spec} expectation trigger.

Supported syntax

Standard 5-field crontab: minute hour day-of-month month day-of-week.

  • * — every value
  • a — a single value
  • a-b — an inclusive range
  • a,b,c — a list
  • */n, a-b/n — steps

Day-of-week is 0..6 with Sunday = 0 (7 is also accepted as Sunday). When both day-of-month and day-of-week are restricted (neither is *), a timestamp matches if either field matches — the standard Vixie-cron rule.

Macros

@yearly / @annually   0 0 1 1 *
@monthly              0 0 1 * *
@weekly               0 0 * * 0
@daily / @midnight    0 0 * * *
@hourly               0 * * * *

Time zone

All matching and next/2 math are in UTC. There is no time-zone or DST handling — "0 5 * * *" means 05:00 UTC, every day.

Examples

iex> {:ok, c} = Cyclium.Cron.parse("0 5 * * *")
iex> Cyclium.Cron.next(c, ~U[2026-06-05 04:59:30Z])
~U[2026-06-05 05:00:00Z]

Summary

Types

t()

Functions

match?(cron, dt)

Returns true if dt (UTC) matches the cron expression.

next(cron, from)

First occurrence strictly after from (UTC), at second :00. Raises if no occurrence falls within 366 days (an impossible spec, e.g. Feb 30).

parse(spec)

Parse a cron expression (or macro) into a t/0. Returns {:error, reason} for malformed input.

parse!(spec)

Raising variant of parse/1 — used for boot-time validation.

Types

t()

@type t() :: %Cyclium.Cron{
  dom: MapSet.t(),
  dom_restricted: boolean(),
  dow: MapSet.t(),
  dow_restricted: boolean(),
  hour: MapSet.t(),
  minute: MapSet.t(),
  month: MapSet.t()
}

Functions

match?(cron, dt)

@spec match?(t(), DateTime.t()) :: boolean()

Returns true if dt (UTC) matches the cron expression.

next(cron, from)

@spec next(t(), DateTime.t()) :: DateTime.t()

First occurrence strictly after from (UTC), at second :00. Raises if no occurrence falls within 366 days (an impossible spec, e.g. Feb 30).

parse(spec)

@spec parse(String.t()) :: {:ok, t()} | {:error, term()}

Parse a cron expression (or macro) into a t/0. Returns {:error, reason} for malformed input.

parse!(spec)

@spec parse!(String.t()) :: t()

Raising variant of parse/1 — used for boot-time validation.