effect 3.8.4 → 3.9.0

package/src/Trie.ts

@@ -114,7 +114,49 @@ export const make: <Entries extends Array<readonly [string, any]>>(
  * @category mutations
  */
 export const insert: {
+  /**
+   * Insert a new entry in the `Trie`.
+   *
+   * @example
+   * import { Trie } from "effect"
+   *
+   * const trie1 = Trie.empty<number>().pipe(
+   *   Trie.insert("call", 0)
+   * )
+   * const trie2 = trie1.pipe(Trie.insert("me", 1))
+   * const trie3 = trie2.pipe(Trie.insert("mind", 2))
+   * const trie4 = trie3.pipe(Trie.insert("mid", 3))
+   *
+   * assert.deepStrictEqual(Array.from(trie1), [["call", 0]])
+   * assert.deepStrictEqual(Array.from(trie2), [["call", 0], ["me", 1]])
+   * assert.deepStrictEqual(Array.from(trie3), [["call", 0], ["me", 1], ["mind", 2]])
+   * assert.deepStrictEqual(Array.from(trie4), [["call", 0], ["me", 1], ["mid", 3], ["mind", 2]])
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <V>(key: string, value: V): (self: Trie<V>) => Trie<V>
+  /**
+   * Insert a new entry in the `Trie`.
+   *
+   * @example
+   * import { Trie } from "effect"
+   *
+   * const trie1 = Trie.empty<number>().pipe(
+   *   Trie.insert("call", 0)
+   * )
+   * const trie2 = trie1.pipe(Trie.insert("me", 1))
+   * const trie3 = trie2.pipe(Trie.insert("mind", 2))
+   * const trie4 = trie3.pipe(Trie.insert("mid", 3))
+   *
+   * assert.deepStrictEqual(Array.from(trie1), [["call", 0]])
+   * assert.deepStrictEqual(Array.from(trie2), [["call", 0], ["me", 1]])
+   * assert.deepStrictEqual(Array.from(trie3), [["call", 0], ["me", 1], ["mind", 2]])
+   * assert.deepStrictEqual(Array.from(trie4), [["call", 0], ["me", 1], ["mid", 3], ["mind", 2]])
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <V>(self: Trie<V>, key: string, value: V): Trie<V>
 } = TR.insert
 
@@ -225,7 +267,47 @@ export const toEntries = <V>(self: Trie<V>): Array<[string, V]> => Array.from(en
  * @category getters
  */
 export const keysWithPrefix: {
+  /**
+   * Returns an `IterableIterator` of the keys within the `Trie`
+   * that have `prefix` as prefix (`prefix` included if it exists).
+   *
+   * @example
+   * import { Trie } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("she", 0),
+   *   Trie.insert("shells", 1),
+   *   Trie.insert("sea", 2),
+   *   Trie.insert("shore", 3)
+   * )
+   *
+   * const result = Array.from(Trie.keysWithPrefix(trie, "she"))
+   * assert.deepStrictEqual(result, ["she", "shells"])
+   *
+   * @since 2.0.0
+   * @category getters
+   */
   (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
+   * import { Trie } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("she", 0),
+   *   Trie.insert("shells", 1),
+   *   Trie.insert("sea", 2),
+   *   Trie.insert("shore", 3)
+   * )
+   *
+   * const result = Array.from(Trie.keysWithPrefix(trie, "she"))
+   * assert.deepStrictEqual(result, ["she", "shells"])
+   *
+   * @since 2.0.0
+   * @category getters
+   */
   <V>(self: Trie<V>, prefix: string): IterableIterator<string>
 } = TR.keysWithPrefix
 
@@ -252,7 +334,51 @@ export const keysWithPrefix: {
  * @category getters
  */
 export const valuesWithPrefix: {
+  /**
+   * Returns an `IterableIterator` of the values within the `Trie`
+   * that have `prefix` as prefix (`prefix` included if it exists).
+   *
+   * @example
+   * import { Trie } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("she", 0),
+   *   Trie.insert("shells", 1),
+   *   Trie.insert("sea", 2),
+   *   Trie.insert("shore", 3)
+   * )
+   *
+   * const result = Array.from(Trie.valuesWithPrefix(trie, "she"))
+   *
+   * // 0: "she", 1: "shells"
+   * assert.deepStrictEqual(result, [0, 1])
+   *
+   * @since 2.0.0
+   * @category getters
+   */
   (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
+   * import { Trie } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("she", 0),
+   *   Trie.insert("shells", 1),
+   *   Trie.insert("sea", 2),
+   *   Trie.insert("shore", 3)
+   * )
+   *
+   * const result = Array.from(Trie.valuesWithPrefix(trie, "she"))
+   *
+   * // 0: "she", 1: "shells"
+   * assert.deepStrictEqual(result, [0, 1])
+   *
+   * @since 2.0.0
+   * @category getters
+   */
   <V>(self: Trie<V>, prefix: string): IterableIterator<V>
 } = TR.valuesWithPrefix
 
@@ -277,7 +403,47 @@ export const valuesWithPrefix: {
  * @category getters
  */
 export const entriesWithPrefix: {
+  /**
+   * Returns an `IterableIterator` of the entries within the `Trie`
+   * that have `prefix` as prefix (`prefix` included if it exists).
+   *
+   * @example
+   * import { Trie } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("she", 0),
+   *   Trie.insert("shells", 1),
+   *   Trie.insert("sea", 2),
+   *   Trie.insert("shore", 3)
+   * )
+   *
+   * const result = Array.from(Trie.entriesWithPrefix(trie, "she"))
+   * assert.deepStrictEqual(result, [["she", 0], ["shells", 1]])
+   *
+   * @since 2.0.0
+   * @category getters
+   */
   (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
+   * import { Trie } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("she", 0),
+   *   Trie.insert("shells", 1),
+   *   Trie.insert("sea", 2),
+   *   Trie.insert("shore", 3)
+   * )
+   *
+   * const result = Array.from(Trie.entriesWithPrefix(trie, "she"))
+   * assert.deepStrictEqual(result, [["she", 0], ["shells", 1]])
+   *
+   * @since 2.0.0
+   * @category getters
+   */
   <V>(self: Trie<V>, prefix: string): IterableIterator<[string, V]>
 } = TR.entriesWithPrefix
 
@@ -302,7 +468,47 @@ export const entriesWithPrefix: {
  * @category getters
  */
 export const toEntriesWithPrefix: {
+  /**
+   * Returns `Array<[K, V]>` of the entries within the `Trie`
+   * that have `prefix` as prefix (`prefix` included if it exists).
+   *
+   * @example
+   * import { Trie } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("sea", 2),
+   *   Trie.insert("she", 3)
+   * )
+   *
+   * const result = Trie.toEntriesWithPrefix(trie, "she")
+   * assert.deepStrictEqual(result, [["she", 3], ["shells", 0]])
+   *
+   * @since 2.0.0
+   * @category getters
+   */
   (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).
+   *
+   * @example
+   * import { Trie } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("sea", 2),
+   *   Trie.insert("she", 3)
+   * )
+   *
+   * const result = Trie.toEntriesWithPrefix(trie, "she")
+   * assert.deepStrictEqual(result, [["she", 3], ["shells", 0]])
+   *
+   * @since 2.0.0
+   * @category getters
+   */
   <V>(self: Trie<V>, prefix: string): Array<[string, V]>
 } = TR.toEntriesWithPrefix
 
@@ -328,7 +534,49 @@ export const toEntriesWithPrefix: {
  * @category getters
  */
 export const longestPrefixOf: {
+  /**
+   * Returns the longest key/value in the `Trie`
+   * that is a prefix of that `key` if it exists, `None` otherwise.
+   *
+   * @example
+   * import { Trie, Option } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * assert.deepStrictEqual(Trie.longestPrefixOf(trie, "sell"), Option.none())
+   * assert.deepStrictEqual(Trie.longestPrefixOf(trie, "sells"), Option.some(["sells", 1]))
+   * assert.deepStrictEqual(Trie.longestPrefixOf(trie, "shell"), Option.some(["she", 2]))
+   * assert.deepStrictEqual(Trie.longestPrefixOf(trie, "shellsort"), Option.some(["shells", 0]))
+   *
+   * @since 2.0.0
+   * @category getters
+   */
   (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
+   * import { Trie, Option } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * assert.deepStrictEqual(Trie.longestPrefixOf(trie, "sell"), Option.none())
+   * assert.deepStrictEqual(Trie.longestPrefixOf(trie, "sells"), Option.some(["sells", 1]))
+   * assert.deepStrictEqual(Trie.longestPrefixOf(trie, "shell"), Option.some(["she", 2]))
+   * assert.deepStrictEqual(Trie.longestPrefixOf(trie, "shellsort"), Option.some(["shells", 0]))
+   *
+   * @since 2.0.0
+   * @category getters
+   */
   <V>(self: Trie<V>, key: string): Option<[string, V]>
 } = TR.longestPrefixOf
 
@@ -376,7 +624,57 @@ export const size: <V>(self: Trie<V>) => number = TR.size
  * @category elements
  */
 export const get: {
+  /**
+   * Safely lookup the value for the specified key in the `Trie`.
+   *
+   * @example
+   * import { Trie, Option } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("call", 0),
+   *   Trie.insert("me", 1),
+   *   Trie.insert("mind", 2),
+   *   Trie.insert("mid", 3)
+   * )
+   *
+   * assert.deepStrictEqual(Trie.get(trie, "call"), Option.some(0))
+   * assert.deepStrictEqual(Trie.get(trie, "me"), Option.some(1))
+   * assert.deepStrictEqual(Trie.get(trie, "mind"), Option.some(2))
+   * assert.deepStrictEqual(Trie.get(trie, "mid"), Option.some(3))
+   * assert.deepStrictEqual(Trie.get(trie, "cale"), Option.none())
+   * assert.deepStrictEqual(Trie.get(trie, "ma"), Option.none())
+   * assert.deepStrictEqual(Trie.get(trie, "midn"), Option.none())
+   * assert.deepStrictEqual(Trie.get(trie, "mea"), Option.none())
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   (key: string): <V>(self: Trie<V>) => Option<V>
+  /**
+   * Safely lookup the value for the specified key in the `Trie`.
+   *
+   * @example
+   * import { Trie, Option } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("call", 0),
+   *   Trie.insert("me", 1),
+   *   Trie.insert("mind", 2),
+   *   Trie.insert("mid", 3)
+   * )
+   *
+   * assert.deepStrictEqual(Trie.get(trie, "call"), Option.some(0))
+   * assert.deepStrictEqual(Trie.get(trie, "me"), Option.some(1))
+   * assert.deepStrictEqual(Trie.get(trie, "mind"), Option.some(2))
+   * assert.deepStrictEqual(Trie.get(trie, "mid"), Option.some(3))
+   * assert.deepStrictEqual(Trie.get(trie, "cale"), Option.none())
+   * assert.deepStrictEqual(Trie.get(trie, "ma"), Option.none())
+   * assert.deepStrictEqual(Trie.get(trie, "midn"), Option.none())
+   * assert.deepStrictEqual(Trie.get(trie, "mea"), Option.none())
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <V>(self: Trie<V>, key: string): Option<V>
 } = TR.get
 
@@ -406,7 +704,57 @@ export const get: {
  * @category elements
  */
 export const has: {
+  /**
+   * Check if the given key exists in the `Trie`.
+   *
+   * @example
+   * import { Trie } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("call", 0),
+   *   Trie.insert("me", 1),
+   *   Trie.insert("mind", 2),
+   *   Trie.insert("mid", 3)
+   * )
+   *
+   * assert.equal(Trie.has(trie, "call"), true)
+   * assert.equal(Trie.has(trie, "me"), true)
+   * assert.equal(Trie.has(trie, "mind"), true)
+   * assert.equal(Trie.has(trie, "mid"), true)
+   * assert.equal(Trie.has(trie, "cale"), false)
+   * assert.equal(Trie.has(trie, "ma"), false)
+   * assert.equal(Trie.has(trie, "midn"), false)
+   * assert.equal(Trie.has(trie, "mea"), false)
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   (key: string): <V>(self: Trie<V>) => boolean
+  /**
+   * Check if the given key exists in the `Trie`.
+   *
+   * @example
+   * import { Trie } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("call", 0),
+   *   Trie.insert("me", 1),
+   *   Trie.insert("mind", 2),
+   *   Trie.insert("mid", 3)
+   * )
+   *
+   * assert.equal(Trie.has(trie, "call"), true)
+   * assert.equal(Trie.has(trie, "me"), true)
+   * assert.equal(Trie.has(trie, "mind"), true)
+   * assert.equal(Trie.has(trie, "mid"), true)
+   * assert.equal(Trie.has(trie, "cale"), false)
+   * assert.equal(Trie.has(trie, "ma"), false)
+   * assert.equal(Trie.has(trie, "midn"), false)
+   * assert.equal(Trie.has(trie, "mea"), false)
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <V>(self: Trie<V>, key: string): boolean
 } = TR.has
 
@@ -447,7 +795,45 @@ export const isEmpty: <V>(self: Trie<V>) => boolean = TR.isEmpty
  * @category unsafe
  */
 export const unsafeGet: {
+  /**
+   * Unsafely lookup the value for the specified key in the `Trie`.
+   *
+   * `unsafeGet` will throw if the key is not found. Use `get` instead to safely
+   * get a value from the `Trie`.
+   *
+   * @example
+   * import { Trie } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("call", 0),
+   *   Trie.insert("me", 1)
+   * )
+   *
+   * assert.throws(() => Trie.unsafeGet(trie, "mae"))
+   *
+   * @since 2.0.0
+   * @category unsafe
+   */
   (key: string): <V>(self: Trie<V>) => V
+  /**
+   * Unsafely lookup the value for the specified key in the `Trie`.
+   *
+   * `unsafeGet` will throw if the key is not found. Use `get` instead to safely
+   * get a value from the `Trie`.
+   *
+   * @example
+   * import { Trie } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("call", 0),
+   *   Trie.insert("me", 1)
+   * )
+   *
+   * assert.throws(() => Trie.unsafeGet(trie, "mae"))
+   *
+   * @since 2.0.0
+   * @category unsafe
+   */
   <V>(self: Trie<V>, key: string): V
 } = TR.unsafeGet
 
@@ -475,7 +861,53 @@ export const unsafeGet: {
  * @category mutations
  */
 export const remove: {
+  /**
+   * Remove the entry for the specified key in the `Trie`.
+   *
+   * @example
+   * import { Trie, Option } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("call", 0),
+   *   Trie.insert("me", 1),
+   *   Trie.insert("mind", 2),
+   *   Trie.insert("mid", 3)
+   * )
+   *
+   * const trie1 = trie.pipe(Trie.remove("call"))
+   * const trie2 = trie1.pipe(Trie.remove("mea"))
+   *
+   * assert.deepStrictEqual(Trie.get(trie, "call"), Option.some(0))
+   * assert.deepStrictEqual(Trie.get(trie1, "call"), Option.none())
+   * assert.deepStrictEqual(Trie.get(trie2, "call"), Option.none())
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   (key: string): <V>(self: Trie<V>) => Trie<V>
+  /**
+   * Remove the entry for the specified key in the `Trie`.
+   *
+   * @example
+   * import { Trie, Option } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("call", 0),
+   *   Trie.insert("me", 1),
+   *   Trie.insert("mind", 2),
+   *   Trie.insert("mid", 3)
+   * )
+   *
+   * const trie1 = trie.pipe(Trie.remove("call"))
+   * const trie2 = trie1.pipe(Trie.remove("mea"))
+   *
+   * assert.deepStrictEqual(Trie.get(trie, "call"), Option.some(0))
+   * assert.deepStrictEqual(Trie.get(trie1, "call"), Option.none())
+   * assert.deepStrictEqual(Trie.get(trie2, "call"), Option.none())
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <V>(self: Trie<V>, key: string): Trie<V>
 } = TR.remove
 
@@ -514,7 +946,75 @@ export const remove: {
  * @category folding
  */
 export const reduce: {
+  /**
+   * Reduce a state over the entries of the `Trie`.
+   *
+   * @example
+   * import { Trie } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * assert.equal(
+   *   trie.pipe(
+   *     Trie.reduce(0, (acc, n) => acc + n)
+   *   ),
+   *   3
+   * )
+   * assert.equal(
+   *   trie.pipe(
+   *     Trie.reduce(10, (acc, n) => acc + n)
+   *   ),
+   *   13
+   * )
+   * assert.equal(
+   *   trie.pipe(
+   *     Trie.reduce("", (acc, _, key) => acc + key)
+   *   ),
+   *   "sellssheshells"
+   * )
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   <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
+   * import { Trie } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * assert.equal(
+   *   trie.pipe(
+   *     Trie.reduce(0, (acc, n) => acc + n)
+   *   ),
+   *   3
+   * )
+   * assert.equal(
+   *   trie.pipe(
+   *     Trie.reduce(10, (acc, n) => acc + n)
+   *   ),
+   *   13
+   * )
+   * assert.equal(
+   *   trie.pipe(
+   *     Trie.reduce("", (acc, _, key) => acc + key)
+   *   ),
+   *   "sellssheshells"
+   * )
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   <Z, V>(self: Trie<V>, zero: Z, f: (accumulator: Z, value: V, key: string) => Z): Z
 } = TR.reduce
 
@@ -549,7 +1049,67 @@ export const reduce: {
  * @category folding
  */
 export const map: {
+  /**
+   * Maps over the entries of the `Trie` using the specified function.
+   *
+   * @example
+   * import { Trie, Equal } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieMapV = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 1),
+   *   Trie.insert("sells", 2),
+   *   Trie.insert("she", 3)
+   * )
+   *
+   * const trieMapK = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 6),
+   *   Trie.insert("sells", 5),
+   *   Trie.insert("she", 3)
+   * )
+   *
+   * assert.equal(Equal.equals(Trie.map(trie, (v) => v + 1), trieMapV), true)
+   * assert.equal(Equal.equals(Trie.map(trie, (_, k) => k.length), trieMapK), true)
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   <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
+   * import { Trie, Equal } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieMapV = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 1),
+   *   Trie.insert("sells", 2),
+   *   Trie.insert("she", 3)
+   * )
+   *
+   * const trieMapK = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 6),
+   *   Trie.insert("sells", 5),
+   *   Trie.insert("she", 3)
+   * )
+   *
+   * assert.equal(Equal.equals(Trie.map(trie, (v) => v + 1), trieMapV), true)
+   * assert.equal(Equal.equals(Trie.map(trie, (_, k) => k.length), trieMapK), true)
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   <V, A>(self: Trie<V>, f: (value: V, key: string) => A): Trie<A>
 } = TR.map
 
@@ -581,9 +1141,117 @@ export const map: {
  * @category filtering
  */
 export const filter: {
+  /**
+   * Filters entries out of a `Trie` using the specified predicate.
+   *
+   * @example
+   * import { Trie, Equal } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieMapV = Trie.empty<number>().pipe(
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieMapK = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1)
+   * )
+   *
+   * assert.equal(Equal.equals(Trie.filter(trie, (v) => v > 1), trieMapV), true)
+   * assert.equal(Equal.equals(Trie.filter(trie, (_, k) => k.length > 3), trieMapK), true)
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <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
+   * import { Trie, Equal } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieMapV = Trie.empty<number>().pipe(
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieMapK = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1)
+   * )
+   *
+   * assert.equal(Equal.equals(Trie.filter(trie, (v) => v > 1), trieMapV), true)
+   * assert.equal(Equal.equals(Trie.filter(trie, (_, k) => k.length > 3), trieMapK), true)
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <A>(f: (a: NoInfer<A>, k: string) => boolean): (self: Trie<A>) => Trie<A>
+  /**
+   * Filters entries out of a `Trie` using the specified predicate.
+   *
+   * @example
+   * import { Trie, Equal } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieMapV = Trie.empty<number>().pipe(
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieMapK = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1)
+   * )
+   *
+   * assert.equal(Equal.equals(Trie.filter(trie, (v) => v > 1), trieMapV), true)
+   * assert.equal(Equal.equals(Trie.filter(trie, (_, k) => k.length > 3), trieMapK), true)
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <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
+   * import { Trie, Equal } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieMapV = Trie.empty<number>().pipe(
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieMapK = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1)
+   * )
+   *
+   * assert.equal(Equal.equals(Trie.filter(trie, (v) => v > 1), trieMapV), true)
+   * assert.equal(Equal.equals(Trie.filter(trie, (_, k) => k.length > 3), trieMapK), true)
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <A>(self: Trie<A>, f: (a: A, k: string) => boolean): Trie<A>
 } = TR.filter
 
@@ -619,7 +1287,69 @@ export const filter: {
  * @category filtering
  */
 export const filterMap: {
+  /**
+   * Maps over the entries of the `Trie` using the specified partial function
+   * and filters out `None` values.
+   *
+   * @example
+   * import { Trie, Equal, Option } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieMapV = Trie.empty<number>().pipe(
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieMapK = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1)
+   * )
+   *
+   * assert.equal(Equal.equals(Trie.filterMap(trie, (v) => v > 1 ? Option.some(v) : Option.none()), trieMapV), true)
+   * assert.equal(
+   *   Equal.equals(Trie.filterMap(trie, (v, k) => k.length > 3 ? Option.some(v) : Option.none()), trieMapK),
+   *   true
+   * )
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <A, B>(f: (value: A, key: string) => Option<B>): (self: Trie<A>) => Trie<B>
+  /**
+   * Maps over the entries of the `Trie` using the specified partial function
+   * and filters out `None` values.
+   *
+   * @example
+   * import { Trie, Equal, Option } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieMapV = Trie.empty<number>().pipe(
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieMapK = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1)
+   * )
+   *
+   * assert.equal(Equal.equals(Trie.filterMap(trie, (v) => v > 1 ? Option.some(v) : Option.none()), trieMapV), true)
+   * assert.equal(
+   *   Equal.equals(Trie.filterMap(trie, (v, k) => k.length > 3 ? Option.some(v) : Option.none()), trieMapK),
+   *   true
+   * )
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <A, B>(self: Trie<A>, f: (value: A, key: string) => Option<B>): Trie<B>
 } = TR.filterMap
 
@@ -670,7 +1400,51 @@ export const compact: <A>(self: Trie<Option<A>>) => Trie<A> = TR.compact
  * @category traversing
  */
 export const forEach: {
+  /**
+   * Applies the specified function to the entries of the `Trie`.
+   *
+   * @example
+   * import { Trie } from "effect"
+   *
+   * let value = 0
+   *
+   * Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2),
+   *   Trie.forEach((n, key) => {
+   *     value += n + key.length
+   *   })
+   * )
+   *
+   * assert.equal(value, 17)
+   *
+   * @since 2.0.0
+   * @category traversing
+   */
   <V>(f: (value: V, key: string) => void): (self: Trie<V>) => void
+  /**
+   * Applies the specified function to the entries of the `Trie`.
+   *
+   * @example
+   * import { Trie } from "effect"
+   *
+   * let value = 0
+   *
+   * Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2),
+   *   Trie.forEach((n, key) => {
+   *     value += n + key.length
+   *   })
+   * )
+   *
+   * assert.equal(value, 17)
+   *
+   * @since 2.0.0
+   * @category traversing
+   */
   <V>(self: Trie<V>, f: (value: V, key: string) => void): void
 } = TR.forEach
 
@@ -694,7 +1468,45 @@ export const forEach: {
  * @category mutations
  */
 export const modify: {
+  /**
+   * Updates the value of the specified key within the `Trie` if it exists.
+   *
+   * @example
+   * import { Trie, Equal, Option } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * assert.deepStrictEqual(trie.pipe(Trie.modify("she", (v) => v + 10), Trie.get("she")), Option.some(12))
+   *
+   * assert.equal(Equal.equals(trie.pipe(Trie.modify("me", (v) => v)), trie), true)
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <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
+   * import { Trie, Equal, Option } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * assert.deepStrictEqual(trie.pipe(Trie.modify("she", (v) => v + 10), Trie.get("she")), Option.some(12))
+   *
+   * assert.equal(Equal.equals(trie.pipe(Trie.modify("me", (v) => v)), trie), true)
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <V>(self: Trie<V>, key: string, f: (v: V) => V): Trie<V>
 } = TR.modify
 
@@ -719,7 +1531,47 @@ export const modify: {
  * @category mutations
  */
 export const removeMany: {
+  /**
+   * Removes all entries in the `Trie` which have the specified keys.
+   *
+   * @example
+   * import { Trie, Equal } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * assert.equal(
+   *   Equal.equals(trie.pipe(Trie.removeMany(["she", "sells"])), Trie.empty<number>().pipe(Trie.insert("shells", 0))),
+   *   true
+   * )
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   (keys: Iterable<string>): <V>(self: Trie<V>) => Trie<V>
+  /**
+   * Removes all entries in the `Trie` which have the specified keys.
+   *
+   * @example
+   * import { Trie, Equal } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * assert.equal(
+   *   Equal.equals(trie.pipe(Trie.removeMany(["she", "sells"])), Trie.empty<number>().pipe(Trie.insert("shells", 0))),
+   *   true
+   * )
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <V>(self: Trie<V>, keys: Iterable<string>): Trie<V>
 } = TR.removeMany
 
@@ -751,6 +1603,60 @@ export const removeMany: {
  * @category mutations
  */
 export const insertMany: {
+  /**
+   * Insert multiple entries in the `Trie` at once.
+   *
+   * @example
+   * import { Trie, Equal } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieInsert = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insertMany(
+   *     [["sells", 1], ["she", 2]]
+   *   )
+   * )
+   *
+   * assert.equal(
+   *   Equal.equals(trie, trieInsert),
+   *   true
+   * )
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <V>(iter: Iterable<[string, V]>): (self: Trie<V>) => Trie<V>
+  /**
+   * Insert multiple entries in the `Trie` at once.
+   *
+   * @example
+   * import { Trie, Equal } from "effect"
+   *
+   * const trie = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insert("sells", 1),
+   *   Trie.insert("she", 2)
+   * )
+   *
+   * const trieInsert = Trie.empty<number>().pipe(
+   *   Trie.insert("shells", 0),
+   *   Trie.insertMany(
+   *     [["sells", 1], ["she", 2]]
+   *   )
+   * )
+   *
+   * assert.equal(
+   *   Equal.equals(trie, trieInsert),
+   *   true
+   * )
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <V>(self: Trie<V>, iter: Iterable<[string, V]>): Trie<V>
 } = TR.insertMany