effect 3.2.3 → 3.2.4

package/dist/cjs/Array.js

@@ -51,6 +51,12 @@ function _interopRequireWildcard(e, r) {
 /**
  * Builds a `NonEmptyArray` from an non-empty collection of elements.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const result = Array.make(1, 2, 3)
+ * assert.deepStrictEqual(result, [1, 2, 3])
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -58,6 +64,12 @@ const make = (...elements) => elements;
 /**
  * Creates a new `Array` of the specified length.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const result = Array.allocate<number>(3)
+ * assert.deepStrictEqual(result.length, 3)
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -104,9 +116,9 @@ const range = (start, end) => start <= end ? makeBy(end - start + 1, i => start
  * **Note**. `n` is normalized to an integer >= 1.
  *
  * @example
- * import { replicate } from "effect/Array"
+ * import { Array } from "effect"
  *
- * assert.deepStrictEqual(replicate("a", 3), ["a", "a", "a"])
+ * assert.deepStrictEqual(Array.replicate("a", 3), ["a", "a", "a"])
  *
  * @category constructors
  * @since 2.0.0
@@ -115,6 +127,15 @@ exports.range = range;
 const replicate = exports.replicate = /*#__PURE__*/(0, _Function.dual)(2, (a, n) => makeBy(n, () => a));
 /**
  * Creates a new `Array` from an iterable collection of values.
+ * If the input is already an array, it returns the input as-is.
+ * Otherwise, it converts the iterable collection to an array.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const set = new Set([1, 2, 3])
+ * const result = Array.fromIterable(set)
+ * assert.deepStrictEqual(result, [1, 2, 3])
  *
  * @category constructors
  * @since 2.0.0
@@ -126,10 +147,10 @@ const fromIterable = collection => Array.isArray(collection) ? collection : Arra
  * @param self - The record to transform.
  *
  * @example
- * import { fromRecord } from "effect/Array"
+ * import { Array } from "effect"
  *
  * const x = { a: 1, b: 2, c: 3 }
- * assert.deepStrictEqual(fromRecord(x), [["a", 1], ["b", 2], ["c", 3]])
+ * assert.deepStrictEqual(Array.fromRecord(x), [["a", 1], ["b", 2], ["c", 3]])
  *
  * @category conversions
  * @since 2.0.0
@@ -137,11 +158,31 @@ const fromIterable = collection => Array.isArray(collection) ? collection : Arra
 exports.fromIterable = fromIterable;
 const fromRecord = exports.fromRecord = Record.toEntries;
 /**
+ * Converts an `Option` to an array.
+ *
+ * @example
+ * import { Array, Option } from "effect"
+ *
+ * assert.deepStrictEqual(Array.fromOption(Option.some(1)), [1])
+ * assert.deepStrictEqual(Array.fromOption(Option.none()), [])
+ *
  * @category conversions
  * @since 2.0.0
  */
 const fromOption = exports.fromOption = O.toArray;
 /**
+ * Matches the elements of an array, applying functions to cases of empty and non-empty arrays.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const match = Array.match({
+ *   onEmpty: () => "empty",
+ *   onNonEmpty: ([head, ...tail]) => `head: ${head}, tail: ${tail.length}`
+ * })
+ * assert.deepStrictEqual(match([]), "empty")
+ * assert.deepStrictEqual(match([1, 2, 3]), "head: 1, tail: 2")
+ *
  * @category pattern matching
  * @since 2.0.0
  */
@@ -150,6 +191,18 @@ const match = exports.match = /*#__PURE__*/(0, _Function.dual)(2, (self, {
   onNonEmpty
 }) => isNonEmptyReadonlyArray(self) ? onNonEmpty(self) : onEmpty());
 /**
+ * Matches the elements of an array from the left, applying functions to cases of empty and non-empty arrays.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const matchLeft = Array.matchLeft({
+ *   onEmpty: () => "empty",
+ *   onNonEmpty: (head, tail) => `head: ${head}, tail: ${tail.length}`
+ * })
+ * assert.deepStrictEqual(matchLeft([]), "empty")
+ * assert.deepStrictEqual(matchLeft([1, 2, 3]), "head: 1, tail: 2")
+ *
  * @category pattern matching
  * @since 2.0.0
  */
@@ -158,6 +211,18 @@ const matchLeft = exports.matchLeft = /*#__PURE__*/(0, _Function.dual)(2, (self,
   onNonEmpty
 }) => isNonEmptyReadonlyArray(self) ? onNonEmpty(headNonEmpty(self), tailNonEmpty(self)) : onEmpty());
 /**
+ * Matches the elements of an array from the right, applying functions to cases of empty and non-empty arrays.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const matchRight = Array.matchRight({
+ *   onEmpty: () => "empty",
+ *   onNonEmpty: (init, last) => `init: ${init.length}, last: ${last}`
+ * })
+ * assert.deepStrictEqual(matchRight([]), "empty")
+ * assert.deepStrictEqual(matchRight([1, 2, 3]), "init: 2, last: 3")
+ *
  * @category pattern matching
  * @since 2.0.0
  */
@@ -168,6 +233,13 @@ const matchRight = exports.matchRight = /*#__PURE__*/(0, _Function.dual)(2, (sel
 /**
  * Prepend an element to the front of an `Iterable`, creating a new `NonEmptyArray`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const original = [2, 3, 4];
+ * const result = Array.prepend(original, 1);
+ * assert.deepStrictEqual(result, [1, 2, 3, 4]);
+ *
  * @category concatenating
  * @since 2.0.0
  */
@@ -179,10 +251,10 @@ const prepend = exports.prepend = /*#__PURE__*/(0, _Function.dual)(2, (self, hea
  * @example
  * import { Array } from "effect"
  *
- * assert.deepStrictEqual(
- *   Array.prependAll([1, 2], ["a", "b"]),
- *   ["a", "b", 1, 2]
- * )
+ * const prefix = [0, 1];
+ * const array = [2, 3];
+ * const result = Array.prependAll(array, prefix);
+ * assert.deepStrictEqual(result, [0, 1, 2, 3]);
  *
  * @category concatenating
  * @since 2.0.0
@@ -191,6 +263,13 @@ const prependAll = exports.prependAll = /*#__PURE__*/(0, _Function.dual)(2, (sel
 /**
  * Append an element to the end of an `Iterable`, creating a new `NonEmptyArray`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const original = [1, 2, 3];
+ * const result = Array.append(original, 4);
+ * assert.deepStrictEqual(result, [1, 2, 3, 4]);
+ *
  * @category concatenating
  * @since 2.0.0
  */
@@ -204,7 +283,22 @@ const append = exports.append = /*#__PURE__*/(0, _Function.dual)(2, (self, last)
  */
 const appendAll = exports.appendAll = /*#__PURE__*/(0, _Function.dual)(2, (self, that) => fromIterable(self).concat(fromIterable(that)));
 /**
- * Reduce an `Iterable` from the left, keeping all intermediate results instead of only the final result.
+ * Accumulates values from an `Iterable` starting from the left, storing
+ * each intermediate result in an array. Useful for tracking the progression of
+ * a value through a series of transformations.
+ *
+ * @example
+ * import { Array } from "effect";
+ *
+ * const numbers = [1, 2, 3, 4]
+ * const result = Array.scan(numbers, 0, (acc, value) => acc + value)
+ * assert.deepStrictEqual(result, [0, 1, 3, 6, 10])
+ *
+ * // Explanation:
+ * // This function starts with the initial value (0 in this case)
+ * // and adds each element of the array to this accumulator one by one,
+ * // keeping track of the cumulative sum after each addition.
+ * // Each of these sums is captured in the resulting array.
  *
  * @category folding
  * @since 2.0.0
@@ -219,7 +313,16 @@ const scan = exports.scan = /*#__PURE__*/(0, _Function.dual)(3, (self, b, f) =>
   return out;
 });
 /**
- * Reduce an `Iterable` from the right, keeping all intermediate results instead of only the final result.
+ * Accumulates values from an `Iterable` starting from the right, storing
+ * each intermediate result in an array. Useful for tracking the progression of
+ * a value through a series of transformations.
+ *
+ * @example
+ * import { Array } from "effect";
+ *
+ * const numbers = [1, 2, 3, 4]
+ * const result = Array.scanRight(numbers, 0, (acc, value) => acc + value)
+ * assert.deepStrictEqual(result, [10, 9, 7, 4, 0])
  *
  * @category folding
  * @since 2.0.0
@@ -349,6 +452,12 @@ const unsafeGet = exports.unsafeGet = /*#__PURE__*/(0, _Function.dual)(2, (self,
 /**
  * Return a tuple containing the first element, and a new `Array` of the remaining elements, if any.
  *
+ * @example
+ * import { Array } from "effect";
+ *
+ * const result = Array.unprepend([1, 2, 3, 4])
+ * assert.deepStrictEqual(result, [1, [2, 3, 4]])
+ *
  * @category splitting
  * @since 2.0.0
  */
@@ -356,6 +465,12 @@ const unprepend = self => [headNonEmpty(self), tailNonEmpty(self)];
 /**
  * Return a tuple containing a copy of the `NonEmptyReadonlyArray` without its last element, and that last element.
  *
+ * @example
+ * import { Array } from "effect";
+ *
+ * const result = Array.unappend([1, 2, 3, 4])
+ * assert.deepStrictEqual(result, [[1, 2, 3], 4])
+ *
  * @category splitting
  * @since 2.0.0
  */
@@ -370,6 +485,14 @@ const unappend = self => [initNonEmpty(self), lastNonEmpty(self)];
 exports.unappend = unappend;
 const head = exports.head = /*#__PURE__*/get(0);
 /**
+ * Get the first element of a non empty array.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const result = Array.headNonEmpty([1, 2, 3, 4])
+ * assert.deepStrictEqual(result, 1)
+ *
  * @category getters
  * @since 2.0.0
  */
@@ -382,6 +505,14 @@ const headNonEmpty = exports.headNonEmpty = /*#__PURE__*/unsafeGet(0);
  */
 const last = self => isNonEmptyReadonlyArray(self) ? O.some(lastNonEmpty(self)) : O.none();
 /**
+ * Get the last element of a non empty array.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const result = Array.lastNonEmpty([1, 2, 3, 4])
+ * assert.deepStrictEqual(result, 4)
+ *
  * @category getters
  * @since 2.0.0
  */
@@ -399,6 +530,14 @@ const tail = self => {
   return isNonEmptyReadonlyArray(input) ? O.some(tailNonEmpty(input)) : O.none();
 };
 /**
+ * Get all but the first element of a `NonEmptyReadonlyArray`.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const result = Array.tailNonEmpty([1, 2, 3, 4])
+ * assert.deepStrictEqual(result, [2, 3, 4])
+ *
  * @category getters
  * @since 2.0.0
  */
@@ -418,6 +557,12 @@ const init = self => {
 /**
  * Get all but the last element of a non empty array, creating a new array.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const result = Array.initNonEmpty([1, 2, 3, 4])
+ * assert.deepStrictEqual(result, [1, 2, 3])
+ *
  * @category getters
  * @since 2.0.0
  */
@@ -428,6 +573,13 @@ const initNonEmpty = self => self.slice(0, -1);
  *
  * **Note**. `n` is normalized to a non negative integer.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4, 5]
+ * const result = Array.take(numbers, 3)
+ * assert.deepStrictEqual(result, [1, 2, 3])
+ *
  * @category getters
  * @since 2.0.0
  */
@@ -441,6 +593,13 @@ const take = exports.take = /*#__PURE__*/(0, _Function.dual)(2, (self, n) => {
  *
  * **Note**. `n` is normalized to a non negative integer.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4, 5]
+ * const result = Array.takeRight(numbers, 3)
+ * assert.deepStrictEqual(result, [3, 4, 5])
+ *
  * @category getters
  * @since 2.0.0
  */
@@ -452,6 +611,19 @@ const takeRight = exports.takeRight = /*#__PURE__*/(0, _Function.dual)(2, (self,
 /**
  * Calculate the longest initial subarray for which all element satisfy the specified predicate, creating a new `Array`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 3, 2, 4, 1, 2]
+ * const result = Array.takeWhile(numbers, x => x < 4)
+ * assert.deepStrictEqual(result, [1, 3, 2])
+ *
+ * // Explanation:
+ * // - The function starts with the first element (`1`), which is less than `4`, so it adds `1` to the result.
+ * // - The next element (`3`) is also less than `4`, so it adds `3`.
+ * // - The next element (`2`) is again less than `4`, so it adds `2`.
+ * // - The function then encounters `4`, which is not less than `4`. At this point, it stops checking further elements and finalizes the result.
+ *
  * @category getters
  * @since 2.0.0
  */
@@ -492,6 +664,13 @@ const span = exports.span = /*#__PURE__*/(0, _Function.dual)(2, (self, predicate
  *
  * **Note**. `n` is normalized to a non negative integer.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4, 5]
+ * const result = Array.drop(numbers, 2)
+ * assert.deepStrictEqual(result, [3, 4, 5])
+ *
  * @category getters
  * @since 2.0.0
  */
@@ -504,6 +683,13 @@ const drop = exports.drop = /*#__PURE__*/(0, _Function.dual)(2, (self, n) => {
  *
  * **Note**. `n` is normalized to a non negative integer.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4, 5]
+ * const result = Array.dropRight(numbers, 2)
+ * assert.deepStrictEqual(result, [1, 2, 3])
+ *
  * @category getters
  * @since 2.0.0
  */
@@ -514,6 +700,13 @@ const dropRight = exports.dropRight = /*#__PURE__*/(0, _Function.dual)(2, (self,
 /**
  * Remove the longest initial subarray for which all element satisfy the specified predicate, creating a new `Array`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4, 5]
+ * const result = Array.dropWhile(numbers, x => x < 4)
+ * assert.deepStrictEqual(result, [4, 5])
+ *
  * @category getters
  * @since 2.0.0
  */
@@ -521,6 +714,13 @@ const dropWhile = exports.dropWhile = /*#__PURE__*/(0, _Function.dual)(2, (self,
 /**
  * Return the first index for which a predicate holds.
  *
+ * @example
+ * import { Array, Option } from "effect"
+ *
+ * const numbers = [5, 3, 8, 9]
+ * const result = Array.findFirstIndex(numbers, x => x > 5)
+ * assert.deepStrictEqual(result, Option.some(2))
+ *
  * @category elements
  * @since 2.0.0
  */
@@ -537,6 +737,13 @@ const findFirstIndex = exports.findFirstIndex = /*#__PURE__*/(0, _Function.dual)
 /**
  * Return the last index for which a predicate holds.
  *
+ * @example
+ * import { Array, Option } from "effect"
+ *
+ * const numbers = [1, 3, 8, 9]
+ * const result = Array.findLastIndex(numbers, x => x < 5)
+ * assert.deepStrictEqual(result, Option.some(1))
+ *
  * @category elements
  * @since 2.0.0
  */
@@ -553,12 +760,27 @@ const findLastIndex = exports.findLastIndex = /*#__PURE__*/(0, _Function.dual)(2
  * Returns the first element that satisfies the specified
  * predicate, or `None` if no such element exists.
  *
+ * @example
+ * import { Array, Option } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4, 5]
+ * const result = Array.findFirst(numbers, x => x > 3)
+ * assert.deepStrictEqual(result, Option.some(4))
+ *
  * @category elements
  * @since 2.0.0
  */
 const findFirst = exports.findFirst = EffectIterable.findFirst;
 /**
- * Find the last element for which a predicate holds.
+ * Finds the last element in an iterable collection that satisfies the given predicate or refinement.
+ * Returns an `Option` containing the found element, or `Option.none` if no element matches.
+ *
+ * @example
+ * import { Array, Option } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4, 5]
+ * const result = Array.findLast(numbers, n => n % 2 === 0)
+ * assert.deepStrictEqual(result, Option.some(4))
  *
  * @category elements
  * @since 2.0.0
@@ -584,6 +806,13 @@ const findLast = exports.findLast = /*#__PURE__*/(0, _Function.dual)(2, (self, f
  * Insert an element at the specified index, creating a new `NonEmptyArray`,
  * or return `None` if the index is out of bounds.
  *
+ * @example
+ * import { Array, Option } from "effect"
+ *
+ * const letters = ['a', 'b', 'c', 'e']
+ * const result = Array.insertAt(letters, 3, 'd')
+ * assert.deepStrictEqual(result, Option.some(['a', 'b', 'c', 'd', 'e']))
+ *
  * @since 2.0.0
  */
 const insertAt = exports.insertAt = /*#__PURE__*/(0, _Function.dual)(3, (self, i, b) => {
@@ -599,10 +828,26 @@ const insertAt = exports.insertAt = /*#__PURE__*/(0, _Function.dual)(3, (self, i
  * Change the element at the specified index, creating a new `Array`,
  * or return a copy of the input if the index is out of bounds.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const letters = ['a', 'b', 'c', 'd']
+ * const result = Array.replace(1, 'z')(letters)
+ * assert.deepStrictEqual(result, ['a', 'z', 'c', 'd'])
+ *
  * @since 2.0.0
  */
 const replace = exports.replace = /*#__PURE__*/(0, _Function.dual)(3, (self, i, b) => modify(self, i, () => b));
 /**
+ * Replaces an element in an array with the given value, returning an option of the updated array.
+ *
+ * @example
+ * import { Array, Option } from "effect"
+ *
+ * const numbers = [1, 2, 3]
+ * const result = Array.replaceOption(numbers, 1, 4)
+ * assert.deepStrictEqual(result, Option.some([1, 4, 3]))
+ *
  * @since 2.0.0
  */
 const replaceOption = exports.replaceOption = /*#__PURE__*/(0, _Function.dual)(3, (self, i, b) => modifyOption(self, i, () => b));
@@ -610,6 +855,13 @@ const replaceOption = exports.replaceOption = /*#__PURE__*/(0, _Function.dual)(3
  * Apply a function to the element at the specified index, creating a new `Array`,
  * or return a copy of the input if the index is out of bounds.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4]
+ * const result = Array.modify(numbers, 2, (n) => n * 2)
+ * assert.deepStrictEqual(result, [1, 2, 6, 4])
+ *
  * @since 2.0.0
  */
 const modify = exports.modify = /*#__PURE__*/(0, _Function.dual)(3, (self, i, f) => O.getOrElse(modifyOption(self, i, f), () => Array.from(self)));
@@ -617,6 +869,16 @@ const modify = exports.modify = /*#__PURE__*/(0, _Function.dual)(3, (self, i, f)
  * Apply a function to the element at the specified index, creating a new `Array`,
  * or return `None` if the index is out of bounds.
  *
+ * @example
+ * import { Array, Option } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4]
+ * const result = Array.modifyOption(numbers, 2, (n) => n * 2)
+ * assert.deepStrictEqual(result, Option.some([1, 2, 6, 4]))
+ *
+ * const outOfBoundsResult = Array.modifyOption(numbers, 5, (n) => n * 2)
+ * assert.deepStrictEqual(outOfBoundsResult, Option.none())
+ *
  * @since 2.0.0
  */
 const modifyOption = exports.modifyOption = /*#__PURE__*/(0, _Function.dual)(3, (self, i, f) => {
@@ -633,6 +895,16 @@ const modifyOption = exports.modifyOption = /*#__PURE__*/(0, _Function.dual)(3,
  * Delete the element at the specified index, creating a new `Array`,
  * or return a copy of the input if the index is out of bounds.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4]
+ * const result = Array.remove(numbers, 2)
+ * assert.deepStrictEqual(result, [1, 2, 4])
+ *
+ * const outOfBoundsResult = Array.remove(numbers, 5)
+ * assert.deepStrictEqual(outOfBoundsResult, [1, 2, 3, 4])
+ *
  * @since 2.0.0
  */
 const remove = exports.remove = /*#__PURE__*/(0, _Function.dual)(2, (self, i) => {
@@ -646,6 +918,13 @@ const remove = exports.remove = /*#__PURE__*/(0, _Function.dual)(2, (self, i) =>
 /**
  * Reverse an `Iterable`, creating a new `Array`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4]
+ * const result = Array.reverse(numbers)
+ * assert.deepStrictEqual(result, [4, 3, 2, 1])
+ *
  * @category elements
  * @since 2.0.0
  */
@@ -664,13 +943,54 @@ const sort = exports.sort = /*#__PURE__*/(0, _Function.dual)(2, (self, O) => {
   return out;
 });
 /**
+ * Sorts an array based on a provided mapping function and order. The mapping
+ * function transforms the elements into a value that can be compared, and the
+ * order defines how those values should be sorted.
+ *
+ * @example
+ * import { Array, Order } from "effect"
+ *
+ * const strings = ["aaa", "b", "cc"]
+ * const result = Array.sortWith(strings, (s) => s.length, Order.number)
+ * assert.deepStrictEqual(result, ["b", "cc", "aaa"])
+ *
+ * // Explanation:
+ * // The array of strings is sorted based on their lengths. The mapping function `(s) => s.length`
+ * // converts each string into its length, and the `Order.number` specifies that the lengths should
+ * // be sorted in ascending order.
+ *
  * @since 2.0.0
  * @category elements
  */
 const sortWith = exports.sortWith = /*#__PURE__*/(0, _Function.dual)(3, (self, f, order) => sort(self, Order.mapInput(order, f)));
 /**
- * Sort the elements of an `Iterable` in increasing order, where elements are compared
- * using first `orders[0]`, then `orders[1]`, etc...
+ * Sorts the elements of an `Iterable` in increasing order based on the provided
+ * orders. The elements are compared using the first order in `orders`, then the
+ * second order if the first comparison is equal, and so on.
+ *
+ * @example
+ * import { Array, Order } from "effect"
+ *
+ * const users = [
+ *   { name: "Alice", age: 30 },
+ *   { name: "Bob", age: 25 },
+ *   { name: "Charlie", age: 30 }
+ * ]
+ *
+ * const result = Array.sortBy(
+ *   Order.mapInput(Order.number, (user: (typeof users)[number]) => user.age),
+ *   Order.mapInput(Order.string, (user: (typeof users)[number]) => user.name)
+ * )(users)
+ *
+ * assert.deepStrictEqual(result, [
+ *   { name: "Bob", age: 25 },
+ *   { name: "Alice", age: 30 },
+ *   { name: "Charlie", age: 30 }
+ * ])
+ *
+ * // Explanation:
+ * // The array of users is sorted first by age in ascending order. When ages are equal,
+ * // the users are further sorted by name in ascending order.
  *
  * @category sorting
  * @since 2.0.0
@@ -690,6 +1010,14 @@ const sortBy = (...orders) => {
  * If one input `Iterable` is short, excess elements of the
  * longer `Iterable` are discarded.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const array1 = [1, 2, 3]
+ * const array2 = ['a', 'b']
+ * const result = Array.zip(array1, array2)
+ * assert.deepStrictEqual(result, [[1, 'a'], [2, 'b']])
+ *
  * @category zipping
  * @since 2.0.0
  */
@@ -699,6 +1027,14 @@ const zip = exports.zip = /*#__PURE__*/(0, _Function.dual)(2, (self, that) => zi
  * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results in a new `Array`. If one
  * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const array1 = [1, 2, 3]
+ * const array2 = [4, 5, 6]
+ * const result = Array.zipWith(array1, array2, (a, b) => a + b)
+ * assert.deepStrictEqual(result, [5, 7, 9])
+ *
  * @category zipping
  * @since 2.0.0
  */
@@ -718,6 +1054,12 @@ const zipWith = exports.zipWith = /*#__PURE__*/(0, _Function.dual)(3, (self, tha
 /**
  * This function is the inverse of `zip`. Takes an `Iterable` of pairs and return two corresponding `Array`s.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const result = Array.unzip([[1, "a"], [2, "b"], [3, "c"]])
+ * assert.deepStrictEqual(result, [[1, 2, 3], ['a', 'b', 'c']])
+ *
  * @since 2.0.0
  */
 const unzip = self => {
@@ -737,6 +1079,13 @@ const unzip = self => {
  * Places an element in between members of an `Iterable`.
  * If the input is a non-empty array, the result is also a non-empty array.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3]
+ * const result = Array.intersperse(numbers, 0)
+ * assert.deepStrictEqual(result, [1, 0, 2, 0, 3])
+ *
  * @since 2.0.0
  */
 exports.unzip = unzip;
@@ -758,24 +1107,48 @@ const intersperse = exports.intersperse = /*#__PURE__*/(0, _Function.dual)(2, (s
 /**
  * Apply a function to the head, creating a new `NonEmptyReadonlyArray`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const result = Array.modifyNonEmptyHead([1, 2, 3], n => n * 10)
+ * assert.deepStrictEqual(result, [10, 2, 3])
+ *
  * @since 2.0.0
  */
 const modifyNonEmptyHead = exports.modifyNonEmptyHead = /*#__PURE__*/(0, _Function.dual)(2, (self, f) => [f(headNonEmpty(self)), ...tailNonEmpty(self)]);
 /**
  * Change the head, creating a new `NonEmptyReadonlyArray`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const result = Array.setNonEmptyHead([1, 2, 3], 10)
+ * assert.deepStrictEqual(result, [10, 2, 3])
+ *
  * @since 2.0.0
  */
 const setNonEmptyHead = exports.setNonEmptyHead = /*#__PURE__*/(0, _Function.dual)(2, (self, b) => modifyNonEmptyHead(self, () => b));
 /**
  * Apply a function to the last element, creating a new `NonEmptyReadonlyArray`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const result = Array.modifyNonEmptyLast([1, 2, 3], n => n * 2)
+ * assert.deepStrictEqual(result, [1, 2, 6])
+ *
  * @since 2.0.0
  */
 const modifyNonEmptyLast = exports.modifyNonEmptyLast = /*#__PURE__*/(0, _Function.dual)(2, (self, f) => append(initNonEmpty(self), f(lastNonEmpty(self))));
 /**
  * Change the last element, creating a new `NonEmptyReadonlyArray`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const result = Array.setNonEmptyLast([1, 2, 3], 4)
+ * assert.deepStrictEqual(result, [1, 2, 4])
+ *
  * @since 2.0.0
  */
 const setNonEmptyLast = exports.setNonEmptyLast = /*#__PURE__*/(0, _Function.dual)(2, (self, b) => modifyNonEmptyLast(self, () => b));
@@ -783,6 +1156,13 @@ const setNonEmptyLast = exports.setNonEmptyLast = /*#__PURE__*/(0, _Function.dua
  * Rotate an `Iterable` by `n` steps.
  * If the input is a non-empty array, the result is also a non-empty array.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const letters = ['a', 'b', 'c', 'd']
+ * const result = Array.rotate(letters, 2)
+ * assert.deepStrictEqual(result, ['c', 'd', 'a', 'b'])
+ *
  * @since 2.0.0
  */
 const rotate = exports.rotate = /*#__PURE__*/(0, _Function.dual)(2, (self, n) => {
@@ -805,6 +1185,15 @@ const rotate = exports.rotate = /*#__PURE__*/(0, _Function.dual)(2, (self, n) =>
 /**
  * Returns a function that checks if a `ReadonlyArray` contains a given value using a provided `isEquivalent` function.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4]
+ * const isEquivalent = (a: number, b: number) => a === b
+ * const containsNumber = Array.containsWith(isEquivalent)
+ * const result = containsNumber(3)(numbers)
+ * assert.deepStrictEqual(result, true)
+ *
  * @category elements
  * @since 2.0.0
  */
@@ -821,6 +1210,13 @@ const _equivalence = /*#__PURE__*/Equal.equivalence();
 /**
  * Returns a function that checks if a `ReadonlyArray` contains a given value using the default `Equivalence`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const letters = ['a', 'b', 'c', 'd']
+ * const result = Array.contains('c')(letters)
+ * assert.deepStrictEqual(result, true)
+ *
  * @category elements
  * @since 2.0.0
  */
@@ -830,6 +1226,18 @@ const contains = exports.contains = /*#__PURE__*/containsWith(_equivalence);
  * `Iterable`. Typically chop is called with some function that will consume an initial prefix of the `Iterable` and produce a
  * value and the rest of the `Array`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4, 5]
+ * const result = Array.chop(numbers, (as): [number, Array<number>] => [as[0] * 2, as.slice(1)])
+ * assert.deepStrictEqual(result, [2, 4, 6, 8, 10])
+ *
+ * // Explanation:
+ * // The `chopFunction` takes the first element of the array, doubles it, and then returns it along with the rest of the array.
+ * // The `chop` function applies this `chopFunction` recursively to the input array `[1, 2, 3, 4, 5]`,
+ * // resulting in a new array `[2, 4, 6, 8, 10]`.
+ *
  * @since 2.0.0
  */
 const chop = exports.chop = /*#__PURE__*/(0, _Function.dual)(2, (self, f) => {
@@ -851,6 +1259,13 @@ const chop = exports.chop = /*#__PURE__*/(0, _Function.dual)(2, (self, f) => {
  * Splits an `Iterable` into two segments, with the first segment containing a maximum of `n` elements.
  * The value of `n` can be `0`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4, 5]
+ * const result = Array.splitAt(numbers, 3)
+ * assert.deepStrictEqual(result, [[1, 2, 3], [4, 5]])
+ *
  * @category splitting
  * @since 2.0.0
  */
@@ -869,6 +1284,12 @@ const splitAt = exports.splitAt = /*#__PURE__*/(0, _Function.dual)(2, (self, n)
  * Splits a `NonEmptyReadonlyArray` into two segments, with the first segment containing a maximum of `n` elements.
  * The value of `n` must be `>= 1`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const result = Array.splitNonEmptyAt(["a", "b", "c", "d", "e"], 3)
+ * assert.deepStrictEqual(result, [["a", "b", "c"], ["d", "e"]])
+ *
  * @category splitting
  * @since 2.0.0
  */
@@ -879,6 +1300,13 @@ const splitNonEmptyAt = exports.splitNonEmptyAt = /*#__PURE__*/(0, _Function.dua
 /**
  * Splits this iterable into `n` equally sized arrays.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4, 5, 6, 7, 8]
+ * const result = Array.split(numbers, 3)
+ * assert.deepStrictEqual(result, [[1, 2, 3], [4, 5, 6], [7, 8]])
+ *
  * @since 2.0.0
  * @category splitting
  */
@@ -890,11 +1318,27 @@ const split = exports.split = /*#__PURE__*/(0, _Function.dual)(2, (self, n) => {
  * Splits this iterable on the first element that matches this predicate.
  * Returns a tuple containing two arrays: the first one is before the match, and the second one is from the match onward.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4, 5]
+ * const result = Array.splitWhere(numbers, n => n > 3)
+ * assert.deepStrictEqual(result, [[1, 2, 3], [4, 5]])
+ *
  * @category splitting
  * @since 2.0.0
  */
 const splitWhere = exports.splitWhere = /*#__PURE__*/(0, _Function.dual)(2, (self, predicate) => span(self, (a, i) => !predicate(a, i)));
 /**
+ * Copies an array.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3]
+ * const copy = Array.copy(numbers)
+ * assert.deepStrictEqual(copy, [1, 2, 3])
+ *
  * @since 2.0.0
  */
 const copy = self => self.slice();
@@ -909,6 +1353,19 @@ const copy = self => self.slice();
  *
  * whenever `n` evenly divides the length of `self`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4, 5]
+ * const result = Array.chunksOf(numbers, 2)
+ * assert.deepStrictEqual(result, [[1, 2], [3, 4], [5]])
+ *
+ * // Explanation:
+ * // The `chunksOf` function takes an array of numbers `[1, 2, 3, 4, 5]` and a number `2`.
+ * // It splits the array into chunks of length 2. Since the array length is not evenly divisible by 2,
+ * // the last chunk contains the remaining elements.
+ * // The result is `[[1, 2], [3, 4], [5]]`.
+ *
  * @category splitting
  * @since 2.0.0
  */
@@ -923,6 +1380,12 @@ const chunksOf = exports.chunksOf = /*#__PURE__*/(0, _Function.dual)(2, (self, n
 /**
  * Group equal, consecutive elements of a `NonEmptyReadonlyArray` into `NonEmptyArray`s using the provided `isEquivalent` function.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const result = Array.groupWith(["a", "a", "b", "b", "b", "c", "a"], (x, y) => x === y)
+ * assert.deepStrictEqual(result, [["a", "a"], ["b", "b", "b"], ["c"], ["a"]])
+ *
  * @category grouping
  * @since 2.0.0
  */
@@ -943,6 +1406,12 @@ const groupWith = exports.groupWith = /*#__PURE__*/(0, _Function.dual)(2, (self,
 /**
  * Group equal, consecutive elements of a `NonEmptyReadonlyArray` into `NonEmptyArray`s.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const result = Array.group([1, 1, 2, 2, 2, 3, 1])
+ * assert.deepStrictEqual(result, [[1, 1], [2, 2, 2], [3], [1]])
+ *
  * @category grouping
  * @since 2.0.0
  */
@@ -951,6 +1420,20 @@ const group = exports.group = /*#__PURE__*/groupWith( /*#__PURE__*/Equal.equival
  * Splits an `Iterable` into sub-non-empty-arrays stored in an object, based on the result of calling a `string`-returning
  * function on each element, and grouping the results according to values returned
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const people = [
+ *   { name: "Alice", group: "A" },
+ *   { name: "Bob", group: "B" },
+ *   { name: "Charlie", group: "A" }
+ * ]
+ * const result = Array.groupBy(people, person => person.group)
+ * assert.deepStrictEqual(result, {
+ *   A: [{ name: "Alice", group: "A" }, { name: "Charlie", group: "A" }],
+ *   B: [{ name: "Bob", group: "B" }]
+ * })
+ *
  * @category grouping
  * @since 2.0.0
  */
@@ -967,6 +1450,16 @@ const groupBy = exports.groupBy = /*#__PURE__*/(0, _Function.dual)(2, (self, f)
   return out;
 });
 /**
+ * Calculates the union of two arrays using the provided equivalence relation.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const array1 = [1, 2]
+ * const array2 = [2, 3]
+ * const union = Array.unionWith(array1, array2, (a, b) => a === b)
+ * assert.deepStrictEqual(union, [1, 2, 3])
+ *
  * @since 2.0.0
  */
 const unionWith = exports.unionWith = /*#__PURE__*/(0, _Function.dual)(3, (self, that, isEquivalent) => {
@@ -982,6 +1475,16 @@ const unionWith = exports.unionWith = /*#__PURE__*/(0, _Function.dual)(3, (self,
   return b;
 });
 /**
+ * Creates a union of two arrays, removing duplicates.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const array1 = [1, 2]
+ * const array2 = [2, 3]
+ * const result = Array.union(array1, array2)
+ * assert.deepStrictEqual(result, [1, 2, 3])
+ *
  * @since 2.0.0
  */
 const union = exports.union = /*#__PURE__*/(0, _Function.dual)(2, (self, that) => unionWith(self, that, _equivalence));
@@ -989,6 +1492,15 @@ const union = exports.union = /*#__PURE__*/(0, _Function.dual)(2, (self, that) =
  * Creates an `Array` of unique values that are included in all given `Iterable`s using the provided `isEquivalent` function.
  * The order and references of result values are determined by the first `Iterable`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }]
+ * const array2 = [{ id: 3 }, { id: 4 }, { id: 1 }]
+ * const isEquivalent = (a: { id: number }, b: { id: number }) => a.id === b.id
+ * const result = Array.intersectionWith(isEquivalent)(array2)(array1)
+ * assert.deepStrictEqual(result, [{ id: 1 }, { id: 3 }])
+ *
  * @since 2.0.0
  */
 const intersectionWith = isEquivalent => {
@@ -999,6 +1511,14 @@ const intersectionWith = isEquivalent => {
  * Creates an `Array` of unique values that are included in all given `Iterable`s.
  * The order and references of result values are determined by the first `Iterable`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const array1 = [1, 2, 3]
+ * const array2 = [3, 4, 1]
+ * const result = Array.intersection(array1, array2)
+ * assert.deepStrictEqual(result, [1, 3])
+ *
  * @since 2.0.0
  */
 exports.intersectionWith = intersectionWith;
@@ -1007,6 +1527,14 @@ const intersection = exports.intersection = /*#__PURE__*/intersectionWith(_equiv
  * Creates a `Array` of values not included in the other given `Iterable` using the provided `isEquivalent` function.
  * The order and references of result values are determined by the first `Iterable`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const array1 = [1, 2, 3]
+ * const array2 = [2, 3, 4]
+ * const difference = Array.differenceWith<number>((a, b) => a === b)(array1, array2)
+ * assert.deepStrictEqual(difference, [1])
+ *
  * @since 2.0.0
  */
 const differenceWith = isEquivalent => {
@@ -1017,6 +1545,14 @@ const differenceWith = isEquivalent => {
  * Creates a `Array` of values not included in the other given `Iterable`.
  * The order and references of result values are determined by the first `Iterable`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const array1 = [1, 2, 3]
+ * const array2 = [2, 3, 4]
+ * const difference = Array.difference(array1, array2)
+ * assert.deepStrictEqual(difference, [1])
+ *
  * @since 2.0.0
  */
 exports.differenceWith = differenceWith;
@@ -1060,13 +1596,35 @@ const flatMap = exports.flatMap = /*#__PURE__*/(0, _Function.dual)(2, (self, f)
   return out;
 });
 /**
- * Flattens an array of arrays into a single array by concatenating all arrays.
+ * Combines multiple arrays into a single array by concatenating all elements
+ * from each nested array. This function ensures that the structure of nested
+ * arrays is collapsed into a single, flat array.
+ *
+ * @example
+ * import { Array } from "effect";
+ *
+ * const nestedArrays = [[1, 2], [], [3, 4], [], [5, 6]]
+ * const result = Array.flatten(nestedArrays)
+ *
+ * assert.deepStrictEqual(result, [1, 2, 3, 4, 5, 6]);
  *
  * @category sequencing
  * @since 2.0.0
  */
 const flatten = exports.flatten = /*#__PURE__*/flatMap(_Function.identity);
 /**
+ * Applies a function to each element of the `Iterable` and filters based on the result, keeping the transformed values where the function returns `Some`.
+ * This method combines filtering and mapping functionalities, allowing transformations and filtering of elements based on a single function pass.
+ *
+ * @example
+ * import { Array, Option } from "effect";
+ *
+ * const data = [1, 2, 3, 4, 5];
+ * const evenSquares = (x: number) => x % 2 === 0 ? Option.some(x * x) : Option.none();
+ * const result = Array.filterMap(data, evenSquares);
+ *
+ * assert.deepStrictEqual(result, [4, 16]);
+ *
  * @category filtering
  * @since 2.0.0
  */
@@ -1082,7 +1640,18 @@ const filterMap = exports.filterMap = /*#__PURE__*/(0, _Function.dual)(2, (self,
   return out;
 });
 /**
- * Transforms all elements of the `readonlyArray` for as long as the specified function returns some value
+ * Applies a function to each element of the array and filters based on the result, stopping when a condition is not met.
+ * This method combines filtering and mapping in a single pass, and short-circuits, i.e., stops processing, as soon as the function returns `None`.
+ * This is useful when you need to transform an array but only up to the point where a certain condition holds true.
+ *
+ * @example
+ * import { Array, Option } from "effect";
+ *
+ * const data = [2, 4, 5];
+ * const toSquareTillOdd = (x: number) => x % 2 === 0 ? Option.some(x * x) : Option.none();
+ * const result = Array.filterMapWhile(data, toSquareTillOdd);
+ *
+ * assert.deepStrictEqual(result, [4, 16]);
  *
  * @category filtering
  * @since 2.0.0
@@ -1102,6 +1671,25 @@ const filterMapWhile = exports.filterMapWhile = /*#__PURE__*/(0, _Function.dual)
   return out;
 });
 /**
+ * Applies a function to each element of the `Iterable`, categorizing the results into two separate arrays.
+ * This function is particularly useful for operations where each element can result in two possible types,
+ * and you want to separate these types into different collections. For instance, separating validation results
+ * into successes and failures.
+ *
+ * @example
+ * import { Array, Either } from "effect";
+ *
+ * const data = [1, 2, 3, 4, 5]
+ * const isEven = (x: number) => x % 2 === 0
+ * const partitioned = Array.partitionMap(data, x =>
+ *   isEven(x) ? Either.right(x) : Either.left(x)
+ * )
+ *
+ * assert.deepStrictEqual(partitioned, [
+ *   [1, 3, 5],
+ *   [2, 4]
+ * ])
+ *
  * @category filtering
  * @since 2.0.0
  */
@@ -1216,21 +1804,58 @@ const partition = exports.partition = /*#__PURE__*/(0, _Function.dual)(2, (self,
   return [left, right];
 });
 /**
+ * Separates an `Iterable` into two arrays based on a predicate.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4]
+ * const result = Array.partition(numbers, n => n % 2 === 0)
+ * assert.deepStrictEqual(result, [[1, 3], [2, 4]])
+ *
  * @category filtering
  * @since 2.0.0
  */
 const separate = exports.separate = /*#__PURE__*/partitionMap(_Function.identity);
 /**
+ * Reduces an array from the left.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3]
+ * const result = Array.reduce(numbers, 0, (acc, n) => acc + n)
+ * assert.deepStrictEqual(result, 6)
+ *
  * @category folding
  * @since 2.0.0
  */
 const reduce = exports.reduce = /*#__PURE__*/(0, _Function.dual)(3, (self, b, f) => fromIterable(self).reduce((b, a, i) => f(b, a, i), b));
 /**
+ * Reduces an array from the right.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3]
+ * const result = Array.reduceRight(numbers, 0, (acc, n) => acc + n)
+ * assert.deepStrictEqual(result, 6)
+ *
  * @category folding
  * @since 2.0.0
  */
 const reduceRight = exports.reduceRight = /*#__PURE__*/(0, _Function.dual)(3, (self, b, f) => fromIterable(self).reduceRight((b, a, i) => f(b, a, i), b));
 /**
+ * Lifts a predicate into an array.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const isEven = (n: number) => n % 2 === 0
+ * const to = Array.liftPredicate(isEven)
+ * assert.deepStrictEqual(to(1), [])
+ * assert.deepStrictEqual(to(2), [2])
+ *
  * @category lifting
  * @since 2.0.0
  */
@@ -1254,12 +1879,49 @@ const fromNullable = a => a == null ? empty() : [a];
 exports.fromNullable = fromNullable;
 const liftNullable = f => (...a) => fromNullable(f(...a));
 /**
+ * Maps over an array and flattens the result, removing null and undefined values.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3]
+ * const result = Array.flatMapNullable(numbers, n => (n % 2 === 0 ? null : n))
+ * assert.deepStrictEqual(result, [1, 3])
+ *
+ * // Explanation:
+ * // The array of numbers [1, 2, 3] is mapped with a function that returns null for even numbers
+ * // and the number itself for odd numbers. The resulting array [1, null, 3] is then flattened
+ * // to remove null values, resulting in [1, 3].
+ *
  * @category sequencing
  * @since 2.0.0
  */
 exports.liftNullable = liftNullable;
-const flatMapNullable = exports.flatMapNullable = /*#__PURE__*/(0, _Function.dual)(2, (self, f) => isNonEmptyReadonlyArray(self) ? fromNullable(f(headNonEmpty(self))) : empty());
+const flatMapNullable = exports.flatMapNullable = /*#__PURE__*/(0, _Function.dual)(2, (self, f) => flatMap(self, a => fromNullable(f(a))));
 /**
+ * Lifts a function that returns an `Either` into a function that returns an array.
+ * If the `Either` is a left, it returns an empty array.
+ * If the `Either` is a right, it returns an array with the right value.
+ *
+ * @example
+ * import { Array, Either } from "effect"
+ *
+ * const parseNumber = (s: string): Either.Either<number, Error> =>
+ *   isNaN(Number(s)) ? Either.left(new Error("Not a number")) : Either.right(Number(s))
+ *
+ * const liftedParseNumber = Array.liftEither(parseNumber)
+ *
+ * const result1 = liftedParseNumber("42")
+ * assert.deepStrictEqual(result1, [42])
+ *
+ * const result2 = liftedParseNumber("not a number")
+ * assert.deepStrictEqual(result2, [])
+ *
+ * // Explanation:
+ * // The function parseNumber is lifted to return an array.
+ * // When parsing "42", it returns an Either.left with the number 42, resulting in [42].
+ * // When parsing "not a number", it returns an Either.right with an error, resulting in an empty array [].
+ *
  * @category lifting
  * @since 2.0.0
  */
@@ -1283,14 +1945,45 @@ const every = exports.every = /*#__PURE__*/(0, _Function.dual)(2, (self, refinem
  */
 const some = exports.some = /*#__PURE__*/(0, _Function.dual)(2, (self, predicate) => self.some(predicate));
 /**
+ * Extends an array with a function that maps each subarray to a value.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3]
+ * const result = Array.extend(numbers, as => as.length)
+ * assert.deepStrictEqual(result, [3, 2, 1])
+ *
+ * // Explanation:
+ * // The function maps each subarray starting from each element to its length.
+ * // The subarrays are: [1, 2, 3], [2, 3], [3].
+ * // The lengths are: 3, 2, 1.
+ * // Therefore, the result is [3, 2, 1].
+ *
  * @since 2.0.0
  */
 const extend = exports.extend = /*#__PURE__*/(0, _Function.dual)(2, (self, f) => self.map((_, i, as) => f(as.slice(i))));
 /**
+ * Finds the minimum element in an array based on a comparator.
+ *
+ * @example
+ * import { Array, Order } from "effect"
+ *
+ * const min = Array.min([3, 1, 2], Order.number)
+ * assert.deepStrictEqual(min, 1)
+ *
  * @since 2.0.0
  */
 const min = exports.min = /*#__PURE__*/(0, _Function.dual)(2, (self, O) => self.reduce(Order.min(O)));
 /**
+ * Finds the maximum element in an array based on a comparator.
+ *
+ * @example
+ * import { Array, Order } from "effect"
+ *
+ * const max = Array.max([3, 1, 2], Order.number)
+ * assert.deepStrictEqual(max, 3)
+ *
  * @since 2.0.0
  */
 const max = exports.max = /*#__PURE__*/(0, _Function.dual)(2, (self, O) => self.reduce(Order.max(O)));
@@ -1321,12 +2014,28 @@ const unfold = (b, f) => {
 exports.unfold = unfold;
 const getOrder = exports.getOrder = Order.array;
 /**
+ * Creates an equivalence relation for arrays.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers1 = [1, 2, 3]
+ * const numbers2 = [1, 2, 3]
+ * const eq = Array.getEquivalence<number>((a, b) => a === b)
+ * assert.deepStrictEqual(eq(numbers1, numbers2), true)
+ *
  * @category instances
  * @since 2.0.0
  */
 const getEquivalence = exports.getEquivalence = Equivalence.array;
 /**
- * Iterate over the `Iterable` applying `f`.
+ * Performs a side-effect for each element of the `Iterable`.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3]
+ * Array.forEach(numbers, n => console.log(n)) // 1, 2, 3
  *
  * @since 2.0.0
  */
@@ -1335,6 +2044,13 @@ const forEach = exports.forEach = /*#__PURE__*/(0, _Function.dual)(2, (self, f)
  * Remove duplicates from an `Iterable` using the provided `isEquivalent` function,
  * preserving the order of the first occurrence of each element.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 2, 3, 3, 3]
+ * const unique = Array.dedupeWith(numbers, (a, b) => a === b)
+ * assert.deepStrictEqual(unique, [1, 2, 3])
+ *
  * @since 2.0.0
  */
 const dedupeWith = exports.dedupeWith = /*#__PURE__*/(0, _Function.dual)(2, (self, isEquivalent) => {
@@ -1361,6 +2077,13 @@ const dedupe = self => dedupeWith(self, Equal.equivalence());
 /**
  * Deduplicates adjacent elements that are identical using the provided `isEquivalent` function.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 1, 2, 2, 3, 3]
+ * const unique = Array.dedupeAdjacentWith(numbers, (a, b) => a === b)
+ * assert.deepStrictEqual(unique, [1, 2, 3])
+ *
  * @since 2.0.0
  */
 exports.dedupe = dedupe;
@@ -1378,12 +2101,26 @@ const dedupeAdjacentWith = exports.dedupeAdjacentWith = /*#__PURE__*/(0, _Functi
 /**
  * Deduplicates adjacent elements that are identical.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 1, 2, 2, 3, 3]
+ * const unique = Array.dedupeAdjacent(numbers)
+ * assert.deepStrictEqual(unique, [1, 2, 3])
+ *
  * @since 2.0.0
  */
 const dedupeAdjacent = exports.dedupeAdjacent = /*#__PURE__*/dedupeAdjacentWith( /*#__PURE__*/Equal.equivalence());
 /**
  * Joins the elements together with "sep" in the middle.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const strings = ["a", "b", "c"]
+ * const joined = Array.join(strings, "-")
+ * assert.deepStrictEqual(joined, "a-b-c")
+ *
  * @since 2.0.0
  * @category folding
  */
@@ -1391,6 +2128,13 @@ const join = exports.join = /*#__PURE__*/(0, _Function.dual)(2, (self, sep) => f
 /**
  * Statefully maps over the chunk, producing new elements of type `B`.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3]
+ * const result = Array.mapAccum(numbers, 0, (acc, n) => [acc + n, acc + n])
+ * assert.deepStrictEqual(result, [6, [1, 3, 6]])
+ *
  * @since 2.0.0
  * @category folding
  */
@@ -1409,6 +2153,14 @@ const mapAccum = exports.mapAccum = /*#__PURE__*/(0, _Function.dual)(3, (self, s
 /**
  * Zips this chunk crosswise with the specified chunk using the specified combiner.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const array1 = [1, 2]
+ * const array2 = ["a", "b"]
+ * const product = Array.cartesianWith(array1, array2, (a, b) => `${a}-${b}`)
+ * assert.deepStrictEqual(product, ["1-a", "1-b", "2-a", "2-b"])
+ *
  * @since 2.0.0
  * @category elements
  */
@@ -1416,6 +2168,14 @@ const cartesianWith = exports.cartesianWith = /*#__PURE__*/(0, _Function.dual)(3
 /**
  * Zips this chunk crosswise with the specified chunk.
  *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const array1 = [1, 2]
+ * const array2 = ["a", "b"]
+ * const product = Array.cartesian(array1, array2)
+ * assert.deepStrictEqual(product, [[1, "a"], [1, "b"], [2, "a"], [2, "b"]])
+ *
  * @since 2.0.0
  * @category elements
  */