effect 4.0.7 → 4.1.0

package/src/Cron.ts

@@ -28,6 +28,60 @@ import type { Mutable } from "./Types.ts"
 
 const TypeId = "~effect/Cron"
 
+/**
+ * Chooses which occurrences of a repeated wall-clock time a `Cron` schedule
+ * includes.
+ *
+ * **When to use**
+ *
+ * Use to control how a schedule behaves when clocks fall back, for example at
+ * the end of daylight saving time, and a range of local times occurs twice.
+ *
+ * **Details**
+ *
+ * Despite the name, the policy applies to every repeated local time, not only
+ * those caused by daylight saving time. For example, Antarctica/Casey repeated
+ * 00:00-02:59 on 2023-03-09 when its standard offset changed from +11:00 to
+ * +08:00.
+ *
+ * - `"earlier"` (default) includes only the first occurrence, before the
+ *   offset change.
+ * - `"later"` includes only the second occurrence, after the offset change.
+ * - `"both"` includes both occurrences, in chronological order.
+ *
+ * Time zones without repeated times, such as UTC or fixed offsets, behave the
+ * same under every policy.
+ *
+ * **Gotchas**
+ *
+ * The policy does not apply to local times skipped when clocks move forward. A
+ * matching time inside such a gap resolves to the instant after the gap, the
+ * same under every policy, and near a gap `next` and `prev` are not guaranteed
+ * to return the nearest matching instant.
+ *
+ * **Example** (Running every occurrence of a repeated hour)
+ *
+ * ```ts import.meta.vitest
+ * import { Cron } from "effect"
+ *
+ * // Europe/Berlin repeats 02:00-02:59 on 2026-10-25, first at +02:00
+ * // (00:30Z) and again at +01:00 (01:30Z)
+ * const earlier = Cron.parseUnsafe("30 2 * * *", "Europe/Berlin")
+ * const both = Cron.parseUnsafe("30 2 * * *", "Europe/Berlin", { onDstOverlap: "both" })
+ *
+ * Cron.next(earlier, "2026-10-25T00:30:00Z").toISOString() // => "2026-10-26T01:30:00.000Z"
+ * Cron.next(both, "2026-10-25T00:30:00Z").toISOString() // => "2026-10-25T01:30:00.000Z"
+ * ```
+ *
+ * @see {@link make} for setting the policy from explicit field constraints
+ * @see {@link parse} for setting the policy when parsing an expression
+ *
+ * @stability stable
+ * @category models
+ * @since 4.1.0
+ */
+export type DstOverlapPolicy = "earlier" | "later" | "both"
+
 /**
  * Represents a cron schedule with time constraints and timezone information.
  *
@@ -79,6 +133,7 @@ export interface Cron extends Pipeable, Equal.Equal, Inspectable {
   readonly days: ReadonlySet<number>
   readonly months: ReadonlySet<number>
   readonly weekdays: ReadonlySet<number>
+  readonly onDstOverlap: DstOverlapPolicy
   /** @internal */
   readonly and: boolean
   /** @internal */
@@ -128,7 +183,8 @@ function toPojo(cron: Cron): Record<string, unknown> {
     hours: Arr.fromIterable(cron.hours),
     days: Arr.fromIterable(cron.days),
     months: Arr.fromIterable(cron.months),
-    weekdays: Arr.fromIterable(cron.weekdays)
+    weekdays: Arr.fromIterable(cron.weekdays),
+    onDstOverlap: cron.onDstOverlap
   }
   return out
 }
@@ -147,7 +203,8 @@ const CronProto = {
       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)))
+      Hash.combine(Hash.array(Arr.fromIterable(this.weekdays))),
+      Hash.combine(Hash.hash(this.onDstOverlap))
     )
   },
   toObject(this: Cron) {
@@ -223,8 +280,9 @@ export const isCron = (u: unknown): u is Cron => hasProperty(u, TypeId)
  * 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.
+ * to `7` (also Sunday). `onDstOverlap` chooses which occurrences of repeated
+ * local times are included and defaults to `"earlier"`. The constructor throws a
+ * `RangeError` when a field contains a non-integer or out-of-range value.
  *
  * **Example** (Creating schedules from constraints)
  *
@@ -304,6 +362,7 @@ export const make = (values: {
   readonly weekdays: Iterable<number>
   readonly and?: boolean | undefined
   readonly tz?: DateTime.TimeZone | undefined
+  readonly onDstOverlap?: DstOverlapPolicy | undefined
 }): Cron => {
   const o: Mutable<Cron> = Object.create(CronProto)
   o.seconds = restrictions.seconds(values.seconds ?? [0])
@@ -314,6 +373,7 @@ export const make = (values: {
   o.weekdays = restrictions.weekdays(values.weekdays)
   o.and = values.and === true
   o.tz = Option.fromUndefinedOr(values.tz)
+  o.onDstOverlap = values.onDstOverlap ?? "earlier"
 
   const seconds = Array.from(o.seconds)
   const minutes = Array.from(o.minutes)
@@ -529,6 +589,8 @@ export const isCronParseError = (u: unknown): u is CronParseError => hasProperty
  * `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.
+ * `options.onDstOverlap` chooses which occurrences of repeated local times are
+ * included and defaults to `"earlier"`.
  *
  * **Example** (Parsing cron expressions)
  *
@@ -549,7 +611,9 @@ export const isCronParseError = (u: unknown): u is CronParseError => hasProperty
  * @category constructors
  * @since 2.0.0
  */
-export const parse = (cron: string, tz?: DateTime.TimeZone | string): Result.Result<Cron, CronParseError> => {
+export const parse = (cron: string, tz?: DateTime.TimeZone | string, options?: {
+  readonly onDstOverlap?: DstOverlapPolicy | undefined
+}): Result.Result<Cron, CronParseError> => {
   const segments = cron.trim().split(/\s+/).filter(String.isNonEmpty)
   if (segments.length !== 5 && segments.length !== 6) {
     return Result.fail(new CronParseError({ message: `Invalid number of segments in cron expression`, input: cron }))
@@ -584,7 +648,8 @@ export const parse = (cron: string, tz?: DateTime.TimeZone | string): Result.Res
       days: days.values,
       months: months.values,
       weekdays: weekdays.values,
-      and: (days.wildcard || weekdays.wildcard) && days.values.size !== 0 && weekdays.values.size !== 0
+      and: (days.wildcard || weekdays.wildcard) && days.values.size !== 0 && weekdays.values.size !== 0,
+      onDstOverlap: options?.onDstOverlap
     })
   ))
 }
@@ -618,7 +683,9 @@ export const parse = (cron: string, tz?: DateTime.TimeZone | string): Result.Res
  * @category constructors
  * @since 4.0.0
  */
-export const parseUnsafe = (cron: string, tz?: DateTime.TimeZone | string): Cron => Result.getOrThrow(parse(cron, tz))
+export const parseUnsafe = (cron: string, tz?: DateTime.TimeZone | string, options?: {
+  readonly onDstOverlap?: DstOverlapPolicy | undefined
+}): Cron => Result.getOrThrow(parse(cron, tz, options))
 
 /**
  * Formats a `Cron` instance as a cron expression.
@@ -630,8 +697,8 @@ export const parseUnsafe = (cron: string, tz?: DateTime.TimeZone | string): Cron
  *
  * **Gotchas**
  *
- * Formatting drops the timezone information and the `and` restriction between
- * days and weekdays. Parsing the result is therefore not guaranteed to produce
+ * Formatting drops the timezone information, the `onDstOverlap` policy, 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)
@@ -777,7 +844,9 @@ const daysInMonth = (date: Date): number =>
  *
  * 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.
+ * date is provided. The result is always strictly after the starting point.
+ * Repeated local times are included according to the schedule's
+ * `onDstOverlap` policy.
  *
  * **Example** (Finding the next occurrence)
  *
@@ -812,6 +881,8 @@ export const next = (cron: Cron, now?: DateTime.DateTime.Input): Date => {
  * **Details**
  *
  * When no date/time is provided, the search starts from the current time.
+ * Repeated local times are included according to the schedule's
+ * `onDstOverlap` policy.
  *
  * **Gotchas**
  *
@@ -829,8 +900,28 @@ export const prev = (cron: Cron, now?: DateTime.DateTime.Input): Date => {
 }
 
 const stepCron = (cron: Cron, now: DateTime.DateTime.Input | undefined, direction: "next" | "prev"): Date => {
+  const start = now ?? new Date()
+  if (cron.onDstOverlap !== "both") {
+    return searchCron(cron, start, direction, cron.onDstOverlap)
+  }
+  // Both occurrences are eligible, so the result is the nearest of the two
+  // single-occurrence searches in the search direction.
+  const earlier = searchCron(cron, start, direction, "earlier")
+  const later = searchCron(cron, start, direction, "later")
+  if (direction === "next") {
+    return earlier <= later ? earlier : later
+  }
+  return earlier >= later ? earlier : later
+}
+
+const searchCron = (
+  cron: Cron,
+  now: DateTime.DateTime.Input,
+  direction: "next" | "prev",
+  onDstOverlap: "earlier" | "later"
+): Date => {
   const tz = Option.getOrUndefined(cron.tz)
-  const zoned = dateTime.makeZonedUnsafe(now ?? new Date(), {
+  const zoned = dateTime.makeZonedUnsafe(now, {
     timeZone: tz
   })
 
@@ -844,28 +935,81 @@ const stepCron = (cron: Cron, now: DateTime.DateTime.Input | undefined, directio
     (next: number, current: number) => next > current
 
   const utc = tz !== undefined && dateTime.isTimeZoneNamed(tz) && tz.id === "UTC"
-  const adjustDst = utc ? constVoid : (current: Date) => {
+  // Going backward, a candidate inside a gap is left in place: it resolves to
+  // the instant after the gap, and the range check below rejects it when that
+  // instant is not before the input.
+  const adjustDst = utc || reverse ? constVoid : (current: Date) => {
     const adjusted = dateTime.makeZonedUnsafe(current, {
       timeZone: zoned.zone,
-      adjustForTimeZone: true,
-      disambiguation: reverse ? "later" : undefined
+      adjustForTimeZone: true
     }).pipe(dateTime.toDate)
 
     const drift = current.getTime() - adjusted.getTime()
-    if (reverse ? drift !== 0 : drift > 0) {
-      current.setTime(reverse ? adjusted.getTime() : current.getTime() + drift)
+    if (drift > 0) {
+      current.setTime(current.getTime() + drift)
     }
   }
 
-  // Repeated wall times resolve to their first occurrence, so when the search
-  // starts in the second occurrence, matches inside that fold are in the past.
-  const isBeforeStart = reverse || utc ? constFalse : (current: Date) =>
-    dateTime.makeZonedUnsafe(current, {
+  // Repeated wall times resolve to the occurrence chosen by the policy. Gaps
+  // resolve to the instant after the gap under either disambiguation.
+  const disambiguation = onDstOverlap === "later" ? "later" : "compatible"
+  const resolve = (wallMillis: number) =>
+    dateTime.makeZonedUnsafe(wallMillis, {
       timeZone: zoned.zone,
-      adjustForTimeZone: true
-    }).epochMilliseconds <= zoned.epochMilliseconds
+      adjustForTimeZone: true,
+      disambiguation
+    }).epochMilliseconds
+
+  // Inside a fold, wall-clock order differs from instant order, so a candidate
+  // can resolve to an instant on the wrong side of the input.
+  const isOutOfRange = utc ? constFalse : reverse ?
+    (wallMillis: number) => resolve(wallMillis) >= zoned.epochMilliseconds :
+    (wallMillis: number) => resolve(wallMillis) <= zoned.epochMilliseconds
+
+  // A fold near the input shows as a larger offset a day before it than a day
+  // after it (DateTime disambiguation assumes the same single transition).
+  // Inside a fold the resolved instant moves in the same direction as the wall
+  // time, so the rejected candidates form one interval no longer than the
+  // fold: when the wall time one fold length ahead is in range, binary search
+  // for the first second in range instead of stepping through the interval.
+  // Gaps break that ordering, so they keep stepping one second at a time.
+  let foldSeconds: number | undefined
+  const skipOutOfRange = (current: Date) => {
+    if (foldSeconds === undefined) {
+      const offsetAt = (millis: number) =>
+        dateTime.zonedOffset(dateTime.makeZonedUnsafe(millis, { timeZone: zoned.zone }))
+      foldSeconds = Math.floor(
+        (offsetAt(zoned.epochMilliseconds - 86_400_000) - offsetAt(zoned.epochMilliseconds + 86_400_000)) / 1000
+      )
+    }
+    const after = (seconds: number) => current.getTime() + tick * seconds * 1000
+    let outOfRange = 0
+    let inRange = 1
+    if (foldSeconds > 0 && !isOutOfRange(after(foldSeconds))) {
+      inRange = foldSeconds
+      while (inRange - outOfRange > 1) {
+        const mid = outOfRange + Math.floor((inRange - outOfRange) / 2)
+        if (isOutOfRange(after(mid))) {
+          outOfRange = mid
+        } else {
+          inRange = mid
+        }
+      }
+    }
+    current.setTime(after(inRange))
+  }
 
   const result = dateTime.mutate(zoned, (current) => {
+    // When the input is in the occurrence the policy excludes, eligible
+    // instants of the same fold can lie behind its wall time in the search
+    // direction. Start from the wall time of the input under the policy's
+    // offset so they are visited; candidates that resolve on the wrong side
+    // of the input are skipped below.
+    const shift = utc ? 0 : zoned.epochMilliseconds - resolve(current.getTime())
+    if (reverse ? shift > 0 : shift < 0) {
+      current.setTime(current.getTime() + shift)
+    }
+
     // Start from the nearest whole second strictly past the input in the search
     // direction. Going backward, a fractional input already has one.
     const offset = reverse && current.getUTCMilliseconds() > 0 ? 0 : tick
@@ -1011,8 +1155,8 @@ const stepCron = (cron: Cron, now: DateTime.DateTime.Input | undefined, directio
         }
       }
 
-      if (isBeforeStart(current)) {
-        current.setUTCSeconds(current.getUTCSeconds() + 1)
+      if (isOutOfRange(current.getTime())) {
+        skipOutOfRange(current)
         i = -1 // skipped fold candidates do not count against the search budget
         continue
       }
@@ -1021,7 +1165,7 @@ const stepCron = (cron: Cron, now: DateTime.DateTime.Input | undefined, directio
     }
 
     throw new Error("Unable to find cron date")
-  })
+  }, { disambiguation })
 
   return dateTime.toDateUtc(result)
 }
@@ -1084,7 +1228,8 @@ export const sequence = function*(cron: Cron, now?: DateTime.DateTime.Input): It
  * **Details**
  *
  * This comparison checks the optional timezone, the `and` day-matching mode,
- * seconds, minutes, hours, days, months, and weekdays.
+ * the `onDstOverlap` policy, seconds, minutes, hours, days, months, and
+ * weekdays.
  *
  * **Example** (Comparing schedules with equivalence)
  *
@@ -1119,6 +1264,7 @@ export const sequence = function*(cron: Cron, now?: DateTime.DateTime.Input): It
 export const Equivalence: Equ.Equivalence<Cron> = Equ.make((self, that) =>
   Equal.equals(self.tz, that.tz) &&
   self.and === that.and &&
+  self.onDstOverlap === that.onDstOverlap &&
   restrictionsEquals(self.seconds, that.seconds) &&
   restrictionsEquals(self.minutes, that.minutes) &&
   restrictionsEquals(self.hours, that.hours) &&
@@ -1143,7 +1289,8 @@ const restrictionsEquals = (self: ReadonlySet<number>, that: ReadonlySet<number>
  * **Details**
  *
  * The comparison checks the optional timezone, the `and` day-matching mode,
- * seconds, minutes, hours, days, months, and weekdays.
+ * the `onDstOverlap` policy, seconds, minutes, hours, days, months, and
+ * weekdays.
  *
  * **Example** (Checking schedule equality)
  *
@@ -1189,7 +1336,8 @@ export const equals: {
    * **Details**
    *
    * The comparison checks the optional timezone, the `and` day-matching mode,
-   * seconds, minutes, hours, days, months, and weekdays.
+   * the `onDstOverlap` policy, seconds, minutes, hours, days, months, and
+   * weekdays.
    *
    * **Example** (Checking schedule equality)
    *
@@ -1235,7 +1383,8 @@ export const equals: {
    * **Details**
    *
    * The comparison checks the optional timezone, the `and` day-matching mode,
-   * seconds, minutes, hours, days, months, and weekdays.
+   * the `onDstOverlap` policy, seconds, minutes, hours, days, months, and
+   * weekdays.
    *
    * **Example** (Checking schedule equality)
    *

package/src/Duration.ts

@@ -848,6 +848,30 @@ export const days = (days: number): Duration => make(days * 86_400_000)
  */
 export const weeks = (weeks: number): Duration => make(weeks * 604_800_000)
 
+/**
+ * Converts a Duration to microseconds.
+ *
+ * **Example** (Converting durations to microseconds)
+ *
+ * ```ts import.meta.vitest
+ * import { Duration } from "effect"
+ *
+ * Duration.toMicros(Duration.millis(5)) // => 5000
+ * Duration.toMicros(Duration.nanos(123n)) // => 0.123
+ * ```
+ *
+ * @stability stable
+ * @category getters
+ * @since 4.1.0
+ */
+export const toMicros = (self: Input): number =>
+  match(fromInputUnsafe(self), {
+    onMillis: (millis) => millis * 1_000,
+    onNanos: (nanos) => nanosToUnit(nanos, 1_000),
+    onInfinity: () => Infinity,
+    onNegativeInfinity: () => -Infinity
+  })
+
 /**
  * Converts a Duration to milliseconds.
  *
@@ -2534,6 +2558,122 @@ export const format = (self: Duration): string => {
   return pieces.join(" ")
 }
 
+/**
+ * Formats a `Duration` as an ISO 8601 duration string.
+ *
+ * **Details**
+ *
+ * The duration is balanced into days (24 hours), hours, minutes and seconds,
+ * with up to nine fractional second digits. Weeks, months and years are never
+ * produced. Negative durations get a leading `-`, zero is `"PT0S"` and
+ * infinite durations return `Option.none()`.
+ *
+ * **Example** (Formatting durations as ISO 8601)
+ *
+ * ```ts import.meta.vitest
+ * import { Duration, Option } from "effect"
+ *
+ * Duration.formatIso(Duration.minutes(90)) // => Option.some("PT1H30M")
+ * Duration.formatIso(Duration.millis(-1500)) // => Option.some("-PT1.5S")
+ * Duration.formatIso(Duration.hours(26)) // => Option.some("P1DT2H")
+ * Duration.formatIso(Duration.infinity) // => Option.none()
+ * ```
+ *
+ * @see {@link fromIso} for parsing ISO 8601 duration strings
+ *
+ * @stability stable
+ * @category converting
+ * @since 4.1.0
+ */
+export const formatIso = (self: Duration): Option.Option<string> => {
+  if (!isFinite(self)) {
+    return Option.none()
+  }
+  const n = toNanosUnsafe(self)
+  const a = n < bigint0 ? -n : n
+  const days = a / bigintNanosPerDay
+  const hours = a % bigintNanosPerDay / bigintNanosPerHour
+  const minutes = a % bigintNanosPerHour / bigintNanosPerMinute
+  const seconds = a % bigintNanosPerMinute / bigint1e9
+  const fraction = a % bigint1e9
+
+  let time = ""
+  if (hours !== bigint0) time += `${hours}H`
+  if (minutes !== bigint0) time += `${minutes}M`
+  if (fraction !== bigint0) {
+    time += `${seconds}.${fraction.toString().padStart(9, "0").replace(/0+$/, "")}S`
+  } else if (seconds !== bigint0) {
+    time += `${seconds}S`
+  }
+
+  let out = n < bigint0 ? "-P" : "P"
+  if (days !== bigint0) out += `${days}D`
+  if (time !== "") out += `T${time}`
+  return Option.some(out === "P" ? "PT0S" : out)
+}
+
+const DURATION_ISO_REGEXP =
+  /^([+-])?P(?!$)(?:(\d+)W)?(?:(\d+)D)?(?:T(?!$)(?:(\d+)(?:[.,](\d{1,9}))?H)?(?:(\d+)(?:[.,](\d{1,9}))?M)?(?:(\d+)(?:[.,](\d{1,9}))?S)?)?$/
+
+// `scale` is the number of nanoseconds in one unit
+const parseIsoComponent = (whole: string | undefined, fraction: string | undefined, scale: bigint): bigint =>
+  (whole === undefined ? bigint0 : BigInt(whole) * scale) +
+  (fraction === undefined ? bigint0 : BigInt(fraction.padEnd(9, "0")) * (scale / bigint1e9))
+
+/**
+ * Parses an ISO 8601 duration string into a `Duration`.
+ *
+ * **Details**
+ *
+ * Accepts an optional `+` or `-` sign followed by weeks (`W`), days (`D`),
+ * hours (`H`), minutes (`M`) and seconds (`S`). A day is 24 hours and a week
+ * is 7 days. Only the last time component may have a fraction, of up to nine
+ * digits, separated by `.` or `,`.
+ *
+ * **Gotchas**
+ *
+ * Years (`Y`) and months (`M` before `T`) are rejected because they have no
+ * fixed length. Fractional weeks and days are rejected.
+ *
+ * **Example** (Parsing ISO 8601 durations)
+ *
+ * ```ts import.meta.vitest
+ * import { Duration, Option } from "effect"
+ *
+ * Duration.fromIso("PT1H30M") // => Option.some(Duration.minutes(90))
+ * Duration.fromIso("-PT1.5S") // => Option.some(Duration.millis(-1500))
+ * Duration.fromIso("P1W2D") // => Option.some(Duration.days(9))
+ * Duration.fromIso("P1M") // => Option.none()
+ * ```
+ *
+ * @see {@link formatIso} for formatting a `Duration` as an ISO 8601 string
+ *
+ * @stability stable
+ * @category constructors
+ * @since 4.1.0
+ */
+export const fromIso = (input: string): Option.Option<Duration> => {
+  const match = DURATION_ISO_REGEXP.exec(input)
+  if (match === null) {
+    return Option.none()
+  }
+  const [, sign, w, d, h, hf, m, mf, s, sf] = match
+  // a fraction is only allowed on the last time component
+  if ((hf !== undefined && (m !== undefined || s !== undefined)) || (mf !== undefined && s !== undefined)) {
+    return Option.none()
+  }
+  const total = parseIsoComponent(w, undefined, bigintNanosPerWeek) +
+    parseIsoComponent(d, undefined, bigintNanosPerDay) +
+    parseIsoComponent(h, hf, bigintNanosPerHour) +
+    parseIsoComponent(m, mf, bigintNanosPerMinute) +
+    parseIsoComponent(s, sf, bigint1e9)
+  const signed = sign === "-" ? -total : total
+  const ms = Number(signed / bigint1e6)
+  return Option.some(
+    signed % bigint1e6 === bigint0 && Number.isSafeInteger(ms) ? millis(ms) : nanos(signed)
+  )
+}
+
 /**
  * Reducer for summing `Duration`s.
  *