effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/MutableHashMap.ts

@@ -106,7 +106,7 @@ export interface MutableHashMap<out K, out V> extends Iterable<[K, V]>, Pipeable
 }
 
 /**
- * Checks if the specified value is a `MutableHashMap`, `false` otherwise.
+ * Checks whether the specified value is a `MutableHashMap`, `false` otherwise.
  *
  * **When to use**
  *
@@ -265,7 +265,7 @@ export const fromIterable = <K, V>(entries: Iterable<readonly [K, V]>): MutableH
 }
 
 /**
- * Looks up a key in the `MutableHashMap`.
+ * Looks up a key in the `MutableHashMap` safely.
  *
  * **When to use**
  *
@@ -299,7 +299,7 @@ export const fromIterable = <K, V>(entries: Iterable<readonly [K, V]>): MutableH
  */
 export const get: {
   /**
-   * Looks up a key in the `MutableHashMap`.
+   * Looks up a key in the `MutableHashMap` safely.
    *
    * **When to use**
    *
@@ -333,7 +333,7 @@ export const get: {
    */
   <K>(key: K): <V>(self: MutableHashMap<K, V>) => Option.Option<V>
   /**
-   * Looks up a key in the `MutableHashMap`.
+   * Looks up a key in the `MutableHashMap` safely.
    *
    * **When to use**
    *
@@ -368,7 +368,7 @@ export const get: {
   <K, V>(self: MutableHashMap<K, V>, key: K): Option.Option<V>
 } = dual<
   /**
-   * Looks up a key in the `MutableHashMap`.
+   * Looks up a key in the `MutableHashMap` safely.
    *
    * **When to use**
    *
@@ -402,7 +402,7 @@ export const get: {
    */
   <K>(key: K) => <V>(self: MutableHashMap<K, V>) => Option.Option<V>,
   /**
-   * Looks up a key in the `MutableHashMap`.
+   * Looks up a key in the `MutableHashMap` safely.
    *
    * **When to use**
    *
@@ -542,7 +542,7 @@ const getFromBucket = <K, V>(
 }
 
 /**
- * Checks if the MutableHashMap contains the specified key.
+ * Checks whether the MutableHashMap contains the specified key.
  *
  * **When to use**
  *
@@ -570,7 +570,7 @@ const getFromBucket = <K, V>(
  */
 export const has: {
   /**
-   * Checks if the MutableHashMap contains the specified key.
+   * Checks whether the MutableHashMap contains the specified key.
    *
    * **When to use**
    *
@@ -598,7 +598,7 @@ export const has: {
    */
   <K>(key: K): <V>(self: MutableHashMap<K, V>) => boolean
   /**
-   * Checks if the MutableHashMap contains the specified key.
+   * Checks whether the MutableHashMap contains the specified key.
    *
    * **When to use**
    *
@@ -627,7 +627,7 @@ export const has: {
   <K, V>(self: MutableHashMap<K, V>, key: K): boolean
 } = dual<
   /**
-   * Checks if the MutableHashMap contains the specified key.
+   * Checks whether the MutableHashMap contains the specified key.
    *
    * **When to use**
    *
@@ -655,7 +655,7 @@ export const has: {
    */
   <K>(key: K) => <V>(self: MutableHashMap<K, V>) => boolean,
   /**
-   * Checks if the MutableHashMap contains the specified key.
+   * Checks whether the MutableHashMap contains the specified key.
    *
    * **When to use**
    *
@@ -1150,10 +1150,8 @@ export const modify: {
 })
 
 /**
- * Sets or removes the specified key in the MutableHashMap using an update function.
- * The function receives the current value as an Option and returns an Option.
- * If the function returns Some, the key is set to that value.
- * If the function returns None, the key is removed.
+ * Updates or removes the specified key using a function from the current
+ * optional value to the next optional value.
  *
  * **When to use**
  *
@@ -1205,10 +1203,8 @@ export const modify: {
  */
 export const modifyAt: {
   /**
-   * Sets or removes the specified key in the MutableHashMap using an update function.
-   * The function receives the current value as an Option and returns an Option.
-   * If the function returns Some, the key is set to that value.
-   * If the function returns None, the key is removed.
+   * Updates or removes the specified key using a function from the current
+   * optional value to the next optional value.
    *
    * **When to use**
    *
@@ -1260,10 +1256,8 @@ export const modifyAt: {
    */
   <K, V>(key: K, f: (value: Option.Option<V>) => Option.Option<V>): (self: MutableHashMap<K, V>) => MutableHashMap<K, V>
   /**
-   * Sets or removes the specified key in the MutableHashMap using an update function.
-   * The function receives the current value as an Option and returns an Option.
-   * If the function returns Some, the key is set to that value.
-   * If the function returns None, the key is removed.
+   * Updates or removes the specified key using a function from the current
+   * optional value to the next optional value.
    *
    * **When to use**
    *
@@ -1320,10 +1314,8 @@ export const modifyAt: {
   ): MutableHashMap<K, V>
 } = dual<
   /**
-   * Sets or removes the specified key in the MutableHashMap using an update function.
-   * The function receives the current value as an Option and returns an Option.
-   * If the function returns Some, the key is set to that value.
-   * If the function returns None, the key is removed.
+   * Updates or removes the specified key using a function from the current
+   * optional value to the next optional value.
    *
    * **When to use**
    *
@@ -1375,10 +1367,8 @@ export const modifyAt: {
    */
   <K, V>(key: K, f: (value: Option.Option<V>) => Option.Option<V>) => (self: MutableHashMap<K, V>) => MutableHashMap<K, V>,
   /**
-   * Sets or removes the specified key in the MutableHashMap using an update function.
-   * The function receives the current value as an Option and returns an Option.
-   * If the function returns Some, the key is set to that value.
-   * If the function returns None, the key is removed.
+   * Updates or removes the specified key using a function from the current
+   * optional value to the next optional value.
    *
    * **When to use**
    *

package/src/MutableHashSet.ts

@@ -128,7 +128,7 @@ export interface MutableHashSet<out V> extends Iterable<V>, Pipeable, Inspectabl
 }
 
 /**
- * Checks if the specified value is a `MutableHashSet`, `false` otherwise.
+ * Checks whether the specified value is a `MutableHashSet`, `false` otherwise.
  *
  * **When to use**
  *
@@ -396,7 +396,7 @@ export const add: {
 >(2, (self, key) => (MutableHashMap.set(self.keyMap, key, true), self))
 
 /**
- * Checks if the MutableHashSet contains the specified value.
+ * Checks whether the MutableHashSet contains the specified value.
  *
  * **When to use**
  *
@@ -434,7 +434,7 @@ export const add: {
  */
 export const has: {
   /**
-   * Checks if the MutableHashSet contains the specified value.
+   * Checks whether the MutableHashSet contains the specified value.
    *
    * **When to use**
    *
@@ -472,7 +472,7 @@ export const has: {
    */
   <V>(key: V): (self: MutableHashSet<V>) => boolean
   /**
-   * Checks if the MutableHashSet contains the specified value.
+   * Checks whether the MutableHashSet contains the specified value.
    *
    * **When to use**
    *

package/src/MutableList.ts

@@ -172,9 +172,14 @@ export declare namespace MutableList {
 }
 
 /**
- * A unique symbol used to represent an empty result when taking elements from a MutableList.
+ * Defines the unique symbol used to represent an empty result when taking elements from a MutableList.
  * This symbol is returned by `take` when the list is empty, allowing for safe type checking.
  *
+ * **When to use**
+ *
+ * Use to detect that `take` returned no element before handling the result as a
+ * list item.
+ *
  * **Example** (Checking for empty results)
  *
  * ```ts
@@ -205,7 +210,7 @@ export declare namespace MutableList {
  * console.log(empty === MutableList.Empty) // true, list is empty
  * ```
  *
- * @category Symbols
+ * @category symbols
  * @since 4.0.0
  */
 export const Empty: unique symbol = Symbol.for("effect/MutableList/Empty")
@@ -255,7 +260,7 @@ export const Empty: unique symbol = Symbol.for("effect/MutableList/Empty")
  * }
  * ```
  *
- * @category Symbols
+ * @category symbols
  * @since 4.0.0
  */
 export type Empty = typeof Empty
@@ -830,7 +835,10 @@ export const take = <A>(self: MutableList<A>): Empty | A => {
  *
  * **When to use**
  *
- * Use when the copied elements should also be removed from the list.
+ * Use when you need to inspect or snapshot a bounded prefix of the list without
+ * consuming it.
+ *
+ * @see {@link takeN} for removing up to `n` values and returning them as an array
  *
  * @category elements
  * @since 4.0.0
@@ -856,8 +864,10 @@ export const toArrayN = <A>(self: MutableList<A>, n: number): Array<A> => {
  *
  * **When to use**
  *
- * Use when the list should be emptied after converting it to an
- * array.
+ * Use when you need a snapshot of all current elements while keeping the list
+ * unchanged.
+ *
+ * @see {@link takeAll} for converting all elements to an array and clearing the list
  *
  * @category elements
  * @since 4.0.0

package/src/MutableRef.ts

@@ -140,7 +140,7 @@ 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.
  *
@@ -183,7 +183,7 @@ 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.
    *
@@ -226,7 +226,7 @@ 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.
    *
@@ -1408,7 +1408,8 @@ 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**
  *

package/src/NonEmptyIterable.ts

@@ -143,7 +143,7 @@
  */
 
 /**
- * Type-level symbol used to brand the `NonEmptyIterable` type.
+ * Defines the type-level symbol used to brand the `NonEmptyIterable` type.
  *
  * **When to use**
  *
@@ -158,7 +158,7 @@
  *
  * @see {@link NonEmptyIterable} for the branded iterable type that uses this symbol
  *
- * @category symbol
+ * @category symbols
  * @since 2.0.0
  */
 export declare const nonEmpty: unique symbol
@@ -229,7 +229,7 @@ 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**
  *

package/src/Number.ts

@@ -67,11 +67,11 @@ import * as predicate from "./Predicate.ts"
 import * as Reducer from "./Reducer.ts"
 
 /**
- * The global `Number` constructor.
+ * Exposes the global number constructor.
  *
  * **When to use**
  *
- * Use when you want native `Number` constructor coercion from the Effect module
+ * Use to access native JavaScript numeric coercion from the Effect module
  * namespace.
  *
  * **Gotchas**
@@ -99,7 +99,7 @@ import * as Reducer from "./Reducer.ts"
 export const Number = globalThis.Number
 
 /**
- * Tests if a value is a `number`.
+ * Checks whether a value is a `number`.
  *
  * **When to use**
  *
@@ -319,7 +319,7 @@ export const subtract: {
 } = dual(2, (self: number, that: number): number => self - that)
 
 /**
- * Provides a division operation on `number`s, returning `Option.none()` if the divisor is `0`.
+ * Divides `number`s safely, returning `Option.none()` if the divisor is `0`.
  *
  * **When to use**
  *
@@ -342,7 +342,7 @@ export const subtract: {
  */
 export const divide: {
   /**
-   * Provides a division operation on `number`s, returning `Option.none()` if the divisor is `0`.
+   * Divides `number`s safely, returning `Option.none()` if the divisor is `0`.
    *
    * **When to use**
    *
@@ -365,7 +365,7 @@ export const divide: {
    */
   (that: number): (self: number) => Option.Option<number>
   /**
-   * Provides a division operation on `number`s, returning `Option.none()` if the divisor is `0`.
+   * Divides `number`s safely, returning `Option.none()` if the divisor is `0`.
    *
    * **When to use**
    *
@@ -513,11 +513,12 @@ export const increment = (n: number): number => n + 1
 export const decrement = (n: number): number => n - 1
 
 /**
- * An `Order` instance for `number` values.
+ * Order instance for `number` values.
  *
  * **When to use**
  *
- * Use when an API needs an `Order` instance for numbers.
+ * Use when sorting or comparing numbers through APIs that accept an ordering
+ * instance.
  *
  * **Example** (Comparing numbers)
  *
@@ -535,11 +536,12 @@ export const decrement = (n: number): number => n - 1
 export const Order: order.Order<number> = order.Number
 
 /**
- * An `Equivalence` instance for numbers where `NaN` is considered equal to `NaN`.
+ * Equivalence instance for numbers where `NaN` is considered equal to `NaN`.
  *
  * **When to use**
  *
- * Use when an API needs an `Equivalence` instance for numeric equality.
+ * Use when checking numeric equality through APIs that accept an equivalence
+ * relation.
  *
  * **Example** (Comparing numbers for equivalence)
  *
@@ -829,7 +831,7 @@ export const isGreaterThanOrEqualTo: {
 } = order.isGreaterThanOrEqualTo(Order)
 
 /**
- * Checks if a `number` is between a `minimum` and `maximum` value (inclusive).
+ * Checks whether a `number` is between a `minimum` and `maximum` value (inclusive).
  *
  * **When to use**
  *
@@ -855,7 +857,7 @@ export const isGreaterThanOrEqualTo: {
  */
 export const between: {
   /**
-   * Checks if a `number` is between a `minimum` and `maximum` value (inclusive).
+   * Checks whether a `number` is between a `minimum` and `maximum` value (inclusive).
    *
    * **When to use**
    *
@@ -886,7 +888,7 @@ export const between: {
     }
   ): (self: number) => boolean
   /**
-   * Checks if a `number` is between a `minimum` and `maximum` value (inclusive).
+   * Checks whether a `number` is between a `minimum` and `maximum` value (inclusive).
    *
    * **When to use**
    *
@@ -1371,7 +1373,7 @@ export const nextPow2 = (n: number): number => {
 }
 
 /**
- * Tries to parse a `number` from a `string` using the `Number()` function.
+ * Parses a `number` from a `string` safely using the `Number()` function.
  * The following special string values are supported: "NaN", "Infinity", "-Infinity".
  *
  * **When to use**
@@ -1482,7 +1484,7 @@ export const round: {
 })
 
 /**
- * A `Reducer` for combining `number`s using addition.
+ * Reducer for combining `number`s using addition.
  *
  * **When to use**
  *
@@ -1501,7 +1503,7 @@ export const round: {
 export const ReducerSum: Reducer.Reducer<number> = Reducer.make((a, b) => a + b, 0)
 
 /**
- * A `Reducer` for combining `number`s using multiplication.
+ * Reducer for combining `number`s using multiplication.
  *
  * **When to use**
  *
@@ -1531,7 +1533,7 @@ export const ReducerMultiply: Reducer.Reducer<number> = Reducer.make((a, b) => a
 })
 
 /**
- * A `Reducer` for reducing `number`s by keeping the maximum value.
+ * Reducer for reducing `number`s by keeping the maximum value.
  *
  * **When to use**
  *
@@ -1555,7 +1557,7 @@ export const ReducerMultiply: Reducer.Reducer<number> = Reducer.make((a, b) => a
 export const ReducerMax: Reducer.Reducer<number> = Reducer.make((a, b) => Math.max(a, b), -Infinity)
 
 /**
- * A `Reducer` for reducing `number`s by keeping the minimum value.
+ * Reducer for reducing `number`s by keeping the minimum value.
  *
  * **When to use**
  *

package/src/Optic.ts

@@ -157,7 +157,6 @@ export interface Iso<in out S, in out A> extends Lens<S, A>, Prism<S, A> {}
  *
  * **Details**
  *
- * - Does not mutate inputs.
  * - The returned optic can be composed with any other optic.
  *
  * **Example** (wrapping/unwrapping a branded type)
@@ -239,7 +238,6 @@ export interface Lens<in out S, in out A> extends Optional<S, A> {
  *
  * **Details**
  *
- * - Does not mutate inputs.
  * - `replace(a, s)` should return a structurally new `S` with `a` in place
  *   of the old focus.
  *
@@ -328,7 +326,6 @@ export interface Prism<in out S, in out A> extends Optional<S, A> {
  *
  * **Details**
  *
- * - Does not mutate inputs.
  * - `getResult` should return `Result.fail(message)` on mismatch.
  *
  * **Example** (parsing a string to a number)
@@ -375,7 +372,6 @@ export function makePrism<S, A>(getResult: (s: S) => Result.Result<A, string>, s
  * - `getResult` runs all checks; fails with a combined error message when
  *   any check fails.
  * - `set` is identity — the value passes through unchanged.
- * - Does not mutate inputs.
  *
  * **Example** (positive integer prism)
  *
@@ -546,10 +542,10 @@ type ForbidUnion<A, Message extends string> = IsUnion<A> extends true ? [Message
  *
  * **When to use**
  *
- * Use when the focus may not exist in `S` **and** writing a new `A` back may also
- *   fail (e.g. the source no longer matches the expected shape).
- * - As the base type: every optic ({@link Iso}, {@link Lens}, {@link Prism},
- *   {@link Traversal}) extends `Optional`.
+ * Use when the focus may not exist in `S` and writing a new `A` back may also
+ * fail, for example when the source no longer matches the expected shape. This
+ * is the base type extended by {@link Iso}, {@link Lens}, {@link Prism}, and
+ * {@link Traversal}.
  *
  * **Details**
  *
@@ -1034,7 +1030,6 @@ export interface Optional<in out S, in out A> {
  *
  * **Details**
  *
- * - Does not mutate inputs.
  * - `getResult` should return `Result.fail(message)` on mismatch.
  * - `set` should return `Result.fail(message)` when the update cannot be
  *   applied.
@@ -1480,7 +1475,6 @@ function getCompositionTag(a: Op["_tag"], b: Op["_tag"]): Op["_tag"] {
  *
  * - Returns an empty array when the traversal cannot focus.
  * - Always returns a fresh array (safe to mutate).
- * - Does not mutate the source.
  *
  * **Example** (collecting positive numbers)
  *
@@ -1522,12 +1516,11 @@ export function getAll<S, A>(traversal: Traversal<S, A>): (s: S) => Array<A> {
 const identityIso = make(identityNode)
 
 /**
- * The identity {@link Iso}. Focuses on the whole value unchanged.
+ * Iso that focuses on the whole value unchanged.
  *
  * **When to use**
  *
- * Use when as the starting point of an optic chain: `Optic.id<S>().key("x")...`
- * - Anywhere an `Iso<S, S>` is needed.
+ * Use when starting an optic chain with a focus on the whole value.
  *
  * **Details**
  *
@@ -1558,7 +1551,7 @@ export function id<S>(): Iso<S, S> {
 }
 
 /**
- * An {@link Iso} that converts a `Record<string, A>` to an array of
+ * Iso that converts a `Record<string, A>` to an array of
  * `[key, value]` entries and back.
  *
  * **When to use**
@@ -1597,7 +1590,7 @@ export function entries<A>(): Iso<Record<string, A>, ReadonlyArray<readonly [str
 }
 
 /**
- * A {@link Prism} that focuses on the value inside `Option.Some`.
+ * Prism that focuses on the value inside `Option.Some`.
  *
  * **When to use**
  *
@@ -1645,7 +1638,7 @@ export function some<A>(): Prism<Option.Option<A>, A> {
 }
 
 /**
- * A {@link Prism} that focuses on `Option.None`, exposing `undefined`.
+ * Prism that focuses on `Option.None`, exposing `undefined`.
  *
  * **When to use**
  *
@@ -1690,7 +1683,7 @@ export function none<A>(): Prism<Option.Option<A>, undefined> {
 }
 
 /**
- * A {@link Prism} that focuses on the success value of a `Result`.
+ * Prism that focuses on the success value of a `Result`.
  *
  * **When to use**
  *
@@ -1735,7 +1728,7 @@ export function success<A, E>(): Prism<Result.Result<A, E>, A> {
 }
 
 /**
- * A {@link Prism} that focuses on the failure value of a `Result`.
+ * Prism that focuses on the failure value of a `Result`.
  *
  * **When to use**
  *