effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/DateTime.js

@@ -10,43 +10,45 @@ const TimeZoneTypeId = Internal.TimeZoneTypeId;
 // guards
 // =============================================================================
 /**
- * @since 3.6.0
+ * Checks whether a value is a `DateTime`.
+ *
  * @category guards
+ * @since 3.6.0
  */
 export const isDateTime = Internal.isDateTime;
 /**
  * Checks if a value is a `TimeZone`.
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export const isTimeZone = Internal.isTimeZone;
 /**
  * Checks if a value is an offset-based `TimeZone`.
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export const isTimeZoneOffset = Internal.isTimeZoneOffset;
 /**
  * Checks if a value is a named `TimeZone` (IANA time zone).
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export const isTimeZoneNamed = Internal.isTimeZoneNamed;
 /**
  * Checks if a `DateTime` is a UTC `DateTime` (no time zone information).
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export const isUtc = Internal.isUtc;
 /**
  * Checks if a `DateTime` is a zoned `DateTime` (has time zone information).
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export const isZoned = Internal.isZoned;
 // =============================================================================
@@ -58,7 +60,8 @@ export const isZoned = Internal.isZoned;
  * Two `DateTime` values are considered equivalent if they represent the same
  * point in time, regardless of their time zone.
  *
- * @example
+ * **Example** (Comparing DateTime values for equivalence)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -80,7 +83,8 @@ export const Equivalence = Internal.Equivalence;
  * `DateTime` values are ordered by their epoch milliseconds, so earlier times
  * come before later times regardless of time zone.
  *
- * @example
+ * **Example** (Sorting DateTime values chronologically)
+ *
  * ```ts
  * import { Array, DateTime } from "effect"
  *
@@ -105,7 +109,8 @@ export const Order = Internal.Order;
  * If the `DateTime` is after the maximum, the maximum is returned.
  * Otherwise, the original `DateTime` is returned.
  *
- * @example
+ * **Example** (Clamping DateTime values)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -129,7 +134,8 @@ export const clamp = Internal.clamp;
  *
  * If the `Date` is invalid, an `IllegalArgumentError` will be thrown.
  *
- * @example
+ * **Example** (Creating DateTime values from Dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -152,21 +158,26 @@ export const fromDateUnsafe = Internal.fromDateUnsafe;
  * - An object with the parts of a date
  * - A `string` that can be parsed by `Date.parse`
  *
- * @since 3.6.0
- * @category constructors
- * @example
+ * **Example** (Creating DateTime values unsafely)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
  * // from Date
- * DateTime.makeUnsafe(new Date())
+ * const fromDate = DateTime.makeUnsafe(new Date("2024-01-01T12:00:00Z"))
+ * console.log(DateTime.formatIso(fromDate)) // "2024-01-01T12:00:00.000Z"
  *
  * // from parts
- * DateTime.makeUnsafe({ year: 2024 })
+ * const fromParts = DateTime.makeUnsafe({ year: 2024 })
+ * console.log(DateTime.formatIso(fromParts)) // "2024-01-01T00:00:00.000Z"
  *
  * // from string
- * DateTime.makeUnsafe("2024-01-01")
+ * const fromString = DateTime.makeUnsafe("2024-01-01")
+ * console.log(DateTime.formatIso(fromString)) // "2024-01-01T00:00:00.000Z"
  * ```
+ *
+ * @category constructors
+ * @since 3.6.0
  */
 export const makeUnsafe = Internal.makeUnsafe;
 /**
@@ -183,76 +194,108 @@ export const makeUnsafe = Internal.makeUnsafe;
  * - `later`: Always choose the later of two possible times
  * - `reject`: Throw an error when ambiguous times are encountered
  *
- * @since 3.6.0
- * @category constructors
- * @example
+ * **Example** (Creating zoned DateTime values unsafely)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
- * DateTime.makeZonedUnsafe(new Date(), { timeZone: "Europe/London" })
+ * const zoned = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
+ *   timeZone: "Europe/London"
+ * })
+ *
+ * console.log(DateTime.formatIsoZoned(zoned)) // "2024-06-15T15:30:00.000+01:00[Europe/London]"
  * ```
+ *
+ * @category constructors
+ * @since 3.6.0
  */
 export const makeZonedUnsafe = Internal.makeZonedUnsafe;
 /**
- * Create a `DateTime.Zoned` using `DateTime.make` and a time zone.
+ * Creates a `DateTime.Zoned` from an input and a time zone.
  *
- * The input is treated as UTC and then the time zone is attached, unless
- * `adjustForTimeZone` is set to `true`. In that case, the input is treated as
- * already in the time zone.
+ * By default, the input is interpreted as a UTC instant and the time zone is
+ * attached without changing that instant. When `adjustForTimeZone` is `true`,
+ * the input is interpreted as wall-clock time in the target zone.
  *
- * When `adjustForTimeZone` is true and ambiguous times occur during DST transitions,
- * the `disambiguation` option controls how to resolve the ambiguity:
- * - `compatible` (default): Choose earlier time for repeated times, later for gaps
- * - `earlier`: Always choose the earlier of two possible times
- * - `later`: Always choose the later of two possible times
- * - `reject`: Throw an error when ambiguous times are encountered
+ * When `adjustForTimeZone` is `true`, `disambiguation` controls
+ * daylight-saving gaps and repeated times:
  *
- * If the date time input or time zone is invalid, `None` will be returned.
+ * - `"compatible"` (default): chooses the earlier occurrence for repeated
+ *   times and the later interpretation for gaps
+ * - `"earlier"`: chooses the earlier possible instant
+ * - `"later"`: chooses the later possible instant
+ * - `"reject"`: rejects ambiguous or nonexistent wall-clock times
+ *
+ * Returns `Some` when construction succeeds, or `None` when the input, time
+ * zone, or disambiguation cannot be resolved.
+ *
+ * **Example** (Creating optional zoned DateTime values)
  *
- * @since 3.6.0
- * @category constructors
- * @example
  * ```ts
  * import { DateTime } from "effect"
  *
- * DateTime.makeZoned(new Date(), { timeZone: "Europe/London" })
+ * const result = DateTime.makeZoned("2024-06-15T14:30:00Z", {
+ *   timeZone: "Europe/London"
+ * })
+ *
+ * console.log(result._tag) // "Some"
+ * if (result._tag === "Some") {
+ *   console.log(DateTime.formatIsoZoned(result.value)) // "2024-06-15T15:30:00.000+01:00[Europe/London]"
+ * }
  * ```
+ *
+ * @category constructors
+ * @since 3.6.0
  */
 export const makeZoned = Internal.makeZoned;
 /**
- * Create a `DateTime` from one of the following:
+ * Creates a `DateTime` from one of the following:
  *
  * - A `DateTime`
- * - A `Date` instance (invalid dates will throw an `IllegalArgumentError`)
- * - The `number` of milliseconds since the Unix epoch
- * - An object with the parts of a date
- * - A `string` that can be parsed by `Date.parse`
+ * - A JavaScript `Date`
+ * - The number of milliseconds since the Unix epoch
+ * - An object with date and time parts
+ * - A string that can be parsed as a date
  *
- * If the input is invalid, `None` will be returned.
+ * Returns `Some` with the constructed `DateTime` when the input is valid, or
+ * `None` when construction would fail, including invalid `Date` instances or
+ * unparseable strings.
+ *
+ * **Example** (Creating optional DateTime values)
  *
- * @since 3.6.0
- * @category constructors
- * @example
  * ```ts
  * import { DateTime } from "effect"
  *
  * // from Date
- * DateTime.make(new Date())
+ * const fromDate = DateTime.make(new Date("2024-01-01T12:00:00Z"))
+ * console.log(fromDate._tag) // "Some"
  *
  * // from parts
- * DateTime.make({ year: 2024 })
+ * const fromParts = DateTime.make({ year: 2024 })
+ * console.log(fromParts._tag) // "Some"
  *
  * // from string
- * DateTime.make("2024-01-01")
+ * const fromString = DateTime.make("2024-01-01")
+ * console.log(fromString._tag) // "Some"
+ *
+ * const invalid = DateTime.make("not a date")
+ * console.log(invalid._tag) // "None"
  * ```
+ *
+ * @category constructors
+ * @since 3.6.0
  */
 export const make = Internal.make;
 /**
- * Create a `DateTime.Zoned` from a string.
+ * Parses an ISO zoned date-time string into a `DateTime.Zoned`.
  *
- * It uses the format: `YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]`.
+ * Accepts named-zone strings such as
+ * `YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]` and offset-only strings such as
+ * `YYYY-MM-DDTHH:mm:ss.sss+HH:MM`. Returns `None` when the input cannot be
+ * parsed.
+ *
+ * **Example** (Parsing zoned DateTime strings)
  *
- * @example
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -268,31 +311,34 @@ export const make = Internal.make;
  * console.log(invalid._tag === "None") // true
  * ```
  *
- * @since 3.6.0
  * @category constructors
+ * @since 3.6.0
  */
 export const makeZonedFromString = Internal.makeZonedFromString;
 /**
  * Get the current time using the `Clock` service and convert it to a `DateTime`.
  *
- * @since 3.6.0
- * @category constructors
- * @example
+ * **Example** (Getting the current DateTime)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
  * Effect.gen(function*() {
- *   const now = yield* DateTime.now
+ *   const now = yield* DateTime.nowAsDate
+ *   console.log(now instanceof Date) // true
  * })
  * ```
+ *
+ * @category constructors
+ * @since 3.6.0
  */
 export const now = Internal.now;
 /**
- * Get the current time using the `Clock` service and convert it to a `DateTime`.
+ * Gets the current time from the `Clock` service and returns it as a
+ * JavaScript `Date`.
+ *
+ * **Example** (Getting the current Date)
  *
- * @since 3.6.0
- * @category constructors
- * @example
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -300,6 +346,9 @@ export const now = Internal.now;
  *   const now = yield* DateTime.now
  * })
  * ```
+ *
+ * @category constructors
+ * @since 3.6.0
  */
 export const nowAsDate = Internal.nowAsDate;
 /**
@@ -308,7 +357,8 @@ export const nowAsDate = Internal.nowAsDate;
  * This is a synchronous version of `now` that directly uses `Date.now()`
  * instead of the Effect `Clock` service.
  *
- * @example
+ * **Example** (Getting the current DateTime unsafely)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -326,9 +376,8 @@ export const nowUnsafe = Internal.nowUnsafe;
 /**
  * For a `DateTime` returns a new `DateTime.Utc`.
  *
- * @since 3.13.0
- * @category time zones
- * @example
+ * **Example** (Converting DateTime values to UTC)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -339,14 +388,16 @@ export const nowUnsafe = Internal.nowUnsafe;
  * // set as UTC
  * const utc: DateTime.Utc = DateTime.toUtc(now)
  * ```
+ *
+ * @category time zones
+ * @since 3.13.0
  */
 export const toUtc = Internal.toUtc;
 /**
  * Set the time zone of a `DateTime`, returning a new `DateTime.Zoned`.
  *
- * @since 3.6.0
- * @category time zones
- * @example
+ * **Example** (Setting time zones)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -358,6 +409,9 @@ export const toUtc = Internal.toUtc;
  *   const zoned: DateTime.Zoned = DateTime.setZone(now, zone)
  * })
  * ```
+ *
+ * @category time zones
+ * @since 3.6.0
  */
 export const setZone = Internal.setZone;
 /**
@@ -365,9 +419,8 @@ export const setZone = Internal.setZone;
  *
  * The offset is in milliseconds.
  *
- * @since 3.6.0
- * @category time zones
- * @example
+ * **Example** (Setting fixed-offset time zones)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -378,6 +431,9 @@ export const setZone = Internal.setZone;
  *   const zoned: DateTime.Zoned = DateTime.setZoneOffset(now, 3 * 60 * 60 * 1000)
  * })
  * ```
+ *
+ * @category time zones
+ * @since 3.6.0
  */
 export const setZoneOffset = Internal.setZoneOffset;
 /**
@@ -385,7 +441,8 @@ export const setZoneOffset = Internal.setZoneOffset;
  *
  * If the time zone is invalid, an `IllegalArgumentError` will be thrown.
  *
- * @example
+ * **Example** (Creating named time zones unsafely)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -399,8 +456,8 @@ export const setZoneOffset = Internal.setZoneOffset;
  * // DateTime.zoneMakeNamedUnsafe("Invalid/Zone")
  * ```
  *
- * @since 3.6.0
  * @category time zones
+ * @since 3.6.0
  */
 export const zoneMakeNamedUnsafe = Internal.zoneMakeNamedUnsafe;
 /**
@@ -409,7 +466,8 @@ export const zoneMakeNamedUnsafe = Internal.zoneMakeNamedUnsafe;
  * The offset is specified in milliseconds from UTC. Positive values are
  * ahead of UTC, negative values are behind UTC.
  *
- * @example
+ * **Example** (Creating fixed-offset time zones)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -430,7 +488,8 @@ export const zoneMakeOffset = Internal.zoneMakeOffset;
  *
  * If the time zone is invalid, `None` will be returned.
  *
- * @example
+ * **Example** (Creating optional named time zones)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -450,7 +509,8 @@ export const zoneMakeNamed = Internal.zoneMakeNamed;
  *
  * If the time zone is invalid, it will fail with an `IllegalArgumentError`.
  *
- * @example
+ * **Example** (Creating named time zones effectfully)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -471,15 +531,13 @@ export const zoneMakeNamedEffect = Internal.zoneMakeNamedEffect;
  * This uses the system's configured time zone, which may vary depending
  * on the runtime environment.
  *
- * @example
+ * **Example** (Creating local time zones)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
  * const localZone = DateTime.zoneMakeLocal()
- * const now = DateTime.nowUnsafe()
- * const localTime = DateTime.setZone(now, localZone)
- *
- * console.log(DateTime.formatIsoZoned(localTime))
+ * console.log(DateTime.zoneToString(localZone)) // Output depends on system time zone
  * ```
  *
  * @category time zones
@@ -491,7 +549,8 @@ export const zoneMakeLocal = Internal.zoneMakeLocal;
  *
  * Supports both IANA time zone identifiers and offset formats like "+03:00".
  *
- * @example
+ * **Example** (Parsing time zones)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -511,9 +570,8 @@ export const zoneFromString = Internal.zoneFromString;
 /**
  * Format a `TimeZone` as a string.
  *
- * @since 3.6.0
- * @category time zones
- * @example
+ * **Example** (Formatting time zones)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -523,15 +581,17 @@ export const zoneFromString = Internal.zoneFromString;
  * // Outputs "Europe/London"
  * DateTime.zoneToString(DateTime.zoneMakeNamedUnsafe("Europe/London"))
  * ```
+ *
+ * @category time zones
+ * @since 3.6.0
  */
 export const zoneToString = Internal.zoneToString;
 /**
  * Set the time zone of a `DateTime` from an IANA time zone identifier. If the
  * time zone is invalid, `None` will be returned.
  *
- * @since 3.6.0
- * @category time zones
- * @example
+ * **Example** (Setting named time zones safely)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -541,15 +601,17 @@ export const zoneToString = Internal.zoneToString;
  *   DateTime.setZoneNamed(now, "Europe/London")
  * })
  * ```
+ *
+ * @category time zones
+ * @since 3.6.0
  */
 export const setZoneNamed = Internal.setZoneNamed;
 /**
  * Set the time zone of a `DateTime` from an IANA time zone identifier. If the
  * time zone is invalid, an `IllegalArgumentError` will be thrown.
  *
- * @since 3.6.0
- * @category time zones
- * @example
+ * **Example** (Setting named time zones unsafely)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -559,6 +621,9 @@ export const setZoneNamed = Internal.setZoneNamed;
  *   DateTime.setZoneNamedUnsafe(now, "Europe/London")
  * })
  * ```
+ *
+ * @category time zones
+ * @since 3.6.0
  */
 export const setZoneNamedUnsafe = Internal.setZoneNamedUnsafe;
 // =============================================================================
@@ -572,9 +637,8 @@ export const setZoneNamedUnsafe = Internal.setZoneNamedUnsafe;
  * `other` is *before* `self`, the result will be a negative `Duration`. If they
  * are equal, the result will be a `Duration` of zero.
  *
- * @since 3.6.0
- * @category comparisons
- * @example
+ * **Example** (Measuring distance between DateTime values)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -586,12 +650,16 @@ export const setZoneNamedUnsafe = Internal.setZoneNamedUnsafe;
  *   DateTime.distance(now, other)
  * })
  * ```
+ *
+ * @category comparisons
+ * @since 3.6.0
  */
 export const distance = Internal.distance;
 /**
  * Returns the earlier of two `DateTime` values.
  *
- * @example
+ * **Example** (Selecting the earlier DateTime)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -609,7 +677,8 @@ export const min = Internal.min;
 /**
  * Returns the later of two `DateTime` values.
  *
- * @example
+ * **Example** (Selecting the later DateTime)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -627,7 +696,8 @@ export const max = Internal.max;
 /**
  * Checks if the first `DateTime` is after the second `DateTime`.
  *
- * @example
+ * **Example** (Checking whether a DateTime is later)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -645,7 +715,8 @@ export const isGreaterThan = Internal.isGreaterThan;
 /**
  * Checks if the first `DateTime` is after or equal to the second `DateTime`.
  *
- * @example
+ * **Example** (Checking whether a DateTime is later or equal)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -665,7 +736,8 @@ export const isGreaterThanOrEqualTo = Internal.isGreaterThanOrEqualTo;
 /**
  * Checks if the first `DateTime` is before the second `DateTime`.
  *
- * @example
+ * **Example** (Checking whether a DateTime is earlier)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -683,7 +755,8 @@ export const isLessThan = Internal.isLessThan;
 /**
  * Checks if the first `DateTime` is before or equal to the second `DateTime`.
  *
- * @example
+ * **Example** (Checking whether a DateTime is earlier or equal)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -703,7 +776,8 @@ export const isLessThanOrEqualTo = Internal.isLessThanOrEqualTo;
 /**
  * Checks if a `DateTime` is between two other `DateTime` values (inclusive).
  *
- * @example
+ * **Example** (Checking whether a DateTime is within bounds)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -723,7 +797,8 @@ export const between = Internal.between;
  *
  * This is an effectful operation that uses the current time from the `Clock` service.
  *
- * @example
+ * **Example** (Checking future DateTime values effectfully)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -743,7 +818,8 @@ export const isFuture = Internal.isFuture;
  *
  * This is a synchronous version that uses `Date.now()` directly.
  *
- * @example
+ * **Example** (Checking future DateTime values unsafely)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -763,7 +839,8 @@ export const isFutureUnsafe = Internal.isFutureUnsafe;
  *
  * This is an effectful operation that uses the current time from the `Clock` service.
  *
- * @example
+ * **Example** (Checking past DateTime values effectfully)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -783,7 +860,8 @@ export const isPast = Internal.isPast;
  *
  * This is a synchronous version that uses `Date.now()` directly.
  *
- * @example
+ * **Example** (Checking past DateTime values unsafely)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -806,7 +884,8 @@ export const isPastUnsafe = Internal.isPastUnsafe;
  *
  * This always returns the UTC representation, ignoring any time zone information.
  *
- * @example
+ * **Example** (Converting DateTime values to UTC Dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -828,7 +907,8 @@ export const toDateUtc = Internal.toDateUtc;
  * For `DateTime.Zoned`, this adjusts for the time zone before converting.
  * For `DateTime.Utc`, this is equivalent to `toDateUtc`.
  *
- * @example
+ * **Example** (Converting DateTime values to Dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -851,7 +931,8 @@ export const toDate = Internal.toDate;
  * Returns the offset from UTC in milliseconds. Positive values indicate
  * time zones ahead of UTC, negative values indicate time zones behind UTC.
  *
- * @example
+ * **Example** (Reading zoned offsets)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -872,7 +953,8 @@ export const zonedOffset = Internal.zonedOffset;
  *
  * The offset is formatted as "±HH:MM".
  *
- * @example
+ * **Example** (Formatting zoned offsets)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -893,7 +975,8 @@ export const zonedOffsetIso = Internal.zonedOffsetIso;
  *
  * This returns the UTC timestamp regardless of any time zone information.
  *
- * @example
+ * **Example** (Reading epoch milliseconds)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -901,7 +984,6 @@ export const zonedOffsetIso = Internal.zonedOffsetIso;
  * const epochMillis = DateTime.toEpochMillis(dt)
  *
  * console.log(epochMillis) // 1704067200000
- * console.log(new Date(epochMillis).toISOString()) // "2024-01-01T00:00:00.000Z"
  * ```
  *
  * @category conversions
@@ -912,9 +994,8 @@ export const toEpochMillis = Internal.toEpochMillis;
  * Remove the time aspect of a `DateTime`, first adjusting for the time
  * zone. It will return a `DateTime.Utc` only containing the date.
  *
- * @since 3.6.0
- * @category conversions
- * @example
+ * **Example** (Removing time components)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -927,6 +1008,9 @@ export const toEpochMillis = Internal.toEpochMillis;
  *   DateTime.formatIso
  * )
  * ```
+ *
+ * @category conversions
+ * @since 3.6.0
  */
 export const removeTime = Internal.removeTime;
 // =============================================================================
@@ -937,7 +1021,8 @@ export const removeTime = Internal.removeTime;
  *
  * The parts will be time zone adjusted if the `DateTime` is zoned.
  *
- * @example
+ * **Example** (Reading DateTime parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -966,7 +1051,8 @@ export const toParts = Internal.toParts;
  *
  * The parts will always be in UTC, ignoring any time zone information.
  *
- * @example
+ * **Example** (Reading UTC DateTime parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -988,17 +1074,18 @@ export const toPartsUtc = Internal.toPartsUtc;
  *
  * The part will be in the UTC time zone.
  *
- * @since 3.6.0
- * @category parts
- * @example
+ * **Example** (Reading UTC DateTime parts by key)
+ *
  * ```ts
  * import { DateTime } from "effect"
- * import * as assert from "node:assert"
  *
- * const now = DateTime.makeUnsafe({ year: 2024 })
- * const year = DateTime.getPartUtc(now, "year")
- * assert.strictEqual(year, 2024)
+ * const dateTime = DateTime.makeUnsafe({ year: 2024 })
+ * const year = DateTime.getPartUtc(dateTime, "year")
+ * console.log(year) // 2024
  * ```
+ *
+ * @category parts
+ * @since 3.6.0
  */
 export const getPartUtc = Internal.getPartUtc;
 /**
@@ -1006,19 +1093,20 @@ export const getPartUtc = Internal.getPartUtc;
  *
  * The part will be time zone adjusted.
  *
- * @since 3.6.0
- * @category parts
- * @example
+ * **Example** (Reading DateTime parts by key)
+ *
  * ```ts
  * import { DateTime } from "effect"
- * import * as assert from "node:assert"
  *
- * const now = DateTime.makeZonedUnsafe({ year: 2024 }, {
+ * const dateTime = DateTime.makeZonedUnsafe({ year: 2024 }, {
  *   timeZone: "Europe/London"
  * })
- * const year = DateTime.getPart(now, "year")
- * assert.strictEqual(year, 2024)
+ * const year = DateTime.getPart(dateTime, "year")
+ * console.log(year) // 2024
  * ```
+ *
+ * @category parts
+ * @since 3.6.0
  */
 export const getPart = Internal.getPart;
 /**
@@ -1026,7 +1114,8 @@ export const getPart = Internal.getPart;
  *
  * The date will be time zone adjusted for `DateTime.Zoned`.
  *
- * @example
+ * **Example** (Updating DateTime parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1049,7 +1138,8 @@ export const setParts = Internal.setParts;
  *
  * The parts are always interpreted as UTC, ignoring any time zone information.
  *
- * @example
+ * **Example** (Updating UTC DateTime parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1070,7 +1160,15 @@ export const setPartsUtc = Internal.setPartsUtc;
 // current time zone
 // =============================================================================
 /**
- * @example
+ * Context service that supplies the ambient `TimeZone` for APIs that work in
+ * the current zone, such as `DateTime.setZoneCurrent` and
+ * `DateTime.nowInCurrentZone`.
+ *
+ * Provide it with `DateTime.withCurrentZone`, one of the `withCurrentZone*`
+ * helpers, or one of the `layerCurrentZone*` layers.
+ *
+ * **Example** (Accessing the current time zone service)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -1085,17 +1183,16 @@ export const setPartsUtc = Internal.setPartsUtc;
  * Effect.provide(program, layer)
  * ```
  *
- * @since 3.11.0
  * @category current time zone
+ * @since 3.11.0
  */
 export class CurrentTimeZone extends /*#__PURE__*/Context.Service()("effect/DateTime/CurrentTimeZone") {}
 /**
  * Set the time zone of a `DateTime` to the current time zone, which is
  * determined by the `CurrentTimeZone` service.
  *
- * @since 3.6.0
- * @category current time zone
- * @example
+ * **Example** (Setting the current time zone)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -1106,14 +1203,16 @@ export class CurrentTimeZone extends /*#__PURE__*/Context.Service()("effect/Date
  *   const zoned = yield* DateTime.setZoneCurrent(now)
  * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export const setZoneCurrent = self => Effect.map(CurrentTimeZone, zone => setZone(self, zone));
 /**
  * Provide the `CurrentTimeZone` to an effect.
  *
- * @since 3.6.0
- * @category current time zone
- * @example
+ * **Example** (Providing the current time zone)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -1123,15 +1222,17 @@ export const setZoneCurrent = self => Effect.map(CurrentTimeZone, zone => setZon
  *   const now = yield* DateTime.nowInCurrentZone
  * }).pipe(DateTime.withCurrentZone(zone))
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export const withCurrentZone = /*#__PURE__*/provideService(CurrentTimeZone);
 /**
  * Provide the `CurrentTimeZone` to an effect, using the system's local time
  * zone.
  *
- * @since 3.6.0
- * @category current time zone
- * @example
+ * **Example** (Providing the local time zone)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -1140,22 +1241,27 @@ export const withCurrentZone = /*#__PURE__*/provideService(CurrentTimeZone);
  *   const now = yield* DateTime.nowInCurrentZone
  * }).pipe(DateTime.withCurrentZoneLocal)
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export const withCurrentZoneLocal = effect => Effect.provideServiceEffect(effect, CurrentTimeZone, Effect.sync(zoneMakeLocal));
 /**
  * Provide the `CurrentTimeZone` to an effect, using a offset.
  *
- * @since 3.6.0
- * @category current time zone
- * @example
+ * **Example** (Providing a fixed-offset time zone)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
  * Effect.gen(function*() {
- *   // will use the system's local time zone
- *   const now = yield* DateTime.nowInCurrentZone
+ *   const zone = yield* DateTime.CurrentTimeZone
+ *   console.log(DateTime.zoneToString(zone)) // "+03:00"
  * }).pipe(DateTime.withCurrentZoneOffset(3 * 60 * 60 * 1000))
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export const withCurrentZoneOffset = /*#__PURE__*/dual(2, (effect, offset) => Effect.provideService(effect, CurrentTimeZone, zoneMakeOffset(offset)));
 /**
@@ -1164,9 +1270,8 @@ export const withCurrentZoneOffset = /*#__PURE__*/dual(2, (effect, offset) => Ef
  *
  * If the time zone is invalid, it will fail with an `IllegalArgumentError`.
  *
- * @since 3.6.0
- * @category current time zone
- * @example
+ * **Example** (Providing a named time zone)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -1175,14 +1280,16 @@ export const withCurrentZoneOffset = /*#__PURE__*/dual(2, (effect, offset) => Ef
  *   const now = yield* DateTime.nowInCurrentZone
  * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export const withCurrentZoneNamed = /*#__PURE__*/dual(2, (effect, zone) => Effect.provideServiceEffect(effect, CurrentTimeZone, zoneMakeNamedEffect(zone)));
 /**
  * Get the current time as a `DateTime.Zoned`, using the `CurrentTimeZone`.
  *
- * @since 3.6.0
- * @category current time zone
- * @example
+ * **Example** (Getting the current time in the current zone)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -1191,6 +1298,9 @@ export const withCurrentZoneNamed = /*#__PURE__*/dual(2, (effect, zone) => Effec
  *   const now = yield* DateTime.nowInCurrentZone
  * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export const nowInCurrentZone = /*#__PURE__*/Effect.flatMap(now, setZoneCurrent);
 // =============================================================================
@@ -1204,7 +1314,8 @@ export const nowInCurrentZone = /*#__PURE__*/Effect.flatMap(now, setZoneCurrent)
  *
  * Supports `disambiguation` when the new wall clock time is ambiguous.
  *
- * @example
+ * **Example** (Mutating DateTime values with Dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1218,14 +1329,15 @@ export const nowInCurrentZone = /*#__PURE__*/Effect.flatMap(now, setZoneCurrent)
  * console.log(DateTime.formatIso(modified)) // "2024-01-01T15:30:00.000Z"
  * ```
  *
- * @since 3.6.0
  * @category mapping
+ * @since 3.6.0
  */
 export const mutate = Internal.mutate;
 /**
  * Modify a `DateTime` by applying a function to a cloned UTC `Date` instance.
  *
- * @example
+ * **Example** (Mutating DateTime values with UTC Dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1240,17 +1352,16 @@ export const mutate = Internal.mutate;
  * console.log(DateTime.formatIso(modified)) // "2024-01-01T18:00:00.000Z"
  * ```
  *
- * @since 3.6.0
  * @category mapping
+ * @since 3.6.0
  */
 export const mutateUtc = Internal.mutateUtc;
 /**
  * Transform a `DateTime` by applying a function to the number of milliseconds
  * since the Unix epoch.
  *
- * @since 3.6.0
- * @category mapping
- * @example
+ * **Example** (Mapping epoch milliseconds)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1259,15 +1370,20 @@ export const mutateUtc = Internal.mutateUtc;
  *   DateTime.mapEpochMillis((millis) => millis + 10)
  * )
  * ```
+ *
+ * @category mapping
+ * @since 3.6.0
  */
 export const mapEpochMillis = Internal.mapEpochMillis;
 /**
- * Using the time zone adjusted `Date`, apply a function to the `Date` and
- * return the result.
+ * Applies a function to a JavaScript `Date` representing the `DateTime`'s UTC
+ * instant and returns the function's result.
+ *
+ * This ignores any associated time zone. Use `DateTime.withDate` when the
+ * callback should receive the time-zone-adjusted wall-clock date.
+ *
+ * **Example** (Using time zone adjusted Dates)
  *
- * @since 3.6.0
- * @category mapping
- * @example
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1276,15 +1392,20 @@ export const mapEpochMillis = Internal.mapEpochMillis;
  *   DateTime.withDate((date) => date.getTime())
  * )
  * ```
+ *
+ * @category mapping
+ * @since 3.6.0
  */
 export const withDate = Internal.withDate;
 /**
- * Using the time zone adjusted `Date`, apply a function to the `Date` and
- * return the result.
+ * Applies a function to a JavaScript `Date` representing the `DateTime`'s UTC
+ * instant and returns the function's result.
+ *
+ * This ignores any associated time zone. Use `DateTime.withDate` when the
+ * callback should receive the time-zone-adjusted wall-clock date.
+ *
+ * **Example** (Using UTC Dates)
  *
- * @since 3.6.0
- * @category mapping
- * @example
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1293,17 +1414,23 @@ export const withDate = Internal.withDate;
  *   DateTime.withDateUtc((date) => date.getTime())
  * )
  * ```
+ *
+ * @category mapping
+ * @since 3.6.0
  */
 export const withDateUtc = Internal.withDateUtc;
 /**
  * Pattern match on a `DateTime` to handle `Utc` and `Zoned` cases differently.
  *
- * @example
+ * **Example** (Pattern matching DateTime variants)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
- * const dt1 = DateTime.nowUnsafe() // Utc
- * const dt2 = DateTime.makeZonedUnsafe(new Date(), { timeZone: "Europe/London" }) // Zoned
+ * const dt1 = DateTime.makeUnsafe("2024-01-01T12:00:00Z") // Utc
+ * const dt2 = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
+ *   timeZone: "Europe/London"
+ * }) // Zoned
  *
  * const result1 = DateTime.match(dt1, {
  *   onUtc: (utc) => `UTC: ${DateTime.formatIso(utc)}`,
@@ -1314,6 +1441,9 @@ export const withDateUtc = Internal.withDateUtc;
  *   onUtc: (utc) => `UTC: ${DateTime.formatIso(utc)}`,
  *   onZoned: (zoned) => `Zoned: ${DateTime.formatIsoZoned(zoned)}`
  * })
+ *
+ * console.log(result1) // "UTC: 2024-01-01T12:00:00.000Z"
+ * console.log(result2) // "Zoned: 2024-06-15T15:30:00.000+01:00[Europe/London]"
  * ```
  *
  * @category mapping
@@ -1326,9 +1456,8 @@ export const match = Internal.match;
 /**
  * Add the given `Duration` to a `DateTime`.
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Adding durations)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1337,14 +1466,16 @@ export const match = Internal.match;
  *   DateTime.addDuration("5 minutes")
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export const addDuration = Internal.addDuration;
 /**
  * Subtract the given `Duration` from a `DateTime`.
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Subtracting durations)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1353,6 +1484,9 @@ export const addDuration = Internal.addDuration;
  *   DateTime.subtractDuration("5 minutes")
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export const subtractDuration = Internal.subtractDuration;
 /**
@@ -1361,9 +1495,8 @@ export const subtractDuration = Internal.subtractDuration;
  * The time zone is taken into account when adding days, weeks, months, and
  * years.
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Adding date and time parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1372,14 +1505,16 @@ export const subtractDuration = Internal.subtractDuration;
  *   DateTime.add({ minutes: 5 })
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export const add = Internal.add;
 /**
  * Subtract the given `amount` of `unit`'s from a `DateTime`.
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Subtracting date and time parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1388,6 +1523,9 @@ export const add = Internal.add;
  *   DateTime.subtract({ minutes: 5 })
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export const subtract = Internal.subtract;
 /**
@@ -1396,9 +1534,8 @@ export const subtract = Internal.subtract;
  * If the part is `week`, the `weekStartsOn` option can be used to specify the
  * day of the week that the week starts on. The default is 0 (Sunday).
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Rounding down DateTime values)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1408,6 +1545,9 @@ export const subtract = Internal.subtract;
  *   DateTime.formatIso
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export const startOf = Internal.startOf;
 /**
@@ -1416,9 +1556,8 @@ export const startOf = Internal.startOf;
  * If the part is `week`, the `weekStartsOn` option can be used to specify the
  * day of the week that the week starts on. The default is 0 (Sunday).
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Rounding up DateTime values)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1428,6 +1567,9 @@ export const startOf = Internal.startOf;
  *   DateTime.formatIso
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export const endOf = Internal.endOf;
 /**
@@ -1436,9 +1578,8 @@ export const endOf = Internal.endOf;
  * If the part is `week`, the `weekStartsOn` option can be used to specify the
  * day of the week that the week starts on. The default is 0 (Sunday).
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Rounding DateTime values to nearest units)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1448,20 +1589,26 @@ export const endOf = Internal.endOf;
  *   DateTime.formatIso
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export const nearest = Internal.nearest;
 // =============================================================================
 // formatting
 // =============================================================================
 /**
- * Format a `DateTime` as a string using the `DateTimeFormat` API.
+ * Formats a `DateTime` with `Intl.DateTimeFormat`.
+ *
+ * Unless a `timeZone` option is supplied, UTC values are formatted in UTC and
+ * zoned values are formatted in their named zone or fixed-offset zone.
  *
- * The `timeZone` option is set to the offset of the time zone.
+ * Fixed-offset zones depend on runtime support for offset `timeZone`
+ * identifiers. When unsupported, formatting falls back to UTC with the
+ * `DateTime` adjusted to the offset.
  *
- * Note: On Node versions < 22, fixed "Offset" zones will set the time zone to
- * "UTC" and use the adjusted `Date`.
+ * **Example** (Formatting DateTime values with Intl options)
  *
- * @example
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1478,8 +1625,8 @@ export const nearest = Internal.nearest;
  * console.log(formatted) // "Saturday, June 15, 2024 at 3:30 PM"
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export const format = Internal.format;
 /**
@@ -1487,7 +1634,8 @@ export const format = Internal.format;
  *
  * It will use the system's local time zone & locale.
  *
- * @example
+ * **Example** (Formatting DateTime values locally)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1505,8 +1653,8 @@ export const format = Internal.format;
  * console.log(local) // Output depends on system locale/timezone
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export const formatLocal = Internal.formatLocal;
 /**
@@ -1514,7 +1662,8 @@ export const formatLocal = Internal.formatLocal;
  *
  * This forces the time zone to be UTC.
  *
- * @example
+ * **Example** (Formatting DateTime values in UTC)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1535,14 +1684,15 @@ export const formatLocal = Internal.formatLocal;
  * console.log(utcFormatted) // "06/15/2024, 02:30 PM UTC"
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export const formatUtc = Internal.formatUtc;
 /**
  * Format a `DateTime` as a string using the `DateTimeFormat` API.
  *
- * @example
+ * **Example** (Formatting DateTime values with custom formatters)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1562,8 +1712,8 @@ export const formatUtc = Internal.formatUtc;
  * console.log(formatted) // "15. Juni 2024, 16:30"
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export const formatIntl = Internal.formatIntl;
 /**
@@ -1571,7 +1721,8 @@ export const formatIntl = Internal.formatIntl;
  *
  * Always returns the UTC representation in ISO 8601 format, ignoring any time zone.
  *
- * @example
+ * **Example** (Formatting DateTime values as ISO strings)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1593,7 +1744,8 @@ export const formatIso = Internal.formatIso;
  *
  * Returns only the date part (YYYY-MM-DD) after applying time zone adjustments.
  *
- * @example
+ * **Example** (Formatting DateTime values as ISO dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1615,7 +1767,8 @@ export const formatIsoDate = Internal.formatIsoDate;
  *
  * Returns only the date part (YYYY-MM-DD) in UTC, ignoring any time zone.
  *
- * @example
+ * **Example** (Formatting DateTime values as UTC ISO dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1638,7 +1791,8 @@ export const formatIsoDateUtc = Internal.formatIsoDateUtc;
  * For `DateTime.Utc`, returns the same as `formatIso`. For `DateTime.Zoned`,
  * includes the time zone offset in the format.
  *
- * @example
+ * **Example** (Formatting DateTime values with offsets)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1660,7 +1814,8 @@ export const formatIsoOffset = Internal.formatIsoOffset;
  *
  * It uses the format: `YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]`.
  *
- * @example
+ * **Example** (Formatting zoned DateTime values)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1679,8 +1834,8 @@ export const formatIsoOffset = Internal.formatIsoOffset;
  * console.log(offsetFormatted) // "2024-06-15T17:30:45.123+03:00"
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export const formatIsoZoned = Internal.formatIsoZoned;
 /**
@@ -1688,7 +1843,8 @@ export const formatIsoZoned = Internal.formatIsoZoned;
  *
  * This layer provides the `CurrentTimeZone` service with the specified time zone.
  *
- * @example
+ * **Example** (Providing current time zone layers)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -1713,7 +1869,8 @@ export const layerCurrentZone = /*#__PURE__*/Layer.succeed(CurrentTimeZone);
  *
  * This layer provides the `CurrentTimeZone` service with a fixed offset time zone.
  *
- * @example
+ * **Example** (Providing fixed-offset time zone layers)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -1738,7 +1895,8 @@ export const layerCurrentZoneOffset = offset => Layer.succeed(CurrentTimeZone)(I
  * This layer provides the `CurrentTimeZone` service with a named time zone.
  * If the time zone identifier is invalid, the layer will fail.
  *
- * @example
+ * **Example** (Providing named time zone layers)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -1762,7 +1920,8 @@ export const layerCurrentZoneNamed = /*#__PURE__*/flow(Internal.zoneMakeNamedEff
  * This layer provides the `CurrentTimeZone` service using the system's
  * configured local time zone.
  *
- * @example
+ * **Example** (Providing local time zone layers)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *