effect 4.0.0-beta.70 → 4.0.0-beta.71

package/dist/MutableHashMap.d.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
  */
@@ -32,6 +47,11 @@ declare 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
@@ -64,6 +84,10 @@ declare 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
  */
@@ -75,6 +99,20 @@ export interface MutableHashMap<out K, out V> extends Iterable<[K, V]>, Pipeable
 /**
  * Checks if 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
  */
@@ -82,6 +120,14 @@ export declare const isMutableHashMap: <K, V>(value: unknown) => value is Mutabl
 /**
  * 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
@@ -96,6 +142,9 @@ export declare const isMutableHashMap: <K, V>(value: unknown) => value is Mutabl
  * 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
  */
@@ -103,6 +152,10 @@ export declare 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
@@ -118,6 +171,9 @@ export declare 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
  */
@@ -125,6 +181,10 @@ export declare const make: <Entries extends Array<readonly [any, any]>>(...entri
 /**
  * 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
@@ -146,6 +206,9 @@ export declare const make: <Entries extends Array<readonly [any, any]>>(...entri
  * 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
  */
@@ -153,6 +216,10 @@ export declare const fromIterable: <K, V>(entries: Iterable<readonly [K, V]>) =>
 /**
  * Looks up a key in the `MutableHashMap`.
  *
+ * **When to use**
+ *
+ * Use to safely read the value for a key as an `Option`.
+ *
  * **Details**
  *
  * Returns `Some(value)` when an equal key is present and `None` when the key is
@@ -173,6 +240,9 @@ export declare const fromIterable: <K, V>(entries: Iterable<readonly [K, V]>) =>
  * 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
  */
@@ -180,6 +250,10 @@ export declare const get: {
     /**
      * Looks up a key in the `MutableHashMap`.
      *
+     * **When to use**
+     *
+     * Use to safely read the value for a key as an `Option`.
+     *
      * **Details**
      *
      * Returns `Some(value)` when an equal key is present and `None` when the key is
@@ -200,6 +274,9 @@ export declare 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
      */
@@ -207,6 +284,10 @@ export declare const get: {
     /**
      * Looks up a key in the `MutableHashMap`.
      *
+     * **When to use**
+     *
+     * Use to safely read the value for a key as an `Option`.
+     *
      * **Details**
      *
      * Returns `Some(value)` when an equal key is present and `None` when the key is
@@ -227,6 +308,9 @@ export declare 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
      */
@@ -235,6 +319,10 @@ export declare const get: {
 /**
  * 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
@@ -253,6 +341,9 @@ export declare const get: {
  * 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
  */
@@ -260,6 +351,10 @@ export declare const keys: <K, V>(self: MutableHashMap<K, V>) => Iterable<K>;
 /**
  * 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
@@ -283,6 +378,8 @@ export declare const keys: <K, V>(self: MutableHashMap<K, V>) => Iterable<K>;
  * console.log(largeValues) // [2, 3]
  * ```
  *
+ * @see {@link keys} for iterating over stored keys
+ *
  * @category elements
  * @since 3.8.0
  */
@@ -290,6 +387,10 @@ export declare const values: <K, V>(self: MutableHashMap<K, V>) => Iterable<V>;
 /**
  * Checks if 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)
  *
  * ```ts
@@ -305,6 +406,8 @@ export declare const values: <K, V>(self: MutableHashMap<K, V>) => Iterable<V>;
  * console.log(hasKey(map)) // true
  * ```
  *
+ * @see {@link get} for reading the value as an `Option`
+ *
  * @category elements
  * @since 2.0.0
  */
@@ -312,6 +415,10 @@ export declare const has: {
     /**
      * Checks if 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)
      *
      * ```ts
@@ -327,6 +434,8 @@ export declare const has: {
      * console.log(hasKey(map)) // true
      * ```
      *
+     * @see {@link get} for reading the value as an `Option`
+     *
      * @category elements
      * @since 2.0.0
      */
@@ -334,6 +443,10 @@ export declare const has: {
     /**
      * Checks if 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)
      *
      * ```ts
@@ -349,6 +462,8 @@ export declare const has: {
      * console.log(hasKey(map)) // true
      * ```
      *
+     * @see {@link get} for reading the value as an `Option`
+     *
      * @category elements
      * @since 2.0.0
      */
@@ -358,6 +473,10 @@ export declare 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
@@ -382,6 +501,10 @@ export declare 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
  */
@@ -390,6 +513,10 @@ export declare 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
@@ -414,6 +541,10 @@ export declare 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
      */
@@ -422,6 +553,10 @@ export declare 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
@@ -446,6 +581,10 @@ export declare 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
      */
@@ -455,6 +594,10 @@ export declare const set: {
  * 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
@@ -479,6 +622,9 @@ export declare const set: {
  * 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
  */
@@ -487,6 +633,10 @@ export declare 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
@@ -511,6 +661,9 @@ export declare 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
      */
@@ -519,6 +672,10 @@ export declare 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
@@ -543,6 +700,9 @@ export declare 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
      */
@@ -554,6 +714,11 @@ export declare const modify: {
  * If the function returns Some, the key is set to that value.
  * If the function returns None, the key is removed.
  *
+ * **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)
  *
  * ```ts
@@ -590,6 +755,10 @@ export declare 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
  */
@@ -600,6 +769,11 @@ export declare const modifyAt: {
      * If the function returns Some, the key is set to that value.
      * If the function returns None, the key is removed.
      *
+     * **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)
      *
      * ```ts
@@ -636,6 +810,10 @@ export declare 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
      */
@@ -646,6 +824,11 @@ export declare const modifyAt: {
      * If the function returns Some, the key is set to that value.
      * If the function returns None, the key is removed.
      *
+     * **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)
      *
      * ```ts
@@ -682,6 +865,10 @@ export declare 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
      */
@@ -691,6 +878,10 @@ export declare 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
@@ -719,6 +910,9 @@ export declare 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
  */
@@ -727,6 +921,10 @@ export declare 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
@@ -755,6 +953,9 @@ export declare 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
      */
@@ -763,6 +964,10 @@ export declare 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
@@ -791,6 +996,9 @@ export declare 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
      */
@@ -800,6 +1008,10 @@ export declare 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
@@ -824,6 +1036,9 @@ export declare 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
  */
@@ -831,6 +1046,10 @@ export declare const clear: <K, V>(self: MutableHashMap<K, V>) => MutableHashMap
 /**
  * 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
@@ -850,6 +1069,8 @@ export declare const clear: <K, V>(self: MutableHashMap<K, V>) => MutableHashMap
  * console.log(MutableHashMap.size(map)) // 0
  * ```
  *
+ * @see {@link isEmpty} for checking whether the map has no entries
+ *
  * @category elements
  * @since 2.0.0
  */
@@ -857,6 +1078,12 @@ export declare const size: <K, V>(self: MutableHashMap<K, V>) => number;
 /**
  * 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
  */
@@ -864,11 +1091,19 @@ export declare const isEmpty: <K, V>(self: MutableHashMap<K, V>) => boolean;
 /**
  * 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
  */
@@ -876,11 +1111,19 @@ export declare 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
      */
@@ -888,11 +1131,19 @@ export declare 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
      */