Cron

The Cron module lets you define schedules in a style similar to UNIX cron expressions. It also supports partial constraints (e.g., certain months or weekdays), time zone awareness through the DateTime module, and robust error handling.

This module helps you:

Create a Cron instance from individual parts.
Parse and validate cron expressions.
Match existing dates to see if they satisfy a given cron schedule.
Find the next occurrence of a schedule after a given date.
Iterate over future dates that match a schedule.
Convert a Cron instance to a Schedule for use in effectful programs.

Creating a Cron

You can define a cron schedule by specifying numeric constraints for seconds, minutes, hours, days, months, and weekdays. The make function requires you to define all fields representing the schedule’s constraints.

Example (Creating a Cron)

1
import { Cron, DateTime } from "effect"
2

3
// Build a cron that triggers at 4:00 AM
4
// on the 8th to the 14th of each month
5
const cron = Cron.make({
6
  seconds: [0], // Trigger at the start of a minute
7
  minutes: [0], // Trigger at the start of an hour
8
  hours: [4], // Trigger at 4:00 AM
9
  days: [8, 9, 10, 11, 12, 13, 14], // Specific days of the month
10
  months: [], // No restrictions on the month
11
  weekdays: [], // No restrictions on the weekday
12
  tz: DateTime.zoneMakeNamedUnsafe("Europe/Rome"), // Optional time zone
13
})
14

15
const hours = [...cron.hours]
16
hours // => [4]

seconds, minutes, and hours: Define the time of day.
days and months: Specify which calendar days and months are valid.
weekdays: Restrict the schedule to specific days of the week.
tz: Optionally define the time zone for the schedule.

If any field is left empty (e.g., months), it is treated as having “no constraints,” allowing any valid value for that part of the date.

Parsing Cron Expressions

Instead of manually constructing a Cron, you can use UNIX-like cron strings and parse them with parse or parseUnsafe.

parse

The parse(cronExpression, tz?) function safely parses a cron string into a Cron instance. It returns a Result, which will contain either the parsed Cron or a parsing error.

Example (Safely Parsing a Cron Expression)

1
import { Result, Cron } from "effect"
2

3
// Define a cron expression for 4:00 AM
4
// on the 8th to the 14th of every month
5
const expression = "0 0 4 8-14 * *"
6

7
// Parse the cron expression
8
const result = Cron.parse(expression)
9

10
if (Result.isSuccess(result)) {
11
  // Successfully parsed
12
  console.log("Parsed cron:", result.success)
13
} else {
14
  // Parsing failed
15
  console.error("Failed to parse cron:", result.failure.message)
16
}
17

18
Result.isSuccess(result) // => true

parseUnsafe

The parseUnsafe(cronExpression, tz?) function works like parse, but instead of returning a Result, it throws an exception if the input is invalid.

Example (Parsing a Cron Expression)

1
import { Cron } from "effect"
2

3
// Parse a cron expression for 4:00 AM
4
// on the 8th to the 14th of every month
5
// Throws if the expression is invalid
6
const cron = Cron.parseUnsafe("0 0 4 8-14 * *")
7

8
const hours = [...cron.hours]
9
hours // => [4]

Checking Dates with match

The match function allows you to determine if a given Date (or any DateTime.Input) satisfies the constraints of a cron schedule.

If the date meets the schedule’s conditions, match returns true. Otherwise, it returns false.

Example (Checking if a Date Matches a Cron Schedule)

1
import { Cron } from "effect"
2

3
// Suppose we have a cron that triggers at 4:00 AM
4
// on the 8th to the 14th of each month
5
const cron = Cron.parseUnsafe("0 0 4 8-14 * *")
6

7
const checkDate = new Date("2025-01-08 04:00:00")
8

9
console.log(Cron.match(cron, checkDate))
10
Cron.match(cron, checkDate) // => true

Finding the Next Run

The next function determines the next date that satisfies a given cron schedule, starting from a specified date. If no starting date is provided, the current time is used as the starting point.

If next cannot find a matching date within a predefined number of iterations, it throws an error to prevent infinite loops.

Example (Determining the Next Matching Date)

1
import { Cron } from "effect"
2

3
// Define a cron expression for 4:00 AM
4
// on the 8th to the 14th of every month
5
const cron = Cron.parseUnsafe("0 0 4 8-14 * *", "UTC")
6

7
// Specify the starting point for the search
8
const after = new Date("2025-01-08")
9

10
// Find the next matching date
11
const nextDate = Cron.next(cron, after)
12

13
console.log(nextDate)
14
nextDate.toISOString() // => "2025-01-08T04:00:00.000Z"

Iterating Over Future Dates

To generate multiple future dates that match a cron schedule, you can use the sequence function. This function provides an infinite iterator of matching dates, starting from a specified date.

Example (Generating Future Dates with an Iterator)

1
import { Cron } from "effect"
2

3
// Define a cron expression for 4:00 AM
4
// on the 8th to the 14th of every month
5
const cron = Cron.parseUnsafe("0 0 4 8-14 * *", "UTC")
6

7
// Specify the starting date
8
const start = new Date("2021-01-08")
9

10
// Create an iterator for the schedule
11
const iterator = Cron.sequence(cron, start)
12

13
// Get the first matching date after the start date
14
const first = iterator.next().value
15
console.log(first)
16
first?.toISOString() // => "2021-01-08T04:00:00.000Z"
17

18
// Get the second matching date after the start date
19
const second = iterator.next().value
20
console.log(second)
21
second?.toISOString() // => "2021-01-09T04:00:00.000Z"

Converting to Schedule

The Schedule module allows you to define recurring behaviors, such as retries or periodic events. The cron function bridges the Cron module with the Schedule module, enabling you to create schedules based on cron expressions or Cron instances.

cron

The Schedule.cron function generates a Schedule that triggers at the start of each interval defined by the provided cron expression or Cron instance. When triggered, the schedule produces a tuple [start, end] representing the timestamps (in milliseconds) of the cron interval window.

Example (Creating a Schedule from a Cron)

1
import { Effect, Schedule, Fiber, Cron, Console, Duration } from "effect"
2
import { TestClock } from "effect/testing"
3

27 collapsed lines
4
// A helper function to log output at each interval of the schedule
5
const log = <A>(
6
  action: Effect.Effect<A>,
7
  schedule: Schedule.Schedule<Duration.Duration, unknown, Cron.CronParseError>,
8
) => {
9
  let i = 0
10

11
  return Effect.gen(function* () {
12
    const fiber = yield* Effect.gen(function* () {
13
      yield* action
14
      i++
15
    }).pipe(
16
      Effect.repeat(
17
        schedule.pipe(
18
          // Limit the number of iterations for the example
19
          Schedule.upTo({ times: 10 }),
20
          Schedule.tap(({ now, output }) =>
21
            Console.log(
22
              i === 11 ? "..." : new Date(now + Duration.toMillis(output)),
23
            ),
24
          ),
25
        ),
26
      ),
27
      Effect.forkChild,
28
    )
29
    yield* TestClock.adjust(Infinity)
30
    yield* Fiber.join(fiber)
31
  }).pipe(Effect.provide(TestClock.layer()), Effect.runPromise)
32
}
33

34
// Build a cron that triggers at 4:00 AM
35
// on the 8th to the 14th of each month
36
const cron = Cron.parseUnsafe("0 0 4 8-14 * *", "UTC")
37

38
// Convert the Cron into a Schedule
39
const schedule = Schedule.cron(cron)
40

41
// Define a dummy action to repeat
42
const action = Effect.void
43

44
// Log the schedule intervals
45
await log(action, schedule)
46
/*
47
Output:
48
1970-01-08T04:00:00.000Z
49
1970-01-09T04:00:00.000Z
50
1970-01-10T04:00:00.000Z
51
1970-01-11T04:00:00.000Z
52
1970-01-12T04:00:00.000Z
53
1970-01-13T04:00:00.000Z
54
1970-01-14T04:00:00.000Z
55
1970-02-08T04:00:00.000Z
56
1970-02-09T04:00:00.000Z
57
1970-02-10T04:00:00.000Z
58
...
59
*/
60

61
// The schedule fires at the same instants the Cron itself reports,
62
// starting from the Unix epoch (TestClock starts at time 0)
63
const iterator = Cron.sequence(cron, new Date(0))
64
const firstTen = Array.from({ length: 10 }, () =>
65
  iterator.next().value?.toISOString(),
66
)
67
firstTen // => ["1970-01-08T04:00:00.000Z", "1970-01-09T04:00:00.000Z", "1970-01-10T04:00:00.000Z", "1970-01-11T04:00:00.000Z", "1970-01-12T04:00:00.000Z", "1970-01-13T04:00:00.000Z", "1970-01-14T04:00:00.000Z", "1970-02-08T04:00:00.000Z", "1970-02-09T04:00:00.000Z", "1970-02-10T04:00:00.000Z"]