effect 4.0.0-beta.4 → 4.0.0-beta.41

package/src/DateTime.ts

@@ -10,9 +10,9 @@ import type { Inspectable } from "./Inspectable.ts"
 import * as Internal from "./internal/dateTime.ts"
 import { provideService } from "./internal/effect.ts"
 import * as Layer from "./Layer.ts"
+import type * as Option from "./Option.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 +22,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 +56,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 +78,7 @@ export declare namespace DateTime {
    * @category models
    */
   export type UnitSingular =
-    | "milli"
+    | "millisecond"
     | "second"
     | "minute"
     | "hour"
@@ -151,7 +92,7 @@ export declare namespace DateTime {
    * @category models
    */
   export type UnitPlural =
-    | "millis"
+    | "milliseconds"
     | "seconds"
     | "minutes"
     | "hours"
@@ -165,10 +106,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 +121,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 +135,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 +145,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
@@ -600,7 +558,7 @@ export const makeZoned: (
     readonly adjustForTimeZone?: boolean | undefined
     readonly disambiguation?: Disambiguation | undefined
   }
-) => Zoned | undefined = Internal.makeZoned
+) => Option.Option<Zoned> = Internal.makeZoned
 
 /**
  * Create a `DateTime` from one of the following:
@@ -629,7 +587,7 @@ export const makeZoned: (
  * DateTime.make("2024-01-01")
  * ```
  */
-export const make: <A extends DateTime.Input>(input: A) => DateTime.PreserveZone<A> | undefined = Internal.make
+export const make: <A extends DateTime.Input>(input: A) => Option.Option<DateTime.PreserveZone<A>> = Internal.make
 
 /**
  * Create a `DateTime.Zoned` from a string.
@@ -643,19 +601,19 @@ export const make: <A extends DateTime.Input>(input: A) => DateTime.PreserveZone
  * const result1 = DateTime.makeZonedFromString(
  *   "2024-01-01T12:00:00+02:00[Europe/Berlin]"
  * )
- * console.log(result1 !== undefined) // true
+ * console.log(result1._tag === "Some") // true
  *
  * const result2 = DateTime.makeZonedFromString("2024-01-01T12:00:00Z")
- * console.log(result2 !== undefined) // true
+ * console.log(result2._tag === "Some") // true
  *
  * const invalid = DateTime.makeZonedFromString("invalid")
- * console.log(invalid === undefined) // true
+ * console.log(invalid._tag === "None") // true
  * ```
  *
  * @since 3.6.0
  * @category constructors
  */
-export const makeZonedFromString: (input: string) => Zoned | undefined = Internal.makeZonedFromString
+export const makeZonedFromString: (input: string) => Option.Option<Zoned> = Internal.makeZonedFromString
 
 /**
  * Get the current time using the `Clock` service and convert it to a `DateTime`.
@@ -935,16 +893,16 @@ export const zoneMakeOffset: (offset: number) => TimeZone.Offset = Internal.zone
  * import { DateTime } from "effect"
  *
  * const validZone = DateTime.zoneMakeNamed("Europe/London")
- * console.log(validZone !== undefined) // true
+ * console.log(validZone._tag === "Some") // true
  *
  * const invalidZone = DateTime.zoneMakeNamed("Invalid/Zone")
- * console.log(invalidZone === undefined) // true
+ * console.log(invalidZone._tag === "None") // true
  * ```
  *
  * @category time zones
  * @since 3.6.0
  */
-export const zoneMakeNamed: (zoneId: string) => TimeZone.Named | undefined = Internal.zoneMakeNamed
+export const zoneMakeNamed: (zoneId: string) => Option.Option<TimeZone.Named> = Internal.zoneMakeNamed
 
 /**
  * Create a named time zone from a IANA time zone identifier.
@@ -1003,15 +961,15 @@ export const zoneMakeLocal: () => TimeZone.Named = Internal.zoneMakeLocal
  * const offsetZone = DateTime.zoneFromString("+03:00")
  * const invalid = DateTime.zoneFromString("invalid")
  *
- * console.log(namedZone !== undefined) // true
- * console.log(offsetZone !== undefined) // true
- * console.log(invalid === undefined) // true
+ * console.log(namedZone._tag === "Some") // true
+ * console.log(offsetZone._tag === "Some") // true
+ * console.log(invalid._tag === "None") // true
  * ```
  *
  * @category time zones
  * @since 3.6.0
  */
-export const zoneFromString: (zone: string) => TimeZone | undefined = Internal.zoneFromString
+export const zoneFromString: (zone: string) => Option.Option<TimeZone> = Internal.zoneFromString
 
 /**
  * Format a `TimeZone` as a string.
@@ -1072,7 +1030,7 @@ export const setZoneNamed: {
      readonly adjustForTimeZone?: boolean | undefined
      readonly disambiguation?: Disambiguation | undefined
    }
-  ): (self: DateTime) => Zoned | 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.
@@ -1097,7 +1055,7 @@ export const setZoneNamed: {
      readonly adjustForTimeZone?: boolean | undefined
      readonly disambiguation?: Disambiguation | undefined
    }
-  ): Zoned | undefined
+  ): Option.Option<Zoned>
 } = Internal.setZoneNamed
 
 /**
@@ -1174,10 +1132,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 +1149,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 +1160,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 +1177,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 +1206,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 +2097,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 +2119,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 +2141,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 +2873,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 +2893,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 +2927,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 +2943,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/Deferred.ts

@@ -72,6 +72,7 @@ import type * as Exit from "./Exit.ts"
 import { dual, identity, type LazyArg } from "./Function.ts"
 import * as core from "./internal/core.ts"
 import * as internalEffect from "./internal/effect.ts"
+import * as Option from "./Option.ts"
 import type { Pipeable } from "./Pipeable.ts"
 import { pipeArguments } from "./Pipeable.ts"
 import type * as Types from "./Types.ts"
@@ -973,8 +974,9 @@ export const isDone = <A, E>(self: Deferred<A, E>): Effect<boolean> => internalE
 export const isDoneUnsafe = <A, E>(self: Deferred<A, E>): boolean => self.effect !== undefined
 
 /**
- * Returns a `Effect<A, E, R>` from the `Deferred` if this `Deferred` has
- * already been completed, `undefined` otherwise.
+ * Returns the current completion effect as an `Option`. This returns
+ * `Option.some(effect)` when the `Deferred` is completed, `Option.none()`
+ * otherwise.
  *
  * @example
  * ```ts
@@ -983,19 +985,19 @@ export const isDoneUnsafe = <A, E>(self: Deferred<A, E>): boolean => self.effect
  * const program = Effect.gen(function*() {
  *   const deferred = yield* Deferred.make<number>()
  *   const beforeCompletion = yield* Deferred.poll(deferred)
- *   console.log(beforeCompletion === undefined) // true
+ *   console.log(beforeCompletion._tag === "None") // true
  *
  *   yield* Deferred.succeed(deferred, 42)
  *   const afterCompletion = yield* Deferred.poll(deferred)
- *   console.log(afterCompletion !== undefined) // true
+ *   console.log(afterCompletion._tag === "Some") // true
  * })
  * ```
  *
  * @since 2.0.0
  * @category getters
  */
-export function poll<A, E>(self: Deferred<A, E>): Effect<Effect<A, E> | undefined> {
-  return internalEffect.sync(() => self.effect)
+export function poll<A, E>(self: Deferred<A, E>): Effect<Option.Option<Effect<A, E>>> {
+  return internalEffect.sync(() => Option.fromUndefinedOr(self.effect))
 }
 
 /**