effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/HashMap.ts

@@ -1,4 +1,77 @@
 /**
+ * The `HashMap` module provides an immutable key-value data structure with
+ * efficient lookup, insertion, removal, and transformation operations. A
+ * `HashMap<Key, Value>` stores entries by hashing keys and resolving matches
+ * with Effect's structural equality semantics.
+ *
+ * **Mental model**
+ *
+ * - A `HashMap<Key, Value>` is an immutable collection of key-value pairs
+ * - Operations such as {@link set}, {@link remove}, and {@link modifyAt} return
+ *   new maps; existing maps are not mutated
+ * - Keys are compared using the `Equal` protocol and are grouped by hashes from
+ *   the `Hash` protocol
+ * - Plain JavaScript primitives work as keys, and custom objects can define
+ *   `Equal` / `Hash` behavior for structural lookup
+ * - Lookups with {@link get} return an `Option`, making missing keys explicit
+ * - Iteration order is based on the map's internal hash structure and should
+ *   not be treated as insertion order
+ *
+ * **Common tasks**
+ *
+ * - Create maps: {@link empty}, {@link make}, {@link fromIterable}
+ * - Read values: {@link get}, {@link getUnsafe}, {@link has}, {@link hasBy}
+ * - Add or update entries: {@link set}, {@link modify}, {@link modifyAt}, {@link setMany}
+ * - Remove entries: {@link remove}, {@link removeMany}
+ * - Combine maps: {@link union}
+ * - Iterate or convert: {@link keys}, {@link values}, {@link entries}, {@link toValues}, {@link toEntries}
+ * - Transform values: {@link map}, {@link flatMap}, {@link filter}, {@link filterMap}, {@link compact}
+ * - Fold and search: {@link reduce}, {@link findFirst}, {@link some}, {@link every}
+ * - Batch updates efficiently: {@link mutate}, {@link beginMutation}, {@link endMutation}
+ *
+ * **Gotchas**
+ *
+ * - {@link getUnsafe} throws when the key is absent; prefer {@link get} unless
+ *   absence is impossible by construction
+ * - Mutating a key object after insertion can make future lookups fail if its
+ *   equality or hash changes
+ * - Hash collisions are handled by equality checks, so matching hashes alone do
+ *   not make two keys equal
+ * - Use {@link getHash} and {@link hasHash} only when you already have the
+ *   correct hash for the same key
+ * - Convert entries to an array and sort them when deterministic presentation is
+ *   required
+ *
+ * **Quickstart**
+ *
+ * **Example** (Working with immutable maps)
+ *
+ * ```ts
+ * import { HashMap, Option } from "effect"
+ *
+ * const scores = HashMap.make(["alice", 10], ["bob", 15])
+ *
+ * const updated = scores.pipe(
+ *   HashMap.set("carol", 20),
+ *   HashMap.modify("alice", (score) => score + 1)
+ * )
+ *
+ * console.log(HashMap.get(updated, "alice"))
+ * // Output: Option.some(11)
+ *
+ * console.log(HashMap.get(scores, "carol"))
+ * // Output: Option.none()
+ *
+ * console.log(Option.getOrElse(HashMap.get(updated, "dave"), () => 0))
+ * // Output: 0
+ * ```
+ *
+ * **See also**
+ *
+ * - {@link HashSet} for immutable sets backed by hash semantics
+ * - {@link Equal} for structural equality
+ * - {@link Hash} for hash implementations used by hashed collections
+ *
  * @since 2.0.0
  */
 
@@ -17,7 +90,8 @@ const TypeId = internal.HashMapTypeId
  * insertion, and deletion operations. It uses a Hash Array Mapped Trie (HAMT) internally
  * for structural sharing and optimal performance.
  *
- * @example
+ * **Example** (Using basic HashMap operations)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -36,8 +110,8 @@ const TypeId = internal.HashMapTypeId
  * console.log(HashMap.size(updated)) // 4
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface HashMap<out Key, out Value> extends Iterable<[Key, Value]>, Equal, Pipeable, Inspectable {
   readonly [TypeId]: typeof TypeId
@@ -47,7 +121,8 @@ export interface HashMap<out Key, out Value> extends Iterable<[Key, Value]>, Equ
  * The HashMap namespace contains type-level utilities and helper types
  * for working with HashMap instances.
  *
- * @example
+ * **Example** (Extracting HashMap types)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -74,8 +149,8 @@ export interface HashMap<out Key, out Value> extends Iterable<[Key, Value]>, Equ
  * const updatedInventory = updateInventory("tablet", newProduct)
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export declare namespace HashMap {
   /**
@@ -83,7 +158,8 @@ export declare namespace HashMap {
    * Takes an Option representing the current value and returns an Option
    * representing the new value.
    *
-   * @example
+   * **Example** (Updating values from Options)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    * import * as Option from "effect/Option"
@@ -98,15 +174,16 @@ export declare namespace HashMap {
    * console.log(HashMap.get(updated, "a")) // Option.some(2)
    * ```
    *
-   * @since 2.0.0
    * @category models
+   * @since 2.0.0
    */
   export type UpdateFn<V> = (option: Option<V>) => Option<V>
 
   /**
    * This type-level utility extracts the key type `K` from a `HashMap<K, V>` type.
    *
-   * @example
+   * **Example** (Extracting key types)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -123,15 +200,16 @@ export declare namespace HashMap {
    * const getUserById = (id: UserKey) => HashMap.get(userMap, id)
    * console.log(getUserById("alice")) // Option.some({ name: "Alice", age: 30 })
    * ```
-   * @since 2.0.0
    * @category type-level
+   * @since 2.0.0
    */
   export type Key<T extends HashMap<any, any>> = [T] extends [HashMap<infer _K, infer _V>] ? _K : never
 
   /**
    * This type-level utility extracts the value type `V` from a `HashMap<K, V>` type.
    *
-   * @example
+   * **Example** (Extracting value types)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -152,15 +230,16 @@ export declare namespace HashMap {
    * const alice = HashMap.get(userMap, "alice")
    * // alice has type Option<User> thanks to type extraction
    * ```
-   * @since 2.0.0
    * @category type-level
+   * @since 2.0.0
    */
   export type Value<T extends HashMap<any, any>> = [T] extends [HashMap<infer _K, infer _V>] ? _V : never
 
   /**
    * This type-level utility extracts the entry type `[K, V]` from a `HashMap<K, V>` type.
    *
-   * @example
+   * **Example** (Extracting entry types)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -178,12 +257,12 @@ export declare namespace HashMap {
    *   return `${productId}: $${product.price} (${product.category})`
    * }
    *
-   * // Convert to entries and process
-   * const descriptions = HashMap.toEntries(catalog).map(processEntry)
-   * console.log(descriptions) // ["laptop: $999 (electronics)", "book: $29 (education)"]
+   * // Convert to entries, process, and sort for deterministic output
+   * const descriptions = HashMap.toEntries(catalog).map(processEntry).sort()
+   * console.log(descriptions) // ["book: $29 (education)", "laptop: $999 (electronics)"]
    * ```
-   * @since 3.9.0
    * @category type-level
+   * @since 3.9.0
    */
   export type Entry<T extends HashMap<any, any>> = [Key<T>, Value<T>]
 }
@@ -191,7 +270,8 @@ export declare namespace HashMap {
 /**
  * Checks if a value is a HashMap.
  *
- * @example
+ * **Example** (Checking HashMap values)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -203,14 +283,15 @@ export declare namespace HashMap {
  * console.log(HashMap.isHashMap(null)) // false
  * ```
  *
- * @since 2.0.0
  * @category refinements
+ * @since 2.0.0
  */
 export const isHashMap: {
   /**
    * Checks if a value is a HashMap.
    *
-   * @example
+   * **Example** (Checking HashMap values)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -222,14 +303,15 @@ export const isHashMap: {
    * console.log(HashMap.isHashMap(null)) // false
    * ```
    *
-   * @since 2.0.0
    * @category refinements
+   * @since 2.0.0
    */
   <K, V>(u: Iterable<readonly [K, V]>): u is HashMap<K, V>
   /**
    * Checks if a value is a HashMap.
    *
-   * @example
+   * **Example** (Checking HashMap values)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -241,8 +323,8 @@ export const isHashMap: {
    * console.log(HashMap.isHashMap(null)) // false
    * ```
    *
-   * @since 2.0.0
    * @category refinements
+   * @since 2.0.0
    */
   (u: unknown): u is HashMap<unknown, unknown>
 } = internal.isHashMap
@@ -250,7 +332,8 @@ export const isHashMap: {
 /**
  * Creates a new empty `HashMap`.
  *
- * @example
+ * **Example** (Creating an empty HashMap)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -259,15 +342,16 @@ export const isHashMap: {
  * console.log(HashMap.size(map)) // 0
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const empty: <K = never, V = never>() => HashMap<K, V> = internal.empty
 
 /**
  * Constructs a new `HashMap` from an array of key/value pairs.
  *
- * @example
+ * **Example** (Creating a HashMap from entries)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -276,8 +360,8 @@ export const empty: <K = never, V = never>() => HashMap<K, V> = internal.empty
  * console.log(HashMap.get(map, "b")) // Option.some(2)
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make: <Entries extends ReadonlyArray<readonly [any, any]>>(
   ...entries: Entries
@@ -289,7 +373,8 @@ export const make: <Entries extends ReadonlyArray<readonly [any, any]>>(
 /**
  * Creates a new `HashMap` from an iterable collection of key/value pairs.
  *
- * @example
+ * **Example** (Creating a HashMap from an iterable)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -299,15 +384,16 @@ export const make: <Entries extends ReadonlyArray<readonly [any, any]>>(
  * console.log(HashMap.get(map, "a")) // Option.some(1)
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromIterable: <K, V>(entries: Iterable<readonly [K, V]>) => HashMap<K, V> = internal.fromIterable
 
 /**
- * Checks if the `HashMap` contains any entries.
+ * Checks whether the `HashMap` contains no entries.
+ *
+ * **Example** (Checking for empty HashMaps)
  *
- * @example
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -318,8 +404,8 @@ export const fromIterable: <K, V>(entries: Iterable<readonly [K, V]>) => HashMap
  * console.log(HashMap.isEmpty(nonEmptyMap)) // false
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const isEmpty: <K, V>(self: HashMap<K, V>) => boolean = internal.isEmpty
 
@@ -327,7 +413,8 @@ export const isEmpty: <K, V>(self: HashMap<K, V>) => boolean = internal.isEmpty
  * Safely lookup the value for the specified key in the `HashMap` using the
  * internal hashing function.
  *
- * @example
+ * **Example** (Looking up values)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -341,15 +428,16 @@ export const isEmpty: <K, V>(self: HashMap<K, V>) => boolean = internal.isEmpty
  * console.log(value) // Option.some(2)
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const get: {
   /**
    * Safely lookup the value for the specified key in the `HashMap` using the
    * internal hashing function.
    *
-   * @example
+   * **Example** (Looking up values)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -363,15 +451,16 @@ export const get: {
    * console.log(value) // Option.some(2)
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K1 extends K, K>(key: K1): <V>(self: HashMap<K, V>) => Option<V>
   /**
    * Safely lookup the value for the specified key in the `HashMap` using the
    * internal hashing function.
    *
-   * @example
+   * **Example** (Looking up values)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -385,8 +474,8 @@ export const get: {
    * console.log(value) // Option.some(2)
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K1 extends K, K, V>(self: HashMap<K, V>, key: K1): Option<V>
 } = internal.get
@@ -394,7 +483,8 @@ export const get: {
 /**
  * Lookup the value for the specified key in the `HashMap` using a custom hash.
  *
- * @example
+ * **Example** (Looking up values with a hash)
+ *
  * ```ts
  * import { Hash } from "effect"
  * import * as HashMap from "effect/HashMap"
@@ -418,14 +508,15 @@ export const get: {
  * console.log(notFound) // Option.none()
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const getHash: {
   /**
    * Lookup the value for the specified key in the `HashMap` using a custom hash.
    *
-   * @example
+   * **Example** (Looking up values with a hash)
+   *
    * ```ts
    * import { Hash } from "effect"
    * import * as HashMap from "effect/HashMap"
@@ -449,14 +540,15 @@ export const getHash: {
    * console.log(notFound) // Option.none()
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K1 extends K, K>(key: K1, hash: number): <V>(self: HashMap<K, V>) => Option<V>
   /**
    * Lookup the value for the specified key in the `HashMap` using a custom hash.
    *
-   * @example
+   * **Example** (Looking up values with a hash)
+   *
    * ```ts
    * import { Hash } from "effect"
    * import * as HashMap from "effect/HashMap"
@@ -480,8 +572,8 @@ export const getHash: {
    * console.log(notFound) // Option.none()
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K1 extends K, K, V>(self: HashMap<K, V>, key: K1, hash: number): Option<V>
 } = internal.getHash
@@ -493,7 +585,8 @@ export const getHash: {
  * ⚠️ **Warning**: This function throws an error if the key is not found.
  * Use `HashMap.get` for safe access that returns `Option`.
  *
- * @example
+ * **Example** (Unsafely looking up values)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  * import * as Option from "effect/Option"
@@ -518,8 +611,8 @@ export const getHash: {
  * // Error: "HashMap.getUnsafe: key not found"
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export const getUnsafe: {
   /**
@@ -529,7 +622,8 @@ export const getUnsafe: {
    * ⚠️ **Warning**: This function throws an error if the key is not found.
    * Use `HashMap.get` for safe access that returns `Option`.
    *
-   * @example
+   * **Example** (Unsafely looking up values)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    * import * as Option from "effect/Option"
@@ -554,8 +648,8 @@ export const getUnsafe: {
    * // Error: "HashMap.getUnsafe: key not found"
    * ```
    *
-   * @since 2.0.0
    * @category unsafe
+   * @since 2.0.0
    */
   <K1 extends K, K>(key: K1): <V>(self: HashMap<K, V>) => V
   /**
@@ -565,7 +659,8 @@ export const getUnsafe: {
    * ⚠️ **Warning**: This function throws an error if the key is not found.
    * Use `HashMap.get` for safe access that returns `Option`.
    *
-   * @example
+   * **Example** (Unsafely looking up values)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    * import * as Option from "effect/Option"
@@ -590,8 +685,8 @@ export const getUnsafe: {
    * // Error: "HashMap.getUnsafe: key not found"
    * ```
    *
-   * @since 2.0.0
    * @category unsafe
+   * @since 2.0.0
    */
   <K1 extends K, K, V>(self: HashMap<K, V>, key: K1): V
 } = internal.getUnsafe
@@ -599,7 +694,8 @@ export const getUnsafe: {
 /**
  * Checks if the specified key has an entry in the `HashMap`.
  *
- * @example
+ * **Example** (Checking for keys)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -613,14 +709,15 @@ export const getUnsafe: {
  * console.log(hasB) // true
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const has: {
   /**
    * Checks if the specified key has an entry in the `HashMap`.
    *
-   * @example
+   * **Example** (Checking for keys)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -634,14 +731,15 @@ export const has: {
    * console.log(hasB) // true
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K1 extends K, K>(key: K1): <K, V>(self: HashMap<K, V>) => boolean
   /**
    * Checks if the specified key has an entry in the `HashMap`.
    *
-   * @example
+   * **Example** (Checking for keys)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -655,8 +753,8 @@ export const has: {
    * console.log(hasB) // true
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K1 extends K, K, V>(self: HashMap<K, V>, key: K1): boolean
 } = internal.has
@@ -665,7 +763,8 @@ export const has: {
  * Checks if the specified key has an entry in the `HashMap` using a custom
  * hash.
  *
- * @example
+ * **Example** (Checking keys with a hash)
+ *
  * ```ts
  * import { Hash } from "effect"
  * import * as HashMap from "effect/HashMap"
@@ -680,20 +779,24 @@ export const has: {
  * const exactHash = Hash.string("Admin")
  * console.log(HashMap.hasHash(userMap, "Admin", exactHash)) // true
  *
- * // Check case-insensitive by using custom hash
- * const caseInsensitiveHash = Hash.string("admin".toLowerCase())
- * console.log(HashMap.hasHash(userMap, "admin", caseInsensitiveHash)) // false (different hash)
+ * // A matching hash does not override key equality
+ * console.log(HashMap.hasHash(userMap, "admin", exactHash)) // false
+ *
+ * // A different hash also cannot find the existing key
+ * const lowercaseHash = Hash.string("admin")
+ * console.log(HashMap.hasHash(userMap, "Admin", lowercaseHash)) // false
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const hasHash: {
   /**
    * Checks if the specified key has an entry in the `HashMap` using a custom
    * hash.
    *
-   * @example
+   * **Example** (Checking keys with a hash)
+   *
    * ```ts
    * import { Hash } from "effect"
    * import * as HashMap from "effect/HashMap"
@@ -708,20 +811,24 @@ export const hasHash: {
    * const exactHash = Hash.string("Admin")
    * console.log(HashMap.hasHash(userMap, "Admin", exactHash)) // true
    *
-   * // Check case-insensitive by using custom hash
-   * const caseInsensitiveHash = Hash.string("admin".toLowerCase())
-   * console.log(HashMap.hasHash(userMap, "admin", caseInsensitiveHash)) // false (different hash)
+   * // A matching hash does not override key equality
+   * console.log(HashMap.hasHash(userMap, "admin", exactHash)) // false
+   *
+   * // A different hash also cannot find the existing key
+   * const lowercaseHash = Hash.string("admin")
+   * console.log(HashMap.hasHash(userMap, "Admin", lowercaseHash)) // false
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K1 extends K, K>(key: K1, hash: number): <V>(self: HashMap<K, V>) => boolean
   /**
    * Checks if the specified key has an entry in the `HashMap` using a custom
    * hash.
    *
-   * @example
+   * **Example** (Checking keys with a hash)
+   *
    * ```ts
    * import { Hash } from "effect"
    * import * as HashMap from "effect/HashMap"
@@ -736,13 +843,16 @@ export const hasHash: {
    * const exactHash = Hash.string("Admin")
    * console.log(HashMap.hasHash(userMap, "Admin", exactHash)) // true
    *
-   * // Check case-insensitive by using custom hash
-   * const caseInsensitiveHash = Hash.string("admin".toLowerCase())
-   * console.log(HashMap.hasHash(userMap, "admin", caseInsensitiveHash)) // false (different hash)
+   * // A matching hash does not override key equality
+   * console.log(HashMap.hasHash(userMap, "admin", exactHash)) // false
+   *
+   * // A different hash also cannot find the existing key
+   * const lowercaseHash = Hash.string("admin")
+   * console.log(HashMap.hasHash(userMap, "Admin", lowercaseHash)) // false
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K1 extends K, K, V>(self: HashMap<K, V>, key: K1, hash: number): boolean
 } = internal.hasHash
@@ -750,7 +860,8 @@ export const hasHash: {
 /**
  * Checks if an element matching the given predicate exists in the given `HashMap`.
  *
- * @example
+ * **Example** (Checking entries by predicate)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -759,14 +870,15 @@ export const hasHash: {
  * HashMap.hasBy(hm, (value) => value === "b") // -> false
  * ```
  *
- * @since 3.16.0
  * @category elements
+ * @since 3.16.0
  */
 export const hasBy: {
   /**
    * Checks if an element matching the given predicate exists in the given `HashMap`.
    *
-   * @example
+   * **Example** (Checking entries by predicate)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -775,14 +887,15 @@ export const hasBy: {
    * HashMap.hasBy(hm, (value) => value === "b") // -> false
    * ```
    *
-   * @since 3.16.0
    * @category elements
+   * @since 3.16.0
    */
   <K, V>(predicate: (value: NoInfer<V>, key: NoInfer<K>) => boolean): (self: HashMap<K, V>) => boolean
   /**
    * Checks if an element matching the given predicate exists in the given `HashMap`.
    *
-   * @example
+   * **Example** (Checking entries by predicate)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -791,8 +904,8 @@ export const hasBy: {
    * HashMap.hasBy(hm, (value) => value === "b") // -> false
    * ```
    *
-   * @since 3.16.0
    * @category elements
+   * @since 3.16.0
    */
   <K, V>(
    self: HashMap<K, V>,
@@ -804,7 +917,8 @@ export const hasBy: {
  * Sets the specified key to the specified value using the internal hashing
  * function.
  *
- * @example
+ * **Example** (Setting a value)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -818,15 +932,16 @@ export const hasBy: {
  * console.log(HashMap.size(map1)) // 1
  * ```
  *
- * @since 2.0.0
  * @category transformations
+ * @since 2.0.0
  */
 export const set: {
   /**
    * Sets the specified key to the specified value using the internal hashing
    * function.
    *
-   * @example
+   * **Example** (Setting a value)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -840,15 +955,16 @@ export const set: {
    * console.log(HashMap.size(map1)) // 1
    * ```
    *
-   * @since 2.0.0
    * @category transformations
+   * @since 2.0.0
    */
   <K, V>(key: K, value: V): (self: HashMap<K, V>) => HashMap<K, V>
   /**
    * Sets the specified key to the specified value using the internal hashing
    * function.
    *
-   * @example
+   * **Example** (Setting a value)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -862,8 +978,8 @@ export const set: {
    * console.log(HashMap.size(map1)) // 1
    * ```
    *
-   * @since 2.0.0
    * @category transformations
+   * @since 2.0.0
    */
   <K, V>(self: HashMap<K, V>, key: K, value: V): HashMap<K, V>
 } = internal.set
@@ -871,7 +987,8 @@ export const set: {
 /**
  * Returns an `IterableIterator` of the keys within the `HashMap`.
  *
- * @example
+ * **Example** (Iterating keys)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -880,15 +997,16 @@ export const set: {
  * console.log(keys.sort()) // ["a", "b", "c"]
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const keys: <K, V>(self: HashMap<K, V>) => IterableIterator<K> = internal.keys
 
 /**
  * Returns an `IterableIterator` of the values within the `HashMap`.
  *
- * @example
+ * **Example** (Iterating values)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -897,15 +1015,16 @@ export const keys: <K, V>(self: HashMap<K, V>) => IterableIterator<K> = internal
  * console.log(values.sort()) // [1, 2, 3]
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const values: <K, V>(self: HashMap<K, V>) => IterableIterator<V> = internal.values
 
 /**
  * Returns an `Array` of the values within the `HashMap`.
  *
- * @example
+ * **Example** (Converting values to an array)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -928,15 +1047,16 @@ export const values: <K, V>(self: HashMap<K, V>) => IterableIterator<V> = intern
  * console.log(engineers.length) // 2
  * ```
  *
- * @since 3.13.0
  * @category getters
+ * @since 3.13.0
  */
 export const toValues = <K, V>(self: HashMap<K, V>): Array<V> => Array.from(values(self))
 
 /**
  * Returns an `IterableIterator` of the entries within the `HashMap`.
  *
- * @example
+ * **Example** (Iterating entries)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -947,31 +1067,29 @@ export const toValues = <K, V>(self: HashMap<K, V>): Array<V> => Array.from(valu
  *   ["cache.enabled", "true"]
  * )
  *
- * // Get entries iterator for processing
- * const entries = HashMap.entries(config)
+ * // Sort the derived array for deterministic output
+ * const settings = Array.from(HashMap.entries(config))
+ *   .sort(([left], [right]) => left.localeCompare(right))
+ *   .map(([key, value]) => `Setting ${key} = ${value}`)
  *
- * // Process each configuration entry
- * for (const [key, value] of entries) {
- *   console.log(`Setting ${key} = ${value}`)
- * }
- * // Setting database.host = localhost
- * // Setting database.port = 5432
- * // Setting cache.enabled = true
+ * console.log(settings)
+ * // ["Setting cache.enabled = true", "Setting database.host = localhost", "Setting database.port = 5432"]
  *
  * // Convert to array when you need all entries at once
  * const allEntries = Array.from(HashMap.entries(config))
  * console.log(allEntries.length) // 3
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const entries: <K, V>(self: HashMap<K, V>) => IterableIterator<[K, V]> = internal.entries
 
 /**
  * Returns an `Array<[K, V]>` of the entries within the `HashMap`.
  *
- * @example
+ * **Example** (Converting entries to an array)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -996,15 +1114,16 @@ export const entries: <K, V>(self: HashMap<K, V>) => IterableIterator<[K, V]> =
  * const sortedMap = HashMap.fromIterable(scoreEntries)
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const toEntries = <K, V>(self: HashMap<K, V>): Array<[K, V]> => Array.from(entries(self))
 
 /**
  * Returns the number of entries within the `HashMap`.
  *
- * @example
+ * **Example** (Getting the size)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -1015,15 +1134,19 @@ export const toEntries = <K, V>(self: HashMap<K, V>): Array<[K, V]> => Array.fro
  * console.log(HashMap.size(map)) // 3
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const size: <K, V>(self: HashMap<K, V>) => number = internal.size
 
 /**
- * Marks the `HashMap` as mutable for performance optimization during batch operations.
+ * Creates a transient mutable `HashMap` for efficient batched updates.
+ *
+ * Apply updates to the returned map, then call `endMutation` to finish the
+ * mutation window and use the result as an immutable `HashMap`.
+ *
+ * **Example** (Beginning batch mutation)
  *
- * @example
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -1042,15 +1165,16 @@ export const size: <K, V>(self: HashMap<K, V>) => number = internal.size
  * console.log(HashMap.size(result)) // 2
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const beginMutation: <K, V>(self: HashMap<K, V>) => HashMap<K, V> = internal.beginMutation
 
 /**
  * Marks the `HashMap` as immutable, completing the mutation cycle.
  *
- * @example
+ * **Example** (Ending batch mutation)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -1073,15 +1197,20 @@ export const beginMutation: <K, V>(self: HashMap<K, V>) => HashMap<K, V> = inter
  * console.log(HashMap.get(final, "z")) // Option.some(30)
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const endMutation: <K, V>(self: HashMap<K, V>) => HashMap<K, V> = internal.endMutation
 
 /**
- * Mutates the `HashMap` within the context of the provided function.
+ * Runs a batch of updates against a transient mutable copy of the `HashMap`
+ * and returns the finalized immutable result.
+ *
+ * The callback may call mutation-oriented helpers such as `set` and `remove`
+ * on the transient map.
+ *
+ * **Example** (Applying batched mutations)
  *
- * @example
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -1093,14 +1222,19 @@ export const endMutation: <K, V>(self: HashMap<K, V>) => HashMap<K, V> = interna
  * // Returns a new HashMap with mutations applied
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const mutate: {
   /**
-   * Mutates the `HashMap` within the context of the provided function.
+   * Runs a batch of updates against a transient mutable copy of the `HashMap`
+   * and returns the finalized immutable result.
+   *
+   * The callback may call mutation-oriented helpers such as `set` and `remove`
+   * on the transient map.
+   *
+   * **Example** (Applying batched mutations)
    *
-   * @example
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1112,14 +1246,19 @@ export const mutate: {
    * // Returns a new HashMap with mutations applied
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(f: (self: HashMap<K, V>) => void): (self: HashMap<K, V>) => HashMap<K, V>
   /**
-   * Mutates the `HashMap` within the context of the provided function.
+   * Runs a batch of updates against a transient mutable copy of the `HashMap`
+   * and returns the finalized immutable result.
+   *
+   * The callback may call mutation-oriented helpers such as `set` and `remove`
+   * on the transient map.
+   *
+   * **Example** (Applying batched mutations)
    *
-   * @example
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1131,21 +1270,21 @@ export const mutate: {
    * // Returns a new HashMap with mutations applied
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(self: HashMap<K, V>, f: (self: HashMap<K, V>) => void): HashMap<K, V>
 } = internal.mutate
 
 /**
- * Set or remove the specified key in the `HashMap` using the specified
- * update function. The value of the specified key will be computed using the
- * provided hash.
+ * Sets or removes the specified key using an update function.
  *
- * The update function will be invoked with the current value of the key if it
- * exists, or `None` if no such value exists.
+ * The update function receives `Some(value)` when the key exists or `None`
+ * when it does not. Returning `Some(newValue)` stores the value, and returning
+ * `None` removes the key or leaves it absent.
+ *
+ * **Example** (Updating values with Options)
  *
- * @example
  * ```ts
  * import * as HashMap from "effect/HashMap"
  * import * as Option from "effect/Option"
@@ -1160,19 +1299,19 @@ export const mutate: {
  * console.log(HashMap.get(updated, "a")) // Option.some(2)
  * ```
  *
- * @since 2.0.0
  * @category transformations
+ * @since 2.0.0
  */
 export const modifyAt: {
   /**
-   * Set or remove the specified key in the `HashMap` using the specified
-   * update function. The value of the specified key will be computed using the
-   * provided hash.
+   * Sets or removes the specified key using an update function.
    *
-   * The update function will be invoked with the current value of the key if it
-   * exists, or `None` if no such value exists.
+   * The update function receives `Some(value)` when the key exists or `None`
+   * when it does not. Returning `Some(newValue)` stores the value, and returning
+   * `None` removes the key or leaves it absent.
+   *
+   * **Example** (Updating values with Options)
    *
-   * @example
    * ```ts
    * import * as HashMap from "effect/HashMap"
    * import * as Option from "effect/Option"
@@ -1187,19 +1326,19 @@ export const modifyAt: {
    * console.log(HashMap.get(updated, "a")) // Option.some(2)
    * ```
    *
-   * @since 2.0.0
    * @category transformations
+   * @since 2.0.0
    */
   <K, V>(key: K, f: HashMap.UpdateFn<V>): (self: HashMap<K, V>) => HashMap<K, V>
   /**
-   * Set or remove the specified key in the `HashMap` using the specified
-   * update function. The value of the specified key will be computed using the
-   * provided hash.
+   * Sets or removes the specified key using an update function.
+   *
+   * The update function receives `Some(value)` when the key exists or `None`
+   * when it does not. Returning `Some(newValue)` stores the value, and returning
+   * `None` removes the key or leaves it absent.
    *
-   * The update function will be invoked with the current value of the key if it
-   * exists, or `None` if no such value exists.
+   * **Example** (Updating values with Options)
    *
-   * @example
    * ```ts
    * import * as HashMap from "effect/HashMap"
    * import * as Option from "effect/Option"
@@ -1214,23 +1353,22 @@ export const modifyAt: {
    * console.log(HashMap.get(updated, "a")) // Option.some(2)
    * ```
    *
-   * @since 2.0.0
    * @category transformations
+   * @since 2.0.0
    */
   <K, V>(self: HashMap<K, V>, key: K, f: HashMap.UpdateFn<V>): HashMap<K, V>
 } = internal.modifyAt
 
 /**
- * Alter the value of the specified key in the `HashMap` using the specified
- * update function. The value of the specified key will be computed using the
- * provided hash.
+ * Sets or removes the specified key using a precomputed hash and an update
+ * function.
  *
- * The update function will be invoked with the current value of the key if it
- * exists, or `None` if no such value exists.
+ * The update function receives `Some(value)` when the key exists or `None`
+ * when it does not. Returning `Some(newValue)` stores the value, and returning
+ * `None` removes the key or leaves it absent.
  *
- * This function will always either update or insert a value into the `HashMap`.
+ * **Example** (Updating values with a hash)
  *
- * @example
  * ```ts
  * import { Hash } from "effect"
  * import * as HashMap from "effect/HashMap"
@@ -1268,21 +1406,20 @@ export const modifyAt: {
  * console.log(HashMap.get(withClicks, "clicks")) // Option.some(1)
  * ```
  *
- * @since 2.0.0
  * @category transformations
+ * @since 2.0.0
  */
 export const modifyHash: {
   /**
-   * Alter the value of the specified key in the `HashMap` using the specified
-   * update function. The value of the specified key will be computed using the
-   * provided hash.
+   * Sets or removes the specified key using a precomputed hash and an update
+   * function.
    *
-   * The update function will be invoked with the current value of the key if it
-   * exists, or `None` if no such value exists.
+   * The update function receives `Some(value)` when the key exists or `None`
+   * when it does not. Returning `Some(newValue)` stores the value, and returning
+   * `None` removes the key or leaves it absent.
    *
-   * This function will always either update or insert a value into the `HashMap`.
+   * **Example** (Updating values with a hash)
    *
-   * @example
    * ```ts
    * import { Hash } from "effect"
    * import * as HashMap from "effect/HashMap"
@@ -1320,21 +1457,20 @@ export const modifyHash: {
    * console.log(HashMap.get(withClicks, "clicks")) // Option.some(1)
    * ```
    *
-   * @since 2.0.0
    * @category transformations
+   * @since 2.0.0
    */
   <K, V>(key: K, hash: number, f: HashMap.UpdateFn<V>): (self: HashMap<K, V>) => HashMap<K, V>
   /**
-   * Alter the value of the specified key in the `HashMap` using the specified
-   * update function. The value of the specified key will be computed using the
-   * provided hash.
+   * Sets or removes the specified key using a precomputed hash and an update
+   * function.
    *
-   * The update function will be invoked with the current value of the key if it
-   * exists, or `None` if no such value exists.
+   * The update function receives `Some(value)` when the key exists or `None`
+   * when it does not. Returning `Some(newValue)` stores the value, and returning
+   * `None` removes the key or leaves it absent.
    *
-   * This function will always either update or insert a value into the `HashMap`.
+   * **Example** (Updating values with a hash)
    *
-   * @example
    * ```ts
    * import { Hash } from "effect"
    * import * as HashMap from "effect/HashMap"
@@ -1372,8 +1508,8 @@ export const modifyHash: {
    * console.log(HashMap.get(withClicks, "clicks")) // Option.some(1)
    * ```
    *
-   * @since 2.0.0
    * @category transformations
+   * @since 2.0.0
    */
   <K, V>(self: HashMap<K, V>, key: K, hash: number, f: HashMap.UpdateFn<V>): HashMap<K, V>
 } = internal.modifyHash
@@ -1381,7 +1517,8 @@ export const modifyHash: {
 /**
  * Updates the value of the specified key within the `HashMap` if it exists.
  *
- * @example
+ * **Example** (Modifying existing values)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -1392,14 +1529,15 @@ export const modifyHash: {
  * console.log(HashMap.get(map2, "b")) // Option.some(2)
  * ```
  *
- * @since 2.0.0
  * @category transformations
+ * @since 2.0.0
  */
 export const modify: {
   /**
    * Updates the value of the specified key within the `HashMap` if it exists.
    *
-   * @example
+   * **Example** (Modifying existing values)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1410,14 +1548,15 @@ export const modify: {
    * console.log(HashMap.get(map2, "b")) // Option.some(2)
    * ```
    *
-   * @since 2.0.0
    * @category transformations
+   * @since 2.0.0
    */
   <K, V>(key: K, f: (v: V) => V): (self: HashMap<K, V>) => HashMap<K, V>
   /**
    * Updates the value of the specified key within the `HashMap` if it exists.
    *
-   * @example
+   * **Example** (Modifying existing values)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1428,16 +1567,20 @@ export const modify: {
    * console.log(HashMap.get(map2, "b")) // Option.some(2)
    * ```
    *
-   * @since 2.0.0
    * @category transformations
+   * @since 2.0.0
    */
   <K, V>(self: HashMap<K, V>, key: K, f: (v: V) => V): HashMap<K, V>
 } = internal.modify
 
 /**
- * Performs a union of this `HashMap` and that `HashMap`.
+ * Combines two `HashMap`s into one.
+ *
+ * Entries from `that` are inserted into `self`; when both maps contain an
+ * equal key, the value from `that` replaces the value from `self`.
+ *
+ * **Example** (Combining HashMaps)
  *
- * @example
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -1449,14 +1592,18 @@ export const modify: {
  * console.log(HashMap.get(union, "b")) // Option.some(20) - map2 wins
  * ```
  *
- * @since 2.0.0
  * @category combining
+ * @since 2.0.0
  */
 export const union: {
   /**
-   * Performs a union of this `HashMap` and that `HashMap`.
+   * Combines two `HashMap`s into one.
+   *
+   * Entries from `that` are inserted into `self`; when both maps contain an
+   * equal key, the value from `that` replaces the value from `self`.
+   *
+   * **Example** (Combining HashMaps)
    *
-   * @example
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1468,14 +1615,18 @@ export const union: {
    * console.log(HashMap.get(union, "b")) // Option.some(20) - map2 wins
    * ```
    *
-   * @since 2.0.0
    * @category combining
+   * @since 2.0.0
    */
   <K1, V1>(that: HashMap<K1, V1>): <K0, V0>(self: HashMap<K0, V0>) => HashMap<K1 | K0, V1 | V0>
   /**
-   * Performs a union of this `HashMap` and that `HashMap`.
+   * Combines two `HashMap`s into one.
+   *
+   * Entries from `that` are inserted into `self`; when both maps contain an
+   * equal key, the value from `that` replaces the value from `self`.
+   *
+   * **Example** (Combining HashMaps)
    *
-   * @example
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1487,8 +1638,8 @@ export const union: {
    * console.log(HashMap.get(union, "b")) // Option.some(20) - map2 wins
    * ```
    *
-   * @since 2.0.0
    * @category combining
+   * @since 2.0.0
    */
   <K0, V0, K1, V1>(self: HashMap<K0, V0>, that: HashMap<K1, V1>): HashMap<K0 | K1, V0 | V1>
 } = internal.union
@@ -1497,7 +1648,8 @@ export const union: {
  * Remove the entry for the specified key in the `HashMap` using the internal
  * hashing function.
  *
- * @example
+ * **Example** (Removing a key)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -1509,15 +1661,16 @@ export const union: {
  * console.log(HashMap.has(map2, "a")) // true
  * ```
  *
- * @since 2.0.0
  * @category transformations
+ * @since 2.0.0
  */
 export const remove: {
   /**
    * Remove the entry for the specified key in the `HashMap` using the internal
    * hashing function.
    *
-   * @example
+   * **Example** (Removing a key)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1529,15 +1682,16 @@ export const remove: {
    * console.log(HashMap.has(map2, "a")) // true
    * ```
    *
-   * @since 2.0.0
    * @category transformations
+   * @since 2.0.0
    */
   <K>(key: K): <V>(self: HashMap<K, V>) => HashMap<K, V>
   /**
    * Remove the entry for the specified key in the `HashMap` using the internal
    * hashing function.
    *
-   * @example
+   * **Example** (Removing a key)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1549,8 +1703,8 @@ export const remove: {
    * console.log(HashMap.has(map2, "a")) // true
    * ```
    *
-   * @since 2.0.0
    * @category transformations
+   * @since 2.0.0
    */
   <K, V>(self: HashMap<K, V>, key: K): HashMap<K, V>
 } = internal.remove
@@ -1558,7 +1712,8 @@ export const remove: {
 /**
  * Removes all entries in the `HashMap` which have the specified keys.
  *
- * @example
+ * **Example** (Removing multiple keys)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -1570,14 +1725,15 @@ export const remove: {
  * console.log(HashMap.has(map2, "c")) // true
  * ```
  *
- * @since 2.0.0
  * @category transformations
+ * @since 2.0.0
  */
 export const removeMany: {
   /**
    * Removes all entries in the `HashMap` which have the specified keys.
    *
-   * @example
+   * **Example** (Removing multiple keys)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1589,14 +1745,15 @@ export const removeMany: {
    * console.log(HashMap.has(map2, "c")) // true
    * ```
    *
-   * @since 2.0.0
    * @category transformations
+   * @since 2.0.0
    */
   <K>(keys: Iterable<K>): <V>(self: HashMap<K, V>) => HashMap<K, V>
   /**
    * Removes all entries in the `HashMap` which have the specified keys.
    *
-   * @example
+   * **Example** (Removing multiple keys)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1608,8 +1765,8 @@ export const removeMany: {
    * console.log(HashMap.has(map2, "c")) // true
    * ```
    *
-   * @since 2.0.0
    * @category transformations
+   * @since 2.0.0
    */
   <K, V>(self: HashMap<K, V>, keys: Iterable<K>): HashMap<K, V>
 } = internal.removeMany
@@ -1617,7 +1774,8 @@ export const removeMany: {
 /**
  * Sets multiple key-value pairs in the `HashMap`.
  *
- * @example
+ * **Example** (Setting multiple entries)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -1630,14 +1788,15 @@ export const removeMany: {
  * console.log(HashMap.get(map2, "c")) // Option.some(3)
  * ```
  *
- * @since 2.0.0
  * @category transformations
+ * @since 2.0.0
  */
 export const setMany: {
   /**
    * Sets multiple key-value pairs in the `HashMap`.
    *
-   * @example
+   * **Example** (Setting multiple entries)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1650,14 +1809,15 @@ export const setMany: {
    * console.log(HashMap.get(map2, "c")) // Option.some(3)
    * ```
    *
-   * @since 2.0.0
    * @category transformations
+   * @since 2.0.0
    */
   <K, V>(entries: Iterable<readonly [K, V]>): (self: HashMap<K, V>) => HashMap<K, V>
   /**
    * Sets multiple key-value pairs in the `HashMap`.
    *
-   * @example
+   * **Example** (Setting multiple entries)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1670,8 +1830,8 @@ export const setMany: {
    * console.log(HashMap.get(map2, "c")) // Option.some(3)
    * ```
    *
-   * @since 2.0.0
    * @category transformations
+   * @since 2.0.0
    */
   <K, V>(self: HashMap<K, V>, entries: Iterable<readonly [K, V]>): HashMap<K, V>
 } = internal.setMany
@@ -1679,7 +1839,8 @@ export const setMany: {
 /**
  * Maps over the entries of the `HashMap` using the specified function.
  *
- * @example
+ * **Example** (Mapping values)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -1690,14 +1851,15 @@ export const setMany: {
  * console.log(HashMap.get(map2, "b")) // Option.some("b:4")
  * ```
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export const map: {
   /**
    * Maps over the entries of the `HashMap` using the specified function.
    *
-   * @example
+   * **Example** (Mapping values)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1708,14 +1870,15 @@ export const map: {
    * console.log(HashMap.get(map2, "b")) // Option.some("b:4")
    * ```
    *
-   * @since 2.0.0
    * @category mapping
+   * @since 2.0.0
    */
   <A, V, K>(f: (value: V, key: K) => A): (self: HashMap<K, V>) => HashMap<K, A>
   /**
    * Maps over the entries of the `HashMap` using the specified function.
    *
-   * @example
+   * **Example** (Mapping values)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1726,8 +1889,8 @@ export const map: {
    * console.log(HashMap.get(map2, "b")) // Option.some("b:4")
    * ```
    *
-   * @since 2.0.0
    * @category mapping
+   * @since 2.0.0
    */
   <K, V, A>(self: HashMap<K, V>, f: (value: V, key: K) => A): HashMap<K, A>
 } = internal.map
@@ -1737,7 +1900,8 @@ export const map: {
  *
  * **NOTE**: the hash and equal of both maps have to be the same.
  *
- * @example
+ * **Example** (FlatMapping values)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -1752,8 +1916,8 @@ export const map: {
  * console.log(HashMap.get(map2, "b2")) // Option.some(4)
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const flatMap: {
   /**
@@ -1761,7 +1925,8 @@ export const flatMap: {
    *
    * **NOTE**: the hash and equal of both maps have to be the same.
    *
-   * @example
+   * **Example** (FlatMapping values)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1776,8 +1941,8 @@ export const flatMap: {
    * console.log(HashMap.get(map2, "b2")) // Option.some(4)
    * ```
    *
-   * @since 2.0.0
    * @category sequencing
+   * @since 2.0.0
    */
   <A, K, B>(f: (value: A, key: K) => HashMap<K, B>): (self: HashMap<K, A>) => HashMap<K, B>
   /**
@@ -1785,7 +1950,8 @@ export const flatMap: {
    *
    * **NOTE**: the hash and equal of both maps have to be the same.
    *
-   * @example
+   * **Example** (FlatMapping values)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1800,8 +1966,8 @@ export const flatMap: {
    * console.log(HashMap.get(map2, "b2")) // Option.some(4)
    * ```
    *
-   * @since 2.0.0
    * @category sequencing
+   * @since 2.0.0
    */
   <K, A, B>(self: HashMap<K, A>, f: (value: A, key: K) => HashMap<K, B>): HashMap<K, B>
 } = internal.flatMap
@@ -1809,7 +1975,8 @@ export const flatMap: {
 /**
  * Applies the specified function to the entries of the `HashMap`.
  *
- * @example
+ * **Example** (Iterating with side effects)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -1823,14 +1990,15 @@ export const flatMap: {
  * console.log(collected.sort()) // [["a", 1], ["b", 2]]
  * ```
  *
- * @since 2.0.0
  * @category traversing
+ * @since 2.0.0
  */
 export const forEach: {
   /**
    * Applies the specified function to the entries of the `HashMap`.
    *
-   * @example
+   * **Example** (Iterating with side effects)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1844,14 +2012,15 @@ export const forEach: {
    * console.log(collected.sort()) // [["a", 1], ["b", 2]]
    * ```
    *
-   * @since 2.0.0
    * @category traversing
+   * @since 2.0.0
    */
   <V, K>(f: (value: V, key: K) => void): (self: HashMap<K, V>) => void
   /**
    * Applies the specified function to the entries of the `HashMap`.
    *
-   * @example
+   * **Example** (Iterating with side effects)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1865,8 +2034,8 @@ export const forEach: {
    * console.log(collected.sort()) // [["a", 1], ["b", 2]]
    * ```
    *
-   * @since 2.0.0
    * @category traversing
+   * @since 2.0.0
    */
   <V, K>(self: HashMap<K, V>, f: (value: V, key: K) => void): void
 } = internal.forEach
@@ -1874,7 +2043,8 @@ export const forEach: {
 /**
  * Reduces the specified state over the entries of the `HashMap`.
  *
- * @example
+ * **Example** (Reducing values)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -1884,14 +2054,15 @@ export const forEach: {
  * console.log(sum) // 6
  * ```
  *
- * @since 2.0.0
  * @category folding
+ * @since 2.0.0
  */
 export const reduce: {
   /**
    * Reduces the specified state over the entries of the `HashMap`.
    *
-   * @example
+   * **Example** (Reducing values)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1901,14 +2072,15 @@ export const reduce: {
    * console.log(sum) // 6
    * ```
    *
-   * @since 2.0.0
    * @category folding
+   * @since 2.0.0
    */
   <Z, V, K>(zero: Z, f: (accumulator: Z, value: V, key: K) => Z): (self: HashMap<K, V>) => Z
   /**
    * Reduces the specified state over the entries of the `HashMap`.
    *
-   * @example
+   * **Example** (Reducing values)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1918,8 +2090,8 @@ export const reduce: {
    * console.log(sum) // 6
    * ```
    *
-   * @since 2.0.0
    * @category folding
+   * @since 2.0.0
    */
   <K, V, Z>(self: HashMap<K, V>, zero: Z, f: (accumulator: Z, value: V, key: K) => Z): Z
 } = internal.reduce
@@ -1927,7 +2099,8 @@ export const reduce: {
 /**
  * Filters entries out of a `HashMap` using the specified predicate.
  *
- * @example
+ * **Example** (Filtering entries)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -1940,14 +2113,15 @@ export const reduce: {
  * console.log(HashMap.has(map2, "a")) // false
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const filter: {
   /**
    * Filters entries out of a `HashMap` using the specified predicate.
    *
-   * @example
+   * **Example** (Filtering entries)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1960,14 +2134,15 @@ export const filter: {
    * console.log(HashMap.has(map2, "a")) // false
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <K, A>(f: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => HashMap<K, A>
   /**
    * Filters entries out of a `HashMap` using the specified predicate.
    *
-   * @example
+   * **Example** (Filtering entries)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -1980,8 +2155,8 @@ export const filter: {
    * console.log(HashMap.has(map2, "a")) // false
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <K, A>(self: HashMap<K, A>, f: (a: A, k: K) => boolean): HashMap<K, A>
 } = internal.filter
@@ -1989,7 +2164,8 @@ export const filter: {
 /**
  * Filters out `None` values from a `HashMap` of `Options`s.
  *
- * @example
+ * **Example** (Compacting Option values)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  * import * as Option from "effect/Option"
@@ -2006,8 +2182,8 @@ export const filter: {
  * console.log(HashMap.has(map2, "b")) // false
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const compact: <K, A>(self: HashMap<K, Option<A>>) => HashMap<K, A> = internal.compact
 
@@ -2015,7 +2191,8 @@ export const compact: <K, A>(self: HashMap<K, Option<A>>) => HashMap<K, A> = int
  * Maps over the entries of the `HashMap` using the specified filter and keeps
  * only successful results.
  *
- * @example
+ * **Example** (Filtering and mapping Results)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  * import * as Result from "effect/Result"
@@ -2031,15 +2208,16 @@ export const compact: <K, A>(self: HashMap<K, Option<A>>) => HashMap<K, A> = int
  * console.log(HashMap.get(map2, "d")) // Option.some(8)
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const filterMap: {
   /**
    * Maps over the entries of the `HashMap` using the specified filter and keeps
    * only successful results.
    *
-   * @example
+   * **Example** (Filtering and mapping Results)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    * import * as Result from "effect/Result"
@@ -2055,15 +2233,16 @@ export const filterMap: {
    * console.log(HashMap.get(map2, "d")) // Option.some(8)
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <A, K, B, X>(f: (input: A, key: K) => Result<B, X>): (self: HashMap<K, A>) => HashMap<K, B>
   /**
    * Maps over the entries of the `HashMap` using the specified filter and keeps
    * only successful results.
    *
-   * @example
+   * **Example** (Filtering and mapping Results)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    * import * as Result from "effect/Result"
@@ -2079,8 +2258,8 @@ export const filterMap: {
    * console.log(HashMap.get(map2, "d")) // Option.some(8)
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <K, A, B, X>(self: HashMap<K, A>, f: (input: A, key: K) => Result<B, X>): HashMap<K, B>
 } = internal.filterMap
@@ -2089,15 +2268,16 @@ export const filterMap: {
  * Returns the first element that satisfies the specified
  * predicate, or `None` if no such element exists.
  *
- * @example
+ * **Example** (Finding the first matching entry)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  * import * as Option from "effect/Option"
  *
  * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3])
- * const result = HashMap.findFirst(map, (value) => value > 1)
- * console.log(result) // Option.some(["c", 3])
- * console.log(Option.getOrElse(result, () => ["", 0])) // ["c", 3]
+ * const result = HashMap.findFirst(map, (value, key) => key === "b" && value > 1)
+ * console.log(result) // Option.some(["b", 2])
+ * console.log(Option.getOrElse(result, () => ["", 0])) // ["b", 2]
  * ```
  *
  * @category elements
@@ -2108,15 +2288,16 @@ export const findFirst: {
    * Returns the first element that satisfies the specified
    * predicate, or `None` if no such element exists.
    *
-   * @example
+   * **Example** (Finding the first matching entry)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    * import * as Option from "effect/Option"
    *
    * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3])
-   * const result = HashMap.findFirst(map, (value) => value > 1)
-   * console.log(result) // Option.some(["c", 3])
-   * console.log(Option.getOrElse(result, () => ["", 0])) // ["c", 3]
+   * const result = HashMap.findFirst(map, (value, key) => key === "b" && value > 1)
+   * console.log(result) // Option.some(["b", 2])
+   * console.log(Option.getOrElse(result, () => ["", 0])) // ["b", 2]
    * ```
    *
    * @category elements
@@ -2127,15 +2308,16 @@ export const findFirst: {
    * Returns the first element that satisfies the specified
    * predicate, or `None` if no such element exists.
    *
-   * @example
+   * **Example** (Finding the first matching entry)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    * import * as Option from "effect/Option"
    *
    * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3])
-   * const result = HashMap.findFirst(map, (value) => value > 1)
-   * console.log(result) // Option.some(["c", 3])
-   * console.log(Option.getOrElse(result, () => ["", 0])) // ["c", 3]
+   * const result = HashMap.findFirst(map, (value, key) => key === "b" && value > 1)
+   * console.log(result) // Option.some(["b", 2])
+   * console.log(Option.getOrElse(result, () => ["", 0])) // ["b", 2]
    * ```
    *
    * @category elements
@@ -2147,7 +2329,8 @@ export const findFirst: {
 /**
  * Checks if any entry in a hashmap meets a specific condition.
  *
- * @example
+ * **Example** (Checking for any matching entry)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -2157,14 +2340,15 @@ export const findFirst: {
  * console.log(HashMap.some(map, (value) => value > 5)) // false
  * ```
  *
- * @since 3.13.0
  * @category elements
+ * @since 3.13.0
  */
 export const some: {
   /**
    * Checks if any entry in a hashmap meets a specific condition.
    *
-   * @example
+   * **Example** (Checking for any matching entry)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -2174,14 +2358,15 @@ export const some: {
    * console.log(HashMap.some(map, (value) => value > 5)) // false
    * ```
    *
-   * @since 3.13.0
    * @category elements
+   * @since 3.13.0
    */
   <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => boolean
   /**
    * Checks if any entry in a hashmap meets a specific condition.
    *
-   * @example
+   * **Example** (Checking for any matching entry)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -2191,8 +2376,8 @@ export const some: {
    * console.log(HashMap.some(map, (value) => value > 5)) // false
    * ```
    *
-   * @since 3.13.0
    * @category elements
+   * @since 3.13.0
    */
   <K, A>(self: HashMap<K, A>, predicate: (a: A, k: K) => boolean): boolean
 } = internal.some
@@ -2200,7 +2385,8 @@ export const some: {
 /**
  * Checks if all entries in a hashmap meets a specific condition.
  *
- * @example
+ * **Example** (Checking all entries)
+ *
  * ```ts
  * import * as HashMap from "effect/HashMap"
  *
@@ -2213,14 +2399,15 @@ export const some: {
  * @param self - The hashmap to check.
  * @param predicate - The condition to test entries (value, key).
  *
- * @since 3.14.0
  * @category elements
+ * @since 3.14.0
  */
 export const every: {
   /**
    * Checks if all entries in a hashmap meets a specific condition.
    *
-   * @example
+   * **Example** (Checking all entries)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -2233,14 +2420,15 @@ export const every: {
    * @param self - The hashmap to check.
    * @param predicate - The condition to test entries (value, key).
    *
-   * @since 3.14.0
    * @category elements
+   * @since 3.14.0
    */
   <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => boolean
   /**
    * Checks if all entries in a hashmap meets a specific condition.
    *
-   * @example
+   * **Example** (Checking all entries)
+   *
    * ```ts
    * import * as HashMap from "effect/HashMap"
    *
@@ -2253,8 +2441,8 @@ export const every: {
    * @param self - The hashmap to check.
    * @param predicate - The condition to test entries (value, key).
    *
-   * @since 3.14.0
    * @category elements
+   * @since 3.14.0
    */
   <K, A>(self: HashMap<K, A>, predicate: (a: A, k: K) => boolean): boolean
 } = internal.every