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.zoneUnsafeMakeNamed("Europe/Rome"), // Optional time zone
13
})

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 unsafeParse.

parse

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

Example (Safely Parsing a Cron Expression)

1
import { Either, 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 eitherCron = Cron.parse(expression)
9

10
if (Either.isRight(eitherCron)) {
11
  // Successfully parsed
12
  console.log("Parsed cron:", eitherCron.right)
13
} else {
14
  // Parsing failed
15
  console.error("Failed to parse cron:", eitherCron.left.message)
16
}

unsafeParse

The unsafeParse(cronExpression, tz?) function works like parse, but instead of returning an Either, 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.unsafeParse("0 0 4 8-14 * *")

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.unsafeParse("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
// Output: 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.unsafeParse("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
// Output: 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.unsafeParse("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
console.log(iterator.next().value)
15
// Output: 2021-01-08T04:00:00.000Z
16

17
// Get the second matching date after the start date
18
console.log(iterator.next().value)
19
// Output: 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, TestClock, Fiber, TestContext, Cron, Console } from "effect"
2

3
// A helper function to log output at each interval of the schedule
4
const log = <A>(
5
  action: Effect.Effect<A>,
6
  schedule: Schedule.Schedule<[number, number], void>,
7
): void => {
8
  let i = 0
9

10
  Effect.gen(function* () {
11
    const fiber: Fiber.RuntimeFiber<[[number, number], number]> = yield* Effect.gen(function* () {
29 collapsed lines
12
      yield* action
13
      i++
14
    }).pipe(
15
      Effect.repeat(
16
        schedule.pipe(
17
          // Limit the number of iterations for the example
18
          Schedule.intersect(Schedule.recurs(10)),
19
          Schedule.tapOutput(([Out]) =>
20
            Console.log(i === 11 ? "..." : [new Date(Out[0]), new Date(Out[1])]),
21
          ),
22
        ),
23
      ),
24
      Effect.fork,
25
    )
26
    yield* TestClock.adjust(Infinity)
27
    yield* Fiber.join(fiber)
28
  }).pipe(Effect.provide(TestContext.TestContext), Effect.runPromise)
29
}
30

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

35
// Convert the Cron into a Schedule
36
const schedule = Schedule.cron(cron)
37

38
// Define a dummy action to repeat
39
const action = Effect.void
40

41
// Log the schedule intervals
42
log(action, schedule)
43
/*
44
Output:
45
[ 1970-01-08T04:00:00.000Z, 1970-01-08T04:00:01.000Z ]
46
[ 1970-01-09T04:00:00.000Z, 1970-01-09T04:00:01.000Z ]
47
[ 1970-01-10T04:00:00.000Z, 1970-01-10T04:00:01.000Z ]
48
[ 1970-01-11T04:00:00.000Z, 1970-01-11T04:00:01.000Z ]
49
[ 1970-01-12T04:00:00.000Z, 1970-01-12T04:00:01.000Z ]
50
[ 1970-01-13T04:00:00.000Z, 1970-01-13T04:00:01.000Z ]
51
[ 1970-01-14T04:00:00.000Z, 1970-01-14T04:00:01.000Z ]
52
[ 1970-02-08T04:00:00.000Z, 1970-02-08T04:00:01.000Z ]
53
[ 1970-02-09T04:00:00.000Z, 1970-02-09T04:00:01.000Z ]
54
[ 1970-02-10T04:00:00.000Z, 1970-02-10T04:00:01.000Z ]
55
...
56
*/