effect 4.0.1 → 4.0.3

package/src/DateTime.ts

@@ -8,6 +8,7 @@
  * helpers, comparisons, date arithmetic, current-time effects, and formatting
  * functions.
  *
+ * @stability stable
  * @since 3.6.0
  */
 import type { IllegalArgumentError } from "./Cause.ts"
@@ -31,6 +32,7 @@ const TimeZoneTypeId = Internal.TimeZoneTypeId
  * A `DateTime` represents a point in time. It can optionally have a time zone
  * associated with it.
  *
+ * @stability stable
  * @category models
  * @since 3.6.0
  */
@@ -44,6 +46,7 @@ export type DateTime = Utc | Zoned
  *
  * Use `DateTime.isUtc` to narrow a `DateTime` to this variant.
  *
+ * @stability stable
  * @category models
  * @since 3.6.0
  */
@@ -62,6 +65,7 @@ export interface Utc extends DateTime.Proto {
  * `epochMilliseconds`, while the time zone is used for wall-clock parts,
  * formatting, and zone-aware transformations.
  *
+ * @stability stable
  * @category models
  * @since 3.6.0
  */
@@ -78,6 +82,7 @@ export interface Zoned extends DateTime.Proto {
  * Companion namespace containing the public helper types used by `DateTime`
  * constructors, parts APIs, formatting, and date/time arithmetic.
  *
+ * @stability stable
  * @since 3.6.0
  */
 export declare namespace DateTime {
@@ -271,6 +276,7 @@ export declare namespace DateTime {
  *
  * A `TimeZone` is either a fixed offset from UTC or a named IANA time zone.
  *
+ * @stability stable
  * @category models
  * @since 3.6.0
  */
@@ -280,6 +286,7 @@ export type TimeZone = TimeZone.Offset | TimeZone.Named
  * Companion namespace containing the public variant and protocol types for
  * `TimeZone`.
  *
+ * @stability stable
  * @since 3.6.0
  */
 export declare namespace TimeZone {
@@ -397,6 +404,7 @@ export declare namespace TimeZone {
  * afterGap.pipe(Option.getOrThrow, DateTime.formatIso) // => "2025-03-09T07:30:00.000Z"
  * ```
  *
+ * @stability stable
  * @category models
  * @since 3.18.0
  */
@@ -416,6 +424,7 @@ export type Disambiguation = "compatible" | "earlier" | "later" | "reject"
  * @see {@link isUtc} for narrowing a known `DateTime` to UTC
  * @see {@link isZoned} for narrowing a known `DateTime` to zoned
  *
+ * @stability stable
  * @category guards
  * @since 3.6.0
  */
@@ -432,6 +441,7 @@ export const isDateTime: (u: unknown) => u is DateTime = Internal.isDateTime
  * @see {@link isTimeZoneOffset} for narrowing to fixed-offset time zones
  * @see {@link isTimeZoneNamed} for narrowing to named time zones
  *
+ * @stability stable
  * @category guards
  * @since 3.6.0
  */
@@ -448,6 +458,7 @@ export const isTimeZone: (u: unknown) => u is TimeZone = Internal.isTimeZone
  * @see {@link isTimeZone} for checking either time zone variant
  * @see {@link isTimeZoneNamed} for narrowing to named time zones
  *
+ * @stability stable
  * @category guards
  * @since 3.6.0
  */
@@ -464,6 +475,7 @@ export const isTimeZoneOffset: (u: unknown) => u is TimeZone.Offset = Internal.i
  * @see {@link isTimeZone} for checking either time zone variant
  * @see {@link isTimeZoneOffset} for narrowing to fixed-offset time zones
  *
+ * @stability stable
  * @category guards
  * @since 3.6.0
  */
@@ -480,6 +492,7 @@ export const isTimeZoneNamed: (u: unknown) => u is TimeZone.Named = Internal.isT
  * @see {@link isZoned} for narrowing to zoned date-times
  * @see {@link match} for handling both UTC and zoned cases
  *
+ * @stability stable
  * @category guards
  * @since 3.6.0
  */
@@ -496,6 +509,7 @@ export const isUtc: (self: DateTime) => self is Utc = Internal.isUtc
  * @see {@link isUtc} for narrowing to UTC date-times
  * @see {@link match} for handling both UTC and zoned cases
  *
+ * @stability stable
  * @category guards
  * @since 3.6.0
  */
@@ -526,6 +540,7 @@ export const isZoned: (self: DateTime) => self is Zoned = Internal.isZoned
  * DateTime.Equivalence(utc, zoned) // => true
  * ```
  *
+ * @stability stable
  * @category instances
  * @since 3.6.0
  */
@@ -553,6 +568,7 @@ export const Equivalence: Equ.Equivalence<DateTime> = Internal.Equivalence
  * Array.sort(dates, DateTime.Order).map(DateTime.formatIsoDateUtc) // => ["2024-01-01", "2024-02-01", "2024-03-01"]
  * ```
  *
+ * @stability stable
  * @category instances
  * @since 3.6.0
  */
@@ -579,6 +595,7 @@ export const Order: order.Order<DateTime> = Internal.Order
  * DateTime.clamp(date, { minimum: min, maximum: max }) // => DateTime.makeUnsafe("2024-12-31")
  * ```
  *
+ * @stability stable
  * @category ordering
  * @since 3.6.0
  */
@@ -604,6 +621,7 @@ export const clamp: {
    * DateTime.clamp(date, { minimum: min, maximum: max }) // => DateTime.makeUnsafe("2024-12-31")
    * ```
    *
+   * @stability stable
    * @category ordering
    * @since 3.6.0
    */
@@ -629,6 +647,7 @@ export const clamp: {
    * DateTime.clamp(date, { minimum: min, maximum: max }) // => DateTime.makeUnsafe("2024-12-31")
    * ```
    *
+   * @stability stable
    * @category ordering
    * @since 3.6.0
    */
@@ -654,6 +673,7 @@ export const clamp: {
  * DateTime.fromDateUnsafe(new Date("2024-01-01T12:00:00Z")) // => DateTime.makeUnsafe("2024-01-01T12:00:00Z")
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -690,6 +710,7 @@ export const fromDateUnsafe: (date: Date) => Utc = Internal.fromDateUnsafe
  * DateTime.makeUnsafe("2024-01-01") // => DateTime.makeUnsafe("2024-01-01T00:00:00Z")
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -706,6 +727,7 @@ export const makeUnsafe: <A extends DateTime.Input>(input: A) => DateTime.Preser
  * DateTime.fromEpochSeconds(1704067200).toJSON() // => "2024-01-01T00:00:00.000Z"
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -744,6 +766,7 @@ export const fromEpochSeconds: (seconds: number) => Utc = Internal.fromEpochSeco
  * DateTime.formatIsoZoned(zoned) // => "2024-06-15T15:30:00.000+01:00[Europe/London]"
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -786,6 +809,7 @@ export const makeZonedUnsafe: (input: DateTime.Input, options?: {
  * result.pipe(Option.map(DateTime.formatIsoZoned)) // => Option.some("2024-06-15T15:30:00.000+01:00[Europe/London]")
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 3.6.0
  */
@@ -830,6 +854,7 @@ export const makeZoned: (
  * DateTime.make("not a date") // => Option.none()
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 3.6.0
  */
@@ -858,6 +883,7 @@ export const make: <A extends DateTime.Input>(input: A) => Option.Option<DateTim
  * DateTime.makeZonedFromString("invalid") // => Option.none()
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 3.6.0
  */
@@ -875,6 +901,7 @@ export const makeZonedFromString: (input: string) => Option.Option<Zoned> = Inte
  * await Effect.runPromise(Effect.map(DateTime.now, DateTime.isDateTime)) // => true
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 3.6.0
  */
@@ -893,6 +920,7 @@ export const now: Effect.Effect<Utc> = Internal.now
  * await Effect.runPromise(Effect.map(DateTime.nowAsDate, (now) => now instanceof Date)) // => true
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 3.14.0
  */
@@ -919,6 +947,7 @@ export const nowAsDate: Effect.Effect<Date> = Internal.nowAsDate
  * Number.isFinite(DateTime.toEpochMillis(DateTime.nowUnsafe())) // => true
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -954,6 +983,7 @@ export const nowUnsafe: LazyArg<Utc> = Internal.nowUnsafe
  * utc // => DateTime.makeUnsafe("2024-01-01T00:00:00Z")
  * ```
  *
+ * @stability stable
  * @category converting
  * @since 3.13.0
  */
@@ -973,6 +1003,7 @@ export const toUtc: (self: DateTime) => Utc = Internal.toUtc
  * DateTime.isZoned(zoned) // => true
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 3.6.0
  */
@@ -991,6 +1022,7 @@ export const setZone: {
    * DateTime.isZoned(zoned) // => true
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 3.6.0
    */
@@ -1015,6 +1047,7 @@ export const setZone: {
    * DateTime.isZoned(zoned) // => true
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 3.6.0
    */
@@ -1046,6 +1079,7 @@ export const setZone: {
  * DateTime.zoneToString(zoned.zone) // => "+03:00"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 3.6.0
  */
@@ -1068,6 +1102,7 @@ export const setZoneOffset: {
    * DateTime.zoneToString(zoned.zone) // => "+03:00"
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 3.6.0
    */
@@ -1096,6 +1131,7 @@ export const setZoneOffset: {
    * DateTime.zoneToString(zoned.zone) // => "+03:00"
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 3.6.0
    */
@@ -1133,6 +1169,7 @@ export const setZoneOffset: {
  * // DateTime.zoneMakeNamedUnsafe("Invalid/Zone")
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1160,6 +1197,7 @@ export const zoneMakeNamedUnsafe: (zoneId: string) => TimeZone.Named = Internal.
  * DateTime.formatIsoZoned(dt) // => "2024-01-01T15:00:00.000+03:00"
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 3.6.0
  */
@@ -1181,6 +1219,7 @@ export const zoneMakeOffset: (offset: number) => TimeZone.Offset = Internal.zone
  * DateTime.zoneMakeNamed("Invalid/Zone") // => Option.none()
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 3.6.0
  */
@@ -1208,6 +1247,7 @@ export const zoneMakeNamed: (zoneId: string) => Option.Option<TimeZone.Named> =
  * DateTime.zoneToString((await Effect.runPromise(program)).zone) // => "Europe/London"
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 3.6.0
  */
@@ -1230,6 +1270,7 @@ export const zoneMakeNamedEffect: (zoneId: string) => Effect.Effect<TimeZone.Nam
  * DateTime.isTimeZoneNamed(DateTime.zoneMakeLocal()) // => true
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 3.6.0
  */
@@ -1252,6 +1293,7 @@ export const zoneMakeLocal: () => TimeZone.Named = Internal.zoneMakeLocal
  * DateTime.zoneFromString("invalid") // => Option.none()
  * ```
  *
+ * @stability stable
  * @category decoding
  * @since 3.6.0
  */
@@ -1269,6 +1311,7 @@ export const zoneFromString: (zone: string) => Option.Option<TimeZone> = Interna
  * DateTime.zoneToString(DateTime.zoneMakeNamedUnsafe("Europe/London")) // => "Europe/London"
  * ```
  *
+ * @stability stable
  * @category encoding
  * @since 3.6.0
  */
@@ -1289,6 +1332,7 @@ export const zoneToString: (self: TimeZone) => string = Internal.zoneToString
  * result // => Option.some("2024-01-01T00:00:00.000+00:00[Europe/London]")
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 3.6.0
  */
@@ -1308,6 +1352,7 @@ export const setZoneNamed: {
    * result // => Option.some("2024-01-01T00:00:00.000+00:00[Europe/London]")
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 3.6.0
    */
@@ -1333,6 +1378,7 @@ export const setZoneNamed: {
    * result // => Option.some("2024-01-01T00:00:00.000+00:00[Europe/London]")
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 3.6.0
    */
@@ -1361,6 +1407,7 @@ export const setZoneNamed: {
  * DateTime.zoneToString(zoned.zone) // => "Europe/London"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1380,6 +1427,7 @@ export const setZoneNamedUnsafe: {
    * DateTime.zoneToString(zoned.zone) // => "Europe/London"
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 4.0.0
    */
@@ -1405,6 +1453,7 @@ export const setZoneNamedUnsafe: {
    * DateTime.zoneToString(zoned.zone) // => "Europe/London"
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 4.0.0
    */
@@ -1443,6 +1492,7 @@ export const setZoneNamedUnsafe: {
  * DateTime.distance(start, end) // => Duration.minutes(1)
  * ```
  *
+ * @stability stable
  * @category comparisons
  * @since 3.6.0
  */
@@ -1472,6 +1522,7 @@ export const distance: {
    * DateTime.distance(start, end) // => Duration.minutes(1)
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 3.6.0
    */
@@ -1501,6 +1552,7 @@ export const distance: {
    * DateTime.distance(start, end) // => Duration.minutes(1)
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 3.6.0
    */
@@ -1521,6 +1573,7 @@ export const distance: {
  * DateTime.min(date1, date2) // => DateTime.makeUnsafe("2024-01-01")
  * ```
  *
+ * @stability stable
  * @category comparisons
  * @since 3.6.0
  */
@@ -1539,6 +1592,7 @@ export const min: {
    * DateTime.min(date1, date2) // => DateTime.makeUnsafe("2024-01-01")
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 3.6.0
    */
@@ -1557,6 +1611,7 @@ export const min: {
    * DateTime.min(date1, date2) // => DateTime.makeUnsafe("2024-01-01")
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 3.6.0
    */
@@ -1577,6 +1632,7 @@ export const min: {
  * DateTime.max(date1, date2) // => DateTime.makeUnsafe("2024-02-01")
  * ```
  *
+ * @stability stable
  * @category comparisons
  * @since 3.6.0
  */
@@ -1595,6 +1651,7 @@ export const max: {
    * DateTime.max(date1, date2) // => DateTime.makeUnsafe("2024-02-01")
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 3.6.0
    */
@@ -1613,6 +1670,7 @@ export const max: {
    * DateTime.max(date1, date2) // => DateTime.makeUnsafe("2024-02-01")
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 3.6.0
    */
@@ -1634,6 +1692,7 @@ export const max: {
  * DateTime.isGreaterThan(date2, date1) // => false
  * ```
  *
+ * @stability stable
  * @category comparisons
  * @since 4.0.0
  */
@@ -1653,6 +1712,7 @@ export const isGreaterThan: {
    * DateTime.isGreaterThan(date2, date1) // => false
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 4.0.0
    */
@@ -1672,6 +1732,7 @@ export const isGreaterThan: {
    * DateTime.isGreaterThan(date2, date1) // => false
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 4.0.0
    */
@@ -1695,6 +1756,7 @@ export const isGreaterThan: {
  * DateTime.isGreaterThanOrEqualTo(date1, date3) // => false
  * ```
  *
+ * @stability stable
  * @category comparisons
  * @since 4.0.0
  */
@@ -1716,6 +1778,7 @@ export const isGreaterThanOrEqualTo: {
    * DateTime.isGreaterThanOrEqualTo(date1, date3) // => false
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 4.0.0
    */
@@ -1737,6 +1800,7 @@ export const isGreaterThanOrEqualTo: {
    * DateTime.isGreaterThanOrEqualTo(date1, date3) // => false
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 4.0.0
    */
@@ -1758,6 +1822,7 @@ export const isGreaterThanOrEqualTo: {
  * DateTime.isLessThan(date2, date1) // => false
  * ```
  *
+ * @stability stable
  * @category comparisons
  * @since 4.0.0
  */
@@ -1777,6 +1842,7 @@ export const isLessThan: {
    * DateTime.isLessThan(date2, date1) // => false
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 4.0.0
    */
@@ -1796,6 +1862,7 @@ export const isLessThan: {
    * DateTime.isLessThan(date2, date1) // => false
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 4.0.0
    */
@@ -1819,6 +1886,7 @@ export const isLessThan: {
  * DateTime.isLessThanOrEqualTo(date3, date1) // => false
  * ```
  *
+ * @stability stable
  * @category comparisons
  * @since 4.0.0
  */
@@ -1840,6 +1908,7 @@ export const isLessThanOrEqualTo: {
    * DateTime.isLessThanOrEqualTo(date3, date1) // => false
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 4.0.0
    */
@@ -1861,6 +1930,7 @@ export const isLessThanOrEqualTo: {
    * DateTime.isLessThanOrEqualTo(date3, date1) // => false
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 4.0.0
    */
@@ -1882,6 +1952,7 @@ export const isLessThanOrEqualTo: {
  * DateTime.between(date, { minimum: min, maximum: max }) // => true
  * ```
  *
+ * @stability stable
  * @category comparisons
  * @since 3.6.0
  */
@@ -1901,6 +1972,7 @@ export const between: {
    * DateTime.between(date, { minimum: min, maximum: max }) // => true
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 3.6.0
    */
@@ -1920,6 +1992,7 @@ export const between: {
    * DateTime.between(date, { minimum: min, maximum: max }) // => true
    * ```
    *
+   * @stability stable
    * @category comparisons
    * @since 3.6.0
    */
@@ -1943,6 +2016,7 @@ export const between: {
  * await Effect.runPromise(Effect.provide(DateTime.isFuture(futureDate), TestClock.layer())) // => true
  * ```
  *
+ * @stability stable
  * @category comparisons
  * @since 3.6.0
  */
@@ -1969,6 +2043,7 @@ export const isFuture: (self: DateTime) => Effect.Effect<boolean> = Internal.isF
  * DateTime.isFutureUnsafe(oneHourFromNow)
  * ```
  *
+ * @stability stable
  * @category comparisons
  * @since 4.0.0
  */
@@ -1991,6 +2066,7 @@ export const isFutureUnsafe: (self: DateTime) => boolean = Internal.isFutureUnsa
  * await Effect.runPromise(Effect.provide(DateTime.isPast(pastDate), TestClock.layer())) // => true
  * ```
  *
+ * @stability stable
  * @category comparisons
  * @since 3.6.0
  */
@@ -2017,6 +2093,7 @@ export const isPast: (self: DateTime) => Effect.Effect<boolean> = Internal.isPas
  * DateTime.isPastUnsafe(oneHourAgo)
  * ```
  *
+ * @stability stable
  * @category comparisons
  * @since 4.0.0
  */
@@ -2031,7 +2108,7 @@ export const isPastUnsafe: (self: DateTime) => boolean = Internal.isPastUnsafe
  *
  * **Details**
  *
- * This always returns the UTC representation, ignoring any time zone information.
+ * This preserves the original instant, regardless of any time zone information.
  *
  * **Example** (Converting DateTime values to UTC Dates)
  *
@@ -2045,6 +2122,7 @@ export const isPastUnsafe: (self: DateTime) => boolean = Internal.isPastUnsafe
  * DateTime.toDateUtc(dt).toISOString() // => "2024-01-01T12:00:00.000Z"
  * ```
  *
+ * @stability stable
  * @category converting
  * @since 3.6.0
  */
@@ -2055,7 +2133,9 @@ export const toDateUtc: (self: DateTime) => Date = Internal.toDateUtc
  *
  * **Details**
  *
- * For `DateTime.Zoned`, this adjusts for the time zone before converting.
+ * For `DateTime.Zoned`, this stores the zoned wall-clock time in the returned
+ * `Date`'s UTC fields, rather than preserving the original instant. Use
+ * `toDateUtc` to preserve the instant.
  * For `DateTime.Utc`, this is equivalent to `toDateUtc`.
  *
  * **Example** (Converting DateTime values to Dates)
@@ -2063,15 +2143,17 @@ export const toDateUtc: (self: DateTime) => Date = Internal.toDateUtc
  * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
- * const utc = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
- * const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
+ * const utc = DateTime.makeUnsafe("2024-07-01T12:00:00Z")
+ * const zoned = DateTime.makeZonedUnsafe("2024-07-01T12:00:00Z", {
  *   timeZone: "Europe/London"
  * })
  *
- * DateTime.toDate(utc).toISOString() // => "2024-01-01T12:00:00.000Z"
- * DateTime.toDate(zoned).toISOString() // => "2024-01-01T12:00:00.000Z"
+ * DateTime.toDate(utc).toISOString() // => "2024-07-01T12:00:00.000Z"
+ * DateTime.toDate(zoned).toISOString() // => "2024-07-01T13:00:00.000Z"
+ * DateTime.toDateUtc(zoned).toISOString() // => "2024-07-01T12:00:00.000Z"
  * ```
  *
+ * @stability stable
  * @category converting
  * @since 3.6.0
  */
@@ -2097,6 +2179,7 @@ export const toDate: (self: DateTime) => Date = Internal.toDate
  * DateTime.zonedOffset(zoned) // => 0
  * ```
  *
+ * @stability stable
  * @category converting
  * @since 3.6.0
  */
@@ -2121,6 +2204,7 @@ export const zonedOffset: (self: Zoned) => number = Internal.zonedOffset
  * DateTime.zonedOffsetIso(zoned) // => "+03:00"
  * ```
  *
+ * @stability stable
  * @category converting
  * @since 3.6.0
  */
@@ -2142,6 +2226,7 @@ export const zonedOffsetIso: (self: Zoned) => string = Internal.zonedOffsetIso
  * DateTime.toEpochMillis(dt) // => 1704067200000
  * ```
  *
+ * @stability stable
  * @category converting
  * @since 3.6.0
  */
@@ -2164,6 +2249,7 @@ export const toEpochMillis: (self: DateTime) => number = Internal.toEpochMillis
  * DateTime.toEpochSeconds(dt) // => 1704067200
  * ```
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */
@@ -2188,6 +2274,7 @@ export const toEpochSeconds: (self: DateTime) => number = Internal.toEpochSecond
  * ) // => "2024-01-01T00:00:00.000Z"
  * ```
  *
+ * @stability stable
  * @category converting
  * @since 3.6.0
  */
@@ -2215,6 +2302,7 @@ export const removeTime: (self: DateTime) => Utc = Internal.removeTime
  * const selectedParts = [parts.year, parts.month, parts.day, parts.hour] // => [2024, 1, 1, 12]
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 3.6.0
  */
@@ -2240,6 +2328,7 @@ export const toParts: (self: DateTime) => DateTime.PartsWithWeekday = Internal.t
  * const selectedParts = [parts.year, parts.month, parts.day, parts.hour] // => [2024, 1, 1, 12]
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 3.6.0
  */
@@ -2261,6 +2350,7 @@ export const toPartsUtc: (self: DateTime) => DateTime.PartsWithWeekday = Interna
  * DateTime.getPartUtc(dateTime, "year") // => 2024
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 3.6.0
  */
@@ -2281,6 +2371,7 @@ export const getPartUtc: {
    * DateTime.getPartUtc(dateTime, "year") // => 2024
    * ```
    *
+   * @stability stable
    * @category getters
    * @since 3.6.0
    */
@@ -2301,6 +2392,7 @@ export const getPartUtc: {
    * DateTime.getPartUtc(dateTime, "year") // => 2024
    * ```
    *
+   * @stability stable
    * @category getters
    * @since 3.6.0
    */
@@ -2325,6 +2417,7 @@ export const getPartUtc: {
  * DateTime.getPart(dateTime, "year") // => 2024
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 3.6.0
  */
@@ -2347,6 +2440,7 @@ export const getPart: {
    * DateTime.getPart(dateTime, "year") // => 2024
    * ```
    *
+   * @stability stable
    * @category getters
    * @since 3.6.0
    */
@@ -2369,6 +2463,7 @@ export const getPart: {
    * DateTime.getPart(dateTime, "year") // => 2024
    * ```
    *
+   * @stability stable
    * @category getters
    * @since 3.6.0
    */
@@ -2397,6 +2492,7 @@ export const getPart: {
  * updated // => DateTime.makeZonedUnsafe("2025-06-15T12:00:00Z", { timeZone: "UTC" })
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 3.6.0
  */
@@ -2423,6 +2519,7 @@ export const setParts: {
    * updated // => DateTime.makeZonedUnsafe("2025-06-15T12:00:00Z", { timeZone: "UTC" })
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 3.6.0
    */
@@ -2449,6 +2546,7 @@ export const setParts: {
    * updated // => DateTime.makeZonedUnsafe("2025-06-15T12:00:00Z", { timeZone: "UTC" })
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 3.6.0
    */
@@ -2476,6 +2574,7 @@ export const setParts: {
  * updated // => DateTime.makeUnsafe("2025-01-01T18:00:00Z")
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 3.6.0
  */
@@ -2501,6 +2600,7 @@ export const setPartsUtc: {
    * updated // => DateTime.makeUnsafe("2025-01-01T18:00:00Z")
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 3.6.0
    */
@@ -2526,6 +2626,7 @@ export const setPartsUtc: {
    * updated // => DateTime.makeUnsafe("2025-01-01T18:00:00Z")
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 3.6.0
    */
@@ -2560,6 +2661,7 @@ export const setPartsUtc: {
  * await Effect.runPromise(Effect.provide(program, layer)) // => "Europe/London"
  * ```
  *
+ * @stability stable
  * @category services
  * @since 3.11.0
  */
@@ -2582,6 +2684,7 @@ export class CurrentTimeZone extends Context.Service<CurrentTimeZone, TimeZone>(
  * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))) // => "Europe/London"
  * ```
  *
+ * @stability stable
  * @category accessors
  * @since 3.6.0
  */
@@ -2604,6 +2707,7 @@ export const setZoneCurrent = (self: DateTime): Effect.Effect<Zoned, never, Curr
  * }).pipe(DateTime.withCurrentZone(zone))) // => "Europe/London"
  * ```
  *
+ * @stability stable
  * @category providing services
  * @since 3.6.0
  */
@@ -2624,6 +2728,7 @@ export const withCurrentZone: {
    * }).pipe(DateTime.withCurrentZone(zone))) // => "Europe/London"
    * ```
    *
+   * @stability stable
    * @category providing services
    * @since 3.6.0
    */
@@ -2644,6 +2749,7 @@ export const withCurrentZone: {
    * }).pipe(DateTime.withCurrentZone(zone))) // => "Europe/London"
    * ```
    *
+   * @stability stable
    * @category providing services
    * @since 3.6.0
    */
@@ -2664,6 +2770,7 @@ export const withCurrentZone: {
  * }).pipe(DateTime.withCurrentZoneLocal)) // => true
  * ```
  *
+ * @stability stable
  * @category providing services
  * @since 3.6.0
  */
@@ -2687,6 +2794,7 @@ export const withCurrentZoneLocal = <A, E, R>(
  * await Effect.runPromise(program) // => "+03:00"
  * ```
  *
+ * @stability stable
  * @category providing services
  * @since 3.6.0
  */
@@ -2706,6 +2814,7 @@ export const withCurrentZoneOffset: {
    * await Effect.runPromise(program) // => "+03:00"
    * ```
    *
+   * @stability stable
    * @category providing services
    * @since 3.6.0
    */
@@ -2727,6 +2836,7 @@ export const withCurrentZoneOffset: {
    * await Effect.runPromise(program) // => "+03:00"
    * ```
    *
+   * @stability stable
    * @category providing services
    * @since 3.6.0
    */
@@ -2756,6 +2866,7 @@ export const withCurrentZoneOffset: {
  * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))) // => "Europe/London"
  * ```
  *
+ * @stability stable
  * @category providing services
  * @since 3.6.0
  */
@@ -2779,6 +2890,7 @@ export const withCurrentZoneNamed: {
    * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))) // => "Europe/London"
    * ```
    *
+   * @stability stable
    * @category providing services
    * @since 3.6.0
    */
@@ -2804,6 +2916,7 @@ export const withCurrentZoneNamed: {
    * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))) // => "Europe/London"
    * ```
    *
+   * @stability stable
    * @category providing services
    * @since 3.6.0
    */
@@ -2830,6 +2943,7 @@ export const withCurrentZoneNamed: {
  * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))) // => "Europe/London"
  * ```
  *
+ * @stability stable
  * @category accessors
  * @since 3.6.0
  */
@@ -2867,6 +2981,7 @@ export const nowInCurrentZone: Effect.Effect<Zoned, never, CurrentTimeZone> = Ef
  * })
  * ```
  *
+ * @stability stable
  * @category mapping
  * @since 3.6.0
  */
@@ -2903,6 +3018,7 @@ export const mutate: {
    * })
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 3.6.0
    */
@@ -2944,6 +3060,7 @@ export const mutate: {
    * })
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 3.6.0
    */
@@ -2980,6 +3097,7 @@ export const mutate: {
  * modified // => DateTime.makeZonedUnsafe("2024-01-01T18:00:00Z", { timeZone: "Europe/London" })
  * ```
  *
+ * @stability stable
  * @category mapping
  * @since 3.6.0
  */
@@ -3008,6 +3126,7 @@ export const mutateUtc: {
    * modified // => DateTime.makeZonedUnsafe("2024-01-01T18:00:00Z", { timeZone: "Europe/London" })
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 3.6.0
    */
@@ -3036,6 +3155,7 @@ export const mutateUtc: {
    * modified // => DateTime.makeZonedUnsafe("2024-01-01T18:00:00Z", { timeZone: "Europe/London" })
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 3.6.0
    */
@@ -3058,6 +3178,7 @@ export const mutateUtc: {
  * result // => DateTime.makeUnsafe(10)
  * ```
  *
+ * @stability stable
  * @category mapping
  * @since 3.6.0
  */
@@ -3078,6 +3199,7 @@ export const mapEpochMillis: {
    * result // => DateTime.makeUnsafe(10)
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 3.6.0
    */
@@ -3098,6 +3220,7 @@ export const mapEpochMillis: {
    * result // => DateTime.makeUnsafe(10)
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 3.6.0
    */
@@ -3125,6 +3248,7 @@ export const mapEpochMillis: {
  * ) // => 3600000
  * ```
  *
+ * @stability stable
  * @category mapping
  * @since 3.6.0
  */
@@ -3150,6 +3274,7 @@ export const withDate: {
    * ) // => 3600000
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 3.6.0
    */
@@ -3175,6 +3300,7 @@ export const withDate: {
    * ) // => 3600000
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 3.6.0
    */
@@ -3201,6 +3327,7 @@ export const withDate: {
  * ) // => 0
  * ```
  *
+ * @stability stable
  * @category mapping
  * @since 3.6.0
  */
@@ -3225,6 +3352,7 @@ export const withDateUtc: {
    * ) // => 0
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 3.6.0
    */
@@ -3249,6 +3377,7 @@ export const withDateUtc: {
    * ) // => 0
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 3.6.0
    */
@@ -3282,6 +3411,7 @@ export const withDateUtc: {
  * result2 // => "Zoned: 2024-06-15T15:30:00.000+01:00[Europe/London]"
  * ```
  *
+ * @stability stable
  * @category mapping
  * @since 3.6.0
  */
@@ -3313,6 +3443,7 @@ export const match: {
    * result2 // => "Zoned: 2024-06-15T15:30:00.000+01:00[Europe/London]"
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 3.6.0
    */
@@ -3349,6 +3480,7 @@ export const match: {
    * result2 // => "Zoned: 2024-06-15T15:30:00.000+01:00[Europe/London]"
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 3.6.0
    */
@@ -3398,6 +3530,7 @@ export const match: {
  * @see {@link add} for calendar-aware date/time part arithmetic
  * @see {@link subtractDuration} for subtracting an elapsed duration
  *
+ * @stability stable
  * @category math
  * @since 3.6.0
  */
@@ -3439,6 +3572,7 @@ export const addDuration: {
    * @see {@link add} for calendar-aware date/time part arithmetic
    * @see {@link subtractDuration} for subtracting an elapsed duration
    *
+   * @stability stable
    * @category math
    * @since 3.6.0
    */
@@ -3480,6 +3614,7 @@ export const addDuration: {
    * @see {@link add} for calendar-aware date/time part arithmetic
    * @see {@link subtractDuration} for subtracting an elapsed duration
    *
+   * @stability stable
    * @category math
    * @since 3.6.0
    */
@@ -3500,6 +3635,7 @@ export const addDuration: {
  * ) // => DateTime.makeUnsafe(-300000)
  * ```
  *
+ * @stability stable
  * @category math
  * @since 3.6.0
  */
@@ -3518,6 +3654,7 @@ export const subtractDuration: {
    * ) // => DateTime.makeUnsafe(-300000)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 3.6.0
    */
@@ -3536,6 +3673,7 @@ export const subtractDuration: {
    * ) // => DateTime.makeUnsafe(-300000)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 3.6.0
    */
@@ -3561,6 +3699,7 @@ export const subtractDuration: {
  * ) // => DateTime.makeUnsafe(300000)
  * ```
  *
+ * @stability stable
  * @category math
  * @since 3.6.0
  */
@@ -3584,6 +3723,7 @@ export const add: {
    * ) // => DateTime.makeUnsafe(300000)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 3.6.0
    */
@@ -3607,6 +3747,7 @@ export const add: {
    * ) // => DateTime.makeUnsafe(300000)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 3.6.0
    */
@@ -3627,6 +3768,7 @@ export const add: {
  * ) // => DateTime.makeUnsafe(-300000)
  * ```
  *
+ * @stability stable
  * @category math
  * @since 3.6.0
  */
@@ -3645,6 +3787,7 @@ export const subtract: {
    * ) // => DateTime.makeUnsafe(-300000)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 3.6.0
    */
@@ -3663,6 +3806,7 @@ export const subtract: {
    * ) // => DateTime.makeUnsafe(-300000)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 3.6.0
    */
@@ -3688,6 +3832,7 @@ export const subtract: {
  * ) // => DateTime.makeUnsafe("2024-01-01T00:00:00Z")
  * ```
  *
+ * @stability stable
  * @category math
  * @since 3.6.0
  */
@@ -3711,6 +3856,7 @@ export const startOf: {
    * ) // => DateTime.makeUnsafe("2024-01-01T00:00:00Z")
    * ```
    *
+   * @stability stable
    * @category math
    * @since 3.6.0
    */
@@ -3737,6 +3883,7 @@ export const startOf: {
    * ) // => DateTime.makeUnsafe("2024-01-01T00:00:00Z")
    * ```
    *
+   * @stability stable
    * @category math
    * @since 3.6.0
    */
@@ -3766,6 +3913,7 @@ export const startOf: {
  * ) // => DateTime.makeUnsafe("2024-01-01T23:59:59.999Z")
  * ```
  *
+ * @stability stable
  * @category math
  * @since 3.6.0
  */
@@ -3789,6 +3937,7 @@ export const endOf: {
    * ) // => DateTime.makeUnsafe("2024-01-01T23:59:59.999Z")
    * ```
    *
+   * @stability stable
    * @category math
    * @since 3.6.0
    */
@@ -3815,6 +3964,7 @@ export const endOf: {
    * ) // => DateTime.makeUnsafe("2024-01-01T23:59:59.999Z")
    * ```
    *
+   * @stability stable
    * @category math
    * @since 3.6.0
    */
@@ -3844,6 +3994,7 @@ export const endOf: {
  * ) // => DateTime.makeUnsafe("2024-01-02T00:00:00Z")
  * ```
  *
+ * @stability stable
  * @category math
  * @since 3.6.0
  */
@@ -3867,6 +4018,7 @@ export const nearest: {
    * ) // => DateTime.makeUnsafe("2024-01-02T00:00:00Z")
    * ```
    *
+   * @stability stable
    * @category math
    * @since 3.6.0
    */
@@ -3893,6 +4045,7 @@ export const nearest: {
    * ) // => DateTime.makeUnsafe("2024-01-02T00:00:00Z")
    * ```
    *
+   * @stability stable
    * @category math
    * @since 3.6.0
    */
@@ -3935,6 +4088,7 @@ export const nearest: {
  * }) // => "Saturday, June 15, 2024 at 3:30 PM"
  * ```
  *
+ * @stability stable
  * @category formatting
  * @since 3.6.0
  */
@@ -3971,6 +4125,7 @@ export const format: {
    * }) // => "Saturday, June 15, 2024 at 3:30 PM"
    * ```
    *
+   * @stability stable
    * @category formatting
    * @since 3.6.0
    */
@@ -4013,6 +4168,7 @@ export const format: {
    * }) // => "Saturday, June 15, 2024 at 3:30 PM"
    * ```
    *
+   * @stability stable
    * @category formatting
    * @since 3.6.0
    */
@@ -4047,6 +4203,7 @@ export const format: {
  * })
  * ```
  *
+ * @stability stable
  * @category formatting
  * @since 3.6.0
  */
@@ -4072,6 +4229,7 @@ export const formatLocal: {
    * })
    * ```
    *
+   * @stability stable
    * @category formatting
    * @since 3.6.0
    */
@@ -4103,6 +4261,7 @@ export const formatLocal: {
    * })
    * ```
    *
+   * @stability stable
    * @category formatting
    * @since 3.6.0
    */
@@ -4143,6 +4302,7 @@ export const formatLocal: {
  * })
  * ```
  *
+ * @stability stable
  * @category formatting
  * @since 3.6.0
  */
@@ -4174,6 +4334,7 @@ export const formatUtc: {
    * })
    * ```
    *
+   * @stability stable
    * @category formatting
    * @since 3.6.0
    */
@@ -4211,6 +4372,7 @@ export const formatUtc: {
    * })
    * ```
    *
+   * @stability stable
    * @category formatting
    * @since 3.6.0
    */
@@ -4260,6 +4422,7 @@ export const formatUtc: {
  * @see {@link formatUtc} for formatting with options forced to UTC
  * @see {@link formatIso} for stable ISO formatting
  *
+ * @stability stable
  * @category formatting
  * @since 3.6.0
  */
@@ -4300,6 +4463,7 @@ export const formatIntl: {
    * @see {@link formatUtc} for formatting with options forced to UTC
    * @see {@link formatIso} for stable ISO formatting
    *
+   * @stability stable
    * @category formatting
    * @since 3.6.0
    */
@@ -4340,6 +4504,7 @@ export const formatIntl: {
    * @see {@link formatUtc} for formatting with options forced to UTC
    * @see {@link formatIso} for stable ISO formatting
    *
+   * @stability stable
    * @category formatting
    * @since 3.6.0
    */
@@ -4366,6 +4531,7 @@ export const formatIntl: {
  * DateTime.formatIso(zoned) // => "2024-01-01T12:30:45.123Z"
  * ```
  *
+ * @stability stable
  * @category formatting
  * @since 3.6.0
  */
@@ -4392,6 +4558,7 @@ export const formatIso: (self: DateTime) => string = Internal.formatIso
  * DateTime.formatIsoDate(zoned) // => "2024-01-02"
  * ```
  *
+ * @stability stable
  * @category formatting
  * @since 3.6.0
  */
@@ -4418,6 +4585,7 @@ export const formatIsoDate: (self: DateTime) => string = Internal.formatIsoDate
  * DateTime.formatIsoDateUtc(zoned) // => "2024-01-01"
  * ```
  *
+ * @stability stable
  * @category formatting
  * @since 3.6.0
  */
@@ -4445,6 +4613,7 @@ export const formatIsoDateUtc: (self: DateTime) => string = Internal.formatIsoDa
  * DateTime.formatIsoOffset(zoned) // => "2024-01-01T15:00:00.000+03:00"
  * ```
  *
+ * @stability stable
  * @category formatting
  * @since 3.6.0
  */
@@ -4475,6 +4644,7 @@ export const formatIsoOffset: (self: DateTime) => string = Internal.formatIsoOff
  * DateTime.formatIsoZoned(offsetZone) // => "2024-06-15T17:30:45.123+03:00"
  * ```
  *
+ * @stability stable
  * @category formatting
  * @since 3.6.0
  */
@@ -4504,6 +4674,7 @@ export const formatIsoZoned: (self: Zoned) => string = Internal.formatIsoZoned
  * await Effect.runPromise(Effect.provide(program, layer)) // => "Europe/London"
  * ```
  *
+ * @stability stable
  * @category layers
  * @since 3.6.0
  */
@@ -4534,6 +4705,7 @@ export const layerCurrentZone: (resource: NoInfer<TimeZone>) => Layer.Layer<Curr
  * await Effect.runPromise(Effect.provide(program, layer)) // => "+03:00"
  * ```
  *
+ * @stability stable
  * @category layers
  * @since 3.6.0
  */
@@ -4563,6 +4735,7 @@ export const layerCurrentZoneOffset = (offset: number): Layer.Layer<CurrentTimeZ
  * await Effect.runPromise(Effect.provide(program, layer)) // => "Europe/London"
  * ```
  *
+ * @stability stable
  * @category layers
  * @since 3.6.0
  */
@@ -4593,6 +4766,7 @@ export const layerCurrentZoneNamed: (zoneId: string) => Layer.Layer<
  * await Effect.runPromise(Effect.provide(program, DateTime.layerCurrentZoneLocal)) // => true
  * ```
  *
+ * @stability stable
  * @category layers
  * @since 3.6.0
  */