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

package/src/MutableHashMap.ts

@@ -1,25 +1,40 @@
 /**
- * MutableHashMap is a high-performance, mutable hash map implementation designed for efficient key-value storage
- * with support for both structural and referential equality. It provides O(1) average-case performance for
- * basic operations and integrates seamlessly with Effect's Equal and Hash interfaces.
- *
- * The implementation uses a hybrid approach:
- * - Referential keys (without Equal implementation) are stored in a native Map
- * - Structural keys (with Equal implementation) are stored in hash buckets with collision handling
- *
- * Key Features:
- * - Mutable operations for performance-critical scenarios
- * - Supports both structural and referential equality
- * - Efficient collision handling through bucketing
- * - Iterable interface for easy traversal
- * - Memory-efficient storage with automatic bucket management
- *
- * Performance Characteristics:
- * - Get/Set/Has: O(1) average, O(n) worst case (hash collisions)
- * - Remove: O(1) average, O(n) worst case
- * - Clear: O(1)
- * - Size: O(1)
- * - Iteration: O(n)
+ * `MutableHashMap` is an in-place key-value map with fast lookup, insertion,
+ * removal, clearing, and iteration. It combines a native `Map` for ordinary
+ * JavaScript keys with hash buckets for keys that implement Effect `Equal` /
+ * `Hash`, so callers can mix referential and structural lookup in the same
+ * collection.
+ *
+ * **Mental model**
+ *
+ * - `MutableHashMap<K, V>` stores entries on a single mutable map instance
+ * - {@link set}, {@link remove}, and {@link clear} mutate that instance and
+ *   return it for convenient piping
+ * - Keys that implement `Equal` / `Hash` are matched structurally through hash
+ *   buckets; other keys use JavaScript map semantics
+ * - The map is iterable as `[key, value]` pairs and reports size in O(1)
+ *
+ * **Common tasks**
+ *
+ * - Create maps: {@link empty}, {@link make}, {@link fromIterable}
+ * - Read entries: {@link get}, {@link has}, {@link size}
+ * - Mutate entries: {@link set}, {@link modify}, {@link remove}, {@link clear}
+ * - Narrow unknown values: {@link isMutableHashMap}
+ *
+ * **Gotchas**
+ *
+ * - This data structure is intentionally mutable; share it only when callers
+ *   agree on ownership
+ * - Mutating a structural key after insertion can make future lookups fail if
+ *   its equality or hash changes
+ * - Iteration follows the underlying storage order and should not be used as a
+ *   sorting guarantee
+ *
+ * **Performance**
+ *
+ * - Lookup, insertion, removal, clearing, and size are O(1) on average
+ * - Hash collisions can make key lookup and removal O(n)
+ * - Iteration is O(n)
  *
  * @since 2.0.0
  */
@@ -40,6 +55,11 @@ const TypeId = "~effect/collections/MutableHashMap"
  * A mutable hash map that stores key-value pairs and supports both referential
  * and Effect structural equality.
  *
+ * **When to use**
+ *
+ * Use as a mutable key-value map when in-place updates are acceptable and keys
+ * may rely on Effect structural equality.
+ *
  * **Details**
  *
  * Operations mutate the map in place. Keys that implement `Equal` / `Hash` can
@@ -72,6 +92,10 @@ const TypeId = "~effect/collections/MutableHashMap"
  * console.log(entries) // [["count", 42], ["total", 100]]
  * ```
  *
+ * @see {@link empty} for creating an empty mutable hash map
+ * @see {@link get} for reading values by key
+ * @see {@link set} for mutating entries by key
+ *
  * @category models
  * @since 2.0.0
  */
@@ -82,7 +106,21 @@ 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**
+ *
+ * Use to narrow an unknown value before treating it as a mutable hash map.
+ *
+ * **Details**
+ *
+ * The check looks for the `MutableHashMap` runtime marker.
+ *
+ * **Gotchas**
+ *
+ * The check does not validate the key or value types carried by the map.
+ *
+ * @see {@link MutableHashMap} for the mutable hash map interface
  *
  * @category refinements
  * @since 4.0.0
@@ -114,6 +152,14 @@ const MutableHashMapProto: Omit<MutableHashMap<unknown, unknown>, "backing" | "b
 /**
  * Creates an empty MutableHashMap.
  *
+ * **When to use**
+ *
+ * Use to create a fresh mutable map before adding entries over time.
+ *
+ * **Details**
+ *
+ * Each call returns a new empty map instance.
+ *
  * **Example** (Creating an empty map)
  *
  * ```ts
@@ -128,6 +174,9 @@ const MutableHashMapProto: Omit<MutableHashMap<unknown, unknown>, "backing" | "b
  * console.log(MutableHashMap.size(map)) // 2
  * ```
  *
+ * @see {@link make} for creating a map from explicit entries
+ * @see {@link fromIterable} for creating a map from an iterable of entries
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -141,6 +190,10 @@ export const empty = <K, V>(): MutableHashMap<K, V> => {
 /**
  * Creates a MutableHashMap from a variable number of key-value pairs.
  *
+ * **When to use**
+ *
+ * Use to create a mutable hash map from explicit entries known at the call site.
+ *
  * **Example** (Creating a map from entries)
  *
  * ```ts
@@ -156,6 +209,9 @@ export const empty = <K, V>(): MutableHashMap<K, V> => {
  * console.log(MutableHashMap.size(map)) // 3
  * ```
  *
+ * @see {@link empty} for creating an empty map
+ * @see {@link fromIterable} for creating a map from an iterable of entries
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -169,6 +225,10 @@ export const make: <Entries extends Array<readonly [any, any]>>(
 /**
  * Creates a MutableHashMap from an iterable collection of key-value pairs.
  *
+ * **When to use**
+ *
+ * Use to create a mutable hash map from an existing iterable of entries.
+ *
  * **Example** (Creating a map from an iterable)
  *
  * ```ts
@@ -190,6 +250,9 @@ export const make: <Entries extends Array<readonly [any, any]>>(
  * console.log(MutableHashMap.get(fromMap, "x")) // Some(10)
  * ```
  *
+ * @see {@link make} for creating a map from explicit entries
+ * @see {@link empty} for creating an empty map
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -202,7 +265,11 @@ 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**
+ *
+ * Use to safely read the value for a key as an `Option`.
  *
  * **Details**
  *
@@ -224,12 +291,19 @@ export const fromIterable = <K, V>(entries: Iterable<readonly [K, V]>): MutableH
  * console.log(getValue(map)) // Some(42)
  * ```
  *
+ * @see {@link has} for checking only whether a key is present
+ * @see {@link set} for inserting or replacing a value by key
+ *
  * @category elements
  * @since 2.0.0
  */
 export const get: {
   /**
-   * Looks up a key in the `MutableHashMap`.
+   * Looks up a key in the `MutableHashMap` safely.
+   *
+   * **When to use**
+   *
+   * Use to safely read the value for a key as an `Option`.
    *
    * **Details**
    *
@@ -251,12 +325,19 @@ export const get: {
    * console.log(getValue(map)) // Some(42)
    * ```
    *
+   * @see {@link has} for checking only whether a key is present
+   * @see {@link set} for inserting or replacing a value by key
+   *
    * @category elements
    * @since 2.0.0
    */
   <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**
+   *
+   * Use to safely read the value for a key as an `Option`.
    *
    * **Details**
    *
@@ -278,13 +359,20 @@ export const get: {
    * console.log(getValue(map)) // Some(42)
    * ```
    *
+   * @see {@link has} for checking only whether a key is present
+   * @see {@link set} for inserting or replacing a value by key
+   *
    * @category elements
    * @since 2.0.0
    */
   <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**
+   *
+   * Use to safely read the value for a key as an `Option`.
    *
    * **Details**
    *
@@ -306,12 +394,19 @@ export const get: {
    * console.log(getValue(map)) // Some(42)
    * ```
    *
+   * @see {@link has} for checking only whether a key is present
+   * @see {@link set} for inserting or replacing a value by key
+   *
    * @category elements
    * @since 2.0.0
    */
   <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**
+   *
+   * Use to safely read the value for a key as an `Option`.
    *
    * **Details**
    *
@@ -333,6 +428,9 @@ export const get: {
    * console.log(getValue(map)) // Some(42)
    * ```
    *
+   * @see {@link has} for checking only whether a key is present
+   * @see {@link set} for inserting or replacing a value by key
+   *
    * @category elements
    * @since 2.0.0
    */
@@ -361,6 +459,10 @@ const isSimpleKey = (u: unknown): boolean => typeof u !== "object" && typeof u !
 /**
  * Returns an iterable over the keys in the `MutableHashMap`.
  *
+ * **When to use**
+ *
+ * Use to iterate over the keys currently stored in a mutable hash map.
+ *
  * **Example** (Reading keys)
  *
  * ```ts
@@ -379,6 +481,9 @@ const isSimpleKey = (u: unknown): boolean => typeof u !== "object" && typeof u !
  * const hasRequiredKeys = allKeys.includes("apple") && allKeys.includes("banana")
  * ```
  *
+ * @see {@link values} for iterating over stored values
+ * @see {@link has} for checking one key without iterating
+ *
  * @category elements
  * @since 3.8.0
  */
@@ -387,6 +492,10 @@ export const keys = <K, V>(self: MutableHashMap<K, V>): Iterable<K> => self.back
 /**
  * Returns an iterable over the values in the `MutableHashMap`.
  *
+ * **When to use**
+ *
+ * Use to iterate over the values currently stored in a mutable hash map.
+ *
  * **Example** (Reading values)
  *
  * ```ts
@@ -410,6 +519,8 @@ export const keys = <K, V>(self: MutableHashMap<K, V>): Iterable<K> => self.back
  * console.log(largeValues) // [2, 3]
  * ```
  *
+ * @see {@link keys} for iterating over stored keys
+ *
  * @category elements
  * @since 3.8.0
  */
@@ -431,7 +542,11 @@ const getFromBucket = <K, V>(
 }
 
 /**
- * Checks if the MutableHashMap contains the specified key.
+ * Checks whether the MutableHashMap contains the specified key.
+ *
+ * **When to use**
+ *
+ * Use to test whether a key is present without reading its value.
  *
  * **Example** (Checking for a key)
  *
@@ -448,12 +563,18 @@ const getFromBucket = <K, V>(
  * console.log(hasKey(map)) // true
  * ```
  *
+ * @see {@link get} for reading the value as an `Option`
+ *
  * @category elements
  * @since 2.0.0
  */
 export const has: {
   /**
-   * Checks if the MutableHashMap contains the specified key.
+   * Checks whether the MutableHashMap contains the specified key.
+   *
+   * **When to use**
+   *
+   * Use to test whether a key is present without reading its value.
    *
    * **Example** (Checking for a key)
    *
@@ -470,12 +591,18 @@ export const has: {
    * console.log(hasKey(map)) // true
    * ```
    *
+   * @see {@link get} for reading the value as an `Option`
+   *
    * @category elements
    * @since 2.0.0
    */
   <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**
+   *
+   * Use to test whether a key is present without reading its value.
    *
    * **Example** (Checking for a key)
    *
@@ -492,13 +619,19 @@ export const has: {
    * console.log(hasKey(map)) // true
    * ```
    *
+   * @see {@link get} for reading the value as an `Option`
+   *
    * @category elements
    * @since 2.0.0
    */
   <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**
+   *
+   * Use to test whether a key is present without reading its value.
    *
    * **Example** (Checking for a key)
    *
@@ -515,12 +648,18 @@ export const has: {
    * console.log(hasKey(map)) // true
    * ```
    *
+   * @see {@link get} for reading the value as an `Option`
+   *
    * @category elements
    * @since 2.0.0
    */
   <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**
+   *
+   * Use to test whether a key is present without reading its value.
    *
    * **Example** (Checking for a key)
    *
@@ -537,6 +676,8 @@ export const has: {
    * console.log(hasKey(map)) // true
    * ```
    *
+   * @see {@link get} for reading the value as an `Option`
+   *
    * @category elements
    * @since 2.0.0
    */
@@ -547,6 +688,10 @@ export const has: {
  * Sets a key-value pair in the MutableHashMap, mutating the map in place.
  * If the key already exists, its value is updated.
  *
+ * **When to use**
+ *
+ * Use to insert a new entry or replace an existing entry in place.
+ *
  * **Example** (Setting key-value pairs)
  *
  * ```ts
@@ -571,6 +716,10 @@ export const has: {
  * console.log(MutableHashMap.size(map)) // 3
  * ```
  *
+ * @see {@link modify} for updating an existing value with a function
+ * @see {@link modifyAt} for setting or removing based on the current optional value
+ * @see {@link remove} for deleting an entry by key
+ *
  * @category mutations
  * @since 2.0.0
  */
@@ -579,6 +728,10 @@ export const set: {
    * Sets a key-value pair in the MutableHashMap, mutating the map in place.
    * If the key already exists, its value is updated.
    *
+   * **When to use**
+   *
+   * Use to insert a new entry or replace an existing entry in place.
+   *
    * **Example** (Setting key-value pairs)
    *
    * ```ts
@@ -603,6 +756,10 @@ export const set: {
    * console.log(MutableHashMap.size(map)) // 3
    * ```
    *
+   * @see {@link modify} for updating an existing value with a function
+   * @see {@link modifyAt} for setting or removing based on the current optional value
+   * @see {@link remove} for deleting an entry by key
+   *
    * @category mutations
    * @since 2.0.0
    */
@@ -611,6 +768,10 @@ export const set: {
    * Sets a key-value pair in the MutableHashMap, mutating the map in place.
    * If the key already exists, its value is updated.
    *
+   * **When to use**
+   *
+   * Use to insert a new entry or replace an existing entry in place.
+   *
    * **Example** (Setting key-value pairs)
    *
    * ```ts
@@ -635,6 +796,10 @@ export const set: {
    * console.log(MutableHashMap.size(map)) // 3
    * ```
    *
+   * @see {@link modify} for updating an existing value with a function
+   * @see {@link modifyAt} for setting or removing based on the current optional value
+   * @see {@link remove} for deleting an entry by key
+   *
    * @category mutations
    * @since 2.0.0
    */
@@ -644,6 +809,10 @@ export const set: {
    * Sets a key-value pair in the MutableHashMap, mutating the map in place.
    * If the key already exists, its value is updated.
    *
+   * **When to use**
+   *
+   * Use to insert a new entry or replace an existing entry in place.
+   *
    * **Example** (Setting key-value pairs)
    *
    * ```ts
@@ -668,6 +837,10 @@ export const set: {
    * console.log(MutableHashMap.size(map)) // 3
    * ```
    *
+   * @see {@link modify} for updating an existing value with a function
+   * @see {@link modifyAt} for setting or removing based on the current optional value
+   * @see {@link remove} for deleting an entry by key
+   *
    * @category mutations
    * @since 2.0.0
    */
@@ -676,6 +849,10 @@ export const set: {
    * Sets a key-value pair in the MutableHashMap, mutating the map in place.
    * If the key already exists, its value is updated.
    *
+   * **When to use**
+   *
+   * Use to insert a new entry or replace an existing entry in place.
+   *
    * **Example** (Setting key-value pairs)
    *
    * ```ts
@@ -700,6 +877,10 @@ export const set: {
    * console.log(MutableHashMap.size(map)) // 3
    * ```
    *
+   * @see {@link modify} for updating an existing value with a function
+   * @see {@link modifyAt} for setting or removing based on the current optional value
+   * @see {@link remove} for deleting an entry by key
+   *
    * @category mutations
    * @since 2.0.0
    */
@@ -748,6 +929,10 @@ const getRefKey = <K>(
  * Updates the value of the specified key within the MutableHashMap if it exists.
  * If the key doesn't exist, the map remains unchanged.
  *
+ * **When to use**
+ *
+ * Use to transform an existing value in place without inserting missing keys.
+ *
  * **Example** (Modifying existing values)
  *
  * ```ts
@@ -772,6 +957,9 @@ const getRefKey = <K>(
  * increment(map)
  * ```
  *
+ * @see {@link set} for inserting or replacing a value directly
+ * @see {@link modifyAt} for handling both missing and existing keys
+ *
  * @category mutations
  * @since 2.0.0
  */
@@ -780,6 +968,10 @@ export const modify: {
    * Updates the value of the specified key within the MutableHashMap if it exists.
    * If the key doesn't exist, the map remains unchanged.
    *
+   * **When to use**
+   *
+   * Use to transform an existing value in place without inserting missing keys.
+   *
    * **Example** (Modifying existing values)
    *
    * ```ts
@@ -804,6 +996,9 @@ export const modify: {
    * increment(map)
    * ```
    *
+   * @see {@link set} for inserting or replacing a value directly
+   * @see {@link modifyAt} for handling both missing and existing keys
+   *
    * @category mutations
    * @since 2.0.0
    */
@@ -812,6 +1007,10 @@ export const modify: {
    * Updates the value of the specified key within the MutableHashMap if it exists.
    * If the key doesn't exist, the map remains unchanged.
    *
+   * **When to use**
+   *
+   * Use to transform an existing value in place without inserting missing keys.
+   *
    * **Example** (Modifying existing values)
    *
    * ```ts
@@ -836,6 +1035,9 @@ export const modify: {
    * increment(map)
    * ```
    *
+   * @see {@link set} for inserting or replacing a value directly
+   * @see {@link modifyAt} for handling both missing and existing keys
+   *
    * @category mutations
    * @since 2.0.0
    */
@@ -845,6 +1047,10 @@ export const modify: {
    * Updates the value of the specified key within the MutableHashMap if it exists.
    * If the key doesn't exist, the map remains unchanged.
    *
+   * **When to use**
+   *
+   * Use to transform an existing value in place without inserting missing keys.
+   *
    * **Example** (Modifying existing values)
    *
    * ```ts
@@ -869,6 +1075,9 @@ export const modify: {
    * increment(map)
    * ```
    *
+   * @see {@link set} for inserting or replacing a value directly
+   * @see {@link modifyAt} for handling both missing and existing keys
+   *
    * @category mutations
    * @since 2.0.0
    */
@@ -877,6 +1086,10 @@ export const modify: {
    * Updates the value of the specified key within the MutableHashMap if it exists.
    * If the key doesn't exist, the map remains unchanged.
    *
+   * **When to use**
+   *
+   * Use to transform an existing value in place without inserting missing keys.
+   *
    * **Example** (Modifying existing values)
    *
    * ```ts
@@ -901,6 +1114,9 @@ export const modify: {
    * increment(map)
    * ```
    *
+   * @see {@link set} for inserting or replacing a value directly
+   * @see {@link modifyAt} for handling both missing and existing keys
+   *
    * @category mutations
    * @since 2.0.0
    */
@@ -934,10 +1150,13 @@ 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**
+ *
+ * Use to decide whether to insert, update, or remove a key based on its current
+ * optional value.
  *
  * **Example** (Updating or removing a key)
  *
@@ -975,15 +1194,22 @@ export const modify: {
  * console.log(MutableHashMap.has(map, "new")) // false (42 <= 50)
  * ```
  *
+ * @see {@link modify} for updating only when the key already exists
+ * @see {@link set} for inserting or replacing directly
+ * @see {@link remove} for deleting directly
+ *
  * @category mutations
  * @since 2.0.0
  */
 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**
+   *
+   * Use to decide whether to insert, update, or remove a key based on its current
+   * optional value.
    *
    * **Example** (Updating or removing a key)
    *
@@ -1021,15 +1247,22 @@ export const modifyAt: {
    * console.log(MutableHashMap.has(map, "new")) // false (42 <= 50)
    * ```
    *
+   * @see {@link modify} for updating only when the key already exists
+   * @see {@link set} for inserting or replacing directly
+   * @see {@link remove} for deleting directly
+   *
    * @category mutations
    * @since 2.0.0
    */
   <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**
+   *
+   * Use to decide whether to insert, update, or remove a key based on its current
+   * optional value.
    *
    * **Example** (Updating or removing a key)
    *
@@ -1067,6 +1300,10 @@ export const modifyAt: {
    * console.log(MutableHashMap.has(map, "new")) // false (42 <= 50)
    * ```
    *
+   * @see {@link modify} for updating only when the key already exists
+   * @see {@link set} for inserting or replacing directly
+   * @see {@link remove} for deleting directly
+   *
    * @category mutations
    * @since 2.0.0
    */
@@ -1077,10 +1314,13 @@ 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**
+   *
+   * Use to decide whether to insert, update, or remove a key based on its current
+   * optional value.
    *
    * **Example** (Updating or removing a key)
    *
@@ -1118,15 +1358,22 @@ export const modifyAt: {
    * console.log(MutableHashMap.has(map, "new")) // false (42 <= 50)
    * ```
    *
+   * @see {@link modify} for updating only when the key already exists
+   * @see {@link set} for inserting or replacing directly
+   * @see {@link remove} for deleting directly
+   *
    * @category mutations
    * @since 2.0.0
    */
   <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**
+   *
+   * Use to decide whether to insert, update, or remove a key based on its current
+   * optional value.
    *
    * **Example** (Updating or removing a key)
    *
@@ -1164,6 +1411,10 @@ export const modifyAt: {
    * console.log(MutableHashMap.has(map, "new")) // false (42 <= 50)
    * ```
    *
+   * @see {@link modify} for updating only when the key already exists
+   * @see {@link set} for inserting or replacing directly
+   * @see {@link remove} for deleting directly
+   *
    * @category mutations
    * @since 2.0.0
    */
@@ -1189,6 +1440,10 @@ export const modifyAt: {
  * Removes the specified key from the MutableHashMap, mutating the map in place.
  * If the key doesn't exist, the map remains unchanged.
  *
+ * **When to use**
+ *
+ * Use to delete one key from a mutable hash map in place.
+ *
  * **Example** (Removing a key)
  *
  * ```ts
@@ -1217,6 +1472,9 @@ export const modifyAt: {
  * console.log(MutableHashMap.size(map)) // 1
  * ```
  *
+ * @see {@link clear} for removing all entries
+ * @see {@link modifyAt} for conditionally removing based on the current value
+ *
  * @category mutations
  * @since 2.0.0
  */
@@ -1225,6 +1483,10 @@ export const remove: {
    * Removes the specified key from the MutableHashMap, mutating the map in place.
    * If the key doesn't exist, the map remains unchanged.
    *
+   * **When to use**
+   *
+   * Use to delete one key from a mutable hash map in place.
+   *
    * **Example** (Removing a key)
    *
    * ```ts
@@ -1253,6 +1515,9 @@ export const remove: {
    * console.log(MutableHashMap.size(map)) // 1
    * ```
    *
+   * @see {@link clear} for removing all entries
+   * @see {@link modifyAt} for conditionally removing based on the current value
+   *
    * @category mutations
    * @since 2.0.0
    */
@@ -1261,6 +1526,10 @@ export const remove: {
    * Removes the specified key from the MutableHashMap, mutating the map in place.
    * If the key doesn't exist, the map remains unchanged.
    *
+   * **When to use**
+   *
+   * Use to delete one key from a mutable hash map in place.
+   *
    * **Example** (Removing a key)
    *
    * ```ts
@@ -1289,6 +1558,9 @@ export const remove: {
    * console.log(MutableHashMap.size(map)) // 1
    * ```
    *
+   * @see {@link clear} for removing all entries
+   * @see {@link modifyAt} for conditionally removing based on the current value
+   *
    * @category mutations
    * @since 2.0.0
    */
@@ -1298,6 +1570,10 @@ export const remove: {
    * Removes the specified key from the MutableHashMap, mutating the map in place.
    * If the key doesn't exist, the map remains unchanged.
    *
+   * **When to use**
+   *
+   * Use to delete one key from a mutable hash map in place.
+   *
    * **Example** (Removing a key)
    *
    * ```ts
@@ -1326,6 +1602,9 @@ export const remove: {
    * console.log(MutableHashMap.size(map)) // 1
    * ```
    *
+   * @see {@link clear} for removing all entries
+   * @see {@link modifyAt} for conditionally removing based on the current value
+   *
    * @category mutations
    * @since 2.0.0
    */
@@ -1334,6 +1613,10 @@ export const remove: {
    * Removes the specified key from the MutableHashMap, mutating the map in place.
    * If the key doesn't exist, the map remains unchanged.
    *
+   * **When to use**
+   *
+   * Use to delete one key from a mutable hash map in place.
+   *
    * **Example** (Removing a key)
    *
    * ```ts
@@ -1362,6 +1645,9 @@ export const remove: {
    * console.log(MutableHashMap.size(map)) // 1
    * ```
    *
+   * @see {@link clear} for removing all entries
+   * @see {@link modifyAt} for conditionally removing based on the current value
+   *
    * @category mutations
    * @since 2.0.0
    */
@@ -1396,6 +1682,10 @@ export const remove: {
  * Removes all key-value pairs from the MutableHashMap, mutating the map in place.
  * The map becomes empty after this operation.
  *
+ * **When to use**
+ *
+ * Use to empty a mutable hash map while keeping the same map instance.
+ *
  * **Example** (Clearing all entries)
  *
  * ```ts
@@ -1420,6 +1710,9 @@ export const remove: {
  * console.log(MutableHashMap.size(map)) // 1
  * ```
  *
+ * @see {@link remove} for deleting one key
+ * @see {@link empty} for creating a fresh empty map
+ *
  * @category mutations
  * @since 2.0.0
  */
@@ -1432,6 +1725,10 @@ export const clear = <K, V>(self: MutableHashMap<K, V>) => {
 /**
  * Returns the number of key-value pairs in the MutableHashMap.
  *
+ * **When to use**
+ *
+ * Use to read how many entries are currently stored in the mutable hash map.
+ *
  * **Example** (Checking map size)
  *
  * ```ts
@@ -1451,6 +1748,8 @@ export const clear = <K, V>(self: MutableHashMap<K, V>) => {
  * console.log(MutableHashMap.size(map)) // 0
  * ```
  *
+ * @see {@link isEmpty} for checking whether the map has no entries
+ *
  * @category elements
  * @since 2.0.0
  */
@@ -1459,6 +1758,12 @@ export const size = <K, V>(self: MutableHashMap<K, V>): number => self.backing.s
 /**
  * Returns `true` when the `MutableHashMap` contains no key-value pairs.
  *
+ * **When to use**
+ *
+ * Use to branch on whether a mutable map currently has any entries.
+ *
+ * @see {@link size} for reading the exact number of entries
+ *
  * @category predicates
  * @since 2.0.0
  */
@@ -1467,11 +1772,19 @@ export const isEmpty = <K, V>(self: MutableHashMap<K, V>): boolean => self.backi
 /**
  * Runs a callback for each key-value pair in the `MutableHashMap`.
  *
+ * **When to use**
+ *
+ * Use to run a synchronous side-effecting callback for every key-value pair in
+ * an existing mutable map.
+ *
  * **Details**
  *
  * Iteration follows the backing map's order. The callback receives the value
  * first and the key second, matching `Map.prototype.forEach`.
  *
+ * @see {@link keys} for iterating only keys
+ * @see {@link values} for iterating only values
+ *
  * @category traversing
  * @since 2.0.0
  */
@@ -1479,11 +1792,19 @@ export const forEach: {
   /**
    * Runs a callback for each key-value pair in the `MutableHashMap`.
    *
+   * **When to use**
+   *
+   * Use to run a synchronous side-effecting callback for every key-value pair in
+   * an existing mutable map.
+   *
    * **Details**
    *
    * Iteration follows the backing map's order. The callback receives the value
    * first and the key second, matching `Map.prototype.forEach`.
    *
+   * @see {@link keys} for iterating only keys
+   * @see {@link values} for iterating only values
+   *
    * @category traversing
    * @since 2.0.0
    */
@@ -1491,11 +1812,19 @@ export const forEach: {
   /**
    * Runs a callback for each key-value pair in the `MutableHashMap`.
    *
+   * **When to use**
+   *
+   * Use to run a synchronous side-effecting callback for every key-value pair in
+   * an existing mutable map.
+   *
    * **Details**
    *
    * Iteration follows the backing map's order. The callback receives the value
    * first and the key second, matching `Map.prototype.forEach`.
    *
+   * @see {@link keys} for iterating only keys
+   * @see {@link values} for iterating only values
+   *
    * @category traversing
    * @since 2.0.0
    */