effect 3.8.4 → 3.8.5

package/src/DateTime.ts

@@ -394,7 +394,13 @@ export const Order: order.Order<DateTime> = order.make((self, that) =>
  * @since 3.6.0
  */
 export const clamp: {
+  /**
+   * @since 3.6.0
+   */
   (options: { minimum: DateTime; maximum: DateTime }): (self: DateTime) => DateTime
+  /**
+   * @since 3.6.0
+   */
   (self: DateTime, options: { minimum: DateTime; maximum: DateTime }): DateTime
 } = order.clamp(Order)
 
@@ -611,12 +617,59 @@ export const unsafeNow: LazyArg<Utc> = () => makeUtc(Date.now())
  * })
  */
 export const setZone: {
-  (zone: TimeZone, options?: {
-    readonly adjustForTimeZone?: boolean | undefined
-  }): (self: DateTime) => Zoned
-  (self: DateTime, zone: TimeZone, options?: {
-    readonly adjustForTimeZone?: boolean | undefined
-  }): Zoned
+  // =============================================================================
+  // time zones
+  // =============================================================================
+
+  /**
+   * Set the time zone of a `DateTime`, returning a new `DateTime.Zoned`.
+   *
+   * @since 3.6.0
+   * @category time zones
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.now
+   *   const zone = DateTime.zoneUnsafeMakeNamed("Europe/London")
+   *
+   *   // set the time zone
+   *   const zoned: DateTime.Zoned = DateTime.setZone(now, zone)
+   * })
+   */
+  (
+    zone: TimeZone,
+    options?: {
+      readonly adjustForTimeZone?: boolean | undefined
+    }
+  ): (self: DateTime) => Zoned
+  // =============================================================================
+  // time zones
+  // =============================================================================
+
+  /**
+   * Set the time zone of a `DateTime`, returning a new `DateTime.Zoned`.
+   *
+   * @since 3.6.0
+   * @category time zones
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.now
+   *   const zone = DateTime.zoneUnsafeMakeNamed("Europe/London")
+   *
+   *   // set the time zone
+   *   const zoned: DateTime.Zoned = DateTime.setZone(now, zone)
+   * })
+   */
+  (
+    self: DateTime,
+    zone: TimeZone,
+    options?: {
+      readonly adjustForTimeZone?: boolean | undefined
+    }
+  ): Zoned
 } = dual(isDateTimeArgs, (self: DateTime, zone: TimeZone, options?: {
   readonly adjustForTimeZone?: boolean | undefined
 }): Zoned =>
@@ -642,12 +695,53 @@ export const setZone: {
  * })
  */
 export const setZoneOffset: {
-  (offset: number, options?: {
-    readonly adjustForTimeZone?: boolean | undefined
-  }): (self: DateTime) => Zoned
-  (self: DateTime, offset: number, options?: {
-    readonly adjustForTimeZone?: boolean | undefined
-  }): Zoned
+  /**
+   * Add a fixed offset time zone to a `DateTime`.
+   *
+   * The offset is in milliseconds.
+   *
+   * @since 3.6.0
+   * @category time zones
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.now
+   *
+   *   // set the offset time zone in milliseconds
+   *   const zoned: DateTime.Zoned = DateTime.setZoneOffset(now, 3 * 60 * 60 * 1000)
+   * })
+   */
+  (
+    offset: number,
+    options?: {
+      readonly adjustForTimeZone?: boolean | undefined
+    }
+  ): (self: DateTime) => Zoned
+  /**
+   * Add a fixed offset time zone to a `DateTime`.
+   *
+   * The offset is in milliseconds.
+   *
+   * @since 3.6.0
+   * @category time zones
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.now
+   *
+   *   // set the offset time zone in milliseconds
+   *   const zoned: DateTime.Zoned = DateTime.setZoneOffset(now, 3 * 60 * 60 * 1000)
+   * })
+   */
+  (
+    self: DateTime,
+    offset: number,
+    options?: {
+      readonly adjustForTimeZone?: boolean | undefined
+    }
+  ): Zoned
 } = dual(isDateTimeArgs, (self: DateTime, offset: number, options?: {
   readonly adjustForTimeZone?: boolean | undefined
 }): Zoned => setZone(self, zoneMakeOffset(offset), options))
@@ -799,12 +893,49 @@ export const zoneToString = (self: TimeZone): string => {
  * })
  */
 export const setZoneNamed: {
-  (zoneId: string, options?: {
-    readonly adjustForTimeZone?: boolean | undefined
-  }): (self: DateTime) => Option.Option<Zoned>
-  (self: DateTime, zoneId: string, options?: {
-    readonly adjustForTimeZone?: boolean | undefined
-  }): Option.Option<Zoned>
+  /**
+   * 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
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.now
+   *   // set the time zone, returns an Option
+   *   DateTime.setZoneNamed(now, "Europe/London")
+   * })
+   */
+  (
+    zoneId: string,
+    options?: {
+      readonly adjustForTimeZone?: boolean | undefined
+    }
+  ): (self: DateTime) => Option.Option<Zoned>
+  /**
+   * 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
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.now
+   *   // set the time zone, returns an Option
+   *   DateTime.setZoneNamed(now, "Europe/London")
+   * })
+   */
+  (
+    self: DateTime,
+    zoneId: string,
+    options?: {
+      readonly adjustForTimeZone?: boolean | undefined
+    }
+  ): Option.Option<Zoned>
 } = dual(
   isDateTimeArgs,
   (self: DateTime, zoneId: string, options?: {
@@ -828,12 +959,49 @@ export const setZoneNamed: {
  * })
  */
 export const unsafeSetZoneNamed: {
-  (zoneId: string, options?: {
-    readonly adjustForTimeZone?: boolean | undefined
-  }): (self: DateTime) => Zoned
-  (self: DateTime, zoneId: string, options?: {
-    readonly adjustForTimeZone?: boolean | undefined
-  }): Zoned
+  /**
+   * Set the time zone of a `DateTime` from an IANA time zone identifier. If the
+   * time zone is invalid, an `IllegalArgumentException` will be thrown.
+   *
+   * @since 3.6.0
+   * @category time zones
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.now
+   *   // set the time zone
+   *   DateTime.unsafeSetZoneNamed(now, "Europe/London")
+   * })
+   */
+  (
+    zoneId: string,
+    options?: {
+      readonly adjustForTimeZone?: boolean | undefined
+    }
+  ): (self: DateTime) => Zoned
+  /**
+   * Set the time zone of a `DateTime` from an IANA time zone identifier. If the
+   * time zone is invalid, an `IllegalArgumentException` will be thrown.
+   *
+   * @since 3.6.0
+   * @category time zones
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.now
+   *   // set the time zone
+   *   DateTime.unsafeSetZoneNamed(now, "Europe/London")
+   * })
+   */
+  (
+    self: DateTime,
+    zoneId: string,
+    options?: {
+      readonly adjustForTimeZone?: boolean | undefined
+    }
+  ): Zoned
 } = dual(isDateTimeArgs, (self: DateTime, zoneId: string, options?: {
   readonly adjustForTimeZone?: boolean | undefined
 }): Zoned => setZone(self, zoneUnsafeMakeNamed(zoneId), options))
@@ -862,7 +1030,53 @@ export const unsafeSetZoneNamed: {
  * })
  */
 export const distance: {
+  // =============================================================================
+  // comparisons
+  // =============================================================================
+
+  /**
+   * Calulate the difference between two `DateTime` values, returning the number
+   * of milliseconds the `other` DateTime is from `self`.
+   *
+   * If `other` is *after* `self`, the result will be a positive number.
+   *
+   * @since 3.6.0
+   * @category comparisons
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.now
+   *   const other = DateTime.add(now, { minutes: 1 })
+   *
+   *   // returns 60000
+   *   DateTime.distance(now, other)
+   * })
+   */
   (other: DateTime): (self: DateTime) => number
+  // =============================================================================
+  // comparisons
+  // =============================================================================
+
+  /**
+   * Calulate the difference between two `DateTime` values, returning the number
+   * of milliseconds the `other` DateTime is from `self`.
+   *
+   * If `other` is *after* `self`, the result will be a positive number.
+   *
+   * @since 3.6.0
+   * @category comparisons
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.now
+   *   const other = DateTime.add(now, { minutes: 1 })
+   *
+   *   // returns 60000
+   *   DateTime.distance(now, other)
+   * })
+   */
   (self: DateTime, other: DateTime): number
 } = dual(2, (self: DateTime, other: DateTime): number => toEpochMillis(other) - toEpochMillis(self))
 
@@ -892,7 +1106,57 @@ export const distance: {
  * })
  */
 export const distanceDurationEither: {
+  /**
+   * Calulate the difference between two `DateTime` values.
+   *
+   * If the `other` DateTime is before `self`, the result will be a negative
+   * `Duration`, returned as a `Left`.
+   *
+   * If the `other` DateTime is after `self`, the result will be a positive
+   * `Duration`, returned as a `Right`.
+   *
+   * @since 3.6.0
+   * @category comparisons
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.now
+   *   const other = DateTime.add(now, { minutes: 1 })
+   *
+   *   // returns Either.right(Duration.minutes(1))
+   *   DateTime.distanceDurationEither(now, other)
+   *
+   *   // returns Either.left(Duration.minutes(1))
+   *   DateTime.distanceDurationEither(other, now)
+   * })
+   */
   (other: DateTime): (self: DateTime) => Either.Either<Duration.Duration, Duration.Duration>
+  /**
+   * Calulate the difference between two `DateTime` values.
+   *
+   * If the `other` DateTime is before `self`, the result will be a negative
+   * `Duration`, returned as a `Left`.
+   *
+   * If the `other` DateTime is after `self`, the result will be a positive
+   * `Duration`, returned as a `Right`.
+   *
+   * @since 3.6.0
+   * @category comparisons
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.now
+   *   const other = DateTime.add(now, { minutes: 1 })
+   *
+   *   // returns Either.right(Duration.minutes(1))
+   *   DateTime.distanceDurationEither(now, other)
+   *
+   *   // returns Either.left(Duration.minutes(1))
+   *   DateTime.distanceDurationEither(other, now)
+   * })
+   */
   (self: DateTime, other: DateTime): Either.Either<Duration.Duration, Duration.Duration>
 } = dual(2, (self: DateTime, other: DateTime): Either.Either<Duration.Duration, Duration.Duration> => {
   const diffMillis = distance(self, other)
@@ -918,7 +1182,39 @@ export const distanceDurationEither: {
  * })
  */
 export const distanceDuration: {
+  /**
+   * Calulate the distance between two `DateTime` values.
+   *
+   * @since 3.6.0
+   * @category comparisons
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.now
+   *   const other = DateTime.add(now, { minutes: 1 })
+   *
+   *   // returns Duration.minutes(1)
+   *   DateTime.distanceDuration(now, other)
+   * })
+   */
   (other: DateTime): (self: DateTime) => Duration.Duration
+  /**
+   * Calulate the distance between two `DateTime` values.
+   *
+   * @since 3.6.0
+   * @category comparisons
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.now
+   *   const other = DateTime.add(now, { minutes: 1 })
+   *
+   *   // returns Duration.minutes(1)
+   *   DateTime.distanceDuration(now, other)
+   * })
+   */
   (self: DateTime, other: DateTime): Duration.Duration
 } = dual(
   2,
@@ -930,7 +1226,15 @@ export const distanceDuration: {
  * @category comparisons
  */
 export const min: {
+  /**
+   * @since 3.6.0
+   * @category comparisons
+   */
   (that: DateTime): (self: DateTime) => DateTime
+  /**
+   * @since 3.6.0
+   * @category comparisons
+   */
   (self: DateTime, that: DateTime): DateTime
 } = order.min(Order)
 
@@ -939,7 +1243,15 @@ export const min: {
  * @category comparisons
  */
 export const max: {
+  /**
+   * @since 3.6.0
+   * @category comparisons
+   */
   (that: DateTime): (self: DateTime) => DateTime
+  /**
+   * @since 3.6.0
+   * @category comparisons
+   */
   (self: DateTime, that: DateTime): DateTime
 } = order.max(Order)
 
@@ -948,7 +1260,15 @@ export const max: {
  * @category comparisons
  */
 export const greaterThan: {
+  /**
+   * @since 3.6.0
+   * @category comparisons
+   */
   (that: DateTime): (self: DateTime) => boolean
+  /**
+   * @since 3.6.0
+   * @category comparisons
+   */
   (self: DateTime, that: DateTime): boolean
 } = order.greaterThan(Order)
 
@@ -957,7 +1277,15 @@ export const greaterThan: {
  * @category comparisons
  */
 export const greaterThanOrEqualTo: {
+  /**
+   * @since 3.6.0
+   * @category comparisons
+   */
   (that: DateTime): (self: DateTime) => boolean
+  /**
+   * @since 3.6.0
+   * @category comparisons
+   */
   (self: DateTime, that: DateTime): boolean
 } = order.greaterThanOrEqualTo(Order)
 
@@ -966,7 +1294,15 @@ export const greaterThanOrEqualTo: {
  * @category comparisons
  */
 export const lessThan: {
+  /**
+   * @since 3.6.0
+   * @category comparisons
+   */
   (that: DateTime): (self: DateTime) => boolean
+  /**
+   * @since 3.6.0
+   * @category comparisons
+   */
   (self: DateTime, that: DateTime): boolean
 } = order.lessThan(Order)
 
@@ -975,7 +1311,15 @@ export const lessThan: {
  * @category comparisons
  */
 export const lessThanOrEqualTo: {
+  /**
+   * @since 3.6.0
+   * @category comparisons
+   */
   (that: DateTime): (self: DateTime) => boolean
+  /**
+   * @since 3.6.0
+   * @category comparisons
+   */
   (self: DateTime, that: DateTime): boolean
 } = order.lessThanOrEqualTo(Order)
 
@@ -984,7 +1328,15 @@ export const lessThanOrEqualTo: {
  * @category comparisons
  */
 export const between: {
+  /**
+   * @since 3.6.0
+   * @category comparisons
+   */
   (options: { minimum: DateTime; maximum: DateTime }): (self: DateTime) => boolean
+  /**
+   * @since 3.6.0
+   * @category comparisons
+   */
   (self: DateTime, options: { minimum: DateTime; maximum: DateTime }): boolean
 } = order.between(Order)
 
@@ -1179,7 +1531,35 @@ export const toPartsUtc = (self: DateTime): DateTime.PartsWithWeekday => {
  * assert.strictEqual(year, 2024)
  */
 export const getPartUtc: {
+  /**
+   * Get a part of a `DateTime` as a number.
+   *
+   * The part will be in the UTC time zone.
+   *
+   * @since 3.6.0
+   * @category parts
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * const now = DateTime.unsafeMake({ year: 2024 })
+   * const year = DateTime.getPartUtc(now, "year")
+   * assert.strictEqual(year, 2024)
+   */
   (part: keyof DateTime.PartsWithWeekday): (self: DateTime) => number
+  /**
+   * Get a part of a `DateTime` as a number.
+   *
+   * The part will be in the UTC time zone.
+   *
+   * @since 3.6.0
+   * @category parts
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * const now = DateTime.unsafeMake({ year: 2024 })
+   * const year = DateTime.getPartUtc(now, "year")
+   * assert.strictEqual(year, 2024)
+   */
   (self: DateTime, part: keyof DateTime.PartsWithWeekday): number
 } = dual(2, (self: DateTime, part: keyof DateTime.PartsWithWeekday): number => toPartsUtc(self)[part])
 
@@ -1198,7 +1578,35 @@ export const getPartUtc: {
  * assert.strictEqual(year, 2024)
  */
 export const getPart: {
+  /**
+   * Get a part of a `DateTime` as a number.
+   *
+   * The part will be time zone adjusted.
+   *
+   * @since 3.6.0
+   * @category parts
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * const now = DateTime.unsafeMakeZoned({ year: 2024 }, { timeZone: "Europe/London" })
+   * const year = DateTime.getPart(now, "year")
+   * assert.strictEqual(year, 2024)
+   */
   (part: keyof DateTime.PartsWithWeekday): (self: DateTime) => number
+  /**
+   * Get a part of a `DateTime` as a number.
+   *
+   * The part will be time zone adjusted.
+   *
+   * @since 3.6.0
+   * @category parts
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * const now = DateTime.unsafeMakeZoned({ year: 2024 }, { timeZone: "Europe/London" })
+   * const year = DateTime.getPart(now, "year")
+   * assert.strictEqual(year, 2024)
+   */
   (self: DateTime, part: keyof DateTime.PartsWithWeekday): number
 } = dual(2, (self: DateTime, part: keyof DateTime.PartsWithWeekday): number => toParts(self)[part])
 
@@ -1239,7 +1647,23 @@ const setPartsDate = (date: Date, parts: Partial<DateTime.PartsWithWeekday>): vo
  * @category parts
  */
 export const setParts: {
+  /**
+   * Set the different parts of a `DateTime` as an object.
+   *
+   * The Date will be time zone adjusted.
+   *
+   * @since 3.6.0
+   * @category parts
+   */
   (parts: Partial<DateTime.PartsWithWeekday>): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
+  /**
+   * Set the different parts of a `DateTime` as an object.
+   *
+   * The Date will be time zone adjusted.
+   *
+   * @since 3.6.0
+   * @category parts
+   */
   <A extends DateTime>(self: A, parts: Partial<DateTime.PartsWithWeekday>): DateTime.PreserveZone<A>
 } = dual(
   2,
@@ -1254,7 +1678,19 @@ export const setParts: {
  * @category parts
  */
 export const setPartsUtc: {
+  /**
+   * Set the different parts of a `DateTime` as an object.
+   *
+   * @since 3.6.0
+   * @category parts
+   */
   (parts: Partial<DateTime.PartsWithWeekday>): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
+  /**
+   * Set the different parts of a `DateTime` as an object.
+   *
+   * @since 3.6.0
+   * @category parts
+   */
   <A extends DateTime>(self: A, parts: Partial<DateTime.PartsWithWeekday>): DateTime.PreserveZone<A>
 } = dual(
   2,
@@ -1309,7 +1745,35 @@ export const setZoneCurrent = (self: DateTime): Effect.Effect<Zoned, never, Curr
  * }).pipe(DateTime.withCurrentZone(zone))
  */
 export const withCurrentZone: {
+  /**
+   * Provide the `CurrentTimeZone` to an effect.
+   *
+   * @since 3.6.0
+   * @category current time zone
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * const zone = DateTime.zoneUnsafeMakeNamed("Europe/London")
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.nowInCurrentZone
+   * }).pipe(DateTime.withCurrentZone(zone))
+   */
   (zone: TimeZone): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, CurrentTimeZone>>
+  /**
+   * Provide the `CurrentTimeZone` to an effect.
+   *
+   * @since 3.6.0
+   * @category current time zone
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * const zone = DateTime.zoneUnsafeMakeNamed("Europe/London")
+   *
+   * Effect.gen(function* () {
+   *   const now = yield* DateTime.nowInCurrentZone
+   * }).pipe(DateTime.withCurrentZone(zone))
+   */
   <A, E, R>(effect: Effect.Effect<A, E, R>, zone: TimeZone): Effect.Effect<A, E, Exclude<R, CurrentTimeZone>>
 } = dual(
   2,
@@ -1350,9 +1814,35 @@ export const withCurrentZoneLocal = <A, E, R>(
  * }).pipe(DateTime.withCurrentZoneOffset(3 * 60 * 60 * 1000))
  */
 export const withCurrentZoneOffset: {
+  /**
+   * Provide the `CurrentTimeZone` to an effect, using a offset.
+   *
+   * @since 3.6.0
+   * @category current time zone
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   // will use the system's local time zone
+   *   const now = yield* DateTime.nowInCurrentZone
+   * }).pipe(DateTime.withCurrentZoneOffset(3 * 60 * 60 * 1000))
+   */
   (offset: number): <A, E, R>(
     effect: Effect.Effect<A, E, R>
   ) => Effect.Effect<A, E, Exclude<R, CurrentTimeZone>>
+  /**
+   * Provide the `CurrentTimeZone` to an effect, using a offset.
+   *
+   * @since 3.6.0
+   * @category current time zone
+   * @example
+   * import { DateTime, Effect } from "effect"
+   *
+   * Effect.gen(function* () {
+   *   // will use the system's local time zone
+   *   const now = yield* DateTime.nowInCurrentZone
+   * }).pipe(DateTime.withCurrentZoneOffset(3 * 60 * 60 * 1000))
+   */
   <A, E, R>(effect: Effect.Effect<A, E, R>, offset: number): Effect.Effect<A, E, Exclude<R, CurrentTimeZone>>
 } = dual(
   2,
@@ -1377,9 +1867,41 @@ export const withCurrentZoneOffset: {
  * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
  */
 export const withCurrentZoneNamed: {
+  /**
+   * Provide the `CurrentTimeZone` to an effect using an IANA time zone
+   * identifier.
+   *
+   * If the time zone is invalid, it will fail with an `IllegalArgumentException`.
+   *
+   * @since 3.6.0
+   * @category current time zone
+   * @example
+   * 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"))
+   */
   (zone: string): <A, E, R>(
     effect: Effect.Effect<A, E, R>
   ) => Effect.Effect<A, E | IllegalArgumentException, Exclude<R, CurrentTimeZone>>
+  /**
+   * Provide the `CurrentTimeZone` to an effect using an IANA time zone
+   * identifier.
+   *
+   * If the time zone is invalid, it will fail with an `IllegalArgumentException`.
+   *
+   * @since 3.6.0
+   * @category current time zone
+   * @example
+   * 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"))
+   */
   <A, E, R>(
     effect: Effect.Effect<A, E, R>,
     zone: string
@@ -1490,7 +2012,25 @@ const calculateNamedOffset = (adjustedMillis: number, zone: TimeZone.Named): num
  * @category mapping
  */
 export const mutate: {
+  /**
+   * Modify a `DateTime` by applying a function to a cloned `Date` instance.
+   *
+   * The `Date` will first have the time zone applied if possible, and then be
+   * converted back to a `DateTime` within the same time zone.
+   *
+   * @since 3.6.0
+   * @category mapping
+   */
   (f: (date: Date) => void): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
+  /**
+   * Modify a `DateTime` by applying a function to a cloned `Date` instance.
+   *
+   * The `Date` will first have the time zone applied if possible, and then be
+   * converted back to a `DateTime` within the same time zone.
+   *
+   * @since 3.6.0
+   * @category mapping
+   */
   <A extends DateTime>(self: A, f: (date: Date) => void): DateTime.PreserveZone<A>
 } = dual(2, (self: DateTime, f: (date: Date) => void): DateTime => {
   if (self._tag === "Utc") {
@@ -1511,7 +2051,19 @@ export const mutate: {
  * @category mapping
  */
 export const mutateUtc: {
+  /**
+   * Modify a `DateTime` by applying a function to a cloned UTC `Date` instance.
+   *
+   * @since 3.6.0
+   * @category mapping
+   */
   (f: (date: Date) => void): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
+  /**
+   * Modify a `DateTime` by applying a function to a cloned UTC `Date` instance.
+   *
+   * @since 3.6.0
+   * @category mapping
+   */
   <A extends DateTime>(self: A, f: (date: Date) => void): DateTime.PreserveZone<A>
 } = dual(2, (self: DateTime, f: (date: Date) => void): DateTime =>
   mapEpochMillis(self, (millis) => {
@@ -1535,7 +2087,35 @@ export const mutateUtc: {
  * )
  */
 export const mapEpochMillis: {
+  /**
+   * Transform a `DateTime` by applying a function to the number of milliseconds
+   * since the Unix epoch.
+   *
+   * @since 3.6.0
+   * @category mapping
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * // add 10 milliseconds
+   * DateTime.unsafeMake(0).pipe(
+   *   DateTime.mapEpochMillis((millis) => millis + 10)
+   * )
+   */
   (f: (millis: number) => number): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
+  /**
+   * Transform a `DateTime` by applying a function to the number of milliseconds
+   * since the Unix epoch.
+   *
+   * @since 3.6.0
+   * @category mapping
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * // add 10 milliseconds
+   * DateTime.unsafeMake(0).pipe(
+   *   DateTime.mapEpochMillis((millis) => millis + 10)
+   * )
+   */
   <A extends DateTime>(self: A, f: (millis: number) => number): DateTime.PreserveZone<A>
 } = dual(2, (self: DateTime, f: (millis: number) => number): DateTime => {
   const millis = f(toEpochMillis(self))
@@ -1557,7 +2137,35 @@ export const mapEpochMillis: {
  * )
  */
 export const withDate: {
+  /**
+   * Using the time zone adjusted `Date`, apply a function to the `Date` and
+   * return the result.
+   *
+   * @since 3.6.0
+   * @category mapping
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * // get the time zone adjusted date in milliseconds
+   * DateTime.unsafeMakeZoned(0, { timeZone: "Europe/London" }).pipe(
+   *   DateTime.withDate((date) => date.getTime())
+   * )
+   */
   <A>(f: (date: Date) => A): (self: DateTime) => A
+  /**
+   * Using the time zone adjusted `Date`, apply a function to the `Date` and
+   * return the result.
+   *
+   * @since 3.6.0
+   * @category mapping
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * // get the time zone adjusted date in milliseconds
+   * DateTime.unsafeMakeZoned(0, { timeZone: "Europe/London" }).pipe(
+   *   DateTime.withDate((date) => date.getTime())
+   * )
+   */
   <A>(self: DateTime, f: (date: Date) => A): A
 } = dual(2, <A>(self: DateTime, f: (date: Date) => A): A => f(toDate(self)))
 
@@ -1576,7 +2184,35 @@ export const withDate: {
  * )
  */
 export const withDateUtc: {
+  /**
+   * Using the time zone adjusted `Date`, apply a function to the `Date` and
+   * return the result.
+   *
+   * @since 3.6.0
+   * @category mapping
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * // get the date in milliseconds
+   * DateTime.unsafeMake(0).pipe(
+   *   DateTime.withDateUtc((date) => date.getTime())
+   * )
+   */
   <A>(f: (date: Date) => A): (self: DateTime) => A
+  /**
+   * Using the time zone adjusted `Date`, apply a function to the `Date` and
+   * return the result.
+   *
+   * @since 3.6.0
+   * @category mapping
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * // get the date in milliseconds
+   * DateTime.unsafeMake(0).pipe(
+   *   DateTime.withDateUtc((date) => date.getTime())
+   * )
+   */
   <A>(self: DateTime, f: (date: Date) => A): A
 } = dual(2, <A>(self: DateTime, f: (date: Date) => A): A => f(toDateUtc(self)))
 
@@ -1585,14 +2221,27 @@ export const withDateUtc: {
  * @category mapping
  */
 export const match: {
-  <A, B>(options: {
-    readonly onUtc: (_: Utc) => A
-    readonly onZoned: (_: Zoned) => B
-  }): (self: DateTime) => A | B
-  <A, B>(self: DateTime, options: {
-    readonly onUtc: (_: Utc) => A
-    readonly onZoned: (_: Zoned) => B
-  }): A | B
+  /**
+   * @since 3.6.0
+   * @category mapping
+   */
+  <A, B>(
+    options: {
+      readonly onUtc: (_: Utc) => A
+      readonly onZoned: (_: Zoned) => B
+    }
+  ): (self: DateTime) => A | B
+  /**
+   * @since 3.6.0
+   * @category mapping
+   */
+  <A, B>(
+    self: DateTime,
+    options: {
+      readonly onUtc: (_: Utc) => A
+      readonly onZoned: (_: Zoned) => B
+    }
+  ): A | B
 } = dual(2, <A, B>(self: DateTime, options: {
   readonly onUtc: (_: Utc) => A
   readonly onZoned: (_: Zoned) => B
@@ -1616,7 +2265,41 @@ export const match: {
  * )
  */
 export const addDuration: {
+  // =============================================================================
+  // math
+  // =============================================================================
+
+  /**
+   * Add the given `Duration` to a `DateTime`.
+   *
+   * @since 3.6.0
+   * @category math
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * // add 5 minutes
+   * DateTime.unsafeMake(0).pipe(
+   *   DateTime.addDuration("5 minutes")
+   * )
+   */
   (duration: Duration.DurationInput): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
+  // =============================================================================
+  // math
+  // =============================================================================
+
+  /**
+   * Add the given `Duration` to a `DateTime`.
+   *
+   * @since 3.6.0
+   * @category math
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * // add 5 minutes
+   * DateTime.unsafeMake(0).pipe(
+   *   DateTime.addDuration("5 minutes")
+   * )
+   */
   <A extends DateTime>(self: A, duration: Duration.DurationInput): DateTime.PreserveZone<A>
 } = dual(
   2,
@@ -1638,7 +2321,33 @@ export const addDuration: {
  * )
  */
 export const subtractDuration: {
+  /**
+   * Subtract the given `Duration` from a `DateTime`.
+   *
+   * @since 3.6.0
+   * @category math
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * // subtract 5 minutes
+   * DateTime.unsafeMake(0).pipe(
+   *   DateTime.subtractDuration("5 minutes")
+   * )
+   */
   (duration: Duration.DurationInput): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
+  /**
+   * Subtract the given `Duration` from a `DateTime`.
+   *
+   * @since 3.6.0
+   * @category math
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * // subtract 5 minutes
+   * DateTime.unsafeMake(0).pipe(
+   *   DateTime.subtractDuration("5 minutes")
+   * )
+   */
   <A extends DateTime>(self: A, duration: Duration.DurationInput): DateTime.PreserveZone<A>
 } = dual(
   2,
@@ -1667,7 +2376,39 @@ const addMillis = (date: Date, amount: number): void => {
  * )
  */
 export const add: {
+  /**
+   * Add the given `amount` of `unit`'s to a `DateTime`.
+   *
+   * The time zone is taken into account when adding days, weeks, months, and
+   * years.
+   *
+   * @since 3.6.0
+   * @category math
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * // add 5 minutes
+   * DateTime.unsafeMake(0).pipe(
+   *   DateTime.add({ minutes: 5 })
+   * )
+   */
   (parts: Partial<DateTime.PartsForMath>): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
+  /**
+   * Add the given `amount` of `unit`'s to a `DateTime`.
+   *
+   * The time zone is taken into account when adding days, weeks, months, and
+   * years.
+   *
+   * @since 3.6.0
+   * @category math
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * // add 5 minutes
+   * DateTime.unsafeMake(0).pipe(
+   *   DateTime.add({ minutes: 5 })
+   * )
+   */
   <A extends DateTime>(self: A, parts: Partial<DateTime.PartsForMath>): DateTime.PreserveZone<A>
 } = dual(2, (self: DateTime, parts: Partial<DateTime.PartsForMath>): DateTime =>
   mutate(self, (date) => {
@@ -1724,7 +2465,33 @@ export const add: {
  * )
  */
 export const subtract: {
+  /**
+   * Subtract the given `amount` of `unit`'s from a `DateTime`.
+   *
+   * @since 3.6.0
+   * @category math
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * // subtract 5 minutes
+   * DateTime.unsafeMake(0).pipe(
+   *   DateTime.subtract({ minutes: 5 })
+   * )
+   */
   (parts: Partial<DateTime.PartsForMath>): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
+  /**
+   * Subtract the given `amount` of `unit`'s from a `DateTime`.
+   *
+   * @since 3.6.0
+   * @category math
+   * @example
+   * import { DateTime } from "effect"
+   *
+   * // subtract 5 minutes
+   * DateTime.unsafeMake(0).pipe(
+   *   DateTime.subtract({ minutes: 5 })
+   * )
+   */
   <A extends DateTime>(self: A, parts: Partial<DateTime.PartsForMath>): DateTime.PreserveZone<A>
 } = dual(2, (self: DateTime, parts: Partial<DateTime.PartsForMath>): DateTime => {
   const newParts = {} as Partial<Mutable<DateTime.PartsForMath>>
@@ -1793,12 +2560,53 @@ function startOfDate(date: Date, part: DateTime.UnitSingular, options?: {
  * )
  */
 export const startOf: {
-  (part: DateTime.UnitSingular, options?: {
-    readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
-  }): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
-  <A extends DateTime>(self: A, part: DateTime.UnitSingular, options?: {
-    readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
-  }): DateTime.PreserveZone<A>
+  /**
+   * Converts a `DateTime` to the start of the given `part`.
+   *
+   * 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
+   * import { DateTime } from "effect"
+   *
+   * // returns "2024-01-01T00:00:00Z"
+   * DateTime.unsafeMake("2024-01-01T12:00:00Z").pipe(
+   *   DateTime.startOf("day"),
+   *   DateTime.formatIso
+   * )
+   */
+  (
+    part: DateTime.UnitSingular,
+    options?: {
+      readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
+    }
+  ): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
+  /**
+   * Converts a `DateTime` to the start of the given `part`.
+   *
+   * 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
+   * import { DateTime } from "effect"
+   *
+   * // returns "2024-01-01T00:00:00Z"
+   * DateTime.unsafeMake("2024-01-01T12:00:00Z").pipe(
+   *   DateTime.startOf("day"),
+   *   DateTime.formatIso
+   * )
+   */
+  <A extends DateTime>(
+    self: A,
+    part: DateTime.UnitSingular,
+    options?: {
+      readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
+    }
+  ): DateTime.PreserveZone<A>
 } = dual(isDateTimeArgs, (self: DateTime, part: DateTime.UnitSingular, options?: {
   readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
 }): DateTime => mutate(self, (date) => startOfDate(date, part, options)))
@@ -1862,12 +2670,53 @@ function endOfDate(date: Date, part: DateTime.UnitSingular, options?: {
  * )
  */
 export const endOf: {
-  (part: DateTime.UnitSingular, options?: {
-    readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
-  }): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
-  <A extends DateTime>(self: A, part: DateTime.UnitSingular, options?: {
-    readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
-  }): DateTime.PreserveZone<A>
+  /**
+   * Converts a `DateTime` to the end of the given `part`.
+   *
+   * 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
+   * import { DateTime } from "effect"
+   *
+   * // returns "2024-01-01T23:59:59.999Z"
+   * DateTime.unsafeMake("2024-01-01T12:00:00Z").pipe(
+   *   DateTime.endOf("day"),
+   *   DateTime.formatIso
+   * )
+   */
+  (
+    part: DateTime.UnitSingular,
+    options?: {
+      readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
+    }
+  ): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
+  /**
+   * Converts a `DateTime` to the end of the given `part`.
+   *
+   * 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
+   * import { DateTime } from "effect"
+   *
+   * // returns "2024-01-01T23:59:59.999Z"
+   * DateTime.unsafeMake("2024-01-01T12:00:00Z").pipe(
+   *   DateTime.endOf("day"),
+   *   DateTime.formatIso
+   * )
+   */
+  <A extends DateTime>(
+    self: A,
+    part: DateTime.UnitSingular,
+    options?: {
+      readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
+    }
+  ): DateTime.PreserveZone<A>
 } = dual(isDateTimeArgs, (self: DateTime, part: DateTime.UnitSingular, options?: {
   readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
 }): DateTime => mutate(self, (date) => endOfDate(date, part, options)))
@@ -1890,12 +2739,53 @@ export const endOf: {
  * )
  */
 export const nearest: {
-  (part: DateTime.UnitSingular, options?: {
-    readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
-  }): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
-  <A extends DateTime>(self: A, part: DateTime.UnitSingular, options?: {
-    readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
-  }): DateTime.PreserveZone<A>
+  /**
+   * Converts a `DateTime` to the nearest given `part`.
+   *
+   * 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
+   * import { DateTime } from "effect"
+   *
+   * // returns "2024-01-02T00:00:00Z"
+   * DateTime.unsafeMake("2024-01-01T12:01:00Z").pipe(
+   *   DateTime.nearest("day"),
+   *   DateTime.formatIso
+   * )
+   */
+  (
+    part: DateTime.UnitSingular,
+    options?: {
+      readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
+    }
+  ): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
+  /**
+   * Converts a `DateTime` to the nearest given `part`.
+   *
+   * 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
+   * import { DateTime } from "effect"
+   *
+   * // returns "2024-01-02T00:00:00Z"
+   * DateTime.unsafeMake("2024-01-01T12:01:00Z").pipe(
+   *   DateTime.nearest("day"),
+   *   DateTime.formatIso
+   * )
+   */
+  <A extends DateTime>(
+    self: A,
+    part: DateTime.UnitSingular,
+    options?: {
+      readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
+    }
+  ): DateTime.PreserveZone<A>
 } = dual(isDateTimeArgs, (self: DateTime, part: DateTime.UnitSingular, options?: {
   readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
 }): DateTime =>
@@ -1940,6 +2830,17 @@ const intlTimeZone = (self: TimeZone): string => {
  * @category formatting
  */
 export const format: {
+  /**
+   * Format a `DateTime` as a string using the `DateTimeFormat` API.
+   *
+   * The `timeZone` option is set to the offset of the time zone.
+   *
+   * Note: On Node versions < 22, fixed "Offset" zones will set the time zone to
+   * "UTC" and use the adjusted `Date`.
+   *
+   * @since 3.6.0
+   * @category formatting
+   */
   (
     options?:
       | Intl.DateTimeFormatOptions & {
@@ -1947,6 +2848,17 @@ export const format: {
       }
       | undefined
   ): (self: DateTime) => string
+  /**
+   * Format a `DateTime` as a string using the `DateTimeFormat` API.
+   *
+   * The `timeZone` option is set to the offset of the time zone.
+   *
+   * Note: On Node versions < 22, fixed "Offset" zones will set the time zone to
+   * "UTC" and use the adjusted `Date`.
+   *
+   * @since 3.6.0
+   * @category formatting
+   */
   (
     self: DateTime,
     options?:
@@ -1985,6 +2897,14 @@ export const format: {
  * @category formatting
  */
 export const formatLocal: {
+  /**
+   * Format a `DateTime` as a string using the `DateTimeFormat` API.
+   *
+   * It will use the system's local time zone & locale.
+   *
+   * @since 3.6.0
+   * @category formatting
+   */
   (
     options?:
       | Intl.DateTimeFormatOptions & {
@@ -1992,6 +2912,14 @@ export const formatLocal: {
       }
       | undefined
   ): (self: DateTime) => string
+  /**
+   * Format a `DateTime` as a string using the `DateTimeFormat` API.
+   *
+   * It will use the system's local time zone & locale.
+   *
+   * @since 3.6.0
+   * @category formatting
+   */
   (
     self: DateTime,
     options?:
@@ -2018,6 +2946,14 @@ export const formatLocal: {
  * @category formatting
  */
 export const formatUtc: {
+  /**
+   * Format a `DateTime` as a string using the `DateTimeFormat` API.
+   *
+   * This forces the time zone to be UTC.
+   *
+   * @since 3.6.0
+   * @category formatting
+   */
   (
     options?:
       | Intl.DateTimeFormatOptions & {
@@ -2025,6 +2961,14 @@ export const formatUtc: {
       }
       | undefined
   ): (self: DateTime) => string
+  /**
+   * Format a `DateTime` as a string using the `DateTimeFormat` API.
+   *
+   * This forces the time zone to be UTC.
+   *
+   * @since 3.6.0
+   * @category formatting
+   */
   (
     self: DateTime,
     options?:
@@ -2053,7 +2997,19 @@ export const formatUtc: {
  * @category formatting
  */
 export const formatIntl: {
+  /**
+   * Format a `DateTime` as a string using the `DateTimeFormat` API.
+   *
+   * @since 3.6.0
+   * @category formatting
+   */
   (format: Intl.DateTimeFormat): (self: DateTime) => string
+  /**
+   * Format a `DateTime` as a string using the `DateTimeFormat` API.
+   *
+   * @since 3.6.0
+   * @category formatting
+   */
   (self: DateTime, format: Intl.DateTimeFormat): string
 } = dual(2, (self: DateTime, format: Intl.DateTimeFormat): string => format.format(self.epochMillis))