effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/HashMap.js

@@ -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
  */
 import * as internal from "./internal/hashMap.js";
@@ -6,9 +79,10 @@ const TypeId = internal.HashMapTypeId;
 /**
  * Checks if a value is a HashMap.
  *
- * @example
+ * **Example** (Checking HashMap values)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * const map = HashMap.make(["a", 1], ["b", 2])
  * const notMap = { a: 1 }
@@ -18,48 +92,51 @@ const TypeId = internal.HashMapTypeId;
  * console.log(HashMap.isHashMap(null)) // false
  * ```
  *
- * @since 2.0.0
  * @category refinements
+ * @since 2.0.0
  */
 export const isHashMap = internal.isHashMap;
 /**
  * Creates a new empty `HashMap`.
  *
- * @example
+ * **Example** (Creating an empty HashMap)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * const map = HashMap.empty<string, number>()
  * console.log(HashMap.isEmpty(map)) // true
  * console.log(HashMap.size(map)) // 0
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const empty = 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"
+ * import { HashMap } from "effect"
  *
  * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3])
  * console.log(HashMap.size(map)) // 3
  * console.log(HashMap.get(map, "b")) // Option.some(2)
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = internal.make;
 /**
  * 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"
+ * import { HashMap } from "effect"
  *
  * const entries = [["a", 1], ["b", 2], ["c", 3]] as const
  * const map = HashMap.fromIterable(entries)
@@ -67,16 +144,17 @@ export const make = internal.make;
  * console.log(HashMap.get(map, "a")) // Option.some(1)
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromIterable = 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"
+ * import { HashMap } from "effect"
  *
  * const emptyMap = HashMap.empty<string, number>()
  * const nonEmptyMap = HashMap.make(["a", 1])
@@ -85,17 +163,18 @@ export const fromIterable = internal.fromIterable;
  * console.log(HashMap.isEmpty(nonEmptyMap)) // false
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const isEmpty = 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"
+ * import { HashMap } from "effect"
  *
  * const map = HashMap.make(["a", 1], ["b", 2])
  *
@@ -107,17 +186,17 @@ export const isEmpty = internal.isEmpty;
  * console.log(value) // Option.some(2)
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const get = internal.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"
+ * import { Hash, HashMap } from "effect"
  *
  * // Useful when implementing custom equality for complex keys
  * const userMap = HashMap.make(
@@ -138,8 +217,8 @@ export const get = internal.get;
  * console.log(notFound) // Option.none()
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const getHash = internal.getHash;
 /**
@@ -149,10 +228,10 @@ export const getHash = internal.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"
+ * import { HashMap, Option } from "effect"
  *
  * const config = HashMap.make(
  *   ["api_url", "https://api.example.com"],
@@ -174,16 +253,17 @@ export const getHash = internal.getHash;
  * // Error: "HashMap.getUnsafe: key not found"
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 4.0.0
  */
 export const getUnsafe = internal.getUnsafe;
 /**
  * Checks if the specified key has an entry in the `HashMap`.
  *
- * @example
+ * **Example** (Checking for keys)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * const map = HashMap.make(["a", 1], ["b", 2])
  *
@@ -195,18 +275,18 @@ export const getUnsafe = internal.getUnsafe;
  * console.log(hasB) // true
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const has = internal.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"
+ * import { Hash, HashMap } from "effect"
  *
  * // Create a map with case-sensitive keys
  * const userMap = HashMap.make(
@@ -218,38 +298,43 @@ export const has = internal.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 = internal.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"
+ * import { HashMap } from "effect"
  *
  * const hm = HashMap.make([1, "a"])
  * HashMap.hasBy(hm, (value, key) => value === "a" && key === 1) // -> true
  * HashMap.hasBy(hm, (value) => value === "b") // -> false
  * ```
  *
- * @since 3.16.0
  * @category elements
+ * @since 3.16.0
  */
 export const hasBy = internal.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"
+ * import { HashMap } from "effect"
  *
  * const map1 = HashMap.make(["a", 1])
  * const map2 = HashMap.set(map1, "b", 2)
@@ -261,48 +346,51 @@ export const hasBy = internal.hasBy;
  * console.log(HashMap.size(map1)) // 1
  * ```
  *
+ * @category transforming
  * @since 2.0.0
- * @category transformations
  */
 export const set = internal.set;
 /**
  * Returns an `IterableIterator` of the keys within the `HashMap`.
  *
- * @example
+ * **Example** (Iterating keys)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3])
  * const keys = Array.from(HashMap.keys(map))
  * console.log(keys.sort()) // ["a", "b", "c"]
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const keys = internal.keys;
 /**
  * Returns an `IterableIterator` of the values within the `HashMap`.
  *
- * @example
+ * **Example** (Iterating values)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3])
  * const values = Array.from(HashMap.values(map))
  * console.log(values.sort()) // [1, 2, 3]
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const values = 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"
+ * import { HashMap } from "effect"
  *
  * const employees = HashMap.make(
  *   ["alice", { department: "engineering", salary: 90000 }],
@@ -323,16 +411,17 @@ export const values = internal.values;
  * console.log(engineers.length) // 2
  * ```
  *
- * @since 3.13.0
  * @category getters
+ * @since 3.13.0
  */
 export const toValues = self => Array.from(values(self));
 /**
  * Returns an `IterableIterator` of the entries within the `HashMap`.
  *
- * @example
+ * **Example** (Iterating entries)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * // Create a configuration map
  * const config = HashMap.make(
@@ -341,32 +430,30 @@ export const toValues = self => Array.from(values(self));
  *   ["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 = 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"
+ * import { HashMap } from "effect"
  *
  * const gameScores = HashMap.make(
  *   ["alice", 1250],
@@ -389,16 +476,17 @@ export const entries = internal.entries;
  * const sortedMap = HashMap.fromIterable(scoreEntries)
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const toEntries = self => Array.from(entries(self));
 /**
  * Returns the number of entries within the `HashMap`.
  *
- * @example
+ * **Example** (Getting the size)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * const emptyMap = HashMap.empty<string, number>()
  * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3])
@@ -407,16 +495,20 @@ export const toEntries = self => Array.from(entries(self));
  * console.log(HashMap.size(map)) // 3
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const size = 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"
+ * import { HashMap } from "effect"
  *
  * const map = HashMap.make(["a", 1])
  *
@@ -433,16 +525,17 @@ export const size = internal.size;
  * console.log(HashMap.size(result)) // 2
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const beginMutation = internal.beginMutation;
 /**
  * Marks the `HashMap` as immutable, completing the mutation cycle.
  *
- * @example
+ * **Example** (Ending batch mutation)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * // Start with an existing map
  * const original = HashMap.make(["x", 10], ["y", 20])
@@ -463,16 +556,21 @@ export const beginMutation = internal.beginMutation;
  * console.log(HashMap.get(final, "z")) // Option.some(30)
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const endMutation = 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"
+ * import { HashMap } from "effect"
  *
  * const map1 = HashMap.make(["a", 1])
  * const map2 = HashMap.mutate(map1, (mutable) => {
@@ -482,22 +580,21 @@ export const endMutation = internal.endMutation;
  * // Returns a new HashMap with mutations applied
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const mutate = 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"
+ * import { HashMap, Option } from "effect"
  *
  * const map = HashMap.make(["a", 1], ["b", 2])
  *
@@ -509,25 +606,22 @@ export const mutate = internal.mutate;
  * console.log(HashMap.get(updated, "a")) // Option.some(2)
  * ```
  *
+ * @category transforming
  * @since 2.0.0
- * @category transformations
  */
 export const modifyAt = 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"
- * import * as Option from "effect/Option"
+ * import { Hash, HashMap, Option } from "effect"
  *
  * // Useful when working with precomputed hashes for performance
  * const counters = HashMap.make(["downloads", 100], ["views", 250])
@@ -561,16 +655,17 @@ export const modifyAt = internal.modifyAt;
  * console.log(HashMap.get(withClicks, "clicks")) // Option.some(1)
  * ```
  *
+ * @category transforming
  * @since 2.0.0
- * @category transformations
  */
 export const modifyHash = internal.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"
+ * import { HashMap } from "effect"
  *
  * const map1 = HashMap.make(["a", 1], ["b", 2])
  * const map2 = HashMap.modify(map1, "a", (value) => value * 3)
@@ -579,16 +674,20 @@ export const modifyHash = internal.modifyHash;
  * console.log(HashMap.get(map2, "b")) // Option.some(2)
  * ```
  *
+ * @category transforming
  * @since 2.0.0
- * @category transformations
  */
 export const modify = 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"
+ * import { HashMap } from "effect"
  *
  * const map1 = HashMap.make(["a", 1], ["b", 2])
  * const map2 = HashMap.make(["b", 20], ["c", 3])
@@ -598,17 +697,18 @@ export const modify = internal.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 = internal.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"
+ * import { HashMap } from "effect"
  *
  * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3])
  * const map2 = HashMap.remove(map1, "b")
@@ -618,16 +718,17 @@ export const union = internal.union;
  * console.log(HashMap.has(map2, "a")) // true
  * ```
  *
+ * @category transforming
  * @since 2.0.0
- * @category transformations
  */
 export const remove = internal.remove;
 /**
  * Removes all entries in the `HashMap` which have the specified keys.
  *
- * @example
+ * **Example** (Removing multiple keys)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3], ["d", 4])
  * const map2 = HashMap.removeMany(map1, ["b", "d"])
@@ -637,16 +738,17 @@ export const remove = internal.remove;
  * console.log(HashMap.has(map2, "c")) // true
  * ```
  *
+ * @category transforming
  * @since 2.0.0
- * @category transformations
  */
 export const removeMany = internal.removeMany;
 /**
  * Sets multiple key-value pairs in the `HashMap`.
  *
- * @example
+ * **Example** (Setting multiple entries)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * const map1 = HashMap.make(["a", 1], ["b", 2])
  * const newEntries = [["c", 3], ["d", 4], ["a", 10]] as const // "a" will be overwritten
@@ -657,16 +759,17 @@ export const removeMany = internal.removeMany;
  * console.log(HashMap.get(map2, "c")) // Option.some(3)
  * ```
  *
- * @since 2.0.0
- * @category transformations
+ * @category transforming
+ * @since 4.0.0
  */
 export const setMany = internal.setMany;
 /**
  * Maps over the entries of the `HashMap` using the specified function.
  *
- * @example
+ * **Example** (Mapping values)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3])
  * const map2 = HashMap.map(map1, (value, key) => `${key}:${value * 2}`)
@@ -675,8 +778,8 @@ export const setMany = internal.setMany;
  * console.log(HashMap.get(map2, "b")) // Option.some("b:4")
  * ```
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export const map = internal.map;
 /**
@@ -684,9 +787,10 @@ export const map = internal.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"
+ * import { HashMap } from "effect"
  *
  * const map1 = HashMap.make(["a", 1], ["b", 2])
  * const map2 = HashMap.flatMap(
@@ -699,16 +803,17 @@ export const map = internal.map;
  * console.log(HashMap.get(map2, "b2")) // Option.some(4)
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const flatMap = internal.flatMap;
 /**
  * Applies the specified function to the entries of the `HashMap`.
  *
- * @example
+ * **Example** (Iterating with side effects)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * const map = HashMap.make(["a", 1], ["b", 2])
  * const collected: Array<[string, number]> = []
@@ -720,16 +825,17 @@ export const flatMap = internal.flatMap;
  * console.log(collected.sort()) // [["a", 1], ["b", 2]]
  * ```
  *
- * @since 2.0.0
  * @category traversing
+ * @since 2.0.0
  */
 export const forEach = internal.forEach;
 /**
  * Reduces the specified state over the entries of the `HashMap`.
  *
- * @example
+ * **Example** (Reducing values)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3])
  * const sum = HashMap.reduce(map, 0, (acc, value) => acc + value)
@@ -737,16 +843,17 @@ export const forEach = internal.forEach;
  * console.log(sum) // 6
  * ```
  *
- * @since 2.0.0
  * @category folding
+ * @since 2.0.0
  */
 export const reduce = internal.reduce;
 /**
  * Filters entries out of a `HashMap` using the specified predicate.
  *
- * @example
+ * **Example** (Filtering entries)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3], ["d", 4])
  * const map2 = HashMap.filter(map1, (value) => value % 2 === 0)
@@ -757,17 +864,17 @@ export const reduce = internal.reduce;
  * console.log(HashMap.has(map2, "a")) // false
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const filter = internal.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"
+ * import { HashMap, Option } from "effect"
  *
  * const map1 = HashMap.make(
  *   ["a", Option.some(1)],
@@ -781,18 +888,18 @@ export const filter = internal.filter;
  * console.log(HashMap.has(map2, "b")) // false
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const compact = internal.compact;
 /**
  * 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"
+ * import { HashMap, Result } from "effect"
  *
  * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3], ["d", 4])
  * const map2 = HashMap.filterMap(
@@ -805,23 +912,23 @@ export const compact = internal.compact;
  * console.log(HashMap.get(map2, "d")) // Option.some(8)
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const filterMap = internal.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"
+ * import { HashMap, Option } from "effect"
  *
  * 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
@@ -831,9 +938,10 @@ export const findFirst = internal.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"
+ * import { HashMap } from "effect"
  *
  * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3])
  *
@@ -841,16 +949,17 @@ export const findFirst = internal.findFirst;
  * console.log(HashMap.some(map, (value) => value > 5)) // false
  * ```
  *
- * @since 3.13.0
  * @category elements
+ * @since 3.13.0
  */
 export const some = internal.some;
 /**
  * Checks if all entries in a hashmap meets a specific condition.
  *
- * @example
+ * **Example** (Checking all entries)
+ *
  * ```ts
- * import * as HashMap from "effect/HashMap"
+ * import { HashMap } from "effect"
  *
  * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3])
  *
@@ -858,11 +967,8 @@ export const some = internal.some;
  * console.log(HashMap.every(map, (value) => value > 1)) // false
  * ```
  *
- * @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 = internal.every;
 //# sourceMappingURL=HashMap.js.map