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

package/src/Trie.ts

@@ -26,7 +26,12 @@ import type { Covariant, NoInfer } from "./Types.ts"
 const TypeId = TR.TrieTypeId
 
 /**
- * @example
+ * An immutable string-keyed map optimized for prefix lookup. Iteration yields
+ * `[key, value]` pairs in key order, and update operations such as insert and
+ * remove return new `Trie` values.
+ *
+ * **Example** (Using a trie for prefix search)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  *
@@ -59,8 +64,8 @@ const TypeId = TR.TrieTypeId
  * console.log(Trie.size(trie)) // 4
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Trie<in out Value> extends Iterable<[string, Value]>, Equal, Pipeable, Inspectable {
   readonly [TypeId]: {
@@ -71,7 +76,8 @@ export interface Trie<in out Value> extends Iterable<[string, Value]>, Equal, Pi
 /**
  * Creates an empty `Trie`.
  *
- * @example
+ * **Example** (Creating an empty trie)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -82,15 +88,16 @@ export interface Trie<in out Value> extends Iterable<[string, Value]>, Equal, Pi
  * assert.deepStrictEqual(Array.from(trie), [])
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const empty: <V = never>() => Trie<V> = TR.empty
 
 /**
  * Creates a new `Trie` from an iterable collection of key/value pairs (e.g. `Array<[string, V]>`).
  *
- * @example
+ * **Example** (Creating a trie from entries)
+ *
  * ```ts
  * import * as Equal from "effect/Equal"
  * import * as Trie from "effect/Trie"
@@ -116,15 +123,16 @@ export const empty: <V = never>() => Trie<V> = TR.empty
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromIterable: <V>(entries: Iterable<readonly [string, V]>) => Trie<V> = TR.fromIterable
 
 /**
  * Constructs a new `Trie` from the specified entries (`[string, V]`).
  *
- * @example
+ * **Example** (Constructing a trie from entries)
+ *
  * ```ts
  * import * as Equal from "effect/Equal"
  * import * as Trie from "effect/Trie"
@@ -139,8 +147,8 @@ export const fromIterable: <V>(entries: Iterable<readonly [string, V]>) => Trie<
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make: <Entries extends Array<readonly [string, any]>>(
   ...entries: Entries
@@ -149,7 +157,8 @@ export const make: <Entries extends Array<readonly [string, any]>>(
 /**
  * Insert a new entry in the `Trie`.
  *
- * @example
+ * **Example** (Inserting entries)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -170,14 +179,15 @@ export const make: <Entries extends Array<readonly [string, any]>>(
  * ]])
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const insert: {
   /**
    * Insert a new entry in the `Trie`.
    *
-   * @example
+   * **Example** (Inserting entries)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -198,14 +208,15 @@ export const insert: {
    * ]])
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(key: string, value: V): (self: Trie<V>) => Trie<V>
   /**
    * Insert a new entry in the `Trie`.
    *
-   * @example
+   * **Example** (Inserting entries)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -226,8 +237,8 @@ export const insert: {
    * ]])
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(self: Trie<V>, key: string, value: V): Trie<V>
 } = TR.insert
@@ -237,7 +248,8 @@ export const insert: {
  *
  * The keys are returned in alphabetical order, regardless of insertion order.
  *
- * @example
+ * **Example** (Reading keys in alphabetical order)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -252,8 +264,8 @@ export const insert: {
  * assert.deepStrictEqual(result, ["abc", "bca", "cab"])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const keys: <V>(self: Trie<V>) => IterableIterator<string> = TR.keys
 
@@ -262,7 +274,8 @@ export const keys: <V>(self: Trie<V>) => IterableIterator<string> = TR.keys
  *
  * Values are ordered based on their key in alphabetical order, regardless of insertion order.
  *
- * @example
+ * **Example** (Reading values by key order)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -277,8 +290,8 @@ export const keys: <V>(self: Trie<V>) => IterableIterator<string> = TR.keys
  * assert.deepStrictEqual(result, [2, 0, 1])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const values: <V>(self: Trie<V>) => IterableIterator<V> = TR.values
 
@@ -287,7 +300,8 @@ export const values: <V>(self: Trie<V>) => IterableIterator<V> = TR.values
  *
  * The entries are returned by keys in alphabetical order, regardless of insertion order.
  *
- * @example
+ * **Example** (Reading entries in alphabetical order)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -301,17 +315,18 @@ export const values: <V>(self: Trie<V>) => IterableIterator<V> = TR.values
  * assert.deepStrictEqual(result, [["call", 0], ["me", 1]])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const entries: <V>(self: Trie<V>) => IterableIterator<[string, V]> = TR.entries
 
 /**
- * Returns an `Array<[K, V]>` of the entries within the `Trie`.
+ * Returns an `Array<[string, V]>` of the entries within the `Trie`.
  *
  * Equivalent to `Array.from(Trie.entries(trie))`.
  *
- * @example
+ * **Example** (Converting entries to an array)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -325,8 +340,8 @@ export const entries: <V>(self: Trie<V>) => IterableIterator<[string, V]> = TR.e
  * assert.deepStrictEqual(result, [["call", 0], ["me", 1]])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const toEntries = <V>(self: Trie<V>): Array<[string, V]> => Array.from(entries(self))
 
@@ -334,7 +349,8 @@ export const toEntries = <V>(self: Trie<V>): Array<[string, V]> => Array.from(en
  * Returns an `IterableIterator` of the keys within the `Trie`
  * that have `prefix` as prefix (`prefix` included if it exists).
  *
- * @example
+ * **Example** (Finding keys with a prefix)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -350,15 +366,16 @@ export const toEntries = <V>(self: Trie<V>): Array<[string, V]> => Array.from(en
  * assert.deepStrictEqual(result, ["she", "shells"])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const keysWithPrefix: {
   /**
    * Returns an `IterableIterator` of the keys within the `Trie`
    * that have `prefix` as prefix (`prefix` included if it exists).
    *
-   * @example
+   * **Example** (Finding keys with a prefix)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -374,15 +391,16 @@ export const keysWithPrefix: {
    * assert.deepStrictEqual(result, ["she", "shells"])
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   (prefix: string): <V>(self: Trie<V>) => IterableIterator<string>
   /**
    * Returns an `IterableIterator` of the keys within the `Trie`
    * that have `prefix` as prefix (`prefix` included if it exists).
    *
-   * @example
+   * **Example** (Finding keys with a prefix)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -398,8 +416,8 @@ export const keysWithPrefix: {
    * assert.deepStrictEqual(result, ["she", "shells"])
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <V>(self: Trie<V>, prefix: string): IterableIterator<string>
 } = TR.keysWithPrefix
@@ -408,7 +426,8 @@ export const keysWithPrefix: {
  * Returns an `IterableIterator` of the values within the `Trie`
  * that have `prefix` as prefix (`prefix` included if it exists).
  *
- * @example
+ * **Example** (Finding values with a prefix)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -426,15 +445,16 @@ export const keysWithPrefix: {
  * assert.deepStrictEqual(result, [0, 1])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const valuesWithPrefix: {
   /**
    * Returns an `IterableIterator` of the values within the `Trie`
    * that have `prefix` as prefix (`prefix` included if it exists).
    *
-   * @example
+   * **Example** (Finding values with a prefix)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -452,15 +472,16 @@ export const valuesWithPrefix: {
    * assert.deepStrictEqual(result, [0, 1])
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   (prefix: string): <V>(self: Trie<V>) => IterableIterator<V>
   /**
    * Returns an `IterableIterator` of the values within the `Trie`
    * that have `prefix` as prefix (`prefix` included if it exists).
    *
-   * @example
+   * **Example** (Finding values with a prefix)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -478,8 +499,8 @@ export const valuesWithPrefix: {
    * assert.deepStrictEqual(result, [0, 1])
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <V>(self: Trie<V>, prefix: string): IterableIterator<V>
 } = TR.valuesWithPrefix
@@ -488,7 +509,8 @@ export const valuesWithPrefix: {
  * Returns an `IterableIterator` of the entries within the `Trie`
  * that have `prefix` as prefix (`prefix` included if it exists).
  *
- * @example
+ * **Example** (Finding entries with a prefix)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -504,15 +526,16 @@ export const valuesWithPrefix: {
  * assert.deepStrictEqual(result, [["she", 0], ["shells", 1]])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const entriesWithPrefix: {
   /**
    * Returns an `IterableIterator` of the entries within the `Trie`
    * that have `prefix` as prefix (`prefix` included if it exists).
    *
-   * @example
+   * **Example** (Finding entries with a prefix)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -528,15 +551,16 @@ export const entriesWithPrefix: {
    * assert.deepStrictEqual(result, [["she", 0], ["shells", 1]])
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   (prefix: string): <V>(self: Trie<V>) => IterableIterator<[string, V]>
   /**
    * Returns an `IterableIterator` of the entries within the `Trie`
    * that have `prefix` as prefix (`prefix` included if it exists).
    *
-   * @example
+   * **Example** (Finding entries with a prefix)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -552,17 +576,18 @@ export const entriesWithPrefix: {
    * assert.deepStrictEqual(result, [["she", 0], ["shells", 1]])
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <V>(self: Trie<V>, prefix: string): IterableIterator<[string, V]>
 } = TR.entriesWithPrefix
 
 /**
- * Returns `Array<[K, V]>` of the entries within the `Trie`
- * that have `prefix` as prefix (`prefix` included if it exists).
+ * Returns an `Array<[string, V]>` of the entries within the `Trie` whose keys
+ * start with `prefix`, including the entry for `prefix` itself when it exists.
+ *
+ * **Example** (Converting prefixed entries to an array)
  *
- * @example
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -578,15 +603,16 @@ export const entriesWithPrefix: {
  * assert.deepStrictEqual(result, [["she", 3], ["shells", 0]])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const toEntriesWithPrefix: {
   /**
-   * Returns `Array<[K, V]>` of the entries within the `Trie`
-   * that have `prefix` as prefix (`prefix` included if it exists).
+   * Returns an `Array<[string, V]>` of the entries within the `Trie` whose keys
+   * start with `prefix`, including the entry for `prefix` itself when it exists.
+   *
+   * **Example** (Converting prefixed entries to an array)
    *
-   * @example
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -602,15 +628,16 @@ export const toEntriesWithPrefix: {
    * assert.deepStrictEqual(result, [["she", 3], ["shells", 0]])
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   (prefix: string): <V>(self: Trie<V>) => Array<[string, V]>
   /**
-   * Returns `Array<[K, V]>` of the entries within the `Trie`
-   * that have `prefix` as prefix (`prefix` included if it exists).
+   * Returns an `Array<[string, V]>` of the entries within the `Trie` whose keys
+   * start with `prefix`, including the entry for `prefix` itself when it exists.
+   *
+   * **Example** (Converting prefixed entries to an array)
    *
-   * @example
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -626,8 +653,8 @@ export const toEntriesWithPrefix: {
    * assert.deepStrictEqual(result, [["she", 3], ["shells", 0]])
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <V>(self: Trie<V>, prefix: string): Array<[string, V]>
 } = TR.toEntriesWithPrefix
@@ -636,7 +663,8 @@ export const toEntriesWithPrefix: {
  * Returns the longest key/value in the `Trie`
  * that is a prefix of that `key` if it exists, `None` otherwise.
  *
- * @example
+ * **Example** (Finding the longest prefix)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -657,15 +685,16 @@ export const toEntriesWithPrefix: {
  * }
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const longestPrefixOf: {
   /**
    * Returns the longest key/value in the `Trie`
    * that is a prefix of that `key` if it exists, `None` otherwise.
    *
-   * @example
+   * **Example** (Finding the longest prefix)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -686,15 +715,16 @@ export const longestPrefixOf: {
    * }
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   (key: string): <V>(self: Trie<V>) => Option<[string, V]>
   /**
    * Returns the longest key/value in the `Trie`
    * that is a prefix of that `key` if it exists, `None` otherwise.
    *
-   * @example
+   * **Example** (Finding the longest prefix)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -715,8 +745,8 @@ export const longestPrefixOf: {
    * }
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <V>(self: Trie<V>, key: string): Option<[string, V]>
 } = TR.longestPrefixOf
@@ -724,7 +754,8 @@ export const longestPrefixOf: {
 /**
  * Returns the size of the `Trie` (number of entries in the `Trie`).
  *
- * @example
+ * **Example** (Getting the size)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -737,15 +768,16 @@ export const longestPrefixOf: {
  * assert.equal(Trie.size(trie), 2)
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const size: <V>(self: Trie<V>) => number = TR.size
 
 /**
  * Safely lookup the value for the specified key in the `Trie`.
  *
- * @example
+ * **Example** (Looking up values safely)
+ *
  * ```ts
  * import * as Option from "effect/Option"
  * import * as Trie from "effect/Trie"
@@ -768,14 +800,15 @@ export const size: <V>(self: Trie<V>) => number = TR.size
  * assert.deepStrictEqual(Trie.get(trie, "mea"), Option.none())
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const get: {
   /**
    * Safely lookup the value for the specified key in the `Trie`.
    *
-   * @example
+   * **Example** (Looking up values safely)
+   *
    * ```ts
    * import * as Option from "effect/Option"
    * import * as Trie from "effect/Trie"
@@ -798,14 +831,15 @@ export const get: {
    * assert.deepStrictEqual(Trie.get(trie, "mea"), Option.none())
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   (key: string): <V>(self: Trie<V>) => Option<V>
   /**
    * Safely lookup the value for the specified key in the `Trie`.
    *
-   * @example
+   * **Example** (Looking up values safely)
+   *
    * ```ts
    * import * as Option from "effect/Option"
    * import * as Trie from "effect/Trie"
@@ -828,8 +862,8 @@ export const get: {
    * assert.deepStrictEqual(Trie.get(trie, "mea"), Option.none())
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(self: Trie<V>, key: string): Option<V>
 } = TR.get
@@ -837,7 +871,8 @@ export const get: {
 /**
  * Check if the given key exists in the `Trie`.
  *
- * @example
+ * **Example** (Checking key membership)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -859,14 +894,15 @@ export const get: {
  * assert.equal(Trie.has(trie, "mea"), false)
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const has: {
   /**
    * Check if the given key exists in the `Trie`.
    *
-   * @example
+   * **Example** (Checking key membership)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -888,14 +924,15 @@ export const has: {
    * assert.equal(Trie.has(trie, "mea"), false)
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   (key: string): <V>(self: Trie<V>) => boolean
   /**
    * Check if the given key exists in the `Trie`.
    *
-   * @example
+   * **Example** (Checking key membership)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -917,16 +954,17 @@ export const has: {
    * assert.equal(Trie.has(trie, "mea"), false)
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(self: Trie<V>, key: string): boolean
 } = TR.has
 
 /**
- * Checks if the `Trie` contains any entries.
+ * Returns `true` when the `Trie` contains no entries.
+ *
+ * **Example** (Checking whether a trie is empty)
  *
- * @example
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -938,8 +976,8 @@ export const has: {
  * assert.equal(Trie.isEmpty(trie1), false)
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const isEmpty: <V>(self: Trie<V>) => boolean = TR.isEmpty
 
@@ -949,7 +987,8 @@ export const isEmpty: <V>(self: Trie<V>) => boolean = TR.isEmpty
  * `getUnsafe` will throw if the key is not found. Use `get` instead to safely
  * get a value from the `Trie`.
  *
- * @example
+ * **Example** (Looking up values unsafely)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -962,8 +1001,8 @@ export const isEmpty: <V>(self: Trie<V>) => boolean = TR.isEmpty
  * assert.throws(() => Trie.getUnsafe(trie, "mae"))
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export const getUnsafe: {
   /**
@@ -972,7 +1011,8 @@ export const getUnsafe: {
    * `getUnsafe` will throw if the key is not found. Use `get` instead to safely
    * get a value from the `Trie`.
    *
-   * @example
+   * **Example** (Looking up values unsafely)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -985,8 +1025,8 @@ export const getUnsafe: {
    * assert.throws(() => Trie.getUnsafe(trie, "mae"))
    * ```
    *
-   * @since 2.0.0
    * @category unsafe
+   * @since 2.0.0
    */
   (key: string): <V>(self: Trie<V>) => V
   /**
@@ -995,7 +1035,8 @@ export const getUnsafe: {
    * `getUnsafe` will throw if the key is not found. Use `get` instead to safely
    * get a value from the `Trie`.
    *
-   * @example
+   * **Example** (Looking up values unsafely)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -1008,8 +1049,8 @@ export const getUnsafe: {
    * assert.throws(() => Trie.getUnsafe(trie, "mae"))
    * ```
    *
-   * @since 2.0.0
    * @category unsafe
+   * @since 2.0.0
    */
   <V>(self: Trie<V>, key: string): V
 } = TR.getUnsafe
@@ -1017,7 +1058,8 @@ export const getUnsafe: {
 /**
  * Remove the entry for the specified key in the `Trie`.
  *
- * @example
+ * **Example** (Removing entries)
+ *
  * ```ts
  * import * as Option from "effect/Option"
  * import * as Trie from "effect/Trie"
@@ -1038,14 +1080,15 @@ export const getUnsafe: {
  * assert.deepStrictEqual(Trie.get(trie2, "call"), Option.none())
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const remove: {
   /**
    * Remove the entry for the specified key in the `Trie`.
    *
-   * @example
+   * **Example** (Removing entries)
+   *
    * ```ts
    * import * as Option from "effect/Option"
    * import * as Trie from "effect/Trie"
@@ -1066,14 +1109,15 @@ export const remove: {
    * assert.deepStrictEqual(Trie.get(trie2, "call"), Option.none())
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   (key: string): <V>(self: Trie<V>) => Trie<V>
   /**
    * Remove the entry for the specified key in the `Trie`.
    *
-   * @example
+   * **Example** (Removing entries)
+   *
    * ```ts
    * import * as Option from "effect/Option"
    * import * as Trie from "effect/Trie"
@@ -1094,8 +1138,8 @@ export const remove: {
    * assert.deepStrictEqual(Trie.get(trie2, "call"), Option.none())
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(self: Trie<V>, key: string): Trie<V>
 } = TR.remove
@@ -1103,7 +1147,8 @@ export const remove: {
 /**
  * Reduce a state over the entries of the `Trie`.
  *
- * @example
+ * **Example** (Reducing entries)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -1134,14 +1179,15 @@ export const remove: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category folding
+ * @since 2.0.0
  */
 export const reduce: {
   /**
    * Reduce a state over the entries of the `Trie`.
    *
-   * @example
+   * **Example** (Reducing entries)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -1172,14 +1218,15 @@ export const reduce: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category folding
+   * @since 2.0.0
    */
   <Z, V>(zero: Z, f: (accumulator: Z, value: V, key: string) => Z): (self: Trie<V>) => Z
   /**
    * Reduce a state over the entries of the `Trie`.
    *
-   * @example
+   * **Example** (Reducing entries)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -1210,8 +1257,8 @@ export const reduce: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category folding
+   * @since 2.0.0
    */
   <Z, V>(self: Trie<V>, zero: Z, f: (accumulator: Z, value: V, key: string) => Z): Z
 } = TR.reduce
@@ -1219,7 +1266,8 @@ export const reduce: {
 /**
  * Maps over the entries of the `Trie` using the specified function.
  *
- * @example
+ * **Example** (Mapping entries)
+ *
  * ```ts
  * import * as Equal from "effect/Equal"
  * import * as Trie from "effect/Trie"
@@ -1247,14 +1295,15 @@ export const reduce: {
  * assert.equal(Equal.equals(Trie.map(trie, (_, k) => k.length), trieMapK), true)
  * ```
  *
- * @since 2.0.0
  * @category folding
+ * @since 2.0.0
  */
 export const map: {
   /**
    * Maps over the entries of the `Trie` using the specified function.
    *
-   * @example
+   * **Example** (Mapping entries)
+   *
    * ```ts
    * import * as Equal from "effect/Equal"
    * import * as Trie from "effect/Trie"
@@ -1282,14 +1331,15 @@ export const map: {
    * assert.equal(Equal.equals(Trie.map(trie, (_, k) => k.length), trieMapK), true)
    * ```
    *
-   * @since 2.0.0
    * @category folding
+   * @since 2.0.0
    */
   <A, V>(f: (value: V, key: string) => A): (self: Trie<V>) => Trie<A>
   /**
    * Maps over the entries of the `Trie` using the specified function.
    *
-   * @example
+   * **Example** (Mapping entries)
+   *
    * ```ts
    * import * as Equal from "effect/Equal"
    * import * as Trie from "effect/Trie"
@@ -1317,8 +1367,8 @@ export const map: {
    * assert.equal(Equal.equals(Trie.map(trie, (_, k) => k.length), trieMapK), true)
    * ```
    *
-   * @since 2.0.0
    * @category folding
+   * @since 2.0.0
    */
   <V, A>(self: Trie<V>, f: (value: V, key: string) => A): Trie<A>
 } = TR.map
@@ -1326,7 +1376,8 @@ export const map: {
 /**
  * Filters entries out of a `Trie` using the specified predicate.
  *
- * @example
+ * **Example** (Filtering entries)
+ *
  * ```ts
  * import * as Equal from "effect/Equal"
  * import * as Trie from "effect/Trie"
@@ -1354,14 +1405,15 @@ export const map: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const filter: {
   /**
    * Filters entries out of a `Trie` using the specified predicate.
    *
-   * @example
+   * **Example** (Filtering entries)
+   *
    * ```ts
    * import * as Equal from "effect/Equal"
    * import * as Trie from "effect/Trie"
@@ -1389,14 +1441,15 @@ export const filter: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <A, B extends A>(f: (a: NoInfer<A>, k: string) => a is B): (self: Trie<A>) => Trie<B>
   /**
    * Filters entries out of a `Trie` using the specified predicate.
    *
-   * @example
+   * **Example** (Filtering entries)
+   *
    * ```ts
    * import * as Equal from "effect/Equal"
    * import * as Trie from "effect/Trie"
@@ -1424,14 +1477,15 @@ export const filter: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <A>(f: (a: NoInfer<A>, k: string) => boolean): (self: Trie<A>) => Trie<A>
   /**
    * Filters entries out of a `Trie` using the specified predicate.
    *
-   * @example
+   * **Example** (Filtering entries)
+   *
    * ```ts
    * import * as Equal from "effect/Equal"
    * import * as Trie from "effect/Trie"
@@ -1459,14 +1513,15 @@ export const filter: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <A, B extends A>(self: Trie<A>, f: (a: A, k: string) => a is B): Trie<B>
   /**
    * Filters entries out of a `Trie` using the specified predicate.
    *
-   * @example
+   * **Example** (Filtering entries)
+   *
    * ```ts
    * import * as Equal from "effect/Equal"
    * import * as Trie from "effect/Trie"
@@ -1494,8 +1549,8 @@ export const filter: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <A>(self: Trie<A>, f: (a: A, k: string) => boolean): Trie<A>
 } = TR.filter
@@ -1504,7 +1559,8 @@ export const filter: {
  * Maps over the entries of the `Trie` using the specified filter and keeps
  * only successful results.
  *
- * @example
+ * **Example** (Filtering and mapping entries)
+ *
  * ```ts
  * import * as Equal from "effect/Equal"
  * import * as Result from "effect/Result"
@@ -1545,15 +1601,16 @@ export const filter: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const filterMap: {
   /**
    * Maps over the entries of the `Trie` using the specified filter and keeps
    * only successful results.
    *
-   * @example
+   * **Example** (Filtering and mapping entries)
+   *
    * ```ts
    * import * as Equal from "effect/Equal"
    * import * as Result from "effect/Result"
@@ -1594,15 +1651,16 @@ export const filterMap: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <A, B, X>(f: (input: A, key: string) => Result<B, X>): (self: Trie<A>) => Trie<B>
   /**
    * Maps over the entries of the `Trie` using the specified filter and keeps
    * only successful results.
    *
-   * @example
+   * **Example** (Filtering and mapping entries)
+   *
    * ```ts
    * import * as Equal from "effect/Equal"
    * import * as Result from "effect/Result"
@@ -1643,8 +1701,8 @@ export const filterMap: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <A, B, X>(self: Trie<A>, f: (input: A, key: string) => Result<B, X>): Trie<B>
 } = TR.filterMap
@@ -1652,7 +1710,8 @@ export const filterMap: {
 /**
  * Filters out `None` values from a `Trie` of `Options`s.
  *
- * @example
+ * **Example** (Compacting optional values)
+ *
  * ```ts
  * import * as Equal from "effect/Equal"
  * import * as Option from "effect/Option"
@@ -1673,15 +1732,16 @@ export const filterMap: {
  * assert.equal(Equal.equals(Trie.compact(trie), trieMapV), true)
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const compact: <A>(self: Trie<Option<A>>) => Trie<A> = TR.compact
 
 /**
  * Applies the specified function to the entries of the `Trie`.
  *
- * @example
+ * **Example** (Iterating over entries)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -1700,14 +1760,15 @@ export const compact: <A>(self: Trie<Option<A>>) => Trie<A> = TR.compact
  * assert.equal(value, 17)
  * ```
  *
- * @since 2.0.0
  * @category traversing
+ * @since 2.0.0
  */
 export const forEach: {
   /**
    * Applies the specified function to the entries of the `Trie`.
    *
-   * @example
+   * **Example** (Iterating over entries)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -1726,14 +1787,15 @@ export const forEach: {
    * assert.equal(value, 17)
    * ```
    *
-   * @since 2.0.0
    * @category traversing
+   * @since 2.0.0
    */
   <V>(f: (value: V, key: string) => void): (self: Trie<V>) => void
   /**
    * Applies the specified function to the entries of the `Trie`.
    *
-   * @example
+   * **Example** (Iterating over entries)
+   *
    * ```ts
    * import * as Trie from "effect/Trie"
    * import * as assert from "node:assert"
@@ -1752,8 +1814,8 @@ export const forEach: {
    * assert.equal(value, 17)
    * ```
    *
-   * @since 2.0.0
    * @category traversing
+   * @since 2.0.0
    */
   <V>(self: Trie<V>, f: (value: V, key: string) => void): void
 } = TR.forEach
@@ -1761,7 +1823,8 @@ export const forEach: {
 /**
  * Updates the value of the specified key within the `Trie` if it exists.
  *
- * @example
+ * **Example** (Modifying an existing value)
+ *
  * ```ts
  * import * as Equal from "effect/Equal"
  * import * as Option from "effect/Option"
@@ -1782,14 +1845,15 @@ export const forEach: {
  * assert.equal(Equal.equals(trie.pipe(Trie.modify("me", (v) => v)), trie), true)
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const modify: {
   /**
    * Updates the value of the specified key within the `Trie` if it exists.
    *
-   * @example
+   * **Example** (Modifying an existing value)
+   *
    * ```ts
    * import * as Equal from "effect/Equal"
    * import * as Option from "effect/Option"
@@ -1810,14 +1874,15 @@ export const modify: {
    * assert.equal(Equal.equals(trie.pipe(Trie.modify("me", (v) => v)), trie), true)
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(key: string, f: (v: V) => V): (self: Trie<V>) => Trie<V>
   /**
    * Updates the value of the specified key within the `Trie` if it exists.
    *
-   * @example
+   * **Example** (Modifying an existing value)
+   *
    * ```ts
    * import * as Equal from "effect/Equal"
    * import * as Option from "effect/Option"
@@ -1838,8 +1903,8 @@ export const modify: {
    * assert.equal(Equal.equals(trie.pipe(Trie.modify("me", (v) => v)), trie), true)
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(self: Trie<V>, key: string, f: (v: V) => V): Trie<V>
 } = TR.modify
@@ -1847,7 +1912,8 @@ export const modify: {
 /**
  * Removes all entries in the `Trie` which have the specified keys.
  *
- * @example
+ * **Example** (Removing multiple entries)
+ *
  * ```ts
  * import * as Equal from "effect/Equal"
  * import * as Trie from "effect/Trie"
@@ -1868,14 +1934,15 @@ export const modify: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const removeMany: {
   /**
    * Removes all entries in the `Trie` which have the specified keys.
    *
-   * @example
+   * **Example** (Removing multiple entries)
+   *
    * ```ts
    * import * as Equal from "effect/Equal"
    * import * as Trie from "effect/Trie"
@@ -1896,14 +1963,15 @@ export const removeMany: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   (keys: Iterable<string>): <V>(self: Trie<V>) => Trie<V>
   /**
    * Removes all entries in the `Trie` which have the specified keys.
    *
-   * @example
+   * **Example** (Removing multiple entries)
+   *
    * ```ts
    * import * as Equal from "effect/Equal"
    * import * as Trie from "effect/Trie"
@@ -1924,8 +1992,8 @@ export const removeMany: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(self: Trie<V>, keys: Iterable<string>): Trie<V>
 } = TR.removeMany
@@ -1933,7 +2001,8 @@ export const removeMany: {
 /**
  * Insert multiple entries in the `Trie` at once.
  *
- * @example
+ * **Example** (Inserting multiple entries)
+ *
  * ```ts
  * import * as Equal from "effect/Equal"
  * import * as Trie from "effect/Trie"
@@ -1958,14 +2027,15 @@ export const removeMany: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const insertMany: {
   /**
    * Insert multiple entries in the `Trie` at once.
    *
-   * @example
+   * **Example** (Inserting multiple entries)
+   *
    * ```ts
    * import * as Equal from "effect/Equal"
    * import * as Trie from "effect/Trie"
@@ -1990,14 +2060,15 @@ export const insertMany: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(iter: Iterable<[string, V]>): (self: Trie<V>) => Trie<V>
   /**
    * Insert multiple entries in the `Trie` at once.
    *
-   * @example
+   * **Example** (Inserting multiple entries)
+   *
    * ```ts
    * import * as Equal from "effect/Equal"
    * import * as Trie from "effect/Trie"
@@ -2022,8 +2093,8 @@ export const insertMany: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(self: Trie<V>, iter: Iterable<[string, V]>): Trie<V>
 } = TR.insertMany