Array.ts

Array.ts overview

Works with JavaScript arrays, readonly arrays, and non-empty arrays.

The helpers cover common collection work such as creating arrays, reading elements, transforming values, sorting, grouping, splitting, combining, and reducing many values to one result. Helpers that change contents return new arrays and preserve non-empty array types when the result is guaranteed to contain values.

Since v2.0.0

---

Exports Grouped by Category

• combining
  • append
  • appendAll
  • prepend
  • prependAll
• constructors
  • Array
  • allocate
  • empty
  • ensure
  • fromIterable
  • make
  • makeBy
  • of
  • range
  • replicate
  • unfold
• converting
  • fromNullishOr
  • fromOption
  • fromRecord
• do notation
  • Do
  • bind
  • bindTo
  • let
• elements
  • cartesian
  • cartesianWith
  • chop
  • contains
  • containsWith
  • copy
  • dedupe
  • dedupeAdjacent
  • dedupeAdjacentWith
  • dedupeWith
  • difference
  • differenceWith
  • every
  • findFirst
  • findFirstIndex
  • findFirstWithIndex
  • findLast
  • findLastIndex
  • forEach
  • insertAt
  • intersection
  • intersectionWith
  • intersperse
  • max
  • min
  • modify
  • modifyHeadNonEmpty
  • modifyLastNonEmpty
  • pad
  • remove
  • replace
  • reverse
  • rotate
  • setHeadNonEmpty
  • setLastNonEmpty
  • some
  • sortWith
  • union
  • unionWith
• filtering
  • filter
  • filterMap
  • getFailures
  • getSomes
  • getSuccesses
  • partition
  • separate
• folding
  • countBy
  • getReadonlyReducerConcat
  • join
  • makeReducerConcat
  • mapAccum
  • reduce
  • reduceRight
  • scan
  • scanRight
• getters
  • drop
  • dropRight
  • dropWhile
  • dropWhileFilter
  • get
  • head
  • headNonEmpty
  • init
  • initNonEmpty
  • last
  • lastNonEmpty
  • length
  • tail
  • tailNonEmpty
  • take
  • takeRight
  • takeWhile
  • takeWhileFilter
• grouping
  • group
  • groupBy
  • groupWith
• guards
  • isArray
  • isArrayEmpty
  • isArrayNonEmpty
  • isReadonlyArrayEmpty
  • isReadonlyArrayNonEmpty
• instances
  • makeEquivalence
  • makeOrder
• lifting
  • liftNullishOr
  • liftOption
  • liftPredicate
  • liftResult
• mapping
  • extend
  • map
• models
  • NonEmptyArray (type alias)
  • NonEmptyReadonlyArray (type alias)
• pattern matching
  • match
  • matchLeft
  • matchRight
• sequencing
  • flatMap
  • flatMapNullishOr
  • flatten
• sorting
  • sort
  • sortBy
• splitting
  • chunksOf
  • span
  • split
  • splitAt
  • splitAtNonEmpty
  • splitWhere
  • unappend
  • unprepend
  • window
• type lambdas
  • ReadonlyArrayTypeLambda (interface)
• unsafe
  • getUnsafe
• utils
  • ReadonlyArray (namespace)
    • Infer (type alias)
    • With (type alias)
    • OrNonEmpty (type alias)
    • AndNonEmpty (type alias)
    • Flatten (type alias)
• zipping
  • unzip
  • zip
  • zipWith

---

combining

append

Adds a single element to the end of an iterable, returning a NonEmptyArray.

When to use

Use when you need to guarantee a non-empty result after adding a required trailing value.

Example (Appending an element)

import { Array } from "effect"

const result = Array.append([1, 2, 3], 4)
console.log(result) // [1, 2, 3, 4]

See

• prepend — add to the front
• appendAll — append multiple elements

Signature

declare const append: {
  <B>(last: B): <A>(self: Iterable<A>) => NonEmptyArray<A | B>
  <A, B>(self: Iterable<A>, last: B): NonEmptyArray<A | B>
}

Source

Since v2.0.0

appendAll

Concatenates two iterables into a single array.

When to use

Use to combine two iterable inputs into a new array with the second input’s elements after the first.

Details

If either input is non-empty, the result is a NonEmptyArray.

Example (Concatenating arrays)

import { Array } from "effect"

const result = Array.appendAll([1, 2], [3, 4])
console.log(result) // [1, 2, 3, 4]

See

• append — add a single element to the end
• prependAll — add elements to the front

Signature

declare const appendAll: {
  <S extends Iterable<any>, T extends Iterable<any>>(
    that: T
  ): (self: S) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>
  <A, B>(self: Iterable<A>, that: NonEmptyReadonlyArray<B>): NonEmptyArray<A | B>
  <A, B>(self: NonEmptyReadonlyArray<A>, that: Iterable<B>): NonEmptyArray<A | B>
  <A, B>(self: Iterable<A>, that: Iterable<B>): Array<A | B>
}

Source

Since v2.0.0

prepend

Adds a single element to the front of an iterable, returning a NonEmptyArray.

When to use

Use when you need to guarantee a non-empty result after adding a required leading value.

Example (Prepending an element)

import { Array } from "effect"

const result = Array.prepend([2, 3, 4], 1)
console.log(result) // [1, 2, 3, 4]

See

• append — add to the end
• prependAll — prepend multiple elements

Signature

declare const prepend: {
  <B>(head: B): <A>(self: Iterable<A>) => NonEmptyArray<A | B>
  <A, B>(self: Iterable<A>, head: B): NonEmptyArray<A | B>
}

Source

Since v2.0.0

prependAll

Prepends all elements from a prefix iterable to the front of an array.

When to use

Use to prepend multiple elements from an iterable to the front of an array.

Details

If either input is non-empty, the result is a NonEmptyArray.

Example (Prepending multiple elements)

import { Array } from "effect"

const result = Array.prependAll([2, 3], [0, 1])
console.log(result) // [0, 1, 2, 3]

See

• prepend — add a single element to the front
• appendAll — add elements to the end

Signature

declare const prependAll: {
  <S extends Iterable<any>, T extends Iterable<any>>(
    that: T
  ): (self: S) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>
  <A, B>(self: Iterable<A>, that: NonEmptyReadonlyArray<B>): NonEmptyArray<A | B>
  <A, B>(self: NonEmptyReadonlyArray<A>, that: Iterable<B>): NonEmptyArray<A | B>
  <A, B>(self: Iterable<A>, that: Iterable<B>): Array<A | B>
}

Source

Since v2.0.0

constructors

Array

Exposes the global array constructor.

When to use

Use to access native JavaScript array constructor methods such as isArray or from from the Effect module namespace.

Example (Accessing the Array constructor)

import { Array } from "effect"

const arr = new Array.Array(3)
console.log(arr) // [undefined, undefined, undefined]

Signature

declare const Array: ArrayConstructor

Source

Since v4.0.0

allocate

Creates a new Array of the specified length with all slots uninitialized.

When to use

Use when you need a pre-sized array that will be filled imperatively.

Details

Elements are typed as A | undefined because the slots are empty.

Example (Allocating a fixed-size array)

import { Array } from "effect"

const result = Array.allocate<number>(3)
console.log(result.length) // 3

See

• makeBy — create an array by computing each element

Signature

declare const allocate: <A = never>(n: number) => Array<A | undefined>

Source

Since v2.0.0

empty

Creates an empty array.

When to use

Use to create a typed empty array without allocating placeholder elements.

Example (Creating an empty array)

import { Array } from "effect"

const result = Array.empty<number>()
console.log(result) // []

See

• of — create a single-element array
• make — create from multiple values

Signature

declare const empty: <A = never>() => Array<A>

Source

Since v2.0.0

ensure

Normalizes a value that is either a single element or an array into an array.

When to use

Use to normalize input that may be a single value or an array into a consistent array.

Details

If the input is already an array, this returns it by reference. If the input is a single value, this wraps it in a one-element array. This is useful for APIs that accept A | Array<A>.

Example (Normalizing input)

import { Array } from "effect"

console.log(Array.ensure("a")) // ["a"]
console.log(Array.ensure(["a", "b", "c"])) // ["a", "b", "c"]

See

• of — always wrap in a single-element array
• fromIterable — convert any iterable

Signature

declare const ensure: <A>(self: ReadonlyArray<A> | A) => Array<A>

Source

Since v3.3.0

fromIterable

Converts an Iterable to an Array.

When to use

Use to convert any Iterable (Set, Generator, etc.) into an array.

Details

If the input is already an array, this returns it by reference without copying. Otherwise, it creates a new array from the iterable. Use copy if you need a fresh array even when the input is already an array.

Example (Converting a Set to an array)

import { Array } from "effect"

const result = Array.fromIterable(new Set([1, 2, 3]))
console.log(result) // [1, 2, 3]

See

• ensure — wrap a single value or return an existing array
• copy — create a shallow copy of an array

Signature

declare const fromIterable: <A>(collection: Iterable<A>) => Array<A>

Source

Since v2.0.0

make

Creates a NonEmptyArray from one or more elements.

When to use

Use when you need to create a typed non-empty array from literal values.

Details

The element type is inferred as the union of all arguments. Because at least one argument is required, this always returns a NonEmptyArray.

Example (Creating an array from values)

import { Array } from "effect"

const result = Array.make(1, 2, 3)
console.log(result) // [1, 2, 3]

See

• of — create a single-element array
• fromIterable — create from any iterable

Signature

declare const make: <Elements extends NonEmptyArray<unknown>>(...elements: Elements) => NonEmptyArray<Elements[number]>

Source

Since v2.0.0

makeBy

Creates a NonEmptyArray of length n where element i is computed by f(i).

When to use

Use when you need to compute each array element from its index.

Details

n is normalized to an integer greater than or equal to 1, so this function always returns at least one element. Supports both data-first and data-last usage.

Example (Generating values from indices)

import { Array } from "effect"

const result = Array.makeBy(5, (n) => n * 2)
console.log(result) // [0, 2, 4, 6, 8]

See

• range — create a range of integers
• replicate — repeat a single value

Signature

declare const makeBy: {
  <A>(f: (i: number) => A): (n: number) => NonEmptyArray<A>
  <A>(n: number, f: (i: number) => A): NonEmptyArray<A>
}

Source

Since v2.0.0

of

Wraps a single value in a NonEmptyArray.

Example (Creating a single-element array)

import { Array } from "effect"

console.log(Array.of(1)) // [1]

See

• make — create from multiple values
• empty — create an empty array

Signature

declare const of: <A>(a: A) => NonEmptyArray<A>

Source

Since v2.0.0

range

Creates a NonEmptyArray containing a range of integers, inclusive on both ends.

When to use

Use when you need a non-empty sequence of consecutive integers.

Details

If start > end, returns [start].

Example (Creating a range)

import { Array } from "effect"

const result = Array.range(1, 3)
console.log(result) // [1, 2, 3]

See

• makeBy — generate values from a function

Signature

declare const range: (start: number, end: number) => NonEmptyArray<number>

Source

Since v2.0.0

replicate

Creates a NonEmptyArray containing a value repeated n times.

When to use

Use when you need a non-empty array containing repeated copies of one value.

Details

n is normalized to an integer greater than or equal to 1, so this function always returns at least one element. Supports both data-first and data-last usage.

Example (Repeating a value)

import { Array } from "effect"

const result = Array.replicate("a", 3)
console.log(result) // ["a", "a", "a"]

See

• makeBy — vary values based on index

Signature

declare const replicate: { (n: number): <A>(a: A) => NonEmptyArray<A>; <A>(a: A, n: number): NonEmptyArray<A> }

Source

Since v2.0.0

unfold

Builds an array by repeatedly applying a function to a seed value. The function returns Option.some([element, nextSeed]) to continue, or Option.none() to stop.

Example (Generating a sequence)

import { Array, Option } from "effect"

console.log(Array.unfold(1, (n) => (n <= 5 ? Option.some([n, n + 1]) : Option.none())))
// [1, 2, 3, 4, 5]

See

• makeBy — generate from index
• range — generate a numeric range

Signature

declare const unfold: <B, A>(b: B, f: (b: B) => Option.Option<readonly [A, B]>) => Array<A>

Source

Since v2.0.0

converting

fromNullishOr

Converts a nullable value to an array: null/undefined becomes [], anything else becomes [value].

When to use

Use to treat a nullable single value as zero or one array element.

Example (Converting nullable values to an array)

import { Array } from "effect"

console.log(Array.fromNullishOr(1)) // [1]
console.log(Array.fromNullishOr(null)) // []
console.log(Array.fromNullishOr(undefined)) // []

See

• liftNullishOr — lift a nullable-returning function
• fromOption — convert from Option

Signature

declare const fromNullishOr: <A>(a: A) => Array<NonNullable<A>>

Source

Since v4.0.0

fromOption

Converts an Option to an array: Some(a) becomes [a], None becomes [].

When to use

Use to convert a single Option into an array for downstream array operations.

Example (Converting an Option to an array)

import { Array, Option } from "effect"

console.log(Array.fromOption(Option.some(1))) // [1]
console.log(Array.fromOption(Option.none())) // []

See

• getSomes — extract Some values from an array of Options

Signature

declare const fromOption: <A>(self: Option.Option<A>) => Array<A>

Source

Since v2.0.0

fromRecord

Converts a record into an array of [key, value] tuples.

When to use

Use to convert a record into an array of key-value tuples for iteration or transformation.

Details

Key order follows Object.entries semantics. Empty records produce an empty array.

Example (Converting a record to entries)

import { Array } from "effect"

const result = Array.fromRecord({ a: 1, b: 2, c: 3 })
console.log(result) // [["a", 1], ["b", 2], ["c", 3]]

See

• Record.toEntries the equivalent function from the Record module
• Record.fromEntries to build a record from an array of tuples

Signature

declare const fromRecord: <K extends string, A>(self: Readonly<Record<K, A>>) => Array<[K, A]>

Source

Since v2.0.0

do notation

Do

Provides the starting point for the “do simulation” — an array comprehension pattern.

When to use

Use when you want array-comprehension style code with do notation.

Details

Use bind to introduce array variables and let for plain values. Each bind produces the cartesian product of all bound variables, like nested loops. Use filter and map in the pipeline to add conditions and transformations.

Example (Building array comprehensions with do notation)

import { Array, pipe } from "effect"

const result = pipe(
  Array.Do,
  Array.bind("x", () => [1, 3, 5]),
  Array.bind("y", () => [2, 4, 6]),
  Array.filter(({ x, y }) => x < y),
  Array.map(({ x, y }) => [x, y] as const)
)
console.log(result) // [[1, 2], [1, 4], [1, 6], [3, 4], [3, 6], [5, 6]]

See

• bind — introduce an array variable into the scope
• bindTo — start a pipeline by naming the first array
• let — introduce a plain computed value

Signature

declare const Do: ReadonlyArray<{}>

Source

Since v3.2.0

bind

Adds a new array variable to a do-notation scope, producing the cartesian product with all previous bindings.

When to use

Use to add another array-producing binding to an Array.Do pipeline, pairing each existing scope with every value returned by the callback.

Details

Each bind call adds a named property to the accumulated object. The callback receives the current scope and must return an array. This is equivalent to flatMap plus merging the new value into the scope object.

Example (Binding two arrays)

import { Array, pipe } from "effect"

const result = pipe(
  Array.Do,
  Array.bind("x", () => [1, 2]),
  Array.bind("y", () => ["a", "b"])
)
console.log(result)
// [{ x: 1, y: "a" }, { x: 1, y: "b" }, { x: 2, y: "a" }, { x: 2, y: "b" }]

See

• Do — start a do-notation pipeline
• bindTo — name the first array in a pipeline
• let — add a plain computed value

Signature

declare const bind: {
  <A extends object, N extends string, B>(
    tag: Exclude<N, keyof A>,
    f: (a: NoInfer<A>) => ReadonlyArray<B>
  ): (self: ReadonlyArray<A>) => Array<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }>
  <A extends object, N extends string, B>(
    self: ReadonlyArray<A>,
    tag: Exclude<N, keyof A>,
    f: (a: NoInfer<A>) => ReadonlyArray<B>
  ): Array<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }>
}

Source

Since v3.2.0

bindTo

Wraps each array element in an object with the given key, starting a do-notation scope.

When to use

Use when you already have an array and want to start a do-notation pipeline by naming each element.

Details

Equivalent to Array.map(self, (a) => ({ [tag]: a })). This is an alternative to starting with Do plus bind when you already have an array.

Example (Naming an existing array)

import { Array, pipe } from "effect"

const result = pipe([1, 2, 3], Array.bindTo("x"))
console.log(result) // [{ x: 1 }, { x: 2 }, { x: 3 }]

See

• Do — start with an empty scope
• bind — add another array variable to the scope

Signature

declare const bindTo: {
  <N extends string>(tag: N): <A>(self: ReadonlyArray<A>) => Array<{ [K in N]: A }>
  <A, N extends string>(self: ReadonlyArray<A>, tag: N): Array<{ [K in N]: A }>
}

Source

Since v3.2.0

let

Adds a computed plain value to the do-notation scope without introducing a new array dimension.

When to use

Use when each do-notation branch needs a derived field from the current bindings without multiplying the number of branches.

Details

Unlike bind, the callback returns a single value instead of an array, so no cartesian product occurs. Use this for derived or intermediate values that depend on previously bound variables.

Example (Adding a computed value)

import { Array, pipe } from "effect"

const result = pipe(
  Array.Do,
  Array.bind("x", () => [1, 2, 3]),
  Array.let("doubled", ({ x }) => x * 2)
)
console.log(result)
// [{ x: 1, doubled: 2 }, { x: 2, doubled: 4 }, { x: 3, doubled: 6 }]

See

• Do — start a do-notation pipeline
• bind — introduce an array variable (produces cartesian product)

Signature

declare const let: {
  <N extends string, B, A extends object>(
    tag: Exclude<N, keyof A>,
    f: (a: NoInfer<A>) => B
  ): (self: ReadonlyArray<A>) => Array<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }>
  <N extends string, A extends object, B>(
    self: ReadonlyArray<A>,
    tag: Exclude<N, keyof A>,
    f: (a: NoInfer<A>) => B
  ): Array<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }>
}

Source

Since v3.2.0

elements

cartesian

Computes the cartesian product of two arrays, returning all pairs as tuples.

When to use

Use when you need every [a, b] pair from two arrays as tuples.

Details

Produces every [a, b] combination of an element from self with an element from that, so the result length is self.length * that.length.

Example (Generating all pairs from two arrays)

import { Array } from "effect"

const result = Array.cartesian([1, 2], ["a", "b"])
console.log(result) // [[1, "a"], [1, "b"], [2, "a"], [2, "b"]]

See

• cartesianWith — apply a combiner to each pair

Signature

declare const cartesian: {
  <B>(that: ReadonlyArray<B>): <A>(self: ReadonlyArray<A>) => Array<[A, B]>
  <A, B>(self: ReadonlyArray<A>, that: ReadonlyArray<B>): Array<[A, B]>
}

Source

Since v2.0.0

cartesianWith

Computes the cartesian product of two arrays, applying a combiner to each pair.

When to use

Use to compute every combination from two arrays and immediately transform each pair into a custom result.

Details

Produces every combination of an element from self with an element from that, so the result length is self.length * that.length. Iteration visits every element of that for each element of self.

Example (Combining numbers and letters)

import { Array } from "effect"

const result = Array.cartesianWith([1, 2], ["a", "b"], (a, b) => `${a}-${b}`)
console.log(result) // ["1-a", "1-b", "2-a", "2-b"]

See

• cartesian for returning tuples instead of applying a combiner

Signature

declare const cartesianWith: {
  <A, B, C>(that: ReadonlyArray<B>, f: (a: A, b: B) => C): (self: ReadonlyArray<A>) => Array<C>
  <A, B, C>(self: ReadonlyArray<A>, that: ReadonlyArray<B>, f: (a: A, b: B) => C): Array<C>
}

Source

Since v2.0.0

chop

Applies a function repeatedly to consume prefixes of the array and collect the values it produces.

When to use

Use when you need custom grouping logic where each step returns both a value and the remaining input.

Details

The function receives a NonEmptyReadonlyArray and returns [value, rest]. Processing continues until the remaining array is empty.

Example (Chopping an array)

import { Array } from "effect"

const result = Array.chop([1, 2, 3, 4, 5], (as): [number, Array<number>] => [as[0] * 2, as.slice(1)])
console.log(result) // [2, 4, 6, 8, 10]

See

• chunksOf — split into fixed-size chunks
• splitAt — split at an index

Signature

declare const chop: {
  <S extends Iterable<any>, B>(
    f: (as: NonEmptyReadonlyArray<ReadonlyArray.Infer<S>>) => readonly [B, ReadonlyArray<ReadonlyArray.Infer<S>>]
  ): (self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
  <A, B>(
    self: NonEmptyReadonlyArray<A>,
    f: (as: NonEmptyReadonlyArray<A>) => readonly [B, ReadonlyArray<A>]
  ): NonEmptyArray<B>
  <A, B>(self: Iterable<A>, f: (as: NonEmptyReadonlyArray<A>) => readonly [B, ReadonlyArray<A>]): Array<B>
}

Source

Since v2.0.0

contains

Checks whether an array contains a value, using Equal.equivalence() for comparison.

When to use

Use to check whether an iterable contains a value using Effect’s default equality instead of providing a comparison function.

Example (Checking membership)

import { Array, pipe } from "effect"

console.log(pipe(["a", "b", "c", "d"], Array.contains("c"))) // true

See

• containsWith — use custom equality

Signature

declare const contains: { <A>(a: A): (self: Iterable<A>) => boolean; <A>(self: Iterable<A>, a: A): boolean }

Source

Since v2.0.0

containsWith

Returns a membership-test function using a custom equivalence.

When to use

Use when checking membership with caller-provided equality instead of Equal.equivalence().

Example (Checking with custom equality)

import { Array, pipe } from "effect"

const containsNumber = Array.containsWith((a: number, b: number) => a === b)
console.log(pipe([1, 2, 3, 4], containsNumber(3))) // true

See

• contains for the Equal.equivalence() variant

Signature

declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boolean) => {
  (a: A): (self: Iterable<A>) => boolean
  (self: Iterable<A>, a: A): boolean
}

Source

Since v2.0.0

copy

Creates a shallow copy of an array.

When to use

Use to create a distinct array reference for an existing array, for example before mutating the returned array.

Details

The return type preserves NonEmptyArray. Use this when you need a distinct reference, for example before mutating the returned array.

Example (Copying an array)

import { Array } from "effect"

const original = [1, 2, 3]
const copied = Array.copy(original)
console.log(copied) // [1, 2, 3]
console.log(original === copied) // false

See

• fromIterable — returns the same reference for arrays

Signature

declare const copy: { <A>(self: NonEmptyReadonlyArray<A>): NonEmptyArray<A>; <A>(self: ReadonlyArray<A>): Array<A> }

Source

Since v2.0.0

dedupe

Removes duplicates using Equal.equivalence(), preserving the order of the first occurrence.

When to use

Use to remove repeated values from an iterable when Effect’s default equality is the right comparison, preserving the first occurrence.

Example (Removing duplicates)

import { Array } from "effect"

console.log(Array.dedupe([1, 2, 1, 3, 2, 4])) // [1, 2, 3, 4]

See

• dedupeWith — use custom equality
• dedupeAdjacent — only dedupes consecutive elements

Signature

declare const dedupe: <S extends Iterable<any>>(
  self: S
) => S extends NonEmptyReadonlyArray<infer A> ? NonEmptyArray<A> : S extends Iterable<infer A> ? Array<A> : never

Source

Since v2.0.0

dedupeAdjacent

Removes consecutive duplicate elements using Equal.equivalence().

When to use

Use when you need to collapse consecutive duplicates while preserving later non-consecutive repeats, and the default equality is sufficient.

Example (Removing adjacent duplicates)

import { Array } from "effect"

console.log(Array.dedupeAdjacent([1, 1, 2, 2, 3, 3])) // [1, 2, 3]

See

• dedupeAdjacentWith — use custom equality
• dedupe — remove all duplicates

Signature

declare const dedupeAdjacent: <A>(self: Iterable<A>) => Array<A>

Source

Since v2.0.0

dedupeAdjacentWith

Removes consecutive duplicate elements using a custom equivalence.

When to use

Use when consecutive duplicates should be collapsed using a custom equivalence, while equivalent values that appear later should remain in the result.

Details

Non-adjacent duplicates are preserved.

Example (Deduplicating adjacent elements)

import { Array } from "effect"

console.log(Array.dedupeAdjacentWith([1, 1, 2, 2, 3, 3], (a, b) => a === b))
// [1, 2, 3]

See

• dedupeAdjacent — uses default equality
• dedupeWith — dedupes all duplicates, not just adjacent

Signature

declare const dedupeAdjacentWith: {
  <A>(isEquivalent: (self: A, that: A) => boolean): (self: Iterable<A>) => Array<A>
  <A>(self: Iterable<A>, isEquivalent: (self: A, that: A) => boolean): Array<A>
}

Source

Since v2.0.0

dedupeWith

Removes duplicates using a custom equivalence, preserving the order of the first occurrence.

When to use

Use to remove all duplicate elements with a custom equivalence when default equality is not appropriate.

Example (Deduplicating with custom equality)

import { Array } from "effect"

console.log(Array.dedupeWith([1, 2, 2, 3, 3, 3], (a, b) => a === b)) // [1, 2, 3]

See

• dedupe — uses default equality
• dedupeAdjacentWith — only dedupes consecutive elements

Signature

declare const dedupeWith: {
  <S extends Iterable<any>>(
    isEquivalent: (self: ReadonlyArray.Infer<S>, that: ReadonlyArray.Infer<S>) => boolean
  ): (self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
  <A>(self: NonEmptyReadonlyArray<A>, isEquivalent: (self: A, that: A) => boolean): NonEmptyArray<A>
  <A>(self: Iterable<A>, isEquivalent: (self: A, that: A) => boolean): Array<A>
}

Source

Since v2.0.0

difference

Computes elements in the first array that are not in the second, using Equal.equivalence().

When to use

Use when you need to keep values from the first array that are absent from the second and the default Equal.equivalence() comparison is appropriate.

Example (Computing array differences)

import { Array } from "effect"

console.log(Array.difference([1, 2, 3], [2, 3, 4])) // [1]

See

• differenceWith — use custom equality
• union — elements in either array
• intersection — elements in both arrays

Signature

declare const difference: {
  <A>(that: Iterable<A>): (self: Iterable<A>) => Array<A>
  <A>(self: Iterable<A>, that: Iterable<A>): Array<A>
}

Source

Since v2.0.0

differenceWith

Computes elements in the first array that are not in the second, using a custom equivalence.

When to use

Use when you need to keep only values from the first array and equality must be defined by a custom comparator, such as matching objects by id.

Example (Computing differences with custom equality)

import { Array } from "effect"

const diff = Array.differenceWith<number>((a, b) => a === b)([1, 2, 3], [2, 3, 4])
console.log(diff) // [1]

See

• difference for the Equal.equivalence() variant
• unionWith for keeping values from either array with custom equality
• intersectionWith for keeping values present in both arrays with custom equality

Signature

declare const differenceWith: <A>(isEquivalent: (self: A, that: A) => boolean) => {
  (that: Iterable<A>): (self: Iterable<A>) => Array<A>
  (self: Iterable<A>, that: Iterable<A>): Array<A>
}

Source

Since v2.0.0

every

Checks whether all elements satisfy the predicate. Supports refinements for type narrowing.

When to use

Use to check whether every array element satisfies a predicate, including refinement-based type narrowing.

Example (Testing all elements)

import { Array } from "effect"

console.log(Array.every([2, 4, 6], (x) => x % 2 === 0)) // true
console.log(Array.every([2, 3, 6], (x) => x % 2 === 0)) // false

See

• some — test if any element matches

Signature

declare const every: {
  <A, B extends A>(
    refinement: (a: NoInfer<A>, i: number) => a is B
  ): (self: ReadonlyArray<A>) => self is ReadonlyArray<B>
  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: ReadonlyArray<A>) => boolean
  <A, B extends A>(self: ReadonlyArray<A>, refinement: (a: A, i: number) => a is B): self is ReadonlyArray<B>
  <A>(self: ReadonlyArray<A>, predicate: (a: A, i: number) => boolean): boolean
}

Source

Since v2.0.0

findFirst

Returns the first element matching a predicate, refinement, or mapping function, wrapped in Option.

When to use

Use to scan an iterable in iteration order and return the first selected element or mapped value as an Option.

Details

Accepts a predicate (a, i) => boolean, a refinement, or a function (a, i) => Option<B> for simultaneous find-and-transform. If no element matches, this returns Option.none().

Example (Finding the first match)

import { Array } from "effect"

console.log(Array.findFirst([1, 2, 3, 4, 5], (x) => x > 3)) // Option.some(4)

See

• findLast — search from the end
• findFirstIndex — get the index instead
• findFirstWithIndex — get both element and index

Signature

declare const findFirst: {
  <A, B>(f: (a: NoInfer<A>, i: number) => Option.Option<B>): (self: Iterable<A>) => Option.Option<B>
  <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Option.Option<B>
  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option.Option<A>
  <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option.Option<B>): Option.Option<B>
  <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Option.Option<B>
  <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option.Option<A>
}

Source

Since v2.0.0

findFirstIndex

Returns the index of the first element matching the predicate, wrapped in an Option.

When to use

Use to find the index of the first matching element from the start of an iterable.

Example (Finding an index)

import { Array } from "effect"

console.log(Array.findFirstIndex([5, 3, 8, 9], (x) => x > 5)) // Option.some(2)

See

• findLastIndex — search from the end
• findFirst — get the element itself

Signature

declare const findFirstIndex: {
  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option.Option<number>
  <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option.Option<number>
}

Source

Since v2.0.0

findFirstWithIndex

Returns the first selected value together with its index, wrapped in an Option.

When to use

Use to find both the first matching element and its index in one pass.

Details

Accepts a predicate, a refinement, or a function returning Option. For an Option-returning function, returns [mappedValue, index] for the first Some, or Option.none() if no element is selected.

Example (Finding element with its index)

import { Array } from "effect"

console.log(Array.findFirstWithIndex([1, 2, 3, 4, 5], (x) => x > 3)) // Option.some([4, 3])

See

• findFirst — get only the element
• findFirstIndex — get only the index

Signature

declare const findFirstWithIndex: {
  <A, B>(f: (a: NoInfer<A>, i: number) => Option.Option<B>): (self: Iterable<A>) => Option.Option<[B, number]>
  <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Option.Option<[B, number]>
  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option.Option<[A, number]>
  <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option.Option<B>): Option.Option<[B, number]>
  <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Option.Option<[B, number]>
  <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option.Option<[A, number]>
}

Source

Since v3.17.0

findLast

Returns the last element matching a predicate, refinement, or mapping function, wrapped in Option.

When to use

Use to find the last matching element from the end of an array.

Details

Searches from the end of the array. If no element matches, this returns Option.none().

Example (Finding the last match)

import { Array } from "effect"

console.log(Array.findLast([1, 2, 3, 4, 5], (n) => n % 2 === 0)) // Option.some(4)

See

• findFirst — search from the start
• findLastIndex — get the index instead

Signature

declare const findLast: {
  <A, B>(f: (a: NoInfer<A>, i: number) => Option.Option<B>): (self: Iterable<A>) => Option.Option<B>
  <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Option.Option<B>
  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option.Option<A>
  <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option.Option<B>): Option.Option<B>
  <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Option.Option<B>
  <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option.Option<A>
}

Source

Since v2.0.0

findLastIndex

Returns the index of the last element matching the predicate, wrapped in an Option.

When to use

Use to find the index of the last matching element from the end of an array.

Example (Finding the last matching index)

import { Array } from "effect"

console.log(Array.findLastIndex([1, 3, 8, 9], (x) => x < 5)) // Option.some(1)

See

• findFirstIndex — search from the start
• findLast — get the element itself

Signature

declare const findLastIndex: {
  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option.Option<number>
  <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option.Option<number>
}

Source

Since v2.0.0

forEach

Runs a side-effect for each element. The callback receives (element, index).

When to use

Use to iterate over an array for side-effects only, when no transformed result is needed.

Example (Iterating with side-effects)

import { Array } from "effect"

Array.forEach([1, 2, 3], (n) => console.log(n)) // 1, 2, 3

See

• map for transforming each element into a new array

Signature

declare const forEach: {
  <A>(f: (a: A, i: number) => void): (self: Iterable<A>) => void
  <A>(self: Iterable<A>, f: (a: A, i: number) => void): void
}

Source

Since v2.0.0

insertAt

Inserts an element at the specified index safely, returning a new NonEmptyArray wrapped in an Option.

When to use

Use to insert a single element at a specific position in an array.

Details

Valid indices are 0 to length, inclusive. Inserting at length appends.

Example (Inserting at an index)

import { Array } from "effect"

console.log(Array.insertAt(["a", "b", "c", "e"], 3, "d")) // Option.some(["a", "b", "c", "d", "e"])

See

• replace — replace an existing element
• modify — transform an element at an index

Signature

declare const insertAt: {
  <B>(i: number, b: B): <A>(self: Iterable<A>) => Option.Option<NonEmptyArray<A | B>>
  <A, B>(self: Iterable<A>, i: number, b: B): Option.Option<NonEmptyArray<A | B>>
}

Source

Since v2.0.0

intersection

Computes the intersection of two arrays using Equal.equivalence(). Order is determined by the first array.

When to use

Use when Effect equality is the right membership test and you want to keep values present in both inputs while preserving the first input’s order.

Example (Computing array intersections)

import { Array } from "effect"

console.log(Array.intersection([1, 2, 3], [3, 4, 1])) // [1, 3]

See

• intersectionWith — use custom equality
• union — elements in either array
• difference — elements only in the first array

Signature

declare const intersection: {
  <B>(that: Iterable<B>): <A>(self: Iterable<A>) => Array<A & B>
  <A, B>(self: Iterable<A>, that: Iterable<B>): Array<A & B>
}

Source

Since v2.0.0

intersectionWith

Computes the intersection of two arrays using a custom equivalence. Order is determined by the first array.

When to use

Use when you need to keep only values present in both arrays and equality must be defined by a custom comparator, such as matching objects by id.

Example (Computing intersections with custom equality)

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
console.log(Array.intersectionWith(isEquivalent)(array2)(array1)) // [{ id: 1 }, { id: 3 }]

See

• intersection for the Equal.equivalence() variant
• unionWith for keeping values from either array with custom equality
• differenceWith for keeping values only from the first array with custom equality

Signature

declare const intersectionWith: <A>(isEquivalent: (self: A, that: A) => boolean) => {
  (that: Iterable<A>): (self: Iterable<A>) => Array<A>
  (self: Iterable<A>, that: Iterable<A>): Array<A>
}

Source

Since v2.0.0

intersperse

Places a separator element between every pair of elements.

When to use

Use to insert a separator between elements, for example when preparing data for display or concatenation.

Details

The return type preserves NonEmptyArray. Empty inputs produce an empty result.

Example (Interspersing a separator)

import { Array } from "effect"

console.log(Array.intersperse([1, 2, 3], 0)) // [1, 0, 2, 0, 3]

See

• join — intersperse and join into a string

Signature

declare const intersperse: {
  <B>(middle: B): <S extends Iterable<any>>(self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>
  <A, B>(self: NonEmptyReadonlyArray<A>, middle: B): NonEmptyArray<A | B>
  <A, B>(self: Iterable<A>, middle: B): Array<A | B>
}

Source

Since v2.0.0

max

Returns the maximum element of a non-empty array according to the given Order.

Example (Finding the maximum)

import { Array, Order } from "effect"

console.log(Array.max([3, 1, 2], Order.Number)) // 3

See

• min — find the minimum
• sort — sort the entire array

Signature

declare const max: {
  <A>(O: Order.Order<A>): (self: NonEmptyReadonlyArray<A>) => A
  <A>(self: NonEmptyReadonlyArray<A>, O: Order.Order<A>): A
}

Source

Since v2.0.0

min

Returns the minimum element of a non-empty array according to the given Order.

Example (Finding the minimum)

import { Array, Order } from "effect"

console.log(Array.min([3, 1, 2], Order.Number)) // 1

See

• max — find the maximum
• sort — sort the entire array

Signature

declare const min: {
  <A>(O: Order.Order<A>): (self: NonEmptyReadonlyArray<A>) => A
  <A>(self: NonEmptyReadonlyArray<A>, O: Order.Order<A>): A
}

Source

Since v2.0.0

modify

Applies a function to the element at the specified index safely, returning the updated array in Option.some.

When to use

Use to derive a replacement value from an array element at a specific index while leaving the other elements unchanged.

Details

Returns Option.none() when the index is out of bounds.

Example (Modifying an element)

import { Array } from "effect"

console.log(Array.modify([1, 2, 3, 4], 2, (n) => n * 2)) // Option.some([1, 2, 6, 4])
console.log(Array.modify([1, 2, 3, 4], 5, (n) => n * 2)) // Option.none()

See

• replace — set a fixed value at an index
• modifyHeadNonEmpty — modify the first element
• modifyLastNonEmpty — modify the last element

Signature

declare const modify: {
  <A, B, S extends Iterable<A> = Iterable<A>>(
    i: number,
    f: (a: ReadonlyArray.Infer<S>) => B
  ): (self: S) => Option.Option<ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>>
  <A, B, S extends Iterable<A> = Iterable<A>>(
    self: S,
    i: number,
    f: (a: ReadonlyArray.Infer<S>) => B
  ): Option.Option<ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>>
}

Source

Since v2.0.0

modifyHeadNonEmpty

Applies a function to the first element of a non-empty array, returning a new array.

When to use

Use to transform the first element of a non-empty array while preserving the rest.

Example (Modifying the head)

import { Array } from "effect"

console.log(Array.modifyHeadNonEmpty([1, 2, 3], (n) => n * 10)) // [10, 2, 3]

See

• setHeadNonEmpty — replace with a fixed value
• modifyLastNonEmpty — modify the last element

Signature

declare const modifyHeadNonEmpty: {
  <A, B>(f: (a: A) => B): (self: NonEmptyReadonlyArray<A>) => NonEmptyArray<A | B>
  <A, B>(self: NonEmptyReadonlyArray<A>, f: (a: A) => B): NonEmptyArray<A | B>
}

Source

Since v4.0.0

modifyLastNonEmpty

Applies a function to the last element of a non-empty array, returning a new array.

When to use

Use when you already know the array is non-empty and the new last element depends on the current last element.

Example (Modifying the last element)

import { Array } from "effect"

console.log(Array.modifyLastNonEmpty([1, 2, 3], (n) => n * 2)) // [1, 2, 6]

See

• setLastNonEmpty — replace with a fixed value
• modifyHeadNonEmpty — modify the first element

Signature

declare const modifyLastNonEmpty: {
  <A, B>(f: (a: A) => B): (self: NonEmptyReadonlyArray<A>) => NonEmptyArray<A | B>
  <A, B>(self: NonEmptyReadonlyArray<A>, f: (a: A) => B): NonEmptyArray<A | B>
}

Source

Since v4.0.0

pad

Pads or truncates an array to exactly n elements, filling with fill if the array is shorter, or slicing if longer.

When to use

Use to ensure an array has a specific length, padding with a fill value or truncating as needed.

Details

Returns an empty array when n <= 0.

Example (Padding an array)

import { Array } from "effect"

console.log(Array.pad([1, 2, 3], 6, 0)) // [1, 2, 3, 0, 0, 0]

See

• take — truncate without padding
• replicate — create an array of a single repeated value

Signature

declare const pad: {
  <A, T>(n: number, fill: T): (self: Array<A>) => Array<A | T>
  <A, T>(self: Array<A>, n: number, fill: T): Array<A | T>
}

Source

Since v3.8.4

remove

Removes the element at the specified index, returning a new array. If the index is out of bounds, returns a copy of the original.

When to use

Use when you want a missing index to be a no-op and need a fresh array result instead of an optional failure.

Example (Removing an element)

import { Array } from "effect"

console.log(Array.remove([1, 2, 3, 4], 2)) // [1, 2, 4]
console.log(Array.remove([1, 2, 3, 4], 5)) // [1, 2, 3, 4]

See

• insertAt — insert an element
• filter — remove elements by predicate

Signature

declare const remove: { (i: number): <A>(self: Iterable<A>) => Array<A>; <A>(self: Iterable<A>, i: number): Array<A> }

Source

Since v2.0.0

replace

Replaces the element at the specified index safely with a new value, returning the updated array in Option.some.

When to use

Use to set a fixed replacement value at a specific index.

Details

Returns Option.none() when the index is out of bounds.

Example (Replacing an element)

import { Array } from "effect"

console.log(Array.replace([1, 2, 3], 1, 4)) // Option.some([1, 4, 3])

See

• modify — transform an element with a function
• insertAt — insert without removing

Signature

declare const replace: {
  <B>(
    i: number,
    b: B
  ): <A, S extends Iterable<A> = Iterable<A>>(
    self: S
  ) => Option.Option<ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>>
  <A, B, S extends Iterable<A> = Iterable<A>>(
    self: S,
    i: number,
    b: B
  ): Option.Option<ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>>
}

Source

Since v2.0.0

reverse

Reverses an iterable into a new array.

When to use

Use to reverse an iterable into a new array without mutating the original input.

Details

Preserves NonEmptyArray in the return type.

Example (Reversing an array)

import { Array } from "effect"

console.log(Array.reverse([1, 2, 3, 4])) // [4, 3, 2, 1]

Signature

declare const reverse: <S extends Iterable<any>>(
  self: S
) => S extends NonEmptyReadonlyArray<infer A> ? NonEmptyArray<A> : S extends Iterable<infer A> ? Array<A> : never

Source

Since v2.0.0

rotate

Transforms an array by rotating it n steps. Positive n rotates right; negative n rotates left.

When to use

Use when elements should wrap around the end of the array rather than being dropped.

Details

n is rounded to the nearest integer before rotating. The return type preserves NonEmptyArray. Empty arrays, or rotations normalized to 0, return a copy.

Example (Rotating elements)

import { Array } from "effect"

console.log(Array.rotate(["a", "b", "c", "d"], 2)) // ["c", "d", "a", "b"]

See

• take for taking a fixed number of elements from the start
• drop for dropping a fixed number of elements from the start

Signature

declare const rotate: {
  (n: number): <S extends Iterable<any>>(self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
  <A>(self: NonEmptyReadonlyArray<A>, n: number): NonEmptyArray<A>
  <A>(self: Iterable<A>, n: number): Array<A>
}

Source

Since v2.0.0

setHeadNonEmpty

Replaces the first element of a non-empty array with a new value.

When to use

Use when you already know the array is non-empty and the replacement value does not depend on the current first element.

Example (Setting the head)

import { Array } from "effect"

console.log(Array.setHeadNonEmpty([1, 2, 3], 10)) // [10, 2, 3]

See

• modifyHeadNonEmpty — transform the head with a function
• setLastNonEmpty — replace the last element

Signature

declare const setHeadNonEmpty: {
  <B>(b: B): <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray<A | B>
  <A, B>(self: NonEmptyReadonlyArray<A>, b: B): NonEmptyArray<A | B>
}

Source

Since v4.0.0

setLastNonEmpty

Replaces the last element of a non-empty array with a new value.

When to use

Use when you already know the array is non-empty and the replacement value does not depend on the current last element.

Example (Setting the last element)

import { Array } from "effect"

console.log(Array.setLastNonEmpty([1, 2, 3], 4)) // [1, 2, 4]

See

• modifyLastNonEmpty — transform the last element with a function
• setHeadNonEmpty — replace the first element

Signature

declare const setLastNonEmpty: {
  <B>(b: B): <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray<A | B>
  <A, B>(self: NonEmptyReadonlyArray<A>, b: B): NonEmptyArray<A | B>
}

Source

Since v4.0.0

some

Checks whether at least one element satisfies the predicate. Narrows the type to NonEmptyReadonlyArray on success.

Example (Testing for any match)

import { Array } from "effect"

console.log(Array.some([1, 3, 4], (x) => x % 2 === 0)) // true
console.log(Array.some([1, 3, 5], (x) => x % 2 === 0)) // false

See

• every — test if all elements match
• contains — test for a specific value

Signature

declare const some: {
  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: ReadonlyArray<A>) => self is NonEmptyReadonlyArray<A>
  <A>(self: ReadonlyArray<A>, predicate: (a: A, i: number) => boolean): self is NonEmptyReadonlyArray<A>
}

Source

Since v2.0.0

sortWith

Sorts an array by a derived key using a mapping function and an Order for that key.

When to use

Use when you need to sort values by a derived key, such as a string length or object field, while keeping the original values.

Details

Equivalent to sort(Order.mapInput(order, f)), but more convenient.

Example (Sorting strings by length)

import { Array, Order } from "effect"

console.log(Array.sortWith(["aaa", "b", "cc"], (s) => s.length, Order.Number))
// ["b", "cc", "aaa"]

See

• sort for sorting with an Order that compares the elements directly
• sortBy for sorting with multiple Orders applied in sequence

Signature

declare const sortWith: {
  <S extends Iterable<any>, B>(
    f: (a: ReadonlyArray.Infer<S>) => B,
    order: Order.Order<B>
  ): (self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
  <A, B>(self: NonEmptyReadonlyArray<A>, f: (a: A) => B, O: Order.Order<B>): NonEmptyArray<A>
  <A, B>(self: Iterable<A>, f: (a: A) => B, order: Order.Order<B>): Array<A>
}

Source

Since v2.0.0

union

Computes the union of two arrays, removing duplicates using Equal.equivalence().

Example (Computing array unions)

import { Array } from "effect"

console.log(Array.union([1, 2], [2, 3])) // [1, 2, 3]

See

• unionWith — use custom equality
• intersection — elements in both arrays
• difference — elements only in the first array

Signature

declare const union: {
  <T extends Iterable<any>>(
    that: T
  ): <S extends Iterable<any>>(
    self: S
  ) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>
  <A, B>(self: NonEmptyReadonlyArray<A>, that: ReadonlyArray<B>): NonEmptyArray<A | B>
  <A, B>(self: ReadonlyArray<A>, that: NonEmptyReadonlyArray<B>): NonEmptyArray<A | B>
  <A, B>(self: Iterable<A>, that: Iterable<B>): Array<A | B>
}

Source

Since v2.0.0

unionWith

Computes the union of two arrays using a custom equivalence, removing duplicates.

When to use

Use when you need the union of two arrays but duplicate detection must use a custom equivalence instead of the default Equal.equivalence().

Example (Computing unions with custom equality)

import { Array } from "effect"

console.log(Array.unionWith([1, 2], [2, 3], (a, b) => a === b)) // [1, 2, 3]

See

• union for the Equal.equivalence() variant
• intersectionWith for keeping elements present in both arrays
• differenceWith for keeping elements present only in the first array

Signature

declare const unionWith: {
  <S extends Iterable<any>, T extends Iterable<any>>(
    that: T,
    isEquivalent: (self: ReadonlyArray.Infer<S>, that: ReadonlyArray.Infer<T>) => boolean
  ): (self: S) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>
  <A, B>(
    self: NonEmptyReadonlyArray<A>,
    that: Iterable<B>,
    isEquivalent: (self: A, that: B) => boolean
  ): NonEmptyArray<A | B>
  <A, B>(
    self: Iterable<A>,
    that: NonEmptyReadonlyArray<B>,
    isEquivalent: (self: A, that: B) => boolean
  ): NonEmptyArray<A | B>
  <A, B>(self: Iterable<A>, that: Iterable<B>, isEquivalent: (self: A, that: B) => boolean): Array<A | B>
}

Source

Since v2.0.0

filtering

filter

Keeps only elements satisfying a predicate (or refinement).

When to use

Use to filter an iterable into a new array of original elements that satisfy a boolean predicate or refinement.

Details

The predicate receives (element, index). Refinements are supported for type narrowing.

Example (Filtering even numbers)

import { Array } from "effect"

console.log(Array.filter([1, 2, 3, 4], (x) => x % 2 === 0)) // [2, 4]

See

• partition — split into matching and non-matching
• filterMap for transforming while filtering

Signature

declare const filter: {
  <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Array<B>
  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Array<A>
  <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Array<B>
  <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Array<A>
}

Source

Since v2.0.0

filterMap

Keeps transformed values for elements where a Filter succeeds.

When to use

Use to filter an iterable with a Result-returning transformation while discarding failures.

Details

The filter receives (element, index). Failures are discarded.

Example (Filtering and transforming)

import { Array, Result } from "effect"

console.log(Array.filterMap([1, 2, 3, 4], (n) => (n % 2 === 0 ? Result.succeed(n * 10) : Result.failVoid)))
// [20, 40]

See

• filter — keep original elements matching a predicate
• partition for keeping both failures and successes

Signature

declare const filterMap: {
  <A, B, X>(f: (input: NoInfer<A>, i: number) => Result.Result<B, X>): (self: Iterable<A>) => Array<B>
  <A, B, X>(self: Iterable<A>, f: (input: A, i: number) => Result.Result<B, X>): Array<B>
}

Source

Since v2.0.0

getFailures

Extracts all failure values from an iterable of Results, discarding successes.

When to use

Use when you can drop the success channel and only need the failure payloads, not the original result wrappers.

Example (Extracting failures)

import { Array, Result } from "effect"

console.log(Array.getFailures([Result.succeed(1), Result.fail("err"), Result.succeed(2)]))
// ["err"]

See

• getSuccesses — extract success values
• separate — split into failures and successes

Signature

declare const getFailures: <T extends Iterable<Result.Result<any, any>>>(
  self: T
) => Array<Result.Result.Failure<ReadonlyArray.Infer<T>>>

Source

Since v4.0.0

getSomes

Extracts all Some values from an iterable of Options, discarding Nones.

When to use

Use to collect only present values from an iterable of Option values while discarding None values.

Example (Extracting Some values)

import { Array, Option } from "effect"

console.log(Array.getSomes([Option.some(1), Option.none(), Option.some(2)])) // [1, 2]

See

• fromOption — convert a single Option
• getSuccesses — extract successes from Results

Signature

declare const getSomes: <T extends Iterable<Option.Option<X>>, X = any>(
  self: T
) => Array<Option.Option.Value<ReadonlyArray.Infer<T>>>

Source

Since v2.0.0

getSuccesses

Extracts all success values from an iterable of Results, discarding failures.

When to use

Use when you can drop the failure channel and only need the success payloads, not the original result wrappers.

Example (Extracting successes)

import { Array, Result } from "effect"

console.log(Array.getSuccesses([Result.succeed(1), Result.fail("err"), Result.succeed(2)]))
// [1, 2]

See

• getFailures — extract failure values
• separate — split into failures and successes

Signature

declare const getSuccesses: <T extends Iterable<Result.Result<any, any>>>(
  self: T
) => Array<Result.Result.Success<ReadonlyArray.Infer<T>>>

Source

Since v4.0.0

partition

Splits an iterable using a Filter into failures and successes.

When to use

Use to partition an iterable by evaluating each element with a Result-returning filter and keeping both failure and success values.

Details

Returns [excluded, satisfying]. The filter receives (element, index).

Example (Partitioning with a filter)

import { Array, Result } from "effect"

console.log(Array.partition([1, -2, 3], (n, i) => (n > 0 ? Result.succeed(n + i) : Result.fail(`negative:${n}`))))
// [["negative:-2"], [1, 5]]

See

• filter — keep only matching elements
• filterMap for discarding failures
• separate — split an iterable of Result values

Signature

declare const partition: {
  <A, Pass, Fail>(
    f: (input: NoInfer<A>, i: number) => Result.Result<Pass, Fail>
  ): (self: Iterable<A>) => [excluded: Array<Fail>, satisfying: Array<Pass>]
  <A, Pass, Fail>(
    self: Iterable<A>,
    f: (input: A, i: number) => Result.Result<Pass, Fail>
  ): [excluded: Array<Fail>, satisfying: Array<Pass>]
}

Source

Since v2.0.0

separate

Separates an iterable of Results into failure values and success values.

When to use

Use to split an iterable of Result values into failure and success arrays.

Details

Returns [failures, successes]. This is equivalent to partition(identity).

Example (Separating Results)

import { Array, Result } from "effect"

const [failures, successes] = Array.separate([Result.succeed(1), Result.fail("error"), Result.succeed(2)])
console.log(failures) // ["error"]
console.log(successes) // [1, 2]

See

• getFailures — extract only failures
• getSuccesses — extract only successes
• partition for computing Result values while splitting

Signature

declare const separate: <T extends Iterable<Result.Result<any, any>>>(
  self: T
) => [
  failures: Array<Result.Result.Failure<ReadonlyArray.Infer<T>>>,
  successes: Array<Result.Result.Success<ReadonlyArray.Infer<T>>>
]

Source

Since v2.0.0

folding

countBy

Computes the number of elements in an iterable that satisfy a predicate.

When to use

Use when you need to count how many elements of an iterable satisfy a predicate.

Details

The predicate receives both the element and its index. Empty iterables return 0.

Example (Counting even numbers)

import { Array } from "effect"

const result = Array.countBy([1, 2, 3, 4, 5], (n) => n % 2 === 0)
console.log(result) // 2

See

• filter — when you need the matching elements, not just the count

Signature

declare const countBy: {
  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => number
  <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): number
}

Source

Since v3.16.0

getReadonlyReducerConcat

Returns a Reducer that combines ReadonlyArray values by concatenation.

See

• makeReducerConcat — mutable Array variant

Signature

declare const getReadonlyReducerConcat: <A>() => Reducer.Reducer<ReadonlyArray<A>>

Source

Since v4.0.0

join

Joins string elements with a separator.

Example (Joining strings)

import { Array } from "effect"

console.log(Array.join(["a", "b", "c"], "-")) // "a-b-c"

See

• intersperse — insert separator elements without joining

Signature

declare const join: { (sep: string): (self: Iterable<string>) => string; (self: Iterable<string>, sep: string): string }

Source

Since v2.0.0

makeReducerConcat

Returns a Reducer that combines Array values by concatenation.

See

• getReadonlyReducerConcat — readonly variant

Signature

declare const makeReducerConcat: <A>() => Reducer.Reducer<Array<A>>

Source

Since v4.0.0

mapAccum

Maps over an array while threading an accumulator through each step, returning both the final state and the mapped array.

When to use

Use when you need to map while threading state through each element and keep the final state.

Details

Combines map and reduce in a single pass. The callback receives the current state, element, and index, and returns [nextState, mappedValue]. The result is [finalState, mappedArray]. This can be used in both data-first and data-last style.

Example (Running sum alongside mapped values)

import { Array } from "effect"

const result = Array.mapAccum([1, 2, 3], 0, (acc, n) => [acc + n, acc + n])
console.log(result) // [6, [1, 3, 6]]

See

• scan — when you only need the accumulated results (not the final state)
• reduce — when you only need the final accumulated value

Signature

declare const mapAccum: {
  <S, A, B, I extends Iterable<A> = Iterable<A>>(
    s: S,
    f: (s: S, a: ReadonlyArray.Infer<I>, i: number) => readonly [S, B]
  ): (self: I) => [state: S, mappedArray: ReadonlyArray.With<I, B>]
  <S, A, B, I extends Iterable<A> = Iterable<A>>(
    self: I,
    s: S,
    f: (s: S, a: ReadonlyArray.Infer<I>, i: number) => readonly [S, B]
  ): [state: S, mappedArray: ReadonlyArray.With<I, B>]
}

Source

Since v2.0.0

reduce

Folds an iterable from left to right into a single value.

When to use

Use to combine all elements into one accumulated value from left to right.

Details

The function receives (accumulator, element, index).

Example (Summing an array)

import { Array } from "effect"

console.log(Array.reduce([1, 2, 3], 0, (acc, n) => acc + n)) // 6

See

• reduceRight — fold from right to left
• scan — fold keeping intermediate values

Signature

declare const reduce: {
  <B, A>(b: B, f: (b: B, a: A, i: number) => B): (self: Iterable<A>) => B
  <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A, i: number) => B): B
}

Source

Since v2.0.0

reduceRight

Folds an iterable from right to left into a single value.

When to use

Use when you need to fold values from right to left.

Details

The function receives (accumulator, element, index).

Example (Folding from right to left)

import { Array } from "effect"

console.log(Array.reduceRight([1, 2, 3], 0, (acc, n) => acc + n)) // 6

See

• reduce — fold from left to right
• scanRight — fold keeping intermediate values

Signature

declare const reduceRight: {
  <B, A>(b: B, f: (b: B, a: A, i: number) => B): (self: Iterable<A>) => B
  <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A, i: number) => B): B
}

Source

Since v2.0.0

scan

Folds left-to-right while keeping every intermediate accumulator value.

When to use

Use to compute a running accumulator where each intermediate value is needed.

Details

The output length is input.length + 1 because it starts with the initial value. The result is always a NonEmptyArray. Use reduce if you only need the final accumulated value.

Example (Running totals)

import { Array } from "effect"

const result = Array.scan([1, 2, 3, 4], 0, (acc, value) => acc + value)
console.log(result) // [0, 1, 3, 6, 10]

See

• scanRight — right-to-left scan
• reduce — fold without intermediate values

Signature

declare const scan: {
  <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<A>) => NonEmptyArray<B>
  <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A) => B): NonEmptyArray<B>
}

Source

Since v2.0.0

scanRight

Folds right-to-left while keeping every intermediate accumulator value.

When to use

Use to compute a running accumulator from right to left where each intermediate value is needed.

Details

The output length is input.length + 1 because it ends with the initial value. The result is always a NonEmptyArray.

Example (Scanning running totals in reverse)

import { Array } from "effect"

const result = Array.scanRight([1, 2, 3, 4], 0, (acc, value) => acc + value)
console.log(result) // [10, 9, 7, 4, 0]

See

• scan — left-to-right scan
• reduceRight — fold without intermediate values

Signature

declare const scanRight: {
  <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<A>) => NonEmptyArray<B>
  <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A) => B): NonEmptyArray<B>
}

Source

Since v2.0.0

getters

drop

Removes the first n elements, creating a new array.

When to use

Use to keep the suffix of an iterable after skipping a fixed number of leading elements.

Details

n is clamped to [0, length]. When n <= 0, this returns a copy of the full array.

Example (Dropping from the start)

import { Array } from "effect"

console.log(Array.drop([1, 2, 3, 4, 5], 2)) // [3, 4, 5]

See

• dropRight for removing a fixed number of elements from the end
• dropWhile for removing a prefix based on a predicate instead of a fixed count
• take for keeping a fixed number of elements from the start

Signature

declare const drop: { (n: number): <A>(self: Iterable<A>) => Array<A>; <A>(self: Iterable<A>, n: number): Array<A> }

Source

Since v2.0.0

dropRight

Removes the last n elements, creating a new array.

When to use

Use to remove the last n elements from an iterable.

Details

n is clamped to [0, length].

Example (Dropping from the end)

import { Array } from "effect"

console.log(Array.dropRight([1, 2, 3, 4, 5], 2)) // [1, 2, 3]

See

• drop — remove from the start
• takeRight — keep from the end

Signature

declare const dropRight: {
  (n: number): <A>(self: Iterable<A>) => Array<A>
  <A>(self: Iterable<A>, n: number): Array<A>
}

Source

Since v2.0.0

dropWhile

Drops elements from the start while the predicate holds, returning the rest.

When to use

Use to remove a leading prefix of elements that satisfy a predicate.

Details

The predicate receives (element, index).

Example (Dropping while condition holds)

import { Array } from "effect"

console.log(Array.dropWhile([1, 2, 3, 4, 5], (x) => x < 4)) // [4, 5]

See

• takeWhile — keep the matching prefix instead
• drop — drop a fixed count

Signature

declare const dropWhile: {
  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Array<A>
  <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Array<A>
}

Source

Since v2.0.0

dropWhileFilter

Drops elements from the start while a Filter succeeds.

When to use

Use when you need to drop a prefix from an iterable by computing a Result per element instead of using a simple boolean predicate.

Details

The filter receives (element, index). The result contains the remaining original elements after the first filter failure.

See

• dropWhile for dropping a prefix with a simple boolean predicate
• takeWhileFilter for keeping only the matching prefix

Signature

declare const dropWhileFilter: {
  <A, B, X>(f: (input: NoInfer<A>, i: number) => Result.Result<B, X>): (self: Iterable<A>) => Array<A>
  <A, B, X>(self: Iterable<A>, f: (input: A, i: number) => Result.Result<B, X>): Array<A>
}

Source

Since v4.0.0

get

Reads an element at the given index safely, returning Option.some or Option.none if the index is out of bounds.

When to use

Use when you need to read an array element by index and handle an out-of-bounds index as Option.none.

Details

The index is floored to an integer. This never throws.

Example (Accessing indexes safely)

import { Array } from "effect"

console.log(Array.get([1, 2, 3], 1)) // Some(2)
console.log(Array.get([1, 2, 3], 10)) // None

See

• getUnsafe for indexed access that throws when the index is out of bounds
• head for reading the first element as an Option
• last for reading the last element as an Option

Signature

declare const get: {
  (index: number): <A>(self: ReadonlyArray<A>) => Option.Option<A>
  <A>(self: ReadonlyArray<A>, index: number): Option.Option<A>
}

Source

Since v2.0.0

head

Returns the first element of an array safely wrapped in Option.some, or Option.none if the array is empty.

When to use

Use to safely get the first element of an array that may be empty.

Example (Getting the first element)

import { Array } from "effect"

console.log(Array.head([1, 2, 3])) // Some(1)
console.log(Array.head([])) // None

See

• headNonEmpty — direct access when array is known non-empty
• last — get the last element

Signature

declare const head: <A>(self: ReadonlyArray<A>) => Option.Option<A>

Source

Since v2.0.0

headNonEmpty

Returns the first element of a NonEmptyReadonlyArray directly (no Option wrapper).

When to use

Use to get the first element without Option wrapping when the array is known to be non-empty.

Example (Getting the head of a non-empty array)

import { Array } from "effect"

console.log(Array.headNonEmpty([1, 2, 3, 4])) // 1

See

• head — safe version for possibly-empty arrays

Signature

declare const headNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => A

Source

Since v2.0.0

init

Returns all elements except the last safely, wrapped in an Option.

When to use

Use to safely get all elements before the last when the iterable may be empty.

Details

Allocates a new array via slice(0, -1). Empty inputs return Option.none().

Example (Getting init)

import { Array } from "effect"

console.log(Array.init([1, 2, 3, 4])) // Option.some([1, 2, 3])
console.log(Array.init([])) // Option.none()

See

• initNonEmpty — when the array is known non-empty
• tail — all elements except the first

Signature

declare const init: <A>(self: Iterable<A>) => Option.Option<Array<A>>

Source

Since v2.0.0

initNonEmpty

Returns all elements except the last of a NonEmptyReadonlyArray.

When to use

Use to get all elements before the last when the array is known to be non-empty.

Example (Getting init of a non-empty array)

import { Array } from "effect"

console.log(Array.initNonEmpty([1, 2, 3, 4])) // [1, 2, 3]

See

• init — safe version for possibly-empty arrays
• tailNonEmpty — all elements except the first

Signature

declare const initNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => Array<A>

Source

Since v2.0.0

last

Returns the last element of an array safely wrapped in Option.some, or Option.none if the array is empty.

When to use

Use to safely get the last element of an array that may be empty.

Example (Getting the last element)

import { Array } from "effect"

console.log(Array.last([1, 2, 3])) // Some(3)
console.log(Array.last([])) // None

See

• lastNonEmpty — direct access when array is known non-empty
• head — get the first element

Signature

declare const last: <A>(self: ReadonlyArray<A>) => Option.Option<A>

Source

Since v2.0.0

lastNonEmpty

Returns the last element of a NonEmptyReadonlyArray directly (no Option wrapper).

When to use

Use to get the last element without Option wrapping when the array is known to be non-empty.

Example (Getting the last of a non-empty array)

import { Array } from "effect"

console.log(Array.lastNonEmpty([1, 2, 3, 4])) // 4

See

• last — safe version for possibly-empty arrays

Signature

declare const lastNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => A

Source

Since v2.0.0

length

Returns the number of elements in a ReadonlyArray.

When to use

Use when you need length as a composable function rather than a property access.

Example (Getting the length)

import { Array } from "effect"

console.log(Array.length([1, 2, 3])) // 3

Signature

declare const length: <A>(self: ReadonlyArray<A>) => number

Source

Since v2.0.0

tail

Returns all elements except the first safely, wrapped in an Option.

When to use

Use to safely get all elements after the first when the iterable may be empty.

Details

Allocates a new array via slice(1). Empty inputs return Option.none().

Example (Getting the tail)

import { Array } from "effect"

console.log(Array.tail([1, 2, 3, 4])) // Option.some([2, 3, 4])
console.log(Array.tail([])) // Option.none()

See

• tailNonEmpty — when the array is known non-empty
• init — all elements except the last

Signature

declare const tail: <A>(self: Iterable<A>) => Option.Option<Array<A>>

Source

Since v2.0.0

tailNonEmpty

Returns all elements except the first of a NonEmptyReadonlyArray.

When to use

Use to get all elements after the first when the array is known to be non-empty.

Example (Getting the tail of a non-empty array)

import { Array } from "effect"

console.log(Array.tailNonEmpty([1, 2, 3, 4])) // [2, 3, 4]

See

• tail — safe version for possibly-empty arrays
• initNonEmpty — all elements except the last

Signature

declare const tailNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => Array<A>

Source

Since v2.0.0

take

Keeps the first n elements, creating a new array.

When to use

Use to keep up to the first n elements from an iterable as a new array.

Details

n is clamped to [0, length]. Returns an empty array when n <= 0.

Example (Taking from the start)

import { Array } from "effect"

console.log(Array.take([1, 2, 3, 4, 5], 3)) // [1, 2, 3]

See

• takeRight for keeping elements from the end
• takeWhile for keeping an initial prefix while a predicate holds
• drop for removing elements from the start

Signature

declare const take: { (n: number): <A>(self: Iterable<A>) => Array<A>; <A>(self: Iterable<A>, n: number): Array<A> }

Source

Since v2.0.0

takeRight

Keeps the last n elements, creating a new array.

When to use

Use to keep the last n elements of an iterable.

Details

n is clamped to [0, length]. Returns an empty array when n <= 0.

Example (Taking from the end)

import { Array } from "effect"

console.log(Array.takeRight([1, 2, 3, 4, 5], 3)) // [3, 4, 5]

See

• take — keep from the start
• dropRight — remove from the end

Signature

declare const takeRight: {
  (n: number): <A>(self: Iterable<A>) => Array<A>
  <A>(self: Iterable<A>, n: number): Array<A>
}

Source

Since v2.0.0

takeWhile

Takes elements from the start while the predicate holds, stopping at the first element that fails.

When to use

Use to keep the leading elements of an iterable while each element satisfies a predicate, returning the retained prefix as an array.

Details

Supports refinements for type narrowing. The predicate receives (element, index).

Example (Taking while condition holds)

import { Array } from "effect"

console.log(Array.takeWhile([1, 3, 2, 4, 1, 2], (x) => x < 4)) // [1, 3, 2]

See

• take for keeping a fixed number of leading elements
• dropWhile for removing the matching prefix and keeping the rest
• span for splitting the matching prefix from the remaining elements

Signature

declare const takeWhile: {
  <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Array<B>
  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Array<A>
  <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Array<B>
  <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Array<A>
}

Source

Since v2.0.0

takeWhileFilter

Takes elements from the start while a Filter succeeds, collecting transformed values.

When to use

Use when you need to take a prefix from an iterable while a function can successfully extract or transform elements, stopping at the first element that produces a failure result.

Details

The filter receives (element, index) and processing stops at the first filter failure.

See

• takeWhile for taking a prefix based on a boolean predicate

Signature

declare const takeWhileFilter: {
  <A, B, X>(f: (input: NoInfer<A>, i: number) => Result.Result<B, X>): (self: Iterable<A>) => Array<B>
  <A, B, X>(self: Iterable<A>, f: (input: NoInfer<A>, i: number) => Result.Result<B, X>): Array<B>
}

Source

Since v4.0.0

grouping

group

Groups consecutive equal elements using Equal.equivalence().

When to use

Use when you already have adjacent equal values and Effect’s default equality is the right comparison.

Details

Only adjacent elements are grouped.

Example (Grouping adjacent equal elements)

import { Array } from "effect"

console.log(Array.group([1, 1, 2, 2, 2, 3, 1])) // [[1, 1], [2, 2, 2], [3], [1]]

See

• groupWith — use custom equality
• groupBy — group by a key function into a record

Signature

declare const group: <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray<NonEmptyArray<A>>

Source

Since v2.0.0

groupBy

Groups elements into a record by a key-returning function. Each key maps to a NonEmptyArray of elements that produced that key.

When to use

Use to build buckets of elements indexed by a computed string or symbol key.

Details

Unlike group and groupWith, elements do not need to be adjacent to be grouped together. The key function must return a string or symbol.

Example (Grouping by a property)

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)
console.log(result)
// { A: [{ name: "Alice", group: "A" }, { name: "Charlie", group: "A" }], B: [{ name: "Bob", group: "B" }] }

See

• group — group adjacent equal elements
• groupWith — group adjacent elements by custom equality

Signature

declare const groupBy: {
  <A, K extends string | symbol>(
    f: (a: A) => K
  ): (self: Iterable<A>) => Record<Record.ReadonlyRecord.NonLiteralKey<K>, NonEmptyArray<A>>
  <A, K extends string | symbol>(
    self: Iterable<A>,
    f: (a: A) => K
  ): Record<Record.ReadonlyRecord.NonLiteralKey<K>, NonEmptyArray<A>>
}

Source

Since v2.0.0

groupWith

Groups consecutive equal elements using a custom equivalence function.

When to use

Use when you already have a non-empty array arranged so matching elements are adjacent and need a custom equivalence function.

Details

Only adjacent elements are grouped. Non-adjacent duplicates stay separate. Requires a NonEmptyReadonlyArray.

Example (Grouping consecutive equal elements)

import { Array } from "effect"

console.log(Array.groupWith(["a", "a", "b", "b", "b", "c", "a"], (x, y) => x === y))
// [["a", "a"], ["b", "b", "b"], ["c"], ["a"]]

See

• group for grouping adjacent elements with Equal.equivalence()
• groupBy for grouping all elements into a record by key, regardless of adjacency

Signature

declare const groupWith: {
  <A>(isEquivalent: (self: A, that: A) => boolean): (self: NonEmptyReadonlyArray<A>) => NonEmptyArray<NonEmptyArray<A>>
  <A>(self: NonEmptyReadonlyArray<A>, isEquivalent: (self: A, that: A) => boolean): NonEmptyArray<NonEmptyArray<A>>
}

Source

Since v2.0.0

guards

isArray

Checks whether a value is an Array.

When to use

Use to verify a value is a mutable array, narrowing its type to Array<unknown>.

Details

Acts as a type guard narrowing the input to Array<unknown> and delegates to globalThis.Array.isArray.

Example (Type-guarding an unknown value)

import { Array } from "effect"

console.log(Array.isArray(null)) // false
console.log(Array.isArray([1, 2, 3])) // true

See

• isArrayEmpty — check for an empty array
• isArrayNonEmpty — check for a non-empty array

Signature

declare const isArray: { (self: unknown): self is Array<unknown>; <T>(self: T): self is Extract<T, ReadonlyArray<any>> }

Source

Since v2.0.0

isArrayEmpty

Checks whether a mutable Array is empty, narrowing the type to [].

Example (Checking for an empty array)

import { Array } from "effect"

console.log(Array.isArrayEmpty([])) // true
console.log(Array.isArrayEmpty([1, 2, 3])) // false

See

• isReadonlyArrayEmpty — readonly variant
• isArrayNonEmpty — opposite check

Signature

declare const isArrayEmpty: <A>(self: Array<A>) => self is []

Source

Since v4.0.0

isArrayNonEmpty

Checks whether a mutable Array is non-empty, narrowing the type to NonEmptyArray.

When to use

Use when you need the narrowed value to remain a mutable Array after proving it has at least one element.

Example (Checking for a non-empty array)

import { Array } from "effect"

console.log(Array.isArrayNonEmpty([])) // false
console.log(Array.isArrayNonEmpty([1, 2, 3])) // true

See

• isReadonlyArrayNonEmpty — readonly variant
• isArrayEmpty — opposite check

Signature

declare const isArrayNonEmpty: <A>(self: Array<A>) => self is NonEmptyArray<A>

Source

Since v4.0.0

isReadonlyArrayEmpty

Checks whether a ReadonlyArray is empty, narrowing the type to readonly [].

Example (Checking for an empty readonly array)

import { Array } from "effect"

console.log(Array.isReadonlyArrayEmpty([])) // true
console.log(Array.isReadonlyArrayEmpty([1, 2, 3])) // false

See

• isArrayEmpty — mutable variant
• isReadonlyArrayNonEmpty — opposite check

Signature

declare const isReadonlyArrayEmpty: <A>(self: ReadonlyArray<A>) => self is readonly []

Source

Since v4.0.0

isReadonlyArrayNonEmpty

Checks whether a ReadonlyArray is non-empty, narrowing the type to NonEmptyReadonlyArray.

When to use

Use when you need to prove a readonly array has at least one element without requiring mutable array methods afterward.

Example (Checking for a non-empty readonly array)

import { Array } from "effect"

console.log(Array.isReadonlyArrayNonEmpty([])) // false
console.log(Array.isReadonlyArrayNonEmpty([1, 2, 3])) // true

See

• isArrayNonEmpty — mutable variant
• isReadonlyArrayEmpty — opposite check

Signature

declare const isReadonlyArrayNonEmpty: <A>(self: ReadonlyArray<A>) => self is NonEmptyReadonlyArray<A>

Source

Since v4.0.0

instances

makeEquivalence

Creates an Equivalence for arrays based on an element Equivalence. Two arrays are equivalent when they have the same length and all elements are pairwise equivalent.

Example (Comparing arrays for equality)

import { Array } from "effect"

const eq = Array.makeEquivalence<number>((a, b) => a === b)
console.log(eq([1, 2, 3], [1, 2, 3])) // true

See

• makeOrder — create an ordering for arrays

Signature

declare const makeEquivalence: <A>(
  isEquivalent: Equivalence.Equivalence<A>
) => Equivalence.Equivalence<ReadonlyArray<A>>

Source

Since v4.0.0

makeOrder

Creates an Order for arrays based on an element Order. Arrays are compared element-wise; if all compared elements are equal, shorter arrays come first.

Example (Comparing arrays)

import { Array, Order } from "effect"

const arrayOrder = Array.makeOrder(Order.Number)
console.log(arrayOrder([1, 2], [1, 3])) // -1

See

• makeEquivalence — create an equivalence for arrays

Signature

declare const makeOrder: <A>(O: Order.Order<A>) => Order.Order<ReadonlyArray<A>>

Source

Since v4.0.0

lifting

liftNullishOr

Lifts a nullable-returning function into one that returns an array: null/undefined becomes [], anything else becomes [value].

Example (Lifting a nullable function)

import { Array } from "effect"

const parseNumber = Array.liftNullishOr((s: string) => {
  const n = Number(s)
  return isNaN(n) ? null : n
})
console.log(parseNumber("123")) // [123]
console.log(parseNumber("abc")) // []

See

• fromNullishOr — convert a single nullable value
• liftOption — lift an Option-returning function

Signature

declare const liftNullishOr: <A extends Array<unknown>, B>(f: (...a: A) => B) => (...a: A) => Array<NonNullable<B>>

Source

Since v4.0.0

liftOption

Lifts an Option-returning function into one that returns an array: Some(a) becomes [a], None becomes [].

When to use

Use when an optional parser or lookup should participate in array pipelines as zero-or-one results.

Example (Lifting an Option function)

import { Array, Option } from "effect"

const parseNumber = Array.liftOption((s: string) => {
  const n = Number(s)
  return isNaN(n) ? Option.none() : Option.some(n)
})
console.log(parseNumber("123")) // [123]
console.log(parseNumber("abc")) // []

See

• liftPredicate — lift a boolean predicate
• liftResult — lift a Result-returning function

Signature

declare const liftOption: <A extends Array<unknown>, B>(f: (...a: A) => Option.Option<B>) => (...a: A) => Array<B>

Source

Since v2.0.0

liftPredicate

Lifts a predicate into an array: returns [value] if the predicate holds, [] otherwise.

Example (Wrapping values conditionally)

import { Array } from "effect"

const isEven = (n: number) => n % 2 === 0
const to = Array.liftPredicate(isEven)
console.log(to(1)) // []
console.log(to(2)) // [2]

See

• liftOption — lift an Option-returning function

Signature

declare const liftPredicate: {
  <A, B extends A>(refinement: Predicate.Refinement<A, B>): (a: A) => Array<B>
  <A>(predicate: Predicate.Predicate<A>): <B extends A>(b: B) => Array<B>
}

Source

Since v2.0.0

liftResult

Lifts a Result-returning function into one that returns an array: failures produce [], successes produce [value].

When to use

Use when a fallible parser or lookup should participate in array pipelines as zero-or-one results and the failure value should be discarded.

Example (Lifting a Result function)

import { Array, Result } from "effect"

const parseNumber = (s: string): Result.Result<number, Error> =>
  isNaN(Number(s)) ? Result.fail(new Error("Not a number")) : Result.succeed(Number(s))

const liftedParseNumber = Array.liftResult(parseNumber)
console.log(liftedParseNumber("42")) // [42]
console.log(liftedParseNumber("not a number")) // []

See

• liftOption — lift an Option-returning function
• liftPredicate — lift a boolean predicate

Signature

declare const liftResult: <A extends Array<unknown>, E, B>(f: (...a: A) => Result.Result<B, E>) => (...a: A) => Array<B>

Source

Since v4.0.0

mapping

extend

Applies a function to each suffix of the array (starting from each index), collecting the results.

When to use

Use when you need to compute a result from every suffix of an array, such as cumulative aggregations from each position.

Details

For index i, the function receives self.slice(i).

Example (Computing suffix lengths)

import { Array } from "effect"

console.log(Array.extend([1, 2, 3], (as) => as.length)) // [3, 2, 1]

See

• scan for keeping intermediate accumulator values during a fold

Signature

declare const extend: {
  <A, B>(f: (as: ReadonlyArray<A>) => B): (self: ReadonlyArray<A>) => Array<B>
  <A, B>(self: ReadonlyArray<A>, f: (as: ReadonlyArray<A>) => B): Array<B>
}

Source

Since v2.0.0

map

Transforms each element using a function, returning a new array.

When to use

Use to transform each element independently while preserving the array shape.

Details

The function receives (element, index). The return type preserves NonEmptyArray.

Example (Doubling values)

import { Array } from "effect"

console.log(Array.map([1, 2, 3], (x) => x * 2)) // [2, 4, 6]

See

• flatMap — map and flatten

Signature

declare const map: {
  <S extends ReadonlyArray<any>, B>(
    f: (a: ReadonlyArray.Infer<S>, i: number) => B
  ): (self: S) => ReadonlyArray.With<S, B>
  <S extends ReadonlyArray<any>, B>(self: S, f: (a: ReadonlyArray.Infer<S>, i: number) => B): ReadonlyArray.With<S, B>
}

Source

Since v2.0.0

models

NonEmptyArray (type alias)

A mutable array guaranteed to have at least one element.

When to use

Use when mutation is acceptable and non-emptiness must be tracked at the type level.

Details

This is the mutable counterpart of NonEmptyReadonlyArray. Most Array module functions return NonEmptyArray when the result is guaranteed non-empty.

Example (Typing a mutable non-empty array)

import type { Array } from "effect"

const nonEmpty: Array.NonEmptyArray<number> = [1, 2, 3]
nonEmpty.push(4)

See

• NonEmptyReadonlyArray — readonly counterpart
• isArrayNonEmpty — narrow an Array to this type

Signature

type [A, ...A[]] = [A, ...Array<A>]

Source

Since v2.0.0

NonEmptyReadonlyArray (type alias)

A readonly array guaranteed to have at least one element.

When to use

Use when non-emptiness must be tracked at the type level while preventing mutation. Many Array module functions accept or return this type.

Example (Typing a non-empty array)

import type { Array } from "effect"

const nonEmpty: Array.NonEmptyReadonlyArray<number> = [1, 2, 3]
const head: number = nonEmpty[0] // guaranteed to exist

See

• NonEmptyArray — mutable counterpart
• isReadonlyArrayNonEmpty — narrow a ReadonlyArray to this type

Signature

type readonly [A, ...A[]] = readonly [A, ...Array<A>]

Source

Since v2.0.0

pattern matching

match

Pattern-matches on an array, handling empty and non-empty cases separately.

When to use

Use when you need to branch on whether an array is empty.

Details

onNonEmpty receives a NonEmptyReadonlyArray. Supports both data-first and data-last usage.

Example (Branching on emptiness)

import { Array } from "effect"

const describe = Array.match({
  onEmpty: () => "empty",
  onNonEmpty: ([head, ...tail]) => `head: ${head}, tail: ${tail.length}`
})
console.log(describe([])) // "empty"
console.log(describe([1, 2, 3])) // "head: 1, tail: 2"

See

• matchLeft — destructures into head + tail
• matchRight — destructures into init + last

Signature

declare const match: {
  <B, A, C = B>(options: {
    readonly onEmpty: LazyArg<B>
    readonly onNonEmpty: (self: NonEmptyReadonlyArray<A>) => C
  }): (self: ReadonlyArray<A>) => B | C
  <A, B, C = B>(
    self: ReadonlyArray<A>,
    options: { readonly onEmpty: LazyArg<B>; readonly onNonEmpty: (self: NonEmptyReadonlyArray<A>) => C }
  ): B | C
}

Source

Since v2.0.0

matchLeft

Pattern-matches on an array from the left, providing the first element and the remaining elements separately.

When to use

Use when you need to branch on an array and handle the non-empty case as the first element plus the remaining elements.

Details

onNonEmpty receives (head, tail) where tail is the rest of the array.

Example (Destructuring head and tail)

import { Array } from "effect"

const matchLeft = Array.matchLeft({
  onEmpty: () => "empty",
  onNonEmpty: (head, tail) => `head: ${head}, tail: ${tail.length}`
})
console.log(matchLeft([])) // "empty"
console.log(matchLeft([1, 2, 3])) // "head: 1, tail: 2"

See

• match — receives the full non-empty array
• matchRight — destructures into init + last

Signature

declare const matchLeft: {
  <B, A, C = B>(options: {
    readonly onEmpty: LazyArg<B>
    readonly onNonEmpty: (head: A, tail: Array<A>) => C
  }): (self: ReadonlyArray<A>) => B | C
  <A, B, C = B>(
    self: ReadonlyArray<A>,
    options: { readonly onEmpty: LazyArg<B>; readonly onNonEmpty: (head: A, tail: Array<A>) => C }
  ): B | C
}

Source

Since v2.0.0

matchRight

Pattern-matches on an array from the right, providing all elements except the last and the last element separately.

When to use

Use when you need to branch on an array and handle the non-empty case as the elements before the last plus the last element.

Details

onNonEmpty receives (init, last) where init is everything but the last element.

Example (Destructuring init and last)

import { Array } from "effect"

const matchRight = Array.matchRight({
  onEmpty: () => "empty",
  onNonEmpty: (init, last) => `init: ${init.length}, last: ${last}`
})
console.log(matchRight([])) // "empty"
console.log(matchRight([1, 2, 3])) // "init: 2, last: 3"

See

• match — receives the full non-empty array
• matchLeft — destructures into head + tail

Signature

declare const matchRight: {
  <B, A, C = B>(options: {
    readonly onEmpty: LazyArg<B>
    readonly onNonEmpty: (init: Array<A>, last: A) => C
  }): (self: ReadonlyArray<A>) => B | C
  <A, B, C = B>(
    self: ReadonlyArray<A>,
    options: { readonly onEmpty: LazyArg<B>; readonly onNonEmpty: (init: Array<A>, last: A) => C }
  ): B | C
}

Source

Since v2.0.0

sequencing

flatMap

Maps each element to an array and flattens the results into a single array.

When to use

Use to map each array element to zero or more values and concatenate the results in one pass.

Details

The function receives (element, index). This returns NonEmptyArray when both the input and mapped arrays are non-empty.

Example (Flat mapping an array)

import { Array } from "effect"

console.log(Array.flatMap([1, 2, 3], (x) => [x, x * 2])) // [1, 2, 2, 4, 3, 6]

See

• map — transform without flattening
• flatten — flatten without mapping

Signature

declare const flatMap: {
  <S extends ReadonlyArray<any>, T extends ReadonlyArray<any>>(
    f: (a: ReadonlyArray.Infer<S>, i: number) => T
  ): (self: S) => ReadonlyArray.AndNonEmpty<S, T, ReadonlyArray.Infer<T>>
  <A, B>(self: NonEmptyReadonlyArray<A>, f: (a: A, i: number) => NonEmptyReadonlyArray<B>): NonEmptyArray<B>
  <A, B>(self: ReadonlyArray<A>, f: (a: A, i: number) => ReadonlyArray<B>): Array<B>
}

Source

Since v2.0.0

flatMapNullishOr

Maps each element with a nullable-returning function, keeping only non-null / non-undefined results.

When to use

Use when you need to map and filter in one step, where the mapper can return null or undefined to skip elements.

Example (Flat mapping with nullable values)

import { Array } from "effect"

console.log(Array.flatMapNullishOr([1, 2, 3], (n) => (n % 2 === 0 ? null : n)))
// [1, 3]

See

• flatMap for mapping each element to an array and flattening
• fromNullishOr for converting a single nullable value to an array

Signature

declare const flatMapNullishOr: {
  <A, B>(f: (a: A) => B): (self: ReadonlyArray<A>) => Array<NonNullable<B>>
  <A, B>(self: ReadonlyArray<A>, f: (a: A) => B): Array<NonNullable<B>>
}

Source

Since v4.0.0

flatten

Flattens a nested array of arrays into a single array.

When to use

Use to collapse one level of nested arrays when no per-element mapping is needed.

Example (Flattening nested arrays)

import { Array } from "effect"

console.log(Array.flatten([[1, 2], [], [3, 4], [], [5, 6]])) // [1, 2, 3, 4, 5, 6]

See

• flatMap — map then flatten in one step

Signature

declare const flatten: <const S extends ReadonlyArray<ReadonlyArray<any>>>(self: S) => ReadonlyArray.Flatten<S>

Source

Since v2.0.0

sorting

sort

Sorts an array by the given Order, returning a new array.

When to use

Use to sort an array using a single Order comparator.

Details

Preserves NonEmptyArray in the return type. Use sortWith to sort by a derived key, or sortBy for multi-key sorting.

Example (Sorting numbers)

import { Array, Order } from "effect"

console.log(Array.sort([3, 1, 4, 1, 5], Order.Number)) // [1, 1, 3, 4, 5]

See

• sortWith — sort by a mapping function
• sortBy — sort by multiple orders

Signature

declare const sort: {
  <B>(O: Order.Order<B>): <A extends B, S extends Iterable<A>>(self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
  <A extends B, B>(self: NonEmptyReadonlyArray<A>, O: Order.Order<B>): NonEmptyArray<A>
  <A extends B, B>(self: Iterable<A>, O: Order.Order<B>): Array<A>
}

Source

Since v2.0.0

sortBy

Sorts an array by multiple Orders applied in sequence: the first order is used first; ties are broken by the second order, and so on.

When to use

Use to sort by multiple criteria where later orders break ties from earlier ones.

Details

This is data-last only and returns a function. The return type preserves NonEmptyArray.

Example (Sorting by multiple keys)

import { Array, Order, pipe } from "effect"

const users = [
  { name: "Alice", age: 30 },
  { name: "Bob", age: 25 },
  { name: "Charlie", age: 30 }
]

const result = pipe(
  users,
  Array.sortBy(
    Order.mapInput(Order.Number, (user: (typeof users)[number]) => user.age),
    Order.mapInput(Order.String, (user: (typeof users)[number]) => user.name)
  )
)
console.log(result)
// [{ name: "Bob", age: 25 }, { name: "Alice", age: 30 }, { name: "Charlie", age: 30 }]

See

• sort — sort by a single Order
• sortWith — sort by a derived key

Signature

declare const sortBy: <S extends Iterable<any>>(
  ...orders: ReadonlyArray<Order.Order<ReadonlyArray.Infer<S>>>
) => (
  self: S
) => S extends NonEmptyReadonlyArray<infer A> ? NonEmptyArray<A> : S extends Iterable<infer A> ? Array<A> : never

Source

Since v2.0.0

splitting

chunksOf

Splits an iterable into chunks of length n. The last chunk may be shorter if n does not evenly divide the length.

When to use

Use to divide an iterable into a new array of non-overlapping chunks with a maximum chunk size.

Details

chunksOf(n)([]) is [], not [[]]. Each chunk is a NonEmptyArray, and the outer return type preserves NonEmptyArray.

Example (Chunking an array)

import { Array } from "effect"

console.log(Array.chunksOf([1, 2, 3, 4, 5], 2)) // [[1, 2], [3, 4], [5]]

See

• split — split into a given number of groups
• window — sliding windows

Signature

declare const chunksOf: {
  (n: number): <S extends Iterable<any>>(self: S) => ReadonlyArray.With<S, NonEmptyArray<ReadonlyArray.Infer<S>>>
  <A>(self: NonEmptyReadonlyArray<A>, n: number): NonEmptyArray<NonEmptyArray<A>>
  <A>(self: Iterable<A>, n: number): Array<NonEmptyArray<A>>
}

Source

Since v2.0.0

span

Splits an iterable into two arrays: the longest prefix where the predicate holds, and the remaining elements.

When to use

Use when you need both the longest predicate-matching prefix and the remaining elements.

Details

Equivalent to [takeWhile(pred), dropWhile(pred)], but more efficient because it runs in a single pass. Supports refinements for type narrowing of the prefix.

Example (Splitting at predicate boundary)

import { Array } from "effect"

console.log(Array.span([1, 3, 2, 4, 5], (x) => x % 2 === 1)) // [[1, 3], [2, 4, 5]]

See

• takeWhile for keeping only the matching prefix
• dropWhile for keeping only the elements after the matching prefix
• splitWhere for splitting at the first element that satisfies a predicate

Signature

declare const span: {
  <A, B extends A>(
    refinement: (a: NoInfer<A>, i: number) => a is B
  ): (self: Iterable<A>) => [init: Array<B>, rest: Array<Exclude<A, B>>]
  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => [init: Array<A>, rest: Array<A>]
  <A, B extends A>(
    self: Iterable<A>,
    refinement: (a: A, i: number) => a is B
  ): [init: Array<B>, rest: Array<Exclude<A, B>>]
  <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): [init: Array<A>, rest: Array<A>]
}

Source

Since v2.0.0

split

Splits an iterable into n roughly equal-sized chunks.

When to use

Use to distribute elements across a fixed number of groups, such as when splitting work across threads.

Details

Uses chunksOf(ceil(length / n)) internally. The last chunk may be shorter.

Example (Splitting into groups)

import { Array } from "effect"

console.log(Array.split([1, 2, 3, 4, 5, 6, 7, 8], 3)) // [[1, 2, 3], [4, 5, 6], [7, 8]]

See

• chunksOf — split into fixed-size chunks

Signature

declare const split: {
  (n: number): <A>(self: Iterable<A>) => Array<Array<A>>
  <A>(self: Iterable<A>, n: number): Array<Array<A>>
}

Source

Since v2.0.0

splitAt

Splits an iterable into two arrays at the given index.

When to use

Use to divide an array into a prefix and suffix at a specific position.

Details

n can be 0, in which case all elements are placed in the second array. The index is floored to an integer.

Example (Splitting at an index)

import { Array } from "effect"

console.log(Array.splitAt([1, 2, 3, 4, 5], 3)) // [[1, 2, 3], [4, 5]]

See

• splitAtNonEmpty — for non-empty arrays
• splitWhere — split at a predicate boundary

Signature

declare const splitAt: {
  (n: number): <A>(self: Iterable<A>) => [beforeIndex: Array<A>, fromIndex: Array<A>]
  <A>(self: Iterable<A>, n: number): [beforeIndex: Array<A>, fromIndex: Array<A>]
}

Source

Since v2.0.0

splitAtNonEmpty

Splits a non-empty array into two parts at the given index. The first part is guaranteed to be non-empty (n is clamped to >= 1).

When to use

Use when downstream code requires the left side of the split to contain at least one element.

Example (Splitting a non-empty array)

import { Array } from "effect"

console.log(Array.splitAtNonEmpty(["a", "b", "c", "d", "e"], 3))
// [["a", "b", "c"], ["d", "e"]]

See

• splitAt — for possibly-empty arrays

Signature

declare const splitAtNonEmpty: {
  (n: number): <A>(self: NonEmptyReadonlyArray<A>) => [beforeIndex: NonEmptyArray<A>, fromIndex: Array<A>]
  <A>(self: NonEmptyReadonlyArray<A>, n: number): [beforeIndex: NonEmptyArray<A>, fromIndex: Array<A>]
}

Source

Since v4.0.0

splitWhere

Splits an iterable at the first element matching the predicate. The matching element is included in the second array.

When to use

Use when you need to split an array at the first element that marks a condition boundary.

Example (Splitting at a condition)

import { Array } from "effect"

console.log(Array.splitWhere([1, 2, 3, 4, 5], (n) => n > 3)) // [[1, 2, 3], [4, 5]]

See

• span — splits at the first element that fails the predicate
• splitAt — split at a fixed index

Signature

declare const splitWhere: {
  <A>(
    predicate: (a: NoInfer<A>, i: number) => boolean
  ): (self: Iterable<A>) => [beforeMatch: Array<A>, fromMatch: Array<A>]
  <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): [beforeMatch: Array<A>, fromMatch: Array<A>]
}

Source

Since v2.0.0

unappend

Splits a non-empty array into all elements except the last, and the last element.

When to use

Use when you need to split a non-empty array into the elements before the last element and the last element.

Details

Returns a tuple [init, last] and requires a NonEmptyReadonlyArray.

Example (Destructuring init and last)

import { Array } from "effect"

const result = Array.unappend([1, 2, 3, 4])
console.log(result) // [[1, 2, 3], 4]

See

• unprepend for splitting a non-empty array into head and tail
• initNonEmpty for getting only the elements before the last
• lastNonEmpty for getting only the last element

Signature

declare const unappend: <A>(self: NonEmptyReadonlyArray<A>) => [arrayWithoutLastElement: Array<A>, lastElement: A]

Source

Since v2.0.0

unprepend

Splits a non-empty array into its first element and the remaining elements.

When to use

Use when you have a NonEmptyReadonlyArray and need both its first element and the remaining elements as separate values.

Details

Returns a tuple [head, tail] and requires a NonEmptyReadonlyArray.

Example (Destructuring head and tail)

import { Array } from "effect"

const result = Array.unprepend([1, 2, 3, 4])
console.log(result) // [1, [2, 3, 4]]

See

• unappend for splitting a non-empty array into init and last
• headNonEmpty for getting only the first element
• tailNonEmpty for getting only the elements after the first

Signature

declare const unprepend: <A>(self: NonEmptyReadonlyArray<A>) => [firstElement: A, remainingElements: Array<A>]

Source

Since v2.0.0

window

Creates overlapping sliding windows of size n.

When to use

Use to process sequences with a moving window, such as for computing running averages or detecting patterns.

Details

Returns an empty array if n <= 0 or the array has fewer than n elements. Each window is a tuple of exactly n elements.

Example (Creating sliding windows)

import { Array } from "effect"

console.log(Array.window([1, 2, 3, 4, 5], 3)) // [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
console.log(Array.window([1, 2, 3, 4, 5], 6)) // []

See

• chunksOf — non-overlapping chunks

Signature

declare const window: {
  <N extends number>(n: N): <A>(self: Iterable<A>) => Array<TupleOf<N, A>>
  <A, N extends number>(self: Iterable<A>, n: N): Array<TupleOf<N, A>>
}

Source

Since v3.13.2

type lambdas

ReadonlyArrayTypeLambda (interface)

Type lambda for ReadonlyArray, used for higher-kinded type operations.

Signature

export interface ReadonlyArrayTypeLambda extends TypeLambda {
  readonly type: ReadonlyArray<this["Target"]>
}

Source

Since v2.0.0

unsafe

getUnsafe

Reads an element at the given index, throwing if the index is out of bounds.

When to use

Use to read an array element at a known valid index when out-of-bounds would be a programming error.

Details

Throws an Error with the message "Index out of bounds: <i>". Prefer get for safe access.

Example (Accessing indexes unsafely)

import { Array } from "effect"

console.log(Array.getUnsafe([1, 2, 3], 1)) // 2
// Array.getUnsafe([1, 2, 3], 10) // throws Error

See

• get — safe version returning Option

Signature

declare const getUnsafe: {
  (index: number): <A>(self: ReadonlyArray<A>) => A
  <A>(self: ReadonlyArray<A>, index: number): A
}

Source

Since v4.0.0

utils

ReadonlyArray (namespace)

Utility types for working with ReadonlyArray at the type level. Use these to infer element types, preserve non-emptiness, and flatten nested arrays.

Source

Since v2.0.0

Infer (type alias)

Infers the element type of an iterable.

Example (Inferring an element type)

import type { Array } from "effect"

type StringArrayType = Array.ReadonlyArray.Infer<ReadonlyArray<string>>
// StringArrayType is string

Signature

type Infer<S> = S extends ReadonlyArray<infer A> ? A : S extends Iterable<infer A> ? A : never

Source

Since v2.0.0

With (type alias)

Constructs an array type preserving non-emptiness.

Example (Preserving non-emptiness)

import type { Array } from "effect"

type Result = Array.ReadonlyArray.With<readonly [number], string>
// Result is NonEmptyArray<string>

Signature

type With<S, A> = S extends NonEmptyReadonlyArray<any> ? NonEmptyArray<A> : Array<A>

Source

Since v2.0.0

OrNonEmpty (type alias)

Creates a non-empty array if either input is non-empty.

Example (Preserving non-emptiness from either input)

import type { Array } from "effect"

type Result = Array.ReadonlyArray.OrNonEmpty<readonly [number], ReadonlyArray<string>, number>
// Result is NonEmptyArray<number>

Signature

type OrNonEmpty<S, T, A> =
  S extends NonEmptyReadonlyArray<any>
    ? NonEmptyArray<A>
    : T extends NonEmptyReadonlyArray<any>
      ? NonEmptyArray<A>
      : Array<A>

Source

Since v2.0.0

AndNonEmpty (type alias)

Creates a non-empty array only if both inputs are non-empty.

Example (Preserving non-emptiness from both inputs)

import type { Array } from "effect"

type Result = Array.ReadonlyArray.AndNonEmpty<readonly [number], readonly [string], boolean>
// Result is NonEmptyArray<boolean>

Signature

type AndNonEmpty<S, T, A> =
  S extends NonEmptyReadonlyArray<any> ? (T extends NonEmptyReadonlyArray<any> ? NonEmptyArray<A> : Array<A>) : Array<A>

Source

Since v2.0.0

Flatten (type alias)

Flattens a nested array type.

Example (Flattening nested array types)

import type { Array } from "effect"

type Nested = ReadonlyArray<ReadonlyArray<number>>
type Flattened = Array.ReadonlyArray.Flatten<Nested>
// Flattened is Array<number>

Signature

type Flatten<T> =
  T extends NonEmptyReadonlyArray<NonEmptyReadonlyArray<any>>
    ? NonEmptyArray<T[number][number]>
    : Array<T[number][number]>

Source

Since v2.0.0

zipping

unzip

Splits an array of pairs into two arrays. Inverse of zip.

Example (Unzipping pairs)

import { Array } from "effect"

console.log(
  Array.unzip([
    [1, "a"],
    [2, "b"],
    [3, "c"]
  ])
) // [[1, 2, 3], ["a", "b", "c"]]

See

• zip — combine two arrays into pairs

Signature

declare const unzip: <S extends Iterable<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

Source

Since v2.0.0

zip

Pairs elements from two iterables by position. If the iterables differ in length, the extra elements from the longer one are discarded.

When to use

Use when you need simple pairs of corresponding elements from two iterables.

Details

Returns NonEmptyArray when both inputs are non-empty.

Example (Zipping two arrays)

import { Array } from "effect"

console.log(Array.zip([1, 2, 3], ["a", "b"])) // [[1, "a"], [2, "b"]]

See

• zipWith — zip with a combiner function
• unzip — inverse operation

Signature

declare const zip: {
  <B>(that: NonEmptyReadonlyArray<B>): <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray<[A, B]>
  <B>(that: Iterable<B>): <A>(self: Iterable<A>) => Array<[A, B]>
  <A, B>(self: NonEmptyReadonlyArray<A>, that: NonEmptyReadonlyArray<B>): NonEmptyArray<[A, B]>
  <A, B>(self: Iterable<A>, that: Iterable<B>): Array<[A, B]>
}

Source

Since v2.0.0

zipWith

Combines elements from two iterables pairwise using a function. If the iterables differ in length, extra elements are discarded.

When to use

Use when zipping two iterables in an array pipeline and each pair should become a computed array element instead of a tuple.

Example (Zipping with addition)

import { Array } from "effect"

console.log(Array.zipWith([1, 2, 3], [4, 5, 6], (a, b) => a + b)) // [5, 7, 9]

See

• zip — zip into tuples

Signature

declare const zipWith: {
  <B, A, C>(that: NonEmptyReadonlyArray<B>, f: (a: A, b: B) => C): (self: NonEmptyReadonlyArray<A>) => NonEmptyArray<C>
  <B, A, C>(that: Iterable<B>, f: (a: A, b: B) => C): (self: Iterable<A>) => Array<C>
  <A, B, C>(self: NonEmptyReadonlyArray<A>, that: NonEmptyReadonlyArray<B>, f: (a: A, b: B) => C): NonEmptyArray<C>
  <B, A, C>(self: Iterable<A>, that: Iterable<B>, f: (a: A, b: B) => C): Array<C>
}

Source

Since v2.0.0