effect 4.0.0-beta.74 → 4.0.0-beta.75

package/src/Data.ts

@@ -87,7 +87,7 @@ import type { Unify } from "./Unify.ts"
  *
  * **When to use**
  *
- * Use when you need a lightweight immutable value type with `.pipe()` support. If you also need a `_tag` discriminator, use {@link TaggedClass}; if you need a yieldable error, use {@link Error} or {@link TaggedError}.
+ * Use when you need a lightweight immutable value type with `.pipe()` support.
  *
  * **Details**
  *
@@ -131,7 +131,7 @@ export const Class: new<A extends Record<string, any> = {}>(
  *
  * **When to use**
  *
- * Use when you need a single-variant tagged type or an ad-hoc discriminator. For multi-variant unions, prefer {@link TaggedEnum} with {@link taggedEnum}; for yieldable errors, use {@link TaggedError}.
+ * Use when you need a single-variant tagged type or an ad-hoc discriminator.
  *
  * **Details**
  *
@@ -174,7 +174,7 @@ export const TaggedClass = <Tag extends string>(
  *
  * **When to use**
  *
- * Use when you have two or more variants that share a common `_tag` discriminator. For generic tagged enums, see {@link TaggedEnum.WithGenerics}.
+ * Use when you have two or more variants that share a common `_tag` discriminator.
  *
  * **Details**
  *
@@ -254,7 +254,7 @@ export declare namespace TaggedEnum {
    *
    * **When to use**
    *
-   * Use when variant payloads need to be parameterized, such as `Result<E, A>`. Pass the interface, not the type alias, to {@link taggedEnum} to get generic-aware constructors and matchers.
+   * Use when variant payloads need to be parameterized, such as `Result<E, A>`.
    *
    * **Details**
    *
@@ -420,7 +420,8 @@ export declare namespace TaggedEnum {
    *
    * **When to use**
    *
-   * Use to type the constructors-and-matchers object returned by `taggedEnum`.
+   * Use when you want to annotate an exported constructor bundle so downstream
+   * code keeps exact variant constructors and exhaustive matching.
    *
    * **Details**
    *
@@ -586,7 +587,8 @@ export declare namespace TaggedEnum {
  *
  * **When to use**
  *
- * Use when you have a `TaggedEnum` type and need constructors and matchers for its values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+ * Use when you model a closed union with plain data objects and want
+ * construction, tag checks, and exhaustive matching from the same definition.
  *
  * **Details**
  *
@@ -658,7 +660,8 @@ export const taggedEnum: {
    *
    * **When to use**
    *
-   * Use when you have a `TaggedEnum` type and need constructors and matchers for its values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * Use when you model a closed union with plain data objects and want
+   * construction, tag checks, and exhaustive matching from the same definition.
    *
    * **Details**
    *
@@ -741,7 +744,8 @@ export const taggedEnum: {
    *
    * **When to use**
    *
-   * Use when you have a `TaggedEnum` type and need constructors and matchers for its values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * Use when you model a closed union with plain data objects and want
+   * construction, tag checks, and exhaustive matching from the same definition.
    *
    * **Details**
    *
@@ -824,7 +828,8 @@ export const taggedEnum: {
    *
    * **When to use**
    *
-   * Use when you have a `TaggedEnum` type and need constructors and matchers for its values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * Use when you model a closed union with plain data objects and want
+   * construction, tag checks, and exhaustive matching from the same definition.
    *
    * **Details**
    *
@@ -907,7 +912,8 @@ export const taggedEnum: {
    *
    * **When to use**
    *
-   * Use when you have a `TaggedEnum` type and need constructors and matchers for its values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * Use when you model a closed union with plain data objects and want
+   * construction, tag checks, and exhaustive matching from the same definition.
    *
    * **Details**
    *
@@ -990,7 +996,8 @@ export const taggedEnum: {
    *
    * **When to use**
    *
-   * Use when you have a `TaggedEnum` type and need constructors and matchers for its values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * Use when you model a closed union with plain data objects and want
+   * construction, tag checks, and exhaustive matching from the same definition.
    *
    * **Details**
    *
@@ -1106,8 +1113,8 @@ function taggedMatch<
  *
  * **When to use**
  *
- * Use when defining yieldable errors that do **not** need tag-based
- * discrimination. If you need tag-based recovery, use {@link TaggedError}.
+ * Use when you need yieldable errors that do **not** need tag-based
+ * discrimination.
  *
  * **Details**
  *
@@ -1149,8 +1156,7 @@ export const Error: new<A extends Record<string, any> = {}>(
  *
  * **When to use**
  *
- * Use when modeling domain errors in Effect applications where you want
- * discriminated-union error handling.
+ * Use when you need domain errors with discriminated-union handling.
  *
  * **Details**
  *

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**
  *
@@ -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**
    *
@@ -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**
    *
@@ -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**
  *
@@ -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**
    *
@@ -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**
    *
@@ -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**
  *
@@ -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**
    *
@@ -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**
    *
@@ -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**
  *
@@ -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**
    *
@@ -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**
    *

package/src/Duration.ts

@@ -222,6 +222,11 @@ const DURATION_REGEXP = /^(-?\d+(?:\.\d+)?)\s+(nanos?|micros?|millis?|seconds?|m
 /**
  * Decodes a `Duration.Input` into a `Duration`.
  *
+ * **When to use**
+ *
+ * Use when the input has already been validated or comes from a trusted source
+ * and throwing is acceptable for invalid duration syntax.
+ *
  * **Gotchas**
  *
  * If the input is not a valid `Duration.Input`, it throws an error.
@@ -909,7 +914,12 @@ export const toWeeks = (self: Input): number =>
   })
 
 /**
- * Gets the duration in nanoseconds as a bigint, throwing for infinite durations.
+ * Gets the duration in nanoseconds as a bigint.
+ *
+ * **When to use**
+ *
+ * Use when the duration is known to be finite and you need the nanosecond value
+ * as a `bigint`.
  *
  * **Gotchas**
  *
@@ -1652,6 +1662,11 @@ export const divide: {
  * Divides a `Duration` by a number using fallback rules instead of returning
  * an `Option`.
  *
+ * **When to use**
+ *
+ * Use when dividing a `Duration` should return `Duration.zero` or signed
+ * infinity for invalid cases instead of forcing callers to handle `Option.none`.
+ *
  * **Details**
  *
  * Non-finite divisors return `Duration.zero`. Division by positive or negative
@@ -1680,6 +1695,11 @@ export const divideUnsafe: {
    * Divides a `Duration` by a number using fallback rules instead of returning
    * an `Option`.
    *
+   * **When to use**
+   *
+   * Use when dividing a `Duration` should return `Duration.zero` or signed
+   * infinity for invalid cases instead of forcing callers to handle `Option.none`.
+   *
    * **Details**
    *
    * Non-finite divisors return `Duration.zero`. Division by positive or negative
@@ -1708,6 +1728,11 @@ export const divideUnsafe: {
    * Divides a `Duration` by a number using fallback rules instead of returning
    * an `Option`.
    *
+   * **When to use**
+   *
+   * Use when dividing a `Duration` should return `Duration.zero` or signed
+   * infinity for invalid cases instead of forcing callers to handle `Option.none`.
+   *
    * **Details**
    *
    * Non-finite divisors return `Duration.zero`. Division by positive or negative
@@ -1843,16 +1868,12 @@ export const times: {
  *
  * **Details**
  *
- * Infinity subtraction follows these rules:
- *
- * - infinity - infinity = 0
- * - infinity - negativeInfinity = infinity
- * - infinity - finite = infinity
- * - negativeInfinity - negativeInfinity = 0
- * - negativeInfinity - infinity = negativeInfinity
- * - negativeInfinity - finite = negativeInfinity
- * - finite - infinity = negativeInfinity
- * - finite - negativeInfinity = infinity
+ * Infinity subtraction follows signed-infinity arithmetic. Subtracting the
+ * same infinity from itself returns zero. Positive infinity minus negative
+ * infinity or any finite duration remains positive infinity. Negative infinity
+ * minus positive infinity or any finite duration remains negative infinity.
+ * Finite durations minus positive infinity produce negative infinity, and
+ * finite durations minus negative infinity produce positive infinity.
  *
  * **Example** (Subtracting durations)
  *
@@ -1872,16 +1893,12 @@ export const subtract: {
    *
    * **Details**
    *
-   * Infinity subtraction follows these rules:
-   *
-   * - infinity - infinity = 0
-   * - infinity - negativeInfinity = infinity
-   * - infinity - finite = infinity
-   * - negativeInfinity - negativeInfinity = 0
-   * - negativeInfinity - infinity = negativeInfinity
-   * - negativeInfinity - finite = negativeInfinity
-   * - finite - infinity = negativeInfinity
-   * - finite - negativeInfinity = infinity
+   * Infinity subtraction follows signed-infinity arithmetic. Subtracting the
+   * same infinity from itself returns zero. Positive infinity minus negative
+   * infinity or any finite duration remains positive infinity. Negative infinity
+   * minus positive infinity or any finite duration remains negative infinity.
+   * Finite durations minus positive infinity produce negative infinity, and
+   * finite durations minus negative infinity produce positive infinity.
    *
    * **Example** (Subtracting durations)
    *
@@ -1901,16 +1918,12 @@ export const subtract: {
    *
    * **Details**
    *
-   * Infinity subtraction follows these rules:
-   *
-   * - infinity - infinity = 0
-   * - infinity - negativeInfinity = infinity
-   * - infinity - finite = infinity
-   * - negativeInfinity - negativeInfinity = 0
-   * - negativeInfinity - infinity = negativeInfinity
-   * - negativeInfinity - finite = negativeInfinity
-   * - finite - infinity = negativeInfinity
-   * - finite - negativeInfinity = infinity
+   * Infinity subtraction follows signed-infinity arithmetic. Subtracting the
+   * same infinity from itself returns zero. Positive infinity minus negative
+   * infinity or any finite duration remains positive infinity. Negative infinity
+   * minus positive infinity or any finite duration remains negative infinity.
+   * Finite durations minus positive infinity produce negative infinity, and
+   * finite durations minus negative infinity produce positive infinity.
    *
    * **Example** (Subtracting durations)
    *