effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/DateTime.ts

@@ -80,6 +80,8 @@ export type DateTime = Utc | Zoned
  * Represents a `DateTime` stored as an absolute UTC instant with no associated
  * time zone.
  *
+ * **Details**
+ *
  * Use `DateTime.isUtc` to narrow a `DateTime` to this variant.
  *
  * @category models
@@ -94,6 +96,8 @@ export interface Utc extends DateTime.Proto {
 /**
  * Represents a `DateTime` with an associated `TimeZone`.
  *
+ * **Details**
+ *
  * A zoned value still represents an absolute instant through
  * `epochMilliseconds`, while the time zone is used for wall-clock parts,
  * formatting, and zone-aware transformations.
@@ -121,6 +125,8 @@ export declare namespace DateTime {
    * Input accepted by `DateTime.make`, `DateTime.makeUnsafe`, and the zoned
    * constructors.
    *
+   * **Details**
+   *
    * Includes existing `DateTime` values, partial date parts, epoch-millisecond
    * objects, epoch milliseconds, JavaScript `Date` instances, and parseable date
    * strings.
@@ -133,6 +139,8 @@ export declare namespace DateTime {
   /**
    * Type-level helper used by constructors to preserve a zoned input.
    *
+   * **Details**
+   *
    * When the input type is `DateTime.Zoned`, the result type is
    * `DateTime.Zoned`; otherwise the result type is `DateTime.Utc`.
    *
@@ -145,6 +153,8 @@ export declare namespace DateTime {
    * Date and time unit name accepted by `DateTime` rounding and arithmetic
    * APIs.
    *
+   * **Details**
+   *
    * Includes both singular units, such as `"day"`, and plural units, such as
    * `"days"`.
    *
@@ -190,6 +200,8 @@ export declare namespace DateTime {
   /**
    * Calendar and time components of a `DateTime`, including the weekday.
    *
+   * **Details**
+   *
    * `month` is one-based (`1` for January through `12` for December), and
    * `weekDay` follows JavaScript `Date#getUTCDay` numbering (`0` for Sunday
    * through `6` for Saturday).
@@ -211,6 +223,8 @@ export declare namespace DateTime {
   /**
    * Calendar and time components of a `DateTime`, without weekday information.
    *
+   * **Details**
+   *
    * `month` is one-based (`1` for January through `12` for December).
    *
    * @category models
@@ -229,6 +243,8 @@ export declare namespace DateTime {
   /**
    * Plural amount fields accepted by `DateTime.add` and `DateTime.subtract`.
    *
+   * **Details**
+   *
    * Each field represents the number of units to add or subtract for that part.
    *
    * @category models
@@ -259,6 +275,8 @@ export declare namespace DateTime {
   /**
    * Object input representing an absolute instant plus a time zone identifier.
    *
+   * **Details**
+   *
    * `DateTime.makeZoned` and `DateTime.makeZonedUnsafe` use `timeZoneId` when
    * no explicit `timeZone` option is supplied.
    *
@@ -273,6 +291,8 @@ export declare namespace DateTime {
   /**
    * Shared protocol implemented by all `DateTime` values.
    *
+   * **Details**
+   *
    * Provides the `DateTime` type identifier along with pipe and inspection
    * support.
    *
@@ -287,6 +307,8 @@ export declare namespace DateTime {
 /**
  * Represents a time zone used by `DateTime.Zoned`.
  *
+ * **Details**
+ *
  * A `TimeZone` is either a fixed offset from UTC or a named IANA time zone.
  *
  * @category models
@@ -304,6 +326,8 @@ export declare namespace TimeZone {
   /**
    * Shared protocol implemented by all `TimeZone` values.
    *
+   * **Details**
+   *
    * Provides the `TimeZone` type identifier and inspection support.
    *
    * @category models
@@ -316,6 +340,8 @@ export declare namespace TimeZone {
   /**
    * Fixed-offset time zone.
    *
+   * **Details**
+   *
    * The `offset` is measured in milliseconds from UTC. Positive offsets are
    * ahead of UTC, and negative offsets are behind UTC.
    *
@@ -330,6 +356,8 @@ export declare namespace TimeZone {
   /**
    * Named IANA time zone.
    *
+   * **Details**
+   *
    * The `id` field contains the resolved time zone identifier, such as
    * `"Europe/London"` or `"America/New_York"`.
    *
@@ -348,6 +376,8 @@ export declare namespace TimeZone {
  * A `Disambiguation` is used to resolve ambiguities when a `DateTime` is
  * ambiguous, such as during a daylight saving time transition.
  *
+ * **Details**
+ *
  * For more information, see the [Temporal documentation](https://tc39.es/proposal-temporal/docs/timezone.html#ambiguity-due-to-dst-or-other-time-zone-offset-changes)
  *
  * - `"compatible"`: (default) Behavior matching Temporal API and legacy JavaScript Date and moment.js.
@@ -466,6 +496,8 @@ export const isZoned: (self: DateTime) => self is Zoned = Internal.isZoned
 /**
  * An `Equivalence` for comparing two `DateTime` values for equality.
  *
+ * **Details**
+ *
  * Two `DateTime` values are considered equivalent if they represent the same
  * point in time, regardless of their time zone.
  *
@@ -490,6 +522,8 @@ export const Equivalence: Equ.Equivalence<DateTime> = Internal.Equivalence
 /**
  * An `Order` for comparing and sorting `DateTime` values.
  *
+ * **Details**
+ *
  * `DateTime` values are ordered by their epoch milliseconds, so earlier times
  * come before later times regardless of time zone.
  *
@@ -516,6 +550,8 @@ export const Order: order.Order<DateTime> = Internal.Order
 /**
  * Clamp a `DateTime` between a minimum and maximum value.
  *
+ * **Details**
+ *
  * If the `DateTime` is before the minimum, the minimum is returned.
  * If the `DateTime` is after the maximum, the maximum is returned.
  * Otherwise, the original `DateTime` is returned.
@@ -540,6 +576,8 @@ export const clamp: {
   /**
    * Clamp a `DateTime` between a minimum and maximum value.
    *
+   * **Details**
+   *
    * If the `DateTime` is before the minimum, the minimum is returned.
    * If the `DateTime` is after the maximum, the maximum is returned.
    * Otherwise, the original `DateTime` is returned.
@@ -564,6 +602,8 @@ export const clamp: {
   /**
    * Clamp a `DateTime` between a minimum and maximum value.
    *
+   * **Details**
+   *
    * If the `DateTime` is before the minimum, the minimum is returned.
    * If the `DateTime` is after the maximum, the maximum is returned.
    * Otherwise, the original `DateTime` is returned.
@@ -594,6 +634,8 @@ export const clamp: {
 /**
  * Create a `DateTime` from a `Date`.
  *
+ * **Details**
+ *
  * If the `Date` is invalid, an `IllegalArgumentError` will be thrown.
  *
  * **Example** (Creating DateTime values from Dates)
@@ -613,7 +655,9 @@ export const clamp: {
 export const fromDateUnsafe: (date: Date) => Utc = Internal.fromDateUnsafe
 
 /**
- * Create a `DateTime` from one of the following:
+ * Create a `DateTime` from supported input values.
+ *
+ * **Details**
  *
  * - A `DateTime`
  * - A `Date` instance (invalid dates will throw an `IllegalArgumentError`)
@@ -647,6 +691,8 @@ export const makeUnsafe: <A extends DateTime.Input>(input: A) => DateTime.Preser
 /**
  * Create a `DateTime.Zoned` using `DateTime.makeUnsafe` and a time zone.
  *
+ * **Details**
+ *
  * 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.
@@ -682,6 +728,8 @@ export const makeZonedUnsafe: (input: DateTime.Input, options?: {
 /**
  * Creates a `DateTime.Zoned` from an input and a time zone.
  *
+ * **Details**
+ *
  * 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.
@@ -726,7 +774,9 @@ export const makeZoned: (
 ) => Option.Option<Zoned> = Internal.makeZoned
 
 /**
- * Creates a `DateTime` from one of the following:
+ * Creates a `DateTime` from supported input values.
+ *
+ * **Details**
  *
  * - A `DateTime`
  * - A JavaScript `Date`
@@ -767,6 +817,8 @@ export const make: <A extends DateTime.Input>(input: A) => Option.Option<DateTim
 /**
  * Parses an ISO zoned date-time string into a `DateTime.Zoned`.
  *
+ * **Details**
+ *
  * 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
@@ -835,6 +887,8 @@ export const nowAsDate: Effect.Effect<Date> = Internal.nowAsDate
 /**
  * Get the current time using `Date.now`.
  *
+ * **Details**
+ *
  * This is a synchronous version of `now` that directly uses `Date.now()`
  * instead of the Effect `Clock` service.
  *
@@ -958,6 +1012,8 @@ export const setZone: {
 /**
  * Add a fixed offset time zone to a `DateTime`.
  *
+ * **Details**
+ *
  * The offset is in milliseconds.
  *
  * **Example** (Setting fixed-offset time zones)
@@ -980,6 +1036,8 @@ export const setZoneOffset: {
   /**
    * Add a fixed offset time zone to a `DateTime`.
    *
+   * **Details**
+   *
    * The offset is in milliseconds.
    *
    * **Example** (Setting fixed-offset time zones)
@@ -1008,6 +1066,8 @@ export const setZoneOffset: {
   /**
    * Add a fixed offset time zone to a `DateTime`.
    *
+   * **Details**
+   *
    * The offset is in milliseconds.
    *
    * **Example** (Setting fixed-offset time zones)
@@ -1039,6 +1099,8 @@ export const setZoneOffset: {
 /**
  * Attempt to create a named time zone from a IANA time zone identifier.
  *
+ * **Details**
+ *
  * If the time zone is invalid, an `IllegalArgumentError` will be thrown.
  *
  * **Example** (Creating named time zones unsafely)
@@ -1064,6 +1126,8 @@ export const zoneMakeNamedUnsafe: (zoneId: string) => TimeZone.Named = Internal.
 /**
  * Create a fixed offset time zone.
  *
+ * **Details**
+ *
  * The offset is specified in milliseconds from UTC. Positive values are
  * ahead of UTC, negative values are behind UTC.
  *
@@ -1088,6 +1152,8 @@ export const zoneMakeOffset: (offset: number) => TimeZone.Offset = Internal.zone
 /**
  * Create a named time zone from a IANA time zone identifier.
  *
+ * **Details**
+ *
  * If the time zone is invalid, `None` will be returned.
  *
  * **Example** (Creating optional named time zones)
@@ -1110,6 +1176,8 @@ export const zoneMakeNamed: (zoneId: string) => Option.Option<TimeZone.Named> =
 /**
  * Create a named time zone from a IANA time zone identifier.
  *
+ * **Details**
+ *
  * If the time zone is invalid, it will fail with an `IllegalArgumentError`.
  *
  * **Example** (Creating named time zones effectfully)
@@ -1133,6 +1201,8 @@ export const zoneMakeNamedEffect: (zoneId: string) => Effect.Effect<TimeZone.Nam
 /**
  * Create a named time zone from the system's local time zone.
  *
+ * **Details**
+ *
  * This uses the system's configured time zone, which may vary depending
  * on the runtime environment.
  *
@@ -1153,6 +1223,8 @@ export const zoneMakeLocal: () => TimeZone.Named = Internal.zoneMakeLocal
 /**
  * Try to parse a `TimeZone` from a string.
  *
+ * **Details**
+ *
  * Supports both IANA time zone identifiers and offset formats like "+03:00".
  *
  * **Example** (Parsing time zones)
@@ -1352,6 +1424,8 @@ export const setZoneNamedUnsafe: {
  * Calulate the difference between two `DateTime` values, returning a
  * `Duration` representing the amount of time between them.
  *
+ * **Details**
+ *
  * If `other` is *after* `self`, the result will be a positive `Duration`. If
  * `other` is *before* `self`, the result will be a negative `Duration`. If they
  * are equal, the result will be a `Duration` of zero.
@@ -1382,6 +1456,8 @@ export const distance: {
    * Calulate the difference between two `DateTime` values, returning a
    * `Duration` representing the amount of time between them.
    *
+   * **Details**
+   *
    * If `other` is *after* `self`, the result will be a positive `Duration`. If
    * `other` is *before* `self`, the result will be a negative `Duration`. If they
    * are equal, the result will be a `Duration` of zero.
@@ -1412,6 +1488,8 @@ export const distance: {
    * Calulate the difference between two `DateTime` values, returning a
    * `Duration` representing the amount of time between them.
    *
+   * **Details**
+   *
    * If `other` is *after* `self`, the result will be a positive `Duration`. If
    * `other` is *before* `self`, the result will be a negative `Duration`. If they
    * are equal, the result will be a `Duration` of zero.
@@ -1864,6 +1942,8 @@ export const between: {
 /**
  * Checks if a `DateTime` is in the future compared to the current time.
  *
+ * **Details**
+ *
  * This is an effectful operation that uses the current time from the `Clock` service.
  *
  * **Example** (Checking future DateTime values effectfully)
@@ -1886,6 +1966,8 @@ export const isFuture: (self: DateTime) => Effect.Effect<boolean> = Internal.isF
 /**
  * Checks if a `DateTime` is in the future compared to the current time.
  *
+ * **Details**
+ *
  * This is a synchronous version that uses `Date.now()` directly.
  *
  * **Example** (Checking future DateTime values unsafely)
@@ -1908,6 +1990,8 @@ export const isFutureUnsafe: (self: DateTime) => boolean = Internal.isFutureUnsa
 /**
  * Checks if a `DateTime` is in the past compared to the current time.
  *
+ * **Details**
+ *
  * This is an effectful operation that uses the current time from the `Clock` service.
  *
  * **Example** (Checking past DateTime values effectfully)
@@ -1930,6 +2014,8 @@ export const isPast: (self: DateTime) => Effect.Effect<boolean> = Internal.isPas
 /**
  * Checks if a `DateTime` is in the past compared to the current time.
  *
+ * **Details**
+ *
  * This is a synchronous version that uses `Date.now()` directly.
  *
  * **Example** (Checking past DateTime values unsafely)
@@ -1956,6 +2042,8 @@ export const isPastUnsafe: (self: DateTime) => boolean = Internal.isPastUnsafe
 /**
  * Get the UTC `Date` of a `DateTime`.
  *
+ * **Details**
+ *
  * This always returns the UTC representation, ignoring any time zone information.
  *
  * **Example** (Converting DateTime values to UTC Dates)
@@ -1979,6 +2067,8 @@ export const toDateUtc: (self: DateTime) => Date = Internal.toDateUtc
 /**
  * Convert a `DateTime` to a `Date`, applying the time zone first.
  *
+ * **Details**
+ *
  * For `DateTime.Zoned`, this adjusts for the time zone before converting.
  * For `DateTime.Utc`, this is equivalent to `toDateUtc`.
  *
@@ -2004,6 +2094,8 @@ export const toDate: (self: DateTime) => Date = Internal.toDate
 /**
  * Calculate the time zone offset of a `DateTime.Zoned` in milliseconds.
  *
+ * **Details**
+ *
  * Returns the offset from UTC in milliseconds. Positive values indicate
  * time zones ahead of UTC, negative values indicate time zones behind UTC.
  *
@@ -2028,6 +2120,8 @@ export const zonedOffset: (self: Zoned) => number = Internal.zonedOffset
 /**
  * Format the time zone offset of a `DateTime.Zoned` as an ISO string.
  *
+ * **Details**
+ *
  * The offset is formatted as "±HH:MM".
  *
  * **Example** (Formatting zoned offsets)
@@ -2051,6 +2145,8 @@ export const zonedOffsetIso: (self: Zoned) => string = Internal.zonedOffsetIso
 /**
  * Get the milliseconds since the Unix epoch of a `DateTime`.
  *
+ * **Details**
+ *
  * This returns the UTC timestamp regardless of any time zone information.
  *
  * **Example** (Reading epoch milliseconds)
@@ -2100,6 +2196,8 @@ export const removeTime: (self: DateTime) => Utc = Internal.removeTime
 /**
  * Get the different parts of a `DateTime` as an object.
  *
+ * **Details**
+ *
  * The parts will be time zone adjusted if the `DateTime` is zoned.
  *
  * **Example** (Reading DateTime parts)
@@ -2131,6 +2229,8 @@ export const toParts: (self: DateTime) => DateTime.PartsWithWeekday = Internal.t
 /**
  * Get the different parts of a `DateTime` as an object.
  *
+ * **Details**
+ *
  * The parts will always be in UTC, ignoring any time zone information.
  *
  * **Example** (Reading UTC DateTime parts)
@@ -2155,6 +2255,8 @@ export const toPartsUtc: (self: DateTime) => DateTime.PartsWithWeekday = Interna
 /**
  * Get a part of a `DateTime` as a number.
  *
+ * **Details**
+ *
  * The part will be in the UTC time zone.
  *
  * **Example** (Reading UTC DateTime parts by key)
@@ -2174,6 +2276,8 @@ export const getPartUtc: {
   /**
    * Get a part of a `DateTime` as a number.
    *
+   * **Details**
+   *
    * The part will be in the UTC time zone.
    *
    * **Example** (Reading UTC DateTime parts by key)
@@ -2193,6 +2297,8 @@ export const getPartUtc: {
   /**
    * Get a part of a `DateTime` as a number.
    *
+   * **Details**
+   *
    * The part will be in the UTC time zone.
    *
    * **Example** (Reading UTC DateTime parts by key)
@@ -2214,6 +2320,8 @@ export const getPartUtc: {
 /**
  * Get a part of a `DateTime` as a number.
  *
+ * **Details**
+ *
  * The part will be time zone adjusted.
  *
  * **Example** (Reading DateTime parts by key)
@@ -2235,6 +2343,8 @@ export const getPart: {
   /**
    * Get a part of a `DateTime` as a number.
    *
+   * **Details**
+   *
    * The part will be time zone adjusted.
    *
    * **Example** (Reading DateTime parts by key)
@@ -2256,6 +2366,8 @@ export const getPart: {
   /**
    * Get a part of a `DateTime` as a number.
    *
+   * **Details**
+   *
    * The part will be time zone adjusted.
    *
    * **Example** (Reading DateTime parts by key)
@@ -2279,6 +2391,8 @@ export const getPart: {
 /**
  * Set the different parts of a `DateTime` as an object.
  *
+ * **Details**
+ *
  * The date will be time zone adjusted for `DateTime.Zoned`.
  *
  * **Example** (Updating DateTime parts)
@@ -2303,6 +2417,8 @@ export const setParts: {
   /**
    * Set the different parts of a `DateTime` as an object.
    *
+   * **Details**
+   *
    * The date will be time zone adjusted for `DateTime.Zoned`.
    *
    * **Example** (Updating DateTime parts)
@@ -2327,6 +2443,8 @@ export const setParts: {
   /**
    * Set the different parts of a `DateTime` as an object.
    *
+   * **Details**
+   *
    * The date will be time zone adjusted for `DateTime.Zoned`.
    *
    * **Example** (Updating DateTime parts)
@@ -2353,6 +2471,8 @@ export const setParts: {
 /**
  * Set the different parts of a `DateTime` as an object.
  *
+ * **Details**
+ *
  * The parts are always interpreted as UTC, ignoring any time zone information.
  *
  * **Example** (Updating UTC DateTime parts)
@@ -2376,6 +2496,8 @@ export const setPartsUtc: {
   /**
    * Set the different parts of a `DateTime` as an object.
    *
+   * **Details**
+   *
    * The parts are always interpreted as UTC, ignoring any time zone information.
    *
    * **Example** (Updating UTC DateTime parts)
@@ -2399,6 +2521,8 @@ export const setPartsUtc: {
   /**
    * Set the different parts of a `DateTime` as an object.
    *
+   * **Details**
+   *
    * The parts are always interpreted as UTC, ignoring any time zone information.
    *
    * **Example** (Updating UTC DateTime parts)
@@ -2430,6 +2554,8 @@ export const setPartsUtc: {
  * the current zone, such as `DateTime.setZoneCurrent` and
  * `DateTime.nowInCurrentZone`.
  *
+ * **Details**
+ *
  * Provide it with `DateTime.withCurrentZone`, one of the `withCurrentZone*`
  * helpers, or one of the `layerCurrentZone*` layers.
  *
@@ -2627,6 +2753,8 @@ export const withCurrentZoneOffset: {
  * Provide the `CurrentTimeZone` to an effect using an IANA time zone
  * identifier.
  *
+ * **Details**
+ *
  * If the time zone is invalid, it will fail with an `IllegalArgumentError`.
  *
  * **Example** (Providing a named time zone)
@@ -2648,6 +2776,8 @@ export const withCurrentZoneNamed: {
    * Provide the `CurrentTimeZone` to an effect using an IANA time zone
    * identifier.
    *
+   * **Details**
+   *
    * If the time zone is invalid, it will fail with an `IllegalArgumentError`.
    *
    * **Example** (Providing a named time zone)
@@ -2671,6 +2801,8 @@ export const withCurrentZoneNamed: {
    * Provide the `CurrentTimeZone` to an effect using an IANA time zone
    * identifier.
    *
+   * **Details**
+   *
    * If the time zone is invalid, it will fail with an `IllegalArgumentError`.
    *
    * **Example** (Providing a named time zone)
@@ -2723,6 +2855,8 @@ export const nowInCurrentZone: Effect.Effect<Zoned, never, CurrentTimeZone> = Ef
 /**
  * Modify a `DateTime` by applying a function to a cloned `Date` instance.
  *
+ * **Details**
+ *
  * The `Date` will first have the time zone applied if possible, and then be
  * converted back to a `DateTime` within the same time zone.
  *
@@ -2754,6 +2888,8 @@ export const mutate: {
   /**
    * Modify a `DateTime` by applying a function to a cloned `Date` instance.
    *
+   * **Details**
+   *
    * The `Date` will first have the time zone applied if possible, and then be
    * converted back to a `DateTime` within the same time zone.
    *
@@ -2790,6 +2926,8 @@ export const mutate: {
   /**
    * Modify a `DateTime` by applying a function to a cloned `Date` instance.
    *
+   * **Details**
+   *
    * The `Date` will first have the time zone applied if possible, and then be
    * converted back to a `DateTime` within the same time zone.
    *
@@ -2953,11 +3091,14 @@ export const mapEpochMillis: {
 } = Internal.mapEpochMillis
 
 /**
- * Applies a function to a JavaScript `Date` representing the `DateTime`'s UTC
- * instant and returns the function's result.
+ * Applies a function to a JavaScript `Date` representing the `DateTime` 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.
+ * **Details**
+ *
+ * The callback receives the time-zone-adjusted wall-clock date for
+ * `DateTime.Zoned` values. Use `DateTime.withDateUtc` when the callback should
+ * receive the UTC instant.
  *
  * **Example** (Using time zone adjusted Dates)
  *
@@ -2975,11 +3116,14 @@ export const mapEpochMillis: {
  */
 export const withDate: {
   /**
-   * Applies a function to a JavaScript `Date` representing the `DateTime`'s UTC
-   * instant and returns the function's result.
+   * Applies a function to a JavaScript `Date` representing the `DateTime` 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.
+   * **Details**
+   *
+   * The callback receives the time-zone-adjusted wall-clock date for
+   * `DateTime.Zoned` values. Use `DateTime.withDateUtc` when the callback should
+   * receive the UTC instant.
    *
    * **Example** (Using time zone adjusted Dates)
    *
@@ -2997,11 +3141,14 @@ export const withDate: {
    */
   <A>(f: (date: Date) => A): (self: DateTime) => A
   /**
-   * Applies a function to a JavaScript `Date` representing the `DateTime`'s UTC
-   * instant and returns the function's result.
+   * Applies a function to a JavaScript `Date` representing the `DateTime` 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.
+   * **Details**
+   *
+   * The callback receives the time-zone-adjusted wall-clock date for
+   * `DateTime.Zoned` values. Use `DateTime.withDateUtc` when the callback should
+   * receive the UTC instant.
    *
    * **Example** (Using time zone adjusted Dates)
    *
@@ -3024,6 +3171,8 @@ export const withDate: {
  * Applies a function to a JavaScript `Date` representing the `DateTime`'s UTC
  * instant and returns the function's result.
  *
+ * **Details**
+ *
  * This ignores any associated time zone. Use `DateTime.withDate` when the
  * callback should receive the time-zone-adjusted wall-clock date.
  *
@@ -3046,6 +3195,8 @@ export const withDateUtc: {
    * Applies a function to a JavaScript `Date` representing the `DateTime`'s UTC
    * instant and returns the function's result.
    *
+   * **Details**
+   *
    * This ignores any associated time zone. Use `DateTime.withDate` when the
    * callback should receive the time-zone-adjusted wall-clock date.
    *
@@ -3068,6 +3219,8 @@ export const withDateUtc: {
    * Applies a function to a JavaScript `Date` representing the `DateTime`'s UTC
    * instant and returns the function's result.
    *
+   * **Details**
+   *
    * This ignores any associated time zone. Use `DateTime.withDate` when the
    * callback should receive the time-zone-adjusted wall-clock date.
    *
@@ -3321,6 +3474,8 @@ export const subtractDuration: {
 /**
  * Add the given `amount` of `unit`'s to a `DateTime`.
  *
+ * **Details**
+ *
  * The time zone is taken into account when adding days, weeks, months, and
  * years.
  *
@@ -3342,6 +3497,8 @@ export const add: {
   /**
    * Add the given `amount` of `unit`'s to a `DateTime`.
    *
+   * **Details**
+   *
    * The time zone is taken into account when adding days, weeks, months, and
    * years.
    *
@@ -3363,6 +3520,8 @@ export const add: {
   /**
    * Add the given `amount` of `unit`'s to a `DateTime`.
    *
+   * **Details**
+   *
    * The time zone is taken into account when adding days, weeks, months, and
    * years.
    *
@@ -3442,6 +3601,8 @@ export const subtract: {
 /**
  * Converts a `DateTime` to the start of the given `part`.
  *
+ * **Details**
+ *
  * 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).
  *
@@ -3464,6 +3625,8 @@ export const startOf: {
   /**
    * Converts a `DateTime` to the start of the given `part`.
    *
+   * **Details**
+   *
    * 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).
    *
@@ -3489,6 +3652,8 @@ export const startOf: {
   /**
    * Converts a `DateTime` to the start of the given `part`.
    *
+   * **Details**
+   *
    * 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).
    *
@@ -3517,6 +3682,8 @@ export const startOf: {
 /**
  * Converts a `DateTime` to the end of the given `part`.
  *
+ * **Details**
+ *
  * 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).
  *
@@ -3539,6 +3706,8 @@ export const endOf: {
   /**
    * Converts a `DateTime` to the end of the given `part`.
    *
+   * **Details**
+   *
    * 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).
    *
@@ -3564,6 +3733,8 @@ export const endOf: {
   /**
    * Converts a `DateTime` to the end of the given `part`.
    *
+   * **Details**
+   *
    * 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).
    *
@@ -3592,6 +3763,8 @@ export const endOf: {
 /**
  * Converts a `DateTime` to the nearest given `part`.
  *
+ * **Details**
+ *
  * 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).
  *
@@ -3614,6 +3787,8 @@ export const nearest: {
   /**
    * Converts a `DateTime` to the nearest given `part`.
    *
+   * **Details**
+   *
    * 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).
    *
@@ -3639,6 +3814,8 @@ export const nearest: {
   /**
    * Converts a `DateTime` to the nearest given `part`.
    *
+   * **Details**
+   *
    * 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).
    *
@@ -3671,6 +3848,8 @@ export const nearest: {
 /**
  * Formats a `DateTime` with `Intl.DateTimeFormat`.
  *
+ * **Details**
+ *
  * 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.
  *
@@ -3707,6 +3886,8 @@ export const format: {
   /**
    * Formats a `DateTime` with `Intl.DateTimeFormat`.
    *
+   * **Details**
+   *
    * 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.
    *
@@ -3749,6 +3930,8 @@ export const format: {
   /**
    * Formats a `DateTime` with `Intl.DateTimeFormat`.
    *
+   * **Details**
+   *
    * 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.
    *
@@ -3790,6 +3973,8 @@ export const format: {
 /**
  * Format a `DateTime` as a string using the `DateTimeFormat` API.
  *
+ * **Details**
+ *
  * It will use the system's local time zone & locale.
  *
  * **Example** (Formatting DateTime values locally)
@@ -3818,6 +4003,8 @@ export const formatLocal: {
   /**
    * Format a `DateTime` as a string using the `DateTimeFormat` API.
    *
+   * **Details**
+   *
    * It will use the system's local time zone & locale.
    *
    * **Example** (Formatting DateTime values locally)
@@ -3852,6 +4039,8 @@ export const formatLocal: {
   /**
    * Format a `DateTime` as a string using the `DateTimeFormat` API.
    *
+   * **Details**
+   *
    * It will use the system's local time zone & locale.
    *
    * **Example** (Formatting DateTime values locally)
@@ -3889,6 +4078,8 @@ export const formatLocal: {
 /**
  * Format a `DateTime` as a string using the `DateTimeFormat` API.
  *
+ * **Details**
+ *
  * This forces the time zone to be UTC.
  *
  * **Example** (Formatting DateTime values in UTC)
@@ -3920,6 +4111,8 @@ export const formatUtc: {
   /**
    * Format a `DateTime` as a string using the `DateTimeFormat` API.
    *
+   * **Details**
+   *
    * This forces the time zone to be UTC.
    *
    * **Example** (Formatting DateTime values in UTC)
@@ -3957,6 +4150,8 @@ export const formatUtc: {
   /**
    * Format a `DateTime` as a string using the `DateTimeFormat` API.
    *
+   * **Details**
+   *
    * This forces the time zone to be UTC.
    *
    * **Example** (Formatting DateTime values in UTC)
@@ -4083,6 +4278,8 @@ export const formatIntl: {
 /**
  * Format a `DateTime` as a UTC ISO string.
  *
+ * **Details**
+ *
  * Always returns the UTC representation in ISO 8601 format, ignoring any time zone.
  *
  * **Example** (Formatting DateTime values as ISO strings)
@@ -4107,6 +4304,8 @@ export const formatIso: (self: DateTime) => string = Internal.formatIso
 /**
  * Format a `DateTime` as a time zone adjusted ISO date string.
  *
+ * **Details**
+ *
  * Returns only the date part (YYYY-MM-DD) after applying time zone adjustments.
  *
  * **Example** (Formatting DateTime values as ISO dates)
@@ -4131,6 +4330,8 @@ export const formatIsoDate: (self: DateTime) => string = Internal.formatIsoDate
 /**
  * Format a `DateTime` as a UTC ISO date string.
  *
+ * **Details**
+ *
  * Returns only the date part (YYYY-MM-DD) in UTC, ignoring any time zone.
  *
  * **Example** (Formatting DateTime values as UTC ISO dates)
@@ -4155,6 +4356,8 @@ export const formatIsoDateUtc: (self: DateTime) => string = Internal.formatIsoDa
 /**
  * Format a `DateTime.Zoned` as an ISO string with an offset.
  *
+ * **Details**
+ *
  * For `DateTime.Utc`, returns the same as `formatIso`. For `DateTime.Zoned`,
  * includes the time zone offset in the format.
  *
@@ -4180,6 +4383,8 @@ export const formatIsoOffset: (self: DateTime) => string = Internal.formatIsoOff
 /**
  * Format a `DateTime.Zoned` as a string.
  *
+ * **Details**
+ *
  * It uses the format: `YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]`.
  *
  * **Example** (Formatting zoned DateTime values)
@@ -4210,6 +4415,8 @@ export const formatIsoZoned: (self: Zoned) => string = Internal.formatIsoZoned
 /**
  * Create a Layer from the given time zone.
  *
+ * **Details**
+ *
  * This layer provides the `CurrentTimeZone` service with the specified time zone.
  *
  * **Example** (Providing current time zone layers)
@@ -4239,6 +4446,8 @@ export const layerCurrentZone: (resource: NoInfer<TimeZone>) => Layer.Layer<Curr
 /**
  * Create a Layer from the given time zone offset.
  *
+ * **Details**
+ *
  * This layer provides the `CurrentTimeZone` service with a fixed offset time zone.
  *
  * **Example** (Providing fixed-offset time zone layers)
@@ -4266,6 +4475,8 @@ export const layerCurrentZoneOffset = (offset: number): Layer.Layer<CurrentTimeZ
 /**
  * Create a Layer from the given IANA time zone identifier.
  *
+ * **Details**
+ *
  * This layer provides the `CurrentTimeZone` service with a named time zone.
  * If the time zone identifier is invalid, the layer will fail.
  *
@@ -4295,6 +4506,8 @@ export const layerCurrentZoneNamed: (zoneId: string) => Layer.Layer<
 /**
  * Create a Layer from the system's local time zone.
  *
+ * **Details**
+ *
  * This layer provides the `CurrentTimeZone` service using the system's
  * configured local time zone.
  *