effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/MutableRef.ts

@@ -43,6 +43,10 @@ const TypeId = "~effect/MutableRef"
 /**
  * A synchronous mutable reference that stores a current value.
  *
+ * **When to use**
+ *
+ * Use to keep local mutable state in a stable, pipeable reference.
+ *
  * **Details**
  *
  * Read or write the value directly through `.current`, or use the `MutableRef`
@@ -103,6 +107,10 @@ const MutableRefProto: Omit<MutableRef<unknown>, "current"> = {
 /**
  * Creates a new MutableRef with the specified initial value.
  *
+ * **When to use**
+ *
+ * Use to create a synchronous mutable reference initialized with a value.
+ *
  * **Example** (Creating mutable refs)
  *
  * ```ts
@@ -132,10 +140,15 @@ export const make = <T>(value: T): MutableRef<T> => {
 }
 
 /**
- * Atomically sets the value to newValue if the current value equals oldValue.
+ * Sets the value to newValue atomically if the current value equals oldValue.
  * Returns true if the value was updated, false otherwise.
  * Uses Effect's Equal interface for value comparison.
  *
+ * **When to use**
+ *
+ * Use to replace a value only when the current value still matches an expected
+ * value.
+ *
  * **Example** (Comparing and setting values)
  *
  * ```ts
@@ -170,10 +183,15 @@ export const make = <T>(value: T): MutableRef<T> => {
  */
 export const compareAndSet: {
   /**
-   * Atomically sets the value to newValue if the current value equals oldValue.
+   * Sets the value to newValue atomically if the current value equals oldValue.
    * Returns true if the value was updated, false otherwise.
    * Uses Effect's Equal interface for value comparison.
    *
+   * **When to use**
+   *
+   * Use to replace a value only when the current value still matches an expected
+   * value.
+   *
    * **Example** (Comparing and setting values)
    *
    * ```ts
@@ -208,10 +226,15 @@ export const compareAndSet: {
    */
   <T>(oldValue: T, newValue: T): (self: MutableRef<T>) => boolean
   /**
-   * Atomically sets the value to newValue if the current value equals oldValue.
+   * Sets the value to newValue atomically if the current value equals oldValue.
    * Returns true if the value was updated, false otherwise.
    * Uses Effect's Equal interface for value comparison.
    *
+   * **When to use**
+   *
+   * Use to replace a value only when the current value still matches an expected
+   * value.
+   *
    * **Example** (Comparing and setting values)
    *
    * ```ts
@@ -259,6 +282,11 @@ export const compareAndSet: {
 /**
  * Decrements a numeric MutableRef by 1 and returns the reference.
  *
+ * **When to use**
+ *
+ * Use to decrement a numeric reference in place when you want the same
+ * reference back.
+ *
  * **Example** (Decrementing numeric refs)
  *
  * ```ts
@@ -291,6 +319,10 @@ export const decrement = (self: MutableRef<number>): MutableRef<number> => updat
 /**
  * Decrements a numeric MutableRef by 1 and returns the new value.
  *
+ * **When to use**
+ *
+ * Use to decrement a numeric reference and immediately read the updated value.
+ *
  * **Example** (Decrementing and reading refs)
  *
  * ```ts
@@ -323,6 +355,10 @@ export const decrementAndGet = (self: MutableRef<number>): number => updateAndGe
 /**
  * Gets the current value of the MutableRef.
  *
+ * **When to use**
+ *
+ * Use to read the current value without mutating the reference.
+ *
  * **Example** (Reading current values)
  *
  * ```ts
@@ -353,6 +389,10 @@ export const get = <T>(self: MutableRef<T>): T => self.current
 /**
  * Decrements a numeric MutableRef by 1 and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use to read the current numeric value before decrementing it.
+ *
  * **Example** (Reading before decrementing)
  *
  * ```ts
@@ -386,6 +426,10 @@ export const getAndDecrement = (self: MutableRef<number>): number => getAndUpdat
 /**
  * Increments a numeric MutableRef by 1 and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use to read the current numeric value before incrementing it.
+ *
  * **Example** (Reading before incrementing)
  *
  * ```ts
@@ -427,6 +471,10 @@ export const getAndIncrement = (self: MutableRef<number>): number => getAndUpdat
 /**
  * Sets the MutableRef to a new value and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use to replace the current value while keeping the previous value.
+ *
  * **Example** (Reading before setting)
  *
  * ```ts
@@ -463,6 +511,10 @@ export const getAndSet: {
   /**
    * Sets the MutableRef to a new value and returns the previous value.
    *
+   * **When to use**
+   *
+   * Use to replace the current value while keeping the previous value.
+   *
    * **Example** (Reading before setting)
    *
    * ```ts
@@ -499,6 +551,10 @@ export const getAndSet: {
   /**
    * Sets the MutableRef to a new value and returns the previous value.
    *
+   * **When to use**
+   *
+   * Use to replace the current value while keeping the previous value.
+   *
    * **Example** (Reading before setting)
    *
    * ```ts
@@ -545,6 +601,10 @@ export const getAndSet: {
  * Updates the MutableRef with the result of applying a function to its current value,
  * and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use to transform the current value while keeping the previous value.
+ *
  * **Example** (Reading before updating)
  *
  * ```ts
@@ -588,6 +648,10 @@ export const getAndUpdate: {
    * Updates the MutableRef with the result of applying a function to its current value,
    * and returns the previous value.
    *
+   * **When to use**
+   *
+   * Use to transform the current value while keeping the previous value.
+   *
    * **Example** (Reading before updating)
    *
    * ```ts
@@ -631,6 +695,10 @@ export const getAndUpdate: {
    * Updates the MutableRef with the result of applying a function to its current value,
    * and returns the previous value.
    *
+   * **When to use**
+   *
+   * Use to transform the current value while keeping the previous value.
+   *
    * **Example** (Reading before updating)
    *
    * ```ts
@@ -678,6 +746,11 @@ export const getAndUpdate: {
 /**
  * Increments a numeric MutableRef by 1 and returns the reference.
  *
+ * **When to use**
+ *
+ * Use to increment a numeric reference in place when you want the same
+ * reference back.
+ *
  * **Example** (Incrementing numeric refs)
  *
  * ```ts
@@ -713,6 +786,10 @@ export const increment = (self: MutableRef<number>): MutableRef<number> => updat
 /**
  * Increments a numeric MutableRef by 1 and returns the new value.
  *
+ * **When to use**
+ *
+ * Use to increment a numeric reference and immediately read the updated value.
+ *
  * **Example** (Incrementing and reading refs)
  *
  * ```ts
@@ -749,6 +826,11 @@ export const incrementAndGet = (self: MutableRef<number>): number => updateAndGe
 /**
  * Sets the MutableRef to a new value and returns the reference.
  *
+ * **When to use**
+ *
+ * Use to replace the current value in place when you want the same reference
+ * back.
+ *
  * **Example** (Setting values)
  *
  * ```ts
@@ -789,6 +871,11 @@ export const set: {
   /**
    * Sets the MutableRef to a new value and returns the reference.
    *
+   * **When to use**
+   *
+   * Use to replace the current value in place when you want the same reference
+   * back.
+   *
    * **Example** (Setting values)
    *
    * ```ts
@@ -829,6 +916,11 @@ export const set: {
   /**
    * Sets the MutableRef to a new value and returns the reference.
    *
+   * **When to use**
+   *
+   * Use to replace the current value in place when you want the same reference
+   * back.
+   *
    * **Example** (Setting values)
    *
    * ```ts
@@ -877,6 +969,10 @@ export const set: {
 /**
  * Sets the MutableRef to a new value and returns the new value.
  *
+ * **When to use**
+ *
+ * Use to replace the current value and immediately read the replacement.
+ *
  * **Example** (Setting and reading values)
  *
  * ```ts
@@ -913,6 +1009,10 @@ export const setAndGet: {
   /**
    * Sets the MutableRef to a new value and returns the new value.
    *
+   * **When to use**
+   *
+   * Use to replace the current value and immediately read the replacement.
+   *
    * **Example** (Setting and reading values)
    *
    * ```ts
@@ -949,6 +1049,10 @@ export const setAndGet: {
   /**
    * Sets the MutableRef to a new value and returns the new value.
    *
+   * **When to use**
+   *
+   * Use to replace the current value and immediately read the replacement.
+   *
    * **Example** (Setting and reading values)
    *
    * ```ts
@@ -994,6 +1098,11 @@ export const setAndGet: {
  * Updates the MutableRef with the result of applying a function to its current value,
  * and returns the reference.
  *
+ * **When to use**
+ *
+ * Use to transform the current value in place when you want the same reference
+ * back.
+ *
  * **Example** (Updating values)
  *
  * ```ts
@@ -1039,6 +1148,11 @@ export const update: {
    * Updates the MutableRef with the result of applying a function to its current value,
    * and returns the reference.
    *
+   * **When to use**
+   *
+   * Use to transform the current value in place when you want the same reference
+   * back.
+   *
    * **Example** (Updating values)
    *
    * ```ts
@@ -1084,6 +1198,11 @@ export const update: {
    * Updates the MutableRef with the result of applying a function to its current value,
    * and returns the reference.
    *
+   * **When to use**
+   *
+   * Use to transform the current value in place when you want the same reference
+   * back.
+   *
    * **Example** (Updating values)
    *
    * ```ts
@@ -1134,6 +1253,10 @@ export const update: {
  * Updates the MutableRef with the result of applying a function to its current value,
  * and returns the new value.
  *
+ * **When to use**
+ *
+ * Use to transform the current value and immediately read the updated value.
+ *
  * **Example** (Updating and reading values)
  *
  * ```ts
@@ -1181,6 +1304,10 @@ export const updateAndGet: {
    * Updates the MutableRef with the result of applying a function to its current value,
    * and returns the new value.
    *
+   * **When to use**
+   *
+   * Use to transform the current value and immediately read the updated value.
+   *
    * **Example** (Updating and reading values)
    *
    * ```ts
@@ -1228,6 +1355,10 @@ export const updateAndGet: {
    * Updates the MutableRef with the result of applying a function to its current value,
    * and returns the new value.
    *
+   * **When to use**
+   *
+   * Use to transform the current value and immediately read the updated value.
+   *
    * **Example** (Updating and reading values)
    *
    * ```ts
@@ -1277,7 +1408,13 @@ export const updateAndGet: {
 >(2, (self, f) => setAndGet(self, f(get(self))))
 
 /**
- * Toggles a boolean MutableRef (true becomes false, false becomes true) and returns the reference.
+ * Switches a boolean `MutableRef` between `true` and `false`, then returns the
+ * reference.
+ *
+ * **When to use**
+ *
+ * Use to flip a boolean reference in place when you want the same reference
+ * back.
  *
  * **Example** (Toggling boolean refs)
  *

package/src/Newtype.ts

@@ -78,9 +78,9 @@ const TypeId = "~effect/Newtype"
  *
  * **When to use**
  *
- * Define your newtype as an `interface` extending
- * `Newtype<"MyKey", CarrierType>` when you need two structurally identical
- * carrier types to remain distinct in TypeScript.
+ * Use to define a newtype as an `interface` extending
+ * `Newtype<"MyKey", CarrierType>` when structurally identical carrier types
+ * should remain distinct in TypeScript.
  *
  * **Details**
  *
@@ -116,6 +116,11 @@ export interface Newtype<in out Key extends string, out Carrier> {
  * Namespace containing type-level helpers for `Newtype` values, including
  * constraints and utilities for extracting a newtype's key and carrier type.
  *
+ * **When to use**
+ *
+ * Use to access generic constraints and type-level utilities for `Newtype`
+ * values.
+ *
  * @since 4.0.0
  */
 export declare namespace Newtype {
@@ -123,6 +128,10 @@ export declare namespace Newtype {
    * A type that matches any `Newtype`, useful as a generic constraint:
    * `<N extends Newtype.Any>`.
    *
+   * **When to use**
+   *
+   * Use as a generic constraint when a type parameter can be any `Newtype`.
+   *
    * @see {@link Newtype} — the base tagged interface
    *
    * @category utility types
@@ -135,7 +144,7 @@ export declare namespace Newtype {
    *
    * **When to use**
    *
-   * Use this in generic code that needs to inspect or constrain the key.
+   * Use to inspect or constrain a newtype's key in generic code.
    *
    * @category utility types
    * @since 4.0.0
@@ -147,7 +156,7 @@ export declare namespace Newtype {
    *
    * **When to use**
    *
-   * Use this when you need to refer to the wrapped type in generic utilities.
+   * Use when you need to refer to the wrapped type in generic utilities.
    *
    * @category utility types
    * @since 4.0.0
@@ -160,7 +169,7 @@ export declare namespace Newtype {
  *
  * **When to use**
  *
- * Use this when you only need to read the inner value and do not need to wrap
+ * 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}.
  *
  * **Details**
@@ -193,7 +202,7 @@ export const value: <N extends Newtype.Any>(newtype: N) => Newtype.Carrier<N> =
  *
  * **When to use**
  *
- * Use this as the primary way to construct and deconstruct newtype values.
+ * Use as the primary way to construct and deconstruct newtype values.
  *
  * **Details**
  *
@@ -228,7 +237,7 @@ export function makeIso<N extends Newtype.Any>(): Optic.Iso<N, Newtype.Carrier<N
  *
  * **When to use**
  *
- * Use this when you need to compare two newtype values for equality.
+ * Use when you need to compare two newtype values for equality.
  *
  * **Details**
  *
@@ -263,7 +272,7 @@ export const makeEquivalence: <N extends Newtype.Any>(
  *
  * **When to use**
  *
- * Use this when you need to sort or compare newtype values.
+ * Use when you need to sort or compare newtype values.
  *
  * **Details**
  *
@@ -294,7 +303,7 @@ export const makeOrder: <N extends Newtype.Any>(order: Order.Order<Newtype.Carri
  *
  * **When to use**
  *
- * Use this when you need to combine newtype values.
+ * Use when you need to combine newtype values.
  *
  * **Details**
  *
@@ -329,7 +338,7 @@ export const makeCombiner: <N extends Newtype.Any>(
  *
  * **When to use**
  *
- * Use this when you need to fold or reduce over a collection of newtype
+ * Use when you need to fold or reduce over a collection of newtype
  * values.
  *
  * **Details**

package/src/NonEmptyIterable.ts

@@ -143,15 +143,22 @@
  */
 
 /**
- * A unique symbol used to brand the `NonEmptyIterable` type.
+ * Defines the type-level symbol used to brand the `NonEmptyIterable` type.
+ *
+ * **When to use**
+ *
+ * Use as the property key for the type-level brand that marks an `Iterable` as
+ * non-empty.
  *
  * **Details**
  *
- * This symbol ensures that `NonEmptyIterable<A>` is a distinct type from regular
- * `Iterable<A>`, providing compile-time guarantees about non-emptiness while
- * maintaining full compatibility with the JavaScript iteration protocol.
+ * `NonEmptyIterable<A>` includes `readonly [nonEmpty]: A`, which makes it
+ * distinct from a plain `Iterable<A>` at compile time while preserving the
+ * normal iteration shape.
  *
- * @category symbol
+ * @see {@link NonEmptyIterable} for the branded iterable type that uses this symbol
+ *
+ * @category symbols
  * @since 2.0.0
  */
 export declare const nonEmpty: unique symbol
@@ -159,6 +166,10 @@ export declare const nonEmpty: unique symbol
 /**
  * Represents an iterable that is guaranteed to contain at least one element.
  *
+ * **When to use**
+ *
+ * Use to require an iterable input that must provide at least one element.
+ *
  * **Details**
  *
  * `NonEmptyIterable<A>` extends the standard `Iterable<A>` interface with a type-level
@@ -218,7 +229,12 @@ export interface NonEmptyIterable<out A> extends Iterable<A> {
 }
 
 /**
- * Safely extracts the first element and remaining elements from a non-empty iterable.
+ * Extracts the first element and remaining elements from a non-empty iterable safely.
+ *
+ * **When to use**
+ *
+ * Use to split a non-empty iterable into its first element and an iterator for
+ * the remaining elements.
  *
  * **Details**
  *