effect 4.0.0-beta.102 → 4.0.0-beta.103

package/dist/DateTime.js

@@ -111,7 +111,7 @@ export const isZoned = Internal.isZoned;
  *
  * **Example** (Comparing DateTime values for equivalence)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const utc = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
@@ -119,7 +119,7 @@ export const isZoned = Internal.isZoned;
  *   timeZone: "Europe/London"
  * })
  *
- * console.log(DateTime.Equivalence(utc, zoned)) // true
+ * DateTime.Equivalence(utc, zoned) // => true
  * ```
  *
  * @category instances
@@ -136,7 +136,7 @@ export const Equivalence = Internal.Equivalence;
  *
  * **Example** (Sorting DateTime values chronologically)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Array, DateTime } from "effect"
  *
  * const dates = [
@@ -145,8 +145,7 @@ export const Equivalence = Internal.Equivalence;
  *   DateTime.makeUnsafe("2024-02-01")
  * ]
  *
- * const sorted = Array.sort(dates, DateTime.Order)
- * // Results in chronological order: 2024-01-01, 2024-02-01, 2024-03-01
+ * Array.sort(dates, DateTime.Order).map(DateTime.formatIsoDateUtc) // => ["2024-01-01", "2024-02-01", "2024-03-01"]
  * ```
  *
  * @category instances
@@ -164,15 +163,14 @@ export const Order = Internal.Order;
  *
  * **Example** (Clamping DateTime values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const min = DateTime.makeUnsafe("2024-01-01")
  * const max = DateTime.makeUnsafe("2024-12-31")
  * const date = DateTime.makeUnsafe("2025-06-15")
  *
- * const clamped = DateTime.clamp(date, { minimum: min, maximum: max })
- * // clamped equals max (2024-12-31)
+ * DateTime.clamp(date, { minimum: min, maximum: max }) // => DateTime.makeUnsafe("2024-12-31")
  * ```
  *
  * @category ordering
@@ -191,13 +189,10 @@ export const clamp = Internal.clamp;
  *
  * **Example** (Creating DateTime values from Dates)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
- * const date = new Date("2024-01-01T12:00:00Z")
- * const dateTime = DateTime.fromDateUnsafe(date)
- *
- * console.log(DateTime.formatIso(dateTime)) // "2024-01-01T12:00:00.000Z"
+ * DateTime.fromDateUnsafe(new Date("2024-01-01T12:00:00Z")) // => DateTime.makeUnsafe("2024-01-01T12:00:00Z")
  * ```
  *
  * @category constructors
@@ -222,26 +217,38 @@ export const fromDateUnsafe = Internal.fromDateUnsafe;
  *
  * **Example** (Creating DateTime values unsafely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * // from Date
- * const fromDate = DateTime.makeUnsafe(new Date("2024-01-01T12:00:00Z"))
- * console.log(DateTime.formatIso(fromDate)) // "2024-01-01T12:00:00.000Z"
+ * DateTime.makeUnsafe(new Date("2024-01-01T12:00:00Z")) // => DateTime.makeUnsafe("2024-01-01T12:00:00Z")
  *
  * // from parts
- * const fromParts = DateTime.makeUnsafe({ year: 2024 })
- * console.log(DateTime.formatIso(fromParts)) // "2024-01-01T00:00:00.000Z"
+ * DateTime.makeUnsafe({ year: 2024 }) // => DateTime.makeUnsafe("2024-01-01T00:00:00Z")
  *
  * // from string
- * const fromString = DateTime.makeUnsafe("2024-01-01")
- * console.log(DateTime.formatIso(fromString)) // "2024-01-01T00:00:00.000Z"
+ * DateTime.makeUnsafe("2024-01-01") // => DateTime.makeUnsafe("2024-01-01T00:00:00Z")
  * ```
  *
  * @category constructors
  * @since 4.0.0
  */
 export const makeUnsafe = Internal.makeUnsafe;
+/**
+ * Creates a `DateTime.Utc` from the number of seconds since the Unix epoch.
+ *
+ * **Example** (Creating from epoch seconds)
+ *
+ * ```ts import.meta.vitest
+ * import { DateTime } from "effect"
+ *
+ * DateTime.fromEpochSeconds(1704067200).toJSON() // => "2024-01-01T00:00:00.000Z"
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const fromEpochSeconds = Internal.fromEpochSeconds;
 /**
  * Create a `DateTime.Zoned` using `DateTime.makeUnsafe` and a time zone.
  *
@@ -265,14 +272,14 @@ export const makeUnsafe = Internal.makeUnsafe;
  *
  * **Example** (Creating zoned DateTime values unsafely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * 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]"
+ * DateTime.formatIsoZoned(zoned) // => "2024-06-15T15:30:00.000+01:00[Europe/London]"
  * ```
  *
  * @category constructors
@@ -302,17 +309,14 @@ export const makeZonedUnsafe = Internal.makeZonedUnsafe;
  *
  * **Example** (Creating optional zoned DateTime values)
  *
- * ```ts
- * import { DateTime } from "effect"
+ * ```ts import.meta.vitest
+ * import { DateTime, Option } from "effect"
  *
  * 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]"
- * }
+ * result.pipe(Option.map(DateTime.formatIsoZoned)) // => Option.some("2024-06-15T15:30:00.000+01:00[Europe/London]")
  * ```
  *
  * @category constructors
@@ -336,23 +340,19 @@ export const makeZoned = Internal.makeZoned;
  *
  * **Example** (Creating optional DateTime values)
  *
- * ```ts
- * import { DateTime } from "effect"
+ * ```ts import.meta.vitest
+ * import { DateTime, Option } from "effect"
  *
  * // from Date
- * const fromDate = DateTime.make(new Date("2024-01-01T12:00:00Z"))
- * console.log(fromDate._tag) // "Some"
+ * DateTime.make(new Date("2024-01-01T12:00:00Z")) // => Option.some(DateTime.makeUnsafe("2024-01-01T12:00:00Z"))
  *
  * // from parts
- * const fromParts = DateTime.make({ year: 2024 })
- * console.log(fromParts._tag) // "Some"
+ * DateTime.make({ year: 2024 }) // => Option.some(DateTime.makeUnsafe("2024-01-01T00:00:00Z"))
  *
  * // from string
- * const fromString = DateTime.make("2024-01-01")
- * console.log(fromString._tag) // "Some"
+ * DateTime.make("2024-01-01") // => Option.some(DateTime.makeUnsafe("2024-01-01T00:00:00Z"))
  *
- * const invalid = DateTime.make("not a date")
- * console.log(invalid._tag) // "None"
+ * DateTime.make("not a date") // => Option.none()
  * ```
  *
  * @category constructors
@@ -371,19 +371,15 @@ export const make = Internal.make;
  *
  * **Example** (Parsing zoned DateTime strings)
  *
- * ```ts
- * import { DateTime } from "effect"
+ * ```ts import.meta.vitest
+ * import { DateTime, Option } from "effect"
  *
- * const result1 = DateTime.makeZonedFromString(
+ * DateTime.makeZonedFromString(
  *   "2024-01-01T12:00:00+02:00[Europe/Berlin]"
- * )
- * console.log(result1._tag === "Some") // true
- *
- * const result2 = DateTime.makeZonedFromString("2024-01-01T12:00:00Z")
- * console.log(result2._tag === "Some") // true
+ * ).pipe(Option.map(DateTime.formatIsoZoned)) // => Option.some("2024-01-01T11:00:00.000+01:00[Europe/Berlin]")
  *
- * const invalid = DateTime.makeZonedFromString("invalid")
- * console.log(invalid._tag === "None") // true
+ * DateTime.makeZonedFromString("2024-01-01T12:00:00Z") // => Option.none()
+ * DateTime.makeZonedFromString("invalid") // => Option.none()
  * ```
  *
  * @category constructors
@@ -391,17 +387,15 @@ export const make = Internal.make;
  */
 export const makeZonedFromString = Internal.makeZonedFromString;
 /**
- * Gets the current time using the `Clock` service and convert it to a `DateTime`.
+ * Gets the current time using the `Clock` service and converts it to a `DateTime`.
  *
  * **Example** (Getting the current DateTime)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
+ * import { TestClock } from "effect/testing"
  *
- * Effect.gen(function*() {
- *   const now = yield* DateTime.nowAsDate
- *   console.log(now instanceof Date) // true
- * })
+ * await Effect.runPromise(Effect.map(DateTime.now, DateTime.isDateTime)) // => true
  * ```
  *
  * @category constructors
@@ -414,12 +408,11 @@ export const now = Internal.now;
  *
  * **Example** (Getting the current Date)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
+ * import { TestClock } from "effect/testing"
  *
- * Effect.gen(function*() {
- *   const now = yield* DateTime.now
- * })
+ * await Effect.runPromise(Effect.map(DateTime.nowAsDate, (now) => now instanceof Date)) // => true
  * ```
  *
  * @category constructors
@@ -441,11 +434,10 @@ export const nowAsDate = Internal.nowAsDate;
  *
  * **Example** (Getting the current DateTime unsafely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
- * const now = DateTime.nowUnsafe()
- * console.log(DateTime.formatIso(now))
+ * Number.isFinite(DateTime.toEpochMillis(DateTime.nowUnsafe())) // => true
  * ```
  *
  * @category constructors
@@ -469,7 +461,7 @@ export const nowUnsafe = Internal.nowUnsafe;
  *
  * **Example** (Converting DateTime values to UTC)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const now = DateTime.makeZonedUnsafe({ year: 2024 }, {
@@ -478,9 +470,10 @@ export const nowUnsafe = Internal.nowUnsafe;
  *
  * // set as UTC
  * const utc: DateTime.Utc = DateTime.toUtc(now)
+ * utc // => DateTime.makeUnsafe("2024-01-01T00:00:00Z")
  * ```
  *
- * @category time zones
+ * @category converting
  * @since 3.13.0
  */
 export const toUtc = Internal.toUtc;
@@ -489,19 +482,16 @@ export const toUtc = Internal.toUtc;
  *
  * **Example** (Setting time zones)
  *
- * ```ts
- * import { DateTime, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { DateTime } from "effect"
  *
- * Effect.gen(function*() {
- *   const now = yield* DateTime.now
- *   const zone = DateTime.zoneMakeNamedUnsafe("Europe/London")
+ * const zone = DateTime.zoneMakeNamedUnsafe("Europe/London")
+ * const zoned: DateTime.Zoned = DateTime.setZone(DateTime.makeUnsafe("2024-01-01"), zone)
  *
- *   // set the time zone
- *   const zoned: DateTime.Zoned = DateTime.setZone(now, zone)
- * })
+ * DateTime.isZoned(zoned) // => true
  * ```
  *
- * @category time zones
+ * @category transforming
  * @since 3.6.0
  */
 export const setZone = Internal.setZone;
@@ -514,18 +504,16 @@ export const setZone = Internal.setZone;
  *
  * **Example** (Setting fixed-offset time zones)
  *
- * ```ts
- * import { DateTime, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { DateTime } from "effect"
  *
- * Effect.gen(function*() {
- *   const now = yield* DateTime.now
+ * const dateTime = DateTime.makeUnsafe("2024-01-01")
+ * const zoned: DateTime.Zoned = DateTime.setZoneOffset(dateTime, 3 * 60 * 60 * 1000)
  *
- *   // set the offset time zone in milliseconds
- *   const zoned: DateTime.Zoned = DateTime.setZoneOffset(now, 3 * 60 * 60 * 1000)
- * })
+ * DateTime.zoneToString(zoned.zone) // => "+03:00"
  * ```
  *
- * @category time zones
+ * @category transforming
  * @since 3.6.0
  */
 export const setZoneOffset = Internal.setZoneOffset;
@@ -543,20 +531,17 @@ export const setZoneOffset = Internal.setZoneOffset;
  *
  * **Example** (Creating named time zones unsafely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
- * const londonZone = DateTime.zoneMakeNamedUnsafe("Europe/London")
- * console.log(DateTime.zoneToString(londonZone)) // "Europe/London"
- *
- * const tokyoZone = DateTime.zoneMakeNamedUnsafe("Asia/Tokyo")
- * console.log(DateTime.zoneToString(tokyoZone)) // "Asia/Tokyo"
+ * DateTime.zoneToString(DateTime.zoneMakeNamedUnsafe("Europe/London")) // => "Europe/London"
+ * DateTime.zoneToString(DateTime.zoneMakeNamedUnsafe("Asia/Tokyo")) // => "Asia/Tokyo"
  *
  * // This would throw an IllegalArgumentError:
  * // DateTime.zoneMakeNamedUnsafe("Invalid/Zone")
  * ```
  *
- * @category time zones
+ * @category constructors
  * @since 4.0.0
  */
 export const zoneMakeNamedUnsafe = Internal.zoneMakeNamedUnsafe;
@@ -570,7 +555,7 @@ export const zoneMakeNamedUnsafe = Internal.zoneMakeNamedUnsafe;
  *
  * **Example** (Creating fixed-offset time zones)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * // Create a time zone with +3 hours offset
@@ -579,9 +564,10 @@ export const zoneMakeNamedUnsafe = Internal.zoneMakeNamedUnsafe;
  * const dt = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
  *   timeZone: zone
  * })
+ * DateTime.formatIsoZoned(dt) // => "2024-01-01T15:00:00.000+03:00"
  * ```
  *
- * @category time zones
+ * @category constructors
  * @since 3.6.0
  */
 export const zoneMakeOffset = Internal.zoneMakeOffset;
@@ -594,17 +580,14 @@ export const zoneMakeOffset = Internal.zoneMakeOffset;
  *
  * **Example** (Creating optional named time zones)
  *
- * ```ts
- * import { DateTime } from "effect"
- *
- * const validZone = DateTime.zoneMakeNamed("Europe/London")
- * console.log(validZone._tag === "Some") // true
+ * ```ts import.meta.vitest
+ * import { DateTime, Option } from "effect"
  *
- * const invalidZone = DateTime.zoneMakeNamed("Invalid/Zone")
- * console.log(invalidZone._tag === "None") // true
+ * DateTime.zoneMakeNamed("Europe/London").pipe(Option.map(DateTime.zoneToString)) // => Option.some("Europe/London")
+ * DateTime.zoneMakeNamed("Invalid/Zone") // => Option.none()
  * ```
  *
- * @category time zones
+ * @category constructors
  * @since 3.6.0
  */
 export const zoneMakeNamed = Internal.zoneMakeNamed;
@@ -618,7 +601,7 @@ export const zoneMakeNamed = Internal.zoneMakeNamed;
  *
  * **Example** (Creating named time zones effectfully)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -626,9 +609,11 @@ export const zoneMakeNamed = Internal.zoneMakeNamed;
  *   const now = yield* DateTime.now
  *   return DateTime.setZone(now, zone)
  * })
+ *
+ * DateTime.zoneToString((await Effect.runPromise(program)).zone) // => "Europe/London"
  * ```
  *
- * @category time zones
+ * @category constructors
  * @since 3.6.0
  */
 export const zoneMakeNamedEffect = Internal.zoneMakeNamedEffect;
@@ -642,14 +627,13 @@ export const zoneMakeNamedEffect = Internal.zoneMakeNamedEffect;
  *
  * **Example** (Creating local time zones)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
- * const localZone = DateTime.zoneMakeLocal()
- * console.log(DateTime.zoneToString(localZone)) // Output depends on system time zone
+ * DateTime.isTimeZoneNamed(DateTime.zoneMakeLocal()) // => true
  * ```
  *
- * @category time zones
+ * @category constructors
  * @since 3.6.0
  */
 export const zoneMakeLocal = Internal.zoneMakeLocal;
@@ -662,19 +646,15 @@ export const zoneMakeLocal = Internal.zoneMakeLocal;
  *
  * **Example** (Parsing time zones)
  *
- * ```ts
- * import { DateTime } from "effect"
- *
- * const namedZone = DateTime.zoneFromString("Europe/London")
- * const offsetZone = DateTime.zoneFromString("+03:00")
- * const invalid = DateTime.zoneFromString("invalid")
+ * ```ts import.meta.vitest
+ * import { DateTime, Option } from "effect"
  *
- * console.log(namedZone._tag === "Some") // true
- * console.log(offsetZone._tag === "Some") // true
- * console.log(invalid._tag === "None") // true
+ * DateTime.zoneFromString("Europe/London").pipe(Option.map(DateTime.zoneToString)) // => Option.some("Europe/London")
+ * DateTime.zoneFromString("+03:00").pipe(Option.map(DateTime.zoneToString)) // => Option.some("+03:00")
+ * DateTime.zoneFromString("invalid") // => Option.none()
  * ```
  *
- * @category time zones
+ * @category decoding
  * @since 3.6.0
  */
 export const zoneFromString = Internal.zoneFromString;
@@ -683,17 +663,14 @@ export const zoneFromString = Internal.zoneFromString;
  *
  * **Example** (Formatting time zones)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
- * // Outputs "+03:00"
- * DateTime.zoneToString(DateTime.zoneMakeOffset(3 * 60 * 60 * 1000))
- *
- * // Outputs "Europe/London"
- * DateTime.zoneToString(DateTime.zoneMakeNamedUnsafe("Europe/London"))
+ * DateTime.zoneToString(DateTime.zoneMakeOffset(3 * 60 * 60 * 1000)) // => "+03:00"
+ * DateTime.zoneToString(DateTime.zoneMakeNamedUnsafe("Europe/London")) // => "Europe/London"
  * ```
  *
- * @category time zones
+ * @category encoding
  * @since 3.6.0
  */
 export const zoneToString = Internal.zoneToString;
@@ -703,17 +680,16 @@ export const zoneToString = Internal.zoneToString;
  *
  * **Example** (Setting named time zones safely)
  *
- * ```ts
- * import { DateTime, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { DateTime, Option } from "effect"
  *
- * Effect.gen(function*() {
- *   const now = yield* DateTime.now
- *   // set the time zone, returns an Option
- *   DateTime.setZoneNamed(now, "Europe/London")
- * })
+ * const dateTime = DateTime.makeUnsafe("2024-01-01")
+ * const result = DateTime.setZoneNamed(dateTime, "Europe/London").pipe(Option.map(DateTime.formatIsoZoned))
+ *
+ * result // => Option.some("2024-01-01T00:00:00.000+00:00[Europe/London]")
  * ```
  *
- * @category time zones
+ * @category transforming
  * @since 3.6.0
  */
 export const setZoneNamed = Internal.setZoneNamed;
@@ -723,17 +699,16 @@ export const setZoneNamed = Internal.setZoneNamed;
  *
  * **Example** (Setting named time zones unsafely)
  *
- * ```ts
- * import { DateTime, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { DateTime } from "effect"
  *
- * Effect.gen(function*() {
- *   const now = yield* DateTime.now
- *   // set the time zone
- *   DateTime.setZoneNamedUnsafe(now, "Europe/London")
- * })
+ * const dateTime = DateTime.makeUnsafe("2024-01-01")
+ * const zoned = DateTime.setZoneNamedUnsafe(dateTime, "Europe/London")
+ *
+ * DateTime.zoneToString(zoned.zone) // => "Europe/London"
  * ```
  *
- * @category time zones
+ * @category transforming
  * @since 4.0.0
  */
 export const setZoneNamedUnsafe = Internal.setZoneNamedUnsafe;
@@ -752,16 +727,13 @@ export const setZoneNamedUnsafe = Internal.setZoneNamedUnsafe;
  *
  * **Example** (Measuring distance between DateTime values)
  *
- * ```ts
- * import { DateTime, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { DateTime, Duration } from "effect"
  *
- * Effect.gen(function*() {
- *   const now = yield* DateTime.now
- *   const other = DateTime.add(now, { minutes: 1 })
+ * const start = DateTime.makeUnsafe("2024-01-01T00:00:00Z")
+ * const end = DateTime.add(start, { minutes: 1 })
  *
- *   // returns Duration.minutes(1)
- *   DateTime.distance(now, other)
- * })
+ * DateTime.distance(start, end) // => Duration.minutes(1)
  * ```
  *
  * @category comparisons
@@ -773,14 +745,13 @@ export const distance = Internal.distance;
  *
  * **Example** (Selecting the earlier DateTime)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const date1 = DateTime.makeUnsafe("2024-01-01")
  * const date2 = DateTime.makeUnsafe("2024-02-01")
  *
- * const earlier = DateTime.min(date1, date2)
- * // earlier equals date1 (2024-01-01)
+ * DateTime.min(date1, date2) // => DateTime.makeUnsafe("2024-01-01")
  * ```
  *
  * @category comparisons
@@ -792,14 +763,13 @@ export const min = Internal.min;
  *
  * **Example** (Selecting the later DateTime)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const date1 = DateTime.makeUnsafe("2024-01-01")
  * const date2 = DateTime.makeUnsafe("2024-02-01")
  *
- * const later = DateTime.max(date1, date2)
- * // later equals date2 (2024-02-01)
+ * DateTime.max(date1, date2) // => DateTime.makeUnsafe("2024-02-01")
  * ```
  *
  * @category comparisons
@@ -811,14 +781,14 @@ export const max = Internal.max;
  *
  * **Example** (Checking whether a DateTime is later)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const date1 = DateTime.makeUnsafe("2024-02-01")
  * const date2 = DateTime.makeUnsafe("2024-01-01")
  *
- * console.log(DateTime.isGreaterThan(date1, date2)) // true
- * console.log(DateTime.isGreaterThan(date2, date1)) // false
+ * DateTime.isGreaterThan(date1, date2) // => true
+ * DateTime.isGreaterThan(date2, date1) // => false
  * ```
  *
  * @category comparisons
@@ -830,16 +800,16 @@ export const isGreaterThan = Internal.isGreaterThan;
  *
  * **Example** (Checking whether a DateTime is later or equal)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const date1 = DateTime.makeUnsafe("2024-01-01")
  * const date2 = DateTime.makeUnsafe("2024-01-01")
  * const date3 = DateTime.makeUnsafe("2024-02-01")
  *
- * console.log(DateTime.isGreaterThanOrEqualTo(date1, date2)) // true
- * console.log(DateTime.isGreaterThanOrEqualTo(date3, date1)) // true
- * console.log(DateTime.isGreaterThanOrEqualTo(date1, date3)) // false
+ * DateTime.isGreaterThanOrEqualTo(date1, date2) // => true
+ * DateTime.isGreaterThanOrEqualTo(date3, date1) // => true
+ * DateTime.isGreaterThanOrEqualTo(date1, date3) // => false
  * ```
  *
  * @category comparisons
@@ -851,14 +821,14 @@ export const isGreaterThanOrEqualTo = Internal.isGreaterThanOrEqualTo;
  *
  * **Example** (Checking whether a DateTime is earlier)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const date1 = DateTime.makeUnsafe("2024-01-01")
  * const date2 = DateTime.makeUnsafe("2024-02-01")
  *
- * console.log(DateTime.isLessThan(date1, date2)) // true
- * console.log(DateTime.isLessThan(date2, date1)) // false
+ * DateTime.isLessThan(date1, date2) // => true
+ * DateTime.isLessThan(date2, date1) // => false
  * ```
  *
  * @category comparisons
@@ -870,16 +840,16 @@ export const isLessThan = Internal.isLessThan;
  *
  * **Example** (Checking whether a DateTime is earlier or equal)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const date1 = DateTime.makeUnsafe("2024-01-01")
  * const date2 = DateTime.makeUnsafe("2024-01-01")
  * const date3 = DateTime.makeUnsafe("2024-02-01")
  *
- * console.log(DateTime.isLessThanOrEqualTo(date1, date2)) // true
- * console.log(DateTime.isLessThanOrEqualTo(date1, date3)) // true
- * console.log(DateTime.isLessThanOrEqualTo(date3, date1)) // false
+ * DateTime.isLessThanOrEqualTo(date1, date2) // => true
+ * DateTime.isLessThanOrEqualTo(date1, date3) // => true
+ * DateTime.isLessThanOrEqualTo(date3, date1) // => false
  * ```
  *
  * @category comparisons
@@ -891,14 +861,14 @@ export const isLessThanOrEqualTo = Internal.isLessThanOrEqualTo;
  *
  * **Example** (Checking whether a DateTime is within bounds)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const min = DateTime.makeUnsafe("2024-01-01")
  * const max = DateTime.makeUnsafe("2024-12-31")
  * const date = DateTime.makeUnsafe("2024-06-15")
  *
- * console.log(DateTime.between(date, { minimum: min, maximum: max })) // true
+ * DateTime.between(date, { minimum: min, maximum: max }) // => true
  * ```
  *
  * @category comparisons
@@ -914,14 +884,12 @@ export const between = Internal.between;
  *
  * **Example** (Checking future DateTime values effectfully)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
+ * import { TestClock } from "effect/testing"
  *
- * const program = Effect.gen(function*() {
- *   const futureDate = DateTime.add(yield* DateTime.now, { hours: 1 })
- *   const isFuture = yield* DateTime.isFuture(futureDate)
- *   console.log(isFuture) // true
- * })
+ * const futureDate = DateTime.makeUnsafe(1)
+ * await Effect.runPromise(Effect.provide(DateTime.isFuture(futureDate), TestClock.layer())) // => true
  * ```
  *
  * @category comparisons
@@ -945,11 +913,8 @@ export const isFuture = Internal.isFuture;
  * ```ts
  * import { DateTime } from "effect"
  *
- * const now = DateTime.nowUnsafe()
- * const futureDate = DateTime.add(now, { hours: 1 })
- *
- * console.log(DateTime.isFutureUnsafe(futureDate)) // true
- * console.log(DateTime.isFutureUnsafe(now)) // false
+ * const oneHourFromNow = DateTime.add(DateTime.nowUnsafe(), { hours: 1 })
+ * DateTime.isFutureUnsafe(oneHourFromNow)
  * ```
  *
  * @category comparisons
@@ -965,14 +930,12 @@ export const isFutureUnsafe = Internal.isFutureUnsafe;
  *
  * **Example** (Checking past DateTime values effectfully)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
+ * import { TestClock } from "effect/testing"
  *
- * const program = Effect.gen(function*() {
- *   const pastDate = DateTime.subtract(yield* DateTime.now, { hours: 1 })
- *   const isPast = yield* DateTime.isPast(pastDate)
- *   console.log(isPast) // true
- * })
+ * const pastDate = DateTime.makeUnsafe(-1)
+ * await Effect.runPromise(Effect.provide(DateTime.isPast(pastDate), TestClock.layer())) // => true
  * ```
  *
  * @category comparisons
@@ -996,11 +959,8 @@ export const isPast = Internal.isPast;
  * ```ts
  * import { DateTime } from "effect"
  *
- * const now = DateTime.nowUnsafe()
- * const pastDate = DateTime.subtract(now, { hours: 1 })
- *
- * console.log(DateTime.isPastUnsafe(pastDate)) // true
- * console.log(DateTime.isPastUnsafe(now)) // false
+ * const oneHourAgo = DateTime.subtract(DateTime.nowUnsafe(), { hours: 1 })
+ * DateTime.isPastUnsafe(oneHourAgo)
  * ```
  *
  * @category comparisons
@@ -1019,15 +979,14 @@ export const isPastUnsafe = Internal.isPastUnsafe;
  *
  * **Example** (Converting DateTime values to UTC Dates)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dt = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
  *   timeZone: "Europe/London"
  * })
  *
- * const utcDate = DateTime.toDateUtc(dt)
- * console.log(utcDate.toISOString()) // "2024-01-01T12:00:00.000Z"
+ * DateTime.toDateUtc(dt).toISOString() // => "2024-01-01T12:00:00.000Z"
  * ```
  *
  * @category converting
@@ -1044,7 +1003,7 @@ export const toDateUtc = Internal.toDateUtc;
  *
  * **Example** (Converting DateTime values to Dates)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const utc = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
@@ -1052,8 +1011,8 @@ export const toDateUtc = Internal.toDateUtc;
  *   timeZone: "Europe/London"
  * })
  *
- * console.log(DateTime.toDate(utc).toISOString())
- * console.log(DateTime.toDate(zoned).toISOString())
+ * DateTime.toDate(utc).toISOString() // => "2024-01-01T12:00:00.000Z"
+ * DateTime.toDate(zoned).toISOString() // => "2024-01-01T12:00:00.000Z"
  * ```
  *
  * @category converting
@@ -1070,15 +1029,14 @@ export const toDate = Internal.toDate;
  *
  * **Example** (Reading zoned offsets)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
  *   timeZone: "Europe/London"
  * })
  *
- * const offset = DateTime.zonedOffset(zoned)
- * console.log(offset) // 0 (London is UTC+0 in winter)
+ * DateTime.zonedOffset(zoned) // => 0
  * ```
  *
  * @category converting
@@ -1094,15 +1052,14 @@ export const zonedOffset = Internal.zonedOffset;
  *
  * **Example** (Formatting zoned offsets)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
  *   timeZone: DateTime.zoneMakeOffset(3 * 60 * 60 * 1000) // +3 hours
  * })
  *
- * const offsetString = DateTime.zonedOffsetIso(zoned)
- * console.log(offsetString) // "+03:00"
+ * DateTime.zonedOffsetIso(zoned) // => "+03:00"
  * ```
  *
  * @category converting
@@ -1118,26 +1075,45 @@ export const zonedOffsetIso = Internal.zonedOffsetIso;
  *
  * **Example** (Reading epoch milliseconds)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dt = DateTime.makeUnsafe("2024-01-01T00:00:00Z")
- * const epochMillis = DateTime.toEpochMillis(dt)
- *
- * console.log(epochMillis) // 1704067200000
+ * DateTime.toEpochMillis(dt) // => 1704067200000
  * ```
  *
  * @category converting
  * @since 3.6.0
  */
 export const toEpochMillis = Internal.toEpochMillis;
+/**
+ * Converts a `DateTime` to the number of seconds since the Unix epoch.
+ *
+ * **Details**
+ *
+ * This returns the UTC timestamp regardless of any time zone information.
+ * The result is floored to the nearest second.
+ *
+ * **Example** (Reading epoch seconds)
+ *
+ * ```ts import.meta.vitest
+ * import { DateTime } from "effect"
+ *
+ * const dt = DateTime.makeUnsafe("2024-01-01T00:00:00Z")
+ * DateTime.toEpochSeconds(dt) // => 1704067200
+ * ```
+ *
+ * @category converting
+ * @since 4.0.0
+ */
+export const toEpochSeconds = Internal.toEpochSeconds;
 /**
  * Removes the time aspect of a `DateTime`, first adjusting for the time
  * zone. It will return a `DateTime.Utc` only containing the date.
  *
  * **Example** (Removing time components)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * // returns "2024-01-01T00:00:00Z"
@@ -1147,7 +1123,7 @@ export const toEpochMillis = Internal.toEpochMillis;
  * }).pipe(
  *   DateTime.removeTime,
  *   DateTime.formatIso
- * )
+ * ) // => "2024-01-01T00:00:00.000Z"
  * ```
  *
  * @category converting
@@ -1166,26 +1142,16 @@ export const removeTime = Internal.removeTime;
  *
  * **Example** (Reading DateTime parts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dt = DateTime.makeUnsafe("2024-01-01T12:30:45.123Z")
  * const parts = DateTime.toParts(dt)
  *
- * console.log(parts)
- * // {
- * //   year: 2024,
- * //   month: 1,
- * //   day: 1,
- * //   hours: 12,
- * //   minutes: 30,
- * //   seconds: 45,
- * //   millis: 123,
- * //   weekDay: 1 // Monday
- * // }
+ * const selectedParts = [parts.year, parts.month, parts.day, parts.hour] // => [2024, 1, 1, 12]
  * ```
  *
- * @category parts
+ * @category getters
  * @since 3.6.0
  */
 export const toParts = Internal.toParts;
@@ -1198,7 +1164,7 @@ export const toParts = Internal.toParts;
  *
  * **Example** (Reading UTC DateTime parts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:30:45.123Z", {
@@ -1206,11 +1172,10 @@ export const toParts = Internal.toParts;
  * })
  * const parts = DateTime.toPartsUtc(zoned)
  *
- * console.log(parts)
- * // Always returns UTC parts regardless of time zone
+ * const selectedParts = [parts.year, parts.month, parts.day, parts.hour] // => [2024, 1, 1, 12]
  * ```
  *
- * @category parts
+ * @category getters
  * @since 3.6.0
  */
 export const toPartsUtc = Internal.toPartsUtc;
@@ -1223,15 +1188,14 @@ export const toPartsUtc = Internal.toPartsUtc;
  *
  * **Example** (Reading UTC DateTime parts by key)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dateTime = DateTime.makeUnsafe({ year: 2024 })
- * const year = DateTime.getPartUtc(dateTime, "year")
- * console.log(year) // 2024
+ * DateTime.getPartUtc(dateTime, "year") // => 2024
  * ```
  *
- * @category parts
+ * @category getters
  * @since 3.6.0
  */
 export const getPartUtc = Internal.getPartUtc;
@@ -1244,17 +1208,16 @@ export const getPartUtc = Internal.getPartUtc;
  *
  * **Example** (Reading DateTime parts by key)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dateTime = DateTime.makeZonedUnsafe({ year: 2024 }, {
  *   timeZone: "Europe/London"
  * })
- * const year = DateTime.getPart(dateTime, "year")
- * console.log(year) // 2024
+ * DateTime.getPart(dateTime, "year") // => 2024
  * ```
  *
- * @category parts
+ * @category getters
  * @since 3.6.0
  */
 export const getPart = Internal.getPart;
@@ -1267,20 +1230,20 @@ export const getPart = Internal.getPart;
  *
  * **Example** (Updating DateTime parts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
- * const dt = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
+ * const dt = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", { timeZone: "UTC" })
  * const updated = DateTime.setParts(dt, {
  *   year: 2025,
  *   month: 6,
  *   day: 15
  * })
  *
- * console.log(DateTime.formatIso(updated)) // "2025-06-15T12:00:00.000Z"
+ * updated // => DateTime.makeZonedUnsafe("2025-06-15T12:00:00Z", { timeZone: "UTC" })
  * ```
  *
- * @category parts
+ * @category transforming
  * @since 3.6.0
  */
 export const setParts = Internal.setParts;
@@ -1293,7 +1256,7 @@ export const setParts = Internal.setParts;
  *
  * **Example** (Updating UTC DateTime parts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dt = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
@@ -1302,10 +1265,10 @@ export const setParts = Internal.setParts;
  *   hour: 18
  * })
  *
- * console.log(DateTime.formatIso(updated)) // "2025-01-01T18:00:00.000Z"
+ * updated // => DateTime.makeUnsafe("2025-01-01T18:00:00Z")
  * ```
  *
- * @category parts
+ * @category transforming
  * @since 3.6.0
  */
 export const setPartsUtc = Internal.setPartsUtc;
@@ -1324,21 +1287,19 @@ export const setPartsUtc = Internal.setPartsUtc;
  *
  * **Example** (Accessing the current time zone service)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
- *   // Access the current time zone service
- *   const zone = yield* DateTime.CurrentTimeZone
- *   console.log(DateTime.zoneToString(zone))
+ *   return DateTime.zoneToString(yield* DateTime.CurrentTimeZone)
  * })
  *
  * // Provide a time zone
  * const layer = DateTime.layerCurrentZoneNamed("Europe/London")
- * Effect.provide(program, layer)
+ * await Effect.runPromise(Effect.provide(program, layer)) // => "Europe/London"
  * ```
  *
- * @category current time zone
+ * @category services
  * @since 3.11.0
  */
 export class CurrentTimeZone extends /*#__PURE__*/Context.Service()("effect/DateTime/CurrentTimeZone") {}
@@ -1348,18 +1309,16 @@ export class CurrentTimeZone extends /*#__PURE__*/Context.Service()("effect/Date
  *
  * **Example** (Setting the current time zone)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
  *
- * Effect.gen(function*() {
- *   const now = yield* DateTime.now
- *
- *   // set the time zone to "Europe/London"
- *   const zoned = yield* DateTime.setZoneCurrent(now)
- * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
+ * await Effect.runPromise(Effect.gen(function*() {
+ *   const zoned = yield* DateTime.setZoneCurrent(DateTime.makeUnsafe("2024-01-01"))
+ *   return DateTime.zoneToString(zoned.zone)
+ * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))) // => "Europe/London"
  * ```
  *
- * @category current time zone
+ * @category accessors
  * @since 3.6.0
  */
 export const setZoneCurrent = self => Effect.map(CurrentTimeZone, zone => setZone(self, zone));
@@ -1368,17 +1327,18 @@ export const setZoneCurrent = self => Effect.map(CurrentTimeZone, zone => setZon
  *
  * **Example** (Providing the current time zone)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
  *
  * const zone = DateTime.zoneMakeNamedUnsafe("Europe/London")
  *
- * Effect.gen(function*() {
- *   const now = yield* DateTime.nowInCurrentZone
- * }).pipe(DateTime.withCurrentZone(zone))
+ * await Effect.runPromise(Effect.gen(function*() {
+ *   const zoned = yield* DateTime.setZoneCurrent(DateTime.makeUnsafe("2024-01-01"))
+ *   return DateTime.zoneToString(zoned.zone)
+ * }).pipe(DateTime.withCurrentZone(zone))) // => "Europe/London"
  * ```
  *
- * @category current time zone
+ * @category providing services
  * @since 3.6.0
  */
 export const withCurrentZone = /*#__PURE__*/provideService(CurrentTimeZone);
@@ -1388,16 +1348,15 @@ export const withCurrentZone = /*#__PURE__*/provideService(CurrentTimeZone);
  *
  * **Example** (Providing the local time zone)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
  *
- * Effect.gen(function*() {
- *   // will use the system's local time zone
- *   const now = yield* DateTime.nowInCurrentZone
- * }).pipe(DateTime.withCurrentZoneLocal)
+ * await Effect.runPromise(Effect.gen(function*() {
+ *   return DateTime.isZoned(yield* DateTime.nowInCurrentZone)
+ * }).pipe(DateTime.withCurrentZoneLocal)) // => true
  * ```
  *
- * @category current time zone
+ * @category providing services
  * @since 3.6.0
  */
 export const withCurrentZoneLocal = effect => Effect.provideServiceEffect(effect, CurrentTimeZone, Effect.sync(zoneMakeLocal));
@@ -1406,16 +1365,17 @@ export const withCurrentZoneLocal = effect => Effect.provideServiceEffect(effect
  *
  * **Example** (Providing a fixed-offset time zone)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
  *
- * Effect.gen(function*() {
- *   const zone = yield* DateTime.CurrentTimeZone
- *   console.log(DateTime.zoneToString(zone)) // "+03:00"
+ * const program = Effect.gen(function*() {
+ *   return DateTime.zoneToString(yield* DateTime.CurrentTimeZone)
  * }).pipe(DateTime.withCurrentZoneOffset(3 * 60 * 60 * 1000))
+ *
+ * await Effect.runPromise(program) // => "+03:00"
  * ```
  *
- * @category current time zone
+ * @category providing services
  * @since 3.6.0
  */
 export const withCurrentZoneOffset = /*#__PURE__*/dual(2, (effect, offset) => Effect.provideService(effect, CurrentTimeZone, zoneMakeOffset(offset)));
@@ -1429,16 +1389,16 @@ export const withCurrentZoneOffset = /*#__PURE__*/dual(2, (effect, offset) => Ef
  *
  * **Example** (Providing a named time zone)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
  *
- * Effect.gen(function*() {
- *   // will use the "Europe/London" time zone
- *   const now = yield* DateTime.nowInCurrentZone
- * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
+ * await Effect.runPromise(Effect.gen(function*() {
+ *   const zoned = yield* DateTime.setZoneCurrent(DateTime.makeUnsafe("2024-01-01"))
+ *   return DateTime.zoneToString(zoned.zone)
+ * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))) // => "Europe/London"
  * ```
  *
- * @category current time zone
+ * @category providing services
  * @since 3.6.0
  */
 export const withCurrentZoneNamed = /*#__PURE__*/dual(2, (effect, zone) => Effect.provideServiceEffect(effect, CurrentTimeZone, zoneMakeNamedEffect(zone)));
@@ -1447,16 +1407,15 @@ export const withCurrentZoneNamed = /*#__PURE__*/dual(2, (effect, zone) => Effec
  *
  * **Example** (Getting the current time in the current zone)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
  *
- * Effect.gen(function*() {
- *   // will use the "Europe/London" time zone
- *   const now = yield* DateTime.nowInCurrentZone
- * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
+ * await Effect.runPromise(Effect.gen(function*() {
+ *   return DateTime.zoneToString((yield* DateTime.nowInCurrentZone).zone)
+ * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))) // => "Europe/London"
  * ```
  *
- * @category current time zone
+ * @category accessors
  * @since 3.6.0
  */
 export const nowInCurrentZone = /*#__PURE__*/Effect.flatMap(now, setZoneCurrent);
@@ -1480,17 +1439,15 @@ export const nowInCurrentZone = /*#__PURE__*/Effect.flatMap(now, setZoneCurrent)
  *
  * **Example** (Mutating DateTime values with Dates)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dt = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
  *
- * const modified = DateTime.mutate(dt, (date) => {
+ * DateTime.mutate(dt, (date) => {
  *   date.setHours(15) // Set to 3 PM
  *   date.setMinutes(30) // Set to 30 minutes
  * })
- *
- * console.log(DateTime.formatIso(modified)) // "2024-01-01T15:30:00.000Z"
  * ```
  *
  * @category mapping
@@ -1507,7 +1464,7 @@ export const mutate = Internal.mutate;
  *
  * **Example** (Mutating DateTime values with UTC Dates)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dt = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
@@ -1518,7 +1475,7 @@ export const mutate = Internal.mutate;
  *   date.setUTCHours(18) // Set UTC time to 6 PM
  * })
  *
- * console.log(DateTime.formatIso(modified)) // "2024-01-01T18:00:00.000Z"
+ * modified // => DateTime.makeZonedUnsafe("2024-01-01T18:00:00Z", { timeZone: "Europe/London" })
  * ```
  *
  * @category mapping
@@ -1531,13 +1488,14 @@ export const mutateUtc = Internal.mutateUtc;
  *
  * **Example** (Mapping epoch milliseconds)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * // add 10 milliseconds
- * DateTime.makeUnsafe(0).pipe(
+ * const result = DateTime.makeUnsafe(0).pipe(
  *   DateTime.mapEpochMillis((millis) => millis + 10)
  * )
+ * result // => DateTime.makeUnsafe(10)
  * ```
  *
  * @category mapping
@@ -1556,13 +1514,13 @@ export const mapEpochMillis = Internal.mapEpochMillis;
  *
  * **Example** (Applying time zone adjusted Dates)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * // get the time zone adjusted date in milliseconds
  * DateTime.makeZonedUnsafe(0, { timeZone: "Europe/London" }).pipe(
  *   DateTime.withDate((date) => date.getTime())
- * )
+ * ) // => 3600000
  * ```
  *
  * @category mapping
@@ -1580,13 +1538,13 @@ export const withDate = Internal.withDate;
  *
  * **Example** (Applying UTC Dates)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * // get the date in milliseconds
  * DateTime.makeUnsafe(0).pipe(
  *   DateTime.withDateUtc((date) => date.getTime())
- * )
+ * ) // => 0
  * ```
  *
  * @category mapping
@@ -1598,7 +1556,7 @@ export const withDateUtc = Internal.withDateUtc;
  *
  * **Example** (Pattern matching DateTime variants)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dt1 = DateTime.makeUnsafe("2024-01-01T12:00:00Z") // Utc
@@ -1616,8 +1574,8 @@ export const withDateUtc = Internal.withDateUtc;
  *   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]"
+ * result1 // => "UTC: 2024-01-01T12:00:00.000Z"
+ * result2 // => "Zoned: 2024-06-15T15:30:00.000+01:00[Europe/London]"
  * ```
  *
  * @category mapping
@@ -1648,13 +1606,13 @@ export const match = Internal.match;
  *
  * **Example** (Adding durations)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * // add 5 minutes
  * DateTime.makeUnsafe(0).pipe(
  *   DateTime.addDuration("5 minutes")
- * )
+ * ) // => DateTime.makeUnsafe(300000)
  * ```
  *
  * @see {@link add} for calendar-aware date/time part arithmetic
@@ -1669,13 +1627,13 @@ export const addDuration = Internal.addDuration;
  *
  * **Example** (Subtracting durations)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * // subtract 5 minutes
  * DateTime.makeUnsafe(0).pipe(
  *   DateTime.subtractDuration("5 minutes")
- * )
+ * ) // => DateTime.makeUnsafe(-300000)
  * ```
  *
  * @category math
@@ -1692,13 +1650,13 @@ export const subtractDuration = Internal.subtractDuration;
  *
  * **Example** (Adding date and time parts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * // add 5 minutes
  * DateTime.makeUnsafe(0).pipe(
  *   DateTime.add({ minutes: 5 })
- * )
+ * ) // => DateTime.makeUnsafe(300000)
  * ```
  *
  * @category math
@@ -1710,13 +1668,13 @@ export const add = Internal.add;
  *
  * **Example** (Subtracting date and time parts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * // subtract 5 minutes
  * DateTime.makeUnsafe(0).pipe(
  *   DateTime.subtract({ minutes: 5 })
- * )
+ * ) // => DateTime.makeUnsafe(-300000)
  * ```
  *
  * @category math
@@ -1733,14 +1691,13 @@ export const subtract = Internal.subtract;
  *
  * **Example** (Rounding down DateTime values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * // returns "2024-01-01T00:00:00Z"
  * DateTime.makeUnsafe("2024-01-01T12:00:00Z").pipe(
  *   DateTime.startOf("day"),
- *   DateTime.formatIso
- * )
+ * ) // => DateTime.makeUnsafe("2024-01-01T00:00:00Z")
  * ```
  *
  * @category math
@@ -1757,14 +1714,13 @@ export const startOf = Internal.startOf;
  *
  * **Example** (Rounding up DateTime values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * // returns "2024-01-01T23:59:59.999Z"
  * DateTime.makeUnsafe("2024-01-01T12:00:00Z").pipe(
  *   DateTime.endOf("day"),
- *   DateTime.formatIso
- * )
+ * ) // => DateTime.makeUnsafe("2024-01-01T23:59:59.999Z")
  * ```
  *
  * @category math
@@ -1781,14 +1737,13 @@ export const endOf = Internal.endOf;
  *
  * **Example** (Rounding DateTime values to nearest units)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * // returns "2024-01-02T00:00:00Z"
  * DateTime.makeUnsafe("2024-01-01T12:01:00Z").pipe(
  *   DateTime.nearest("day"),
- *   DateTime.formatIso
- * )
+ * ) // => DateTime.makeUnsafe("2024-01-02T00:00:00Z")
  * ```
  *
  * @category math
@@ -1812,20 +1767,18 @@ export const nearest = Internal.nearest;
  *
  * **Example** (Formatting DateTime values with Intl options)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dt = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
  *   timeZone: "Europe/London"
  * })
  *
- * const formatted = DateTime.format(dt, {
+ * DateTime.format(dt, {
  *   dateStyle: "full",
  *   timeStyle: "short",
  *   locale: "en-US"
- * })
- *
- * console.log(formatted) // "Saturday, June 15, 2024 at 3:30 PM"
+ * }) // => "Saturday, June 15, 2024 at 3:30 PM"
  * ```
  *
  * @category formatting
@@ -1838,21 +1791,19 @@ export const format = Internal.format;
  *
  * **Example** (Formatting DateTime values locally)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dt = DateTime.makeUnsafe("2024-06-15T14:30:00Z")
  *
  * // Uses system local time zone and locale
- * const local = DateTime.formatLocal(dt, {
+ * DateTime.formatLocal(dt, {
  *   year: "numeric",
  *   month: "long",
  *   day: "numeric",
  *   hour: "2-digit",
  *   minute: "2-digit"
  * })
- *
- * console.log(local) // Output depends on system locale/timezone
  * ```
  *
  * @category formatting
@@ -1868,7 +1819,7 @@ export const formatLocal = Internal.formatLocal;
  *
  * **Example** (Formatting DateTime values in UTC)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dt = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
@@ -1876,7 +1827,7 @@ export const formatLocal = Internal.formatLocal;
  * })
  *
  * // Force UTC formatting regardless of time zone
- * const utcFormatted = DateTime.formatUtc(dt, {
+ * DateTime.formatUtc(dt, {
  *   year: "numeric",
  *   month: "2-digit",
  *   day: "2-digit",
@@ -1884,8 +1835,6 @@ export const formatLocal = Internal.formatLocal;
  *   minute: "2-digit",
  *   timeZoneName: "short"
  * })
- *
- * console.log(utcFormatted) // "06/15/2024, 02:30 PM UTC"
  * ```
  *
  * @category formatting
@@ -1907,7 +1856,7 @@ export const formatUtc = Internal.formatUtc;
  *
  * **Example** (Formatting DateTime values with custom formatters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dt = DateTime.makeUnsafe("2024-06-15T14:30:00Z")
@@ -1922,8 +1871,7 @@ export const formatUtc = Internal.formatUtc;
  *   timeZone: "Europe/Berlin"
  * })
  *
- * const formatted = DateTime.formatIntl(dt, formatter)
- * console.log(formatted.length > 0) // true
+ * DateTime.formatIntl(dt, formatter).length > 0 // => true
  * ```
  *
  * @see {@link formatUtc} for formatting with options forced to UTC
@@ -1942,16 +1890,15 @@ export const formatIntl = Internal.formatIntl;
  *
  * **Example** (Formatting DateTime values as ISO strings)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
- * const dt = DateTime.makeUnsafe("2024-01-01T12:30:45.123Z")
- * console.log(DateTime.formatIso(dt)) // "2024-01-01T12:30:45.123Z"
+ * DateTime.formatIso(DateTime.makeUnsafe("2024-01-01T12:30:45.123Z")) // => "2024-01-01T12:30:45.123Z"
  *
  * const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:30:45.123Z", {
  *   timeZone: "Europe/London"
  * })
- * console.log(DateTime.formatIso(zoned)) // "2024-01-01T12:30:45.123Z"
+ * DateTime.formatIso(zoned) // => "2024-01-01T12:30:45.123Z"
  * ```
  *
  * @category formatting
@@ -1967,16 +1914,16 @@ export const formatIso = Internal.formatIso;
  *
  * **Example** (Formatting DateTime values as ISO dates)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dt = DateTime.makeUnsafe("2024-01-01T23:30:00Z")
- * console.log(DateTime.formatIsoDate(dt)) // "2024-01-01"
+ * DateTime.formatIsoDate(dt) // => "2024-01-01"
  *
  * const zoned = DateTime.makeZonedUnsafe("2024-01-01T23:30:00Z", {
  *   timeZone: "Pacific/Auckland" // UTC+12/13
  * })
- * console.log(DateTime.formatIsoDate(zoned)) // "2024-01-02" (next day in Auckland)
+ * DateTime.formatIsoDate(zoned) // => "2024-01-02"
  * ```
  *
  * @category formatting
@@ -1992,16 +1939,16 @@ export const formatIsoDate = Internal.formatIsoDate;
  *
  * **Example** (Formatting DateTime values as UTC ISO dates)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const dt = DateTime.makeUnsafe("2024-01-01T23:30:00Z")
- * console.log(DateTime.formatIsoDateUtc(dt)) // "2024-01-01"
+ * DateTime.formatIsoDateUtc(dt) // => "2024-01-01"
  *
  * const zoned = DateTime.makeZonedUnsafe("2024-01-01T23:30:00Z", {
  *   timeZone: "Pacific/Auckland"
  * })
- * console.log(DateTime.formatIsoDateUtc(zoned)) // "2024-01-01" (always UTC)
+ * DateTime.formatIsoDateUtc(zoned) // => "2024-01-01"
  * ```
  *
  * @category formatting
@@ -2018,16 +1965,16 @@ export const formatIsoDateUtc = Internal.formatIsoDateUtc;
  *
  * **Example** (Formatting DateTime values with offsets)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const utc = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
- * console.log(DateTime.formatIsoOffset(utc)) // "2024-01-01T12:00:00.000Z"
+ * DateTime.formatIsoOffset(utc) // => "2024-01-01T12:00:00.000Z"
  *
  * const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
  *   timeZone: DateTime.zoneMakeOffset(3 * 60 * 60 * 1000)
  * })
- * console.log(DateTime.formatIsoOffset(zoned)) // "2024-01-01T15:00:00.000+03:00"
+ * DateTime.formatIsoOffset(zoned) // => "2024-01-01T15:00:00.000+03:00"
  * ```
  *
  * @category formatting
@@ -2043,22 +1990,20 @@ export const formatIsoOffset = Internal.formatIsoOffset;
  *
  * **Example** (Formatting zoned DateTime values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
  * const zoned = DateTime.makeZonedUnsafe("2024-06-15T14:30:45.123Z", {
  *   timeZone: "Europe/London"
  * })
  *
- * const formatted = DateTime.formatIsoZoned(zoned)
- * console.log(formatted) // "2024-06-15T15:30:45.123+01:00[Europe/London]"
+ * DateTime.formatIsoZoned(zoned) // => "2024-06-15T15:30:45.123+01:00[Europe/London]"
  *
  * const offsetZone = DateTime.makeZonedUnsafe("2024-06-15T14:30:45.123Z", {
  *   timeZone: DateTime.zoneMakeOffset(3 * 60 * 60 * 1000)
  * })
  *
- * const offsetFormatted = DateTime.formatIsoZoned(offsetZone)
- * console.log(offsetFormatted) // "2024-06-15T17:30:45.123+03:00"
+ * DateTime.formatIsoZoned(offsetZone) // => "2024-06-15T17:30:45.123+03:00"
  * ```
  *
  * @category formatting
@@ -2074,7 +2019,7 @@ export const formatIsoZoned = Internal.formatIsoZoned;
  *
  * **Example** (Providing current time zone layers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
  *
  * const zone = DateTime.zoneMakeNamedUnsafe("Europe/London")
@@ -2082,14 +2027,14 @@ export const formatIsoZoned = Internal.formatIsoZoned;
  *
  * const program = Effect.gen(function*() {
  *   const now = yield* DateTime.nowInCurrentZone
- *   return DateTime.formatIsoZoned(now)
+ *   return DateTime.zoneToString(now.zone)
  * })
  *
  * // Use the layer to provide the time zone
- * Effect.provide(program, layer)
+ * await Effect.runPromise(Effect.provide(program, layer)) // => "Europe/London"
  * ```
  *
- * @category current time zone
+ * @category layers
  * @since 3.6.0
  */
 export const layerCurrentZone = /*#__PURE__*/Layer.succeed(CurrentTimeZone);
@@ -2102,7 +2047,7 @@ export const layerCurrentZone = /*#__PURE__*/Layer.succeed(CurrentTimeZone);
  *
  * **Example** (Providing fixed-offset time zone layers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
  *
  * // Create a layer for UTC+3
@@ -2110,13 +2055,13 @@ export const layerCurrentZone = /*#__PURE__*/Layer.succeed(CurrentTimeZone);
  *
  * const program = Effect.gen(function*() {
  *   const now = yield* DateTime.nowInCurrentZone
- *   return DateTime.formatIsoZoned(now)
+ *   return DateTime.zoneToString(now.zone)
  * })
  *
- * Effect.provide(program, layer)
+ * await Effect.runPromise(Effect.provide(program, layer)) // => "+03:00"
  * ```
  *
- * @category current time zone
+ * @category layers
  * @since 3.6.0
  */
 export const layerCurrentZoneOffset = offset => Layer.succeed(CurrentTimeZone)(Internal.zoneMakeOffset(offset));
@@ -2130,20 +2075,20 @@ export const layerCurrentZoneOffset = offset => Layer.succeed(CurrentTimeZone)(I
  *
  * **Example** (Providing named time zone layers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
  *
  * const layer = DateTime.layerCurrentZoneNamed("Europe/London")
  *
  * const program = Effect.gen(function*() {
  *   const now = yield* DateTime.nowInCurrentZone
- *   return DateTime.formatIsoZoned(now)
+ *   return DateTime.zoneToString(now.zone)
  * })
  *
- * Effect.provide(program, layer)
+ * await Effect.runPromise(Effect.provide(program, layer)) // => "Europe/London"
  * ```
  *
- * @category current time zone
+ * @category layers
  * @since 3.6.0
  */
 export const layerCurrentZoneNamed = /*#__PURE__*/flow(Internal.zoneMakeNamedEffect, /*#__PURE__*/Layer.effect(CurrentTimeZone));
@@ -2157,19 +2102,19 @@ export const layerCurrentZoneNamed = /*#__PURE__*/flow(Internal.zoneMakeNamedEff
  *
  * **Example** (Providing local time zone layers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const now = yield* DateTime.nowInCurrentZone
- *   return DateTime.formatIsoZoned(now)
+ *   return DateTime.isZoned(now)
  * })
  *
  * // Use the system's local time zone
- * Effect.provide(program, DateTime.layerCurrentZoneLocal)
+ * await Effect.runPromise(Effect.provide(program, DateTime.layerCurrentZoneLocal)) // => true
  * ```
  *
- * @category current time zone
+ * @category layers
  * @since 3.6.0
  */
 export const layerCurrentZoneLocal = /*#__PURE__*/Layer.sync(CurrentTimeZone)(zoneMakeLocal);