effect 4.0.6 → 4.1.0

package/src/Context.ts

@@ -642,6 +642,7 @@ interface ContextImpl<in Services> extends Context<Services> {
   overlay: Overlay | undefined
   depth: number
   _flat: ReadonlyMap<string, any> | undefined
+  maxDepth: number
 }
 
 interface Overlay {
@@ -650,7 +651,6 @@ interface Overlay {
   readonly parent: Overlay | undefined
 }
 
-const MaxDepth = 8
 // Keep small bases cheap to read; larger bases are worth copying only after
 // enough fall-throughs to amortize the copy.
 const FlattenAfterBaseHits = 8
@@ -659,7 +659,8 @@ const makeImpl = <Services>(
   cacheRoot: ContextImpl<any> | undefined,
   base: ReadonlyMap<string, any>,
   overlay: Overlay | undefined,
-  depth: number
+  depth: number,
+  maxDepth: number
 ): ContextImpl<Services> => {
   const self: ContextImpl<Services> = Object.create(Proto)
   self.cacheRoot = cacheRoot ?? self
@@ -668,6 +669,7 @@ const makeImpl = <Services>(
   self.depth = depth
   self._flat = undefined
   self.baseHits = 0
+  self.maxDepth = maxDepth
   return self
 }
 
@@ -688,7 +690,7 @@ const flatten = (self: ContextImpl<any>): ReadonlyMap<string, any> => {
 const withFlat = <B>(self: Context<any>, f: (map: Map<string, any>) => void): Context<B> => {
   const map = new Map(self.mapUnsafe)
   f(map)
-  return makeUnsafe(map)
+  return makeImpl(undefined, map, undefined, 0, (self as ContextImpl<any>).maxDepth)
 }
 
 // A private symbol so user code cannot forge a value that reads as absent
@@ -720,8 +722,23 @@ const lookup = (self: Context<any>, key: string): unknown => {
  * Use when constructing a low-level `Context` from a trusted map whose lifecycle
  * you control.
  *
+ * **Details**
+ *
+ * `options.maxDepth` sets how many `add` calls are kept as overlays before the
+ * context is rebased into a flat map (default `8`). Lower values make lookups
+ * cheaper, higher values make additions to a large base cheaper. Invalid
+ * values fall back to the default.
+ *
+ * Contexts derived with `add`, `pick`, `omit`, and `merge` keep the setting
+ * (`merge` from its first non-empty argument). `make`, `empty`, and `mergeAll`
+ * use the default. Layers are combined with `mergeAll`, so apply it to the
+ * final context rather than inside a layer.
+ *
  * **Gotchas**
  *
+ * Excessively large `maxDepth` values can cause stack overflow when overlays
+ * are materialized or rebased. Choose a modest value.
+ *
  * The provided map is retained without copying and must not be mutated after
  * construction. Prefer `empty`, `make`, `add`, or `merge` for normal Context
  * construction.
@@ -744,12 +761,18 @@ const lookup = (self: Context<any>, key: string): unknown => {
  * @category constructors
  * @since 4.0.0
  */
-export const makeUnsafe = <Services = never>(mapUnsafe: ReadonlyMap<string, any>): Context<Services> =>
-  makeImpl(undefined, mapUnsafe, undefined, 0)
+export const makeUnsafe = <Services = never>(
+  mapUnsafe: ReadonlyMap<string, any>,
+  options?: { readonly maxDepth?: number }
+): Context<Services> => {
+  const maxDepth = options?.maxDepth
+  // NaN or Infinity would never trigger a rebase, so fall back to the default
+  return makeImpl(undefined, mapUnsafe, undefined, 0, Number.isInteger(maxDepth) && maxDepth! >= 0 ? maxDepth! : 8)
+}
 
 const Proto: Omit<
   ContextImpl<never>,
-  "cacheRoot" | "base" | "overlay" | "depth" | "_flat" | "baseHits"
+  "cacheRoot" | "base" | "overlay" | "depth" | "_flat" | "baseHits" | "maxDepth"
 > = {
   get mapUnsafe() {
     return flatten(this as any as ContextImpl<any>)
@@ -1032,19 +1055,20 @@ export const addUnsafe = <Services, I, S>(
 ): Context<Services | I> => {
   const impl = self as ContextImpl<Services>
   const cacheRoot = cacheKeys.has(key) ? undefined : impl.cacheRoot
-  if (impl.depth >= MaxDepth) {
+  if (impl.depth >= impl.maxDepth) {
     // Avoid mapUnsafe: it would flatten the parent before copying.
     const map = new Map(impl._flat ?? impl.base)
     if (!impl._flat) applyOverlays(map, impl.overlay)
     map.set(key, service)
-    return makeImpl(cacheRoot, map, undefined, 0)
+    return makeImpl(cacheRoot, map, undefined, 0, impl.maxDepth)
   }
 
   return makeImpl(
     cacheRoot,
     impl.base,
     { key, value: service, parent: impl.overlay },
-    impl.depth + 1
+    impl.depth + 1,
+    impl.maxDepth
   )
 }
 
@@ -1993,7 +2017,7 @@ export const pick = <S extends ReadonlyArray<Key<any, any>>>(
       const value = lookup(self, key)
       if (value !== notFound) map.set(key, value)
     }
-    return makeUnsafe(map)
+    return makeImpl(undefined, map, undefined, 0, (self as ContextImpl<any>).maxDepth)
   }
   const keep = new Set(services.map((key) => key.key))
   return withFlat(self, (map) =>

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)
    *