effect 4.0.0-beta.65 → 4.0.0-beta.67

package/dist/TxHashMap.js

@@ -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.js";
@@ -32,7 +57,8 @@ const TxHashMapProto = {
 /**
  * Creates an empty TxHashMap.
  *
- * @example
+ * **Example** (Creating an empty map)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -54,8 +80,8 @@ const TxHashMapProto = {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const empty = () => Effect.gen(function* () {
   const ref = yield* TxRef.make(HashMap.empty());
@@ -66,7 +92,8 @@ export const empty = () => Effect.gen(function* () {
 /**
  * Creates a TxHashMap from the provided key-value pairs.
  *
- * @example
+ * **Example** (Creating a map from entries)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -91,8 +118,8 @@ export const empty = () => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = (...entries) => Effect.gen(function* () {
   const hashMap = HashMap.make(...entries);
@@ -104,7 +131,8 @@ export const make = (...entries) => Effect.gen(function* () {
 /**
  * Creates a TxHashMap from an iterable of key-value pairs.
  *
- * @example
+ * **Example** (Creating a map from an iterable)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -132,8 +160,8 @@ export const make = (...entries) => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromIterable = entries => Effect.gen(function* () {
   const hashMap = HashMap.fromIterable(entries);
@@ -145,7 +173,8 @@ export const fromIterable = entries => Effect.gen(function* () {
 /**
  * Safely lookup the value for the specified key in the TxHashMap.
  *
- * @example
+ * **Example** (Looking up values safely)
+ *
  * ```ts
  * import { Effect, Option, TxHashMap } from "effect"
  *
@@ -170,8 +199,8 @@ export const fromIterable = entries => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const get = /*#__PURE__*/dual(2, (self, key) => Effect.gen(function* () {
   const map = yield* TxRef.get(self.ref);
@@ -183,7 +212,8 @@ export const get = /*#__PURE__*/dual(2, (self, key) => Effect.gen(function* () {
  * **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"
  *
@@ -208,14 +238,15 @@ export const get = /*#__PURE__*/dual(2, (self, key) => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const set = /*#__PURE__*/dual(3, (self, key, value) => TxRef.update(self.ref, map => HashMap.set(map, key, value)));
 /**
  * Checks if the specified key exists in the TxHashMap.
  *
- * @example
+ * **Example** (Checking for keys)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -239,8 +270,8 @@ export const set = /*#__PURE__*/dual(3, (self, key, value) => TxRef.update(self.
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const has = /*#__PURE__*/dual(2, (self, key) => Effect.gen(function* () {
   const map = yield* TxRef.get(self.ref);
@@ -252,7 +283,8 @@ export const has = /*#__PURE__*/dual(2, (self, key) => Effect.gen(function* () {
  * **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"
  *
@@ -280,8 +312,8 @@ export const has = /*#__PURE__*/dual(2, (self, key) => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const remove = /*#__PURE__*/dual(2, (self, key) => Effect.gen(function* () {
   const currentMap = yield* TxRef.get(self.ref);
@@ -297,7 +329,8 @@ export const remove = /*#__PURE__*/dual(2, (self, key) => Effect.gen(function* (
  * **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"
  *
@@ -324,14 +357,15 @@ export const remove = /*#__PURE__*/dual(2, (self, key) => Effect.gen(function* (
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const clear = self => TxRef.set(self.ref, HashMap.empty());
 /**
  * Returns the number of entries in the TxHashMap.
  *
- * @example
+ * **Example** (Counting entries)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -357,8 +391,8 @@ export const clear = self => TxRef.set(self.ref, HashMap.empty());
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const size = self => Effect.gen(function* () {
   const map = yield* TxRef.get(self.ref);
@@ -367,7 +401,8 @@ export const size = self => Effect.gen(function* () {
 /**
  * Checks if the TxHashMap is empty.
  *
- * @example
+ * **Example** (Checking for an empty map)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -389,8 +424,8 @@ export const size = self => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const isEmpty = self => Effect.gen(function* () {
   const map = yield* TxRef.get(self.ref);
@@ -399,7 +434,8 @@ export const isEmpty = self => Effect.gen(function* () {
 /**
  * Checks if the TxHashMap is non-empty.
  *
- * @example
+ * **Example** (Checking for a non-empty map)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -416,17 +452,21 @@ export const isEmpty = self => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const isNonEmpty = self => 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"
  *
@@ -460,8 +500,8 @@ export const isNonEmpty = self => Effect.map(isEmpty(self), empty => !empty);
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const modify = /*#__PURE__*/dual(3, (self, key, f) => Effect.gen(function* () {
   const currentMap = yield* TxRef.get(self.ref);
@@ -480,7 +520,8 @@ export const modify = /*#__PURE__*/dual(3, (self, key, f) => Effect.gen(function
  * 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"
  *
@@ -519,8 +560,8 @@ export const modify = /*#__PURE__*/dual(3, (self, key, f) => Effect.gen(function
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const modifyAt = /*#__PURE__*/dual(3, (self, key, f) => Effect.gen(function* () {
   const currentMap = yield* TxRef.get(self.ref);
@@ -535,7 +576,8 @@ export const modifyAt = /*#__PURE__*/dual(3, (self, key, f) => Effect.gen(functi
 /**
  * Returns an array of all keys in the TxHashMap.
  *
- * @example
+ * **Example** (Reading keys)
+ *
  * ```ts
  * import { Effect, Option, TxHashMap } from "effect"
  *
@@ -559,8 +601,8 @@ export const modifyAt = /*#__PURE__*/dual(3, (self, key, f) => Effect.gen(functi
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const keys = self => Effect.gen(function* () {
   const map = yield* TxRef.get(self.ref);
@@ -569,7 +611,8 @@ export const keys = self => Effect.gen(function* () {
 /**
  * Returns an array of all values in the TxHashMap.
  *
- * @example
+ * **Example** (Reading values)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -581,12 +624,12 @@ export const keys = self => Effect.gen(function* () {
  *   )
  *
  *   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)
@@ -594,8 +637,8 @@ export const keys = self => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const values = self => Effect.gen(function* () {
   const map = yield* TxRef.get(self.ref);
@@ -604,7 +647,8 @@ export const values = self => Effect.gen(function* () {
 /**
  * Returns an array of all key-value pairs in the TxHashMap.
  *
- * @example
+ * **Example** (Reading entries)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -616,11 +660,12 @@ export const values = self => Effect.gen(function* () {
  *   )
  *
  *   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
@@ -629,8 +674,8 @@ export const values = self => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const entries = self => Effect.gen(function* () {
   const map = yield* TxRef.get(self.ref);
@@ -639,7 +684,8 @@ export const entries = self => Effect.gen(function* () {
 /**
  * Returns an immutable snapshot of the current TxHashMap state.
  *
- * @example
+ * **Example** (Taking immutable snapshots)
+ *
  * ```ts
  * import { Effect, HashMap, TxHashMap } from "effect"
  *
@@ -667,8 +713,8 @@ export const entries = self => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const snapshot = self => TxRef.get(self.ref);
 /**
@@ -678,7 +724,8 @@ export const snapshot = self => TxRef.get(self.ref);
  * **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"
  *
@@ -715,8 +762,8 @@ export const snapshot = self => TxRef.get(self.ref);
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const union = /*#__PURE__*/dual(2, (self, other) => TxRef.update(self.ref, map => HashMap.union(map, other)));
 /**
@@ -725,7 +772,8 @@ export const union = /*#__PURE__*/dual(2, (self, other) => TxRef.update(self.ref
  * **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"
  *
@@ -758,8 +806,8 @@ export const union = /*#__PURE__*/dual(2, (self, other) => TxRef.update(self.ref
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const removeMany = /*#__PURE__*/dual(2, (self, keys) => TxRef.update(self.ref, map => HashMap.removeMany(map, keys)));
 /**
@@ -768,7 +816,8 @@ export const removeMany = /*#__PURE__*/dual(2, (self, keys) => TxRef.update(self
  * **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"
  *
@@ -816,14 +865,15 @@ export const removeMany = /*#__PURE__*/dual(2, (self, keys) => TxRef.update(self
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const setMany = /*#__PURE__*/dual(2, (self, entries) => TxRef.update(self.ref, map => HashMap.setMany(map, entries)));
 /**
  * Returns `true` if the specified value is a `TxHashMap`, `false` otherwise.
  *
- * @example
+ * **Example** (Checking TxHashMap values)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -846,25 +896,29 @@ export const setMany = /*#__PURE__*/dual(2, (self, entries) => TxRef.update(self
  * })
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export const isTxHashMap = value => {
   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)
@@ -885,15 +939,19 @@ export const isTxHashMap = value => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const getHash = /*#__PURE__*/dual(3, (self, key, hash) => TxRef.get(self.ref).pipe(Effect.map(map => HashMap.getHash(map, key, hash))));
 /**
- * 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"
  *
@@ -931,8 +989,8 @@ export const getHash = /*#__PURE__*/dual(3, (self, key, hash) => TxRef.get(self.
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const hasHash = /*#__PURE__*/dual(3, (self, key, hash) => TxRef.get(self.ref).pipe(Effect.map(map => HashMap.hasHash(map, key, hash))));
 /**
@@ -941,7 +999,8 @@ export const hasHash = /*#__PURE__*/dual(3, (self, key, hash) => TxRef.get(self.
  * **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"
  *
@@ -977,8 +1036,8 @@ export const hasHash = /*#__PURE__*/dual(3, (self, key, hash) => TxRef.get(self.
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const map = /*#__PURE__*/dual(2, (self, f) => Effect.gen(function* () {
   const currentMap = yield* TxRef.get(self.ref);
@@ -991,7 +1050,8 @@ export const map = /*#__PURE__*/dual(2, (self, f) => Effect.gen(function* () {
  * **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"
  *
@@ -1030,8 +1090,8 @@ export const map = /*#__PURE__*/dual(2, (self, f) => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const filter = /*#__PURE__*/dual(2, (self, predicate) => Effect.gen(function* () {
   const currentMap = yield* TxRef.get(self.ref);
@@ -1042,7 +1102,8 @@ export const filter = /*#__PURE__*/dual(2, (self, predicate) => Effect.gen(funct
  * 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"
  *
@@ -1089,8 +1150,8 @@ export const filter = /*#__PURE__*/dual(2, (self, predicate) => Effect.gen(funct
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const reduce = /*#__PURE__*/dual(3, (self, zero, f) => TxRef.get(self.ref).pipe(Effect.map(map => HashMap.reduce(map, zero, f))));
 /**
@@ -1100,7 +1161,8 @@ export const reduce = /*#__PURE__*/dual(3, (self, zero, f) => TxRef.get(self.ref
  * **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"
  *
@@ -1147,8 +1209,8 @@ export const reduce = /*#__PURE__*/dual(3, (self, zero, f) => TxRef.get(self.ref
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const filterMap = /*#__PURE__*/dual(2, (self, f) => Effect.gen(function* () {
   const currentMap = yield* TxRef.get(self.ref);
@@ -1158,16 +1220,18 @@ export const filterMap = /*#__PURE__*/dual(2, (self, f) => Effect.gen(function*
 /**
  * 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
@@ -1186,21 +1250,22 @@ export const filterMap = /*#__PURE__*/dual(2, (self, f) => Effect.gen(function*
  *
  *   // 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 const hasBy = /*#__PURE__*/dual(2, (self, predicate) => TxRef.get(self.ref).pipe(Effect.map(map => HashMap.hasBy(map, predicate))));
 /**
  * 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"
  *
@@ -1235,14 +1300,15 @@ export const hasBy = /*#__PURE__*/dual(2, (self, predicate) => TxRef.get(self.re
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const findFirst = /*#__PURE__*/dual(2, (self, predicate) => TxRef.get(self.ref).pipe(Effect.map(map => HashMap.findFirst(map, predicate))));
 /**
  * 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"
  *
@@ -1276,14 +1342,15 @@ export const findFirst = /*#__PURE__*/dual(2, (self, predicate) => TxRef.get(sel
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const some = /*#__PURE__*/dual(2, (self, predicate) => TxRef.get(self.ref).pipe(Effect.map(map => HashMap.some(map, predicate))));
 /**
  * Checks if all entries in the TxHashMap satisfy the given predicate.
  *
- * @example
+ * **Example** (Checking whether every entry matches)
+ *
  * ```ts
  * import { Effect, TxHashMap } from "effect"
  *
@@ -1317,15 +1384,16 @@ export const some = /*#__PURE__*/dual(2, (self, predicate) => TxRef.get(self.ref
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const every = /*#__PURE__*/dual(2, (self, predicate) => TxRef.get(self.ref).pipe(Effect.map(map => HashMap.every(map, predicate))));
 /**
  * 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"
  *
@@ -1359,8 +1427,8 @@ export const every = /*#__PURE__*/dual(2, (self, predicate) => TxRef.get(self.re
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const forEach = /*#__PURE__*/dual(2, (self, f) => Effect.gen(function* () {
   const currentMap = yield* TxRef.get(self.ref);
@@ -1368,13 +1436,13 @@ export const forEach = /*#__PURE__*/dual(2, (self, f) => Effect.gen(function* ()
   yield* Effect.forEach(entries, ([key, value]) => f(value, key));
 }));
 /**
- * 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"
  *
@@ -1415,8 +1483,8 @@ export const forEach = /*#__PURE__*/dual(2, (self, f) => Effect.gen(function* ()
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const flatMap = /*#__PURE__*/dual(2, (self, f) => Effect.gen(function* () {
   const currentMap = yield* TxRef.get(self.ref);
@@ -1435,7 +1503,8 @@ export const flatMap = /*#__PURE__*/dual(2, (self, f) => Effect.gen(function* ()
  * **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"
  *
@@ -1467,12 +1536,13 @@ export const flatMap = /*#__PURE__*/dual(2, (self, f) => Effect.gen(function* ()
  *   // 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 const compact = self => Effect.gen(function* () {
   const currentMap = yield* TxRef.get(self.ref);
@@ -1483,7 +1553,8 @@ export const compact = self => Effect.gen(function* () {
  * 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"
  *
@@ -1496,29 +1567,32 @@ export const compact = self => Effect.gen(function* () {
  *
  *   // 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 const toEntries = self => entries(self);
 /**
  * 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"
  *
@@ -1531,24 +1605,23 @@ export const toEntries = self => entries(self);
  *
  *   // 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 const toValues = self => values(self);
 /**