automata - v0.2.0

automata/schedule

Types

IterStep

</>

Result of stepping an OccurrenceIterator.

Yield(at, next) carries the validated occurrence and the next iterator state. Done signals the schedule has been exhausted (RRULE COUNT reached, RRULE UNTIL exceeded, Once consumed, or a pathological cron iteration hit its safety guard).

pub type IterStep {
  Yield(at: ast.ValidDateTime, next: OccurrenceIterator)
  Done
}

Constructors

OccurrenceIterator

opaque </>

Iterator over future occurrences of a Schedule.

opaque because the cursor (and any per-variant counter such as the RRULE yielded count) must stay synchronised with the embedded plan. An externally-constructed iterator could break COUNT enforcement or skip occurrences.

pub opaque type OccurrenceIterator

Schedule

opaque </>

A unified schedule.

opaque so the only way to obtain a value is through from_* smart constructors; this prevents callers from forging “validated” schedules and lets us add new variants (timezones, solar times, 7-field cron) without breaking existing code.

pub opaque type Schedule

ScheduleError

</>

Errors raised at the schedule boundary.

Carries enough context that LLMs and operators can understand what failed and what value caused it without parsing strings.

pub type ScheduleError {
  EveryIntervalMustBePositive(actual: Int)
  InvalidRRuleAnchor(at: ast.DateTime)
}

Constructors 

  • EveryIntervalMustBePositive(actual: Int)
  • InvalidRRuleAnchor(at: ast.DateTime)

Values

from_cron

</> 
pub fn from_cron(
  spec spec: validator.ValidCron,
) -> Result(Schedule, ScheduleError)

Build a Schedule from a validated cron expression.

Cron schedules are infinite; iterators never return Done on well-formed input. The return type is Result so that this constructor shares one shape with from_rrule, from_every, and from_once, letting generic helpers treat the four uniformly. The current implementation cannot fail (a ValidCron cannot produce a normalisation error), so callers can let assert Ok(_) = ... with confidence.

from_every

</> 
pub fn from_every(
  interval_seconds interval_seconds: Int,
  anchor anchor: ast.ValidDateTime,
) -> Result(Schedule, ScheduleError)

Build an interval Schedule that fires interval_seconds apart starting at anchor (inclusive).

Returns EveryIntervalMustBePositive when the interval is zero or negative.

from_once

</> 
pub fn from_once(
  at at: ast.ValidDateTime,
) -> Result(Schedule, ScheduleError)

Build a one-shot Schedule that fires exactly once at at.

The return type is Result so that this constructor shares one shape with from_rrule, from_every, and from_cron. The current implementation cannot fail (the at argument is already a ValidDateTime), so callers can let assert Ok(_) = ... with confidence.

from_rrule

</> 
pub fn from_rrule(
  spec spec: validator.ValidRRule,
  anchor anchor: ast.ValidDateTime,
) -> Result(Schedule, ScheduleError)

Build a Schedule from a validated RRULE plus an anchor.

The anchor seeds defaults for unspecified BYHOUR / BYMINUTE / BYDAY / BYMONTH / BYMONTHDAY and contributes the second component for every yielded occurrence.

iterator_after

</> 
pub fn iterator_after(
  schedule schedule: Schedule,
  boundary boundary: ast.Boundary,
) -> OccurrenceIterator

Build an iterator over occurrences strictly satisfying boundary.

matches

</> 
pub fn matches(
  schedule schedule: Schedule,
  at at: ast.ValidDateTime,
) -> Bool

Return True when at is an occurrence of schedule.

Pure: same inputs always produce the same output.

next_after

</> 
pub fn next_after(
  schedule schedule: Schedule,
  after after: ast.ValidDateTime,
) -> option.Option(ast.ValidDateTime)

Return the next occurrence strictly after after, if any.

Equivalent to stepping iterator_after(schedule, Exclusive(after)) once.

step

</> 
pub fn step(iterator iterator: OccurrenceIterator) -> IterStep

Advance an iterator by one occurrence.

✨ Search Document