effect 4.0.0-beta.99 → 4.0.0-rc.109

package/dist/Cron.js

@@ -11,7 +11,7 @@ import * as Arr from "./Array.js";
 import * as Data from "./Data.js";
 import * as Equal from "./Equal.js";
 import * as Equ from "./Equivalence.js";
-import { format } from "./Formatter.js";
+import { format as formatValue } from "./Formatter.js";
 import { constVoid, dual, pipe } from "./Function.js";
 import * as Hash from "./Hash.js";
 import { NodeInspectSymbol } from "./Inspectable.js";
@@ -24,8 +24,9 @@ import * as Result from "./Result.js";
 import * as String from "./String.js";
 const TypeId = "~effect/time/Cron";
 function toPojo(cron) {
-  return {
+  const out = {
     tz: cron.tz,
+    and: cron.and,
     seconds: Arr.fromIterable(cron.seconds),
     minutes: Arr.fromIterable(cron.minutes),
     hours: Arr.fromIterable(cron.hours),
@@ -33,6 +34,7 @@ function toPojo(cron) {
     months: Arr.fromIterable(cron.months),
     weekdays: Arr.fromIterable(cron.weekdays)
   };
+  return out;
 }
 const CronProto = {
   [TypeId]: TypeId,
@@ -43,18 +45,10 @@ const CronProto = {
     return pipe(Hash.hash(this.tz), Hash.combine(Hash.hash(this.and)), Hash.combine(Hash.array(Arr.fromIterable(this.seconds))), Hash.combine(Hash.array(Arr.fromIterable(this.minutes))), Hash.combine(Hash.array(Arr.fromIterable(this.hours))), Hash.combine(Hash.array(Arr.fromIterable(this.days))), Hash.combine(Hash.array(Arr.fromIterable(this.months))), Hash.combine(Hash.array(Arr.fromIterable(this.weekdays))));
   },
   toObject() {
-    return {
-      tz: this.tz,
-      seconds: Arr.fromIterable(this.seconds),
-      minutes: Arr.fromIterable(this.minutes),
-      hours: Arr.fromIterable(this.hours),
-      days: Arr.fromIterable(this.days),
-      months: Arr.fromIterable(this.months),
-      weekdays: Arr.fromIterable(this.weekdays)
-    };
+    return toPojo(this);
   },
   toString() {
-    return `Cron(${format(toPojo(this))})`;
+    return `Cron(${formatValue(toPojo(this))})`;
   },
   toJSON() {
     const out = toPojo(this);
@@ -83,7 +77,7 @@ const CronProto = {
  *
  * **Example** (Checking cron values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cron } from "effect"
  *
  * const cron = Cron.make({
@@ -94,9 +88,9 @@ const CronProto = {
  *   weekdays: [1, 2, 3, 4, 5]
  * })
  *
- * console.log(Cron.isCron(cron)) // true
- * console.log(Cron.isCron({})) // false
- * console.log(Cron.isCron("not a cron")) // false
+ * Cron.isCron(cron) // => true
+ * Cron.isCron({}) // => false
+ * Cron.isCron("not a cron") // => false
  * ```
  *
  * @see {@link make} for constructing a `Cron` value directly
@@ -116,15 +110,19 @@ export const isCron = u => hasProperty(u, TypeId);
  * **Details**
  *
  * Constructs a cron schedule by specifying which seconds, minutes, hours,
- * days, months, and weekdays the schedule should match. Empty arrays mean
- * "match all" for that time unit. When both days and weekdays are restricted,
- * the default matches either field; set `and: true` to require both fields to
- * match.
+ * 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: true` to require both fields to match. Weekdays range from `0` (Sunday)
+ * to `7` (also Sunday). The constructor throws a `RangeError` when a field
+ * contains a non-integer or out-of-range value.
  *
  * **Example** (Creating schedules from constraints)
  *
- * ```ts
- * import { Cron } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cron, DateTime } from "effect"
+ *
+ * const utc = DateTime.zoneMakeNamedUnsafe("UTC")
  *
  * // Every day at midnight
  * const midnight = Cron.make({
@@ -164,49 +162,22 @@ export const isCron = u => hasProperty(u, TypeId);
  *     31
  *   ],
  *   months: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
- *   weekdays: [0, 1, 2, 3, 4, 5, 6]
+ *   weekdays: [0, 1, 2, 3, 4, 5, 6],
+ *   tz: utc
  * })
  *
  * // Every 15 minutes during business hours on weekdays
  * const businessHours = Cron.make({
  *   minutes: [0, 15, 30, 45],
  *   hours: [9, 10, 11, 12, 13, 14, 15, 16, 17],
- *   days: [
- *     1,
- *     2,
- *     3,
- *     4,
- *     5,
- *     6,
- *     7,
- *     8,
- *     9,
- *     10,
- *     11,
- *     12,
- *     13,
- *     14,
- *     15,
- *     16,
- *     17,
- *     18,
- *     19,
- *     20,
- *     21,
- *     22,
- *     23,
- *     24,
- *     25,
- *     26,
- *     27,
- *     28,
- *     29,
- *     30,
- *     31
- *   ],
+ *   days: [],
  *   months: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
- *   weekdays: [1, 2, 3, 4, 5] // Monday to Friday
+ *   weekdays: [1, 2, 3, 4, 5], // Monday to Friday
+ *   tz: utc
  * })
+ *
+ * Cron.match(midnight, "2024-01-01T00:00:00Z") // => true
+ * Cron.match(businessHours, "2024-01-01T09:15:00Z") // => true
  * ```
  *
  * @see {@link parse} for building a schedule from a cron expression string
@@ -216,12 +187,12 @@ export const isCron = u => hasProperty(u, TypeId);
  */
 export const make = values => {
   const o = Object.create(CronProto);
-  o.seconds = new Set(Arr.sort(values.seconds ?? [0], N.Order));
-  o.minutes = new Set(Arr.sort(values.minutes, N.Order));
-  o.hours = new Set(Arr.sort(values.hours, N.Order));
-  o.days = new Set(Arr.sort(values.days, N.Order));
-  o.months = new Set(Arr.sort(values.months, N.Order));
-  o.weekdays = new Set(Arr.sort(values.weekdays, N.Order));
+  o.seconds = restrictions.seconds(values.seconds ?? [0]);
+  o.minutes = restrictions.minutes(values.minutes);
+  o.hours = restrictions.hours(values.hours);
+  o.days = restrictions.days(values.days);
+  o.months = restrictions.months(values.months);
+  o.weekdays = restrictions.weekdays(values.weekdays);
   o.and = values.and === true;
   o.tz = Option.fromUndefinedOr(values.tz);
   const seconds = Array.from(o.seconds);
@@ -247,24 +218,42 @@ export const make = values => {
     weekday: weekdays[weekdays.length - 1] ?? 6
   };
   o.next = {
-    second: lookupTable(seconds, 60, "next"),
-    minute: lookupTable(minutes, 60, "next"),
-    hour: lookupTable(hours, 24, "next"),
-    day: lookupTable(days, 32, "next"),
-    month: lookupTable(months, 13, "next"),
-    weekday: lookupTable(weekdays, 7, "next")
+    second: lookup.next.second(seconds),
+    minute: lookup.next.minute(minutes),
+    hour: lookup.next.hour(hours),
+    day: lookup.next.day(days),
+    month: lookup.next.month(months),
+    weekday: lookup.next.weekday(weekdays)
   };
   o.prev = {
-    second: lookupTable(seconds, 60, "prev"),
-    minute: lookupTable(minutes, 60, "prev"),
-    hour: lookupTable(hours, 24, "prev"),
-    day: lookupTable(days, 32, "prev"),
-    month: lookupTable(months, 13, "prev"),
-    weekday: lookupTable(weekdays, 7, "prev")
+    second: lookup.prev.second(seconds),
+    minute: lookup.prev.minute(minutes),
+    hour: lookup.prev.hour(hours),
+    day: lookup.prev.day(days),
+    month: lookup.prev.month(months),
+    weekday: lookup.prev.weekday(weekdays)
   };
   return o;
 };
-const lookupTable = (values, size, dir) => {
+const makeRestrictions = (field, min, max, normalize = value => value) => values => {
+  const restrictions = [];
+  for (const value of values) {
+    if (!Number.isInteger(value) || value < min || value > max) {
+      throw new RangeError(`${field} must contain only integers between ${min} and ${max}`);
+    }
+    restrictions.push(normalize(value));
+  }
+  return new Set(Arr.sort(restrictions, N.Order));
+};
+const restrictions = {
+  seconds: /*#__PURE__*/makeRestrictions("seconds", 0, 59),
+  minutes: /*#__PURE__*/makeRestrictions("minutes", 0, 59),
+  hours: /*#__PURE__*/makeRestrictions("hours", 0, 23),
+  days: /*#__PURE__*/makeRestrictions("days", 1, 31),
+  months: /*#__PURE__*/makeRestrictions("months", 1, 12),
+  weekdays: /*#__PURE__*/makeRestrictions("weekdays", 0, 7, value => value === 7 ? 0 : value)
+};
+const makeLookupTable = (size, dir) => values => {
   const result = new Array(size).fill(undefined);
   if (values.length === 0) {
     return result;
@@ -289,6 +278,24 @@ const lookupTable = (values, size, dir) => {
   }
   return result;
 };
+const lookup = {
+  prev: {
+    second: /*#__PURE__*/makeLookupTable(60, "prev"),
+    minute: /*#__PURE__*/makeLookupTable(60, "prev"),
+    hour: /*#__PURE__*/makeLookupTable(24, "prev"),
+    day: /*#__PURE__*/makeLookupTable(32, "prev"),
+    month: /*#__PURE__*/makeLookupTable(13, "prev"),
+    weekday: /*#__PURE__*/makeLookupTable(7, "prev")
+  },
+  next: {
+    second: /*#__PURE__*/makeLookupTable(60, "next"),
+    minute: /*#__PURE__*/makeLookupTable(60, "next"),
+    hour: /*#__PURE__*/makeLookupTable(24, "next"),
+    day: /*#__PURE__*/makeLookupTable(32, "next"),
+    month: /*#__PURE__*/makeLookupTable(13, "next"),
+    weekday: /*#__PURE__*/makeLookupTable(7, "next")
+  }
+};
 const CronParseErrorTypeId = "~effect/time/Cron/CronParseError";
 /**
  * Represents an error that occurs when parsing a cron expression fails.
@@ -304,21 +311,21 @@ const CronParseErrorTypeId = "~effect/time/Cron/CronParseError";
  *
  * **Example** (Handling cron parse failures)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cron, Result } from "effect"
  *
- * const result = Cron.parse("invalid expression")
- * if (Result.isFailure(result)) {
- *   const error: Cron.CronParseError = result.failure
- *   console.log(error.message) // "Invalid number of segments in cron expression"
- *   console.log(error.input) // "invalid expression"
- * }
+ * const expected = Result.fail(new Cron.CronParseError({
+ *   message: "Invalid number of segments in cron expression",
+ *   input: "invalid expression"
+ * }))
+ *
+ * Cron.parse("invalid expression") // => expected
  * ```
  *
  * @see {@link parse} for the parser that returns this error in `Result.fail`
  * @see {@link isCronParseError} for narrowing unknown values to this error type
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class CronParseError extends /*#__PURE__*/Data.TaggedError("CronParseError") {
@@ -339,17 +346,12 @@ export class CronParseError extends /*#__PURE__*/Data.TaggedError("CronParseErro
  *
  * **Example** (Checking cron parse errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cron, Result } from "effect"
  *
- * const result = Cron.parse("invalid cron expression")
- * if (Result.isFailure(result)) {
- *   const error = result.failure
- *   console.log(Cron.isCronParseError(error)) // true
- * }
- *
- * console.log(Cron.isCronParseError(new Error("regular error"))) // false
- * console.log(Cron.isCronParseError("not an error")) // false
+ * Result.mapError(Cron.parse("invalid cron expression"), Cron.isCronParseError) // => Result.fail(true)
+ * Cron.isCronParseError(new Error("regular error")) // => false
+ * Cron.isCronParseError("not an error") // => false
  * ```
  *
  * @see {@link CronParseError} for the parse error type
@@ -373,26 +375,20 @@ export const isCronParseError = u => hasProperty(u, CronParseErrorTypeId);
  * 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`.
+ * `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.
  *
  * **Example** (Parsing cron expressions)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cron, Result } from "effect"
- * import * as assert from "node:assert"
  *
  * // At 04:00 on every day-of-month from 8 through 14.
- * assert.deepStrictEqual(
- *   Cron.parse("0 0 4 8-14 * *"),
- *   Result.succeed(Cron.make({
- *     seconds: [0],
- *     minutes: [0],
- *     hours: [4],
- *     days: [8, 9, 10, 11, 12, 13, 14],
- *     months: [],
- *     weekdays: []
- *   }))
- * )
+ * const cron = Result.getOrThrow(Cron.parse("0 0 4 8-14 * *"))
+ *
+ * Array.from(cron.hours) // => [4]
+ * Array.from(cron.days) // => [8, 9, 10, 11, 12, 13, 14]
  * ```
  *
  * @see {@link parseUnsafe} for throwing on invalid cron expressions
@@ -454,23 +450,81 @@ export const parse = (cron, tz) => {
  *
  * **Example** (Parsing cron expressions unsafely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cron } from "effect"
  *
  * // At 04:00 on every day-of-month from 8 through 14
- * const cron = Cron.parseUnsafe("0 0 4 8-14 * *")
+ * const cron = Cron.parseUnsafe("0 0 4 8-14 * *", "UTC")
  *
  * // With timezone
  * const cronWithTz = Cron.parseUnsafe("0 0 9 * * *", "America/New_York")
  *
  * // This would throw an error
  * // const invalid = Cron.parseUnsafe("invalid expression")
+ * Cron.match(cron, "2024-01-10T04:00:00Z") // => true
+ * Cron.match(cronWithTz, "2024-01-01T14:00:00Z") // => true
  * ```
  *
  * @category constructors
  * @since 4.0.0
  */
 export const parseUnsafe = (cron, tz) => Result.getOrThrow(parse(cron, tz));
+/**
+ * Formats a `Cron` instance as a cron expression.
+ *
+ * **Details**
+ *
+ * The default seconds field (`0`) is omitted unless `includeSeconds` is `true`.
+ * Other seconds configurations are always included.
+ *
+ * **Gotchas**
+ *
+ * Formatting drops the timezone information and the `and` restriction between
+ * days and weekdays. Parsing the result is therefore not guaranteed to produce
+ * an equivalent schedule.
+ *
+ * **Example** (Formatting a cron expression)
+ *
+ * ```ts import.meta.vitest
+ * import { Cron } from "effect"
+ *
+ * const cron = Cron.parseUnsafe("23 0-20/2 * * 0", "UTC")
+ *
+ * Cron.format(cron) // => "23 0-20/2 * * 0"
+ * Cron.format(cron, { includeSeconds: true }) // => "0 23 0-20/2 * * 0"
+ * ```
+ *
+ * @category getters
+ * @since 4.0.0
+ */
+export const format = (cron, options) => {
+  const segments = [cron.seconds, cron.minutes, cron.hours, cron.days, cron.months, cron.weekdays].map(formatSegment);
+  return (options?.includeSeconds !== true && cron.seconds.size === 1 && cron.seconds.has(0) ? segments.slice(1) : segments).join(" ");
+};
+const formatSegment = values => {
+  if (values.size === 0) {
+    return "*";
+  }
+  const array = Array.from(values);
+  const segments = [];
+  let index = 0;
+  while (index < array.length) {
+    const start = array[index];
+    const step = array[index + 1] - start;
+    if (index + 2 < array.length && array[index + 2] - array[index + 1] === step) {
+      let end = index + 2;
+      while (end + 1 < array.length && array[end + 1] - array[end] === step) {
+        end++;
+      }
+      segments.push(`${start}-${array[end]}${step === 1 ? "" : `/${step}`}`);
+      index = end + 1;
+    } else {
+      segments.push(`${start}`);
+      index++;
+    }
+  }
+  return segments.join(",");
+};
 /**
  * Returns `true` when a date/time matches a `Cron` schedule.
  *
@@ -480,27 +534,25 @@ export const parseUnsafe = (cron, tz) => Result.getOrThrow(parse(cron, tz));
  *
  * **Details**
  *
- * Seconds, minutes, hours, months, and the optional timezone are checked
- * directly. For day constraints, an empty `days` or `weekdays` set means that
- * field matches every value; when both sets are non-empty, a date matches if
- * either the day-of-month or weekday matches.
+ * 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.
  *
  * **Example** (Matching dates against a schedule)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cron, Result } from "effect"
  *
- * const cron = Result.getOrThrow(Cron.parse("0 0 4 8-14 * *"))
+ * const cron = Result.getOrThrow(Cron.parse("0 0 4 8-14 * *", "UTC"))
  *
  * // Check if specific dates match
- * const matches1 = Cron.match(cron, new Date("2021-01-08T04:00:00Z"))
- * console.log(matches1) // true - 4 AM on the 8th
- *
- * const matches2 = Cron.match(cron, new Date("2021-01-08T05:00:00Z"))
- * console.log(matches2) // false - wrong hour
- *
- * const matches3 = Cron.match(cron, new Date("2021-01-07T04:00:00Z"))
- * console.log(matches3) // false - wrong day
+ * Cron.match(cron, "2021-01-08T04:00:00Z") // => true
+ * Cron.match(cron, "2021-01-08T05:00:00Z") // => false
+ * Cron.match(cron, "2021-01-07T04:00:00Z") // => false
  * ```
  *
  * @see {@link next} for finding the next matching date/time
@@ -556,19 +608,13 @@ const daysInMonth = date => new Date(Date.UTC(date.getUTCFullYear(), date.getUTC
  *
  * **Example** (Finding the next occurrence)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cron, Result } from "effect"
  *
- * const cron = Result.getOrThrow(Cron.parse("0 0 4 8-14 * *"))
+ * const cron = Result.getOrThrow(Cron.parse("0 0 4 8-14 * *", "UTC"))
  *
  * // Get next run after a specific date
- * const after = new Date("2021-01-01T00:00:00Z")
- * const nextRun = Cron.next(cron, after)
- * console.log(nextRun) // 2021-01-08T04:00:00.000Z
- *
- * // Get next run from current time
- * const nextFromNow = Cron.next(cron)
- * console.log(nextFromNow) // Next occurrence from now
+ * Cron.next(cron, "2021-01-01T00:00:00Z").toISOString() // => "2021-01-08T04:00:00.000Z"
  * ```
  *
  * @see {@link prev} for finding the previous scheduled occurrence
@@ -690,7 +736,7 @@ const stepCron = (cron, now, direction) => {
             const currentWeekday = current.getUTCDay();
             const nextWeekday = table.weekday[currentWeekday];
             if (nextWeekday === undefined) {
-              a = reverse ? currentWeekday - 7 + boundary.weekday : 7 - currentWeekday + boundary.weekday;
+              a = reverse ? boundary.weekday - 7 - currentWeekday : 7 - currentWeekday + boundary.weekday;
             } else {
               a = nextWeekday - currentWeekday;
             }
@@ -700,8 +746,20 @@ const stepCron = (cron, now, direction) => {
             const nextDay = table.day[currentDay];
             if (nextDay === undefined) {
               if (reverse) {
-                const prevMonthDays = daysInMonth(new Date(Date.UTC(current.getUTCFullYear(), current.getUTCMonth(), 0)));
-                b = -(currentDay + (prevMonthDays - boundary.day));
+                const previous = new Date(current);
+                // Day zero is the previous month's last day. These two probes cover every
+                // valid day-of-month.
+                previous.setUTCDate(0);
+                let day = table.day[previous.getUTCDate()];
+                if (day === undefined) {
+                  previous.setUTCDate(0);
+                  day = table.day[previous.getUTCDate()];
+                }
+                if (day === undefined) {
+                  throw new Error("Unable to find cron date");
+                }
+                previous.setUTCDate(day);
+                b = (previous.getTime() - current.getTime()) / 86_400_000;
               } else {
                 b = daysInMonth(current) - currentDay + boundary.day;
               }
@@ -726,10 +784,10 @@ const stepCron = (cron, now, direction) => {
         const currentMonth = current.getUTCMonth() + 1;
         const nextMonth = table.month[currentMonth];
         const clampBoundaryDay = targetMonthIndex => {
+          const maxDayInMonth = daysInMonth(new Date(Date.UTC(current.getUTCFullYear(), targetMonthIndex + 1, 0)));
           if (cron.days.size !== 0 && cron.weekdays.size === 0) {
-            return boundary.day;
+            return reverse ? table.day[maxDayInMonth] ?? maxDayInMonth : boundary.day;
           }
-          const maxDayInMonth = daysInMonth(new Date(Date.UTC(current.getUTCFullYear(), targetMonthIndex + 1, 0)));
           return reverse ? maxDayInMonth : 1;
         };
         if (nextMonth === undefined) {
@@ -749,7 +807,7 @@ const stepCron = (cron, now, direction) => {
       }
       return;
     }
-    throw new Error("Unable to find " + direction + " cron date");
+    throw new Error("Unable to find cron date");
   });
   return dateTime.toDateUtc(result);
 };
@@ -768,17 +826,23 @@ const stepCron = (cron, now, direction) => {
  *
  * **Example** (Iterating scheduled occurrences)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cron, Result } from "effect"
  *
- * const cron = Result.getOrThrow(Cron.parse("0 0 9 * * 1-5")) // 9 AM weekdays
+ * const cron = Result.getOrThrow(Cron.parse("0 0 9 * * 1-5", "UTC")) // 9 AM weekdays
  *
  * // Get first 5 occurrences
- * const iterator = Cron.sequence(cron, new Date("2023-01-01"))
- * const next5 = Array.from({ length: 5 }, () => iterator.next().value)
- *
- * console.log(next5)
- * // [Mon Jan 02 2023 09:00:00, Tue Jan 03 2023 09:00:00, ...]
+ * const iterator = Cron.sequence(cron, "2023-01-01T00:00:00Z")
+ * const next5 = Array.from({ length: 5 }, () => iterator.next().value.toISOString())
+ * const expected = [
+ *   "2023-01-02T09:00:00.000Z",
+ *   "2023-01-03T09:00:00.000Z",
+ *   "2023-01-04T09:00:00.000Z",
+ *   "2023-01-05T09:00:00.000Z",
+ *   "2023-01-06T09:00:00.000Z"
+ * ]
+ *
+ * next5 // => expected
  * ```
  *
  * @see {@link next} for computing one next occurrence
@@ -792,8 +856,8 @@ export const sequence = function* (cron, now) {
   }
 };
 /**
- * Equivalence instance for comparing the field restrictions of two `Cron`
- * schedules.
+ * Equivalence instance for comparing the timezone, field restrictions, and
+ * day-matching mode of two `Cron` schedules.
  *
  * **When to use**
  *
@@ -802,12 +866,12 @@ export const sequence = function* (cron, now) {
  *
  * **Details**
  *
- * This comparison checks seconds, minutes, hours, days, months, and weekdays.
- * It does not compare the optional timezone.
+ * This comparison checks the optional timezone, the `and` day-matching mode,
+ * seconds, minutes, hours, days, months, and weekdays.
  *
  * **Example** (Comparing schedules with equivalence)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cron } from "effect"
  *
  * const cron1 = Cron.make({
@@ -826,7 +890,7 @@ export const sequence = function* (cron, now) {
  *   weekdays: [1, 2, 3, 4, 5]
  * })
  *
- * console.log(Cron.Equivalence(cron1, cron2)) // true
+ * Cron.Equivalence(cron1, cron2) // => true
  * ```
  *
  * @see {@link equals} for directly comparing two `Cron` values
@@ -834,25 +898,26 @@ export const sequence = function* (cron, now) {
  * @category instances
  * @since 2.0.0
  */
-export const Equivalence = /*#__PURE__*/Equ.make((self, that) => self.and === that.and && restrictionsEquals(self.seconds, that.seconds) && restrictionsEquals(self.minutes, that.minutes) && restrictionsEquals(self.hours, that.hours) && restrictionsEquals(self.days, that.days) && restrictionsEquals(self.months, that.months) && restrictionsEquals(self.weekdays, that.weekdays));
+export const Equivalence = /*#__PURE__*/Equ.make((self, that) => Equal.equals(self.tz, that.tz) && self.and === that.and && restrictionsEquals(self.seconds, that.seconds) && restrictionsEquals(self.minutes, that.minutes) && restrictionsEquals(self.hours, that.hours) && restrictionsEquals(self.days, that.days) && restrictionsEquals(self.months, that.months) && restrictionsEquals(self.weekdays, that.weekdays));
 const restrictionsArrayEquals = /*#__PURE__*/Equ.Array(/*#__PURE__*/Equ.strictEqual());
 const restrictionsEquals = (self, that) => restrictionsArrayEquals(Arr.fromIterable(self), Arr.fromIterable(that));
 /**
- * Checks whether two `Cron` instances have the same field restrictions.
+ * Checks whether two `Cron` instances have equal timezone values, field
+ * restrictions, and day-matching modes.
  *
  * **When to use**
  *
- * Use to directly compare whether two cron schedules have the same field
- * restrictions.
+ * Use to directly compare two cron schedules, including their timezones and
+ * day-matching modes.
  *
  * **Details**
  *
- * The comparison checks seconds, minutes, hours, days, months, and weekdays.
- * It does not compare the optional timezone.
+ * The comparison checks the optional timezone, the `and` day-matching mode,
+ * seconds, minutes, hours, days, months, and weekdays.
  *
  * **Example** (Checking schedule equality)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cron } from "effect"
  *
  * const cron1 = Cron.make({
@@ -871,8 +936,8 @@ const restrictionsEquals = (self, that) => restrictionsArrayEquals(Arr.fromItera
  *   weekdays: [1, 2, 3, 4, 5]
  * })
  *
- * console.log(Cron.equals(cron1, cron2)) // true
- * console.log(Cron.equals(cron1)(cron2)) // true (curried form)
+ * Cron.equals(cron1, cron2) // => true
+ * Cron.equals(cron1)(cron2) // => true
  * ```
  *
  * @see {@link Equivalence} for the reusable equivalence instance
@@ -956,7 +1021,7 @@ const parseSegment = (input, options) => {
       }
       if (step > options.max) {
         return Result.fail(new CronParseError({
-          message: `Expected step value to be less than ${options.max}`,
+          message: `Expected step value to be less than or equal to ${options.max}`,
           input
         }));
       }
@@ -1032,7 +1097,7 @@ const splitRange = (input, aliases) => {
   return [aliasOrValue(input, aliases), undefined];
 };
 function aliasOrValue(field, aliases) {
-  return aliases?.[field.toLocaleLowerCase()] ?? (decimalRegex.test(field) ? Number(field) : NaN);
+  return aliases?.[String.toLowerCase(field)] ?? (decimalRegex.test(field) ? Number(field) : NaN);
 }
 const decimalRegex = /^\d+$/;
 //# sourceMappingURL=Cron.js.map