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

package/dist/Trie.d.ts

@@ -23,7 +23,12 @@ import type { Result } from "./Result.ts";
 import type { Covariant, NoInfer } from "./Types.ts";
 declare const TypeId = "~effect/collections/Trie";
 /**
- * @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"
  *
@@ -56,8 +61,8 @@ declare const TypeId = "~effect/collections/Trie";
  * 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]: {
@@ -67,7 +72,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"
@@ -78,14 +84,15 @@ 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 declare const empty: <V = never>() => Trie<V>;
 /**
  * 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"
@@ -111,14 +118,15 @@ export declare const empty: <V = never>() => Trie<V>;
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromIterable: <V>(entries: Iterable<readonly [string, V]>) => Trie<V>;
 /**
  * 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"
@@ -133,14 +141,15 @@ export declare const fromIterable: <V>(entries: Iterable<readonly [string, V]>)
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const make: <Entries extends Array<readonly [string, any]>>(...entries: Entries) => Trie<Entries[number] extends readonly [any, infer V] ? V : never>;
 /**
  * Insert a new entry in the `Trie`.
  *
- * @example
+ * **Example** (Inserting entries)
+ *
  * ```ts
  * import * as Trie from "effect/Trie"
  * import * as assert from "node:assert"
@@ -161,14 +170,15 @@ export declare const make: <Entries extends Array<readonly [string, any]>>(...en
  * ]])
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export declare 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"
@@ -189,14 +199,15 @@ export declare 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"
@@ -217,8 +228,8 @@ export declare const insert: {
      * ]])
      * ```
      *
-     * @since 2.0.0
      * @category mutations
+     * @since 2.0.0
      */
     <V>(self: Trie<V>, key: string, value: V): Trie<V>;
 };
@@ -227,7 +238,8 @@ export declare 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"
@@ -242,8 +254,8 @@ export declare const insert: {
  * assert.deepStrictEqual(result, ["abc", "bca", "cab"])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const keys: <V>(self: Trie<V>) => IterableIterator<string>;
 /**
@@ -251,7 +263,8 @@ export declare const keys: <V>(self: Trie<V>) => IterableIterator<string>;
  *
  * 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"
@@ -266,8 +279,8 @@ export declare const keys: <V>(self: Trie<V>) => IterableIterator<string>;
  * assert.deepStrictEqual(result, [2, 0, 1])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const values: <V>(self: Trie<V>) => IterableIterator<V>;
 /**
@@ -275,7 +288,8 @@ export declare const values: <V>(self: Trie<V>) => IterableIterator<V>;
  *
  * 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"
@@ -289,16 +303,17 @@ export declare const values: <V>(self: Trie<V>) => IterableIterator<V>;
  * assert.deepStrictEqual(result, [["call", 0], ["me", 1]])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const entries: <V>(self: Trie<V>) => IterableIterator<[string, V]>;
 /**
- * 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"
@@ -312,15 +327,16 @@ export declare const entries: <V>(self: Trie<V>) => IterableIterator<[string, V]
  * assert.deepStrictEqual(result, [["call", 0], ["me", 1]])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const toEntries: <V>(self: Trie<V>) => Array<[string, V]>;
 /**
  * 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"
@@ -336,15 +352,16 @@ export declare const toEntries: <V>(self: Trie<V>) => Array<[string, V]>;
  * assert.deepStrictEqual(result, ["she", "shells"])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare 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"
@@ -360,15 +377,16 @@ export declare 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"
@@ -384,8 +402,8 @@ export declare 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>;
 };
@@ -393,7 +411,8 @@ export declare 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"
@@ -411,15 +430,16 @@ export declare const keysWithPrefix: {
  * assert.deepStrictEqual(result, [0, 1])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare 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"
@@ -437,15 +457,16 @@ export declare 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"
@@ -463,8 +484,8 @@ export declare 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>;
 };
@@ -472,7 +493,8 @@ export declare 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"
@@ -488,15 +510,16 @@ export declare const valuesWithPrefix: {
  * assert.deepStrictEqual(result, [["she", 0], ["shells", 1]])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare 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"
@@ -512,15 +535,16 @@ export declare 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"
@@ -536,16 +560,17 @@ export declare 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]>;
 };
 /**
- * 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"
@@ -561,15 +586,16 @@ export declare const entriesWithPrefix: {
  * assert.deepStrictEqual(result, [["she", 3], ["shells", 0]])
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare 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"
@@ -585,15 +611,16 @@ export declare 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"
@@ -609,8 +636,8 @@ export declare 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]>;
 };
@@ -618,7 +645,8 @@ export declare 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"
@@ -639,15 +667,16 @@ export declare const toEntriesWithPrefix: {
  * }
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare 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"
@@ -668,15 +697,16 @@ export declare 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"
@@ -697,15 +727,16 @@ export declare const longestPrefixOf: {
      * }
      * ```
      *
-     * @since 2.0.0
      * @category getters
+     * @since 2.0.0
      */
     <V>(self: Trie<V>, key: string): Option<[string, V]>;
 };
 /**
  * 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"
@@ -718,14 +749,15 @@ export declare const longestPrefixOf: {
  * assert.equal(Trie.size(trie), 2)
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const size: <V>(self: Trie<V>) => number;
 /**
  * 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"
@@ -748,14 +780,15 @@ export declare const size: <V>(self: Trie<V>) => number;
  * assert.deepStrictEqual(Trie.get(trie, "mea"), Option.none())
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare 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"
@@ -778,14 +811,15 @@ export declare 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"
@@ -808,15 +842,16 @@ export declare 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>;
 };
 /**
  * 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"
@@ -838,14 +873,15 @@ export declare const get: {
  * assert.equal(Trie.has(trie, "mea"), false)
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare 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"
@@ -867,14 +903,15 @@ export declare 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"
@@ -896,15 +933,16 @@ export declare 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;
 };
 /**
- * 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"
@@ -916,8 +954,8 @@ export declare const has: {
  * assert.equal(Trie.isEmpty(trie1), false)
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const isEmpty: <V>(self: Trie<V>) => boolean;
 /**
@@ -926,7 +964,8 @@ export declare const isEmpty: <V>(self: Trie<V>) => boolean;
  * `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"
@@ -939,8 +978,8 @@ export declare const isEmpty: <V>(self: Trie<V>) => boolean;
  * assert.throws(() => Trie.getUnsafe(trie, "mae"))
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export declare const getUnsafe: {
     /**
@@ -949,7 +988,8 @@ export declare 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"
@@ -962,8 +1002,8 @@ export declare 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;
     /**
@@ -972,7 +1012,8 @@ export declare 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,15 +1026,16 @@ export declare 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;
 };
 /**
  * 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"
@@ -1014,14 +1056,15 @@ export declare const getUnsafe: {
  * assert.deepStrictEqual(Trie.get(trie2, "call"), Option.none())
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export declare 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"
@@ -1042,14 +1085,15 @@ export declare 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"
@@ -1070,15 +1114,16 @@ export declare 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>;
 };
 /**
  * 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"
@@ -1109,14 +1154,15 @@ export declare const remove: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category folding
+ * @since 2.0.0
  */
 export declare 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"
@@ -1147,14 +1193,15 @@ export declare 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"
@@ -1185,15 +1232,16 @@ export declare 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;
 };
 /**
  * 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"
@@ -1221,14 +1269,15 @@ export declare 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 declare 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"
@@ -1256,14 +1305,15 @@ export declare 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"
@@ -1291,15 +1341,16 @@ export declare 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>;
 };
 /**
  * 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"
@@ -1327,14 +1378,15 @@ export declare const map: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export declare 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"
@@ -1362,14 +1414,15 @@ export declare 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"
@@ -1397,14 +1450,15 @@ export declare 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"
@@ -1432,14 +1486,15 @@ export declare 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"
@@ -1467,8 +1522,8 @@ export declare const filter: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category filtering
+     * @since 2.0.0
      */
     <A>(self: Trie<A>, f: (a: A, k: string) => boolean): Trie<A>;
 };
@@ -1476,7 +1531,8 @@ export declare 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"
@@ -1517,15 +1573,16 @@ export declare const filter: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export declare 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"
@@ -1566,15 +1623,16 @@ export declare 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"
@@ -1615,15 +1673,16 @@ export declare 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>;
 };
 /**
  * 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"
@@ -1644,14 +1703,15 @@ export declare const filterMap: {
  * assert.equal(Equal.equals(Trie.compact(trie), trieMapV), true)
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export declare const compact: <A>(self: Trie<Option<A>>) => Trie<A>;
 /**
  * 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"
@@ -1670,14 +1730,15 @@ export declare const compact: <A>(self: Trie<Option<A>>) => Trie<A>;
  * assert.equal(value, 17)
  * ```
  *
- * @since 2.0.0
  * @category traversing
+ * @since 2.0.0
  */
 export declare 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"
@@ -1696,14 +1757,15 @@ export declare 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"
@@ -1722,15 +1784,16 @@ export declare 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;
 };
 /**
  * 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"
@@ -1751,14 +1814,15 @@ export declare 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 declare 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"
@@ -1779,14 +1843,15 @@ export declare 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"
@@ -1807,15 +1872,16 @@ export declare 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>;
 };
 /**
  * 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"
@@ -1836,14 +1902,15 @@ export declare const modify: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export declare 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"
@@ -1864,14 +1931,15 @@ export declare 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"
@@ -1892,15 +1960,16 @@ export declare const removeMany: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category mutations
+     * @since 2.0.0
      */
     <V>(self: Trie<V>, keys: Iterable<string>): 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"
@@ -1925,14 +1994,15 @@ export declare const removeMany: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export declare 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"
@@ -1957,14 +2027,15 @@ export declare 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"
@@ -1989,8 +2060,8 @@ export declare const insertMany: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category mutations
+     * @since 2.0.0
      */
     <V>(self: Trie<V>, iter: Iterable<[string, V]>): Trie<V>;
 };