effect 4.0.0-beta.3 → 4.0.0-beta.31

package/src/DateTime.ts

@@ -12,7 +12,6 @@ import { provideService } from "./internal/effect.ts"
 import * as Layer from "./Layer.ts"
 import type * as order from "./Order.ts"
 import type { Pipeable } from "./Pipeable.ts"
-import type * as Result from "./Result.ts"
 import * as ServiceMap from "./ServiceMap.ts"
 
 const TypeId = Internal.TypeId
@@ -22,70 +21,30 @@ const TimeZoneTypeId = Internal.TimeZoneTypeId
  * A `DateTime` represents a point in time. It can optionally have a time zone
  * associated with it.
  *
- * @example
- * ```ts
- * import { DateTime } from "effect"
- *
- * // Create a UTC DateTime
- * const utc: DateTime.DateTime = DateTime.nowUnsafe()
- *
- * // Create a zoned DateTime
- * const zoned: DateTime.DateTime = DateTime.makeZonedUnsafe(new Date(), {
- *   timeZone: "Europe/London"
- * })
- * ```
- *
  * @since 3.6.0
  * @category models
  */
 export type DateTime = Utc | Zoned
 
 /**
- * @example
- * ```ts
- * import { DateTime } from "effect"
- *
- * const utc = DateTime.nowUnsafe()
- *
- * if (DateTime.isUtc(utc)) {
- *   console.log(utc._tag) // "Utc"
- *   console.log(utc.epochMillis) // timestamp in milliseconds
- * }
- * ```
- *
  * @since 3.6.0
  * @category models
  */
 export interface Utc extends DateTime.Proto {
   readonly _tag: "Utc"
-  readonly epochMillis: number
+  readonly epochMilliseconds: number
   partsUtc: DateTime.PartsWithWeekday | undefined
 }
 
 /**
- * @example
- * ```ts
- * import { DateTime } from "effect"
- *
- * const zoned = DateTime.makeZonedUnsafe(new Date(), {
- *   timeZone: "Europe/London"
- * })
- *
- * if (DateTime.isZoned(zoned)) {
- *   console.log(zoned._tag) // "Zoned"
- *   console.log(zoned.epochMillis) // timestamp in milliseconds
- *   console.log(DateTime.zoneToString(zoned.zone)) // "Europe/London"
- * }
- * ```
- *
  * @since 3.6.0
  * @category models
  */
 export interface Zoned extends DateTime.Proto {
   readonly _tag: "Zoned"
-  readonly epochMillis: number
+  readonly epochMilliseconds: number
   readonly zone: TimeZone
-  adjustedEpochMillis: number | undefined
+  adjustedEpochMilliseconds: number | undefined
   partsAdjusted: DateTime.PartsWithWeekday | undefined
   partsUtc: DateTime.PartsWithWeekday | undefined
 }
@@ -96,29 +55,10 @@ export interface Zoned extends DateTime.Proto {
  */
 export declare namespace DateTime {
   /**
-   * @example
-   * ```ts
-   * import { DateTime } from "effect"
-   *
-   * // All valid inputs for DateTime constructors
-   * const date = new Date()
-   * const stringDate = "2024-01-01"
-   * const epochMillis = 1704067200000
-   * const partsObj = { year: 2024, month: 1, day: 1 }
-   * const existing = DateTime.nowUnsafe()
-   *
-   * // All these can be used as DateTime.Input
-   * const dt1 = DateTime.makeUnsafe(date)
-   * const dt2 = DateTime.makeUnsafe(stringDate)
-   * const dt3 = DateTime.makeUnsafe(epochMillis)
-   * const dt4 = DateTime.makeUnsafe(partsObj)
-   * const dt5 = DateTime.makeUnsafe(existing)
-   * ```
-   *
    * @since 3.6.0
    * @category models
    */
-  export type Input = DateTime | Partial<Parts> | Date | number | string
+  export type Input = DateTime | Partial<Parts> | Instant | InstantWithZone | Date | number | string
 
   /**
    * @since 3.6.0
@@ -137,7 +77,7 @@ export declare namespace DateTime {
    * @category models
    */
   export type UnitSingular =
-    | "milli"
+    | "millisecond"
     | "second"
     | "minute"
     | "hour"
@@ -151,7 +91,7 @@ export declare namespace DateTime {
    * @category models
    */
   export type UnitPlural =
-    | "millis"
+    | "milliseconds"
     | "seconds"
     | "minutes"
     | "hours"
@@ -165,10 +105,10 @@ export declare namespace DateTime {
    * @category models
    */
   export interface PartsWithWeekday {
-    readonly millis: number
-    readonly seconds: number
-    readonly minutes: number
-    readonly hours: number
+    readonly millisecond: number
+    readonly second: number
+    readonly minute: number
+    readonly hour: number
     readonly day: number
     readonly weekDay: number
     readonly month: number
@@ -180,10 +120,10 @@ export declare namespace DateTime {
    * @category models
    */
   export interface Parts {
-    readonly millis: number
-    readonly seconds: number
-    readonly minutes: number
-    readonly hours: number
+    readonly millisecond: number
+    readonly second: number
+    readonly minute: number
+    readonly hour: number
     readonly day: number
     readonly month: number
     readonly year: number
@@ -194,7 +134,7 @@ export declare namespace DateTime {
    * @category models
    */
   export interface PartsForMath {
-    readonly millis: number
+    readonly milliseconds: number
     readonly seconds: number
     readonly minutes: number
     readonly hours: number
@@ -204,6 +144,23 @@ export declare namespace DateTime {
     readonly years: number
   }
 
+  /**
+   * @since 4.0.0
+   * @category models
+   */
+  export interface Instant {
+    readonly epochMilliseconds: number
+  }
+
+  /**
+   * @since 4.0.0
+   * @category models
+   */
+  export interface InstantWithZone {
+    readonly timeZoneId: string
+    readonly epochMilliseconds: number
+  }
+
   /**
    * @since 3.6.0
    * @category models
@@ -1174,10 +1131,12 @@ export const setZoneNamedUnsafe: {
 // =============================================================================
 
 /**
- * Calulate the difference between two `DateTime` values, returning the number
- * of milliseconds the `other` DateTime is from `self`.
+ * Calulate the difference between two `DateTime` values, returning a
+ * `Duration` representing the amount of time between them.
  *
- * If `other` is *after* `self`, the result will be a positive number.
+ * If `other` is *after* `self`, the result will be a positive `Duration`. If
+ * `other` is *before* `self`, the result will be a negative `Duration`. If they
+ * are equal, the result will be a `Duration` of zero.
  *
  * @since 3.6.0
  * @category comparisons
@@ -1189,7 +1148,7 @@ export const setZoneNamedUnsafe: {
  *   const now = yield* DateTime.now
  *   const other = DateTime.add(now, { minutes: 1 })
  *
- *   // returns 60000
+ *   // returns Duration.minutes(1)
  *   DateTime.distance(now, other)
  * })
  * ```
@@ -1200,10 +1159,12 @@ export const distance: {
   // =============================================================================
 
   /**
-   * Calulate the difference between two `DateTime` values, returning the number
-   * of milliseconds the `other` DateTime is from `self`.
+   * Calulate the difference between two `DateTime` values, returning a
+   * `Duration` representing the amount of time between them.
    *
-   * If `other` is *after* `self`, the result will be a positive number.
+   * If `other` is *after* `self`, the result will be a positive `Duration`. If
+   * `other` is *before* `self`, the result will be a negative `Duration`. If they
+   * are equal, the result will be a `Duration` of zero.
    *
    * @since 3.6.0
    * @category comparisons
@@ -1215,147 +1176,23 @@ export const distance: {
    *   const now = yield* DateTime.now
    *   const other = DateTime.add(now, { minutes: 1 })
    *
-   *   // returns 60000
+   *   // returns Duration.minutes(1)
    *   DateTime.distance(now, other)
    * })
    * ```
    */
-  (other: DateTime): (self: DateTime) => number
+  (other: DateTime): (self: DateTime) => Duration.Duration
   // =============================================================================
   // comparisons
   // =============================================================================
 
   /**
-   * Calulate the difference between two `DateTime` values, returning the number
-   * of milliseconds the `other` DateTime is from `self`.
+   * Calulate the difference between two `DateTime` values, returning a
+   * `Duration` representing the amount of time between them.
    *
-   * If `other` is *after* `self`, the result will be a positive number.
-   *
-   * @since 3.6.0
-   * @category comparisons
-   * @example
-   * ```ts
-   * 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
-} = Internal.distance
-
-/**
- * Calulate the difference between two `DateTime` values.
- *
- * If the `other` DateTime is before `self`, the result will be a negative
- * `Duration`, returned as a `Failure`.
- *
- * If the `other` DateTime is after `self`, the result will be a positive
- * `Duration`, returned as a `Success`.
- *
- * @since 3.6.0
- * @category comparisons
- * @example
- * ```ts
- * import { DateTime, Effect } from "effect"
- *
- * Effect.gen(function*() {
- *   const now = yield* DateTime.now
- *   const other = DateTime.add(now, { minutes: 1 })
- *
- *   // returns Result.succeed(Duration.minutes(1))
- *   DateTime.distanceDurationResult(now, other)
- *
- *   // returns Result.fail(Duration.minutes(1))
- *   DateTime.distanceDurationResult(other, now)
- * })
- * ```
- */
-export const distanceDurationResult: {
-  /**
-   * Calulate the difference between two `DateTime` values.
-   *
-   * If the `other` DateTime is before `self`, the result will be a negative
-   * `Duration`, returned as a `Failure`.
-   *
-   * If the `other` DateTime is after `self`, the result will be a positive
-   * `Duration`, returned as a `Success`.
-   *
-   * @since 3.6.0
-   * @category comparisons
-   * @example
-   * ```ts
-   * import { DateTime, Effect } from "effect"
-   *
-   * Effect.gen(function*() {
-   *   const now = yield* DateTime.now
-   *   const other = DateTime.add(now, { minutes: 1 })
-   *
-   *   // returns Result.succeed(Duration.minutes(1))
-   *   DateTime.distanceDurationResult(now, other)
-   *
-   *   // returns Result.fail(Duration.minutes(1))
-   *   DateTime.distanceDurationResult(other, now)
-   * })
-   * ```
-   */
-  (other: DateTime): (self: DateTime) => Result.Result<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 `Failure`.
-   *
-   * If the `other` DateTime is after `self`, the result will be a positive
-   * `Duration`, returned as a `Success`.
-   *
-   * @since 3.6.0
-   * @category comparisons
-   * @example
-   * ```ts
-   * import { DateTime, Effect } from "effect"
-   *
-   * Effect.gen(function*() {
-   *   const now = yield* DateTime.now
-   *   const other = DateTime.add(now, { minutes: 1 })
-   *
-   *   // returns Result.succeed(Duration.minutes(1))
-   *   DateTime.distanceDurationResult(now, other)
-   *
-   *   // returns Result.fail(Duration.minutes(1))
-   *   DateTime.distanceDurationResult(other, now)
-   * })
-   * ```
-   */
-  (self: DateTime, other: DateTime): Result.Result<Duration.Duration, Duration.Duration>
-} = Internal.distanceDurationResult
-
-/**
- * Calulate the distance between two `DateTime` values.
- *
- * @since 3.6.0
- * @category comparisons
- * @example
- * ```ts
- * 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)
- * })
- * ```
- */
-export const distanceDuration: {
-  /**
-   * Calulate the distance between two `DateTime` values.
+   * If `other` is *after* `self`, the result will be a positive `Duration`. If
+   * `other` is *before* `self`, the result will be a negative `Duration`. If they
+   * are equal, the result will be a `Duration` of zero.
    *
    * @since 3.6.0
    * @category comparisons
@@ -1368,31 +1205,12 @@ export const distanceDuration: {
    *   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
-   * ```ts
-   * 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)
+   *   DateTime.distance(now, other)
    * })
    * ```
    */
   (self: DateTime, other: DateTime): Duration.Duration
-} = Internal.distanceDuration
+} = Internal.distance
 
 /**
  * Returns the earlier of two `DateTime` values.
@@ -2278,7 +2096,7 @@ export const setParts: {
  * const dt = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
  * const updated = DateTime.setPartsUtc(dt, {
  *   year: 2025,
- *   hours: 18
+ *   hour: 18
  * })
  *
  * console.log(DateTime.formatIso(updated)) // "2025-01-01T18:00:00.000Z"
@@ -2300,7 +2118,7 @@ export const setPartsUtc: {
    * const dt = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
    * const updated = DateTime.setPartsUtc(dt, {
    *   year: 2025,
-   *   hours: 18
+   *   hour: 18
    * })
    *
    * console.log(DateTime.formatIso(updated)) // "2025-01-01T18:00:00.000Z"
@@ -2322,7 +2140,7 @@ export const setPartsUtc: {
    * const dt = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
    * const updated = DateTime.setPartsUtc(dt, {
    *   year: 2025,
-   *   hours: 18
+   *   hour: 18
    * })
    *
    * console.log(DateTime.formatIso(updated)) // "2025-01-01T18:00:00.000Z"
@@ -3054,7 +2872,7 @@ export const addDuration: {
    * )
    * ```
    */
-  (duration: Duration.DurationInput): <A extends DateTime>(self: A) => A
+  (duration: Duration.Input): <A extends DateTime>(self: A) => A
   // =============================================================================
   // math
   // =============================================================================
@@ -3074,7 +2892,7 @@ export const addDuration: {
    * )
    * ```
    */
-  <A extends DateTime>(self: A, duration: Duration.DurationInput): A
+  <A extends DateTime>(self: A, duration: Duration.Input): A
 } = Internal.addDuration
 
 /**
@@ -3108,7 +2926,7 @@ export const subtractDuration: {
    * )
    * ```
    */
-  (duration: Duration.DurationInput): <A extends DateTime>(self: A) => A
+  (duration: Duration.Input): <A extends DateTime>(self: A) => A
   /**
    * Subtract the given `Duration` from a `DateTime`.
    *
@@ -3124,7 +2942,7 @@ export const subtractDuration: {
    * )
    * ```
    */
-  <A extends DateTime>(self: A, duration: Duration.DurationInput): A
+  <A extends DateTime>(self: A, duration: Duration.Input): A
 } = Internal.subtractDuration
 
 /**

package/src/Duration.ts

@@ -23,7 +23,7 @@ import { NodeInspectSymbol } from "./Inspectable.ts"
 import * as order from "./Order.ts"
 import type { Pipeable } from "./Pipeable.ts"
 import { pipeArguments } from "./Pipeable.ts"
-import { hasProperty, isBigInt, isNumber, isString } from "./Predicate.ts"
+import { hasProperty, isNumber } from "./Predicate.ts"
 import * as Reducer from "./Reducer.ts"
 import * as UndefinedOr from "./UndefinedOr.ts"
 
@@ -90,54 +90,71 @@ export type Unit =
  * @since 2.0.0
  * @category models
  */
-export type DurationInput =
+export type Input =
   | Duration
   | number // millis
   | bigint // nanos
   | readonly [seconds: number, nanos: number]
   | `${number} ${Unit}`
+  | DurationObject
+
+/**
+ * An object with optional duration components that can be combined to create
+ * a Duration. All fields are optional and additive.
+ *
+ * Compatible with Temporal.Duration-like objects.
+ *
+ * @example
+ * ```ts
+ * import { Duration } from "effect"
+ *
+ * Duration.fromInputUnsafe({ seconds: 30 })
+ * Duration.fromInputUnsafe({ days: 1 })
+ * Duration.fromInputUnsafe({ seconds: 1, nanoseconds: 500 })
+ * ```
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export interface DurationObject {
+  readonly weeks?: number | undefined
+  readonly days?: number | undefined
+  readonly hours?: number | undefined
+  readonly minutes?: number | undefined
+  readonly seconds?: number | undefined
+  readonly milliseconds?: number | undefined
+  readonly microseconds?: number | undefined
+  readonly nanoseconds?: number | undefined
+}
 
 const DURATION_REGEXP = /^(-?\d+(?:\.\d+)?)\s+(nanos?|micros?|millis?|seconds?|minutes?|hours?|days?|weeks?)$/
 
 /**
- * Decodes a `DurationInput` into a `Duration`.
+ * Decodes a `Duration.Input` into a `Duration`.
  *
- * If the input is not a valid `DurationInput`, it throws an error.
+ * If the input is not a valid `Duration.Input`, it throws an error.
  *
  * @example
  * ```ts
  * import { Duration } from "effect"
  *
- * const duration1 = Duration.fromDurationInputUnsafe(1000) // 1000 milliseconds
- * const duration2 = Duration.fromDurationInputUnsafe("5 seconds")
- * const duration3 = Duration.fromDurationInputUnsafe([2, 500_000_000]) // 2 seconds and 500ms
+ * const duration1 = Duration.fromInputUnsafe(1000) // 1000 milliseconds
+ * const duration2 = Duration.fromInputUnsafe("5 seconds")
+ * const duration3 = Duration.fromInputUnsafe([2, 500_000_000]) // 2 seconds and 500ms
  * ```
  *
  * @since 2.0.0
  * @category constructors
  */
-export const fromDurationInputUnsafe = (input: DurationInput): Duration => {
-  if (isDuration(input)) return input
-  if (isNumber(input)) return millis(input)
-  if (isBigInt(input)) return nanos(input)
-  if (Array.isArray(input) && input.length === 2 && input.every(isNumber)) {
-    if (Number.isNaN(input[0]) || Number.isNaN(input[1])) {
-      return zero
-    }
-
-    if (input[0] === -Infinity || input[1] === -Infinity) {
-      return negativeInfinity
-    }
-
-    if (input[0] === Infinity || input[1] === Infinity) {
-      return infinity
-    }
-
-    return nanos(BigInt(Math.round(input[0] * 1_000_000_000)) + BigInt(Math.round(input[1])))
-  }
-  if (isString(input)) {
-    const match = DURATION_REGEXP.exec(input)
-    if (match) {
+export const fromInputUnsafe = (input: Input): Duration => {
+  switch (typeof input) {
+    case "number":
+      return millis(input)
+    case "bigint":
+      return nanos(input)
+    case "string": {
+      const match = DURATION_REGEXP.exec(input)
+      if (!match) break
       const [_, valueStr, unit] = match
       const value = Number(valueStr)
       switch (unit) {
@@ -166,13 +183,51 @@ export const fromDurationInputUnsafe = (input: DurationInput): Duration => {
         case "weeks":
           return weeks(value)
       }
+      break
+    }
+    case "object": {
+      if (input === null) break
+      if (TypeId in input) return input as Duration
+      if (Array.isArray(input)) {
+        if (input.length !== 2 || !input.every(isNumber)) {
+          return invalid(input)
+        }
+        if (Number.isNaN(input[0]) || Number.isNaN(input[1])) {
+          return zero
+        }
+        if (input[0] === -Infinity || input[1] === -Infinity) {
+          return negativeInfinity
+        }
+        if (input[0] === Infinity || input[1] === Infinity) {
+          return infinity
+        }
+        return make(BigInt(Math.round(input[0] * 1_000_000_000)) + BigInt(Math.round(input[1])))
+      }
+      const obj = input as DurationObject
+      let millis = 0
+      // we can use truthy checks here, because 0 can be ignored
+      if (obj.weeks) millis += obj.weeks * 604_800_000
+      if (obj.days) millis += obj.days * 86_400_000
+      if (obj.hours) millis += obj.hours * 3_600_000
+      if (obj.minutes) millis += obj.minutes * 60_000
+      if (obj.seconds) millis += obj.seconds * 1_000
+      if (obj.milliseconds) millis += obj.milliseconds
+      if (!obj.microseconds && !obj.nanoseconds) return make(millis)
+      let nanos = BigInt(millis) * bigint1e6
+      if (obj.microseconds) nanos += BigInt(obj.microseconds) * bigint1e3
+      if (obj.nanoseconds) nanos += BigInt(obj.nanoseconds)
+      return make(nanos)
     }
   }
-  throw new Error(`Invalid DurationInput: ${input}`)
+  return invalid(input)
+}
+
+const invalid = (input: unknown): never => {
+  throw new Error(`Invalid Input: ${input}`)
 }
 
 /**
- * Safely decodes a `DurationInput` value into a `Duration`, returning
+ * Safely decodes a `Input` value into a `Duration`, returning
  * `undefined` if decoding fails.
  *
  * **Example**
@@ -180,16 +235,16 @@ export const fromDurationInputUnsafe = (input: DurationInput): Duration => {
  * ```ts
  * import { Duration } from "effect"
  *
- * Duration.fromDurationInput(1000)?.pipe(Duration.toSeconds) // 1
+ * Duration.fromInput(1000)?.pipe(Duration.toSeconds) // 1
  *
- * Duration.fromDurationInput("invalid" as any) // undefined
+ * Duration.fromInput("invalid" as any) // undefined
  * ```
  *
  * @category constructors
  * @since 4.0.0
  */
-export const fromDurationInput: (u: DurationInput) => Duration | undefined = UndefinedOr.liftThrowable(
-  fromDurationInputUnsafe
+export const fromInput: (u: Input) => Duration | undefined = UndefinedOr.liftThrowable(
+  fromInputUnsafe
 )
 
 const zeroDurationValue: DurationValue = { _tag: "Millis", millis: 0 }
@@ -238,7 +293,7 @@ const DurationProto: Omit<Duration, "value"> = {
 
 const make = (input: number | bigint): Duration => {
   const duration = Object.create(DurationProto)
-  if (isNumber(input)) {
+  if (typeof input === "number") {
     if (isNaN(input) || input === 0 || Object.is(input, -0)) {
       duration.value = zeroDurationValue
     } else if (!Number.isFinite(input)) {