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

package/src/MutableHashMap.ts

@@ -269,7 +269,7 @@ export const fromIterable = <K, V>(entries: Iterable<readonly [K, V]>): MutableH
  *
  * **When to use**
  *
- * Use to safely read the value for a key as an `Option`.
+ * Use to safely read a `MutableHashMap` value for a key as an `Option`.
  *
  * **Details**
  *
@@ -303,7 +303,7 @@ export const get: {
    *
    * **When to use**
    *
-   * Use to safely read the value for a key as an `Option`.
+   * Use to safely read a `MutableHashMap` value for a key as an `Option`.
    *
    * **Details**
    *
@@ -337,7 +337,7 @@ export const get: {
    *
    * **When to use**
    *
-   * Use to safely read the value for a key as an `Option`.
+   * Use to safely read a `MutableHashMap` value for a key as an `Option`.
    *
    * **Details**
    *
@@ -372,7 +372,7 @@ export const get: {
    *
    * **When to use**
    *
-   * Use to safely read the value for a key as an `Option`.
+   * Use to safely read a `MutableHashMap` value for a key as an `Option`.
    *
    * **Details**
    *
@@ -406,7 +406,7 @@ export const get: {
    *
    * **When to use**
    *
-   * Use to safely read the value for a key as an `Option`.
+   * Use to safely read a `MutableHashMap` value for a key as an `Option`.
    *
    * **Details**
    *
@@ -546,7 +546,8 @@ const getFromBucket = <K, V>(
  *
  * **When to use**
  *
- * Use to test whether a key is present without reading its value.
+ * Use to test whether a key is present in a `MutableHashMap` without reading
+ * its value.
  *
  * **Example** (Checking for a key)
  *
@@ -574,7 +575,8 @@ export const has: {
    *
    * **When to use**
    *
-   * Use to test whether a key is present without reading its value.
+   * Use to test whether a key is present in a `MutableHashMap` without reading
+   * its value.
    *
    * **Example** (Checking for a key)
    *
@@ -602,7 +604,8 @@ export const has: {
    *
    * **When to use**
    *
-   * Use to test whether a key is present without reading its value.
+   * Use to test whether a key is present in a `MutableHashMap` without reading
+   * its value.
    *
    * **Example** (Checking for a key)
    *
@@ -631,7 +634,8 @@ export const has: {
    *
    * **When to use**
    *
-   * Use to test whether a key is present without reading its value.
+   * Use to test whether a key is present in a `MutableHashMap` without reading
+   * its value.
    *
    * **Example** (Checking for a key)
    *
@@ -659,7 +663,8 @@ export const has: {
    *
    * **When to use**
    *
-   * Use to test whether a key is present without reading its value.
+   * Use to test whether a key is present in a `MutableHashMap` without reading
+   * its value.
    *
    * **Example** (Checking for a key)
    *
@@ -690,7 +695,8 @@ export const has: {
  *
  * **When to use**
  *
- * Use to insert a new entry or replace an existing entry in place.
+ * Use to insert a new `MutableHashMap` entry or replace an existing entry in
+ * place.
  *
  * **Example** (Setting key-value pairs)
  *
@@ -730,7 +736,8 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to insert a new entry or replace an existing entry in place.
+   * Use to insert a new `MutableHashMap` entry or replace an existing entry in
+   * place.
    *
    * **Example** (Setting key-value pairs)
    *
@@ -770,7 +777,8 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to insert a new entry or replace an existing entry in place.
+   * Use to insert a new `MutableHashMap` entry or replace an existing entry in
+   * place.
    *
    * **Example** (Setting key-value pairs)
    *
@@ -811,7 +819,8 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to insert a new entry or replace an existing entry in place.
+   * Use to insert a new `MutableHashMap` entry or replace an existing entry in
+   * place.
    *
    * **Example** (Setting key-value pairs)
    *
@@ -851,7 +860,8 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to insert a new entry or replace an existing entry in place.
+   * Use to insert a new `MutableHashMap` entry or replace an existing entry in
+   * place.
    *
    * **Example** (Setting key-value pairs)
    *
@@ -931,7 +941,8 @@ const getRefKey = <K>(
  *
  * **When to use**
  *
- * Use to transform an existing value in place without inserting missing keys.
+ * Use to transform an existing `MutableHashMap` value in place without
+ * inserting missing keys.
  *
  * **Example** (Modifying existing values)
  *
@@ -970,7 +981,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to transform an existing value in place without inserting missing keys.
+   * Use to transform an existing `MutableHashMap` value in place without
+   * inserting missing keys.
    *
    * **Example** (Modifying existing values)
    *
@@ -1009,7 +1021,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to transform an existing value in place without inserting missing keys.
+   * Use to transform an existing `MutableHashMap` value in place without
+   * inserting missing keys.
    *
    * **Example** (Modifying existing values)
    *
@@ -1049,7 +1062,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to transform an existing value in place without inserting missing keys.
+   * Use to transform an existing `MutableHashMap` value in place without
+   * inserting missing keys.
    *
    * **Example** (Modifying existing values)
    *
@@ -1088,7 +1102,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to transform an existing value in place without inserting missing keys.
+   * Use to transform an existing `MutableHashMap` value in place without
+   * inserting missing keys.
    *
    * **Example** (Modifying existing values)
    *

package/src/MutableList.ts

@@ -427,6 +427,11 @@ export const prependAll = <A>(self: MutableList<A>, messages: Iterable<A>): void
  * Prepends all elements from a ReadonlyArray to the beginning of the MutableList.
  * This is an optimized version that can reuse the array when mutable=true.
  *
+ * **When to use**
+ *
+ * Use when prepending a trusted array directly is worth the optimized path and
+ * you control whether the input may be reused.
+ *
  * **Gotchas**
  *
  * When mutable=true, the input array may be modified internally. Only use
@@ -512,6 +517,11 @@ export const appendAll = <A>(self: MutableList<A>, messages: Iterable<A>): numbe
  * This is an optimized version that can reuse the array when mutable=true.
  * Returns the number of elements added.
  *
+ * **When to use**
+ *
+ * Use when appending a trusted array directly is worth the optimized path and
+ * you control whether the input may be reused.
+ *
  * **Gotchas**
  *
  * When mutable=true, the input array may be modified internally. Only use
@@ -942,6 +952,11 @@ export const filter = <A>(self: MutableList<A>, f: (value: A, i: number) => bool
  * Removes all occurrences of a value from the `MutableList` using JavaScript
  * strict equality semantics.
  *
+ * **When to use**
+ *
+ * Use when in-place removal should use JavaScript identity/strict equality
+ * rather than Effect structural equality.
+ *
  * **Details**
  *
  * The list is modified in place.

package/src/MutableRef.ts

@@ -109,7 +109,7 @@ const MutableRefProto: Omit<MutableRef<unknown>, "current"> = {
  *
  * **When to use**
  *
- * Use to create a synchronous mutable reference initialized with a value.
+ * Use to create a synchronous `MutableRef` initialized with a value.
  *
  * **Example** (Creating mutable refs)
  *
@@ -146,8 +146,8 @@ export const make = <T>(value: T): MutableRef<T> => {
  *
  * **When to use**
  *
- * Use to replace a value only when the current value still matches an expected
- * value.
+ * Use to replace a `MutableRef` value only when the current value still matches
+ * an expected value.
  *
  * **Example** (Comparing and setting values)
  *
@@ -189,8 +189,8 @@ export const compareAndSet: {
    *
    * **When to use**
    *
-   * Use to replace a value only when the current value still matches an expected
-   * value.
+   * Use to replace a `MutableRef` value only when the current value still matches
+   * an expected value.
    *
    * **Example** (Comparing and setting values)
    *
@@ -232,8 +232,8 @@ export const compareAndSet: {
    *
    * **When to use**
    *
-   * Use to replace a value only when the current value still matches an expected
-   * value.
+   * Use to replace a `MutableRef` value only when the current value still matches
+   * an expected value.
    *
    * **Example** (Comparing and setting values)
    *
@@ -284,8 +284,8 @@ export const compareAndSet: {
  *
  * **When to use**
  *
- * Use to decrement a numeric reference in place when you want the same
- * reference back.
+ * Use when you need an in-place `MutableRef` decrement that returns the same
+ * `MutableRef`.
  *
  * **Example** (Decrementing numeric refs)
  *
@@ -321,7 +321,8 @@ export const decrement = (self: MutableRef<number>): MutableRef<number> => updat
  *
  * **When to use**
  *
- * Use to decrement a numeric reference and immediately read the updated value.
+ * Use to decrement a numeric `MutableRef` and immediately read the updated
+ * value.
  *
  * **Example** (Decrementing and reading refs)
  *
@@ -357,7 +358,7 @@ export const decrementAndGet = (self: MutableRef<number>): number => updateAndGe
  *
  * **When to use**
  *
- * Use to read the current value without mutating the reference.
+ * Use to read the current `MutableRef` value without mutating it.
  *
  * **Example** (Reading current values)
  *
@@ -391,7 +392,7 @@ export const get = <T>(self: MutableRef<T>): T => self.current
  *
  * **When to use**
  *
- * Use to read the current numeric value before decrementing it.
+ * Use to read the current numeric `MutableRef` value before decrementing it.
  *
  * **Example** (Reading before decrementing)
  *
@@ -428,7 +429,7 @@ export const getAndDecrement = (self: MutableRef<number>): number => getAndUpdat
  *
  * **When to use**
  *
- * Use to read the current numeric value before incrementing it.
+ * Use to read the current numeric `MutableRef` value before incrementing it.
  *
  * **Example** (Reading before incrementing)
  *
@@ -473,7 +474,8 @@ export const getAndIncrement = (self: MutableRef<number>): number => getAndUpdat
  *
  * **When to use**
  *
- * Use to replace the current value while keeping the previous value.
+ * Use to replace the current `MutableRef` value while keeping the previous
+ * value.
  *
  * **Example** (Reading before setting)
  *
@@ -513,7 +515,8 @@ export const getAndSet: {
    *
    * **When to use**
    *
-   * Use to replace the current value while keeping the previous value.
+   * Use to replace the current `MutableRef` value while keeping the previous
+   * value.
    *
    * **Example** (Reading before setting)
    *
@@ -553,7 +556,8 @@ export const getAndSet: {
    *
    * **When to use**
    *
-   * Use to replace the current value while keeping the previous value.
+   * Use to replace the current `MutableRef` value while keeping the previous
+   * value.
    *
    * **Example** (Reading before setting)
    *
@@ -603,7 +607,8 @@ export const getAndSet: {
  *
  * **When to use**
  *
- * Use to transform the current value while keeping the previous value.
+ * Use to transform the current `MutableRef` value while keeping the previous
+ * value.
  *
  * **Example** (Reading before updating)
  *
@@ -650,7 +655,8 @@ export const getAndUpdate: {
    *
    * **When to use**
    *
-   * Use to transform the current value while keeping the previous value.
+   * Use to transform the current `MutableRef` value while keeping the previous
+   * value.
    *
    * **Example** (Reading before updating)
    *
@@ -697,7 +703,8 @@ export const getAndUpdate: {
    *
    * **When to use**
    *
-   * Use to transform the current value while keeping the previous value.
+   * Use to transform the current `MutableRef` value while keeping the previous
+   * value.
    *
    * **Example** (Reading before updating)
    *
@@ -748,8 +755,8 @@ export const getAndUpdate: {
  *
  * **When to use**
  *
- * Use to increment a numeric reference in place when you want the same
- * reference back.
+ * Use when you need an in-place `MutableRef` increment that returns the same
+ * `MutableRef`.
  *
  * **Example** (Incrementing numeric refs)
  *
@@ -788,7 +795,8 @@ export const increment = (self: MutableRef<number>): MutableRef<number> => updat
  *
  * **When to use**
  *
- * Use to increment a numeric reference and immediately read the updated value.
+ * Use to increment a numeric `MutableRef` and immediately read the updated
+ * value.
  *
  * **Example** (Incrementing and reading refs)
  *
@@ -828,8 +836,8 @@ export const incrementAndGet = (self: MutableRef<number>): number => updateAndGe
  *
  * **When to use**
  *
- * Use to replace the current value in place when you want the same reference
- * back.
+ * Use when you need an in-place `MutableRef` replacement that returns the same
+ * `MutableRef`.
  *
  * **Example** (Setting values)
  *
@@ -873,8 +881,8 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to replace the current value in place when you want the same reference
-   * back.
+   * Use when you need an in-place `MutableRef` replacement that returns the same
+   * `MutableRef`.
    *
    * **Example** (Setting values)
    *
@@ -918,8 +926,8 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to replace the current value in place when you want the same reference
-   * back.
+   * Use when you need an in-place `MutableRef` replacement that returns the same
+   * `MutableRef`.
    *
    * **Example** (Setting values)
    *
@@ -971,7 +979,8 @@ export const set: {
  *
  * **When to use**
  *
- * Use to replace the current value and immediately read the replacement.
+ * Use to replace the current `MutableRef` value and immediately read the
+ * replacement.
  *
  * **Example** (Setting and reading values)
  *
@@ -1011,7 +1020,8 @@ export const setAndGet: {
    *
    * **When to use**
    *
-   * Use to replace the current value and immediately read the replacement.
+   * Use to replace the current `MutableRef` value and immediately read the
+   * replacement.
    *
    * **Example** (Setting and reading values)
    *
@@ -1051,7 +1061,8 @@ export const setAndGet: {
    *
    * **When to use**
    *
-   * Use to replace the current value and immediately read the replacement.
+   * Use to replace the current `MutableRef` value and immediately read the
+   * replacement.
    *
    * **Example** (Setting and reading values)
    *
@@ -1100,8 +1111,8 @@ export const setAndGet: {
  *
  * **When to use**
  *
- * Use to transform the current value in place when you want the same reference
- * back.
+ * Use when you need an in-place `MutableRef` value transformation that returns
+ * the same `MutableRef`.
  *
  * **Example** (Updating values)
  *
@@ -1150,8 +1161,8 @@ export const update: {
    *
    * **When to use**
    *
-   * Use to transform the current value in place when you want the same reference
-   * back.
+   * Use when you need an in-place `MutableRef` value transformation that returns
+   * the same `MutableRef`.
    *
    * **Example** (Updating values)
    *
@@ -1200,8 +1211,8 @@ export const update: {
    *
    * **When to use**
    *
-   * Use to transform the current value in place when you want the same reference
-   * back.
+   * Use when you need an in-place `MutableRef` value transformation that returns
+   * the same `MutableRef`.
    *
    * **Example** (Updating values)
    *
@@ -1255,7 +1266,8 @@ export const update: {
  *
  * **When to use**
  *
- * Use to transform the current value and immediately read the updated value.
+ * Use to transform the current `MutableRef` value and immediately read the
+ * updated value.
  *
  * **Example** (Updating and reading values)
  *
@@ -1306,7 +1318,8 @@ export const updateAndGet: {
    *
    * **When to use**
    *
-   * Use to transform the current value and immediately read the updated value.
+   * Use to transform the current `MutableRef` value and immediately read the
+   * updated value.
    *
    * **Example** (Updating and reading values)
    *
@@ -1357,7 +1370,8 @@ export const updateAndGet: {
    *
    * **When to use**
    *
-   * Use to transform the current value and immediately read the updated value.
+   * Use to transform the current `MutableRef` value and immediately read the
+   * updated value.
    *
    * **Example** (Updating and reading values)
    *
@@ -1413,8 +1427,8 @@ export const updateAndGet: {
  *
  * **When to use**
  *
- * Use to flip a boolean reference in place when you want the same reference
- * back.
+ * Use when you need an in-place boolean `MutableRef` toggle that returns the
+ * same `MutableRef`.
  *
  * **Example** (Toggling boolean refs)
  *

package/src/Newtype.ts

@@ -169,8 +169,8 @@ export declare namespace Newtype {
  *
  * **When to use**
  *
- * Use when you only need to read the inner value and do not need to wrap
- * new values. For both wrapping and unwrapping, prefer {@link makeIso}.
+ * Use when you need the carrier value from an existing newtype without
+ * constructing a new newtype value at the same call site.
  *
  * **Details**
  *
@@ -237,7 +237,8 @@ export function makeIso<N extends Newtype.Any>(): Optic.Iso<N, Newtype.Carrier<N
  *
  * **When to use**
  *
- * Use when you need to compare two newtype values for equality.
+ * Use when you need equality for newtype-wrapped values to behave like
+ * equality for the wrapped carrier value, without manually unwrapping.
  *
  * **Details**
  *
@@ -272,7 +273,8 @@ export const makeEquivalence: <N extends Newtype.Any>(
  *
  * **When to use**
  *
- * Use when you need to sort or compare newtype values.
+ * Use when you need to sort newtype-wrapped values according to the ordering
+ * of the wrapped carrier value, without manually unwrapping.
  *
  * **Details**
  *
@@ -303,7 +305,8 @@ export const makeOrder: <N extends Newtype.Any>(order: Order.Order<Newtype.Carri
  *
  * **When to use**
  *
- * Use when you need to combine newtype values.
+ * Use when you need to combine newtype-wrapped values with the carrier's
+ * combining logic, without manually unwrapping.
  *
  * **Details**
  *
@@ -338,8 +341,8 @@ export const makeCombiner: <N extends Newtype.Any>(
  *
  * **When to use**
  *
- * Use when you need to fold or reduce over a collection of newtype
- * values.
+ * Use when you need to reduce a collection of newtype-wrapped values with the
+ * carrier's reducer, without manually unwrapping.
  *
  * **Details**
  *

package/src/Number.ts

@@ -393,12 +393,16 @@ export const divide: {
 )
 
 /**
- * Provides an unsafe division operation on `number`s that throws a `RangeError` if the divisor is `0`.
+ * Divides two `number` values without returning an `Option`.
  *
  * **When to use**
  *
- * Use when the divisor is known to be non-zero and division by zero should be a
- * thrown exception.
+ * Use to divide `number` values where the divisor is known to be non-zero and
+ * a plain `number` result is preferred over handling `Option.none`.
+ *
+ * **Gotchas**
+ *
+ * Throws a `RangeError` if the divisor is `0`.
  *
  * **Example** (Dividing numbers unsafely)
  *
@@ -417,12 +421,16 @@ export const divide: {
  */
 export const divideUnsafe: {
   /**
-   * Provides an unsafe division operation on `number`s that throws a `RangeError` if the divisor is `0`.
+   * Divides two `number` values without returning an `Option`.
    *
    * **When to use**
    *
-   * Use when the divisor is known to be non-zero and division by zero should be a
-   * thrown exception.
+   * Use to divide `number` values where the divisor is known to be non-zero and
+   * a plain `number` result is preferred over handling `Option.none`.
+   *
+   * **Gotchas**
+   *
+   * Throws a `RangeError` if the divisor is `0`.
    *
    * **Example** (Dividing numbers unsafely)
    *
@@ -441,12 +449,16 @@ export const divideUnsafe: {
    */
   (that: number): (self: number) => number
   /**
-   * Provides an unsafe division operation on `number`s that throws a `RangeError` if the divisor is `0`.
+   * Divides two `number` values without returning an `Option`.
    *
    * **When to use**
    *
-   * Use when the divisor is known to be non-zero and division by zero should be a
-   * thrown exception.
+   * Use to divide `number` values where the divisor is known to be non-zero and
+   * a plain `number` result is preferred over handling `Option.none`.
+   *
+   * **Gotchas**
+   *
+   * Throws a `RangeError` if the divisor is `0`.
    *
    * **Example** (Dividing numbers unsafely)
    *
@@ -517,8 +529,8 @@ export const decrement = (n: number): number => n - 1
  *
  * **When to use**
  *
- * Use when sorting or comparing numbers through APIs that accept an ordering
- * instance.
+ * Use when you need to sort or compare numbers through APIs that accept an
+ * ordering instance.
  *
  * **Example** (Comparing numbers)
  *