clockwork

Types

Cron

Represents a valid cron expression with fields for minute, hour, day, month, and weekday

pub type Cron {
  Cron(
    minute: CronField,
    hour: CronField,
    day: CronField,
    month: CronField,
    weekday: CronField,
  )
}

Constructors

Cron(
  minute: CronField,
  hour: CronField,
  day: CronField,
  month: CronField,
  weekday: CronField,
)

CronError

</>

Represents the possible errors when parsing a cron expression

pub type CronError {
  InvalidFieldCount(actual: Int)
  InvalidMinute(value: String, reason: String)
  InvalidHour(value: String, reason: String)
  InvalidDay(value: String, reason: String)
  InvalidMonth(value: String, reason: String)
  InvalidWeekday(value: String, reason: String)
  InvalidStep(field: String, step: String, reason: String)
  InvalidRange(value: String, reason: String)
}

Constructors

```
InvalidFieldCount(actual: Int)
```
Invalid number of fields in the expression (expected exactly 5)

InvalidMinute(value: String, reason: String)

Invalid minute field (must be between 0-59)

InvalidHour(value: String, reason: String)

Invalid hour field (must be between 0-23)

InvalidDay(value: String, reason: String)

Invalid day field (must be between 1-31)

```
InvalidMonth(value: String, reason: String)
```
Invalid month field (must be between 1-12 or a valid month name)
```
InvalidWeekday(value: String, reason: String)
```
Invalid weekday field (must be between 0-6 or a valid weekday name)

InvalidStep(field: String, step: String, reason: String)

Invalid step value

InvalidRange(value: String, reason: String)

Invalid range format

CronField

opaque </>

Represents the different types of fields in a cron expression

pub opaque type CronField

Functions

default

</>

pub fn default() -> Cron

Default cron struct with all fields set to wildcard.

every

</>

pub fn every(step: Int) -> CronField

Create a cron field that represents “every nth time unit”.

This is equivalent to the “*/n” syntax in cron expressions.

Parameters

step: The step increment

Example

// Every 15 minutes
let field = clockwork.every(15)

every_time

</>

pub fn every_time() -> CronField

Create a wildcard field for a cron expression.

A wildcard (*) means “every possible value” for that field. For example, a wildcard in the hour field means “every hour”.

Example

// Every hour
let hour_field = clockwork.every_time()

exactly

</>

pub fn exactly(at v: Int) -> CronField

Create a field that matches exactly one specific value.

Parameters

at: The exact value to match

Example

// At minute 30
let minute_field = clockwork.exactly(at: 30)

format_error

</>

pub fn format_error(error: CronError) -> String

Formats a CronError into a human-readable error message

from_string

</>

pub fn from_string(cron: String) -> Result(Cron, CronError)

Parse a cron string into a Cron struct. Returns a Result with either a valid Cron struct or a detailed CronError.

Standard cron format: minute hour day month weekday

list

</>

pub fn list(fields: List(CronField)) -> CronField

Create a list field that matches any of the provided fields.

This is equivalent to the comma-separated values in cron expressions.

Parameters

fields: A list of cron fields that should be matched

Example

// On Monday, Wednesday, and Friday
let weekdays = clockwork.list([
  clockwork.exactly(1),  // Monday
  clockwork.exactly(3),  // Wednesday
  clockwork.exactly(5),  // Friday
])

next_occurrence

</>

pub fn next_occurrence(
  given cron: Cron,
  from from: Timestamp,
  with_offset offset: Duration,
) -> Timestamp

Calculate the next occurrence of a cron job after the given timestamp.

This function computes when a job with the given cron expression should next run, starting from the provided timestamp and considering the timezone offset.

Parameters

cron: The cron expression to calculate the next occurrence for
from: The timestamp to start calculating from
offset: The timezone offset to apply (e.g., UTC, local time)

Returns

A timestamp representing the next time this cron job should run. The returned timestamp will always have seconds set to zero.

Example

// Find the next time a daily noon job will run
let cron = clockwork.from_string("0 12 * * *") |> result.unwrap(clockwork.default())
let next = clockwork.next_occurrence(
  given: cron,
  from: timestamp.system_time(),
  with_offset: calendar.utc_offset
)

ranging

</>

pub fn ranging(from start: Int, to end: Int) -> CronField

Create a range field that matches any value between start and end (inclusive).

This is equivalent to the “start-end” syntax in cron expressions.

Parameters

start: The beginning value of the range (inclusive)
end: The ending value of the range (inclusive)

Example

// Hours 9 through 17 (9am-5pm)
let work_hours = clockwork.ranging(from: 9, to: 17)

ranging_every

</>

pub fn ranging_every(
  step: Int,
  from start: Int,
  to end: Int,
) -> CronField

Create a range with a step value.

This creates a cron field that represents a range with a specific step increment. For example, “10-30/5” means “every 5th minute from 10 through 30”.

Parameters

step: The step increment
start: The start of the range (inclusive)
end: The end of the range (inclusive)

Example

// Every 5 minutes from 10 through 30
let field = clockwork.ranging_every(5, from: 10, to: 30)

stepping

</>

pub fn stepping(every step: Int, from from: Int) -> CronField

Create a cron field that starts at a specific value and repeats at the given interval.

This is equivalent to the “n/m” syntax in cron expressions.

Parameters

step: The interval between executions
from: The starting value

Example

// Every 15 minutes starting from minute 5 (5, 20, 35, 50)
let field = clockwork.stepping(every: 15, from: 5)

to_string

</>

pub fn to_string(cron: Cron) -> String

Convert a Cron struct into a standard cron expression string.

This function serializes a Cron struct back into the standard cron string format (minute hour day month weekday).

Parameters

cron: The Cron struct to convert to a string

Returns

A string in standard cron format

Example

let cron = 
  clockwork.default()
  |> clockwork.with_minute(clockwork.exactly(0))
  |> clockwork.with_hour(clockwork.exactly(12))

// Will return "0 12 * * *"
let cron_string = clockwork.to_string(cron)

with_day

</>

pub fn with_day(cron: Cron, day: CronField) -> Cron

Set the day field of a cron struct.

with_hour

</>

pub fn with_hour(cron: Cron, hour: CronField) -> Cron

Set the hour field of a cron struct.

with_minute

</>

pub fn with_minute(cron: Cron, minute: CronField) -> Cron

Set the minute field of a cron struct.

with_month

</>

pub fn with_month(cron: Cron, month: CronField) -> Cron

Set the month field of a cron struct.

with_weekday

</>

pub fn with_weekday(cron: Cron, weekday: CronField) -> Cron

Set the weekday field of a cron struct. Weekdays are 0-indexed, starting from Sunday.