effect 3.2.3 → 3.2.5

package/dist/esm/Array.js

@@ -18,6 +18,12 @@ import * as Tuple from "./Tuple.js";
 /**
  * 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
  */
@@ -25,6 +31,12 @@ export 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
  */
@@ -68,9 +80,9 @@ export const range = (start, end) => start <= end ? makeBy(end - start + 1, i =>
  * **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
@@ -78,6 +90,15 @@ export const range = (start, end) => start <= end ? makeBy(end - start + 1, i =>
 export const replicate = /*#__PURE__*/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
@@ -89,21 +110,41 @@ export const fromIterable = collection => Array.isArray(collection) ? collection
  * @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
  */
 export const 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
  */
 export const 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
  */
@@ -112,6 +153,18 @@ export const match = /*#__PURE__*/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
  */
@@ -120,6 +173,18 @@ export const matchLeft = /*#__PURE__*/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
  */
@@ -130,6 +195,13 @@ export const matchRight = /*#__PURE__*/dual(2, (self, {
 /**
  * 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
  */
@@ -141,10 +213,10 @@ export const prepend = /*#__PURE__*/dual(2, (self, head) => [head, ...self]);
  * @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
@@ -153,6 +225,13 @@ export const prependAll = /*#__PURE__*/dual(2, (self, that) => fromIterable(that
 /**
  * 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
  */
@@ -166,7 +245,22 @@ export const append = /*#__PURE__*/dual(2, (self, last) => [...self, last]);
  */
 export const appendAll = /*#__PURE__*/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
@@ -181,7 +275,16 @@ export const scan = /*#__PURE__*/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
@@ -309,6 +412,12 @@ export const unsafeGet = /*#__PURE__*/dual(2, (self, index) => {
 /**
  * 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
  */
@@ -316,6 +425,12 @@ export 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
  */
@@ -328,6 +443,14 @@ export const unappend = self => [initNonEmpty(self), lastNonEmpty(self)];
  */
 export const 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
  */
@@ -340,6 +463,14 @@ export const headNonEmpty = /*#__PURE__*/unsafeGet(0);
  */
 export 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
  */
@@ -355,6 +486,14 @@ export 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
  */
@@ -372,6 +511,12 @@ export 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
  */
@@ -381,6 +526,13 @@ export 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
  */
@@ -393,6 +545,13 @@ export const take = /*#__PURE__*/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
  */
@@ -404,6 +563,19 @@ export const takeRight = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * 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
  */
@@ -444,6 +616,13 @@ export const span = /*#__PURE__*/dual(2, (self, predicate) => splitAt(self, span
  *
  * **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
  */
@@ -456,6 +635,13 @@ export const drop = /*#__PURE__*/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
  */
@@ -466,6 +652,13 @@ export const dropRight = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * 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
  */
@@ -473,6 +666,13 @@ export const dropWhile = /*#__PURE__*/dual(2, (self, predicate) => fromIterable(
 /**
  * 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
  */
@@ -489,6 +689,13 @@ export const findFirstIndex = /*#__PURE__*/dual(2, (self, predicate) => {
 /**
  * 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
  */
@@ -505,12 +712,27 @@ export const findLastIndex = /*#__PURE__*/dual(2, (self, predicate) => {
  * 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
  */
 export const 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
@@ -536,6 +758,13 @@ export const findLast = /*#__PURE__*/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
  */
 export const insertAt = /*#__PURE__*/dual(3, (self, i, b) => {
@@ -551,10 +780,26 @@ export const insertAt = /*#__PURE__*/dual(3, (self, i, b) => {
  * 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
  */
 export const replace = /*#__PURE__*/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
  */
 export const replaceOption = /*#__PURE__*/dual(3, (self, i, b) => modifyOption(self, i, () => b));
@@ -562,6 +807,13 @@ export const replaceOption = /*#__PURE__*/dual(3, (self, i, b) => modifyOption(s
  * 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
  */
 export const modify = /*#__PURE__*/dual(3, (self, i, f) => O.getOrElse(modifyOption(self, i, f), () => Array.from(self)));
@@ -569,6 +821,16 @@ export const modify = /*#__PURE__*/dual(3, (self, i, f) => O.getOrElse(modifyOpt
  * 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
  */
 export const modifyOption = /*#__PURE__*/dual(3, (self, i, f) => {
@@ -585,6 +847,16 @@ export const modifyOption = /*#__PURE__*/dual(3, (self, i, f) => {
  * 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
  */
 export const remove = /*#__PURE__*/dual(2, (self, i) => {
@@ -598,6 +870,13 @@ export const remove = /*#__PURE__*/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
  */
@@ -615,13 +894,54 @@ export const sort = /*#__PURE__*/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
  */
 export const sortWith = /*#__PURE__*/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
@@ -641,6 +961,14 @@ export 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
  */
@@ -649,6 +977,14 @@ export const zip = /*#__PURE__*/dual(2, (self, that) => zipWith(self, that, Tupl
  * 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
  */
@@ -668,6 +1004,12 @@ export const zipWith = /*#__PURE__*/dual(3, (self, that, f) => {
 /**
  * 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
  */
 export const unzip = self => {
@@ -687,6 +1029,13 @@ export 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
  */
 export const intersperse = /*#__PURE__*/dual(2, (self, middle) => {
@@ -707,24 +1056,48 @@ export const intersperse = /*#__PURE__*/dual(2, (self, middle) => {
 /**
  * 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
  */
 export const modifyNonEmptyHead = /*#__PURE__*/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
  */
 export const setNonEmptyHead = /*#__PURE__*/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
  */
 export const modifyNonEmptyLast = /*#__PURE__*/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
  */
 export const setNonEmptyLast = /*#__PURE__*/dual(2, (self, b) => modifyNonEmptyLast(self, () => b));
@@ -732,6 +1105,13 @@ export const setNonEmptyLast = /*#__PURE__*/dual(2, (self, b) => modifyNonEmptyL
  * 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
  */
 export const rotate = /*#__PURE__*/dual(2, (self, n) => {
@@ -754,6 +1134,15 @@ export const rotate = /*#__PURE__*/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
  */
@@ -769,6 +1158,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
  */
@@ -778,6 +1174,18 @@ export const 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
  */
 export const chop = /*#__PURE__*/dual(2, (self, f) => {
@@ -799,6 +1207,13 @@ export const chop = /*#__PURE__*/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
  */
@@ -817,6 +1232,12 @@ export const splitAt = /*#__PURE__*/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
  */
@@ -827,6 +1248,13 @@ export const splitNonEmptyAt = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * 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
  */
@@ -838,11 +1266,27 @@ export const split = /*#__PURE__*/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
  */
 export const splitWhere = /*#__PURE__*/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
  */
 export const copy = self => self.slice();
@@ -857,6 +1301,19 @@ export 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
  */
@@ -870,6 +1327,12 @@ export const chunksOf = /*#__PURE__*/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
  */
@@ -890,6 +1353,12 @@ export const groupWith = /*#__PURE__*/dual(2, (self, isEquivalent) => chop(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
  */
@@ -898,6 +1367,20 @@ export const group = /*#__PURE__*/groupWith( /*#__PURE__*/Equal.equivalence());
  * 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
  */
@@ -914,6 +1397,16 @@ export const groupBy = /*#__PURE__*/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
  */
 export const unionWith = /*#__PURE__*/dual(3, (self, that, isEquivalent) => {
@@ -929,6 +1422,16 @@ export const unionWith = /*#__PURE__*/dual(3, (self, that, isEquivalent) => {
   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
  */
 export const union = /*#__PURE__*/dual(2, (self, that) => unionWith(self, that, _equivalence));
@@ -936,6 +1439,15 @@ export const union = /*#__PURE__*/dual(2, (self, that) => unionWith(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
  */
 export const intersectionWith = isEquivalent => {
@@ -946,6 +1458,14 @@ export 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
  */
 export const intersection = /*#__PURE__*/intersectionWith(_equivalence);
@@ -953,6 +1473,14 @@ export const intersection = /*#__PURE__*/intersectionWith(_equivalence);
  * 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
  */
 export const differenceWith = isEquivalent => {
@@ -963,6 +1491,14 @@ export 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
  */
 export const difference = /*#__PURE__*/differenceWith(_equivalence);
@@ -1003,13 +1539,35 @@ export const flatMap = /*#__PURE__*/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
  */
 export const flatten = /*#__PURE__*/flatMap(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
  */
@@ -1025,7 +1583,18 @@ export const filterMap = /*#__PURE__*/dual(2, (self, f) => {
   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
@@ -1045,6 +1614,25 @@ export const filterMapWhile = /*#__PURE__*/dual(2, (self, f) => {
   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
  */
@@ -1157,21 +1745,58 @@ export const partition = /*#__PURE__*/dual(2, (self, predicate) => {
   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
  */
 export const separate = /*#__PURE__*/partitionMap(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
  */
 export const reduce = /*#__PURE__*/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
  */
 export const reduceRight = /*#__PURE__*/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
  */
@@ -1192,11 +1817,48 @@ export const fromNullable = a => a == null ? empty() : [a];
  */
 export 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
  */
-export const flatMapNullable = /*#__PURE__*/dual(2, (self, f) => isNonEmptyReadonlyArray(self) ? fromNullable(f(headNonEmpty(self))) : empty());
+export const flatMapNullable = /*#__PURE__*/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
  */
@@ -1219,14 +1881,45 @@ export const every = /*#__PURE__*/dual(2, (self, refinement) => self.every(refin
  */
 export const some = /*#__PURE__*/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
  */
 export const extend = /*#__PURE__*/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
  */
 export const min = /*#__PURE__*/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
  */
 export const max = /*#__PURE__*/dual(2, (self, O) => self.reduce(Order.max(O)));
@@ -1256,12 +1949,28 @@ export const unfold = (b, f) => {
  */
 export const 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
  */
 export const 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
  */
@@ -1270,6 +1979,13 @@ export const forEach = /*#__PURE__*/dual(2, (self, f) => fromIterable(self).forE
  * 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
  */
 export const dedupeWith = /*#__PURE__*/dual(2, (self, isEquivalent) => {
@@ -1296,6 +2012,13 @@ export 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
  */
 export const dedupeAdjacentWith = /*#__PURE__*/dual(2, (self, isEquivalent) => {
@@ -1312,12 +2035,26 @@ export const dedupeAdjacentWith = /*#__PURE__*/dual(2, (self, isEquivalent) => {
 /**
  * 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
  */
 export const 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
  */
@@ -1325,6 +2062,13 @@ export const join = /*#__PURE__*/dual(2, (self, sep) => fromIterable(self).join(
 /**
  * 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
  */
@@ -1343,6 +2087,14 @@ export const mapAccum = /*#__PURE__*/dual(3, (self, s, f) => {
 /**
  * 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
  */
@@ -1350,6 +2102,14 @@ export const cartesianWith = /*#__PURE__*/dual(3, (self, that, f) => flatMap(sel
 /**
  * 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
  */