effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/Chunk.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
@@ -94,7 +96,8 @@ 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"
  *
@@ -120,7 +123,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"
  *
@@ -137,7 +141,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"
@@ -204,9 +209,11 @@ function copy<A>(
 const emptyArray: ReadonlyArray<never> = []
 
 /**
- * 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"
@@ -316,7 +323,8 @@ const makeChunk = <A>(backing: Backing<A>): Chunk<A> => {
 /**
  * Checks if `u` is a `Chunk<unknown>`
  *
- * @example
+ * **Example** (Checking for chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -335,7 +343,8 @@ export const isChunk: {
   /**
    * Checks if `u` is a `Chunk<unknown>`
    *
-   * @example
+   * **Example** (Checking for chunks)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -354,7 +363,8 @@ export const isChunk: {
   /**
    * Checks if `u` is a `Chunk<unknown>`
    *
-   * @example
+   * **Example** (Checking for chunks)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -377,7 +387,8 @@ const _empty = makeChunk<never>({ _tag: "IEmpty" })
 /**
  * Creates an empty `Chunk`.
  *
- * @example
+ * **Example** (Creating an empty chunk)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -393,13 +404,13 @@ export const empty: <A = never>() => Chunk<A> = () => _empty
 /**
  * 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
@@ -411,13 +422,13 @@ export const make = <As extends readonly [any, ...Array<any>]>(...as: As): NonEm
 /**
  * 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
@@ -428,13 +439,13 @@ export const of = <A>(a: A): NonEmptyChunk<A> => makeChunk({ _tag: "ISingleton",
 /**
  * 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
@@ -478,7 +489,8 @@ const toArray_ = <A>(self: Chunk<A>): Array<A> => toReadonlyArray(self).slice()
  * (`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"
  *
@@ -527,7 +539,8 @@ const toReadonlyArray_ = <A>(self: Chunk<A>): ReadonlyArray<A> => {
  * 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"
  *
@@ -571,7 +584,7 @@ const reverseChunk = <A>(self: Chunk<A>): Chunk<A> => {
  * 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"
@@ -579,19 +592,19 @@ const reverseChunk = <A>(self: Chunk<A>): Chunk<A> => {
  * 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 const reverse: <S extends Chunk<any>>(self: S) => Chunk.With<S, Chunk.Infer<S>> = reverseChunk as any
 
 /**
  * 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"
  *
@@ -613,7 +626,8 @@ export 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"
    *
@@ -635,7 +649,8 @@ export 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"
    *
@@ -663,7 +678,8 @@ export 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"
  *
@@ -676,8 +692,8 @@ export const get: {
  * console.log(Chunk.toArray(chunk)) // [999, 2, 3, 4, 5]
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export const fromArrayUnsafe = <A>(self: ReadonlyArray<A>): Chunk<A> =>
   self.length === 0 ? empty() : self.length === 1 ? of(self[0]) : makeChunk({ _tag: "IArray", array: self })
@@ -685,7 +701,8 @@ export 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"
@@ -698,8 +715,8 @@ export 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 const fromNonEmptyArrayUnsafe = <A>(self: NonEmptyReadonlyArray<A>): NonEmptyChunk<A> =>
   fromArrayUnsafe(self) as any
@@ -707,73 +724,64 @@ export const fromNonEmptyArrayUnsafe = <A>(self: NonEmptyReadonlyArray<A>): NonE
 /**
  * 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 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
 } = dual(2, <A>(self: Chunk<A>, index: number): A => {
@@ -808,7 +816,8 @@ export const getUnsafe: {
 /**
  * Appends the specified element to the end of the `Chunk`.
  *
- * @example
+ * **Example** (Appending an element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -829,7 +838,8 @@ export const append: {
   /**
    * Appends the specified element to the end of the `Chunk`.
    *
-   * @example
+   * **Example** (Appending an element)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -850,7 +860,8 @@ export const append: {
   /**
    * Appends the specified element to the end of the `Chunk`.
    *
-   * @example
+   * **Example** (Appending an element)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -873,7 +884,8 @@ export 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"
  *
@@ -894,7 +906,8 @@ export 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"
    *
@@ -915,7 +928,8 @@ export 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"
    *
@@ -938,14 +952,14 @@ export 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
@@ -955,14 +969,14 @@ export 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
@@ -972,14 +986,14 @@ export 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
@@ -1027,14 +1041,14 @@ export 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
@@ -1044,14 +1058,14 @@ export 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
@@ -1061,14 +1075,14 @@ export 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
@@ -1115,14 +1129,14 @@ export 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
@@ -1132,14 +1146,14 @@ export 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
@@ -1149,14 +1163,14 @@ export 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
@@ -1168,14 +1182,14 @@ export 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
@@ -1185,14 +1199,14 @@ export 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
@@ -1202,14 +1216,14 @@ export 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
@@ -1230,7 +1244,7 @@ export 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"
@@ -1252,7 +1266,7 @@ export 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"
@@ -1274,7 +1288,7 @@ export 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"
@@ -1296,7 +1310,7 @@ export 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"
@@ -1318,7 +1332,7 @@ export 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"
@@ -1342,7 +1356,7 @@ export 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"
@@ -1364,7 +1378,7 @@ export 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"
@@ -1386,7 +1400,7 @@ export 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"
@@ -1408,7 +1422,7 @@ export 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"
@@ -1430,7 +1444,7 @@ export 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"
@@ -1461,7 +1475,7 @@ export 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"
@@ -1513,7 +1527,8 @@ export 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"
@@ -1533,14 +1548,15 @@ export const appendAll: {
  * console.log(Chunk.toArray(evenIndexNumbers)) // [1]
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export 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"
@@ -1560,14 +1576,15 @@ export 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"
@@ -1587,8 +1604,8 @@ export 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>
 } = dual(
@@ -1609,7 +1626,8 @@ export const filterMap: {
 /**
  * Returns a filtered subset of the elements.
  *
- * @example
+ * **Example** (Filtering values)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1623,14 +1641,15 @@ export const filterMap: {
  * console.log(Chunk.toArray(numbers)) // [42, 100]
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const filter: {
   /**
    * Returns a filtered subset of the elements.
    *
-   * @example
+   * **Example** (Filtering values)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -1644,14 +1663,15 @@ export 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"
    *
@@ -1665,14 +1685,15 @@ export 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"
    *
@@ -1686,14 +1707,15 @@ export 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"
    *
@@ -1707,8 +1729,8 @@ export 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>
 } = dual(
@@ -1719,7 +1741,8 @@ export const filter: {
 /**
  * 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"
@@ -1740,14 +1763,15 @@ export const filter: {
  * console.log(Chunk.toArray(allNumbers)) // [1, 2, 3, 4]
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export 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"
@@ -1768,14 +1792,15 @@ export 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"
@@ -1796,8 +1821,8 @@ export 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>
 } = dual(2, <A, B, X>(self: Chunk<A>, f: Filter.Filter<A, B, X>): Chunk<B> => {
@@ -1816,15 +1841,15 @@ export const filterMapWhile: {
 /**
  * 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
@@ -1843,7 +1868,8 @@ export 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"
  *
@@ -1864,14 +1890,15 @@ export 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 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"
    *
@@ -1892,14 +1919,15 @@ export 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"
    *
@@ -1920,14 +1948,15 @@ export 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"
    *
@@ -1948,8 +1977,8 @@ export 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>
 } = dual(2, <A, B>(self: Chunk<A>, f: (a: A, i: number) => Chunk<B>) => {
@@ -1974,7 +2003,8 @@ export 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"
  *
@@ -1997,8 +2027,8 @@ export const flatMap: {
  * // Index 3: 4
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const forEach: {
   /**
@@ -2011,7 +2041,8 @@ export 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"
    *
@@ -2034,8 +2065,8 @@ export 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
   /**
@@ -2048,7 +2079,8 @@ export 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"
    *
@@ -2071,8 +2103,8 @@ export 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
 } = dual(2, <A, B>(self: Chunk<A>, f: (a: A) => B): void => toReadonlyArray(self).forEach(f))
@@ -2080,7 +2112,8 @@ export const forEach: {
 /**
  * Flattens a chunk of chunks into a single chunk by concatenating all chunks.
  *
- * @example
+ * **Example** (Flattening nested chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2101,15 +2134,16 @@ export const forEach: {
  * console.log(Chunk.toArray(Chunk.flatten(withEmpty))) // [1, 2, 3, 4]
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const flatten: <S extends Chunk<Chunk<any>>>(self: S) => Chunk.Flatten<S> = flatMap(identity) as any
 
 /**
  * Groups elements in chunks of up to `n` elements.
  *
- * @example
+ * **Example** (Splitting into fixed-size chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2126,14 +2160,15 @@ export const flatten: <S extends Chunk<Chunk<any>>>(self: S) => Chunk.Flatten<S>
  * // [[1, 2], [3, 4], [5]]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const chunksOf: {
   /**
    * Groups elements in chunks of up to `n` elements.
    *
-   * @example
+   * **Example** (Splitting into fixed-size chunks)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -2150,14 +2185,15 @@ export 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"
    *
@@ -2174,8 +2210,8 @@ export 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>>
 } = dual(2, <A>(self: Chunk<A>, n: number) => {
@@ -2199,7 +2235,8 @@ export const chunksOf: {
  *
  * The order and references of result values are determined by the Chunk.
  *
- * @example
+ * **Example** (Intersecting chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2219,8 +2256,8 @@ export const chunksOf: {
  * console.log(Chunk.toArray(Chunk.intersection(chunk3, chunk4))) // []
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const intersection: {
   /**
@@ -2228,7 +2265,8 @@ export const intersection: {
    *
    * The order and references of result values are determined by the Chunk.
    *
-   * @example
+   * **Example** (Intersecting chunks)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -2248,8 +2286,8 @@ export 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>
   /**
@@ -2257,7 +2295,8 @@ export const intersection: {
    *
    * The order and references of result values are determined by the Chunk.
    *
-   * @example
+   * **Example** (Intersecting chunks)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -2277,8 +2316,8 @@ export 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>
 } = dual(
@@ -2290,7 +2329,8 @@ export const intersection: {
 /**
  * Determines if the chunk is empty.
  *
- * @example
+ * **Example** (Checking for empty chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2306,7 +2346,8 @@ export const isEmpty = <A>(self: Chunk<A>): boolean => self.length === 0
 /**
  * Determines if the chunk is not empty.
  *
- * @example
+ * **Example** (Checking for non-empty chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2322,7 +2363,8 @@ export const isNonEmpty = <A>(self: Chunk<A>): self is NonEmptyChunk<A> => self.
 /**
  * Returns the first element of this chunk if it exists.
  *
- * @example
+ * **Example** (Getting the first element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2340,9 +2382,10 @@ export const head: <A>(self: Chunk<A>) => Option<A> = get(0)
  *
  * 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
@@ -2350,23 +2393,20 @@ export const head: <A>(self: Chunk<A>) => Option<A> = get(0)
  * 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 const headUnsafe = <A>(self: Chunk<A>): A => getUnsafe(self, 0)
 
 /**
  * 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"
  *
@@ -2380,15 +2420,16 @@ export const headUnsafe = <A>(self: Chunk<A>): A => getUnsafe(self, 0)
  * // Chunk.headNonEmpty(Chunk.empty()) // TypeScript error
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const headNonEmpty: <A>(self: NonEmptyChunk<A>) => A = headUnsafe
 
 /**
  * Returns the last element of this chunk if it exists.
  *
- * @example
+ * **Example** (Getting the last element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2406,9 +2447,10 @@ export const last = <A>(self: Chunk<A>): Option<A> => get(self, self.length - 1)
  *
  * 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
@@ -2416,23 +2458,20 @@ export const last = <A>(self: Chunk<A>): Option<A> => get(self, self.length - 1)
  * 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 const lastUnsafe = <A>(self: Chunk<A>): A => getUnsafe(self, self.length - 1)
 
 /**
  * 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"
  *
@@ -2446,15 +2485,16 @@ export const lastUnsafe = <A>(self: Chunk<A>): A => getUnsafe(self, self.length
  * // Chunk.lastNonEmpty(Chunk.empty()) // TypeScript error
  * ```
  *
- * @since 3.4.0
  * @category elements
+ * @since 3.4.0
  */
 export const lastNonEmpty: <A>(self: NonEmptyChunk<A>) => A = lastUnsafe
 
 /**
  * A namespace containing utility types for Chunk operations.
  *
- * @example
+ * **Example** (Working with Chunk utility types)
+ *
  * ```ts
  * import type { Chunk } from "effect"
  *
@@ -2474,7 +2514,8 @@ export declare namespace Chunk {
   /**
    * Infers the element type of a Chunk.
    *
-   * @example
+   * **Example** (Inferring element types)
+   *
    * ```ts
    * import type { Chunk } from "effect"
    *
@@ -2493,7 +2534,8 @@ export declare namespace Chunk {
   /**
    * Constructs a Chunk type preserving non-emptiness.
    *
-   * @example
+   * **Example** (Preserving non-emptiness)
+   *
    * ```ts
    * import type { Chunk } from "effect"
    *
@@ -2512,7 +2554,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"
    *
@@ -2547,7 +2590,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"
    *
@@ -2582,7 +2626,8 @@ export declare namespace Chunk {
   /**
    * Flattens a nested Chunk type.
    *
-   * @example
+   * **Example** (Flattening nested chunk types)
+   *
    * ```ts
    * import type { Chunk } from "effect"
    *
@@ -2605,76 +2650,72 @@ 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 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>
 } = dual(2, <A, B>(self: Chunk<A>, f: (a: A, i: number) => B): Chunk<B> =>
@@ -2685,7 +2726,8 @@ export const map: {
 /**
  * Statefully maps over the chunk, producing new elements of type `B`.
  *
- * @example
+ * **Example** (Mapping with accumulated state)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2708,14 +2750,15 @@ export const map: {
  * console.log(Chunk.toArray(indexed)) // ["0: hello", "1: world", "2: effect"]
  * ```
  *
- * @since 2.0.0
  * @category folding
+ * @since 2.0.0
  */
 export const mapAccum: {
   /**
    * Statefully maps over the chunk, producing new elements of type `B`.
    *
-   * @example
+   * **Example** (Mapping with accumulated state)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -2738,14 +2781,15 @@ export 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"
    *
@@ -2768,8 +2812,8 @@ export 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>]
 } = dual(3, <S, A, B>(self: Chunk<A>, s: S, f: (s: S, a: A) => readonly [S, B]): [S, Chunk<B>] => {
@@ -2783,7 +2827,8 @@ export const mapAccum: {
  * - Returns `[excluded, satisfying]`.
  * - The filter receives `(element, index)`.
  *
- * @example
+ * **Example** (Partitioning with a Result)
+ *
  * ```ts
  * import { Chunk, Result } from "effect"
  *
@@ -2805,7 +2850,8 @@ export const partition: {
    * - Returns `[excluded, satisfying]`.
    * - The filter receives `(element, index)`.
    *
-   * @example
+   * **Example** (Partitioning with a Result)
+   *
    * ```ts
    * import { Chunk, Result } from "effect"
    *
@@ -2827,7 +2873,8 @@ export const partition: {
    * - Returns `[excluded, satisfying]`.
    * - The filter receives `(element, index)`.
    *
-   * @example
+   * **Example** (Partitioning with a Result)
+   *
    * ```ts
    * import { Chunk, Result } from "effect"
    *
@@ -2855,9 +2902,14 @@ export const partition: {
 )
 
 /**
- * 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"
@@ -2893,7 +2945,8 @@ export const separate = <A, B>(self: Chunk<Result<B, A>>): [Chunk<A>, Chunk<B>]
 /**
  * Retrieves the size of the chunk.
  *
- * @example
+ * **Example** (Getting chunk size)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2909,7 +2962,8 @@ export const size = <A>(self: Chunk<A>): number => self.length
 /**
  * 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"
@@ -2928,14 +2982,15 @@ export const size = <A>(self: Chunk<A>): number => self.length
  * console.log(Chunk.toArray(sortedWords)) // ["apple", "banana", "cherry"]
  * ```
  *
- * @since 2.0.0
  * @category sorting
+ * @since 2.0.0
  */
 export 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"
@@ -2954,14 +3009,15 @@ export 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"
@@ -2980,8 +3036,8 @@ export 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>
 } = dual(
@@ -2992,7 +3048,8 @@ export const sort: {
 /**
  * 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"
@@ -3019,14 +3076,15 @@ export const sort: {
  * console.log(Chunk.toArray(byLength)) // ["a", "ab", "abc"]
  * ```
  *
- * @since 2.0.0
  * @category sorting
+ * @since 2.0.0
  */
 export 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"
@@ -3053,14 +3111,15 @@ export 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"
@@ -3087,8 +3146,8 @@ export 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>
 } = dual(
@@ -3099,7 +3158,8 @@ export const sortWith: {
 /**
  *  Returns two splits of this chunk at the specified index.
  *
- * @example
+ * **Example** (Splitting at an index)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3119,14 +3179,15 @@ export const sortWith: {
  * console.log(Chunk.toArray(empty2)) // []
  * ```
  *
- * @since 2.0.0
  * @category splitting
+ * @since 2.0.0
  */
 export const splitAt: {
   /**
    *  Returns two splits of this chunk at the specified index.
    *
-   * @example
+   * **Example** (Splitting at an index)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -3146,14 +3207,15 @@ export 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"
    *
@@ -3173,17 +3235,22 @@ export 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>]
 } = dual(2, <A>(self: Chunk<A>, n: number): [Chunk<A>, Chunk<A>] => [take(self, n), drop(self, n)])
 
 /**
- * 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"
  *
@@ -3206,10 +3273,15 @@ export const splitAt: {
  */
 export 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"
    *
@@ -3232,10 +3304,15 @@ export 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"
    *
@@ -3265,9 +3342,13 @@ export const splitNonEmptyAt: {
 })
 
 /**
- * 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"
  *
@@ -3288,14 +3369,18 @@ export const splitNonEmptyAt: {
  * // [[1, 2, 3, 4, 5, 6, 7, 8, 9]]
  * ```
  *
- * @since 2.0.0
  * @category splitting
+ * @since 2.0.0
  */
 export 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"
    *
@@ -3316,14 +3401,18 @@ export 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"
    *
@@ -3344,8 +3433,8 @@ export 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>>
 } = dual(2, <A>(self: Chunk<A>, n: number) => chunksOf(self, Math.ceil(self.length / Math.floor(n))))
@@ -3354,7 +3443,8 @@ export 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"
  *
@@ -3382,7 +3472,8 @@ export 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"
    *
@@ -3410,7 +3501,8 @@ export 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"
    *
@@ -3449,7 +3541,8 @@ export const splitWhere: {
 /**
  * Returns every elements after the first.
  *
- * @example
+ * **Example** (Getting the tail safely)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3463,15 +3556,16 @@ export const splitWhere: {
  * console.log(Chunk.tail(empty)) // Option.none()
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const tail = <A>(self: Chunk<A>): O.Option<Chunk<A>> => self.length > 0 ? O.some(drop(self, 1)) : O.none()
 
 /**
  * Returns every elements after the first.
  *
- * @example
+ * **Example** (Getting the tail of a non-empty chunk)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3487,15 +3581,16 @@ export const tail = <A>(self: Chunk<A>): O.Option<Chunk<A>> => self.length > 0 ?
  * // Chunk.tailNonEmpty(Chunk.empty()) // TypeScript error
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const tailNonEmpty = <A>(self: NonEmptyChunk<A>): Chunk<A> => drop(self, 1)
 
 /**
  * Takes the last `n` elements.
  *
- * @example
+ * **Example** (Taking elements from the end)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3512,14 +3607,15 @@ export const tailNonEmpty = <A>(self: NonEmptyChunk<A>): Chunk<A> => drop(self,
  * console.log(Chunk.toArray(none)) // []
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const takeRight: {
   /**
    * Takes the last `n` elements.
    *
-   * @example
+   * **Example** (Taking elements from the end)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -3536,14 +3632,15 @@ export 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"
    *
@@ -3560,8 +3657,8 @@ export 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>
 } = dual(2, <A>(self: Chunk<A>, n: number): Chunk<A> => drop(self, self.length - n))
@@ -3569,7 +3666,8 @@ export const takeRight: {
 /**
  * Takes all elements so long as the predicate returns true.
  *
- * @example
+ * **Example** (Taking elements while a predicate matches)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3587,14 +3685,15 @@ export const takeRight: {
  * console.log(Chunk.toArray(all)) // [1, 2, 3]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export 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"
    *
@@ -3612,14 +3711,15 @@ export 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"
    *
@@ -3637,14 +3737,15 @@ export 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"
    *
@@ -3662,14 +3763,15 @@ export 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"
    *
@@ -3687,8 +3789,8 @@ export 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>
 } = dual(2, <A>(self: Chunk<A>, predicate: Predicate<A>): Chunk<A> => {
@@ -3706,7 +3808,8 @@ export const takeWhile: {
 /**
  * Creates a Chunks of unique values, in order, from all given Chunks.
  *
- * @example
+ * **Example** (Unioning chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3722,14 +3825,15 @@ export const takeWhile: {
  * console.log(Chunk.toArray(unified)) // [1, 2, 3]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const union: {
   /**
    * Creates a Chunks of unique values, in order, from all given Chunks.
    *
-   * @example
+   * **Example** (Unioning chunks)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -3745,14 +3849,15 @@ export 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"
    *
@@ -3768,8 +3873,8 @@ export 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>
 } = dual(
@@ -3778,9 +3883,11 @@ export const union: {
 )
 
 /**
- * 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"
  *
@@ -3799,15 +3906,16 @@ export const union: {
  * console.log(Chunk.toArray(uniqueDeduped)) // [1, 2, 3]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const dedupe = <A>(self: Chunk<A>): Chunk<A> => fromArrayUnsafe(RA.dedupe(toReadonlyArray(self)))
 
 /**
  * Deduplicates adjacent elements that are identical.
  *
- * @example
+ * **Example** (Removing adjacent duplicates)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3821,8 +3929,8 @@ export const dedupe = <A>(self: Chunk<A>): Chunk<A> => fromArrayUnsafe(RA.dedupe
  * console.log(Chunk.toArray(mixedResult)) // ["a", "b", "a"]
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const dedupeAdjacent = <A>(self: Chunk<A>): Chunk<A> => fromArrayUnsafe(RA.dedupeAdjacent(self))
 
@@ -3831,7 +3939,8 @@ export const dedupeAdjacent = <A>(self: Chunk<A>): Chunk<A> => fromArrayUnsafe(R
  *
  * Note: The function is reverse of `zip`.
  *
- * @example
+ * **Example** (Unzipping pairs)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3851,8 +3960,8 @@ export const dedupeAdjacent = <A>(self: Chunk<A>): Chunk<A> => fromArrayUnsafe(R
  * console.log(Chunk.toArray(emptyStrs)) // []
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const unzip = <A, B>(self: Chunk<readonly [A, B]>): [Chunk<A>, Chunk<B>] => {
   const [left, right] = RA.unzip(self)
@@ -3862,7 +3971,8 @@ export 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"
  *
@@ -3878,14 +3988,15 @@ export const unzip = <A, B>(self: Chunk<readonly [A, B]>): [Chunk<A>, Chunk<B>]
  * console.log(Chunk.toArray(mixed)) // [[1, "a"], [2, "b"]]
  * ```
  *
- * @since 2.0.0
  * @category zipping
+ * @since 2.0.0
  */
 export 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"
    *
@@ -3901,14 +4012,15 @@ export 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"
    *
@@ -3924,8 +4036,8 @@ export 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>
 } = dual(
@@ -3937,7 +4049,8 @@ export const zipWith: {
 /**
  * Zips this chunk pointwise with the specified chunk.
  *
- * @example
+ * **Example** (Zipping chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -3953,14 +4066,15 @@ export const zipWith: {
  * console.log(Chunk.toArray(zipped)) // [[1, "a"], [2, "b"]]
  * ```
  *
- * @since 2.0.0
  * @category zipping
+ * @since 2.0.0
  */
 export const zip: {
   /**
    * Zips this chunk pointwise with the specified chunk.
    *
-   * @example
+   * **Example** (Zipping chunks)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -3976,14 +4090,15 @@ export 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"
    *
@@ -3999,8 +4114,8 @@ export 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]>
 } = dual(
@@ -4011,7 +4126,8 @@ export const zip: {
 /**
  * Delete the element at the specified index, creating a new `Chunk`.
  *
- * @example
+ * **Example** (Removing an element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -4035,7 +4151,8 @@ export const remove: {
   /**
    * Delete the element at the specified index, creating a new `Chunk`.
    *
-   * @example
+   * **Example** (Removing an element)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -4059,7 +4176,8 @@ export const remove: {
   /**
    * Delete the element at the specified index, creating a new `Chunk`.
    *
-   * @example
+   * **Example** (Removing an element)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -4089,7 +4207,8 @@ export 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"
  *
@@ -4114,7 +4233,8 @@ export 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"
    *
@@ -4139,7 +4259,8 @@ export 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"
    *
@@ -4170,7 +4291,8 @@ export 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"
  *
@@ -4195,7 +4317,8 @@ export 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"
    *
@@ -4220,7 +4343,8 @@ export 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"
    *
@@ -4248,13 +4372,13 @@ export 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
@@ -4266,13 +4390,13 @@ export 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
@@ -4284,13 +4408,13 @@ export 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
@@ -4300,15 +4424,19 @@ export const makeBy: {
 } = dual(2, (n, f) => fromIterable(RA.makeBy(n, f)))
 
 /**
- * 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
@@ -4324,7 +4452,8 @@ export 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"
  *
@@ -4353,7 +4482,8 @@ export 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"
    *
@@ -4382,7 +4512,8 @@ export 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"
    *
@@ -4409,7 +4540,8 @@ export 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"
  *
@@ -4445,7 +4577,8 @@ export const containsWith: <A>(
  * 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"
  *
@@ -4475,7 +4608,8 @@ export 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"
    *
@@ -4505,7 +4639,8 @@ export 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"
    *
@@ -4535,7 +4670,8 @@ export 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"
    *
@@ -4565,7 +4701,8 @@ export 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"
    *
@@ -4596,7 +4733,8 @@ export const findFirst: {
 /**
  * Return the first index for which a predicate holds.
  *
- * @example
+ * **Example** (Finding the first matching index)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -4620,7 +4758,8 @@ export const findFirstIndex: {
   /**
    * Return the first index for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the first matching index)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -4644,7 +4783,8 @@ export const findFirstIndex: {
   /**
    * Return the first index for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the first matching index)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -4673,7 +4813,8 @@ export 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"
@@ -4699,7 +4840,8 @@ export 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"
@@ -4725,7 +4867,8 @@ export 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"
@@ -4751,7 +4894,8 @@ export 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"
@@ -4777,7 +4921,8 @@ export 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"
@@ -4805,7 +4950,8 @@ export const findLast: {
 /**
  * Return the last index for which a predicate holds.
  *
- * @example
+ * **Example** (Finding the last matching index)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -4829,7 +4975,8 @@ export const findLastIndex: {
   /**
    * Return the last index for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the last matching index)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -4853,7 +5000,8 @@ export const findLastIndex: {
   /**
    * Return the last index for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the last matching index)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -4882,7 +5030,8 @@ export const findLastIndex: {
 /**
  * Check if a predicate holds true for every `Chunk` element.
  *
- * @example
+ * **Example** (Checking every element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -4909,7 +5058,8 @@ export const every: {
   /**
    * Check if a predicate holds true for every `Chunk` element.
    *
-   * @example
+   * **Example** (Checking every element)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -4936,7 +5086,8 @@ export const every: {
   /**
    * Check if a predicate holds true for every `Chunk` element.
    *
-   * @example
+   * **Example** (Checking every element)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -4963,7 +5114,8 @@ export const every: {
   /**
    * Check if a predicate holds true for every `Chunk` element.
    *
-   * @example
+   * **Example** (Checking every element)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -4990,7 +5142,8 @@ export const every: {
   /**
    * Check if a predicate holds true for every `Chunk` element.
    *
-   * @example
+   * **Example** (Checking every element)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -5023,7 +5176,8 @@ export const every: {
 /**
  * Check if a predicate holds true for some `Chunk` element.
  *
- * @example
+ * **Example** (Checking for some matching element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -5047,7 +5201,8 @@ export const some: {
   /**
    * Check if a predicate holds true for some `Chunk` element.
    *
-   * @example
+   * **Example** (Checking for some matching element)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -5071,7 +5226,8 @@ export const some: {
   /**
    * Check if a predicate holds true for some `Chunk` element.
    *
-   * @example
+   * **Example** (Checking for some matching element)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -5100,7 +5256,8 @@ export const some: {
 /**
  * Joins the elements together with "sep" in the middle.
  *
- * @example
+ * **Example** (Joining chunks into a string)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -5128,7 +5285,8 @@ export const join: {
   /**
    * Joins the elements together with "sep" in the middle.
    *
-   * @example
+   * **Example** (Joining chunks into a string)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -5156,7 +5314,8 @@ export const join: {
   /**
    * Joins the elements together with "sep" in the middle.
    *
-   * @example
+   * **Example** (Joining chunks into a string)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -5186,7 +5345,8 @@ export const join: {
 /**
  * Reduces the elements of a chunk from left to right.
  *
- * @example
+ * **Example** (Reducing from the left)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -5211,7 +5371,8 @@ export const reduce: {
   /**
    * Reduces the elements of a chunk from left to right.
    *
-   * @example
+   * **Example** (Reducing from the left)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -5236,7 +5397,8 @@ export const reduce: {
   /**
    * Reduces the elements of a chunk from left to right.
    *
-   * @example
+   * **Example** (Reducing from the left)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -5263,7 +5425,8 @@ export const reduce: {
 /**
  * Reduces the elements of a chunk from right to left.
  *
- * @example
+ * **Example** (Reducing from the right)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -5292,7 +5455,8 @@ export const reduceRight: {
   /**
    * Reduces the elements of a chunk from right to left.
    *
-   * @example
+   * **Example** (Reducing from the right)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -5321,7 +5485,8 @@ export const reduceRight: {
   /**
    * Reduces the elements of a chunk from right to left.
    *
-   * @example
+   * **Example** (Reducing from the right)
+   *
    * ```ts
    * import { Chunk } from "effect"
    *
@@ -5353,7 +5518,8 @@ export 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"
  *
@@ -5394,7 +5560,8 @@ export const differenceWith = <A>(isEquivalent: (self: A, that: A) => boolean):
  * 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"
  *
@@ -5423,7 +5590,8 @@ export 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"
    *
@@ -5452,7 +5620,8 @@ export 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"
    *