effect 3.8.3 → 3.8.5

package/dist/dts/Trie.d.ts

@@ -104,7 +104,49 @@ export declare const make: <Entries extends Array<readonly [string, any]>>(...en
  * @category mutations
  */
 export declare 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>;
 };
 /**
@@ -210,7 +252,47 @@ export declare const toEntries: <V>(self: Trie<V>) => Array<[string, V]>;
  * @category getters
  */
 export declare 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>;
 };
 /**
@@ -236,7 +318,51 @@ export declare const keysWithPrefix: {
  * @category getters
  */
 export declare 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>;
 };
 /**
@@ -260,7 +386,47 @@ export declare const valuesWithPrefix: {
  * @category getters
  */
 export declare 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]>;
 };
 /**
@@ -284,7 +450,47 @@ export declare const entriesWithPrefix: {
  * @category getters
  */
 export declare 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]>;
 };
 /**
@@ -309,7 +515,49 @@ export declare const toEntriesWithPrefix: {
  * @category getters
  */
 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
+     * 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]>;
 };
 /**
@@ -355,7 +603,57 @@ export declare const size: <V>(self: Trie<V>) => number;
  * @category elements
  */
 export declare 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>;
 };
 /**
@@ -384,7 +682,57 @@ export declare const get: {
  * @category elements
  */
 export declare 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;
 };
 /**
@@ -423,7 +771,45 @@ export declare const isEmpty: <V>(self: Trie<V>) => boolean;
  * @category unsafe
  */
 export declare 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;
 };
 /**
@@ -450,7 +836,53 @@ export declare const unsafeGet: {
  * @category mutations
  */
 export declare 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>;
 };
 /**
@@ -488,7 +920,75 @@ export declare const remove: {
  * @category folding
  */
 export declare 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;
 };
 /**
@@ -522,7 +1022,67 @@ export declare const reduce: {
  * @category folding
  */
 export declare 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>;
 };
 /**
@@ -553,9 +1113,117 @@ export declare const map: {
  * @category filtering
  */
 export declare 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>;
 };
 /**
@@ -590,7 +1258,69 @@ export declare const filter: {
  * @category filtering
  */
 export declare 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>;
 };
 /**
@@ -639,7 +1369,51 @@ export declare const compact: <A>(self: Trie<Option<A>>) => Trie<A>;
  * @category traversing
  */
 export declare 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;
 };
 /**
@@ -662,7 +1436,45 @@ export declare const forEach: {
  * @category mutations
  */
 export declare 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>;
 };
 /**
@@ -686,7 +1498,47 @@ export declare const modify: {
  * @category mutations
  */
 export declare 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>;
 };
 /**
@@ -717,7 +1569,61 @@ export declare const removeMany: {
  * @category mutations
  */
 export declare 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>;
 };
 export {};