effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/DateTime.ts

@@ -477,8 +477,8 @@ export const isTimeZone: (u: unknown) => u is TimeZone = Internal.isTimeZone
  *
  * **When to use**
  *
- * Use when narrowing an unknown or union `TimeZone` value to the fixed-offset
- * variant before reading its offset in milliseconds.
+ * Use when you need to narrow an unknown or union `TimeZone` value to the
+ * fixed-offset variant before reading its offset in milliseconds.
  *
  * @see {@link isTimeZone} for checking either time zone variant
  * @see {@link isTimeZoneNamed} for narrowing to named time zones
@@ -704,6 +704,11 @@ export const fromDateUnsafe: (date: Date) => Utc = Internal.fromDateUnsafe
 /**
  * Create a `DateTime` from supported input values.
  *
+ * **When to use**
+ *
+ * Use when creating a `DateTime` from trusted input and construction failures
+ * should throw an `IllegalArgumentError` instead of returning `Option.none`.
+ *
  * **Details**
  *
  * - A `DateTime`
@@ -738,6 +743,11 @@ export const makeUnsafe: <A extends DateTime.Input>(input: A) => DateTime.Preser
 /**
  * Create a `DateTime.Zoned` using `DateTime.makeUnsafe` and a time zone.
  *
+ * **When to use**
+ *
+ * Use when the date/time input and zone options are trusted and invalid or
+ * rejected ambiguous times should throw instead of returning `Option.none`.
+ *
  * **Details**
  *
  * The input is treated as UTC and then the time zone is attached, unless
@@ -934,6 +944,11 @@ export const nowAsDate: Effect.Effect<Date> = Internal.nowAsDate
 /**
  * Gets the current time using `Date.now`.
  *
+ * **When to use**
+ *
+ * Use when synchronous wall-clock access outside an Effect program is
+ * acceptable and testability through the `Clock` service is not needed.
+ *
  * **Details**
  *
  * This is a synchronous version of `now` that directly uses `Date.now()`
@@ -1155,6 +1170,11 @@ export const setZoneOffset: {
 /**
  * Attempts to create a named time zone from an IANA time zone identifier.
  *
+ * **When to use**
+ *
+ * Use when the IANA zone id is trusted and invalid zones should throw instead
+ * of returning `Option.none` or failing in `Effect`.
+ *
  * **Details**
  *
  * If the time zone is invalid, an `IllegalArgumentError` will be thrown.
@@ -1232,9 +1252,10 @@ export const zoneMakeNamed: (zoneId: string) => Option.Option<TimeZone.Named> =
 /**
  * Creates a named time zone effectfully from an IANA time zone identifier.
  *
- * **Details**
+ * **When to use**
  *
- * If the time zone is invalid, it will fail with an `IllegalArgumentError`.
+ * Use when invalid IANA zone ids should fail in the Effect error channel
+ * instead of returning `Option.none` or throwing.
  *
  * **Example** (Creating named time zones effectfully)
  *
@@ -2022,6 +2043,11 @@ export const isFuture: (self: DateTime) => Effect.Effect<boolean> = Internal.isF
 /**
  * Checks synchronously if a `DateTime` is in the future compared to the current time.
  *
+ * **When to use**
+ *
+ * Use when checking whether a `DateTime` is in the future with a synchronous
+ * live-clock read and `Clock`-based testability is not needed.
+ *
  * **Details**
  *
  * This is a synchronous version that uses `Date.now()` directly.
@@ -2070,6 +2096,11 @@ export const isPast: (self: DateTime) => Effect.Effect<boolean> = Internal.isPas
 /**
  * Checks synchronously if a `DateTime` is in the past compared to the current time.
  *
+ * **When to use**
+ *
+ * Use when checking whether a `DateTime` is in the past with a synchronous
+ * live-clock read and `Clock`-based testability is not needed.
+ *
  * **Details**
  *
  * This is a synchronous version that uses `Date.now()` directly.
@@ -4117,10 +4148,6 @@ export const format: {
  * Formats a `DateTime` with `Intl.DateTimeFormat` using the system local time
  * zone and locale.
  *
- * **Details**
- *
- * It will use the system's local time zone & locale.
- *
  * **Example** (Formatting DateTime values locally)
  *
  * ```ts
@@ -4148,10 +4175,6 @@ export const formatLocal: {
    * Formats a `DateTime` with `Intl.DateTimeFormat` using the system local time
    * zone and locale.
    *
-   * **Details**
-   *
-   * It will use the system's local time zone & locale.
-   *
    * **Example** (Formatting DateTime values locally)
    *
    * ```ts
@@ -4185,10 +4208,6 @@ export const formatLocal: {
    * Formats a `DateTime` with `Intl.DateTimeFormat` using the system local time
    * zone and locale.
    *
-   * **Details**
-   *
-   * It will use the system's local time zone & locale.
-   *
    * **Example** (Formatting DateTime values locally)
    *
    * ```ts

package/src/Deferred.ts

@@ -289,8 +289,8 @@ export {
  *
  * **When to use**
  *
- * Use when completion should run an effect once and share its result with all
- * awaiters.
+ * Use when completing a `Deferred` should run an effect once and share its
+ * result with all awaiters.
  *
  * **Details**
  *
@@ -314,7 +314,7 @@ export {
  *
  * @see {@link completeWith} for storing an effect directly without memoizing its result
  *
- * @category utils
+ * @category completion
  * @since 2.0.0
  */
 export const complete: {
@@ -324,8 +324,8 @@ export const complete: {
    *
    * **When to use**
    *
-   * Use when completion should run an effect once and share its result with all
-   * awaiters.
+   * Use when completing a `Deferred` should run an effect once and share its
+   * result with all awaiters.
    *
    * **Details**
    *
@@ -349,7 +349,7 @@ export const complete: {
    *
    * @see {@link completeWith} for storing an effect directly without memoizing its result
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E, R>(effect: Effect<A, E, R>): (self: Deferred<A, E>) => Effect<boolean, never, R>
@@ -359,8 +359,8 @@ export const complete: {
    *
    * **When to use**
    *
-   * Use when completion should run an effect once and share its result with all
-   * awaiters.
+   * Use when completing a `Deferred` should run an effect once and share its
+   * result with all awaiters.
    *
    * **Details**
    *
@@ -384,7 +384,7 @@ export const complete: {
    *
    * @see {@link completeWith} for storing an effect directly without memoizing its result
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E, R>(self: Deferred<A, E>, effect: Effect<A, E, R>): Effect<boolean, never, R>
@@ -430,7 +430,7 @@ export const complete: {
  * @see {@link complete} for running an effect once and sharing its result
  * @see {@link done} for completing from an already computed `Exit`
  *
- * @category utils
+ * @category completion
  * @since 2.0.0
  */
 export const completeWith: {
@@ -470,7 +470,7 @@ export const completeWith: {
    * @see {@link complete} for running an effect once and sharing its result
    * @see {@link done} for completing from an already computed `Exit`
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E>(effect: Effect<A, E>): (self: Deferred<A, E>) => Effect<boolean>
@@ -510,7 +510,7 @@ export const completeWith: {
    * @see {@link complete} for running an effect once and sharing its result
    * @see {@link done} for completing from an already computed `Exit`
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, effect: Effect<A, E>): Effect<boolean>
@@ -552,7 +552,7 @@ export const completeWith: {
  * @see {@link succeed} for completing with a success value
  * @see {@link failCause} for completing with a failure cause
  *
- * @category utils
+ * @category completion
  * @since 2.0.0
  */
 export const done: {
@@ -588,7 +588,7 @@ export const done: {
    * @see {@link succeed} for completing with a success value
    * @see {@link failCause} for completing with a failure cause
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E>(exit: Exit.Exit<A, E>): (self: Deferred<A, E>) => Effect<boolean>
@@ -624,7 +624,7 @@ export const done: {
    * @see {@link succeed} for completing with a success value
    * @see {@link failCause} for completing with a failure cause
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, exit: Exit.Exit<A, E>): Effect<boolean>
@@ -655,7 +655,7 @@ export const done: {
  * })
  * ```
  *
- * @category utils
+ * @category completion
  * @since 2.0.0
  */
 export const fail: {
@@ -684,7 +684,7 @@ export const fail: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <E>(error: E): <A>(self: Deferred<A, E>) => Effect<boolean>
@@ -713,7 +713,7 @@ export const fail: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, error: E): Effect<boolean>
@@ -725,7 +725,8 @@ export const fail: {
  *
  * **When to use**
  *
- * Use to lazily compute a typed failure value when the completion effect runs.
+ * Use to lazily compute a typed failure value when the `Deferred` completion
+ * effect runs.
  *
  * **Details**
  *
@@ -745,7 +746,7 @@ export const fail: {
  * })
  * ```
  *
- * @category utils
+ * @category completion
  * @since 2.0.0
  */
 export const failSync: {
@@ -755,7 +756,8 @@ export const failSync: {
    *
    * **When to use**
    *
-   * Use to lazily compute a typed failure value when the completion effect runs.
+   * Use to lazily compute a typed failure value when the `Deferred` completion
+   * effect runs.
    *
    * **Details**
    *
@@ -775,7 +777,7 @@ export const failSync: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <E>(evaluate: LazyArg<E>): <A>(self: Deferred<A, E>) => Effect<boolean>
@@ -785,7 +787,8 @@ export const failSync: {
    *
    * **When to use**
    *
-   * Use to lazily compute a typed failure value when the completion effect runs.
+   * Use to lazily compute a typed failure value when the `Deferred` completion
+   * effect runs.
    *
    * **Details**
    *
@@ -805,7 +808,7 @@ export const failSync: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, evaluate: LazyArg<E>): Effect<boolean>
@@ -843,7 +846,7 @@ export const failSync: {
  * })
  * ```
  *
- * @category utils
+ * @category completion
  * @since 2.0.0
  */
 export const failCause: {
@@ -875,7 +878,7 @@ export const failCause: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <E>(cause: Cause.Cause<E>): <A>(self: Deferred<A, E>) => Effect<boolean>
@@ -907,7 +910,7 @@ export const failCause: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, cause: Cause.Cause<E>): Effect<boolean>
@@ -922,7 +925,8 @@ export const failCause: {
  *
  * **When to use**
  *
- * Use to lazily compute a full failure cause when the completion effect runs.
+ * Use to lazily compute a full failure cause when the `Deferred` completion
+ * effect runs.
  *
  * **Details**
  *
@@ -945,7 +949,7 @@ export const failCause: {
  * })
  * ```
  *
- * @category utils
+ * @category completion
  * @since 2.0.0
  */
 export const failCauseSync: {
@@ -955,7 +959,8 @@ export const failCauseSync: {
    *
    * **When to use**
    *
-   * Use to lazily compute a full failure cause when the completion effect runs.
+   * Use to lazily compute a full failure cause when the `Deferred` completion
+   * effect runs.
    *
    * **Details**
    *
@@ -978,7 +983,7 @@ export const failCauseSync: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <E>(evaluate: LazyArg<Cause.Cause<E>>): <A>(self: Deferred<A, E>) => Effect<boolean>
@@ -988,7 +993,8 @@ export const failCauseSync: {
    *
    * **When to use**
    *
-   * Use to lazily compute a full failure cause when the completion effect runs.
+   * Use to lazily compute a full failure cause when the `Deferred` completion
+   * effect runs.
    *
    * **Details**
    *
@@ -1011,7 +1017,7 @@ export const failCauseSync: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, evaluate: LazyArg<Cause.Cause<E>>): Effect<boolean>
@@ -1049,7 +1055,7 @@ export const failCauseSync: {
  * })
  * ```
  *
- * @category utils
+ * @category completion
  * @since 2.0.0
  */
 export const die: {
@@ -1081,7 +1087,7 @@ export const die: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   (defect: unknown): <A, E>(self: Deferred<A, E>) => Effect<boolean>
@@ -1113,7 +1119,7 @@ export const die: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, defect: unknown): Effect<boolean>
@@ -1148,7 +1154,7 @@ export const die: {
  * })
  * ```
  *
- * @category utils
+ * @category completion
  * @since 2.0.0
  */
 export const dieSync: {
@@ -1181,7 +1187,7 @@ export const dieSync: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   (evaluate: LazyArg<unknown>): <A, E>(self: Deferred<A, E>) => Effect<boolean>
@@ -1214,7 +1220,7 @@ export const dieSync: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, evaluate: LazyArg<unknown>): Effect<boolean>
@@ -1250,7 +1256,7 @@ export const dieSync: {
  * })
  * ```
  *
- * @category utils
+ * @category completion
  * @since 2.0.0
  */
 export const interrupt = <A, E>(self: Deferred<A, E>): Effect<boolean> =>
@@ -1282,7 +1288,7 @@ export const interrupt = <A, E>(self: Deferred<A, E>): Effect<boolean> =>
  * })
  * ```
  *
- * @category utils
+ * @category completion
  * @since 2.0.0
  */
 export const interruptWith: {
@@ -1312,7 +1318,7 @@ export const interruptWith: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   (fiberId: number): <A, E>(self: Deferred<A, E>) => Effect<boolean>
@@ -1342,7 +1348,7 @@ export const interruptWith: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, fiberId: number): Effect<boolean>
@@ -1457,7 +1463,7 @@ export function poll<A, E>(self: Deferred<A, E>): Effect<Option.Option<Effect<A,
  * })
  * ```
  *
- * @category utils
+ * @category completion
  * @since 2.0.0
  */
 export const succeed: {
@@ -1488,7 +1494,7 @@ export const succeed: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A>(value: A): <E>(self: Deferred<A, E>) => Effect<boolean>
@@ -1519,7 +1525,7 @@ export const succeed: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, value: A): Effect<boolean>
@@ -1531,7 +1537,8 @@ export const succeed: {
  *
  * **When to use**
  *
- * Use to lazily compute a successful value when the completion effect runs.
+ * Use to lazily compute a successful value when the `Deferred` completion
+ * effect runs.
  *
  * **Details**
  *
@@ -1553,7 +1560,7 @@ export const succeed: {
  * })
  * ```
  *
- * @category utils
+ * @category completion
  * @since 2.0.0
  */
 export const sync: {
@@ -1563,7 +1570,8 @@ export const sync: {
    *
    * **When to use**
    *
-   * Use to lazily compute a successful value when the completion effect runs.
+   * Use to lazily compute a successful value when the `Deferred` completion
+   * effect runs.
    *
    * **Details**
    *
@@ -1585,7 +1593,7 @@ export const sync: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A>(evaluate: LazyArg<A>): <E>(self: Deferred<A, E>) => Effect<boolean>
@@ -1595,7 +1603,8 @@ export const sync: {
    *
    * **When to use**
    *
-   * Use to lazily compute a successful value when the completion effect runs.
+   * Use to lazily compute a successful value when the `Deferred` completion
+   * effect runs.
    *
    * **Details**
    *
@@ -1617,7 +1626,7 @@ export const sync: {
    * })
    * ```
    *
-   * @category utils
+   * @category completion
    * @since 2.0.0
    */
   <A, E>(self: Deferred<A, E>, evaluate: LazyArg<A>): Effect<boolean>