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

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 2.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,15 @@ export interface TxHashMap<in out K, in out V> extends Inspectable, Pipeable {
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.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 +137,15 @@ export declare namespace TxHashMap {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category type-level
+     * @since 2.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 +169,15 @@ export declare namespace TxHashMap {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category type-level
+     * @since 2.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 +204,16 @@ export declare namespace TxHashMap {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category type-level
+     * @since 2.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 +235,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 +268,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 +304,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 +337,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 +370,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 +403,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 +414,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 +440,8 @@ export declare const get: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const set: {
     /**
@@ -413,7 +450,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 +476,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 +486,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 +512,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 +545,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 +577,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 +609,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 +620,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 +649,8 @@ export declare const has: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const remove: {
     /**
@@ -616,7 +659,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 +688,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 +698,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 +727,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 +738,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 +766,15 @@ export declare const remove: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.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 +800,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 +830,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 +855,21 @@ export declare const isEmpty: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<boo
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.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 +903,21 @@ export declare const isNonEmpty: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.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 +951,21 @@ export declare const modify: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +999,8 @@ export declare const modify: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K, V>(self: TxHashMap<K, V>, key: K, f: (value: V) => V): Effect.Effect<Option.Option<V>>;
 };
@@ -950,7 +1011,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 +1051,8 @@ export declare const modify: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const modifyAt: {
     /**
@@ -1000,7 +1062,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 +1102,8 @@ export declare const modifyAt: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K, V>(key: K, f: (value: Option.Option<V>) => Option.Option<V>): (self: TxHashMap<K, V>) => Effect.Effect<void>;
     /**
@@ -1050,7 +1113,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 +1153,16 @@ export declare const modifyAt: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +1186,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 +1206,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 +1219,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 +1239,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 +1253,15 @@ export declare const values: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Arra
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.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 +1289,8 @@ export declare const entries: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Arr
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const snapshot: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<HashMap.HashMap<K, V>>;
 /**
@@ -1231,7 +1300,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 +1338,8 @@ export declare const snapshot: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Ha
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const union: {
     /**
@@ -1279,7 +1349,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 +1387,8 @@ export declare const union: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K1 extends K, K, V1 extends V, V>(other: HashMap.HashMap<K1, V1>): (self: TxHashMap<K, V>) => Effect.Effect<void>;
     /**
@@ -1327,7 +1398,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 +1436,8 @@ export declare const union: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K1 extends K, K, V1 extends V, V>(self: TxHashMap<K, V>, other: HashMap.HashMap<K1, V1>): Effect.Effect<void>;
 };
@@ -1375,7 +1447,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 +1481,8 @@ export declare const union: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const removeMany: {
     /**
@@ -1418,7 +1491,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 +1525,8 @@ export declare const removeMany: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K1 extends K, K>(keys: Iterable<K1>): <V>(self: TxHashMap<K, V>) => Effect.Effect<void>;
     /**
@@ -1461,7 +1535,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 +1569,8 @@ export declare const removeMany: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K1 extends K, K, V>(self: TxHashMap<K, V>, keys: Iterable<K1>): Effect.Effect<void>;
 };
@@ -1505,7 +1580,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 +1629,8 @@ export declare const removeMany: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const setMany: {
     /**
@@ -1563,7 +1639,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 +1688,8 @@ export declare const setMany: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K1 extends K, K, V1 extends V, V>(entries: Iterable<readonly [K1, V1]>): (self: TxHashMap<K, V>) => Effect.Effect<void>;
     /**
@@ -1621,7 +1698,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 +1747,16 @@ export declare const setMany: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +1779,27 @@ export declare const setMany: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.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 +1820,27 @@ export declare const isTxHashMap: <K, V>(value: unknown) => value is TxHashMap<K
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.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 +1861,27 @@ export declare const getHash: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +1902,20 @@ export declare const getHash: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +1953,19 @@ export declare const getHash: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.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 +2003,19 @@ export declare const hasHash: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +2053,8 @@ export declare const hasHash: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K1 extends K, K, V>(self: TxHashMap<K, V>, key: K1, hash: number): Effect.Effect<boolean>;
 };
@@ -1961,7 +2064,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 +2101,8 @@ export declare const hasHash: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const map: {
     /**
@@ -2007,7 +2111,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 +2148,8 @@ export declare const map: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <A, V, K>(f: (value: V, key: K) => A): (self: TxHashMap<K, V>) => Effect.Effect<TxHashMap<K, A>>;
     /**
@@ -2053,7 +2158,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 +2195,8 @@ export declare const map: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K, V, A>(self: TxHashMap<K, V>, f: (value: V, key: K) => A): Effect.Effect<TxHashMap<K, A>>;
 };
@@ -2100,7 +2206,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 +2246,8 @@ export declare const map: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const filter: {
     /**
@@ -2149,7 +2256,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 +2296,8 @@ export declare const filter: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +2306,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 +2346,8 @@ export declare const filter: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K, V>(predicate: (value: V, key: K) => boolean): (self: TxHashMap<K, V>) => Effect.Effect<TxHashMap<K, V>>;
     /**
@@ -2247,7 +2356,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 +2396,8 @@ export declare const filter: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +2406,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 +2446,8 @@ export declare const filter: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K, V>(self: TxHashMap<K, V>, predicate: (value: V, key: K) => boolean): Effect.Effect<TxHashMap<K, V>>;
 };
@@ -2344,7 +2455,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 +2503,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 +2559,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 +2615,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 +2627,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 +2675,8 @@ export declare const reduce: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const filterMap: {
     /**
@@ -2571,7 +2686,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 +2734,8 @@ export declare const filterMap: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +2745,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 +2793,26 @@ export declare const filterMap: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +2831,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 2.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 +2874,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 2.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 +2917,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 2.0.0
      */
     <K, V>(self: TxHashMap<K, V>, predicate: (value: V, key: K) => boolean): Effect.Effect<boolean>;
 };
@@ -2809,7 +2932,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 +2968,16 @@ export declare const hasBy: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.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 +3012,16 @@ export declare const findFirst: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +3056,16 @@ export declare const findFirst: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +3099,15 @@ export declare const findFirst: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.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 +3141,15 @@ export declare const some: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +3183,16 @@ export declare const some: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +3226,15 @@ export declare const some: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.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 +3268,15 @@ export declare const every: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +3310,8 @@ export declare const every: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K, V>(self: TxHashMap<K, V>, predicate: (value: V, key: K) => boolean): Effect.Effect<boolean>;
 };
@@ -3187,7 +3319,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 +3354,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 +3397,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 +3440,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 +3493,18 @@ export declare const forEach: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.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 +3545,18 @@ export declare const flatMap: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +3597,8 @@ export declare const flatMap: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.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 +3608,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 +3641,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 2.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 +3668,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 2.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 +3706,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 2.0.0
  */
 export declare const toValues: <K, V>(self: TxHashMap<K, V>) => Effect.Effect<Array<V>>;
 export {};