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

package/src/TxHashMap.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
  */
 
@@ -41,7 +66,8 @@ const TxHashMapProto = {
  * 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"
  *
@@ -70,8 +96,8 @@ const TxHashMapProto = {
  * })
  * ```
  *
- * @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
@@ -82,7 +108,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"
  *
@@ -110,14 +137,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"
    *
@@ -137,15 +164,16 @@ export declare namespace TxHashMap {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category type-level
+   * @since 4.0.0
    */
   export 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"
    *
@@ -169,15 +197,16 @@ export declare namespace TxHashMap {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category type-level
+   * @since 4.0.0
    */
   export 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"
    *
@@ -204,8 +233,8 @@ export declare namespace TxHashMap {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category type-level
+   * @since 4.0.0
    */
   export type Entry<T extends TxHashMap<any, any>> = T extends TxHashMap<infer K, infer V> ? readonly [K, V] : never
 }
@@ -213,7 +242,8 @@ export declare namespace TxHashMap {
 /**
  * Creates an empty TxHashMap.
  *
- * @example
+ * **Example** (Creating an empty map)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -235,8 +265,8 @@ export declare namespace TxHashMap {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const empty = <K, V>(): Effect.Effect<TxHashMap<K, V>> =>
   Effect.gen(function*() {
@@ -247,7 +277,8 @@ export 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"
  *
@@ -272,8 +303,8 @@ export const empty = <K, V>(): Effect.Effect<TxHashMap<K, V>> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = <K, V>(
   ...entries: Array<readonly [K, V]>
@@ -287,7 +318,8 @@ export const make = <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"
  *
@@ -315,8 +347,8 @@ export const make = <K, V>(
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromIterable = <K, V>(
   entries: Iterable<readonly [K, V]>
@@ -330,7 +362,8 @@ export const fromIterable = <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"
  *
@@ -355,14 +388,15 @@ export const fromIterable = <K, V>(
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export 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"
    *
@@ -387,14 +421,15 @@ export 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"
    *
@@ -419,8 +454,8 @@ export 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>>
 } = dual(
@@ -438,7 +473,8 @@ export 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"
  *
@@ -463,8 +499,8 @@ export const get: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const set: {
   /**
@@ -473,7 +509,8 @@ export 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"
    *
@@ -498,8 +535,8 @@ export 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>
   /**
@@ -508,7 +545,8 @@ export 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"
    *
@@ -533,8 +571,8 @@ export 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>
 } = dual(
@@ -546,7 +584,8 @@ export const set: {
 /**
  * Checks if the specified key exists in the TxHashMap.
  *
- * @example
+ * **Example** (Checking for keys)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -570,14 +609,15 @@ export const set: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const has: {
   /**
    * Checks if the specified key exists in the TxHashMap.
    *
-   * @example
+   * **Example** (Checking for keys)
+   *
    * ```ts
    * import { Effect, TxHashMap } from "effect"
    *
@@ -601,14 +641,15 @@ export 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"
    *
@@ -632,8 +673,8 @@ export 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>
 } = dual(
@@ -651,7 +692,8 @@ export 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"
  *
@@ -679,8 +721,8 @@ export const has: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const remove: {
   /**
@@ -689,7 +731,8 @@ export 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"
    *
@@ -717,8 +760,8 @@ export 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>
   /**
@@ -727,7 +770,8 @@ export 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"
    *
@@ -755,8 +799,8 @@ export 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>
 } = dual(
@@ -778,7 +822,8 @@ export 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"
  *
@@ -805,15 +850,16 @@ export const remove: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const clear = <K, V>(self: TxHashMap<K, V>): Effect.Effect<void> => TxRef.set(self.ref, HashMap.empty<K, V>())
 
 /**
  * Returns the number of entries in the TxHashMap.
  *
- * @example
+ * **Example** (Counting entries)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -839,8 +885,8 @@ export const clear = <K, V>(self: TxHashMap<K, V>): Effect.Effect<void> => TxRef
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const size = <K, V>(self: TxHashMap<K, V>): Effect.Effect<number> =>
   Effect.gen(function*() {
@@ -851,7 +897,8 @@ export 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"
  *
@@ -873,8 +920,8 @@ export const size = <K, V>(self: TxHashMap<K, V>): Effect.Effect<number> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const isEmpty = <K, V>(self: TxHashMap<K, V>): Effect.Effect<boolean> =>
   Effect.gen(function*() {
@@ -885,7 +932,8 @@ export 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"
  *
@@ -902,19 +950,23 @@ export const isEmpty = <K, V>(self: TxHashMap<K, V>): Effect.Effect<boolean> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const isNonEmpty = <K, V>(self: TxHashMap<K, V>): Effect.Effect<boolean> =>
   Effect.map(isEmpty(self), (empty) => !empty)
 
 /**
- * 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"
  *
@@ -948,17 +1000,21 @@ export const isNonEmpty = <K, V>(self: TxHashMap<K, V>): Effect.Effect<boolean>
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export 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"
    *
@@ -992,17 +1048,21 @@ export 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"
    *
@@ -1036,8 +1096,8 @@ export 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>>
 } = dual(
@@ -1066,7 +1126,8 @@ export 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"
  *
@@ -1105,8 +1166,8 @@ export const modify: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const modifyAt: {
   /**
@@ -1116,7 +1177,8 @@ export 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"
    *
@@ -1155,8 +1217,8 @@ export 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>
   /**
@@ -1166,7 +1228,8 @@ export 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"
    *
@@ -1205,8 +1268,8 @@ export const modifyAt: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <K, V>(
     self: TxHashMap<K, V>,
@@ -1236,7 +1299,8 @@ export const modifyAt: {
 /**
  * Returns an array of all keys in the TxHashMap.
  *
- * @example
+ * **Example** (Reading keys)
+ *
  * ```ts
  * import { Effect, Option, TxHashMap } from "effect"
  *
@@ -1260,8 +1324,8 @@ export const modifyAt: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const keys = <K, V>(self: TxHashMap<K, V>): Effect.Effect<Array<K>> =>
   Effect.gen(function*() {
@@ -1272,7 +1336,8 @@ export 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"
  *
@@ -1284,12 +1349,12 @@ export const keys = <K, V>(self: TxHashMap<K, V>): Effect.Effect<Array<K>> =>
  *   )
  *
  *   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)
@@ -1297,8 +1362,8 @@ export const keys = <K, V>(self: TxHashMap<K, V>): Effect.Effect<Array<K>> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const values = <K, V>(self: TxHashMap<K, V>): Effect.Effect<Array<V>> =>
   Effect.gen(function*() {
@@ -1309,7 +1374,8 @@ export 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"
  *
@@ -1321,11 +1387,12 @@ export const values = <K, V>(self: TxHashMap<K, V>): Effect.Effect<Array<V>> =>
  *   )
  *
  *   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
@@ -1334,8 +1401,8 @@ export const values = <K, V>(self: TxHashMap<K, V>): Effect.Effect<Array<V>> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const entries = <K, V>(
   self: TxHashMap<K, V>
@@ -1348,7 +1415,8 @@ export const entries = <K, V>(
 /**
  * Returns an immutable snapshot of the current TxHashMap state.
  *
- * @example
+ * **Example** (Taking immutable snapshots)
+ *
  * ```ts
  * import { Effect, HashMap, TxHashMap } from "effect"
  *
@@ -1376,8 +1444,8 @@ export const entries = <K, V>(
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const snapshot = <K, V>(
   self: TxHashMap<K, V>
@@ -1390,7 +1458,8 @@ export const snapshot = <K, V>(
  * **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"
  *
@@ -1427,8 +1496,8 @@ export const snapshot = <K, V>(
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const union: {
   /**
@@ -1438,7 +1507,8 @@ export 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"
    *
@@ -1475,8 +1545,8 @@ export 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>
   /**
@@ -1486,7 +1556,8 @@ export 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"
    *
@@ -1523,8 +1594,8 @@ export 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>
 } = dual(
@@ -1541,7 +1612,8 @@ export 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"
  *
@@ -1574,8 +1646,8 @@ export const union: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const removeMany: {
   /**
@@ -1584,7 +1656,8 @@ export 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"
    *
@@ -1617,8 +1690,8 @@ export 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>
   /**
@@ -1627,7 +1700,8 @@ export 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"
    *
@@ -1660,8 +1734,8 @@ export 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>
 } = dual(
@@ -1676,7 +1750,8 @@ export 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"
  *
@@ -1724,8 +1799,8 @@ export const removeMany: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const setMany: {
   /**
@@ -1734,7 +1809,8 @@ export 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"
    *
@@ -1782,8 +1858,8 @@ export 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>
   /**
@@ -1792,7 +1868,8 @@ export 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"
    *
@@ -1840,8 +1917,8 @@ export 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>
 } = dual(
@@ -1855,7 +1932,8 @@ export const setMany: {
 /**
  * Returns `true` if the specified value is a `TxHashMap`, `false` otherwise.
  *
- * @example
+ * **Example** (Checking TxHashMap values)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -1878,26 +1956,30 @@ export const setMany: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isTxHashMap = <K, V>(value: unknown): value is TxHashMap<K, V> => {
   return hasProperty(value, TypeId)
 }
 
 /**
- * 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)
@@ -1918,23 +2000,27 @@ export const isTxHashMap = <K, V>(value: unknown): value is TxHashMap<K, V> => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export 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)
@@ -1955,23 +2041,27 @@ export 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)
@@ -1992,8 +2082,8 @@ export 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>>
 } = dual(
@@ -2006,10 +2096,14 @@ export const getHash: {
 )
 
 /**
- * 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"
  *
@@ -2047,15 +2141,19 @@ export const getHash: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export 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"
    *
@@ -2093,15 +2191,19 @@ export 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"
    *
@@ -2139,8 +2241,8 @@ export 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>
 } = dual(
@@ -2158,7 +2260,8 @@ export 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"
  *
@@ -2194,8 +2297,8 @@ export const hasHash: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const map: {
   /**
@@ -2204,7 +2307,8 @@ export 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"
    *
@@ -2240,8 +2344,8 @@ export 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>>
   /**
@@ -2250,7 +2354,8 @@ export 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"
    *
@@ -2286,8 +2391,8 @@ export 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>>
 } = dual(
@@ -2309,7 +2414,8 @@ export 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"
  *
@@ -2348,8 +2454,8 @@ export const map: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const filter: {
   /**
@@ -2358,7 +2464,8 @@ export 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"
    *
@@ -2397,8 +2504,8 @@ export 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>>
   /**
@@ -2407,7 +2514,8 @@ export 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"
    *
@@ -2446,8 +2554,8 @@ export 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>>
   /**
@@ -2456,7 +2564,8 @@ export 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"
    *
@@ -2495,8 +2604,8 @@ export 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>>
   /**
@@ -2505,7 +2614,8 @@ export 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"
    *
@@ -2544,8 +2654,8 @@ export 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>>
 } = dual(
@@ -2565,7 +2675,8 @@ export 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"
  *
@@ -2612,15 +2723,16 @@ export const filter: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export 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"
    *
@@ -2667,15 +2779,16 @@ export 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"
    *
@@ -2722,8 +2835,8 @@ export 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>
 } = dual(
@@ -2742,7 +2855,8 @@ export 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"
  *
@@ -2789,8 +2903,8 @@ export const reduce: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const filterMap: {
   /**
@@ -2800,7 +2914,8 @@ export 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"
    *
@@ -2847,8 +2962,8 @@ export 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>>
   /**
@@ -2858,7 +2973,8 @@ export 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"
    *
@@ -2905,8 +3021,8 @@ export 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>>
 } = dual(
@@ -2925,16 +3041,18 @@ export const filterMap: {
 /**
  * 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
@@ -2953,29 +3071,31 @@ export 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 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
@@ -2994,29 +3114,31 @@ export 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
@@ -3035,14 +3157,14 @@ export 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>
 } = dual(
@@ -3057,7 +3179,8 @@ export 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"
  *
@@ -3092,15 +3215,16 @@ export const hasBy: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export 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"
    *
@@ -3135,15 +3259,16 @@ export 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"
    *
@@ -3178,8 +3303,8 @@ export 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]>>
 } = dual(
@@ -3194,7 +3319,8 @@ export const findFirst: {
 /**
  * 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"
  *
@@ -3228,14 +3354,15 @@ export const findFirst: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export 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"
    *
@@ -3269,14 +3396,15 @@ export 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"
    *
@@ -3310,8 +3438,8 @@ export 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>
 } = dual(
@@ -3325,7 +3453,8 @@ export const some: {
 /**
  * Checks if all entries in the TxHashMap satisfy the given predicate.
  *
- * @example
+ * **Example** (Checking whether every entry matches)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -3359,14 +3488,15 @@ export const some: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export 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"
    *
@@ -3400,14 +3530,15 @@ export 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"
    *
@@ -3441,8 +3572,8 @@ export 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>
 } = dual(
@@ -3457,7 +3588,8 @@ export 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"
  *
@@ -3491,15 +3623,16 @@ export const every: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export 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"
    *
@@ -3533,15 +3666,16 @@ export 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"
    *
@@ -3575,8 +3709,8 @@ export 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>
 } = dual(
@@ -3593,13 +3727,13 @@ export const forEach: {
 )
 
 /**
- * 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"
  *
@@ -3640,18 +3774,18 @@ export const forEach: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export 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"
    *
@@ -3692,18 +3826,18 @@ export 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"
    *
@@ -3744,8 +3878,8 @@ export const flatMap: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <K, V, A>(
     self: TxHashMap<K, V>,
@@ -3760,13 +3894,13 @@ export const flatMap: {
     Effect.gen(function*() {
       const currentMap = yield* TxRef.get(self.ref)
       const result = yield* empty</**
-       * 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"
        *
@@ -3807,17 +3941,17 @@ export const flatMap: {
        * })
        * ```
        *
-       * @since 2.0.0
        * @category combinators
+       * @since 4.0.0
        */
       K, /**
-       * 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"
        *
@@ -3858,8 +3992,8 @@ export const flatMap: {
        * })
        * ```
        *
-       * @since 2.0.0
        * @category combinators
+       * @since 4.0.0
        */
       A>()
 
@@ -3880,7 +4014,8 @@ export 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"
  *
@@ -3912,12 +4047,13 @@ export 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 const compact = <K, A>(
   self: TxHashMap<K, Option.Option<A>>
@@ -3932,7 +4068,8 @@ export const compact = <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"
  *
@@ -3945,22 +4082,24 @@ export const compact = <K, A>(
  *
  *   // 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 const toEntries = <K, V>(
   self: TxHashMap<K, V>
@@ -3970,7 +4109,8 @@ export const toEntries = <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"
  *
@@ -3983,24 +4123,23 @@ export const toEntries = <K, V>(
  *
  *   // 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 const toValues = <K, V>(self: TxHashMap<K, V>): Effect.Effect<Array<V>> => values(self)