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

package/dist/Chunk.js

@@ -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
@@ -89,12 +91,13 @@ function copy(src, srcPos, dest, destPos, len) {
 }
 const emptyArray = [];
 /**
- * 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)
@@ -106,7 +109,7 @@ const emptyArray = [];
  * ```
  *
  * @category equivalence
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const makeEquivalence = isEquivalent => Equivalence.make((self, that) => self.length === that.length && toReadonlyArray(self).every((value, i) => isEquivalent(value, getUnsafe(that, i))));
 const _equivalence = /*#__PURE__*/makeEquivalence(Equal.equals);
@@ -202,7 +205,8 @@ const makeChunk = backing => {
 /**
  * Checks if `u` is a `Chunk<unknown>`
  *
- * @example
+ * **Example** (Checking for chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -224,7 +228,8 @@ const _empty = /*#__PURE__*/makeChunk({
 /**
  * Creates an empty `Chunk`.
  *
- * @example
+ * **Example** (Creating an empty chunk)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -239,13 +244,13 @@ export const empty = () => _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
@@ -255,13 +260,13 @@ export const make = (...as) => fromNonEmptyArrayUnsafe(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
@@ -274,13 +279,13 @@ export const of = a => makeChunk({
 /**
  * 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
@@ -324,7 +329,8 @@ const toArray_ = self => 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"
  *
@@ -338,7 +344,7 @@ const toArray_ = self => toReadonlyArray(self).slice();
  * console.log(Chunk.toArray(emptyChunk)) // []
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 export const toArray = toArray_;
@@ -372,7 +378,8 @@ const toReadonlyArray_ = self => {
  * 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"
  *
@@ -388,7 +395,7 @@ const toReadonlyArray_ = self => {
  * console.log(Chunk.toReadonlyArray(emptyChunk)) // []
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 export const toReadonlyArray = toReadonlyArray_;
@@ -420,7 +427,7 @@ const reverseChunk = self => {
  * 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"
@@ -428,18 +435,18 @@ const reverseChunk = self => {
  * 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 = reverseChunk;
 /**
  * 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"
  *
@@ -461,7 +468,8 @@ export const get = /*#__PURE__*/dual(2, (self, index) => index < 0 || index >= s
 /**
  * Wraps an array into a chunk without copying, unsafe on mutable arrays
  *
- * @example
+ * **Example** (Creating chunks without copying arrays)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -474,8 +482,8 @@ export const get = /*#__PURE__*/dual(2, (self, index) => index < 0 || index >= s
  * console.log(Chunk.toArray(chunk)) // [999, 2, 3, 4, 5]
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 4.0.0
  */
 export const fromArrayUnsafe = self => self.length === 0 ? empty() : self.length === 1 ? of(self[0]) : makeChunk({
   _tag: "IArray",
@@ -484,10 +492,10 @@ export const fromArrayUnsafe = self => self.length === 0 ? empty() : self.length
 /**
  * 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)
@@ -497,32 +505,29 @@ export const fromArrayUnsafe = self => self.length === 0 ? empty() : self.length
  * console.log(Chunk.isNonEmpty(chunk)) // true
  * ```
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 4.0.0
  */
 export const fromNonEmptyArrayUnsafe = self => fromArrayUnsafe(self);
 /**
  * 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 const getUnsafe = /*#__PURE__*/dual(2, (self, index) => {
   const i = Math.floor(index);
@@ -558,7 +563,8 @@ export const getUnsafe = /*#__PURE__*/dual(2, (self, index) => {
 /**
  * Appends the specified element to the end of the `Chunk`.
  *
- * @example
+ * **Example** (Appending an element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -579,7 +585,8 @@ export const append = /*#__PURE__*/dual(2, (self, a) => appendAll(self, of(a)));
 /**
  * Prepend an element to the front of a `Chunk`, creating a new `NonEmptyChunk`.
  *
- * @example
+ * **Example** (Prepending an element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -600,14 +607,14 @@ export const prepend = /*#__PURE__*/dual(2, (self, elem) => appendAll(of(elem),
 /**
  * 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
@@ -655,14 +662,14 @@ export const take = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * 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
@@ -710,14 +717,14 @@ export const drop = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * 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
@@ -727,14 +734,14 @@ export const dropRight = /*#__PURE__*/dual(2, (self, n) => take(self, Math.max(0
 /**
  * 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
@@ -753,7 +760,7 @@ export const dropWhile = /*#__PURE__*/dual(2, (self, predicate) => {
  * 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"
@@ -775,7 +782,7 @@ export const prependAll = /*#__PURE__*/dual(2, (self, that) => appendAll(that, s
  * 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"
@@ -879,10 +886,10 @@ export const appendAll = /*#__PURE__*/dual(2, (self, that) => {
 /**
  * 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) => {
@@ -899,8 +906,8 @@ export const appendAll = /*#__PURE__*/dual(2, (self, that) => {
  * console.log(Chunk.toArray(evenIndexNumbers)) // [1]
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const filterMap = /*#__PURE__*/dual(2, (self, f) => {
   const as = RA.fromIterable(self);
@@ -916,7 +923,8 @@ export const filterMap = /*#__PURE__*/dual(2, (self, f) => {
 /**
  * Returns a filtered subset of the elements.
  *
- * @example
+ * **Example** (Filtering values)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -930,17 +938,17 @@ export const filterMap = /*#__PURE__*/dual(2, (self, f) => {
  * console.log(Chunk.toArray(numbers)) // [42, 100]
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const filter = /*#__PURE__*/dual(2, (self, predicate) => fromArrayUnsafe(RA.filter(self, predicate)));
 /**
  * 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) => {
@@ -958,8 +966,8 @@ export const filter = /*#__PURE__*/dual(2, (self, predicate) => fromArrayUnsafe(
  * console.log(Chunk.toArray(allNumbers)) // [1, 2, 3, 4]
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const filterMapWhile = /*#__PURE__*/dual(2, (self, f) => {
   const out = [];
@@ -976,15 +984,14 @@ export const filterMapWhile = /*#__PURE__*/dual(2, (self, f) => {
 /**
  * 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
@@ -1002,7 +1009,8 @@ export const compact = self => {
 /**
  * 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"
  *
@@ -1023,8 +1031,8 @@ export const compact = self => {
  * console.log(Chunk.toArray(indexed)) // [1, 3, 5]
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const flatMap = /*#__PURE__*/dual(2, (self, f) => {
   if (self.backing._tag === "ISingleton") {
@@ -1047,7 +1055,8 @@ export const flatMap = /*#__PURE__*/dual(2, (self, f) => {
  * 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"
  *
@@ -1070,14 +1079,15 @@ export const flatMap = /*#__PURE__*/dual(2, (self, f) => {
  * // Index 3: 4
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const forEach = /*#__PURE__*/dual(2, (self, f) => toReadonlyArray(self).forEach(f));
 /**
  * Flattens a chunk of chunks into a single chunk by concatenating all chunks.
  *
- * @example
+ * **Example** (Flattening nested chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1098,14 +1108,15 @@ export const forEach = /*#__PURE__*/dual(2, (self, f) => toReadonlyArray(self).f
  * console.log(Chunk.toArray(Chunk.flatten(withEmpty))) // [1, 2, 3, 4]
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const flatten = /*#__PURE__*/flatMap(identity);
 /**
  * Groups elements in chunks of up to `n` elements.
  *
- * @example
+ * **Example** (Splitting into fixed-size chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1122,8 +1133,8 @@ export const flatten = /*#__PURE__*/flatMap(identity);
  * // [[1, 2], [3, 4], [5]]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const chunksOf = /*#__PURE__*/dual(2, (self, n) => {
   const gr = [];
@@ -1145,7 +1156,8 @@ export const chunksOf = /*#__PURE__*/dual(2, (self, n) => {
  *
  * The order and references of result values are determined by the Chunk.
  *
- * @example
+ * **Example** (Intersecting chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1165,14 +1177,15 @@ export const chunksOf = /*#__PURE__*/dual(2, (self, n) => {
  * console.log(Chunk.toArray(Chunk.intersection(chunk3, chunk4))) // []
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const intersection = /*#__PURE__*/dual(2, (self, that) => fromArrayUnsafe(RA.intersection(toReadonlyArray(self), toReadonlyArray(that))));
 /**
  * Determines if the chunk is empty.
  *
- * @example
+ * **Example** (Checking for empty chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1187,7 +1200,8 @@ export const isEmpty = self => self.length === 0;
 /**
  * Determines if the chunk is not empty.
  *
- * @example
+ * **Example** (Checking for non-empty chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1202,7 +1216,8 @@ export const isNonEmpty = self => self.length > 0;
 /**
  * Returns the first element of this chunk if it exists.
  *
- * @example
+ * **Example** (Getting the first element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1219,9 +1234,10 @@ export const head = /*#__PURE__*/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
@@ -1229,22 +1245,19 @@ export const head = /*#__PURE__*/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 4.0.0
  */
 export const headUnsafe = self => 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"
  *
@@ -1258,14 +1271,15 @@ export const headUnsafe = self => getUnsafe(self, 0);
  * // Chunk.headNonEmpty(Chunk.empty()) // TypeScript error
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const headNonEmpty = headUnsafe;
 /**
  * Returns the last element of this chunk if it exists.
  *
- * @example
+ * **Example** (Getting the last element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1282,9 +1296,10 @@ export const last = self => 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
@@ -1292,22 +1307,19 @@ export const last = self => 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 4.0.0
  */
 export const lastUnsafe = self => 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"
  *
@@ -1321,33 +1333,33 @@ export const lastUnsafe = self => getUnsafe(self, self.length - 1);
  * // Chunk.lastNonEmpty(Chunk.empty()) // TypeScript error
  * ```
  *
- * @since 3.4.0
  * @category elements
+ * @since 3.4.0
  */
 export const lastNonEmpty = lastUnsafe;
 /**
  * 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 = /*#__PURE__*/dual(2, (self, f) => self.backing._tag === "ISingleton" ? of(f(self.backing.a, 0)) : fromArrayUnsafe(pipe(toReadonlyArray(self), RA.map((a, i) => f(a, i)))));
 /**
  * Statefully maps over the chunk, producing new elements of type `B`.
  *
- * @example
+ * **Example** (Mapping with accumulated state)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1370,8 +1382,8 @@ export const map = /*#__PURE__*/dual(2, (self, f) => self.backing._tag === "ISin
  * console.log(Chunk.toArray(indexed)) // ["0: hello", "1: world", "2: effect"]
  * ```
  *
- * @since 2.0.0
  * @category folding
+ * @since 2.0.0
  */
 export const mapAccum = /*#__PURE__*/dual(3, (self, s, f) => {
   const [s1, as] = RA.mapAccum(self, s, f);
@@ -1383,7 +1395,8 @@ export const mapAccum = /*#__PURE__*/dual(3, (self, s, f) => {
  * - Returns `[excluded, satisfying]`.
  * - The filter receives `(element, index)`.
  *
- * @example
+ * **Example** (Partitioning with a Result)
+ *
  * ```ts
  * import { Chunk, Result } from "effect"
  *
@@ -1403,12 +1416,16 @@ export const partition = /*#__PURE__*/dual(2, (self, f) => {
   return [fromArrayUnsafe(excluded), fromArrayUnsafe(satisfying)];
 });
 /**
- * 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),
@@ -1436,7 +1453,8 @@ export const separate = self => pipe(RA.separate(toReadonlyArray(self)), ([l, r]
 /**
  * Retrieves the size of the chunk.
  *
- * @example
+ * **Example** (Getting chunk size)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1451,10 +1469,10 @@ export const size = self => 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"
+ * import { Chunk, Order } from "effect"
  *
  * const numbers = Chunk.make(3, 1, 4, 1, 5, 9, 2, 6)
  * const sorted = Chunk.sort(numbers, Order.Number)
@@ -1470,17 +1488,17 @@ export const size = self => self.length;
  * console.log(Chunk.toArray(sortedWords)) // ["apple", "banana", "cherry"]
  * ```
  *
- * @since 2.0.0
  * @category sorting
+ * @since 2.0.0
  */
 export const sort = /*#__PURE__*/dual(2, (self, O) => fromArrayUnsafe(RA.sort(toReadonlyArray(self), O)));
 /**
  * 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 },
@@ -1504,14 +1522,15 @@ export const sort = /*#__PURE__*/dual(2, (self, O) => fromArrayUnsafe(RA.sort(to
  * console.log(Chunk.toArray(byLength)) // ["a", "ab", "abc"]
  * ```
  *
- * @since 2.0.0
  * @category sorting
+ * @since 2.0.0
  */
 export const sortWith = /*#__PURE__*/dual(3, (self, f, order) => sort(self, Order.mapInput(order, f)));
 /**
  *  Returns two splits of this chunk at the specified index.
  *
- * @example
+ * **Example** (Splitting at an index)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1531,15 +1550,20 @@ export const sortWith = /*#__PURE__*/dual(3, (self, f, order) => sort(self, Orde
  * console.log(Chunk.toArray(empty2)) // []
  * ```
  *
- * @since 2.0.0
  * @category splitting
+ * @since 2.0.0
  */
 export const splitAt = /*#__PURE__*/dual(2, (self, n) => [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"
  *
@@ -1565,9 +1589,13 @@ export const splitNonEmptyAt = /*#__PURE__*/dual(2, (self, n) => {
   return _n >= self.length ? [self, empty()] : [take(self, _n), drop(self, _n)];
 });
 /**
- * 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"
  *
@@ -1588,15 +1616,16 @@ export const splitNonEmptyAt = /*#__PURE__*/dual(2, (self, n) => {
  * // [[1, 2, 3, 4, 5, 6, 7, 8, 9]]
  * ```
  *
- * @since 2.0.0
  * @category splitting
+ * @since 2.0.0
  */
 export const split = /*#__PURE__*/dual(2, (self, n) => chunksOf(self, Math.ceil(self.length / Math.floor(n))));
 /**
  * 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"
  *
@@ -1633,7 +1662,8 @@ export const splitWhere = /*#__PURE__*/dual(2, (self, predicate) => {
 /**
  * Returns every elements after the first.
  *
- * @example
+ * **Example** (Getting the tail safely)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1647,14 +1677,15 @@ export const splitWhere = /*#__PURE__*/dual(2, (self, predicate) => {
  * console.log(Chunk.tail(empty)) // Option.none()
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const tail = self => 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"
  *
@@ -1670,14 +1701,15 @@ export const tail = self => self.length > 0 ? O.some(drop(self, 1)) : O.none();
  * // Chunk.tailNonEmpty(Chunk.empty()) // TypeScript error
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const tailNonEmpty = self => drop(self, 1);
 /**
  * Takes the last `n` elements.
  *
- * @example
+ * **Example** (Taking elements from the end)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1694,14 +1726,15 @@ export const tailNonEmpty = self => drop(self, 1);
  * console.log(Chunk.toArray(none)) // []
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const takeRight = /*#__PURE__*/dual(2, (self, n) => drop(self, self.length - n));
 /**
  * Takes all elements so long as the predicate returns true.
  *
- * @example
+ * **Example** (Taking elements while a predicate matches)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1719,8 +1752,8 @@ export const takeRight = /*#__PURE__*/dual(2, (self, n) => drop(self, self.lengt
  * console.log(Chunk.toArray(all)) // [1, 2, 3]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const takeWhile = /*#__PURE__*/dual(2, (self, predicate) => {
   const out = [];
@@ -1736,7 +1769,8 @@ export const takeWhile = /*#__PURE__*/dual(2, (self, predicate) => {
 /**
  * Creates a Chunks of unique values, in order, from all given Chunks.
  *
- * @example
+ * **Example** (Unioning chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1752,14 +1786,16 @@ export const takeWhile = /*#__PURE__*/dual(2, (self, predicate) => {
  * console.log(Chunk.toArray(unified)) // [1, 2, 3]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const union = /*#__PURE__*/dual(2, (self, that) => fromArrayUnsafe(RA.union(toReadonlyArray(self), toReadonlyArray(that))));
 /**
- * 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"
  *
@@ -1778,14 +1814,15 @@ export const union = /*#__PURE__*/dual(2, (self, that) => fromArrayUnsafe(RA.uni
  * console.log(Chunk.toArray(uniqueDeduped)) // [1, 2, 3]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const dedupe = self => fromArrayUnsafe(RA.dedupe(toReadonlyArray(self)));
 /**
  * Deduplicates adjacent elements that are identical.
  *
- * @example
+ * **Example** (Removing adjacent duplicates)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1799,8 +1836,8 @@ export const dedupe = self => fromArrayUnsafe(RA.dedupe(toReadonlyArray(self)));
  * console.log(Chunk.toArray(mixedResult)) // ["a", "b", "a"]
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const dedupeAdjacent = self => fromArrayUnsafe(RA.dedupeAdjacent(self));
 /**
@@ -1808,7 +1845,8 @@ export const dedupeAdjacent = self => fromArrayUnsafe(RA.dedupeAdjacent(self));
  *
  * Note: The function is reverse of `zip`.
  *
- * @example
+ * **Example** (Unzipping pairs)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1828,8 +1866,8 @@ export const dedupeAdjacent = self => fromArrayUnsafe(RA.dedupeAdjacent(self));
  * console.log(Chunk.toArray(emptyStrs)) // []
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const unzip = self => {
   const [left, right] = RA.unzip(self);
@@ -1838,7 +1876,8 @@ export const unzip = self => {
 /**
  * Zips this chunk pointwise with the specified chunk using the specified combiner.
  *
- * @example
+ * **Example** (Zipping chunks with a function)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1854,14 +1893,15 @@ export const unzip = self => {
  * console.log(Chunk.toArray(mixed)) // [[1, "a"], [2, "b"]]
  * ```
  *
- * @since 2.0.0
  * @category zipping
+ * @since 2.0.0
  */
 export const zipWith = /*#__PURE__*/dual(3, (self, that, f) => fromArrayUnsafe(RA.zipWith(self, that, f)));
 /**
  * Zips this chunk pointwise with the specified chunk.
  *
- * @example
+ * **Example** (Zipping chunks)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1877,14 +1917,15 @@ export const zipWith = /*#__PURE__*/dual(3, (self, that, f) => fromArrayUnsafe(R
  * console.log(Chunk.toArray(zipped)) // [[1, "a"], [2, "b"]]
  * ```
  *
- * @since 2.0.0
  * @category zipping
+ * @since 2.0.0
  */
 export const zip = /*#__PURE__*/dual(2, (self, that) => zipWith(self, that, (a, b) => [a, b]));
 /**
  * Delete the element at the specified index, creating a new `Chunk`.
  *
- * @example
+ * **Example** (Removing an element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -1909,7 +1950,8 @@ export const remove = /*#__PURE__*/dual(2, (self, i) => fromArrayUnsafe(RA.remov
  * 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"
  *
@@ -1934,7 +1976,8 @@ export const modify = /*#__PURE__*/dual(3, (self, i, f) => pipe(RA.modify(toRead
  * 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"
  *
@@ -1960,13 +2003,13 @@ export const replace = /*#__PURE__*/dual(3, (self, i, b) => modify(self, i, () =
  *
  * **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
@@ -1974,15 +2017,19 @@ export const replace = /*#__PURE__*/dual(3, (self, i, b) => modify(self, i, () =
  */
 export const makeBy = /*#__PURE__*/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
@@ -1995,7 +2042,8 @@ export const range = (start, end) => start <= end ? makeBy(end - start + 1, i =>
 /**
  * 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"
  *
@@ -2020,7 +2068,8 @@ export const contains = RA.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"
  *
@@ -2050,7 +2099,8 @@ export const containsWith = RA.containsWith;
  * 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"
  *
@@ -2079,7 +2129,8 @@ export const findFirst = RA.findFirst;
 /**
  * Return the first index for which a predicate holds.
  *
- * @example
+ * **Example** (Finding the first matching index)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2103,10 +2154,10 @@ export const findFirstIndex = /*#__PURE__*/dual(2, (self, predicate) => RA.findF
 /**
  * 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)
@@ -2129,7 +2180,8 @@ export const findLast = RA.findLast;
 /**
  * Return the last index for which a predicate holds.
  *
- * @example
+ * **Example** (Finding the last matching index)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2153,7 +2205,8 @@ export const findLastIndex = /*#__PURE__*/dual(2, (self, predicate) => RA.findLa
 /**
  * Check if a predicate holds true for every `Chunk` element.
  *
- * @example
+ * **Example** (Checking every element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2180,7 +2233,8 @@ export const every = /*#__PURE__*/dual(2, (self, refinement) => RA.fromIterable(
 /**
  * Check if a predicate holds true for some `Chunk` element.
  *
- * @example
+ * **Example** (Checking for some matching element)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2204,7 +2258,8 @@ export const some = /*#__PURE__*/dual(2, (self, predicate) => RA.fromIterable(se
 /**
  * Joins the elements together with "sep" in the middle.
  *
- * @example
+ * **Example** (Joining chunks into a string)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2232,7 +2287,8 @@ export const join = RA.join;
 /**
  * Reduces the elements of a chunk from left to right.
  *
- * @example
+ * **Example** (Reducing from the left)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2257,7 +2313,8 @@ export const reduce = RA.reduce;
 /**
  * Reduces the elements of a chunk from right to left.
  *
- * @example
+ * **Example** (Reducing from the right)
+ *
  * ```ts
  * import { Chunk } from "effect"
  *
@@ -2287,7 +2344,8 @@ export const reduceRight = RA.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"
  *
@@ -2321,7 +2379,8 @@ export const differenceWith = isEquivalent => {
  * 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"
  *