Cron
Utilities for recurring calendar schedules written as cron expressions or explicit field constraints. A Cron value stores allowed seconds, minutes, hours, days of month, months, weekdays, and an optional time zone. The module can create or parse schedules, compare them, test whether a date matches, and find previous or next scheduled occurrences.
Constructors
Signature
declare function make(values: {
readonly and?: boolean;
readonly days: Iterable<number>;
readonly hours: Iterable<number>;
readonly minutes: Iterable<number>;
readonly months: Iterable<number>;
readonly seconds?: Iterable<number, any, any>;
readonly tz?: TimeZone;
readonly weekdays: Iterable<number>;
}): Cron;Parses a cron expression safely into a Cron instance, returning a Result instead of throwing.
When to use
Use to parse cron expressions from configuration or user input while handling invalid input as a Result.
Details
The expression may contain five fields, where seconds default to 0, or six fields including seconds. Fields support *, comma-separated values, ranges, steps, and month or weekday aliases. Invalid expressions fail with CronParseError. When both the day-of-month and weekday fields are restricted, a date matches if either field matches. When either field starts with *, both fields must match; an unrestricted field always matches.
See
parseUnsafefor throwing on invalid cron expressionsmakefor constructing a schedule from explicit field constraints
Signature
declare function parse(cron: string, tz?: string | TimeZone): Result<Cron, CronParseError>;parseUnsafe
Parses a cron expression into a Cron instance, throwing on failure.
When to use
Use when you expect the input to be valid and want to avoid handling the Result type.
Signature
declare function parseUnsafe(cron: string, tz?: string | TimeZone): Cron;Errors
CronParseError
Represents an error that occurs when parsing a cron expression fails.
When to use
Use to handle invalid cron expression failures returned by parse.
Details
This error provides information about what went wrong during parsing, including the error message and optionally the input that caused the error.
See
parsefor the parser that returns this error inResult.failisCronParseErrorfor narrowing unknown values to this error type
Signature
declare class CronParseError extends YieldableError<this> & {
readonly _tag: "CronParseError";
} & Readonly<{
readonly input?: string;
readonly message: string;
}> {
constructor(args: {
readonly input?: string;
readonly message: string;
});
readonly "~effect/time/Cron/CronParseError": "~effect/time/Cron/CronParseError";
}Getters
Returns the next scheduled date/time for the given Cron instance.
When to use
Use to find the next occurrence of a cron schedule after a specific date/time or after the current time.
Details
Searches for the next date and time when the cron schedule should trigger, starting after the specified date/time or after the current time when no date is provided.
See
Signature
declare function next(cron: Cron, now?: Input): Date;Returns the previous scheduled date/time for the given Cron instance.
When to use
Use to find the most recent occurrence of a cron schedule before a specific date/time or before the current time.
Details
When no date/time is provided, the search starts from the current time.
Gotchas
The search is strict: if the supplied date/time already matches the schedule, the result is the earlier occurrence.
See
nextfor finding the next scheduled occurrence
Signature
declare function prev(cron: Cron, now?: Input): Date;Guards
Checks whether a given value is a Cron instance.
When to use
Use to narrow an unknown value before treating it as a Cron schedule.
Details
This function is a type guard that determines whether the provided value is a valid Cron instance by checking for the presence of the Cron type identifier.
See
Signature
declare function isCron(u: unknown): u is Cron;isCronParseError
Checks whether a given value is a CronParseError instance.
When to use
Use to narrow an unknown failure before handling it as a cron parse error.
Details
This function is a type guard that determines whether the provided value is a CronParseError by checking for the presence of the CronParseError type identifier.
See
CronParseErrorfor the parse error typeparsefor producingCronParseErrorvalues on invalid input
Signature
declare function isCronParseError(u: unknown): u is CronParseError;Instances
Equivalence
Equivalence instance for comparing the timezone, field restrictions, and day-matching mode of two Cron schedules.
When to use
Use to compare cron schedules through APIs that accept an equivalence relation.
Details
This comparison checks the optional timezone, the and day-matching mode, seconds, minutes, hours, days, months, and weekdays.
See
equalsfor directly comparing twoCronvalues
Signature
declare const Equivalence: Equ.Equivalence<Cron>;Models
Represents a cron schedule with time constraints and timezone information.
When to use
Use to represent a recurring calendar schedule that can be matched against dates or used to compute scheduled occurrences.
Details
A Cron instance defines when a scheduled task should run, supporting seconds, minutes, hours, days, months, and weekday constraints. It also supports timezone-aware scheduling.
See
Signature
interface Cron extends Pipeable, Equal, Inspectable {
readonly "~effect/time/Cron": "~effect/time/Cron";
readonly days: ReadonlySet<number>;
readonly hours: ReadonlySet<number>;
readonly minutes: ReadonlySet<number>;
readonly months: ReadonlySet<number>;
readonly seconds: ReadonlySet<number>;
readonly tz: Option<TimeZone>;
readonly weekdays: ReadonlySet<number>;
}Predicates
Checks whether two Cron instances have equal timezone values, field restrictions, and day-matching modes.
When to use
Use to directly compare two cron schedules, including their timezones and day-matching modes.
Details
The comparison checks the optional timezone, the and day-matching mode, seconds, minutes, hours, days, months, and weekdays.
See
Equivalencefor the reusable equivalence instance
Signature
declare const equals: {
(that: Cron): (self: Cron) => boolean;
(self: Cron, that: Cron): boolean;
};Returns true when a date/time matches a Cron schedule.
When to use
Use to test whether a specific date/time satisfies a cron schedule.
Details
The schedule's timezone determines which calendar fields are read from the input; the host system's timezone is used when the schedule has no timezone. Seconds, minutes, hours, and months are checked against their restrictions; an empty set leaves that field unrestricted. If only days or weekdays is restricted, that field must match. If both are restricted, either may match unless the schedule was created with and: true, which requires both to match.
See
Signature
declare function match(cron: Cron, date: Input): boolean;Sequencing
Returns an infinite iterator that yields dates matching the Cron schedule.
When to use
Use to lazily iterate future occurrences of a cron schedule.
Details
The iterator generates an infinite sequence of dates when the cron schedule should trigger, starting after the specified date/time or after the current time when no date is provided.
See
nextfor computing one next occurrence
Signature
declare function sequence(cron: Cron, now?: Input): IterableIterator<Date>;
Creates a Cron instance from time constraints.
When to use
Use to build a cron schedule from explicit sets of allowed time-field values.
Details
Constructs a cron schedule by specifying which seconds, minutes, hours, days, months, and weekdays the schedule should match. Empty arrays leave a time unit unrestricted. If only days or weekdays are restricted, that field must match. When both are restricted, the default matches either field; set
and: trueto require both fields to match. Weekdays range from0(Sunday) to7(also Sunday). The constructor throws aRangeErrorwhen a field contains a non-integer or out-of-range value.See
parsefor building a schedule from a cron expression string