Skip to main content Link Search Menu Expand Document (external link)
effect

Array.ts overview

This module provides utility functions for working with arrays in TypeScript.

Since v2.0.0

Exports Grouped by Category

concatenating

append

Append an element to the end of an Iterable, creating a new NonEmptyArray.

Example

import { Array } from "effect"

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

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 arrays (or iterables), combining their elements. If either array is non-empty, the result is also a non-empty array.

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

Prepend an element to the front of an Iterable, creating a new NonEmptyArray.

Example

import { Array } from "effect"

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

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 the specified prefix array (or iterable) to the beginning of the specified array (or iterable). If either array is non-empty, the result is also a non-empty array.

Example

import { Array } from "effect"

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

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

allocate

Creates a new Array of the specified length.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

empty

Signature

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

Source

Since v2.0.0

ensure

Creates a new Array from a value that might not be an iterable.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v3.3.0

fromIterable

Creates a new Array from an iterable collection of values. If the input is already an array, it returns the input as-is. Otherwise, it converts the iterable collection to an array.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

make

Builds a NonEmptyArray from an non-empty collection of elements.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

makeBy

Return a NonEmptyArray of length n with element i initialized with f(i).

Note. n is normalized to an integer >= 1.

Example

import { makeBy } from "effect/Array"

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

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

Constructs a new NonEmptyArray<A> from the specified value.

Signature

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

Source

Since v2.0.0

range

Return a NonEmptyArray containing a range of integers, including both endpoints.

Example

import { range } from "effect/Array"

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

Signature

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

Source

Since v2.0.0

replicate

Return a NonEmptyArray containing a value repeated the specified number of times.

Note. n is normalized to an integer >= 1.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

unfold

Signature

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

Source

Since v2.0.0

conversions

fromNullable

Signature

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

Source

Since v2.0.0

fromOption

Converts an Option to an array.

Example

import { Array, Option } from "effect"

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

Signature

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

Source

Since v2.0.0

fromRecord

Takes a record and returns an array of tuples containing its keys and values.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

do notation

Do

The “do simulation” for array allows you to sequentially apply operations to the elements of arrays, just as nested loops allow you to go through all combinations of elements in an arrays.

It can be used to simulate “array comprehension”. It’s a technique that allows you to create new arrays by iterating over existing ones and applying specific conditions or transformations to the elements. It’s like assembling a new collection from pieces of other collections based on certain rules.

Here’s how the do simulation works:

  1. Start the do simulation using the Do value
  2. Within the do simulation scope, you can use the bind function to define variables and bind them to Array values
  3. You can accumulate multiple bind statements to define multiple variables within the scope
  4. Inside the do simulation scope, you can also use the let function to define variables and bind them to simple values
  5. Regular Option functions like map and filter can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope

Example

import { Array, pipe } from "effect"

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

// equivalent
const x = [1, 3, 5],
  y = [2, 4, 6],
  result = []
for (let i = 0; i < x.length; i++) {
  for (let j = 0; j < y.length; j++) {
    const _x = x[i],
      _y = y[j]
    if (_x < _y) result.push([_x, _y] as const)
  }
}

See

  • bindTo
  • bind
  • let

Signature

declare const Do: ReadonlyArray<{}>

Source

Since v3.2.0

bind

The “do simulation” for array allows you to sequentially apply operations to the elements of arrays, just as nested loops allow you to go through all combinations of elements in an arrays.

It can be used to simulate “array comprehension”. It’s a technique that allows you to create new arrays by iterating over existing ones and applying specific conditions or transformations to the elements. It’s like assembling a new collection from pieces of other collections based on certain rules.

Here’s how the do simulation works:

  1. Start the do simulation using the Do value
  2. Within the do simulation scope, you can use the bind function to define variables and bind them to Array values
  3. You can accumulate multiple bind statements to define multiple variables within the scope
  4. Inside the do simulation scope, you can also use the let function to define variables and bind them to simple values
  5. Regular Option functions like map and filter can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope

Example

import { Array, pipe } from "effect"

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

// equivalent
const x = [1, 3, 5],
  y = [2, 4, 6],
  result = []
for (let i = 0; i < x.length; i++) {
  for (let j = 0; j < y.length; j++) {
    const _x = x[i],
      _y = y[j]
    if (_x < _y) result.push([_x, _y] as const)
  }
}

See

  • bindTo
  • Do
  • let

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

The “do simulation” for array allows you to sequentially apply operations to the elements of arrays, just as nested loops allow you to go through all combinations of elements in an arrays.

It can be used to simulate “array comprehension”. It’s a technique that allows you to create new arrays by iterating over existing ones and applying specific conditions or transformations to the elements. It’s like assembling a new collection from pieces of other collections based on certain rules.

Here’s how the do simulation works:

  1. Start the do simulation using the Do value
  2. Within the do simulation scope, you can use the bind function to define variables and bind them to Array values
  3. You can accumulate multiple bind statements to define multiple variables within the scope
  4. Inside the do simulation scope, you can also use the let function to define variables and bind them to simple values
  5. Regular Option functions like map and filter can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope

Example

import { Array, pipe } from "effect"

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

// equivalent
const x = [1, 3, 5],
  y = [2, 4, 6],
  result = []
for (let i = 0; i < x.length; i++) {
  for (let j = 0; j < y.length; j++) {
    const _x = x[i],
      _y = y[j]
    if (_x < _y) result.push([_x, _y] as const)
  }
}

See

  • bindTo
  • Do
  • let

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

The “do simulation” for array allows you to sequentially apply operations to the elements of arrays, just as nested loops allow you to go through all combinations of elements in an arrays.

It can be used to simulate “array comprehension”. It’s a technique that allows you to create new arrays by iterating over existing ones and applying specific conditions or transformations to the elements. It’s like assembling a new collection from pieces of other collections based on certain rules.

Here’s how the do simulation works:

  1. Start the do simulation using the Do value
  2. Within the do simulation scope, you can use the bind function to define variables and bind them to Array values
  3. You can accumulate multiple bind statements to define multiple variables within the scope
  4. Inside the do simulation scope, you can also use the let function to define variables and bind them to simple values
  5. Regular Option functions like map and filter can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope

Example

import { Array, pipe } from "effect"

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

// equivalent
const x = [1, 3, 5],
  y = [2, 4, 6],
  result = []
for (let i = 0; i < x.length; i++) {
  for (let j = 0; j < y.length; j++) {
    const _x = x[i],
      _y = y[j]
    if (_x < _y) result.push([_x, _y] as const)
  }
}

See

  • bindTo
  • bind
  • Do

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

Zips this chunk crosswise with the specified chunk.

Example

import { Array } from "effect"

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

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

Zips this chunk crosswise with the specified chunk using the specified combiner.

Example

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"]

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

contains

Returns a function that checks if a ReadonlyArray contains a given value using the default Equivalence.

Example

import { Array, pipe } from "effect"

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

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 function that checks if a ReadonlyArray contains a given value using a provided isEquivalent function.

Example

import { Array, pipe } from "effect"

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

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

every

Check if a predicate holds true for every ReadonlyArray element.

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 that satisfies the specified predicate, or None if no such element exists.

Example

import { Array } from "effect"

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

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

Return the first index for which a predicate holds.

Example

import { Array } from "effect"

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

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

findLast

Finds the last element in an iterable collection that satisfies the given predicate or refinement. Returns an Option containing the found element, or Option.none if no element matches.

Example

import { Array } from "effect"

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

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

Return the last index for which a predicate holds.

Example

import { Array } from "effect"

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

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

reverse

Reverse an Iterable, creating a new Array.

Example

import { Array } from "effect"

const result = Array.reverse([1, 2, 3, 4])
console.log(result) // [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

some

Check if a predicate holds true for some ReadonlyArray element.

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 based on a provided mapping function and order. The mapping function transforms the elements into a value that can be compared, and the order defines how those values should be sorted.

Example

import { Array, Order } from "effect"

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

// Explanation:
// The array of strings is sorted based on their lengths. The mapping function `(s) => s.length`
// converts each string into its length, and the `Order.number` specifies that the lengths should
// be sorted in ascending order.

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

filtering

filter

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

Applies a function to each element of the Iterable and filters based on the result, keeping the transformed values where the function returns Some. This method combines filtering and mapping functionalities, allowing transformations and filtering of elements based on a single function pass.

Example

import { Array, Option } from "effect"

const evenSquares = (x: number) => (x % 2 === 0 ? Option.some(x * x) : Option.none())

const result = Array.filterMap([1, 2, 3, 4, 5], evenSquares)
console.log(result) // [4, 16]

Signature

declare const filterMap: {
  <A, B>(f: (a: A, i: number) => Option.Option<B>): (self: Iterable<A>) => Array<B>
  <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option.Option<B>): Array<B>
}

Source

Since v2.0.0

filterMapWhile

Applies a function to each element of the array and filters based on the result, stopping when a condition is not met. This method combines filtering and mapping in a single pass, and short-circuits, i.e., stops processing, as soon as the function returns None. This is useful when you need to transform an array but only up to the point where a certain condition holds true.

Example

import { Array, Option } from "effect"

const toSquareTillOdd = (x: number) => (x % 2 === 0 ? Option.some(x * x) : Option.none())

const result = Array.filterMapWhile([2, 4, 5], toSquareTillOdd)
console.log(result) // [4, 16]

Signature

declare const filterMapWhile: {
  <A, B>(f: (a: A, i: number) => Option.Option<B>): (self: Iterable<A>) => Array<B>
  <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option.Option<B>): Array<B>
}

Source

Since v2.0.0

getLefts

Retrieves the Left values from an Iterable of Eithers, collecting them into an array.

Example

import { Array, Either } from "effect"

const result = Array.getLefts([Either.right(1), Either.left("err"), Either.right(2)])
console.log(result) // ["err"]

Signature

declare const getLefts: <T extends Iterable<Either.Either<any, any>>>(
  self: T
) => Array<Either.Either.Left<ReadonlyArray.Infer<T>>>

Source

Since v2.0.0

getRights

Retrieves the Right values from an Iterable of Eithers, collecting them into an array.

Example

import { Array, Either } from "effect"

const result = Array.getRights([Either.right(1), Either.left("err"), Either.right(2)])
console.log(result) // [1, 2]

Signature

declare const getRights: <T extends Iterable<Either.Either<any, any>>>(
  self: T
) => Array<Either.Either.Right<ReadonlyArray.Infer<T>>>

Source

Since v2.0.0

getSomes

Retrieves the Some values from an Iterable of Options, collecting them into an array.

Example

import { Array, Option } from "effect"

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

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

partition

Separate elements based on a predicate that also exposes the index of the element.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

partitionMap

Applies a function to each element of the Iterable, categorizing the results into two separate arrays. This function is particularly useful for operations where each element can result in two possible types, and you want to separate these types into different collections. For instance, separating validation results into successes and failures.

Example

import { Array, Either } from "effect"

const isEven = (x: number) => x % 2 === 0

const result = Array.partitionMap([1, 2, 3, 4, 5], (x) => (isEven(x) ? Either.right(x) : Either.left(x)))
console.log(result)
// [
//   [1, 3, 5],
//   [2, 4]
// ]

Signature

declare const partitionMap: {
  <A, B, C>(f: (a: A, i: number) => Either.Either<C, B>): (self: Iterable<A>) => [left: Array<B>, right: Array<C>]
  <A, B, C>(self: Iterable<A>, f: (a: A, i: number) => Either.Either<C, B>): [left: Array<B>, right: Array<C>]
}

Source

Since v2.0.0

separate

Separates an Iterable into two arrays based on a predicate.

Signature

declare const separate: <T extends Iterable<Either.Either<any, any>>>(
  self: T
) => [Array<Either.Either.Left<ReadonlyArray.Infer<T>>>, Array<Either.Either.Right<ReadonlyArray.Infer<T>>>]

Source

Since v2.0.0

folding

join

Joins the elements together with “sep” in the middle.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

mapAccum

Statefully maps over the chunk, producing new elements of type B.

Example

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]]

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

Reduces an array from the left.

Example

import { Array } from "effect"

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

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

Reduces an array from the right.

Example

import { Array } from "effect"

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

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

Accumulates values from an Iterable starting from the left, storing each intermediate result in an array. Useful for tracking the progression of a value through a series of transformations.

Example

import { Array } from "effect"

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

// Explanation:
// This function starts with the initial value (0 in this case)
// and adds each element of the array to this accumulator one by one,
// keeping track of the cumulative sum after each addition.
// Each of these sums is captured in the resulting array.

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

Accumulates values from an Iterable starting from the right, storing each intermediate result in an array. Useful for tracking the progression of a value through a series of transformations.

Example

import { Array } from "effect"

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

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

Drop a max number of elements from the start of an Iterable, creating a new Array.

Note. n is normalized to a non negative integer.

Example

import { Array } from "effect"

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

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

Drop a max number of elements from the end of an Iterable, creating a new Array.

Note. n is normalized to a non negative integer.

Example

import { Array } from "effect"

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

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

Remove the longest initial subarray for which all element satisfy the specified predicate, creating a new Array.

Example

import { Array } from "effect"

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

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

get

This function provides a safe way to read a value at a particular index from a ReadonlyArray.

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

Get the first element of a ReadonlyArray, or None if the ReadonlyArray is empty.

Signature

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

Source

Since v2.0.0

headNonEmpty

Get the first element of a non empty array.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

init

Get all but the last element of an Iterable, creating a new Array, or None if the Iterable is empty.

Signature

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

Source

Since v2.0.0

initNonEmpty

Get all but the last element of a non empty array, creating a new array.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

last

Get the last element in a ReadonlyArray, or None if the ReadonlyArray is empty.

Signature

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

Source

Since v2.0.0

lastNonEmpty

Get the last element of a non empty array.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

length

Return the number of elements in a ReadonlyArray.

Signature

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

Source

Since v2.0.0

tail

Get all but the first element of an Iterable, creating a new Array, or None if the Iterable is empty.

Signature

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

Source

Since v2.0.0

tailNonEmpty

Get all but the first element of a NonEmptyReadonlyArray.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

take

Keep only a max number of elements from the start of an Iterable, creating a new Array.

Note. n is normalized to a non negative integer.

Example

import { Array } from "effect"

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

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

Keep only a max number of elements from the end of an Iterable, creating a new Array.

Note. n is normalized to a non negative integer.

Example

import { Array } from "effect"

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

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

Calculate the longest initial subarray for which all element satisfy the specified predicate, creating a new Array.

Example

import { Array } from "effect"

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

// Explanation:
// - The function starts with the first element (`1`), which is less than `4`, so it adds `1` to the result.
// - The next element (`3`) is also less than `4`, so it adds `3`.
// - The next element (`2`) is again less than `4`, so it adds `2`.
// - The function then encounters `4`, which is not less than `4`. At this point, it stops checking further elements and finalizes the result.

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

grouping

group

Group equal, consecutive elements of a NonEmptyReadonlyArray into NonEmptyArrays.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

groupBy

Splits an Iterable into sub-non-empty-arrays stored in an object, based on the result of calling a string-returning function on each element, and grouping the results according to values returned

Example

import { Array } from "effect"

const people = [
  { name: "Alice", group: "A" },
  { name: "Bob", group: "B" },
  { name: "Charlie", group: "A" }
]

const result = Array.groupBy(people, (person) => person.group)
console.log(result)
// {
//  A: [{ name: "Alice", group: "A" }, { name: "Charlie", group: "A" }],
//  B: [{ name: "Bob", group: "B" }]
// }

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

Group equal, consecutive elements of a NonEmptyReadonlyArray into NonEmptyArrays using the provided isEquivalent function.

Example

import { Array } from "effect"

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

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

Determine if unknown is an Array.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

isEmptyArray

Determine if an Array is empty narrowing down the type to [].

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

isEmptyReadonlyArray

Determine if a ReadonlyArray is empty narrowing down the type to readonly [].

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

isNonEmptyArray

Determine if an Array is non empty narrowing down the type to NonEmptyArray.

An Array is considered to be a NonEmptyArray if it contains at least one element.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

isNonEmptyReadonlyArray

Determine if a ReadonlyArray is non empty narrowing down the type to NonEmptyReadonlyArray.

A ReadonlyArray is considered to be a NonEmptyReadonlyArray if it contains at least one element.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

instances

getEquivalence

Creates an equivalence relation for arrays.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

getOrder

This function creates and returns a new Order for an array of values based on a given Order for the elements of the array. The returned Order compares two arrays by applying the given Order to each element in the arrays. If all elements are equal, the arrays are then compared based on their length. It is useful when you need to compare two arrays of the same type and you have a specific way of comparing each element of the array.

Signature

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

Source

Since v2.0.0

lifting

liftEither

Lifts a function that returns an Either into a function that returns an array. If the Either is a left, it returns an empty array. If the Either is a right, it returns an array with the right value.

Example

import { Array, Either } from "effect"

const parseNumber = (s: string): Either.Either<number, Error> =>
  isNaN(Number(s)) ? Either.left(new Error("Not a number")) : Either.right(Number(s))

const liftedParseNumber = Array.liftEither(parseNumber)

const result1 = liftedParseNumber("42")
console.log(result1) // [42]

const result2 = liftedParseNumber("not a number")
console.log(result2) // []

// Explanation:
// The function parseNumber is lifted to return an array.
// When parsing "42", it returns an Either.left with the number 42, resulting in [42].
// When parsing "not a number", it returns an Either.right with an error, resulting in an empty array [].

Signature

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

Source

Since v2.0.0

liftNullable

Signature

declare const liftNullable: <A extends Array<unknown>, B>(
  f: (...a: A) => B | null | undefined
) => (...a: A) => Array<NonNullable<B>>

Source

Since v2.0.0

liftOption

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.

Example

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]

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

mapping

map

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)

Signature

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

Source

Since v2.0.0

NonEmptyReadonlyArray (type alias)

Signature

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

Source

Since v2.0.0

pattern matching

match

Matches the elements of an array, applying functions to cases of empty and non-empty arrays.

Example

import { Array } from "effect"

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

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

Matches the elements of an array from the left, applying functions to cases of empty and non-empty arrays.

Example

import { Array } from "effect"

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

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

Matches the elements of an array from the right, applying functions to cases of empty and non-empty arrays.

Example

import { Array } from "effect"

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

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

Applies a function to each element in an array and returns a new array containing the concatenated mapped elements.

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

flatMapNullable

Maps over an array and flattens the result, removing null and undefined values.

Example

import { Array } from "effect"

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

// Explanation:
// The array of numbers [1, 2, 3] is mapped with a function that returns null for even numbers
// and the number itself for odd numbers. The resulting array [1, null, 3] is then flattened
// to remove null values, resulting in [1, 3].

Signature

declare const flatMapNullable: {
  <A, B>(f: (a: A) => B | null | undefined): (self: ReadonlyArray<A>) => Array<NonNullable<B>>
  <A, B>(self: ReadonlyArray<A>, f: (a: A) => B | null | undefined): Array<NonNullable<B>>
}

Source

Since v2.0.0

flatten

Combines multiple arrays into a single array by concatenating all elements from each nested array. This function ensures that the structure of nested arrays is collapsed into a single, flat array.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

sorting

sort

Create a new array with elements sorted in increasing order based on the specified comparator. If the input is a NonEmptyReadonlyArray, the output will also be a NonEmptyReadonlyArray.

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 the elements of an Iterable in increasing order based on the provided orders. The elements are compared using the first order in orders, then the second order if the first comparison is equal, and so on.

Example

import { Array, Order, 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 }
// ]

// Explanation:
// The array of users is sorted first by age in ascending order. When ages are equal,
// the users are further sorted by name in ascending order.

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 length-n pieces. The last piece will be shorter if n does not evenly divide the length of the Iterable. Note that chunksOf(n)([]) is [], not [[]]. This is intentional, and is consistent with a recursive definition of chunksOf; it satisfies the property that

chunksOf(n)(xs).concat(chunksOf(n)(ys)) == chunksOf(n)(xs.concat(ys)))

whenever n evenly divides the length of self.

Example

import { Array } from "effect"

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

// Explanation:
// The `chunksOf` function takes an array of numbers `[1, 2, 3, 4, 5]` and a number `2`.
// It splits the array into chunks of length 2. Since the array length is not evenly divisible by 2,
// the last chunk contains the remaining elements.
// The result is `[[1, 2], [3, 4], [5]]`.

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

Split an Iterable into two parts:

  1. the longest initial subarray for which all elements satisfy the specified predicate
  2. the remaining elements

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 this iterable into n equally sized arrays.

Example

import { Array } from "effect"

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

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 segments, with the first segment containing a maximum of n elements. The value of n can be 0.

Example

import { Array } from "effect"

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

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

splitNonEmptyAt

Splits a NonEmptyReadonlyArray into two segments, with the first segment containing a maximum of n elements. The value of n must be >= 1.

Example

import { Array } from "effect"

const result = Array.splitNonEmptyAt(["a", "b", "c", "d", "e"], 3)
console.log(result) // [["a", "b", "c"], ["d", "e"]]

Signature

declare const splitNonEmptyAt: {
  (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 v2.0.0

splitWhere

Splits this iterable on the first element that matches this predicate. Returns a tuple containing two arrays: the first one is before the match, and the second one is from the match onward.

Example

import { Array } from "effect"

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

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

Return a tuple containing a copy of the NonEmptyReadonlyArray without its last element, and that last element.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

unprepend

Return a tuple containing the first element, and a new Array of the remaining elements, if any.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

window

Creates sliding windows of size n from an Iterable. If the number of elements is less than n or if n is not greater than zero, an empty array is returned.

Example

import * as assert from "node:assert"
import { Array } from "effect"

const numbers = [1, 2, 3, 4, 5]
assert.deepStrictEqual(Array.window(numbers, 3), [
  [1, 2, 3],
  [2, 3, 4],
  [3, 4, 5]
])
assert.deepStrictEqual(Array.window(numbers, 6), [])

Signature

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

Source

Since v3.13.2

type lambdas

ReadonlyArrayTypeLambda (interface)

Signature

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

Source

Since v2.0.0

unsafe

unsafeGet

Gets an element unsafely, will throw on out of bounds.

Signature

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

Source

Since v2.0.0

utils

ReadonlyArray (namespace)

Source

Since v2.0.0

Infer (type alias)

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)

Signature

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

Source

Since v2.0.0

OrNonEmpty (type alias)

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)

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)

Signature

type Flatten<T> =
  T extends NonEmptyReadonlyArray<NonEmptyReadonlyArray<infer A>>
    ? NonEmptyArray<A>
    : T extends ReadonlyArray<ReadonlyArray<infer A>>
      ? Array<A>
      : never

Source

Since v2.0.0

chop

A useful recursion pattern for processing an Iterable to produce a new Array, often used for “chopping” up the input Iterable. Typically chop is called with some function that will consume an initial prefix of the Iterable and produce a value and the rest of the Array.

Example

import { Array } from "effect"

const 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]

// Explanation:
// The `chopFunction` takes the first element of the array, doubles it, and then returns it along with the rest of the array.
// The `chop` function applies this `chopFunction` recursively to the input array `[1, 2, 3, 4, 5]`,
// resulting in a new array `[2, 4, 6, 8, 10]`.

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

copy

Copies an array.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

dedupe

Remove duplicates from an Iterable, preserving the order of the first occurrence of each element. The equivalence used to compare elements is provided by Equal.equivalence() from the Equal module.

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

Deduplicates adjacent elements that are identical.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

dedupeAdjacentWith

Deduplicates adjacent elements that are identical using the provided isEquivalent function.

Example

import { Array } from "effect"

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

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

Remove duplicates from an Iterable using the provided isEquivalent function, preserving the order of the first occurrence of each element.

Example

import { Array } from "effect"

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

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

Creates a Array of values not included in the other given Iterable. The order and references of result values are determined by the first Iterable.

Example

import { Array } from "effect"

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

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

Creates a Array of values not included in the other given Iterable using the provided isEquivalent function. The order and references of result values are determined by the first Iterable.

Example

import { Array } from "effect"

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

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

extend

Extends an array with a function that maps each subarray to a value.

Example

import { Array } from "effect"

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

// Explanation:
// The function maps each subarray starting from each element to its length.
// The subarrays are: [1, 2, 3], [2, 3], [3].
// The lengths are: 3, 2, 1.
// Therefore, the result is [3, 2, 1].

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

forEach

Performs a side-effect for each element of the Iterable.

Example

import { Array } from "effect"

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

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

Insert an element at the specified index, creating a new NonEmptyArray, or return None if the index is out of bounds.

Example

import { Array } from "effect"

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

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

Creates an Array of unique values that are included in all given Iterables. The order and references of result values are determined by the first Iterable.

Example

import { Array } from "effect"

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

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

Creates an Array of unique values that are included in all given Iterables using the provided isEquivalent function. The order and references of result values are determined by the first Iterable.

Example

import { Array } from "effect"

const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }]
const array2 = [{ id: 3 }, { id: 4 }, { id: 1 }]
const isEquivalent = (a: { id: number }, b: { id: number }) => a.id === b.id
const result = Array.intersectionWith(isEquivalent)(array2)(array1)
console.log(result) // [{ id: 1 }, { id: 3 }]

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 an element in between members of an Iterable. If the input is a non-empty array, the result is also a non-empty array.

Example

import { Array } from "effect"

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

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

Finds the maximum element in an array based on a comparator.

Example

import { Array, Order } from "effect"

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

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

Finds the minimum element in an array based on a comparator.

Example

import { Array, Order } from "effect"

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

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

Apply a function to the element at the specified index, creating a new Array, or return a copy of the input if the index is out of bounds.

Example

import { Array } from "effect"

const result = Array.modify([1, 2, 3, 4], 2, (n) => n * 2)
console.log(result) // [1, 2, 6, 4]

Signature

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

Source

Since v2.0.0

modifyNonEmptyHead

Apply a function to the head, creating a new NonEmptyReadonlyArray.

Example

import { Array } from "effect"

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

Signature

declare const modifyNonEmptyHead: {
  <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 v2.0.0

modifyNonEmptyLast

Apply a function to the last element, creating a new NonEmptyReadonlyArray.

Example

import { Array } from "effect"

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

Signature

declare const modifyNonEmptyLast: {
  <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 v2.0.0

modifyOption

Apply a function to the element at the specified index, creating a new Array, or return None if the index is out of bounds.

Example

import { Array } from "effect"

const input = [1, 2, 3, 4]
const result = Array.modifyOption(input, 2, (n) => n * 2)
console.log(result) // Option.some([1, 2, 6, 4])

const outOfBoundsResult = Array.modifyOption(input, 5, (n) => n * 2)
console.log(outOfBoundsResult) // Option.none()

Signature

declare const modifyOption: {
  <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

pad

Pads an array. Returns a new array of length n with the elements of array followed by fill elements if array is shorter than n. If array is longer than n, the returned array will be a slice of array containing the n first elements of array. If n is less than or equal to 0, the returned array will be an empty array.

Example

import { Array } from "effect"

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

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

Delete the element at the specified index, creating a new Array, or return a copy of the input if the index is out of bounds.

Example

import { Array } from "effect"

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

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

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

Change the element at the specified index, creating a new Array, or return a copy of the input if the index is out of bounds.

Example

import { Array } from "effect"

const result = Array.replace(["a", "b", "c", "d"], 1, "z")
console.log(result) // ['a', 'z', 'c', 'd']

Signature

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

Source

Since v2.0.0

replaceOption

Replaces an element in an array with the given value, returning an option of the updated array.

Example

import { Array } from "effect"

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

Signature

declare const replaceOption: {
  <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

rotate

Rotate an Iterable by n steps. If the input is a non-empty array, the result is also a non-empty array.

Example

import { Array } from "effect"

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

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

setNonEmptyHead

Change the head, creating a new NonEmptyReadonlyArray.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

setNonEmptyLast

Change the last element, creating a new NonEmptyReadonlyArray.

Example

import { Array } from "effect"

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

Signature

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

Source

Since v2.0.0

union

Creates a union of two arrays, removing duplicates.

Example

import { Array } from "effect"

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

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

Calculates the union of two arrays using the provided equivalence relation.

Example

import { Array } from "effect"

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

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

unzip

This function is the inverse of zip. Takes an Iterable of pairs and return two corresponding Arrays.

Example

import { Array } from "effect"

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

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

zipping

zip

Takes two Iterables and returns an Array of corresponding pairs. If one input Iterable is short, excess elements of the longer Iterable are discarded.

Example

import { Array } from "effect"

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

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

Apply a function to pairs of elements at the same index in two Iterables, collecting the results in a new Array. If one input Iterable is short, excess elements of the longer Iterable are discarded.

Example

import { Array } from "effect"

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

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