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

package/dist/TxHashMap.d.ts

@@ -1,4 +1,29 @@
 /**
+ * The `TxHashMap` module provides a transactional hash map for storing and
+ * updating key-value pairs inside Effect transactions. It is useful when
+ * multiple fibers need to coordinate shared map state and each read-modify-write
+ * sequence must be committed atomically.
+ *
+ * A `TxHashMap<K, V>` has the familiar shape of a `HashMap<K, V>`, but every
+ * operation returns an `Effect` and participates in transaction semantics
+ * through `TxRef`. Use it for concurrent registries, caches, counters, indexes,
+ * and other mutable maps whose updates should compose safely with other
+ * transactional references.
+ *
+ * **Common tasks**
+ *
+ * - Create maps with {@link empty}, {@link fromIterable}, or {@link make}
+ * - Read entries with {@link get}, {@link has}, {@link keys}, {@link values}, and {@link entries}
+ * - Update entries with {@link set}, {@link modify}, {@link modifyAt}, and {@link remove}
+ * - Inspect aggregate state with {@link size}, {@link isEmpty}, and {@link reduce}
+ *
+ * **Gotchas**
+ *
+ * - Operations are effectful; run them in `Effect.gen` and wrap multi-step
+ *   transactions with `Effect.tx` when the whole sequence must commit together.
+ * - Reads that may be absent return `Option`, so handle both `Some` and `None`
+ *   instead of assuming a key exists.
+ *
  * @since 2.0.0
  */
 import * as Effect from "./Effect.ts";
@@ -14,7 +39,8 @@ declare const TypeId = "~effect/transactions/TxHashMap";
  * on key-value pairs within Effect transactions. It uses an immutable HashMap internally
  * with TxRef for transactional semantics, ensuring all operations are performed atomically.
  *
- * @example
+ * **Example** (Using transactional hash maps)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -43,8 +69,8 @@ declare const TypeId = "~effect/transactions/TxHashMap";
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TxHashMap<in out K, in out V> extends Inspectable, Pipeable {
     readonly [TypeId]: typeof TypeId;
@@ -54,7 +80,8 @@ export interface TxHashMap<in out K, in out V> extends Inspectable, Pipeable {
  * The TxHashMap namespace contains type-level utilities and helper types
  * for working with TxHashMap instances.
  *
- * @example
+ * **Example** (Reusing extracted TxHashMap types)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -82,14 +109,14 @@ export interface TxHashMap<in out K, in out V> extends Inspectable, Pipeable {
  * })
  * ```
  *
- * @since 2.0.0
- * @category models
+ * @since 4.0.0
  */
 export declare namespace TxHashMap {
     /**
      * Extracts the key type from a TxHashMap type.
      *
-     * @example
+     * **Example** (Extracting key types)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -109,14 +136,15 @@ export declare namespace TxHashMap {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category type-level
+     * @since 4.0.0
      */
     type Key<T extends TxHashMap<any, any>> = T extends TxHashMap<infer K, any> ? K : never;
     /**
      * Extracts the value type from a TxHashMap type.
      *
-     * @example
+     * **Example** (Extracting value types)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -140,14 +168,15 @@ export declare namespace TxHashMap {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category type-level
+     * @since 4.0.0
      */
     type Value<T extends TxHashMap<any, any>> = T extends TxHashMap<any, infer V> ? V : never;
     /**
      * Extracts the entry type from a TxHashMap type.
      *
-     * @example
+     * **Example** (Extracting entry types)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -174,15 +203,16 @@ export declare namespace TxHashMap {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category type-level
+     * @since 4.0.0
      */
     type Entry<T extends TxHashMap<any, any>> = T extends TxHashMap<infer K, infer V> ? readonly [K, V] : never;
 }
 /**
  * Creates an empty TxHashMap.
  *
- * @example
+ * **Example** (Creating an empty map)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -204,14 +234,15 @@ export declare namespace TxHashMap {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const empty: <K, V>() => Effect.Effect<TxHashMap<K, V>>;
 /**
  * Creates a TxHashMap from the provided key-value pairs.
  *
- * @example
+ * **Example** (Creating a map from entries)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -236,14 +267,15 @@ export declare const empty: <K, V>() => Effect.Effect<TxHashMap<K, V>>;
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const make: <K, V>(...entries: Array<readonly [K, V]>) => Effect.Effect<TxHashMap<K, V>>;
 /**
  * Creates a TxHashMap from an iterable of key-value pairs.
  *
- * @example
+ * **Example** (Creating a map from an iterable)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -271,14 +303,15 @@ export declare const make: <K, V>(...entries: Array<readonly [K, V]>) => Effect.
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromIterable: <K, V>(entries: Iterable<readonly [K, V]>) => Effect.Effect<TxHashMap<K, V>>;
 /**
  * Safely lookup the value for the specified key in the TxHashMap.
  *
- * @example
+ * **Example** (Looking up values safely)
+ *
  * ```ts
  * import { Effect, Option, TxHashMap } from "effect"
  *
@@ -303,14 +336,15 @@ export declare const fromIterable: <K, V>(entries: Iterable<readonly [K, V]>) =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const get: {
     /**
      * Safely lookup the value for the specified key in the TxHashMap.
      *
-     * @example
+     * **Example** (Looking up values safely)
+     *
      * ```ts
      * import { Effect, Option, TxHashMap } from "effect"
      *
@@ -335,14 +369,15 @@ export declare const get: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K1 extends K, K>(key: K1): <V>(self: TxHashMap<K, V>) => Effect.Effect<Option.Option<V>>;
     /**
      * Safely lookup the value for the specified key in the TxHashMap.
      *
-     * @example
+     * **Example** (Looking up values safely)
+     *
      * ```ts
      * import { Effect, Option, TxHashMap } from "effect"
      *
@@ -367,8 +402,8 @@ export declare const get: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K1 extends K, K, V>(self: TxHashMap<K, V>, key: K1): Effect.Effect<Option.Option<V>>;
 };
@@ -378,7 +413,8 @@ export declare const get: {
  * **Mutation behavior**: This function mutates the original TxHashMap by updating
  * its internal state. It does not return a new TxHashMap reference.
  *
- * @example
+ * **Example** (Setting values)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -403,8 +439,8 @@ export declare const get: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const set: {
     /**
@@ -413,7 +449,8 @@ export declare const set: {
      * **Mutation behavior**: This function mutates the original TxHashMap by updating
      * its internal state. It does not return a new TxHashMap reference.
      *
-     * @example
+     * **Example** (Setting values)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -438,8 +475,8 @@ export declare const set: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K, V>(key: K, value: V): (self: TxHashMap<K, V>) => Effect.Effect<void>;
     /**
@@ -448,7 +485,8 @@ export declare const set: {
      * **Mutation behavior**: This function mutates the original TxHashMap by updating
      * its internal state. It does not return a new TxHashMap reference.
      *
-     * @example
+     * **Example** (Setting values)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -473,15 +511,16 @@ export declare const set: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K, V>(self: TxHashMap<K, V>, key: K, value: V): Effect.Effect<void>;
 };
 /**
  * Checks if the specified key exists in the TxHashMap.
  *
- * @example
+ * **Example** (Checking for keys)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -505,14 +544,15 @@ export declare const set: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const has: {
     /**
      * Checks if the specified key exists in the TxHashMap.
      *
-     * @example
+     * **Example** (Checking for keys)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -536,14 +576,15 @@ export declare const has: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K1 extends K, K>(key: K1): <V>(self: TxHashMap<K, V>) => Effect.Effect<boolean>;
     /**
      * Checks if the specified key exists in the TxHashMap.
      *
-     * @example
+     * **Example** (Checking for keys)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -567,8 +608,8 @@ export declare const has: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K1 extends K, K, V>(self: TxHashMap<K, V>, key: K1): Effect.Effect<boolean>;
 };
@@ -578,7 +619,8 @@ export declare const has: {
  * **Mutation behavior**: This function mutates the original TxHashMap by removing
  * the specified key-value pair. It does not return a new TxHashMap reference.
  *
- * @example
+ * **Example** (Removing keys)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -606,8 +648,8 @@ export declare const has: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const remove: {
     /**
@@ -616,7 +658,8 @@ export declare const remove: {
      * **Mutation behavior**: This function mutates the original TxHashMap by removing
      * the specified key-value pair. It does not return a new TxHashMap reference.
      *
-     * @example
+     * **Example** (Removing keys)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -644,8 +687,8 @@ export declare const remove: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K1 extends K, K>(key: K1): <V>(self: TxHashMap<K, V>) => Effect.Effect<boolean>;
     /**
@@ -654,7 +697,8 @@ export declare const remove: {
      * **Mutation behavior**: This function mutates the original TxHashMap by removing
      * the specified key-value pair. It does not return a new TxHashMap reference.
      *
-     * @example
+     * **Example** (Removing keys)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -682,8 +726,8 @@ export declare const remove: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K1 extends K, K, V>(self: TxHashMap<K, V>, key: K1): Effect.Effect<boolean>;
 };
@@ -693,7 +737,8 @@ export declare const remove: {
  * **Mutation behavior**: This function mutates the original TxHashMap by clearing
  * all key-value pairs. It does not return a new TxHashMap reference.
  *
- * @example
+ * **Example** (Clearing all entries)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -720,14 +765,15 @@ export declare const remove: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const clear: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<void>;
 /**
  * Returns the number of entries in the TxHashMap.
  *
- * @example
+ * **Example** (Counting entries)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -753,14 +799,15 @@ export declare const clear: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<void>
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const size: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<number>;
 /**
  * Checks if the TxHashMap is empty.
  *
- * @example
+ * **Example** (Checking for an empty map)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -782,14 +829,15 @@ export declare const size: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<number
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const isEmpty: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<boolean>;
 /**
  * Checks if the TxHashMap is non-empty.
  *
- * @example
+ * **Example** (Checking for a non-empty map)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -806,17 +854,21 @@ export declare const isEmpty: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<boo
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const isNonEmpty: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<boolean>;
 /**
- * Updates the value for the specified key if it exists.
+ * Updates the value for the specified key if it exists, returning the previous
+ * value in `Some`.
+ *
+ * Returns `None` and leaves the map unchanged when the key is absent.
  *
  * **Mutation behavior**: This function mutates the original TxHashMap by updating
  * the value at the specified key. It does not return a new TxHashMap reference.
  *
- * @example
+ * **Example** (Updating existing values)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -850,17 +902,21 @@ export declare const isNonEmpty: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const modify: {
     /**
-     * Updates the value for the specified key if it exists.
+     * Updates the value for the specified key if it exists, returning the previous
+     * value in `Some`.
+     *
+     * Returns `None` and leaves the map unchanged when the key is absent.
      *
      * **Mutation behavior**: This function mutates the original TxHashMap by updating
      * the value at the specified key. It does not return a new TxHashMap reference.
      *
-     * @example
+     * **Example** (Updating existing values)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -894,17 +950,21 @@ export declare const modify: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V>(key: K, f: (value: V) => V): (self: TxHashMap<K, V>) => Effect.Effect<Option.Option<V>>;
     /**
-     * Updates the value for the specified key if it exists.
+     * Updates the value for the specified key if it exists, returning the previous
+     * value in `Some`.
+     *
+     * Returns `None` and leaves the map unchanged when the key is absent.
      *
      * **Mutation behavior**: This function mutates the original TxHashMap by updating
      * the value at the specified key. It does not return a new TxHashMap reference.
      *
-     * @example
+     * **Example** (Updating existing values)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -938,8 +998,8 @@ export declare const modify: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V>(self: TxHashMap<K, V>, key: K, f: (value: V) => V): Effect.Effect<Option.Option<V>>;
 };
@@ -950,7 +1010,8 @@ export declare const modify: {
  * adding, or removing the key-value pair based on the function result. It does not
  * return a new TxHashMap reference.
  *
- * @example
+ * **Example** (Updating values with Option)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -989,8 +1050,8 @@ export declare const modify: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const modifyAt: {
     /**
@@ -1000,7 +1061,8 @@ export declare const modifyAt: {
      * adding, or removing the key-value pair based on the function result. It does not
      * return a new TxHashMap reference.
      *
-     * @example
+     * **Example** (Updating values with Option)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -1039,8 +1101,8 @@ export declare const modifyAt: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V>(key: K, f: (value: Option.Option<V>) => Option.Option<V>): (self: TxHashMap<K, V>) => Effect.Effect<void>;
     /**
@@ -1050,7 +1112,8 @@ export declare const modifyAt: {
      * adding, or removing the key-value pair based on the function result. It does not
      * return a new TxHashMap reference.
      *
-     * @example
+     * **Example** (Updating values with Option)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -1089,15 +1152,16 @@ export declare const modifyAt: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V>(self: TxHashMap<K, V>, key: K, f: (value: Option.Option<V>) => Option.Option<V>): Effect.Effect<void>;
 };
 /**
  * Returns an array of all keys in the TxHashMap.
  *
- * @example
+ * **Example** (Reading keys)
+ *
  * ```ts
  * import { Effect, Option, TxHashMap } from "effect"
  *
@@ -1121,14 +1185,15 @@ export declare const modifyAt: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const keys: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Array<K>>;
 /**
  * Returns an array of all values in the TxHashMap.
  *
- * @example
+ * **Example** (Reading values)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -1140,12 +1205,12 @@ export declare const keys: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Array<
  *   )
  *
  *   const allScores = yield* TxHashMap.values(scores)
- *   console.log(allScores.sort()) // [87, 92, 95]
+ *   console.log(allScores.sort((a, b) => a - b)) // [87, 92, 95]
  *
  *   // Calculate average
  *   const average = allScores.reduce((sum, score) => sum + score, 0) /
  *     allScores.length
- *   console.log(average) // 91.33
+ *   console.log(average.toFixed(2)) // "91.33"
  *
  *   // Find maximum
  *   const maxScore = Math.max(...allScores)
@@ -1153,14 +1218,15 @@ export declare const keys: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Array<
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const values: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Array<V>>;
 /**
  * Returns an array of all key-value pairs in the TxHashMap.
  *
- * @example
+ * **Example** (Reading entries)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -1172,11 +1238,12 @@ export declare const values: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Arra
  *   )
  *
  *   const allEntries = yield* TxHashMap.entries(config)
- *   console.log(allEntries)
+ *   const sortedEntries = allEntries.toSorted(([left], [right]) => left.localeCompare(right))
+ *   console.log(sortedEntries)
  *   // [["host", "localhost"], ["port", "3000"], ["ssl", "false"]]
  *
  *   // Process configuration entries
- *   for (const [key, value] of allEntries) {
+ *   for (const [key, value] of sortedEntries) {
  *     console.log(`${key}=${value}`)
  *   }
  *   // host=localhost
@@ -1185,14 +1252,15 @@ export declare const values: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Arra
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const entries: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Array<readonly [K, V]>>;
 /**
  * Returns an immutable snapshot of the current TxHashMap state.
  *
- * @example
+ * **Example** (Taking immutable snapshots)
+ *
  * ```ts
  * import { Effect, HashMap, TxHashMap } from "effect"
  *
@@ -1220,8 +1288,8 @@ export declare const entries: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Arr
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const snapshot: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<HashMap.HashMap<K, V>>;
 /**
@@ -1231,7 +1299,8 @@ export declare const snapshot: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Ha
  * **Mutation behavior**: This function mutates the original TxHashMap by merging
  * the provided HashMap into it. It does not return a new TxHashMap reference.
  *
- * @example
+ * **Example** (Merging HashMaps)
+ *
  * ```ts
  * import { Effect, HashMap, TxHashMap } from "effect"
  *
@@ -1268,8 +1337,8 @@ export declare const snapshot: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Ha
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const union: {
     /**
@@ -1279,7 +1348,8 @@ export declare const union: {
      * **Mutation behavior**: This function mutates the original TxHashMap by merging
      * the provided HashMap into it. It does not return a new TxHashMap reference.
      *
-     * @example
+     * **Example** (Merging HashMaps)
+     *
      * ```ts
      * import { Effect, HashMap, TxHashMap } from "effect"
      *
@@ -1316,8 +1386,8 @@ export declare const union: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K1 extends K, K, V1 extends V, V>(other: HashMap.HashMap<K1, V1>): (self: TxHashMap<K, V>) => Effect.Effect<void>;
     /**
@@ -1327,7 +1397,8 @@ export declare const union: {
      * **Mutation behavior**: This function mutates the original TxHashMap by merging
      * the provided HashMap into it. It does not return a new TxHashMap reference.
      *
-     * @example
+     * **Example** (Merging HashMaps)
+     *
      * ```ts
      * import { Effect, HashMap, TxHashMap } from "effect"
      *
@@ -1364,8 +1435,8 @@ export declare const union: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K1 extends K, K, V1 extends V, V>(self: TxHashMap<K, V>, other: HashMap.HashMap<K1, V1>): Effect.Effect<void>;
 };
@@ -1375,7 +1446,8 @@ export declare const union: {
  * **Mutation behavior**: This function mutates the original TxHashMap by removing
  * all specified keys. It does not return a new TxHashMap reference.
  *
- * @example
+ * **Example** (Removing multiple keys)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -1408,8 +1480,8 @@ export declare const union: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const removeMany: {
     /**
@@ -1418,7 +1490,8 @@ export declare const removeMany: {
      * **Mutation behavior**: This function mutates the original TxHashMap by removing
      * all specified keys. It does not return a new TxHashMap reference.
      *
-     * @example
+     * **Example** (Removing multiple keys)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -1451,8 +1524,8 @@ export declare const removeMany: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K1 extends K, K>(keys: Iterable<K1>): <V>(self: TxHashMap<K, V>) => Effect.Effect<void>;
     /**
@@ -1461,7 +1534,8 @@ export declare const removeMany: {
      * **Mutation behavior**: This function mutates the original TxHashMap by removing
      * all specified keys. It does not return a new TxHashMap reference.
      *
-     * @example
+     * **Example** (Removing multiple keys)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -1494,8 +1568,8 @@ export declare const removeMany: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K1 extends K, K, V>(self: TxHashMap<K, V>, keys: Iterable<K1>): Effect.Effect<void>;
 };
@@ -1505,7 +1579,8 @@ export declare const removeMany: {
  * **Mutation behavior**: This function mutates the original TxHashMap by setting
  * all provided key-value pairs. It does not return a new TxHashMap reference.
  *
- * @example
+ * **Example** (Setting multiple entries)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -1553,8 +1628,8 @@ export declare const removeMany: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const setMany: {
     /**
@@ -1563,7 +1638,8 @@ export declare const setMany: {
      * **Mutation behavior**: This function mutates the original TxHashMap by setting
      * all provided key-value pairs. It does not return a new TxHashMap reference.
      *
-     * @example
+     * **Example** (Setting multiple entries)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -1611,8 +1687,8 @@ export declare const setMany: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K1 extends K, K, V1 extends V, V>(entries: Iterable<readonly [K1, V1]>): (self: TxHashMap<K, V>) => Effect.Effect<void>;
     /**
@@ -1621,7 +1697,8 @@ export declare const setMany: {
      * **Mutation behavior**: This function mutates the original TxHashMap by setting
      * all provided key-value pairs. It does not return a new TxHashMap reference.
      *
-     * @example
+     * **Example** (Setting multiple entries)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -1669,15 +1746,16 @@ export declare const setMany: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K1 extends K, K, V1 extends V, V>(self: TxHashMap<K, V>, entries: Iterable<readonly [K1, V1]>): Effect.Effect<void>;
 };
 /**
  * Returns `true` if the specified value is a `TxHashMap`, `false` otherwise.
  *
- * @example
+ * **Example** (Checking TxHashMap values)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -1700,23 +1778,27 @@ export declare const setMany: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isTxHashMap: <K, V>(value: unknown) => value is TxHashMap<K, V>;
 /**
- * Lookup the value for the specified key in the TxHashMap using a custom hash.
- * This can provide performance benefits when the hash is precomputed.
+ * Looks up the value for the specified key using a caller-supplied hash.
+ *
+ * The supplied hash must be the hash for the same key, such as a precomputed
+ * `Hash.hash(key)` value. If the hash does not match the key, an existing entry
+ * may not be found.
+ *
+ * **Example** (Looking up values with precomputed hashes)
  *
- * @example
  * ```ts
  * import { Effect, Hash, TxHashMap } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   // Create a cache with user sessions
  *   const cache = yield* TxHashMap.make(
- *     ["session_abc123", { userId: "user1", lastActive: Date.now() }],
- *     ["session_def456", { userId: "user2", lastActive: Date.now() }]
+ *     ["session_abc123", { userId: "user1", lastActive: 1_700_000_000_000 }],
+ *     ["session_def456", { userId: "user2", lastActive: 1_700_000_060_000 }]
  *   )
  *
  *   // When you have precomputed hash (e.g., from another lookup)
@@ -1737,23 +1819,27 @@ export declare const isTxHashMap: <K, V>(value: unknown) => value is TxHashMap<K
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const getHash: {
     /**
-     * Lookup the value for the specified key in the TxHashMap using a custom hash.
-     * This can provide performance benefits when the hash is precomputed.
+     * Looks up the value for the specified key using a caller-supplied hash.
+     *
+     * The supplied hash must be the hash for the same key, such as a precomputed
+     * `Hash.hash(key)` value. If the hash does not match the key, an existing entry
+     * may not be found.
+     *
+     * **Example** (Looking up values with precomputed hashes)
      *
-     * @example
      * ```ts
      * import { Effect, Hash, TxHashMap } from "effect"
      *
      * const program = Effect.gen(function*() {
      *   // Create a cache with user sessions
      *   const cache = yield* TxHashMap.make(
-     *     ["session_abc123", { userId: "user1", lastActive: Date.now() }],
-     *     ["session_def456", { userId: "user2", lastActive: Date.now() }]
+     *     ["session_abc123", { userId: "user1", lastActive: 1_700_000_000_000 }],
+     *     ["session_def456", { userId: "user2", lastActive: 1_700_000_060_000 }]
      *   )
      *
      *   // When you have precomputed hash (e.g., from another lookup)
@@ -1774,23 +1860,27 @@ export declare const getHash: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K1 extends K, K>(key: K1, hash: number): <V>(self: TxHashMap<K, V>) => Effect.Effect<Option.Option<V>>;
     /**
-     * Lookup the value for the specified key in the TxHashMap using a custom hash.
-     * This can provide performance benefits when the hash is precomputed.
+     * Looks up the value for the specified key using a caller-supplied hash.
+     *
+     * The supplied hash must be the hash for the same key, such as a precomputed
+     * `Hash.hash(key)` value. If the hash does not match the key, an existing entry
+     * may not be found.
+     *
+     * **Example** (Looking up values with precomputed hashes)
      *
-     * @example
      * ```ts
      * import { Effect, Hash, TxHashMap } from "effect"
      *
      * const program = Effect.gen(function*() {
      *   // Create a cache with user sessions
      *   const cache = yield* TxHashMap.make(
-     *     ["session_abc123", { userId: "user1", lastActive: Date.now() }],
-     *     ["session_def456", { userId: "user2", lastActive: Date.now() }]
+     *     ["session_abc123", { userId: "user1", lastActive: 1_700_000_000_000 }],
+     *     ["session_def456", { userId: "user2", lastActive: 1_700_000_060_000 }]
      *   )
      *
      *   // When you have precomputed hash (e.g., from another lookup)
@@ -1811,16 +1901,20 @@ export declare const getHash: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K1 extends K, K, V>(self: TxHashMap<K, V>, key: K1, hash: number): Effect.Effect<Option.Option<V>>;
 };
 /**
- * Checks if the specified key has an entry in the TxHashMap using a custom hash.
- * This can provide performance benefits when the hash is precomputed.
+ * Checks whether the specified key has an entry using a caller-supplied hash.
+ *
+ * The supplied hash must be the hash for the same key, such as a precomputed
+ * `Hash.hash(key)` value. If the hash does not match the key, an existing entry
+ * may not be found.
+ *
+ * **Example** (Checking keys with precomputed hashes)
  *
- * @example
  * ```ts
  * import { Effect, Hash, TxHashMap } from "effect"
  *
@@ -1858,15 +1952,19 @@ export declare const getHash: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const hasHash: {
     /**
-     * Checks if the specified key has an entry in the TxHashMap using a custom hash.
-     * This can provide performance benefits when the hash is precomputed.
+     * Checks whether the specified key has an entry using a caller-supplied hash.
+     *
+     * The supplied hash must be the hash for the same key, such as a precomputed
+     * `Hash.hash(key)` value. If the hash does not match the key, an existing entry
+     * may not be found.
+     *
+     * **Example** (Checking keys with precomputed hashes)
      *
-     * @example
      * ```ts
      * import { Effect, Hash, TxHashMap } from "effect"
      *
@@ -1904,15 +2002,19 @@ export declare const hasHash: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K1 extends K, K>(key: K1, hash: number): <V>(self: TxHashMap<K, V>) => Effect.Effect<boolean>;
     /**
-     * Checks if the specified key has an entry in the TxHashMap using a custom hash.
-     * This can provide performance benefits when the hash is precomputed.
+     * Checks whether the specified key has an entry using a caller-supplied hash.
+     *
+     * The supplied hash must be the hash for the same key, such as a precomputed
+     * `Hash.hash(key)` value. If the hash does not match the key, an existing entry
+     * may not be found.
+     *
+     * **Example** (Checking keys with precomputed hashes)
      *
-     * @example
      * ```ts
      * import { Effect, Hash, TxHashMap } from "effect"
      *
@@ -1950,8 +2052,8 @@ export declare const hasHash: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K1 extends K, K, V>(self: TxHashMap<K, V>, key: K1, hash: number): Effect.Effect<boolean>;
 };
@@ -1961,7 +2063,8 @@ export declare const hasHash: {
  * **Return behavior**: This function returns a new TxHashMap reference with the
  * transformed values. The original TxHashMap is not modified.
  *
- * @example
+ * **Example** (Mapping values)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -1997,8 +2100,8 @@ export declare const hasHash: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const map: {
     /**
@@ -2007,7 +2110,8 @@ export declare const map: {
      * **Return behavior**: This function returns a new TxHashMap reference with the
      * transformed values. The original TxHashMap is not modified.
      *
-     * @example
+     * **Example** (Mapping values)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -2043,8 +2147,8 @@ export declare const map: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, V, K>(f: (value: V, key: K) => A): (self: TxHashMap<K, V>) => Effect.Effect<TxHashMap<K, A>>;
     /**
@@ -2053,7 +2157,8 @@ export declare const map: {
      * **Return behavior**: This function returns a new TxHashMap reference with the
      * transformed values. The original TxHashMap is not modified.
      *
-     * @example
+     * **Example** (Mapping values)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -2089,8 +2194,8 @@ export declare const map: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V, A>(self: TxHashMap<K, V>, f: (value: V, key: K) => A): Effect.Effect<TxHashMap<K, A>>;
 };
@@ -2100,7 +2205,8 @@ export declare const map: {
  * **Return behavior**: This function returns a new TxHashMap reference containing
  * only the entries that match the condition. The original TxHashMap is not modified.
  *
- * @example
+ * **Example** (Filtering entries)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -2139,8 +2245,8 @@ export declare const map: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const filter: {
     /**
@@ -2149,7 +2255,8 @@ export declare const filter: {
      * **Return behavior**: This function returns a new TxHashMap reference containing
      * only the entries that match the condition. The original TxHashMap is not modified.
      *
-     * @example
+     * **Example** (Filtering entries)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -2188,8 +2295,8 @@ export declare const filter: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V, B extends V>(predicate: (value: V, key: K) => value is B): (self: TxHashMap<K, V>) => Effect.Effect<TxHashMap<K, B>>;
     /**
@@ -2198,7 +2305,8 @@ export declare const filter: {
      * **Return behavior**: This function returns a new TxHashMap reference containing
      * only the entries that match the condition. The original TxHashMap is not modified.
      *
-     * @example
+     * **Example** (Filtering entries)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -2237,8 +2345,8 @@ export declare const filter: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V>(predicate: (value: V, key: K) => boolean): (self: TxHashMap<K, V>) => Effect.Effect<TxHashMap<K, V>>;
     /**
@@ -2247,7 +2355,8 @@ export declare const filter: {
      * **Return behavior**: This function returns a new TxHashMap reference containing
      * only the entries that match the condition. The original TxHashMap is not modified.
      *
-     * @example
+     * **Example** (Filtering entries)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -2286,8 +2395,8 @@ export declare const filter: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V, B extends V>(self: TxHashMap<K, V>, predicate: (value: V, key: K) => value is B): Effect.Effect<TxHashMap<K, B>>;
     /**
@@ -2296,7 +2405,8 @@ export declare const filter: {
      * **Return behavior**: This function returns a new TxHashMap reference containing
      * only the entries that match the condition. The original TxHashMap is not modified.
      *
-     * @example
+     * **Example** (Filtering entries)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -2335,8 +2445,8 @@ export declare const filter: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V>(self: TxHashMap<K, V>, predicate: (value: V, key: K) => boolean): Effect.Effect<TxHashMap<K, V>>;
 };
@@ -2344,7 +2454,8 @@ export declare const filter: {
  * Reduces the TxHashMap entries to a single value by applying a reducer function.
  * Iterates over all key-value pairs and accumulates them into a final result.
  *
- * @example
+ * **Example** (Reducing entries)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -2391,15 +2502,16 @@ export declare const filter: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const reduce: {
     /**
      * Reduces the TxHashMap entries to a single value by applying a reducer function.
      * Iterates over all key-value pairs and accumulates them into a final result.
      *
-     * @example
+     * **Example** (Reducing entries)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -2446,15 +2558,16 @@ export declare const reduce: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <A, V, K>(zero: A, f: (accumulator: A, value: V, key: K) => A): (self: TxHashMap<K, V>) => Effect.Effect<A>;
     /**
      * Reduces the TxHashMap entries to a single value by applying a reducer function.
      * Iterates over all key-value pairs and accumulates them into a final result.
      *
-     * @example
+     * **Example** (Reducing entries)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -2501,8 +2614,8 @@ export declare const reduce: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K, V, A>(self: TxHashMap<K, V>, zero: A, f: (accumulator: A, value: V, key: K) => A): Effect.Effect<A>;
 };
@@ -2513,7 +2626,8 @@ export declare const reduce: {
  * **Return behavior**: This function returns a new TxHashMap reference containing
  * only the transformed entries that succeeded. The original TxHashMap is not modified.
  *
- * @example
+ * **Example** (Filtering and mapping entries)
+ *
  * ```ts
  * import { Effect, Option, Result, TxHashMap } from "effect"
  *
@@ -2560,8 +2674,8 @@ export declare const reduce: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const filterMap: {
     /**
@@ -2571,7 +2685,8 @@ export declare const filterMap: {
      * **Return behavior**: This function returns a new TxHashMap reference containing
      * only the transformed entries that succeeded. The original TxHashMap is not modified.
      *
-     * @example
+     * **Example** (Filtering and mapping entries)
+     *
      * ```ts
      * import { Effect, Option, Result, TxHashMap } from "effect"
      *
@@ -2618,8 +2733,8 @@ export declare const filterMap: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <V, K, A, X>(f: (input: V, key: K) => Result<A, X>): (self: TxHashMap<K, V>) => Effect.Effect<TxHashMap<K, A>>;
     /**
@@ -2629,7 +2744,8 @@ export declare const filterMap: {
      * **Return behavior**: This function returns a new TxHashMap reference containing
      * only the transformed entries that succeeded. The original TxHashMap is not modified.
      *
-     * @example
+     * **Example** (Filtering and mapping entries)
+     *
      * ```ts
      * import { Effect, Option, Result, TxHashMap } from "effect"
      *
@@ -2676,24 +2792,26 @@ export declare const filterMap: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V, A, X>(self: TxHashMap<K, V>, f: (input: V, key: K) => Result<A, X>): Effect.Effect<TxHashMap<K, A>>;
 };
 /**
  * Checks if any entry in the TxHashMap matches the given predicate.
  *
- * @example
+ * **Example** (Checking entries with a predicate)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   // Create a user status map
+ *   const currentTime = 1_700_000_000_000
  *   const userStatuses = yield* TxHashMap.make(
- *     ["alice", { status: "online", lastSeen: Date.now() }],
- *     ["bob", { status: "offline", lastSeen: Date.now() - 3600000 }],
- *     ["charlie", { status: "online", lastSeen: Date.now() }]
+ *     ["alice", { status: "online", lastSeen: currentTime }],
+ *     ["bob", { status: "offline", lastSeen: currentTime - 3_600_000 }],
+ *     ["charlie", { status: "online", lastSeen: currentTime }]
  *   )
  *
  *   // Check if any users are online
@@ -2712,29 +2830,31 @@ export declare const filterMap: {
  *
  *   // Data-last usage with pipe
  *   const hasRecentActivity = yield* userStatuses.pipe(
- *     TxHashMap.hasBy((user) => Date.now() - user.lastSeen < 1800000) // 30 minutes
+ *     TxHashMap.hasBy((user) => currentTime - user.lastSeen < 1_800_000) // 30 minutes
  *   )
  *   console.log(hasRecentActivity) // true
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const hasBy: {
     /**
      * Checks if any entry in the TxHashMap matches the given predicate.
      *
-     * @example
+     * **Example** (Checking entries with a predicate)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
      * const program = Effect.gen(function*() {
      *   // Create a user status map
+     *   const currentTime = 1_700_000_000_000
      *   const userStatuses = yield* TxHashMap.make(
-     *     ["alice", { status: "online", lastSeen: Date.now() }],
-     *     ["bob", { status: "offline", lastSeen: Date.now() - 3600000 }],
-     *     ["charlie", { status: "online", lastSeen: Date.now() }]
+     *     ["alice", { status: "online", lastSeen: currentTime }],
+     *     ["bob", { status: "offline", lastSeen: currentTime - 3_600_000 }],
+     *     ["charlie", { status: "online", lastSeen: currentTime }]
      *   )
      *
      *   // Check if any users are online
@@ -2753,29 +2873,31 @@ export declare const hasBy: {
      *
      *   // Data-last usage with pipe
      *   const hasRecentActivity = yield* userStatuses.pipe(
-     *     TxHashMap.hasBy((user) => Date.now() - user.lastSeen < 1800000) // 30 minutes
+     *     TxHashMap.hasBy((user) => currentTime - user.lastSeen < 1_800_000) // 30 minutes
      *   )
      *   console.log(hasRecentActivity) // true
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V>(predicate: (value: V, key: K) => boolean): (self: TxHashMap<K, V>) => Effect.Effect<boolean>;
     /**
      * Checks if any entry in the TxHashMap matches the given predicate.
      *
-     * @example
+     * **Example** (Checking entries with a predicate)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
      * const program = Effect.gen(function*() {
      *   // Create a user status map
+     *   const currentTime = 1_700_000_000_000
      *   const userStatuses = yield* TxHashMap.make(
-     *     ["alice", { status: "online", lastSeen: Date.now() }],
-     *     ["bob", { status: "offline", lastSeen: Date.now() - 3600000 }],
-     *     ["charlie", { status: "online", lastSeen: Date.now() }]
+     *     ["alice", { status: "online", lastSeen: currentTime }],
+     *     ["bob", { status: "offline", lastSeen: currentTime - 3_600_000 }],
+     *     ["charlie", { status: "online", lastSeen: currentTime }]
      *   )
      *
      *   // Check if any users are online
@@ -2794,14 +2916,14 @@ export declare const hasBy: {
      *
      *   // Data-last usage with pipe
      *   const hasRecentActivity = yield* userStatuses.pipe(
-     *     TxHashMap.hasBy((user) => Date.now() - user.lastSeen < 1800000) // 30 minutes
+     *     TxHashMap.hasBy((user) => currentTime - user.lastSeen < 1_800_000) // 30 minutes
      *   )
      *   console.log(hasRecentActivity) // true
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V>(self: TxHashMap<K, V>, predicate: (value: V, key: K) => boolean): Effect.Effect<boolean>;
 };
@@ -2809,7 +2931,8 @@ export declare const hasBy: {
  * Finds the first entry in the TxHashMap that matches the given predicate.
  * Returns the key-value pair as a tuple wrapped in an Option.
  *
- * @example
+ * **Example** (Finding the first matching entry)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -2844,15 +2967,16 @@ export declare const hasBy: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const findFirst: {
     /**
      * Finds the first entry in the TxHashMap that matches the given predicate.
      * Returns the key-value pair as a tuple wrapped in an Option.
      *
-     * @example
+     * **Example** (Finding the first matching entry)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -2887,15 +3011,16 @@ export declare const findFirst: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V>(predicate: (value: V, key: K) => boolean): (self: TxHashMap<K, V>) => Effect.Effect<Option.Option<[K, V]>>;
     /**
      * Finds the first entry in the TxHashMap that matches the given predicate.
      * Returns the key-value pair as a tuple wrapped in an Option.
      *
-     * @example
+     * **Example** (Finding the first matching entry)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -2930,15 +3055,16 @@ export declare const findFirst: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V>(self: TxHashMap<K, V>, predicate: (value: V, key: K) => boolean): Effect.Effect<Option.Option<[K, V]>>;
 };
 /**
  * Checks if at least one entry in the TxHashMap satisfies the given predicate.
  *
- * @example
+ * **Example** (Checking whether some entries match)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -2972,14 +3098,15 @@ export declare const findFirst: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const some: {
     /**
      * Checks if at least one entry in the TxHashMap satisfies the given predicate.
      *
-     * @example
+     * **Example** (Checking whether some entries match)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -3013,14 +3140,15 @@ export declare const some: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V>(predicate: (value: V, key: K) => boolean): (self: TxHashMap<K, V>) => Effect.Effect<boolean>;
     /**
      * Checks if at least one entry in the TxHashMap satisfies the given predicate.
      *
-     * @example
+     * **Example** (Checking whether some entries match)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -3054,15 +3182,16 @@ export declare const some: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V>(self: TxHashMap<K, V>, predicate: (value: V, key: K) => boolean): Effect.Effect<boolean>;
 };
 /**
  * Checks if all entries in the TxHashMap satisfy the given predicate.
  *
- * @example
+ * **Example** (Checking whether every entry matches)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -3096,14 +3225,15 @@ export declare const some: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const every: {
     /**
      * Checks if all entries in the TxHashMap satisfy the given predicate.
      *
-     * @example
+     * **Example** (Checking whether every entry matches)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -3137,14 +3267,15 @@ export declare const every: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V>(predicate: (value: V, key: K) => boolean): (self: TxHashMap<K, V>) => Effect.Effect<boolean>;
     /**
      * Checks if all entries in the TxHashMap satisfy the given predicate.
      *
-     * @example
+     * **Example** (Checking whether every entry matches)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -3178,8 +3309,8 @@ export declare const every: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V>(self: TxHashMap<K, V>, predicate: (value: V, key: K) => boolean): Effect.Effect<boolean>;
 };
@@ -3187,7 +3318,8 @@ export declare const every: {
  * Executes a side-effect function for each entry in the TxHashMap.
  * The function receives the value and key as parameters and can perform effects.
  *
- * @example
+ * **Example** (Running effects for each entry)
+ *
  * ```ts
  * import { Console, Effect, TxHashMap } from "effect"
  *
@@ -3221,15 +3353,16 @@ export declare const every: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const forEach: {
     /**
      * Executes a side-effect function for each entry in the TxHashMap.
      * The function receives the value and key as parameters and can perform effects.
      *
-     * @example
+     * **Example** (Running effects for each entry)
+     *
      * ```ts
      * import { Console, Effect, TxHashMap } from "effect"
      *
@@ -3263,15 +3396,16 @@ export declare const forEach: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <V, K, R, E>(f: (value: V, key: K) => Effect.Effect<void, E, R>): (self: TxHashMap<K, V>) => Effect.Effect<void, E, R>;
     /**
      * Executes a side-effect function for each entry in the TxHashMap.
      * The function receives the value and key as parameters and can perform effects.
      *
-     * @example
+     * **Example** (Running effects for each entry)
+     *
      * ```ts
      * import { Console, Effect, TxHashMap } from "effect"
      *
@@ -3305,19 +3439,19 @@ export declare const forEach: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K, V, R, E>(self: TxHashMap<K, V>, f: (value: V, key: K) => Effect.Effect<void, E, R>): Effect.Effect<void, E, R>;
 };
 /**
- * Transforms the TxHashMap by applying a function that returns a TxHashMap to each entry,
- * then flattening the results. Useful for complex transformations that require creating new maps.
+ * Effectfully maps each entry to a `TxHashMap` and flattens the produced maps.
  *
  * **Return behavior**: This function returns a new TxHashMap reference with the
  * flattened results. The original TxHashMap is not modified.
  *
- * @example
+ * **Example** (Flat mapping entries)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -3358,18 +3492,18 @@ export declare const forEach: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const flatMap: {
     /**
-     * Transforms the TxHashMap by applying a function that returns a TxHashMap to each entry,
-     * then flattening the results. Useful for complex transformations that require creating new maps.
+     * Effectfully maps each entry to a `TxHashMap` and flattens the produced maps.
      *
      * **Return behavior**: This function returns a new TxHashMap reference with the
      * flattened results. The original TxHashMap is not modified.
      *
-     * @example
+     * **Example** (Flat mapping entries)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -3410,18 +3544,18 @@ export declare const flatMap: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, V, K>(f: (value: V, key: K) => Effect.Effect<TxHashMap<K, A>>): (self: TxHashMap<K, V>) => Effect.Effect<TxHashMap<K, A>>;
     /**
-     * Transforms the TxHashMap by applying a function that returns a TxHashMap to each entry,
-     * then flattening the results. Useful for complex transformations that require creating new maps.
+     * Effectfully maps each entry to a `TxHashMap` and flattens the produced maps.
      *
      * **Return behavior**: This function returns a new TxHashMap reference with the
      * flattened results. The original TxHashMap is not modified.
      *
-     * @example
+     * **Example** (Flat mapping entries)
+     *
      * ```ts
      * import { Effect, TxHashMap } from "effect"
      *
@@ -3462,8 +3596,8 @@ export declare const flatMap: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <K, V, A>(self: TxHashMap<K, V>, f: (value: V, key: K) => Effect.Effect<TxHashMap<K, A>>): Effect.Effect<TxHashMap<K, A>>;
 };
@@ -3473,7 +3607,8 @@ export declare const flatMap: {
  * **Return behavior**: This function returns a new TxHashMap reference with only
  * the Some values unwrapped. The original TxHashMap is not modified.
  *
- * @example
+ * **Example** (Compacting optional values)
+ *
  * ```ts
  * import { Effect, Option, TxHashMap } from "effect"
  *
@@ -3505,19 +3640,21 @@ export declare const flatMap: {
  *   // Useful for cleaning up optional data processing results
  *   const userAges = yield* TxHashMap.map(validUsers, (user) => user.age)
  *   const ageEntries = yield* TxHashMap.entries(userAges)
- *   console.log(ageEntries) // [["alice", 30], ["charlie", 25], ["eve", 28]]
+ *   const sortedAgeEntries = ageEntries.toSorted(([left], [right]) => left.localeCompare(right))
+ *   console.log(sortedAgeEntries) // [["alice", 30], ["charlie", 25], ["eve", 28]]
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const compact: <K, A>(self: TxHashMap<K, Option.Option<A>>) => Effect.Effect<TxHashMap<K, A>>;
 /**
  * Returns an array of all key-value pairs in the TxHashMap.
  * This is an alias for the `entries` function, providing API consistency with HashMap.
  *
- * @example
+ * **Example** (Converting to entries)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -3530,29 +3667,32 @@ export declare const compact: <K, A>(self: TxHashMap<K, Option.Option<A>>) => Ef
  *
  *   // Get all entries as an array
  *   const allEntries = yield* TxHashMap.toEntries(settings)
- *   console.log(allEntries)
- *   // [["theme", "dark"], ["language", "en-US"], ["timezone", "UTC"]]
+ *   const sortedEntries = allEntries.toSorted(([left], [right]) => left.localeCompare(right))
+ *   console.log(sortedEntries)
+ *   // [["language", "en-US"], ["theme", "dark"], ["timezone", "UTC"]]
  *
  *   // Process entries
- *   for (const [setting, value] of allEntries) {
+ *   for (const [setting, value] of sortedEntries) {
  *     console.log(`${setting}: ${value}`)
  *   }
  *
  *   // Convert to object for JSON serialization
- *   const settingsObj = Object.fromEntries(allEntries)
+ *   const settingsObj = Object.fromEntries(sortedEntries)
  *   console.log(JSON.stringify(settingsObj))
+ *   // {"language":"en-US","theme":"dark","timezone":"UTC"}
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const toEntries: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Array<readonly [K, V]>>;
 /**
  * Returns an array of all values in the TxHashMap.
  * This is an alias for the `values` function, providing API consistency with HashMap.
  *
- * @example
+ * **Example** (Converting to values)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -3565,24 +3705,23 @@ export declare const toEntries: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<A
  *
  *   // Get all product information
  *   const products = yield* TxHashMap.toValues(inventory)
- *   console.log(products)
- *   // [{ price: 999, stock: 5 }, { price: 29, stock: 50 }, { price: 79, stock: 20 }]
+ *   console.log(products.length) // 3
  *
  *   // Calculate total inventory value
  *   const totalValue = products.reduce(
  *     (sum, product) => sum + (product.price * product.stock),
  *     0
  *   )
- *   console.log(`Total inventory value: $${totalValue}`) // $8,435
+ *   console.log(`Total inventory value: $${totalValue}`) // Total inventory value: $8025
  *
  *   // Find products with low stock
  *   const lowStockProducts = products.filter((product) => product.stock < 10)
- *   console.log(`${lowStockProducts.length} products with low stock`)
+ *   console.log(`${lowStockProducts.length} product with low stock`) // 1 product with low stock
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const toValues: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Array<V>>;
 export {};