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

package/dist/Chunk.d.ts

@@ -28,7 +28,8 @@
  * - **Iteration**: O(n)
  * - **Memory**: Structural sharing minimizes allocation
  *
- * @example
+ * **Example** (Creating and combining chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -42,7 +43,8 @@
  * console.log(Chunk.toReadonlyArray(combined)) // [1, 2, 3, 4, 5, 6]
  * ```
  *
- * @example
+ * **Example** (Transforming chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -53,17 +55,17 @@
  * const sum = Chunk.reduce(evens, 0, (acc, n) => acc + n) // 12
  * ```
  *
- * @example
+ * **Example** (Processing chunks with Effect)
+ *
  * ```ts
  * import { Chunk, Effect } from "effect"
  *
  * // Working with Effects
- * const processChunk = (chunk: Chunk.Chunk<number>) =>
- *   Effect.gen(function*() {
- *     const mapped = Chunk.map(chunk, (n) => n * 2)
- *     const filtered = Chunk.filter(mapped, (n) => n > 5)
- *     return Chunk.toReadonlyArray(filtered)
- *   })
+ * const processChunk = Effect.fnUntraced(function*(chunk: Chunk.Chunk<number>) {
+ *   const mapped = Chunk.map(chunk, (n) => n * 2)
+ *   const filtered = Chunk.filter(mapped, (n) => n > 5)
+ *   return Chunk.toReadonlyArray(filtered)
+ * })
  * ```
  *
  * @since 2.0.0
@@ -87,7 +89,8 @@ declare const TypeId = "~effect/collections/Chunk";
 /**
  * A Chunk is an immutable, ordered collection optimized for efficient concatenation and access patterns.
  *
- * @example
+ * **Example** (Inspecting chunk values)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -112,7 +115,8 @@ export interface Chunk<out A> extends Iterable<A>, Equal.Equal, Pipeable, Inspec
 /**
  * A non-empty Chunk guaranteed to contain at least one element.
  *
- * @example
+ * **Example** (Working with non-empty chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -129,7 +133,8 @@ export interface NonEmptyChunk<out A> extends Chunk<A>, NonEmptyIterable<A> {
 /**
  * Type lambda for Chunk, used for higher-kinded type operations.
  *
- * @example
+ * **Example** (Applying the Chunk type lambda)
+ *
  * ```ts
  * import type { ChunkTypeLambda } from "effect/Chunk"
  * import type { Kind } from "effect/HKT"
@@ -169,9 +174,11 @@ interface ISlice<A> {
     readonly length: number;
 }
 /**
- * Compares the two chunks of equal length using the specified function
+ * Creates an `Equivalence` for chunks that compares chunk lengths and then
+ * compares corresponding elements with the provided element equivalence.
+ *
+ * **Example** (Comparing chunks for equivalence)
  *
- * @example
  * ```ts
  * import { Chunk } from "effect"
  * import * as Equivalence from "effect/Equivalence"
@@ -192,7 +199,8 @@ export declare const makeEquivalence: <A>(isEquivalent: Equivalence.Equivalence<
 /**
  * Checks if `u` is a `Chunk<unknown>`
  *
- * @example
+ * **Example** (Checking for chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -211,7 +219,8 @@ export declare const isChunk: {
     /**
      * Checks if `u` is a `Chunk<unknown>`
      *
-     * @example
+     * **Example** (Checking for chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -230,7 +239,8 @@ export declare const isChunk: {
     /**
      * Checks if `u` is a `Chunk<unknown>`
      *
-     * @example
+     * **Example** (Checking for chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -250,7 +260,8 @@ export declare const isChunk: {
 /**
  * Creates an empty `Chunk`.
  *
- * @example
+ * **Example** (Creating an empty chunk)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -265,13 +276,13 @@ export declare const empty: <A = never>() => Chunk<A>;
 /**
  * Builds a `NonEmptyChunk` from an non-empty collection of elements.
  *
- * @example
+ * **Example** (Creating a non-empty chunk)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
  * const chunk = Chunk.make(1, 2, 3, 4)
- * console.log(chunk)
- * // { _id: 'Chunk', values: [ 1, 2, 3, 4 ] }
+ * console.log(Chunk.toArray(chunk)) // [1, 2, 3, 4]
  * ```
  *
  * @category constructors
@@ -281,13 +292,13 @@ export declare const make: <As extends readonly [any, ...Array<any>]>(...as: As)
 /**
  * Builds a `NonEmptyChunk` from a single element.
  *
- * @example
+ * **Example** (Creating a single-element chunk)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
  * const chunk = Chunk.of("hello")
- * console.log(chunk)
- * // { _id: 'Chunk', values: [ "hello" ] }
+ * console.log(Chunk.toArray(chunk)) // ["hello"]
  * ```
  *
  * @category constructors
@@ -297,13 +308,13 @@ export declare const of: <A>(a: A) => NonEmptyChunk<A>;
 /**
  * Creates a new `Chunk` from an iterable collection of values.
  *
- * @example
+ * **Example** (Creating chunks from iterables)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
  * const chunk = Chunk.fromIterable([1, 2, 3])
- * console.log(chunk)
- * // { _id: 'Chunk', values: [ 1, 2, 3 ] }
+ * console.log(Chunk.toArray(chunk)) // [1, 2, 3]
  * ```
  *
  * @category constructors
@@ -315,7 +326,8 @@ export declare const fromIterable: <A>(self: Iterable<A>) => Chunk<A>;
  * (`NonEmptyChunk`), the function will return a `NonEmptyArray`, ensuring the
  * non-empty property is preserved.
  *
- * @example
+ * **Example** (Converting chunks to mutable arrays)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -338,7 +350,8 @@ export declare const toArray: <S extends Chunk<any>>(self: S) => S extends NonEm
  * non-empty (`NonEmptyChunk`), the function will return a
  * `NonEmptyReadonlyArray`, ensuring the non-empty property is preserved.
  *
- * @example
+ * **Example** (Converting chunks to readonly arrays)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -362,7 +375,7 @@ export declare const toReadonlyArray: <S extends Chunk<any>>(self: S) => S exten
  * Reverses the order of elements in a `Chunk`.
  * Importantly, if the input chunk is a `NonEmptyChunk`, the reversed chunk will also be a `NonEmptyChunk`.
  *
- * @example
+ * **Example** (Reversing chunks)
  *
  * ```ts
  * import { Chunk } from "effect"
@@ -370,18 +383,18 @@ export declare const toReadonlyArray: <S extends Chunk<any>>(self: S) => S exten
  * const chunk = Chunk.make(1, 2, 3)
  * const result = Chunk.reverse(chunk)
  *
- * console.log(result)
- * // { _id: 'Chunk', values: [ 3, 2, 1 ] }
+ * console.log(Chunk.toArray(result)) // [3, 2, 1]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const reverse: <S extends Chunk<any>>(self: S) => Chunk.With<S, Chunk.Infer<S>>;
 /**
  * This function provides a safe way to read a value at a particular index from a `Chunk`.
  *
- * @example
+ * **Example** (Accessing elements safely)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -403,7 +416,8 @@ export declare const get: {
     /**
      * This function provides a safe way to read a value at a particular index from a `Chunk`.
      *
-     * @example
+     * **Example** (Accessing elements safely)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -425,7 +439,8 @@ export declare const get: {
     /**
      * This function provides a safe way to read a value at a particular index from a `Chunk`.
      *
-     * @example
+     * **Example** (Accessing elements safely)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -448,7 +463,8 @@ export declare const get: {
 /**
  * Wraps an array into a chunk without copying, unsafe on mutable arrays
  *
- * @example
+ * **Example** (Creating chunks without copying arrays)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -461,14 +477,15 @@ export declare const get: {
  * console.log(Chunk.toArray(chunk)) // [999, 2, 3, 4, 5]
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export declare const fromArrayUnsafe: <A>(self: ReadonlyArray<A>) => Chunk<A>;
 /**
  * Wraps an array into a chunk without copying, unsafe on mutable arrays
  *
- * @example
+ * **Example** (Creating non-empty chunks without copying arrays)
+ *
  * ```ts
  * import { Chunk } from "effect"
  * import * as Array from "effect/Array"
@@ -481,87 +498,79 @@ export declare const fromArrayUnsafe: <A>(self: ReadonlyArray<A>) => Chunk<A>;
  * console.log(Chunk.isNonEmpty(chunk)) // true
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export declare const fromNonEmptyArrayUnsafe: <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyChunk<A>;
 /**
  * Gets an element unsafely, will throw on out of bounds
  *
- * @example
+ * **Example** (Accessing elements unsafely)
+ *
  * ```ts
- * import { Chunk } from "effect"
+ * import { Chunk, Option } from "effect"
  *
  * const chunk = Chunk.make("a", "b", "c", "d")
  *
  * console.log(Chunk.getUnsafe(chunk, 1)) // "b"
  * console.log(Chunk.getUnsafe(chunk, 3)) // "d"
  *
- * // Warning: This will throw an error for invalid indices
- * try {
- *   Chunk.getUnsafe(chunk, 10) // throws "Index out of bounds"
- * } catch (error) {
- *   console.log((error as Error).message) // "Index out of bounds"
- * }
+ * // Use Chunk.get when the index may be out of bounds
+ * console.log(Option.isNone(Chunk.get(chunk, 10))) // true
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export declare const getUnsafe: {
     /**
      * Gets an element unsafely, will throw on out of bounds
      *
-     * @example
+     * **Example** (Accessing elements unsafely)
+     *
      * ```ts
-     * import { Chunk } from "effect"
+     * import { Chunk, Option } from "effect"
      *
      * const chunk = Chunk.make("a", "b", "c", "d")
      *
      * console.log(Chunk.getUnsafe(chunk, 1)) // "b"
      * console.log(Chunk.getUnsafe(chunk, 3)) // "d"
      *
-     * // Warning: This will throw an error for invalid indices
-     * try {
-     *   Chunk.getUnsafe(chunk, 10) // throws "Index out of bounds"
-     * } catch (error) {
-     *   console.log((error as Error).message) // "Index out of bounds"
-     * }
+     * // Use Chunk.get when the index may be out of bounds
+     * console.log(Option.isNone(Chunk.get(chunk, 10))) // true
      * ```
      *
-     * @since 2.0.0
      * @category unsafe
+     * @since 2.0.0
      */
     (index: number): <A>(self: Chunk<A>) => A;
     /**
      * Gets an element unsafely, will throw on out of bounds
      *
-     * @example
+     * **Example** (Accessing elements unsafely)
+     *
      * ```ts
-     * import { Chunk } from "effect"
+     * import { Chunk, Option } from "effect"
      *
      * const chunk = Chunk.make("a", "b", "c", "d")
      *
      * console.log(Chunk.getUnsafe(chunk, 1)) // "b"
      * console.log(Chunk.getUnsafe(chunk, 3)) // "d"
      *
-     * // Warning: This will throw an error for invalid indices
-     * try {
-     *   Chunk.getUnsafe(chunk, 10) // throws "Index out of bounds"
-     * } catch (error) {
-     *   console.log((error as Error).message) // "Index out of bounds"
-     * }
+     * // Use Chunk.get when the index may be out of bounds
+     * console.log(Option.isNone(Chunk.get(chunk, 10))) // true
      * ```
      *
-     * @since 2.0.0
      * @category unsafe
+     * @since 2.0.0
      */
     <A>(self: Chunk<A>, index: number): A;
 };
 /**
  * Appends the specified element to the end of the `Chunk`.
  *
- * @example
+ * **Example** (Appending an element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -582,7 +591,8 @@ export declare const append: {
     /**
      * Appends the specified element to the end of the `Chunk`.
      *
-     * @example
+     * **Example** (Appending an element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -603,7 +613,8 @@ export declare const append: {
     /**
      * Appends the specified element to the end of the `Chunk`.
      *
-     * @example
+     * **Example** (Appending an element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -625,7 +636,8 @@ export declare const append: {
 /**
  * Prepend an element to the front of a `Chunk`, creating a new `NonEmptyChunk`.
  *
- * @example
+ * **Example** (Prepending an element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -646,7 +658,8 @@ export declare const prepend: {
     /**
      * Prepend an element to the front of a `Chunk`, creating a new `NonEmptyChunk`.
      *
-     * @example
+     * **Example** (Prepending an element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -667,7 +680,8 @@ export declare const prepend: {
     /**
      * Prepend an element to the front of a `Chunk`, creating a new `NonEmptyChunk`.
      *
-     * @example
+     * **Example** (Prepending an element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -689,14 +703,14 @@ export declare const prepend: {
 /**
  * Takes the first up to `n` elements from the chunk.
  *
- * @example
+ * **Example** (Taking elements from the start)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
  * const chunk = Chunk.make(1, 2, 3, 4, 5)
  * const result = Chunk.take(chunk, 3)
- * console.log(result)
- * // { _id: 'Chunk', values: [ 1, 2, 3 ] }
+ * console.log(Chunk.toArray(result)) // [1, 2, 3]
  * ```
  *
  * @category elements
@@ -706,14 +720,14 @@ export declare const take: {
     /**
      * Takes the first up to `n` elements from the chunk.
      *
-     * @example
+     * **Example** (Taking elements from the start)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
      * const chunk = Chunk.make(1, 2, 3, 4, 5)
      * const result = Chunk.take(chunk, 3)
-     * console.log(result)
-     * // { _id: 'Chunk', values: [ 1, 2, 3 ] }
+     * console.log(Chunk.toArray(result)) // [1, 2, 3]
      * ```
      *
      * @category elements
@@ -723,14 +737,14 @@ export declare const take: {
     /**
      * Takes the first up to `n` elements from the chunk.
      *
-     * @example
+     * **Example** (Taking elements from the start)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
      * const chunk = Chunk.make(1, 2, 3, 4, 5)
      * const result = Chunk.take(chunk, 3)
-     * console.log(result)
-     * // { _id: 'Chunk', values: [ 1, 2, 3 ] }
+     * console.log(Chunk.toArray(result)) // [1, 2, 3]
      * ```
      *
      * @category elements
@@ -741,14 +755,14 @@ export declare const take: {
 /**
  * Drops the first up to `n` elements from the chunk.
  *
- * @example
+ * **Example** (Dropping elements from the start)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
  * const chunk = Chunk.make(1, 2, 3, 4, 5)
  * const result = Chunk.drop(chunk, 2)
- * console.log(result)
- * // { _id: 'Chunk', values: [ 3, 4, 5 ] }
+ * console.log(Chunk.toArray(result)) // [3, 4, 5]
  * ```
  *
  * @category elements
@@ -758,14 +772,14 @@ export declare const drop: {
     /**
      * Drops the first up to `n` elements from the chunk.
      *
-     * @example
+     * **Example** (Dropping elements from the start)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
      * const chunk = Chunk.make(1, 2, 3, 4, 5)
      * const result = Chunk.drop(chunk, 2)
-     * console.log(result)
-     * // { _id: 'Chunk', values: [ 3, 4, 5 ] }
+     * console.log(Chunk.toArray(result)) // [3, 4, 5]
      * ```
      *
      * @category elements
@@ -775,14 +789,14 @@ export declare const drop: {
     /**
      * Drops the first up to `n` elements from the chunk.
      *
-     * @example
+     * **Example** (Dropping elements from the start)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
      * const chunk = Chunk.make(1, 2, 3, 4, 5)
      * const result = Chunk.drop(chunk, 2)
-     * console.log(result)
-     * // { _id: 'Chunk', values: [ 3, 4, 5 ] }
+     * console.log(Chunk.toArray(result)) // [3, 4, 5]
      * ```
      *
      * @category elements
@@ -793,14 +807,14 @@ export declare const drop: {
 /**
  * Drops the last `n` elements.
  *
- * @example
+ * **Example** (Dropping elements from the end)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
  * const chunk = Chunk.make(1, 2, 3, 4, 5)
  * const result = Chunk.dropRight(chunk, 2)
- * console.log(result)
- * // { _id: 'Chunk', values: [ 1, 2, 3 ] }
+ * console.log(Chunk.toArray(result)) // [1, 2, 3]
  * ```
  *
  * @category elements
@@ -810,14 +824,14 @@ export declare const dropRight: {
     /**
      * Drops the last `n` elements.
      *
-     * @example
+     * **Example** (Dropping elements from the end)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
      * const chunk = Chunk.make(1, 2, 3, 4, 5)
      * const result = Chunk.dropRight(chunk, 2)
-     * console.log(result)
-     * // { _id: 'Chunk', values: [ 1, 2, 3 ] }
+     * console.log(Chunk.toArray(result)) // [1, 2, 3]
      * ```
      *
      * @category elements
@@ -827,14 +841,14 @@ export declare const dropRight: {
     /**
      * Drops the last `n` elements.
      *
-     * @example
+     * **Example** (Dropping elements from the end)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
      * const chunk = Chunk.make(1, 2, 3, 4, 5)
      * const result = Chunk.dropRight(chunk, 2)
-     * console.log(result)
-     * // { _id: 'Chunk', values: [ 1, 2, 3 ] }
+     * console.log(Chunk.toArray(result)) // [1, 2, 3]
      * ```
      *
      * @category elements
@@ -845,14 +859,14 @@ export declare const dropRight: {
 /**
  * Drops all elements so long as the predicate returns true.
  *
- * @example
+ * **Example** (Dropping elements while a predicate matches)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
  * const chunk = Chunk.make(1, 2, 3, 4, 5)
  * const result = Chunk.dropWhile(chunk, (n) => n < 3)
- * console.log(result)
- * // { _id: 'Chunk', values: [ 3, 4, 5 ] }
+ * console.log(Chunk.toArray(result)) // [3, 4, 5]
  * ```
  *
  * @category elements
@@ -862,14 +876,14 @@ export declare const dropWhile: {
     /**
      * Drops all elements so long as the predicate returns true.
      *
-     * @example
+     * **Example** (Dropping elements while a predicate matches)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
      * const chunk = Chunk.make(1, 2, 3, 4, 5)
      * const result = Chunk.dropWhile(chunk, (n) => n < 3)
-     * console.log(result)
-     * // { _id: 'Chunk', values: [ 3, 4, 5 ] }
+     * console.log(Chunk.toArray(result)) // [3, 4, 5]
      * ```
      *
      * @category elements
@@ -879,14 +893,14 @@ export declare const dropWhile: {
     /**
      * Drops all elements so long as the predicate returns true.
      *
-     * @example
+     * **Example** (Dropping elements while a predicate matches)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
      * const chunk = Chunk.make(1, 2, 3, 4, 5)
      * const result = Chunk.dropWhile(chunk, (n) => n < 3)
-     * console.log(result)
-     * // { _id: 'Chunk', values: [ 3, 4, 5 ] }
+     * console.log(Chunk.toArray(result)) // [3, 4, 5]
      * ```
      *
      * @category elements
@@ -898,7 +912,7 @@ export declare const dropWhile: {
  * Prepends the specified prefix chunk to the beginning of the specified chunk.
  * If either chunk is non-empty, the result is also a non-empty chunk.
  *
- * @example
+ * **Example** (Prepending all elements)
  *
  * ```ts
  * import { Chunk } from "effect"
@@ -920,7 +934,7 @@ export declare const prependAll: {
      * Prepends the specified prefix chunk to the beginning of the specified chunk.
      * If either chunk is non-empty, the result is also a non-empty chunk.
      *
-     * @example
+     * **Example** (Prepending all elements)
      *
      * ```ts
      * import { Chunk } from "effect"
@@ -942,7 +956,7 @@ export declare const prependAll: {
      * Prepends the specified prefix chunk to the beginning of the specified chunk.
      * If either chunk is non-empty, the result is also a non-empty chunk.
      *
-     * @example
+     * **Example** (Prepending all elements)
      *
      * ```ts
      * import { Chunk } from "effect"
@@ -964,7 +978,7 @@ export declare const prependAll: {
      * Prepends the specified prefix chunk to the beginning of the specified chunk.
      * If either chunk is non-empty, the result is also a non-empty chunk.
      *
-     * @example
+     * **Example** (Prepending all elements)
      *
      * ```ts
      * import { Chunk } from "effect"
@@ -986,7 +1000,7 @@ export declare const prependAll: {
      * Prepends the specified prefix chunk to the beginning of the specified chunk.
      * If either chunk is non-empty, the result is also a non-empty chunk.
      *
-     * @example
+     * **Example** (Prepending all elements)
      *
      * ```ts
      * import { Chunk } from "effect"
@@ -1009,7 +1023,7 @@ export declare const prependAll: {
  * Concatenates two chunks, combining their elements.
  * If either chunk is non-empty, the result is also a non-empty chunk.
  *
- * @example
+ * **Example** (Appending all elements)
  *
  * ```ts
  * import { Chunk } from "effect"
@@ -1031,7 +1045,7 @@ export declare const appendAll: {
      * Concatenates two chunks, combining their elements.
      * If either chunk is non-empty, the result is also a non-empty chunk.
      *
-     * @example
+     * **Example** (Appending all elements)
      *
      * ```ts
      * import { Chunk } from "effect"
@@ -1053,7 +1067,7 @@ export declare const appendAll: {
      * Concatenates two chunks, combining their elements.
      * If either chunk is non-empty, the result is also a non-empty chunk.
      *
-     * @example
+     * **Example** (Appending all elements)
      *
      * ```ts
      * import { Chunk } from "effect"
@@ -1075,7 +1089,7 @@ export declare const appendAll: {
      * Concatenates two chunks, combining their elements.
      * If either chunk is non-empty, the result is also a non-empty chunk.
      *
-     * @example
+     * **Example** (Appending all elements)
      *
      * ```ts
      * import { Chunk } from "effect"
@@ -1097,7 +1111,7 @@ export declare const appendAll: {
      * Concatenates two chunks, combining their elements.
      * If either chunk is non-empty, the result is also a non-empty chunk.
      *
-     * @example
+     * **Example** (Appending all elements)
      *
      * ```ts
      * import { Chunk } from "effect"
@@ -1119,7 +1133,8 @@ export declare const appendAll: {
 /**
  * Returns a filtered and mapped subset of the elements.
  *
- * @example
+ * **Example** (Filtering and mapping values)
+ *
  * ```ts
  * import { Chunk } from "effect"
  * import * as Result from "effect/Result"
@@ -1139,14 +1154,15 @@ export declare const appendAll: {
  * console.log(Chunk.toArray(evenIndexNumbers)) // [1]
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export declare const filterMap: {
     /**
      * Returns a filtered and mapped subset of the elements.
      *
-     * @example
+     * **Example** (Filtering and mapping values)
+     *
      * ```ts
      * import { Chunk } from "effect"
      * import * as Result from "effect/Result"
@@ -1166,14 +1182,15 @@ export declare const filterMap: {
      * console.log(Chunk.toArray(evenIndexNumbers)) // [1]
      * ```
      *
-     * @since 2.0.0
      * @category filtering
+     * @since 2.0.0
      */
     <A, B, X>(f: (input: A, i: number) => Result<B, X>): (self: Chunk<A>) => Chunk<B>;
     /**
      * Returns a filtered and mapped subset of the elements.
      *
-     * @example
+     * **Example** (Filtering and mapping values)
+     *
      * ```ts
      * import { Chunk } from "effect"
      * import * as Result from "effect/Result"
@@ -1193,15 +1210,16 @@ export declare const filterMap: {
      * console.log(Chunk.toArray(evenIndexNumbers)) // [1]
      * ```
      *
-     * @since 2.0.0
      * @category filtering
+     * @since 2.0.0
      */
     <A, B, X>(self: Chunk<A>, f: (input: A, i: number) => Result<B, X>): Chunk<B>;
 };
 /**
  * Returns a filtered subset of the elements.
  *
- * @example
+ * **Example** (Filtering values)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1215,14 +1233,15 @@ export declare const filterMap: {
  * console.log(Chunk.toArray(numbers)) // [42, 100]
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export declare const filter: {
     /**
      * Returns a filtered subset of the elements.
      *
-     * @example
+     * **Example** (Filtering values)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -1236,14 +1255,15 @@ export declare const filter: {
      * console.log(Chunk.toArray(numbers)) // [42, 100]
      * ```
      *
-     * @since 2.0.0
      * @category filtering
+     * @since 2.0.0
      */
     <A, B extends A>(refinement: Refinement<NoInfer<A>, B>): (self: Chunk<A>) => Chunk<B>;
     /**
      * Returns a filtered subset of the elements.
      *
-     * @example
+     * **Example** (Filtering values)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -1257,14 +1277,15 @@ export declare const filter: {
      * console.log(Chunk.toArray(numbers)) // [42, 100]
      * ```
      *
-     * @since 2.0.0
      * @category filtering
+     * @since 2.0.0
      */
     <A>(predicate: Predicate<NoInfer<A>>): (self: Chunk<A>) => Chunk<A>;
     /**
      * Returns a filtered subset of the elements.
      *
-     * @example
+     * **Example** (Filtering values)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -1278,14 +1299,15 @@ export declare const filter: {
      * console.log(Chunk.toArray(numbers)) // [42, 100]
      * ```
      *
-     * @since 2.0.0
      * @category filtering
+     * @since 2.0.0
      */
     <A, B extends A>(self: Chunk<A>, refinement: Refinement<A, B>): Chunk<B>;
     /**
      * Returns a filtered subset of the elements.
      *
-     * @example
+     * **Example** (Filtering values)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -1299,15 +1321,16 @@ export declare const filter: {
      * console.log(Chunk.toArray(numbers)) // [42, 100]
      * ```
      *
-     * @since 2.0.0
      * @category filtering
+     * @since 2.0.0
      */
     <A>(self: Chunk<A>, predicate: Predicate<A>): Chunk<A>;
 };
 /**
  * Transforms all elements of the chunk for as long as the specified function succeeds.
  *
- * @example
+ * **Example** (Filtering and mapping while values match)
+ *
  * ```ts
  * import { Chunk } from "effect"
  * import * as Result from "effect/Result"
@@ -1328,14 +1351,15 @@ export declare const filter: {
  * console.log(Chunk.toArray(allNumbers)) // [1, 2, 3, 4]
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export declare const filterMapWhile: {
     /**
      * Transforms all elements of the chunk for as long as the specified function succeeds.
      *
-     * @example
+     * **Example** (Filtering and mapping while values match)
+     *
      * ```ts
      * import { Chunk } from "effect"
      * import * as Result from "effect/Result"
@@ -1356,14 +1380,15 @@ export declare const filterMapWhile: {
      * console.log(Chunk.toArray(allNumbers)) // [1, 2, 3, 4]
      * ```
      *
-     * @since 2.0.0
      * @category filtering
+     * @since 2.0.0
      */
     <A, B, X>(f: Filter.Filter<A, B, X>): (self: Chunk<A>) => Chunk<B>;
     /**
      * Transforms all elements of the chunk for as long as the specified function succeeds.
      *
-     * @example
+     * **Example** (Filtering and mapping while values match)
+     *
      * ```ts
      * import { Chunk } from "effect"
      * import * as Result from "effect/Result"
@@ -1384,23 +1409,23 @@ export declare const filterMapWhile: {
      * console.log(Chunk.toArray(allNumbers)) // [1, 2, 3, 4]
      * ```
      *
-     * @since 2.0.0
      * @category filtering
+     * @since 2.0.0
      */
     <A, B, X>(self: Chunk<A>, f: Filter.Filter<A, B, X>): Chunk<B>;
 };
 /**
  * Filter out optional values
  *
- * @example
+ * **Example** (Compacting optional values)
+ *
  * ```ts
  * import { Chunk } from "effect"
  * import * as Option from "effect/Option"
  *
  * const chunk = Chunk.make(Option.some(1), Option.none(), Option.some(3))
  * const result = Chunk.compact(chunk)
- * console.log(result)
- * // { _id: 'Chunk', values: [ 1, 3 ] }
+ * console.log(Chunk.toArray(result)) // [1, 3]
  * ```
  *
  * @category filtering
@@ -1410,7 +1435,8 @@ export declare const compact: <A>(self: Chunk<Option<A>>) => Chunk<A>;
 /**
  * Applies a function to each element in a chunk and returns a new chunk containing the concatenated mapped elements.
  *
- * @example
+ * **Example** (Flat mapping chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1431,14 +1457,15 @@ export declare const compact: <A>(self: Chunk<Option<A>>) => Chunk<A>;
  * console.log(Chunk.toArray(indexed)) // [1, 3, 5]
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const flatMap: {
     /**
      * Applies a function to each element in a chunk and returns a new chunk containing the concatenated mapped elements.
      *
-     * @example
+     * **Example** (Flat mapping chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -1459,14 +1486,15 @@ export declare const flatMap: {
      * console.log(Chunk.toArray(indexed)) // [1, 3, 5]
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <S extends Chunk<any>, T extends Chunk<any>>(f: (a: Chunk.Infer<S>, i: number) => T): (self: S) => Chunk.AndNonEmpty<S, T, Chunk.Infer<T>>;
     /**
      * Applies a function to each element in a chunk and returns a new chunk containing the concatenated mapped elements.
      *
-     * @example
+     * **Example** (Flat mapping chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -1487,14 +1515,15 @@ export declare const flatMap: {
      * console.log(Chunk.toArray(indexed)) // [1, 3, 5]
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <A, B>(self: NonEmptyChunk<A>, f: (a: A, i: number) => NonEmptyChunk<B>): NonEmptyChunk<B>;
     /**
      * Applies a function to each element in a chunk and returns a new chunk containing the concatenated mapped elements.
      *
-     * @example
+     * **Example** (Flat mapping chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -1515,8 +1544,8 @@ export declare const flatMap: {
      * console.log(Chunk.toArray(indexed)) // [1, 3, 5]
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <A, B>(self: Chunk<A>, f: (a: A, i: number) => Chunk<B>): Chunk<B>;
 };
@@ -1530,7 +1559,8 @@ export declare const flatMap: {
  * instead, it is primarily used for side effects, such as logging or
  * accumulating data in an external variable.
  *
- * @example
+ * **Example** (Iterating over chunk values)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1553,8 +1583,8 @@ export declare const flatMap: {
  * // Index 3: 4
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const forEach: {
     /**
@@ -1567,7 +1597,8 @@ export declare const forEach: {
      * instead, it is primarily used for side effects, such as logging or
      * accumulating data in an external variable.
      *
-     * @example
+     * **Example** (Iterating over chunk values)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -1590,8 +1621,8 @@ export declare const forEach: {
      * // Index 3: 4
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <A, B>(f: (a: A, index: number) => B): (self: Chunk<A>) => void;
     /**
@@ -1604,7 +1635,8 @@ export declare const forEach: {
      * instead, it is primarily used for side effects, such as logging or
      * accumulating data in an external variable.
      *
-     * @example
+     * **Example** (Iterating over chunk values)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -1627,15 +1659,16 @@ export declare const forEach: {
      * // Index 3: 4
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <A, B>(self: Chunk<A>, f: (a: A, index: number) => B): void;
 };
 /**
  * Flattens a chunk of chunks into a single chunk by concatenating all chunks.
  *
- * @example
+ * **Example** (Flattening nested chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1656,14 +1689,15 @@ export declare const forEach: {
  * console.log(Chunk.toArray(Chunk.flatten(withEmpty))) // [1, 2, 3, 4]
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const flatten: <S extends Chunk<Chunk<any>>>(self: S) => Chunk.Flatten<S>;
 /**
  * Groups elements in chunks of up to `n` elements.
  *
- * @example
+ * **Example** (Splitting into fixed-size chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1680,14 +1714,15 @@ export declare const flatten: <S extends Chunk<Chunk<any>>>(self: S) => Chunk.Fl
  * // [[1, 2], [3, 4], [5]]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const chunksOf: {
     /**
      * Groups elements in chunks of up to `n` elements.
      *
-     * @example
+     * **Example** (Splitting into fixed-size chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -1704,14 +1739,15 @@ export declare const chunksOf: {
      * // [[1, 2], [3, 4], [5]]
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     (n: number): <A>(self: Chunk<A>) => Chunk<Chunk<A>>;
     /**
      * Groups elements in chunks of up to `n` elements.
      *
-     * @example
+     * **Example** (Splitting into fixed-size chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -1728,8 +1764,8 @@ export declare const chunksOf: {
      * // [[1, 2], [3, 4], [5]]
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A>(self: Chunk<A>, n: number): Chunk<Chunk<A>>;
 };
@@ -1738,7 +1774,8 @@ export declare const chunksOf: {
  *
  * The order and references of result values are determined by the Chunk.
  *
- * @example
+ * **Example** (Intersecting chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1758,8 +1795,8 @@ export declare const chunksOf: {
  * console.log(Chunk.toArray(Chunk.intersection(chunk3, chunk4))) // []
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const intersection: {
     /**
@@ -1767,7 +1804,8 @@ export declare const intersection: {
      *
      * The order and references of result values are determined by the Chunk.
      *
-     * @example
+     * **Example** (Intersecting chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -1787,8 +1825,8 @@ export declare const intersection: {
      * console.log(Chunk.toArray(Chunk.intersection(chunk3, chunk4))) // []
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A>(that: Chunk<A>): <B>(self: Chunk<B>) => Chunk<A & B>;
     /**
@@ -1796,7 +1834,8 @@ export declare const intersection: {
      *
      * The order and references of result values are determined by the Chunk.
      *
-     * @example
+     * **Example** (Intersecting chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -1816,15 +1855,16 @@ export declare const intersection: {
      * console.log(Chunk.toArray(Chunk.intersection(chunk3, chunk4))) // []
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A, B>(self: Chunk<A>, that: Chunk<B>): Chunk<A & B>;
 };
 /**
  * Determines if the chunk is empty.
  *
- * @example
+ * **Example** (Checking for empty chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1839,7 +1879,8 @@ export declare const isEmpty: <A>(self: Chunk<A>) => boolean;
 /**
  * Determines if the chunk is not empty.
  *
- * @example
+ * **Example** (Checking for non-empty chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1854,7 +1895,8 @@ export declare const isNonEmpty: <A>(self: Chunk<A>) => self is NonEmptyChunk<A>
 /**
  * Returns the first element of this chunk if it exists.
  *
- * @example
+ * **Example** (Getting the first element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1871,9 +1913,10 @@ export declare const head: <A>(self: Chunk<A>) => Option<A>;
  *
  * It will throw an error if the chunk is empty.
  *
- * @example
+ * **Example** (Getting the first element unsafely)
+ *
  * ```ts
- * import { Chunk } from "effect"
+ * import { Chunk, Option } from "effect"
  *
  * const chunk = Chunk.make(1, 2, 3, 4)
  * console.log(Chunk.headUnsafe(chunk)) // 1
@@ -1881,22 +1924,19 @@ export declare const head: <A>(self: Chunk<A>) => Option<A>;
  * const singleElement = Chunk.make("hello")
  * console.log(Chunk.headUnsafe(singleElement)) // "hello"
  *
- * // Warning: This will throw for empty chunks
- * try {
- *   Chunk.headUnsafe(Chunk.empty())
- * } catch (error) {
- *   console.log((error as Error).message) // "Index out of bounds"
- * }
+ * // Use Chunk.head when the chunk may be empty
+ * console.log(Option.isNone(Chunk.head(Chunk.empty()))) // true
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export declare const headUnsafe: <A>(self: Chunk<A>) => A;
 /**
  * Returns the first element of this non empty chunk.
  *
- * @example
+ * **Example** (Getting the first element of a non-empty chunk)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1910,14 +1950,15 @@ export declare const headUnsafe: <A>(self: Chunk<A>) => A;
  * // Chunk.headNonEmpty(Chunk.empty()) // TypeScript error
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const headNonEmpty: <A>(self: NonEmptyChunk<A>) => A;
 /**
  * Returns the last element of this chunk if it exists.
  *
- * @example
+ * **Example** (Getting the last element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1934,9 +1975,10 @@ export declare const last: <A>(self: Chunk<A>) => Option<A>;
  *
  * It will throw an error if the chunk is empty.
  *
- * @example
+ * **Example** (Getting the last element unsafely)
+ *
  * ```ts
- * import { Chunk } from "effect"
+ * import { Chunk, Option } from "effect"
  *
  * const chunk = Chunk.make(1, 2, 3, 4)
  * console.log(Chunk.lastUnsafe(chunk)) // 4
@@ -1944,22 +1986,19 @@ export declare const last: <A>(self: Chunk<A>) => Option<A>;
  * const singleElement = Chunk.make("hello")
  * console.log(Chunk.lastUnsafe(singleElement)) // "hello"
  *
- * // Warning: This will throw for empty chunks
- * try {
- *   Chunk.lastUnsafe(Chunk.empty())
- * } catch (error) {
- *   console.log((error as Error).message) // "Index out of bounds"
- * }
+ * // Use Chunk.last when the chunk may be empty
+ * console.log(Option.isNone(Chunk.last(Chunk.empty()))) // true
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export declare const lastUnsafe: <A>(self: Chunk<A>) => A;
 /**
  * Returns the last element of this non empty chunk.
  *
- * @example
+ * **Example** (Getting the last element of a non-empty chunk)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1973,14 +2012,15 @@ export declare const lastUnsafe: <A>(self: Chunk<A>) => A;
  * // Chunk.lastNonEmpty(Chunk.empty()) // TypeScript error
  * ```
  *
- * @since 3.4.0
  * @category elements
+ * @since 3.4.0
  */
 export declare const lastNonEmpty: <A>(self: NonEmptyChunk<A>) => A;
 /**
  * A namespace containing utility types for Chunk operations.
  *
- * @example
+ * **Example** (Working with Chunk utility types)
+ *
  * ```ts
  * import type { Chunk } from "effect"
  *
@@ -2000,7 +2040,8 @@ export declare namespace Chunk {
     /**
      * Infers the element type of a Chunk.
      *
-     * @example
+     * **Example** (Inferring element types)
+     *
      * ```ts
      * import type { Chunk } from "effect"
      *
@@ -2018,7 +2059,8 @@ export declare namespace Chunk {
     /**
      * Constructs a Chunk type preserving non-emptiness.
      *
-     * @example
+     * **Example** (Preserving non-emptiness)
+     *
      * ```ts
      * import type { Chunk } from "effect"
      *
@@ -2036,7 +2078,8 @@ export declare namespace Chunk {
     /**
      * Creates a non-empty Chunk if either input is non-empty.
      *
-     * @example
+     * **Example** (Preserving non-emptiness from either input)
+     *
      * ```ts
      * import type { Chunk } from "effect"
      *
@@ -2067,7 +2110,8 @@ export declare namespace Chunk {
     /**
      * Creates a non-empty Chunk only if both inputs are non-empty.
      *
-     * @example
+     * **Example** (Requiring non-emptiness from both inputs)
+     *
      * ```ts
      * import type { Chunk } from "effect"
      *
@@ -2098,7 +2142,8 @@ export declare namespace Chunk {
     /**
      * Flattens a nested Chunk type.
      *
-     * @example
+     * **Example** (Flattening nested chunk types)
+     *
      * ```ts
      * import type { Chunk } from "effect"
      *
@@ -2118,83 +2163,80 @@ export declare namespace Chunk {
  * Transforms the elements of a chunk using the specified mapping function.
  * If the input chunk is non-empty, the resulting chunk will also be non-empty.
  *
- * @example
+ * **Example** (Mapping values)
  *
  * ```ts
  * import { Chunk } from "effect"
  *
  * const result = Chunk.map(Chunk.make(1, 2), (n) => n + 1)
  *
- * console.log(result)
- * // { _id: 'Chunk', values: [ 2, 3 ] }
+ * console.log(Chunk.toArray(result)) // [2, 3]
  * ```
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export declare const map: {
     /**
      * Transforms the elements of a chunk using the specified mapping function.
      * If the input chunk is non-empty, the resulting chunk will also be non-empty.
      *
-     * @example
+     * **Example** (Mapping values)
      *
      * ```ts
      * import { Chunk } from "effect"
      *
      * const result = Chunk.map(Chunk.make(1, 2), (n) => n + 1)
      *
-     * console.log(result)
-     * // { _id: 'Chunk', values: [ 2, 3 ] }
+     * console.log(Chunk.toArray(result)) // [2, 3]
      * ```
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <S extends Chunk<any>, B>(f: (a: Chunk.Infer<S>, i: number) => B): (self: S) => Chunk.With<S, B>;
     /**
      * Transforms the elements of a chunk using the specified mapping function.
      * If the input chunk is non-empty, the resulting chunk will also be non-empty.
      *
-     * @example
+     * **Example** (Mapping values)
      *
      * ```ts
      * import { Chunk } from "effect"
      *
      * const result = Chunk.map(Chunk.make(1, 2), (n) => n + 1)
      *
-     * console.log(result)
-     * // { _id: 'Chunk', values: [ 2, 3 ] }
+     * console.log(Chunk.toArray(result)) // [2, 3]
      * ```
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <A, B>(self: NonEmptyChunk<A>, f: (a: A, i: number) => B): NonEmptyChunk<B>;
     /**
      * Transforms the elements of a chunk using the specified mapping function.
      * If the input chunk is non-empty, the resulting chunk will also be non-empty.
      *
-     * @example
+     * **Example** (Mapping values)
      *
      * ```ts
      * import { Chunk } from "effect"
      *
      * const result = Chunk.map(Chunk.make(1, 2), (n) => n + 1)
      *
-     * console.log(result)
-     * // { _id: 'Chunk', values: [ 2, 3 ] }
+     * console.log(Chunk.toArray(result)) // [2, 3]
      * ```
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <A, B>(self: Chunk<A>, f: (a: A, i: number) => B): Chunk<B>;
 };
 /**
  * Statefully maps over the chunk, producing new elements of type `B`.
  *
- * @example
+ * **Example** (Mapping with accumulated state)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2217,14 +2259,15 @@ export declare const map: {
  * console.log(Chunk.toArray(indexed)) // ["0: hello", "1: world", "2: effect"]
  * ```
  *
- * @since 2.0.0
  * @category folding
+ * @since 2.0.0
  */
 export declare const mapAccum: {
     /**
      * Statefully maps over the chunk, producing new elements of type `B`.
      *
-     * @example
+     * **Example** (Mapping with accumulated state)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -2247,14 +2290,15 @@ export declare const mapAccum: {
      * console.log(Chunk.toArray(indexed)) // ["0: hello", "1: world", "2: effect"]
      * ```
      *
-     * @since 2.0.0
      * @category folding
+     * @since 2.0.0
      */
     <S, A, B>(s: S, f: (s: S, a: A) => readonly [S, B]): (self: Chunk<A>) => [S, Chunk<B>];
     /**
      * Statefully maps over the chunk, producing new elements of type `B`.
      *
-     * @example
+     * **Example** (Mapping with accumulated state)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -2277,8 +2321,8 @@ export declare const mapAccum: {
      * console.log(Chunk.toArray(indexed)) // ["0: hello", "1: world", "2: effect"]
      * ```
      *
-     * @since 2.0.0
      * @category folding
+     * @since 2.0.0
      */
     <S, A, B>(self: Chunk<A>, s: S, f: (s: S, a: A) => readonly [S, B]): [S, Chunk<B>];
 };
@@ -2288,7 +2332,8 @@ export declare const mapAccum: {
  * - Returns `[excluded, satisfying]`.
  * - The filter receives `(element, index)`.
  *
- * @example
+ * **Example** (Partitioning with a Result)
+ *
  * ```ts
  * import { Chunk, Result } from "effect"
  *
@@ -2310,7 +2355,8 @@ export declare const partition: {
      * - Returns `[excluded, satisfying]`.
      * - The filter receives `(element, index)`.
      *
-     * @example
+     * **Example** (Partitioning with a Result)
+     *
      * ```ts
      * import { Chunk, Result } from "effect"
      *
@@ -2332,7 +2378,8 @@ export declare const partition: {
      * - Returns `[excluded, satisfying]`.
      * - The filter receives `(element, index)`.
      *
-     * @example
+     * **Example** (Partitioning with a Result)
+     *
      * ```ts
      * import { Chunk, Result } from "effect"
      *
@@ -2350,9 +2397,14 @@ export declare const partition: {
     <A, Pass, Fail>(self: Chunk<A>, f: (input: A, i: number) => Result<Pass, Fail>): [excluded: Chunk<Fail>, satisfying: Chunk<Pass>];
 };
 /**
- * Partitions the elements of this chunk into two chunks.
+ * Separates a chunk of `Result` values into a chunk of failures and a chunk of
+ * successes.
+ *
+ * The returned tuple is `[failures, successes]`, preserving the original order
+ * within each side.
+ *
+ * **Example** (Separating failures and successes)
  *
- * @example
  * ```ts
  * import { Chunk } from "effect"
  * import * as Result from "effect/Result"
@@ -2383,7 +2435,8 @@ export declare const separate: <A, B>(self: Chunk<Result<B, A>>) => [Chunk<A>, C
 /**
  * Retrieves the size of the chunk.
  *
- * @example
+ * **Example** (Getting chunk size)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2398,7 +2451,8 @@ export declare const size: <A>(self: Chunk<A>) => number;
 /**
  * Sort the elements of a Chunk in increasing order, creating a new Chunk.
  *
- * @example
+ * **Example** (Sorting chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  * import * as Order from "effect/Order"
@@ -2417,14 +2471,15 @@ export declare const size: <A>(self: Chunk<A>) => number;
  * console.log(Chunk.toArray(sortedWords)) // ["apple", "banana", "cherry"]
  * ```
  *
- * @since 2.0.0
  * @category sorting
+ * @since 2.0.0
  */
 export declare const sort: {
     /**
      * Sort the elements of a Chunk in increasing order, creating a new Chunk.
      *
-     * @example
+     * **Example** (Sorting chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      * import * as Order from "effect/Order"
@@ -2443,14 +2498,15 @@ export declare const sort: {
      * console.log(Chunk.toArray(sortedWords)) // ["apple", "banana", "cherry"]
      * ```
      *
-     * @since 2.0.0
      * @category sorting
+     * @since 2.0.0
      */
     <B>(O: Order.Order<B>): <A extends B>(self: Chunk<A>) => Chunk<A>;
     /**
      * Sort the elements of a Chunk in increasing order, creating a new Chunk.
      *
-     * @example
+     * **Example** (Sorting chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      * import * as Order from "effect/Order"
@@ -2469,15 +2525,16 @@ export declare const sort: {
      * console.log(Chunk.toArray(sortedWords)) // ["apple", "banana", "cherry"]
      * ```
      *
-     * @since 2.0.0
      * @category sorting
+     * @since 2.0.0
      */
     <A extends B, B>(self: Chunk<A>, O: Order.Order<B>): Chunk<A>;
 };
 /**
  * Sorts the elements of a Chunk based on a projection function.
  *
- * @example
+ * **Example** (Sorting chunks by a derived value)
+ *
  * ```ts
  * import { Chunk } from "effect"
  * import * as Order from "effect/Order"
@@ -2504,14 +2561,15 @@ export declare const sort: {
  * console.log(Chunk.toArray(byLength)) // ["a", "ab", "abc"]
  * ```
  *
- * @since 2.0.0
  * @category sorting
+ * @since 2.0.0
  */
 export declare const sortWith: {
     /**
      * Sorts the elements of a Chunk based on a projection function.
      *
-     * @example
+     * **Example** (Sorting chunks by a derived value)
+     *
      * ```ts
      * import { Chunk } from "effect"
      * import * as Order from "effect/Order"
@@ -2538,14 +2596,15 @@ export declare const sortWith: {
      * console.log(Chunk.toArray(byLength)) // ["a", "ab", "abc"]
      * ```
      *
-     * @since 2.0.0
      * @category sorting
+     * @since 2.0.0
      */
     <A, B>(f: (a: A) => B, order: Order.Order<B>): (self: Chunk<A>) => Chunk<A>;
     /**
      * Sorts the elements of a Chunk based on a projection function.
      *
-     * @example
+     * **Example** (Sorting chunks by a derived value)
+     *
      * ```ts
      * import { Chunk } from "effect"
      * import * as Order from "effect/Order"
@@ -2572,15 +2631,16 @@ export declare const sortWith: {
      * console.log(Chunk.toArray(byLength)) // ["a", "ab", "abc"]
      * ```
      *
-     * @since 2.0.0
      * @category sorting
+     * @since 2.0.0
      */
     <A, B>(self: Chunk<A>, f: (a: A) => B, order: Order.Order<B>): Chunk<A>;
 };
 /**
  *  Returns two splits of this chunk at the specified index.
  *
- * @example
+ * **Example** (Splitting at an index)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2600,14 +2660,15 @@ export declare const sortWith: {
  * console.log(Chunk.toArray(empty2)) // []
  * ```
  *
- * @since 2.0.0
  * @category splitting
+ * @since 2.0.0
  */
 export declare const splitAt: {
     /**
      *  Returns two splits of this chunk at the specified index.
      *
-     * @example
+     * **Example** (Splitting at an index)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -2627,14 +2688,15 @@ export declare const splitAt: {
      * console.log(Chunk.toArray(empty2)) // []
      * ```
      *
-     * @since 2.0.0
      * @category splitting
+     * @since 2.0.0
      */
     (n: number): <A>(self: Chunk<A>) => [beforeIndex: Chunk<A>, fromIndex: Chunk<A>];
     /**
      *  Returns two splits of this chunk at the specified index.
      *
-     * @example
+     * **Example** (Splitting at an index)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -2654,16 +2716,21 @@ export declare const splitAt: {
      * console.log(Chunk.toArray(empty2)) // []
      * ```
      *
-     * @since 2.0.0
      * @category splitting
+     * @since 2.0.0
      */
     <A>(self: Chunk<A>, n: number): [beforeIndex: Chunk<A>, fromIndex: Chunk<A>];
 };
 /**
- * Splits a `NonEmptyChunk` into two segments, with the first segment containing a maximum of `n` elements.
- * The value of `n` must be `>= 1`.
+ * Splits a `NonEmptyChunk` at `n`, returning a non-empty prefix and the
+ * remaining suffix.
+ *
+ * `n` is floored and normalized to at least `1`. If `n` is greater than or
+ * equal to the chunk length, the first result is the original chunk and the
+ * second result is empty.
+ *
+ * **Example** (Splitting non-empty chunks at an index)
  *
- * @example
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2686,10 +2753,15 @@ export declare const splitAt: {
  */
 export declare const splitNonEmptyAt: {
     /**
-     * Splits a `NonEmptyChunk` into two segments, with the first segment containing a maximum of `n` elements.
-     * The value of `n` must be `>= 1`.
+     * Splits a `NonEmptyChunk` at `n`, returning a non-empty prefix and the
+     * remaining suffix.
+     *
+     * `n` is floored and normalized to at least `1`. If `n` is greater than or
+     * equal to the chunk length, the first result is the original chunk and the
+     * second result is empty.
+     *
+     * **Example** (Splitting non-empty chunks at an index)
      *
-     * @example
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -2712,10 +2784,15 @@ export declare const splitNonEmptyAt: {
      */
     (n: number): <A>(self: NonEmptyChunk<A>) => [beforeIndex: NonEmptyChunk<A>, fromIndex: Chunk<A>];
     /**
-     * Splits a `NonEmptyChunk` into two segments, with the first segment containing a maximum of `n` elements.
-     * The value of `n` must be `>= 1`.
+     * Splits a `NonEmptyChunk` at `n`, returning a non-empty prefix and the
+     * remaining suffix.
+     *
+     * `n` is floored and normalized to at least `1`. If `n` is greater than or
+     * equal to the chunk length, the first result is the original chunk and the
+     * second result is empty.
+     *
+     * **Example** (Splitting non-empty chunks at an index)
      *
-     * @example
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -2739,9 +2816,13 @@ export declare const splitNonEmptyAt: {
     <A>(self: NonEmptyChunk<A>, n: number): [beforeIndex: NonEmptyChunk<A>, fromIndex: Chunk<A>];
 };
 /**
- * Splits this chunk into `n` equally sized chunks.
+ * Splits a chunk into up to `n` chunks, distributing elements in order.
+ *
+ * The chunk size is derived from the input length and `n`; the final chunk may
+ * contain fewer elements than the others.
+ *
+ * **Example** (Splitting chunks into groups)
  *
- * @example
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2762,14 +2843,18 @@ export declare const splitNonEmptyAt: {
  * // [[1, 2, 3, 4, 5, 6, 7, 8, 9]]
  * ```
  *
- * @since 2.0.0
  * @category splitting
+ * @since 2.0.0
  */
 export declare const split: {
     /**
-     * Splits this chunk into `n` equally sized chunks.
+     * Splits a chunk into up to `n` chunks, distributing elements in order.
+     *
+     * The chunk size is derived from the input length and `n`; the final chunk may
+     * contain fewer elements than the others.
+     *
+     * **Example** (Splitting chunks into groups)
      *
-     * @example
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -2790,14 +2875,18 @@ export declare const split: {
      * // [[1, 2, 3, 4, 5, 6, 7, 8, 9]]
      * ```
      *
-     * @since 2.0.0
      * @category splitting
+     * @since 2.0.0
      */
     (n: number): <A>(self: Chunk<A>) => Chunk<Chunk<A>>;
     /**
-     * Splits this chunk into `n` equally sized chunks.
+     * Splits a chunk into up to `n` chunks, distributing elements in order.
+     *
+     * The chunk size is derived from the input length and `n`; the final chunk may
+     * contain fewer elements than the others.
+     *
+     * **Example** (Splitting chunks into groups)
      *
-     * @example
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -2818,8 +2907,8 @@ export declare const split: {
      * // [[1, 2, 3, 4, 5, 6, 7, 8, 9]]
      * ```
      *
-     * @since 2.0.0
      * @category splitting
+     * @since 2.0.0
      */
     <A>(self: Chunk<A>, n: number): Chunk<Chunk<A>>;
 };
@@ -2827,7 +2916,8 @@ export declare const split: {
  * Splits this chunk on the first element that matches this predicate.
  * Returns a tuple containing two chunks: the first one is before the match, and the second one is from the match onward.
  *
- * @example
+ * **Example** (Splitting at a matching element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2855,7 +2945,8 @@ export declare const splitWhere: {
      * Splits this chunk on the first element that matches this predicate.
      * Returns a tuple containing two chunks: the first one is before the match, and the second one is from the match onward.
      *
-     * @example
+     * **Example** (Splitting at a matching element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -2883,7 +2974,8 @@ export declare const splitWhere: {
      * Splits this chunk on the first element that matches this predicate.
      * Returns a tuple containing two chunks: the first one is before the match, and the second one is from the match onward.
      *
-     * @example
+     * **Example** (Splitting at a matching element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -2911,7 +3003,8 @@ export declare const splitWhere: {
 /**
  * Returns every elements after the first.
  *
- * @example
+ * **Example** (Getting the tail safely)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2925,14 +3018,15 @@ export declare const splitWhere: {
  * console.log(Chunk.tail(empty)) // Option.none()
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const tail: <A>(self: Chunk<A>) => O.Option<Chunk<A>>;
 /**
  * Returns every elements after the first.
  *
- * @example
+ * **Example** (Getting the tail of a non-empty chunk)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2948,14 +3042,15 @@ export declare const tail: <A>(self: Chunk<A>) => O.Option<Chunk<A>>;
  * // Chunk.tailNonEmpty(Chunk.empty()) // TypeScript error
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const tailNonEmpty: <A>(self: NonEmptyChunk<A>) => Chunk<A>;
 /**
  * Takes the last `n` elements.
  *
- * @example
+ * **Example** (Taking elements from the end)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2972,14 +3067,15 @@ export declare const tailNonEmpty: <A>(self: NonEmptyChunk<A>) => Chunk<A>;
  * console.log(Chunk.toArray(none)) // []
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const takeRight: {
     /**
      * Takes the last `n` elements.
      *
-     * @example
+     * **Example** (Taking elements from the end)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -2996,14 +3092,15 @@ export declare const takeRight: {
      * console.log(Chunk.toArray(none)) // []
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     (n: number): <A>(self: Chunk<A>) => Chunk<A>;
     /**
      * Takes the last `n` elements.
      *
-     * @example
+     * **Example** (Taking elements from the end)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3020,15 +3117,16 @@ export declare const takeRight: {
      * console.log(Chunk.toArray(none)) // []
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A>(self: Chunk<A>, n: number): Chunk<A>;
 };
 /**
  * Takes all elements so long as the predicate returns true.
  *
- * @example
+ * **Example** (Taking elements while a predicate matches)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3046,14 +3144,15 @@ export declare const takeRight: {
  * console.log(Chunk.toArray(all)) // [1, 2, 3]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const takeWhile: {
     /**
      * Takes all elements so long as the predicate returns true.
      *
-     * @example
+     * **Example** (Taking elements while a predicate matches)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3071,14 +3170,15 @@ export declare const takeWhile: {
      * console.log(Chunk.toArray(all)) // [1, 2, 3]
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A, B extends A>(refinement: Refinement<NoInfer<A>, B>): (self: Chunk<A>) => Chunk<B>;
     /**
      * Takes all elements so long as the predicate returns true.
      *
-     * @example
+     * **Example** (Taking elements while a predicate matches)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3096,14 +3196,15 @@ export declare const takeWhile: {
      * console.log(Chunk.toArray(all)) // [1, 2, 3]
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A>(predicate: Predicate<NoInfer<A>>): (self: Chunk<A>) => Chunk<A>;
     /**
      * Takes all elements so long as the predicate returns true.
      *
-     * @example
+     * **Example** (Taking elements while a predicate matches)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3121,14 +3222,15 @@ export declare const takeWhile: {
      * console.log(Chunk.toArray(all)) // [1, 2, 3]
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A, B extends A>(self: Chunk<A>, refinement: Refinement<A, B>): Chunk<B>;
     /**
      * Takes all elements so long as the predicate returns true.
      *
-     * @example
+     * **Example** (Taking elements while a predicate matches)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3146,15 +3248,16 @@ export declare const takeWhile: {
      * console.log(Chunk.toArray(all)) // [1, 2, 3]
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A>(self: Chunk<A>, predicate: Predicate<A>): Chunk<A>;
 };
 /**
  * Creates a Chunks of unique values, in order, from all given Chunks.
  *
- * @example
+ * **Example** (Unioning chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3170,14 +3273,15 @@ export declare const takeWhile: {
  * console.log(Chunk.toArray(unified)) // [1, 2, 3]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const union: {
     /**
      * Creates a Chunks of unique values, in order, from all given Chunks.
      *
-     * @example
+     * **Example** (Unioning chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3193,14 +3297,15 @@ export declare const union: {
      * console.log(Chunk.toArray(unified)) // [1, 2, 3]
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A>(that: Chunk<A>): <B>(self: Chunk<B>) => Chunk<A | B>;
     /**
      * Creates a Chunks of unique values, in order, from all given Chunks.
      *
-     * @example
+     * **Example** (Unioning chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3216,15 +3321,17 @@ export declare const union: {
      * console.log(Chunk.toArray(unified)) // [1, 2, 3]
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A, B>(self: Chunk<A>, that: Chunk<B>): Chunk<A | B>;
 };
 /**
- * Remove duplicates from an array, keeping the first occurrence of an element.
+ * Removes duplicate elements from a `Chunk`, preserving the first occurrence
+ * of each value.
+ *
+ * **Example** (Removing duplicate values)
  *
- * @example
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3243,14 +3350,15 @@ export declare const union: {
  * console.log(Chunk.toArray(uniqueDeduped)) // [1, 2, 3]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const dedupe: <A>(self: Chunk<A>) => Chunk<A>;
 /**
  * Deduplicates adjacent elements that are identical.
  *
- * @example
+ * **Example** (Removing adjacent duplicates)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3264,8 +3372,8 @@ export declare const dedupe: <A>(self: Chunk<A>) => Chunk<A>;
  * console.log(Chunk.toArray(mixedResult)) // ["a", "b", "a"]
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export declare const dedupeAdjacent: <A>(self: Chunk<A>) => Chunk<A>;
 /**
@@ -3273,7 +3381,8 @@ export declare const dedupeAdjacent: <A>(self: Chunk<A>) => Chunk<A>;
  *
  * Note: The function is reverse of `zip`.
  *
- * @example
+ * **Example** (Unzipping pairs)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3293,14 +3402,15 @@ export declare const dedupeAdjacent: <A>(self: Chunk<A>) => Chunk<A>;
  * console.log(Chunk.toArray(emptyStrs)) // []
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const unzip: <A, B>(self: Chunk<readonly [A, B]>) => [Chunk<A>, Chunk<B>];
 /**
  * Zips this chunk pointwise with the specified chunk using the specified combiner.
  *
- * @example
+ * **Example** (Zipping chunks with a function)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3316,14 +3426,15 @@ export declare const unzip: <A, B>(self: Chunk<readonly [A, B]>) => [Chunk<A>, C
  * console.log(Chunk.toArray(mixed)) // [[1, "a"], [2, "b"]]
  * ```
  *
- * @since 2.0.0
  * @category zipping
+ * @since 2.0.0
  */
 export declare const zipWith: {
     /**
      * Zips this chunk pointwise with the specified chunk using the specified combiner.
      *
-     * @example
+     * **Example** (Zipping chunks with a function)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3339,14 +3450,15 @@ export declare const zipWith: {
      * console.log(Chunk.toArray(mixed)) // [[1, "a"], [2, "b"]]
      * ```
      *
-     * @since 2.0.0
      * @category zipping
+     * @since 2.0.0
      */
     <A, B, C>(that: Chunk<B>, f: (a: A, b: B) => C): (self: Chunk<A>) => Chunk<C>;
     /**
      * Zips this chunk pointwise with the specified chunk using the specified combiner.
      *
-     * @example
+     * **Example** (Zipping chunks with a function)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3362,15 +3474,16 @@ export declare const zipWith: {
      * console.log(Chunk.toArray(mixed)) // [[1, "a"], [2, "b"]]
      * ```
      *
-     * @since 2.0.0
      * @category zipping
+     * @since 2.0.0
      */
     <A, B, C>(self: Chunk<A>, that: Chunk<B>, f: (a: A, b: B) => C): Chunk<C>;
 };
 /**
  * Zips this chunk pointwise with the specified chunk.
  *
- * @example
+ * **Example** (Zipping chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3386,14 +3499,15 @@ export declare const zipWith: {
  * console.log(Chunk.toArray(zipped)) // [[1, "a"], [2, "b"]]
  * ```
  *
- * @since 2.0.0
  * @category zipping
+ * @since 2.0.0
  */
 export declare const zip: {
     /**
      * Zips this chunk pointwise with the specified chunk.
      *
-     * @example
+     * **Example** (Zipping chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3409,14 +3523,15 @@ export declare const zip: {
      * console.log(Chunk.toArray(zipped)) // [[1, "a"], [2, "b"]]
      * ```
      *
-     * @since 2.0.0
      * @category zipping
+     * @since 2.0.0
      */
     <B>(that: Chunk<B>): <A>(self: Chunk<A>) => Chunk<[A, B]>;
     /**
      * Zips this chunk pointwise with the specified chunk.
      *
-     * @example
+     * **Example** (Zipping chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3432,15 +3547,16 @@ export declare const zip: {
      * console.log(Chunk.toArray(zipped)) // [[1, "a"], [2, "b"]]
      * ```
      *
-     * @since 2.0.0
      * @category zipping
+     * @since 2.0.0
      */
     <A, B>(self: Chunk<A>, that: Chunk<B>): Chunk<[A, B]>;
 };
 /**
  * Delete the element at the specified index, creating a new `Chunk`.
  *
- * @example
+ * **Example** (Removing an element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3464,7 +3580,8 @@ export declare const remove: {
     /**
      * Delete the element at the specified index, creating a new `Chunk`.
      *
-     * @example
+     * **Example** (Removing an element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3488,7 +3605,8 @@ export declare const remove: {
     /**
      * Delete the element at the specified index, creating a new `Chunk`.
      *
-     * @example
+     * **Example** (Removing an element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3514,7 +3632,8 @@ export declare const remove: {
  * Applies a function to the element at the specified index, creating a new `Chunk`,
  * or returns `None` if the index is out of bounds.
  *
- * @example
+ * **Example** (Modifying an element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3539,7 +3658,8 @@ export declare const modify: {
      * Applies a function to the element at the specified index, creating a new `Chunk`,
      * or returns `None` if the index is out of bounds.
      *
-     * @example
+     * **Example** (Modifying an element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3564,7 +3684,8 @@ export declare const modify: {
      * Applies a function to the element at the specified index, creating a new `Chunk`,
      * or returns `None` if the index is out of bounds.
      *
-     * @example
+     * **Example** (Modifying an element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3590,7 +3711,8 @@ export declare const modify: {
  * Change the element at the specified index, creating a new `Chunk`,
  * or returns `None` if the index is out of bounds.
  *
- * @example
+ * **Example** (Replacing an element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3615,7 +3737,8 @@ export declare const replace: {
      * Change the element at the specified index, creating a new `Chunk`,
      * or returns `None` if the index is out of bounds.
      *
-     * @example
+     * **Example** (Replacing an element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3640,7 +3763,8 @@ export declare const replace: {
      * Change the element at the specified index, creating a new `Chunk`,
      * or returns `None` if the index is out of bounds.
      *
-     * @example
+     * **Example** (Replacing an element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3667,13 +3791,13 @@ export declare const replace: {
  *
  * **Note**. `n` is normalized to an integer >= 1.
  *
- * @example
+ * **Example** (Generating chunks from indices)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
  * const chunk = Chunk.makeBy(5, (i) => i * 2)
- * console.log(chunk)
- * // { _id: 'Chunk', values: [ 0, 2, 4, 6, 8 ] }
+ * console.log(Chunk.toArray(chunk)) // [0, 2, 4, 6, 8]
  * ```
  *
  * @category constructors
@@ -3685,13 +3809,13 @@ export declare const makeBy: {
      *
      * **Note**. `n` is normalized to an integer >= 1.
      *
-     * @example
+     * **Example** (Generating chunks from indices)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
      * const chunk = Chunk.makeBy(5, (i) => i * 2)
-     * console.log(chunk)
-     * // { _id: 'Chunk', values: [ 0, 2, 4, 6, 8 ] }
+     * console.log(Chunk.toArray(chunk)) // [0, 2, 4, 6, 8]
      * ```
      *
      * @category constructors
@@ -3703,13 +3827,13 @@ export declare const makeBy: {
      *
      * **Note**. `n` is normalized to an integer >= 1.
      *
-     * @example
+     * **Example** (Generating chunks from indices)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
      * const chunk = Chunk.makeBy(5, (i) => i * 2)
-     * console.log(chunk)
-     * // { _id: 'Chunk', values: [ 0, 2, 4, 6, 8 ] }
+     * console.log(Chunk.toArray(chunk)) // [0, 2, 4, 6, 8]
      * ```
      *
      * @category constructors
@@ -3718,15 +3842,19 @@ export declare const makeBy: {
     <A>(n: number, f: (i: number) => A): NonEmptyChunk<A>;
 };
 /**
- * Create a non empty `Chunk` containing a range of integers, including both endpoints.
+ * Creates a non-empty `Chunk` of consecutive integers from `start` through
+ * `end`, inclusive.
+ *
+ * If `start` is greater than `end`, returns a single-element chunk containing
+ * `start`.
+ *
+ * **Example** (Creating a range)
  *
- * @example
  * ```ts
  * import { Chunk } from "effect"
  *
  * const chunk = Chunk.range(1, 5)
- * console.log(chunk)
- * // { _id: 'Chunk', values: [ 1, 2, 3, 4, 5 ] }
+ * console.log(Chunk.toArray(chunk)) // [1, 2, 3, 4, 5]
  * ```
  *
  * @category constructors
@@ -3736,7 +3864,8 @@ export declare const range: (start: number, end: number) => NonEmptyChunk<number
 /**
  * Returns a function that checks if a `Chunk` contains a given value using the default `Equivalence`.
  *
- * @example
+ * **Example** (Checking membership)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3761,7 +3890,8 @@ export declare const contains: {
     /**
      * Returns a function that checks if a `Chunk` contains a given value using the default `Equivalence`.
      *
-     * @example
+     * **Example** (Checking membership)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3786,7 +3916,8 @@ export declare const contains: {
     /**
      * Returns a function that checks if a `Chunk` contains a given value using the default `Equivalence`.
      *
-     * @example
+     * **Example** (Checking membership)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -3812,7 +3943,8 @@ export declare const contains: {
 /**
  * Returns a function that checks if a `Chunk` contains a given value using a provided `isEquivalent` function.
  *
- * @example
+ * **Example** (Checking membership with custom equivalence)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3845,7 +3977,8 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
  * Returns the first element that satisfies the specified
  * predicate, or `None` if no such element exists.
  *
- * @example
+ * **Example** (Finding the first matching element)
+ *
  * ```ts
  * import { Chunk, Option } from "effect"
  *
@@ -3875,7 +4008,8 @@ export declare const findFirst: {
      * Returns the first element that satisfies the specified
      * predicate, or `None` if no such element exists.
      *
-     * @example
+     * **Example** (Finding the first matching element)
+     *
      * ```ts
      * import { Chunk, Option } from "effect"
      *
@@ -3905,7 +4039,8 @@ export declare const findFirst: {
      * Returns the first element that satisfies the specified
      * predicate, or `None` if no such element exists.
      *
-     * @example
+     * **Example** (Finding the first matching element)
+     *
      * ```ts
      * import { Chunk, Option } from "effect"
      *
@@ -3935,7 +4070,8 @@ export declare const findFirst: {
      * Returns the first element that satisfies the specified
      * predicate, or `None` if no such element exists.
      *
-     * @example
+     * **Example** (Finding the first matching element)
+     *
      * ```ts
      * import { Chunk, Option } from "effect"
      *
@@ -3965,7 +4101,8 @@ export declare const findFirst: {
      * Returns the first element that satisfies the specified
      * predicate, or `None` if no such element exists.
      *
-     * @example
+     * **Example** (Finding the first matching element)
+     *
      * ```ts
      * import { Chunk, Option } from "effect"
      *
@@ -3995,7 +4132,8 @@ export declare const findFirst: {
 /**
  * Return the first index for which a predicate holds.
  *
- * @example
+ * **Example** (Finding the first matching index)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -4019,7 +4157,8 @@ export declare const findFirstIndex: {
     /**
      * Return the first index for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the first matching index)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4043,7 +4182,8 @@ export declare const findFirstIndex: {
     /**
      * Return the first index for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the first matching index)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4068,7 +4208,8 @@ export declare const findFirstIndex: {
 /**
  * Find the last element for which a predicate holds.
  *
- * @example
+ * **Example** (Finding the last matching element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  * import * as Option from "effect/Option"
@@ -4094,7 +4235,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last matching element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      * import * as Option from "effect/Option"
@@ -4120,7 +4262,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last matching element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      * import * as Option from "effect/Option"
@@ -4146,7 +4289,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last matching element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      * import * as Option from "effect/Option"
@@ -4172,7 +4316,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last matching element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      * import * as Option from "effect/Option"
@@ -4199,7 +4344,8 @@ export declare const findLast: {
 /**
  * Return the last index for which a predicate holds.
  *
- * @example
+ * **Example** (Finding the last matching index)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -4223,7 +4369,8 @@ export declare const findLastIndex: {
     /**
      * Return the last index for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last matching index)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4247,7 +4394,8 @@ export declare const findLastIndex: {
     /**
      * Return the last index for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last matching index)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4272,7 +4420,8 @@ export declare const findLastIndex: {
 /**
  * Check if a predicate holds true for every `Chunk` element.
  *
- * @example
+ * **Example** (Checking every element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -4299,7 +4448,8 @@ export declare const every: {
     /**
      * Check if a predicate holds true for every `Chunk` element.
      *
-     * @example
+     * **Example** (Checking every element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4326,7 +4476,8 @@ export declare const every: {
     /**
      * Check if a predicate holds true for every `Chunk` element.
      *
-     * @example
+     * **Example** (Checking every element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4353,7 +4504,8 @@ export declare const every: {
     /**
      * Check if a predicate holds true for every `Chunk` element.
      *
-     * @example
+     * **Example** (Checking every element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4380,7 +4532,8 @@ export declare const every: {
     /**
      * Check if a predicate holds true for every `Chunk` element.
      *
-     * @example
+     * **Example** (Checking every element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4408,7 +4561,8 @@ export declare const every: {
 /**
  * Check if a predicate holds true for some `Chunk` element.
  *
- * @example
+ * **Example** (Checking for some matching element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -4432,7 +4586,8 @@ export declare const some: {
     /**
      * Check if a predicate holds true for some `Chunk` element.
      *
-     * @example
+     * **Example** (Checking for some matching element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4456,7 +4611,8 @@ export declare const some: {
     /**
      * Check if a predicate holds true for some `Chunk` element.
      *
-     * @example
+     * **Example** (Checking for some matching element)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4481,7 +4637,8 @@ export declare const some: {
 /**
  * Joins the elements together with "sep" in the middle.
  *
- * @example
+ * **Example** (Joining chunks into a string)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -4509,7 +4666,8 @@ export declare const join: {
     /**
      * Joins the elements together with "sep" in the middle.
      *
-     * @example
+     * **Example** (Joining chunks into a string)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4537,7 +4695,8 @@ export declare const join: {
     /**
      * Joins the elements together with "sep" in the middle.
      *
-     * @example
+     * **Example** (Joining chunks into a string)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4566,7 +4725,8 @@ export declare const join: {
 /**
  * Reduces the elements of a chunk from left to right.
  *
- * @example
+ * **Example** (Reducing from the left)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -4591,7 +4751,8 @@ export declare const reduce: {
     /**
      * Reduces the elements of a chunk from left to right.
      *
-     * @example
+     * **Example** (Reducing from the left)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4616,7 +4777,8 @@ export declare const reduce: {
     /**
      * Reduces the elements of a chunk from left to right.
      *
-     * @example
+     * **Example** (Reducing from the left)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4642,7 +4804,8 @@ export declare const reduce: {
 /**
  * Reduces the elements of a chunk from right to left.
  *
- * @example
+ * **Example** (Reducing from the right)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -4671,7 +4834,8 @@ export declare const reduceRight: {
     /**
      * Reduces the elements of a chunk from right to left.
      *
-     * @example
+     * **Example** (Reducing from the right)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4700,7 +4864,8 @@ export declare const reduceRight: {
     /**
      * Reduces the elements of a chunk from right to left.
      *
-     * @example
+     * **Example** (Reducing from the right)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4731,7 +4896,8 @@ export declare const reduceRight: {
  * Creates a `Chunk` of values not included in the other given `Chunk` using the provided `isEquivalent` function.
  * The order and references of result values are determined by the first `Chunk`.
  *
- * @example
+ * **Example** (Computing difference with custom equivalence)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -4766,7 +4932,8 @@ export declare const differenceWith: <A>(isEquivalent: (self: A, that: A) => boo
  * Creates a `Chunk` of values not included in the other given `Chunk`.
  * The order and references of result values are determined by the first `Chunk`.
  *
- * @example
+ * **Example** (Computing chunk difference)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -4795,7 +4962,8 @@ export declare const difference: {
      * Creates a `Chunk` of values not included in the other given `Chunk`.
      * The order and references of result values are determined by the first `Chunk`.
      *
-     * @example
+     * **Example** (Computing chunk difference)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -4824,7 +4992,8 @@ export declare const difference: {
      * Creates a `Chunk` of values not included in the other given `Chunk`.
      * The order and references of result values are determined by the first `Chunk`.
      *
-     * @example
+     * **Example** (Computing chunk difference)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *