effect 3.8.4 → 3.9.0

package/dist/dts/DateTime.d.ts

@@ -215,10 +215,16 @@ export declare const Order: order.Order<DateTime>;
  * @since 3.6.0
  */
 export declare 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;
@@ -365,9 +371,41 @@ export declare const unsafeNow: LazyArg<Utc>;
  * })
  */
 export declare const setZone: {
+    /**
+     * 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;
+    /**
+     * 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;
@@ -390,9 +428,43 @@ export declare const setZone: {
  * })
  */
 export declare const setZoneOffset: {
+    /**
+     * 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;
@@ -474,9 +546,39 @@ export declare const zoneToString: (self: TimeZone) => string;
  * })
  */
 export declare const setZoneNamed: {
+    /**
+     * 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>;
@@ -497,9 +599,39 @@ export declare const setZoneNamed: {
  * })
  */
 export declare const unsafeSetZoneNamed: {
+    /**
+     * 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;
@@ -524,7 +656,45 @@ export declare const unsafeSetZoneNamed: {
  * })
  */
 export declare const distance: {
+    /**
+     * 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;
+    /**
+     * 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;
 };
 /**
@@ -553,7 +723,57 @@ export declare const distance: {
  * })
  */
 export declare 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>;
 };
 /**
@@ -573,7 +793,39 @@ export declare const distanceDurationEither: {
  * })
  */
 export declare 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;
 };
 /**
@@ -581,7 +833,15 @@ export declare const distanceDuration: {
  * @category comparisons
  */
 export declare const min: {
+    /**
+     * @since 3.6.0
+     * @category comparisons
+     */
     (that: DateTime): (self: DateTime) => DateTime;
+    /**
+     * @since 3.6.0
+     * @category comparisons
+     */
     (self: DateTime, that: DateTime): DateTime;
 };
 /**
@@ -589,7 +849,15 @@ export declare const min: {
  * @category comparisons
  */
 export declare const max: {
+    /**
+     * @since 3.6.0
+     * @category comparisons
+     */
     (that: DateTime): (self: DateTime) => DateTime;
+    /**
+     * @since 3.6.0
+     * @category comparisons
+     */
     (self: DateTime, that: DateTime): DateTime;
 };
 /**
@@ -597,7 +865,15 @@ export declare const max: {
  * @category comparisons
  */
 export declare const greaterThan: {
+    /**
+     * @since 3.6.0
+     * @category comparisons
+     */
     (that: DateTime): (self: DateTime) => boolean;
+    /**
+     * @since 3.6.0
+     * @category comparisons
+     */
     (self: DateTime, that: DateTime): boolean;
 };
 /**
@@ -605,7 +881,15 @@ export declare const greaterThan: {
  * @category comparisons
  */
 export declare const greaterThanOrEqualTo: {
+    /**
+     * @since 3.6.0
+     * @category comparisons
+     */
     (that: DateTime): (self: DateTime) => boolean;
+    /**
+     * @since 3.6.0
+     * @category comparisons
+     */
     (self: DateTime, that: DateTime): boolean;
 };
 /**
@@ -613,7 +897,15 @@ export declare const greaterThanOrEqualTo: {
  * @category comparisons
  */
 export declare const lessThan: {
+    /**
+     * @since 3.6.0
+     * @category comparisons
+     */
     (that: DateTime): (self: DateTime) => boolean;
+    /**
+     * @since 3.6.0
+     * @category comparisons
+     */
     (self: DateTime, that: DateTime): boolean;
 };
 /**
@@ -621,7 +913,15 @@ export declare const lessThan: {
  * @category comparisons
  */
 export declare const lessThanOrEqualTo: {
+    /**
+     * @since 3.6.0
+     * @category comparisons
+     */
     (that: DateTime): (self: DateTime) => boolean;
+    /**
+     * @since 3.6.0
+     * @category comparisons
+     */
     (self: DateTime, that: DateTime): boolean;
 };
 /**
@@ -629,10 +929,18 @@ export declare const lessThanOrEqualTo: {
  * @category comparisons
  */
 export declare 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;
@@ -747,7 +1055,35 @@ export declare const toPartsUtc: (self: DateTime) => DateTime.PartsWithWeekday;
  * assert.strictEqual(year, 2024)
  */
 export declare 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;
 };
 /**
@@ -765,7 +1101,35 @@ export declare const getPartUtc: {
  * assert.strictEqual(year, 2024)
  */
 export declare 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;
 };
 /**
@@ -777,7 +1141,23 @@ export declare const getPart: {
  * @category parts
  */
 export declare 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>;
 };
 /**
@@ -787,7 +1167,19 @@ export declare const setParts: {
  * @category parts
  */
 export declare 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>;
 };
 declare const CurrentTimeZone_base: Context.TagClass<CurrentTimeZone, "effect/DateTime/CurrentTimeZone", TimeZone>;
@@ -829,7 +1221,35 @@ export declare const setZoneCurrent: (self: DateTime) => Effect.Effect<Zoned, ne
  * }).pipe(DateTime.withCurrentZone(zone))
  */
 export declare 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>>;
 };
 /**
@@ -861,7 +1281,33 @@ export declare const withCurrentZoneLocal: <A, E, R>(effect: Effect.Effect<A, E,
  * }).pipe(DateTime.withCurrentZoneOffset(3 * 60 * 60 * 1000))
  */
 export declare 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>>;
 };
 /**
@@ -881,7 +1327,39 @@ export declare const withCurrentZoneOffset: {
  * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
  */
 export declare 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): Effect.Effect<A, E | IllegalArgumentException, Exclude<R, CurrentTimeZone>>;
 };
 /**
@@ -936,7 +1414,25 @@ export declare const layerCurrentZoneLocal: Layer.Layer<CurrentTimeZone>;
  * @category mapping
  */
 export declare 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>;
 };
 /**
@@ -946,7 +1442,19 @@ export declare const mutate: {
  * @category mapping
  */
 export declare 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>;
 };
 /**
@@ -964,7 +1472,35 @@ export declare const mutateUtc: {
  * )
  */
 export declare 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>;
 };
 /**
@@ -982,7 +1518,35 @@ export declare const mapEpochMillis: {
  * )
  */
 export declare 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;
 };
 /**
@@ -1000,7 +1564,35 @@ export declare const withDate: {
  * )
  */
 export declare 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;
 };
 /**
@@ -1008,10 +1600,18 @@ export declare const withDateUtc: {
  * @category mapping
  */
 export declare const match: {
+    /**
+     * @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;
@@ -1031,7 +1631,33 @@ export declare const match: {
  * )
  */
 export declare const addDuration: {
+    /**
+     * 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>;
+    /**
+     * 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>;
 };
 /**
@@ -1048,7 +1674,33 @@ export declare const addDuration: {
  * )
  */
 export declare 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>;
 };
 /**
@@ -1068,7 +1720,39 @@ export declare const subtractDuration: {
  * )
  */
 export declare 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>;
 };
 /**
@@ -1085,7 +1769,33 @@ export declare const add: {
  * )
  */
 export declare 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>;
 };
 /**
@@ -1106,9 +1816,43 @@ export declare const subtract: {
  * )
  */
 export declare const startOf: {
+    /**
+     * 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>;
@@ -1131,9 +1875,43 @@ export declare const startOf: {
  * )
  */
 export declare const endOf: {
+    /**
+     * 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>;
@@ -1156,9 +1934,43 @@ export declare const endOf: {
  * )
  */
 export declare const nearest: {
+    /**
+     * 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>;
@@ -1175,9 +1987,31 @@ export declare const nearest: {
  * @category formatting
  */
 export declare 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 & {
         readonly locale?: string | undefined;
     } | 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?: Intl.DateTimeFormatOptions & {
         readonly locale?: string | undefined;
     } | undefined): string;
@@ -1191,9 +2025,25 @@ export declare const format: {
  * @category formatting
  */
 export declare 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 & {
         readonly locale?: string | undefined;
     } | 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?: Intl.DateTimeFormatOptions & {
         readonly locale?: string | undefined;
     } | undefined): string;
@@ -1207,9 +2057,25 @@ export declare const formatLocal: {
  * @category formatting
  */
 export declare 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 & {
         readonly locale?: string | undefined;
     } | 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?: Intl.DateTimeFormatOptions & {
         readonly locale?: string | undefined;
     } | undefined): string;
@@ -1221,7 +2087,19 @@ export declare const formatUtc: {
  * @category formatting
  */
 export declare 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;
 };
 /**