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

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,13 +133,13 @@ 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"
+ * import type { Chunk, HKT } from "effect"
  *
  * // Create a Chunk type using the type lambda
- * type NumberChunk = Kind<ChunkTypeLambda, never, never, never, number>
+ * type NumberChunk = HKT.Kind<Chunk.ChunkTypeLambda, never, never, never, number>
  * // Equivalent to: Chunk<number>
  * ```
  *
@@ -169,12 +173,13 @@ 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"
+ * import { Chunk, Equivalence } from "effect"
  *
  * const chunk1 = Chunk.make(1, 2, 3)
  * const chunk2 = Chunk.make(1, 2, 3)
@@ -186,13 +191,14 @@ interface ISlice<A> {
  * ```
  *
  * @category equivalence
- * @since 2.0.0
+ * @since 4.0.0
  */
 export declare const makeEquivalence: <A>(isEquivalent: Equivalence.Equivalence<A>) => Equivalence.Equivalence<Chunk<A>>;
 /**
  * Checks if `u` is a `Chunk<unknown>`
  *
- * @example
+ * **Example** (Checking for chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -211,7 +217,8 @@ export declare const isChunk: {
     /**
      * Checks if `u` is a `Chunk<unknown>`
      *
-     * @example
+     * **Example** (Checking for chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -230,7 +237,8 @@ export declare const isChunk: {
     /**
      * Checks if `u` is a `Chunk<unknown>`
      *
-     * @example
+     * **Example** (Checking for chunks)
+     *
      * ```ts
      * import { Chunk } from "effect"
      *
@@ -250,7 +258,8 @@ export declare const isChunk: {
 /**
  * Creates an empty `Chunk`.
  *
- * @example
+ * **Example** (Creating an empty chunk)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -265,13 +274,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 +290,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 +306,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 +324,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"
  *
@@ -329,7 +339,7 @@ export declare const fromIterable: <A>(self: Iterable<A>) => Chunk<A>;
  * console.log(Chunk.toArray(emptyChunk)) // []
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 export declare const toArray: <S extends Chunk<any>>(self: S) => S extends NonEmptyChunk<any> ? RA.NonEmptyArray<Chunk.Infer<S>> : Array<Chunk.Infer<S>>;
@@ -338,7 +348,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"
  *
@@ -354,7 +365,7 @@ export declare const toArray: <S extends Chunk<any>>(self: S) => S extends NonEm
  * console.log(Chunk.toReadonlyArray(emptyChunk)) // []
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 export declare const toReadonlyArray: <S extends Chunk<any>>(self: S) => S extends NonEmptyChunk<any> ? RA.NonEmptyReadonlyArray<Chunk.Infer<S>> : ReadonlyArray<Chunk.Infer<S>>;
@@ -362,7 +373,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 +381,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 +414,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 +437,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 +461,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,17 +475,17 @@ export declare const get: {
  * console.log(Chunk.toArray(chunk)) // [999, 2, 3, 4, 5]
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 4.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"
+ * import { Array, Chunk } from "effect"
  *
  * const nonEmptyArray = Array.make(1, 2, 3, 4, 5)
  * const chunk = Chunk.fromNonEmptyArrayUnsafe(nonEmptyArray)
@@ -481,87 +495,79 @@ export declare const fromArrayUnsafe: <A>(self: ReadonlyArray<A>) => Chunk<A>;
  * console.log(Chunk.isNonEmpty(chunk)) // true
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 4.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 4.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 4.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 4.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 +588,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 +610,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 +633,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 +655,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 +677,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 +700,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 +717,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 +734,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 +752,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 +769,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 +786,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 +804,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 +821,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 +838,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 +856,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 +873,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 +890,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 +909,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 +931,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 +953,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 +975,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 +997,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 +1020,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 +1042,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 +1064,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 +1086,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 +1108,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,10 +1130,10 @@ 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"
+ * import { Chunk, Result } from "effect"
  *
  * const chunk = Chunk.make("1", "2", "hello", "3", "world")
  * const numbers = Chunk.filterMap(chunk, (str) => {
@@ -1139,17 +1150,17 @@ 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"
+     * import { Chunk, Result } from "effect"
      *
      * const chunk = Chunk.make("1", "2", "hello", "3", "world")
      * const numbers = Chunk.filterMap(chunk, (str) => {
@@ -1166,17 +1177,17 @@ 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"
+     * import { Chunk, Result } from "effect"
      *
      * const chunk = Chunk.make("1", "2", "hello", "3", "world")
      * const numbers = Chunk.filterMap(chunk, (str) => {
@@ -1193,15 +1204,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 +1227,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 +1249,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 +1271,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 +1293,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,18 +1315,18 @@ 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"
+ * import { Chunk, Result } from "effect"
  *
  * const chunk = Chunk.make("1", "2", "hello", "3", "4")
  * const result = Chunk.filterMapWhile(chunk, (s) => {
@@ -1328,17 +1344,17 @@ 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"
+     * import { Chunk, Result } from "effect"
      *
      * const chunk = Chunk.make("1", "2", "hello", "3", "4")
      * const result = Chunk.filterMapWhile(chunk, (s) => {
@@ -1356,17 +1372,17 @@ 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"
+     * import { Chunk, Result } from "effect"
      *
      * const chunk = Chunk.make("1", "2", "hello", "3", "4")
      * const result = Chunk.filterMapWhile(chunk, (s) => {
@@ -1384,23 +1400,22 @@ 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"
+ * import { Chunk, Option } from "effect"
  *
  * 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 +1425,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 +1447,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 +1476,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 +1505,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 +1534,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 +1549,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 +1573,8 @@ export declare const flatMap: {
  * // Index 3: 4
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const forEach: {
     /**
@@ -1567,7 +1587,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 +1611,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 +1625,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 +1649,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 +1679,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 +1704,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 +1729,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 +1754,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 +1764,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 +1785,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 +1794,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 +1815,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 +1824,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 +1845,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 +1869,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 +1885,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 +1903,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 +1914,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 4.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 +1940,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 +1965,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 +1976,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 4.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 +2002,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"
  *
@@ -1993,14 +2023,14 @@ export declare const lastNonEmpty: <A>(self: NonEmptyChunk<A>) => A;
  * type WithString = Chunk.Chunk.With<typeof nonEmptyChunk, string> // Chunk.NonEmptyChunk<string>
  * ```
  *
- * @category types
  * @since 2.0.0
  */
 export declare namespace Chunk {
     /**
      * Infers the element type of a Chunk.
      *
-     * @example
+     * **Example** (Inferring element types)
+     *
      * ```ts
      * import type { Chunk } from "effect"
      *
@@ -2018,7 +2048,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 +2067,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 +2099,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 +2131,8 @@ export declare namespace Chunk {
     /**
      * Flattens a nested Chunk type.
      *
-     * @example
+     * **Example** (Flattening nested chunk types)
+     *
      * ```ts
      * import type { Chunk } from "effect"
      *
@@ -2118,83 +2152,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 +2248,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 +2279,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 +2310,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 +2321,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 +2344,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 +2367,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,12 +2386,16 @@ 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"
+ * import { Chunk, Result } from "effect"
  *
  * const chunk = Chunk.make(
  *   Result.succeed(1),
@@ -2383,7 +2423,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,10 +2439,10 @@ 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"
+ * import { Chunk, Order } from "effect"
  *
  * const numbers = Chunk.make(3, 1, 4, 1, 5, 9, 2, 6)
  * const sorted = Chunk.sort(numbers, Order.Number)
@@ -2417,17 +2458,17 @@ 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"
+     * import { Chunk, Order } from "effect"
      *
      * const numbers = Chunk.make(3, 1, 4, 1, 5, 9, 2, 6)
      * const sorted = Chunk.sort(numbers, Order.Number)
@@ -2443,17 +2484,17 @@ 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"
+     * import { Chunk, Order } from "effect"
      *
      * const numbers = Chunk.make(3, 1, 4, 1, 5, 9, 2, 6)
      * const sorted = Chunk.sort(numbers, Order.Number)
@@ -2469,18 +2510,18 @@ 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"
+ * import { Chunk, Order } from "effect"
  *
  * const people = Chunk.make(
  *   { name: "Alice", age: 30 },
@@ -2504,17 +2545,17 @@ 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"
+     * import { Chunk, Order } from "effect"
      *
      * const people = Chunk.make(
      *   { name: "Alice", age: 30 },
@@ -2538,17 +2579,17 @@ 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"
+     * import { Chunk, Order } from "effect"
      *
      * const people = Chunk.make(
      *   { name: "Alice", age: 30 },
@@ -2572,15 +2613,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 +2642,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 +2670,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 +2698,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 +2735,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 +2766,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 +2798,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 +2825,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 +2857,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 +2889,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 +2898,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 +2927,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 +2956,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 +2985,8 @@ export declare const splitWhere: {
 /**
  * Returns every elements after the first.
  *
- * @example
+ * **Example** (Getting the tail safely)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2925,14 +3000,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 +3024,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 +3049,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 +3074,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 +3099,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 +3126,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 +3152,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 +3178,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 +3204,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 +3230,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 +3255,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 +3279,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 +3303,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 +3332,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 +3354,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 +3363,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 +3384,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 +3408,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 +3432,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 +3456,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 +3481,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 +3505,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 +3529,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 +3562,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 +3587,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 +3614,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 +3640,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 +3666,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 +3693,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 +3719,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 +3745,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 +3773,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 +3791,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 +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
@@ -3718,15 +3824,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 +3846,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 +3872,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 +3898,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 +3925,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 +3959,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 +3990,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 +4021,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 +4052,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 +4083,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 +4114,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 +4139,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 +4164,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,10 +4190,10 @@ 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"
+ * import { Chunk, Option } from "effect"
  *
  * const chunk = Chunk.make(1, 2, 3, 4, 5)
  * const result = Chunk.findLast(chunk, (n) => n < 4)
@@ -4094,10 +4216,10 @@ 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"
+     * import { Chunk, Option } from "effect"
      *
      * const chunk = Chunk.make(1, 2, 3, 4, 5)
      * const result = Chunk.findLast(chunk, (n) => n < 4)
@@ -4120,10 +4242,10 @@ 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"
+     * import { Chunk, Option } from "effect"
      *
      * const chunk = Chunk.make(1, 2, 3, 4, 5)
      * const result = Chunk.findLast(chunk, (n) => n < 4)
@@ -4146,10 +4268,10 @@ 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"
+     * import { Chunk, Option } from "effect"
      *
      * const chunk = Chunk.make(1, 2, 3, 4, 5)
      * const result = Chunk.findLast(chunk, (n) => n < 4)
@@ -4172,10 +4294,10 @@ 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"
+     * import { Chunk, Option } from "effect"
      *
      * const chunk = Chunk.make(1, 2, 3, 4, 5)
      * const result = Chunk.findLast(chunk, (n) => n < 4)
@@ -4199,7 +4321,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 +4346,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 +4371,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 +4397,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 +4425,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 +4453,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 +4481,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 +4509,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 +4538,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 +4563,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 +4588,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 +4614,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 +4643,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 +4672,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 +4702,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 +4728,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 +4754,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 +4781,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 +4811,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 +4841,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 +4873,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 +4909,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 +4939,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 +4969,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"
      *