effect 3.2.3 → 3.2.4

package/dist/dts/Array.d.ts

@@ -32,6 +32,12 @@ export type NonEmptyArray<A> = [A, ...Array<A>];
 /**
  * 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
  */
@@ -39,6 +45,12 @@ export declare const make: <Elements extends [any, ...any[]]>(...elements: Eleme
 /**
  * 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
  */
@@ -75,9 +87,9 @@ export declare const range: (start: number, end: number) => [number, ...number[]
  * **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
@@ -88,6 +100,15 @@ export declare const replicate: {
 };
 /**
  * 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
@@ -99,21 +120,41 @@ export declare const fromIterable: <A>(collection: Iterable<A>) => Array<A>;
  * @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 declare const fromRecord: <K extends string, A>(self: Readonly<Record<K, A>>) => Array<[K, A]>;
 /**
+ * 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 declare const fromOption: <A>(self: Option<A>) => Array<A>;
 /**
+ * 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
  */
@@ -128,6 +169,18 @@ export declare const match: {
     }): B | C;
 };
 /**
+ * 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
  */
@@ -142,6 +195,18 @@ export declare const matchLeft: {
     }): B | C;
 };
 /**
+ * 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
  */
@@ -158,6 +223,13 @@ export declare const matchRight: {
 /**
  * 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
  */
@@ -172,10 +244,10 @@ export declare const prepend: {
  * @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
@@ -189,6 +261,13 @@ export declare const prependAll: {
 /**
  * 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
  */
@@ -210,7 +289,22 @@ export declare const appendAll: {
     <A, B>(self: Iterable<A>, that: Iterable<B>): Array<A | B>;
 };
 /**
- * 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
@@ -220,7 +314,16 @@ export declare const scan: {
     <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A) => B): NonEmptyArray<B>;
 };
 /**
- * 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
@@ -341,6 +444,12 @@ export declare const unsafeGet: {
 /**
  * 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
  */
@@ -348,6 +457,12 @@ export declare const unprepend: <A>(self: readonly [A, ...A[]]) => [firstElement
 /**
  * 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
  */
@@ -360,6 +475,14 @@ export declare const unappend: <A>(self: readonly [A, ...A[]]) => [arrayWithoutL
  */
 export declare const head: <A>(self: ReadonlyArray<A>) => Option<A>;
 /**
+ * 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
  */
@@ -372,6 +495,14 @@ export declare const headNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => A;
  */
 export declare const last: <A>(self: ReadonlyArray<A>) => Option<A>;
 /**
+ * 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
  */
@@ -384,6 +515,14 @@ export declare const lastNonEmpty: <A>(self: readonly [A, ...A[]]) => A;
  */
 export declare const tail: <A>(self: Iterable<A>) => Option<Array<A>>;
 /**
+ * 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
  */
@@ -398,6 +537,12 @@ export declare const init: <A>(self: Iterable<A>) => Option<Array<A>>;
 /**
  * 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
  */
@@ -407,6 +552,13 @@ export declare const initNonEmpty: <A>(self: readonly [A, ...A[]]) => Array<A>;
  *
  * **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
  */
@@ -419,6 +571,13 @@ export declare const take: {
  *
  * **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
  */
@@ -429,6 +588,19 @@ export declare const takeRight: {
 /**
  * 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
  */
@@ -458,6 +630,13 @@ export declare const 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
  */
@@ -470,6 +649,13 @@ export declare const drop: {
  *
  * **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
  */
@@ -480,6 +666,13 @@ export declare const dropRight: {
 /**
  * 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
  */
@@ -490,6 +683,13 @@ export declare const dropWhile: {
 /**
  * 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
  */
@@ -500,6 +700,13 @@ export declare const findFirstIndex: {
 /**
  * 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
  */
@@ -511,6 +718,13 @@ export declare const findLastIndex: {
  * 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
  */
@@ -523,7 +737,15 @@ export declare const findFirst: {
     <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option<A>;
 };
 /**
- * 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
@@ -540,6 +762,13 @@ export declare const findLast: {
  * 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 declare const insertAt: {
@@ -550,6 +779,13 @@ export declare const insertAt: {
  * 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 declare const replace: {
@@ -557,6 +793,15 @@ export declare const replace: {
     <A, B>(self: Iterable<A>, i: number, b: B): Array<A | 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 declare const replaceOption: {
@@ -567,6 +812,13 @@ export declare const replaceOption: {
  * 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 declare const modify: {
@@ -577,6 +829,16 @@ export declare const modify: {
  * 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 declare const modifyOption: {
@@ -587,6 +849,16 @@ export declare const modifyOption: {
  * 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 declare const remove: {
@@ -596,6 +868,13 @@ export declare const remove: {
 /**
  * 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
  */
@@ -613,6 +892,22 @@ export declare const sort: {
     <A extends B, B>(self: Iterable<A>, O: Order.Order<B>): Array<A>;
 };
 /**
+ * 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
  */
@@ -622,8 +917,33 @@ export declare const sortWith: {
     <A, B>(self: Iterable<A>, f: (a: A) => B, order: Order.Order<B>): Array<A>;
 };
 /**
- * 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
@@ -634,6 +954,14 @@ export declare const sortBy: <S extends readonly [any, ...any[]] | Iterable<any>
  * 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
  */
@@ -647,6 +975,14 @@ export declare const zip: {
  * 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
  */
@@ -659,6 +995,12 @@ export declare const zipWith: {
 /**
  * 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 declare const unzip: <S extends Iterable<readonly [any, any]> | NonEmptyReadonlyArray<readonly [any, any]>>(self: S) => S extends NonEmptyReadonlyArray<readonly [infer A, infer B]> ? [NonEmptyArray<A>, NonEmptyArray<B>] : S extends Iterable<readonly [infer A, infer B]> ? [Array<A>, Array<B>] : never;
@@ -666,6 +1008,13 @@ export declare const unzip: <S extends Iterable<readonly [any, any]> | NonEmptyR
  * 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 declare const intersperse: {
@@ -676,6 +1025,12 @@ export declare const intersperse: {
 /**
  * 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 declare const modifyNonEmptyHead: {
@@ -685,6 +1040,12 @@ export declare const modifyNonEmptyHead: {
 /**
  * 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 declare const setNonEmptyHead: {
@@ -694,6 +1055,12 @@ export declare const setNonEmptyHead: {
 /**
  * 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 declare const modifyNonEmptyLast: {
@@ -703,6 +1070,12 @@ export declare const modifyNonEmptyLast: {
 /**
  * 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 declare const setNonEmptyLast: {
@@ -713,6 +1086,13 @@ export declare const setNonEmptyLast: {
  * 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 declare const rotate: {
@@ -723,6 +1103,15 @@ export declare const rotate: {
 /**
  * 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
  */
@@ -733,6 +1122,13 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
 /**
  * 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
  */
@@ -745,6 +1141,18 @@ export declare const contains: {
  * `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 declare const chop: {
@@ -756,6 +1164,13 @@ export declare const chop: {
  * 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
  */
@@ -767,6 +1182,12 @@ export declare const splitAt: {
  * 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
  */
@@ -777,6 +1198,13 @@ export declare const splitNonEmptyAt: {
 /**
  * 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
  */
@@ -788,6 +1216,13 @@ export declare const split: {
  * 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
  */
@@ -796,6 +1231,15 @@ export declare const splitWhere: {
     <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): [beforeMatch: Array<A>, fromMatch: Array<A>];
 };
 /**
+ * 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 declare const copy: {
@@ -813,6 +1257,19 @@ export declare const copy: {
  *
  * 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
  */
@@ -824,6 +1281,12 @@ export declare const chunksOf: {
 /**
  * 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
  */
@@ -834,6 +1297,12 @@ export declare const groupWith: {
 /**
  * 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
  */
@@ -842,6 +1311,20 @@ export declare const group: <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray
  * 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
  */
@@ -850,6 +1333,16 @@ export declare const groupBy: {
     <A, K extends string | symbol>(self: Iterable<A>, f: (a: A) => K): Record<Record.ReadonlyRecord.NonLiteralKey<K>, NonEmptyArray<A>>;
 };
 /**
+ * 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 declare const unionWith: {
@@ -859,6 +1352,16 @@ export declare const unionWith: {
     <A, B>(self: Iterable<A>, that: Iterable<B>, isEquivalent: (self: A, that: B) => boolean): Array<A | 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 declare const union: {
@@ -871,6 +1374,15 @@ export declare const union: {
  * 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 declare const intersectionWith: <A>(isEquivalent: (self: A, that: A) => boolean) => {
@@ -881,6 +1393,14 @@ export declare const intersectionWith: <A>(isEquivalent: (self: A, that: A) => b
  * 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 declare const intersection: {
@@ -891,6 +1411,14 @@ export declare const intersection: {
  * 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 declare const differenceWith: <A>(isEquivalent: (self: A, that: A) => boolean) => {
@@ -901,6 +1429,14 @@ export declare const differenceWith: <A>(isEquivalent: (self: A, that: A) => boo
  * 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 declare const difference: {
@@ -964,13 +1500,35 @@ export declare const flatMap: {
     <A, B>(self: ReadonlyArray<A>, f: (a: A, i: number) => ReadonlyArray<B>): Array<B>;
 };
 /**
- * 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 declare const flatten: <S extends ReadonlyArray<ReadonlyArray<any>>>(self: S) => ReadonlyArray.Flatten<S>;
 /**
+ * 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
  */
@@ -979,7 +1537,18 @@ export declare const filterMap: {
     <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option<B>): Array<B>;
 };
 /**
- * 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
@@ -989,6 +1558,25 @@ export declare const filterMapWhile: {
     <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option<B>): Array<B>;
 };
 /**
+ * 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
  */
@@ -1064,11 +1652,29 @@ export declare const partition: {
     <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): [excluded: Array<A>, satisfying: Array<A>];
 };
 /**
+ * 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 declare const separate: <R, L>(self: Iterable<Either<R, L>>) => [Array<L>, Array<R>];
 /**
+ * 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
  */
@@ -1077,6 +1683,15 @@ export declare const reduce: {
     <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A, i: number) => B): 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
  */
@@ -1085,6 +1700,16 @@ export declare const reduceRight: {
     <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A, i: number) => B): 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
  */
@@ -1108,6 +1733,20 @@ export declare const fromNullable: <A>(a: A) => Array<NonNullable<A>>;
  */
 export declare const liftNullable: <A extends unknown[], B>(f: (...a: A) => B | null | undefined) => (...a: A) => Array<NonNullable<B>>;
 /**
+ * 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
  */
@@ -1116,6 +1755,29 @@ export declare const flatMapNullable: {
     <A, B>(self: ReadonlyArray<A>, f: (a: A) => B | null | undefined): Array<NonNullable<B>>;
 };
 /**
+ * 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
  */
@@ -1143,6 +1805,21 @@ export declare const some: {
     <A>(self: ReadonlyArray<A>, predicate: (a: A, i: number) => boolean): self is NonEmptyReadonlyArray<A>;
 };
 /**
+ * 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 declare const extend: {
@@ -1150,6 +1827,14 @@ export declare const extend: {
     <A, B>(self: ReadonlyArray<A>, f: (as: ReadonlyArray<A>) => B): Array<B>;
 };
 /**
+ * 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 declare const min: {
@@ -1157,6 +1842,14 @@ export declare const min: {
     <A>(self: NonEmptyReadonlyArray<A>, O: Order.Order<A>): A;
 };
 /**
+ * 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 declare const max: {
@@ -1179,12 +1872,28 @@ export declare const unfold: <B, A>(b: B, f: (b: B) => Option<readonly [A, B]>)
  */
 export declare const getOrder: <A>(O: Order.Order<A>) => Order.Order<ReadonlyArray<A>>;
 /**
+ * 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 declare const getEquivalence: <A>(isEquivalent: Equivalence.Equivalence<A>) => Equivalence.Equivalence<ReadonlyArray<A>>;
 /**
- * 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
  */
@@ -1196,6 +1905,13 @@ export declare const forEach: {
  * 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 declare const dedupeWith: {
@@ -1213,6 +1929,13 @@ export declare const dedupe: <S extends readonly [any, ...any[]] | Iterable<any>
 /**
  * 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 declare const dedupeAdjacentWith: {
@@ -1222,12 +1945,26 @@ export declare const dedupeAdjacentWith: {
 /**
  * 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 declare const dedupeAdjacent: <A>(self: Iterable<A>) => Array<A>;
 /**
  * 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
  */
@@ -1238,6 +1975,13 @@ export declare const 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
  */
@@ -1248,6 +1992,14 @@ export declare const mapAccum: {
 /**
  * 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
  */
@@ -1258,6 +2010,14 @@ export declare const cartesianWith: {
 /**
  * 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
  */