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

package/src/Trie.ts

@@ -26,9 +26,14 @@ 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"
+ * import { Trie } from "effect"
  *
  * // Create a trie with string-to-number mappings
  * const trie: Trie.Trie<number> = Trie.make(
@@ -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,9 +76,10 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<string>()
@@ -82,18 +88,18 @@ 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"
+ * import { Equal, Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const iterable: Array<readonly [string, number]> = [["call", 0], ["me", 1], [
@@ -116,18 +122,18 @@ 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"
+ * import { Equal, Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.make(["ca", 0], ["me", 1])
@@ -139,8 +145,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,9 +155,10 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie1 = Trie.empty<number>().pipe(
@@ -170,16 +177,17 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie1 = Trie.empty<number>().pipe(
@@ -198,16 +206,17 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie1 = Trie.empty<number>().pipe(
@@ -226,8 +235,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,9 +246,10 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -252,8 +262,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,9 +272,10 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -277,8 +288,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,9 +298,10 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -301,19 +313,20 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -325,8 +338,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,9 +347,10 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -350,17 +364,18 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -374,17 +389,18 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -398,8 +414,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,9 +424,10 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -426,17 +443,18 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -452,17 +470,18 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -478,8 +497,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,9 +507,10 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -504,17 +524,18 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -528,17 +549,18 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -552,19 +574,20 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -578,17 +601,18 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -602,17 +626,18 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -626,8 +651,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,9 +661,10 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -657,17 +683,18 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -686,17 +713,18 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -715,8 +743,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,9 +752,10 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -737,18 +766,18 @@ 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"
+ * import { Option, Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -768,17 +797,17 @@ 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"
+   * import { Option, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -798,17 +827,17 @@ 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"
+   * import { Option, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -828,8 +857,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,9 +866,10 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -859,16 +889,17 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -888,16 +919,17 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -917,18 +949,19 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>()
@@ -938,8 +971,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,9 +982,10 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -962,8 +996,8 @@ export const isEmpty: <V>(self: Trie<V>) => boolean = TR.isEmpty
  * assert.throws(() => Trie.getUnsafe(trie, "mae"))
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 4.0.0
  */
 export const getUnsafe: {
   /**
@@ -972,9 +1006,10 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -985,8 +1020,8 @@ export const getUnsafe: {
    * assert.throws(() => Trie.getUnsafe(trie, "mae"))
    * ```
    *
-   * @since 2.0.0
    * @category unsafe
+   * @since 4.0.0
    */
   (key: string): <V>(self: Trie<V>) => V
   /**
@@ -995,9 +1030,10 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1008,8 +1044,8 @@ export const getUnsafe: {
    * assert.throws(() => Trie.getUnsafe(trie, "mae"))
    * ```
    *
-   * @since 2.0.0
    * @category unsafe
+   * @since 4.0.0
    */
   <V>(self: Trie<V>, key: string): V
 } = TR.getUnsafe
@@ -1017,10 +1053,10 @@ 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"
+ * import { Option, Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -1038,17 +1074,17 @@ 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"
+   * import { Option, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1066,17 +1102,17 @@ 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"
+   * import { Option, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1094,8 +1130,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,9 +1139,10 @@ export const remove: {
 /**
  * Reduce a state over the entries of the `Trie`.
  *
- * @example
+ * **Example** (Reducing entries)
+ *
  * ```ts
- * import * as Trie from "effect/Trie"
+ * import { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -1134,16 +1171,17 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1172,16 +1210,17 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1210,8 +1249,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,10 +1258,10 @@ 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"
+ * import { Equal, Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -1247,17 +1286,17 @@ 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"
+   * import { Equal, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1282,17 +1321,17 @@ 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"
+   * import { Equal, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1317,8 +1356,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,10 +1365,10 @@ 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"
+ * import { Equal, Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -1354,17 +1393,17 @@ 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"
+   * import { Equal, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1389,17 +1428,17 @@ 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"
+   * import { Equal, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1424,17 +1463,17 @@ 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"
+   * import { Equal, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1459,17 +1498,17 @@ 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"
+   * import { Equal, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1494,8 +1533,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,11 +1543,10 @@ 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"
- * import * as Trie from "effect/Trie"
+ * import { Equal, Result, Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -1545,19 +1583,18 @@ 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"
-   * import * as Trie from "effect/Trie"
+   * import { Equal, Result, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1594,19 +1631,18 @@ 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"
-   * import * as Trie from "effect/Trie"
+   * import { Equal, Result, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1643,8 +1679,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,11 +1688,10 @@ 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"
- * import * as Trie from "effect/Trie"
+ * import { Equal, Option, Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<Option.Option<number>>().pipe(
@@ -1673,17 +1708,18 @@ 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 { Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * let value = 0
@@ -1700,16 +1736,17 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * let value = 0
@@ -1726,16 +1763,17 @@ 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 { Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * let value = 0
@@ -1752,8 +1790,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,11 +1799,10 @@ 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"
- * import * as Trie from "effect/Trie"
+ * import { Equal, Option, Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -1782,18 +1819,17 @@ 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"
-   * import * as Trie from "effect/Trie"
+   * import { Equal, Option, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1810,18 +1846,17 @@ 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"
-   * import * as Trie from "effect/Trie"
+   * import { Equal, Option, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1838,8 +1873,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,10 +1882,10 @@ 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"
+ * import { Equal, Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -1868,17 +1903,17 @@ 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"
+   * import { Equal, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1896,17 +1931,17 @@ 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"
+   * import { Equal, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1924,8 +1959,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,10 +1968,10 @@ 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"
+ * import { Equal, Trie } from "effect"
  * import * as assert from "node:assert"
  *
  * const trie = Trie.empty<number>().pipe(
@@ -1958,17 +1993,17 @@ 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"
+   * import { Equal, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -1990,17 +2025,17 @@ 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"
+   * import { Equal, Trie } from "effect"
    * import * as assert from "node:assert"
    *
    * const trie = Trie.empty<number>().pipe(
@@ -2022,8 +2057,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