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

Array overview

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

Added in v2.0.0

Table of contents

concatenating

append

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

Signature

export declare const append: {
  <B>(last: B): <A>(self: Iterable<A>) => [B | A, ...(B | A)[]]
  <A, B>(self: Iterable<A>, last: B): [A | B, ...(A | B)[]]
}

Added in 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

export declare const appendAll: {
  <S extends readonly any[] | Iterable<any>, T extends readonly any[] | Iterable<any>>(
    that: T
  ): (self: S) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>
  <A, B>(self: Iterable<A>, that: readonly [B, ...B[]]): [A | B, ...(A | B)[]]
  <A, B>(self: readonly [A, ...A[]], that: Iterable<B>): [A | B, ...(A | B)[]]
  <A, B>(self: Iterable<A>, that: Iterable<B>): (A | B)[]
}

Added in v2.0.0

prepend

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

Signature

export declare const prepend: {
  <B>(head: B): <A>(self: Iterable<A>) => [B | A, ...(B | A)[]]
  <A, B>(self: Iterable<A>, head: B): [A | B, ...(A | B)[]]
}

Added in 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.

Signature

export declare const prependAll: {
  <S extends readonly any[] | Iterable<any>, T extends readonly any[] | Iterable<any>>(
    that: T
  ): (self: S) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>
  <A, B>(self: Iterable<A>, that: readonly [B, ...B[]]): [A | B, ...(A | B)[]]
  <A, B>(self: readonly [A, ...A[]], that: Iterable<B>): [A | B, ...(A | B)[]]
  <A, B>(self: Iterable<A>, that: Iterable<B>): (A | B)[]
}

Example

import { Array } from "effect"

assert.deepStrictEqual(Array.prependAll([1, 2], ["a", "b"]), ["a", "b", 1, 2])

Added in v2.0.0

constructors

allocate

Creates a new Array of the specified length.

Signature

export declare const allocate: <A = never>(n: number) => (A | undefined)[]

Added in v2.0.0

empty

Signature

export declare const empty: <A = never>() => A[]

Added in v2.0.0

fromIterable

Creates a new Array from an iterable collection of values.

Signature

export declare const fromIterable: <A>(collection: Iterable<A>) => A[]

Added in v2.0.0

make

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

Signature

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

Added in 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.

Signature

export declare const makeBy: <A>(n: number, f: (i: number) => A) => [A, ...A[]]

Example

import { makeBy } from "effect/Array"

assert.deepStrictEqual(
  makeBy(5, (n) => n * 2),
  [0, 2, 4, 6, 8]
)

Added in v2.0.0

of

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

Signature

export declare const of: <A>(a: A) => [A, ...A[]]

Added in v2.0.0

range

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

Signature

export declare const range: (start: number, end: number) => [number, ...number[]]

Example

import { range } from "effect/Array"

assert.deepStrictEqual(range(1, 3), [1, 2, 3])

Added in v2.0.0

replicate

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

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

Signature

export declare const replicate: { (n: number): <A>(a: A) => [A, ...A[]]; <A>(a: A, n: number): [A, ...A[]] }

Example

import { replicate } from "effect/Array"

assert.deepStrictEqual(replicate("a", 3), ["a", "a", "a"])

Added in v2.0.0

unfold

Signature

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

Added in v2.0.0

conversions

fromNullable

Signature

export declare const fromNullable: <A>(a: A) => NonNullable<A>[]

Added in v2.0.0

fromOption

Signature

export declare const fromOption: <A>(self: Option<A>) => A[]

Added in v2.0.0

fromRecord

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

Signature

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

Example

import { fromRecord } from "effect/Array"

const x = { a: 1, b: 2, c: 3 }
assert.deepStrictEqual(fromRecord(x), [
  ["a", 1],
  ["b", 2],
  ["c", 3]
])

Added in v2.0.0

elements

cartesian

Zips this chunk crosswise with the specified chunk.

Signature

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

Added in v2.0.0

cartesianWith

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

Signature

export declare const cartesianWith: {
  <A, B, C>(that: readonly B[], f: (a: A, b: B) => C): (self: readonly A[]) => C[]
  <A, B, C>(self: readonly A[], that: readonly B[], f: (a: A, b: B) => C): C[]
}

Added in v2.0.0

contains

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

Signature

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

Added in v2.0.0

containsWith

Returns a function that checks if a ReadonlyArray contains a given value using a provided isEquivalent function.

Signature

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

Added in v2.0.0

every

Check if a predicate holds true for every ReadonlyArray element.

Signature

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

Added in v2.0.0

findFirst

Returns the first element that satisfies the specified predicate, or None if no such element exists.

Signature

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

Added in v2.0.0

findFirstIndex

Return the first index for which a predicate holds.

Signature

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

Added in v2.0.0

findLast

Find the last element for which a predicate holds.

Signature

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

Added in v2.0.0

findLastIndex

Return the last index for which a predicate holds.

Signature

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

Added in v2.0.0

reverse

Reverse an Iterable, creating a new Array.

Signature

export declare const reverse: <S extends readonly [any, ...any[]] | Iterable<any>>(
  self: S
) => S extends readonly [infer A, ...(infer A)[]] ? [A, ...A[]] : S extends Iterable<infer A> ? A[] : never

Added in v2.0.0

some

Check if a predicate holds true for some ReadonlyArray element.

Signature

export declare const some: {
  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: readonly A[]) => self is readonly [A, ...A[]]
  <A>(self: readonly A[], predicate: (a: A, i: number) => boolean): self is readonly [A, ...A[]]
}

Added in v2.0.0

sortWith

Signature

export declare const sortWith: {
  <S extends readonly [any, ...any[]] | Iterable<any>, B>(
    f: (a: ReadonlyArray.Infer<S>) => B,
    order: Order.Order<B>
  ): (self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
  <A, B>(self: readonly [A, ...A[]], f: (a: A) => B, O: Order.Order<B>): [A, ...A[]]
  <A, B>(self: Iterable<A>, f: (a: A) => B, order: Order.Order<B>): A[]
}

Added in v2.0.0

filtering

filter

Signature

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

Added in v2.0.0

filterMap

Signature

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

Added in v2.0.0

filterMapWhile

Transforms all elements of the readonlyArray for as long as the specified function returns some value

Signature

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

Added in v2.0.0

getLefts

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

Signature

export declare const getLefts: <R, L>(self: Iterable<Either<R, L>>) => L[]

Example

import { Array, Either } from "effect"

assert.deepStrictEqual(Array.getLefts([Either.right(1), Either.left("err"), Either.right(2)]), ["err"])

Added in v2.0.0

getRights

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

Signature

export declare const getRights: <R, L>(self: Iterable<Either<R, L>>) => R[]

Example

import { Array, Either } from "effect"

assert.deepStrictEqual(Array.getRights([Either.right(1), Either.left("err"), Either.right(2)]), [1, 2])

Added in v2.0.0

getSomes

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

Signature

export declare const getSomes: <A>(self: Iterable<Option<A>>) => A[]

Example

import { Array, Option } from "effect"

assert.deepStrictEqual(Array.getSomes([Option.some(1), Option.none(), Option.some(2)]), [1, 2])

Added in v2.0.0

partition

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

Signature

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

Added in v2.0.0

partitionMap

Signature

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

Added in v2.0.0

separate

Signature

export declare const separate: <R, L>(self: Iterable<Either<R, L>>) => [L[], R[]]

Added in v2.0.0

folding

join

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

Signature

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

Added in v2.0.0

mapAccum

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

Signature

export declare const mapAccum: {
  <S, A, B>(s: S, f: (s: S, a: A, i: number) => readonly [S, B]): (self: Iterable<A>) => [state: S, mappedArray: B[]]
  <S, A, B>(self: Iterable<A>, s: S, f: (s: S, a: A, i: number) => readonly [S, B]): [state: S, mappedArray: B[]]
}

Added in v2.0.0

reduce

Signature

export 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
}

Added in v2.0.0

reduceRight

Signature

export 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
}

Added in v2.0.0

scan

Reduce an Iterable from the left, keeping all intermediate results instead of only the final result.

Signature

export declare const scan: {
  <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<A>) => [B, ...B[]]
  <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A) => B): [B, ...B[]]
}

Added in v2.0.0

scanRight

Reduce an Iterable from the right, keeping all intermediate results instead of only the final result.

Signature

export declare const scanRight: {
  <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<A>) => [B, ...B[]]
  <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A) => B): [B, ...B[]]
}

Added in 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.

Signature

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

Added in 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.

Signature

export declare const dropRight: { (n: number): <A>(self: Iterable<A>) => A[]; <A>(self: Iterable<A>, n: number): A[] }

Added in v2.0.0

dropWhile

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

Signature

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

Added in v2.0.0

get

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

Signature

export declare const get: {
  (index: number): <A>(self: readonly A[]) => Option<A>
  <A>(self: readonly A[], index: number): Option<A>
}

Added in v2.0.0

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

Signature

export declare const head: <A>(self: readonly A[]) => Option<A>

Added in v2.0.0

headNonEmpty

Signature

export declare const headNonEmpty: <A>(self: readonly [A, ...A[]]) => A

Added in 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

export declare const init: <A>(self: Iterable<A>) => Option<A[]>

Added in v2.0.0

initNonEmpty

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

Signature

export declare const initNonEmpty: <A>(self: readonly [A, ...A[]]) => A[]

Added in v2.0.0

last

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

Signature

export declare const last: <A>(self: readonly A[]) => Option<A>

Added in v2.0.0

lastNonEmpty

Signature

export declare const lastNonEmpty: <A>(self: readonly [A, ...A[]]) => A

Added in v2.0.0

length

Return the number of elements in a ReadonlyArray.

Signature

export declare const length: <A>(self: readonly A[]) => number

Added in 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

export declare const tail: <A>(self: Iterable<A>) => Option<A[]>

Added in v2.0.0

tailNonEmpty

Signature

export declare const tailNonEmpty: <A>(self: readonly [A, ...A[]]) => A[]

Added in 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.

Signature

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

Added in 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.

Signature

export declare const takeRight: { (n: number): <A>(self: Iterable<A>) => A[]; <A>(self: Iterable<A>, n: number): A[] }

Added in v2.0.0

takeWhile

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

Signature

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

Added in v2.0.0

grouping

group

Group equal, consecutive elements of a NonEmptyReadonlyArray into NonEmptyArrays.

Signature

export declare const group: <A>(self: readonly [A, ...A[]]) => [[A, ...A[]], ...[A, ...A[]][]]

Added in 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

Signature

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

Added in v2.0.0

groupWith

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

Signature

export declare const groupWith: {
  <A>(isEquivalent: (self: A, that: A) => boolean): (self: readonly [A, ...A[]]) => [[A, ...A[]], ...[A, ...A[]][]]
  <A>(self: readonly [A, ...A[]], isEquivalent: (self: A, that: A) => boolean): [[A, ...A[]], ...[A, ...A[]][]]
}

Added in v2.0.0

guards

isArray

Determine if unknown is an Array.

Signature

export declare const isArray: { (self: unknown): self is unknown[]; <T>(self: T): self is Extract<T, readonly any[]> }

Example

import { isArray } from "effect/Array"

assert.deepStrictEqual(isArray(null), false)
assert.deepStrictEqual(isArray([1, 2, 3]), true)

Added in v2.0.0

isEmptyArray

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

Signature

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

Example

import { isEmptyArray } from "effect/Array"

assert.deepStrictEqual(isEmptyArray([]), true)
assert.deepStrictEqual(isEmptyArray([1, 2, 3]), false)

Added in v2.0.0

isEmptyReadonlyArray

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

Signature

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

Example

import { isEmptyReadonlyArray } from "effect/Array"

assert.deepStrictEqual(isEmptyReadonlyArray([]), true)
assert.deepStrictEqual(isEmptyReadonlyArray([1, 2, 3]), false)

Added in 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.

Signature

export declare const isNonEmptyArray: <A>(self: A[]) => self is [A, ...A[]]

Example

import { isNonEmptyArray } from "effect/Array"

assert.deepStrictEqual(isNonEmptyArray([]), false)
assert.deepStrictEqual(isNonEmptyArray([1, 2, 3]), true)

Added in 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.

Signature

export declare const isNonEmptyReadonlyArray: <A>(self: readonly A[]) => self is readonly [A, ...A[]]

Example

import { isNonEmptyReadonlyArray } from "effect/Array"

assert.deepStrictEqual(isNonEmptyReadonlyArray([]), false)
assert.deepStrictEqual(isNonEmptyReadonlyArray([1, 2, 3]), true)

Added in v2.0.0

instances

getEquivalence

Signature

export declare const getEquivalence: <A>(
  isEquivalent: Equivalence.Equivalence<A>
) => Equivalence.Equivalence<readonly A[]>

Added in 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

export declare const getOrder: <A>(O: Order.Order<A>) => Order.Order<readonly A[]>

Added in v2.0.0

lifting

liftEither

Signature

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

Added in v2.0.0

liftNullable

Signature

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

Added in v2.0.0

liftOption

Signature

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

Added in v2.0.0

liftPredicate

Signature

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

Added in v2.0.0

mapping

map

Signature

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

Added in v2.0.0

models

NonEmptyArray (type alias)

Signature

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

Added in v2.0.0

NonEmptyReadonlyArray (type alias)

Signature

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

Added in v2.0.0

pattern matching

match

Signature

export declare const match: {
  <B, A, C = B>(options: {
    readonly onEmpty: LazyArg<B>
    readonly onNonEmpty: (self: readonly [A, ...A[]]) => C
  }): (self: readonly A[]) => B | C
  <A, B, C = B>(
    self: readonly A[],
    options: { readonly onEmpty: LazyArg<B>; readonly onNonEmpty: (self: readonly [A, ...A[]]) => C }
  ): B | C
}

Added in v2.0.0

matchLeft

Signature

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

Added in v2.0.0

matchRight

Signature

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

Added in 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

export declare const flatMap: {
  <S extends readonly any[], T extends readonly any[]>(
    f: (a: ReadonlyArray.Infer<S>, i: number) => T
  ): (self: S) => ReadonlyArray.AndNonEmpty<S, T, ReadonlyArray.Infer<T>>
  <A, B>(self: readonly [A, ...A[]], f: (a: A, i: number) => readonly [B, ...B[]]): [B, ...B[]]
  <A, B>(self: readonly A[], f: (a: A, i: number) => readonly B[]): B[]
}

Added in v2.0.0

flatMapNullable

Signature

export declare const flatMapNullable: {
  <A, B>(f: (a: A) => B | null | undefined): (self: readonly A[]) => NonNullable<B>[]
  <A, B>(self: readonly A[], f: (a: A) => B | null | undefined): NonNullable<B>[]
}

Added in v2.0.0

flatten

Flattens an array of arrays into a single array by concatenating all arrays.

Signature

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

Added in 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

export declare const sort: {
  <B>(
    O: Order.Order<B>
  ): <A extends B, S extends readonly A[] | Iterable<A>>(self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
  <A extends B, B>(self: readonly [A, ...A[]], O: Order.Order<B>): [A, ...A[]]
  <A extends B, B>(self: Iterable<A>, O: Order.Order<B>): A[]
}

Added in v2.0.0

sortBy

Sort the elements of an Iterable in increasing order, where elements are compared using first orders[0], then orders[1], etc…

Signature

export declare const sortBy: <S extends readonly [any, ...any[]] | Iterable<any>>(
  ...orders: readonly Order.Order<ReadonlyArray.Infer<S>>[]
) => (self: S) => S extends readonly [infer A, ...(infer A)[]] ? [A, ...A[]] : S extends Iterable<infer A> ? A[] : never

Added in 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.

Signature

export declare const chunksOf: {
  (
    n: number
  ): <S extends readonly any[] | Iterable<any>>(
    self: S
  ) => ReadonlyArray.With<S, [ReadonlyArray.Infer<S>, ...ReadonlyArray.Infer<S>[]]>
  <A>(self: readonly [A, ...A[]], n: number): [[A, ...A[]], ...[A, ...A[]][]]
  <A>(self: Iterable<A>, n: number): [A, ...A[]][]
}

Added in 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

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

Added in v2.0.0

split

Splits this iterable into n equally sized arrays.

Signature

export declare const split: { (n: number): <A>(self: Iterable<A>) => A[][]; <A>(self: Iterable<A>, n: number): A[][] }

Added in 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.

Signature

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

Added in 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.

Signature

export declare const splitNonEmptyAt: {
  (n: number): <A>(self: readonly [A, ...A[]]) => [beforeIndex: [A, ...A[]], fromIndex: A[]]
  <A>(self: readonly [A, ...A[]], n: number): [beforeIndex: [A, ...A[]], fromIndex: A[]]
}

Added in 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.

Signature

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

Added in v2.0.0

unappend

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

Signature

export declare const unappend: <A>(self: readonly [A, ...A[]]) => [arrayWithoutLastElement: A[], lastElement: A]

Added in v2.0.0

unprepend

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

Signature

export declare const unprepend: <A>(self: readonly [A, ...A[]]) => [firstElement: A, remainingElements: A[]]

Added in v2.0.0

type lambdas

ReadonlyArrayTypeLambda (interface)

Signature

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

Added in v2.0.0

unsafe

unsafeGet

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

Signature

export declare const unsafeGet: {
  (index: number): <A>(self: readonly A[]) => A
  <A>(self: readonly A[], index: number): A
}

Added in v2.0.0

utils

ReadonlyArray (namespace)

Added in v2.0.0

AndNonEmpty (type alias)

Signature

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

Added in v2.0.0

Flatten (type alias)

Signature

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

Added in v2.0.0

Infer (type alias)

Signature

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

Added in v2.0.0

OrNonEmpty (type alias)

Signature

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

Added in v2.0.0

With (type alias)

Signature

export type With<S extends ReadonlyArray<any> | Iterable<any>, A> =
  S extends NonEmptyReadonlyArray<any> ? NonEmptyArray<A> : Array<A>

Added in 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.

Signature

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

Added in v2.0.0

copy

Signature

export declare const copy: { <A>(self: readonly [A, ...A[]]): [A, ...A[]]; <A>(self: readonly A[]): A[] }

Added in 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

export declare const dedupe: <S extends readonly [any, ...any[]] | Iterable<any>>(
  self: S
) => S extends readonly [infer A, ...(infer A)[]] ? [A, ...A[]] : S extends Iterable<infer A> ? A[] : never

Added in v2.0.0

dedupeAdjacent

Deduplicates adjacent elements that are identical.

Signature

export declare const dedupeAdjacent: <A>(self: Iterable<A>) => A[]

Added in v2.0.0

dedupeAdjacentWith

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

Signature

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

Added in v2.0.0

dedupeWith

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

Signature

export declare const dedupeWith: {
  <S extends readonly any[] | Iterable<any>>(
    isEquivalent: (self: ReadonlyArray.Infer<S>, that: ReadonlyArray.Infer<S>) => boolean
  ): (self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
  <A>(self: readonly [A, ...A[]], isEquivalent: (self: A, that: A) => boolean): [A, ...A[]]
  <A>(self: Iterable<A>, isEquivalent: (self: A, that: A) => boolean): A[]
}

Added in 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.

Signature

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

Added in 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.

Signature

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

Added in v2.0.0

extend

Signature

export declare const extend: {
  <A, B>(f: (as: readonly A[]) => B): (self: readonly A[]) => B[]
  <A, B>(self: readonly A[], f: (as: readonly A[]) => B): B[]
}

Added in v2.0.0

forEach

Iterate over the Iterable applying f.

Signature

export 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
}

Added in 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.

Signature

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

Added in 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.

Signature

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

Added in 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.

Signature

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

Added in 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.

Signature

export declare const intersperse: {
  <B>(
    middle: B
  ): <S extends readonly any[] | Iterable<any>>(self: S) => ReadonlyArray.With<S, B | ReadonlyArray.Infer<S>>
  <A, B>(self: readonly [A, ...A[]], middle: B): [A | B, ...(A | B)[]]
  <A, B>(self: Iterable<A>, middle: B): (A | B)[]
}

Added in v2.0.0

max

Signature

export declare const max: {
  <A>(O: Order.Order<A>): (self: readonly [A, ...A[]]) => A
  <A>(self: readonly [A, ...A[]], O: Order.Order<A>): A
}

Added in v2.0.0

min

Signature

export declare const min: {
  <A>(O: Order.Order<A>): (self: readonly [A, ...A[]]) => A
  <A>(self: readonly [A, ...A[]], O: Order.Order<A>): A
}

Added in 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.

Signature

export declare const modify: {
  <A, B>(i: number, f: (a: A) => B): (self: Iterable<A>) => (A | B)[]
  <A, B>(self: Iterable<A>, i: number, f: (a: A) => B): (A | B)[]
}

Added in v2.0.0

modifyNonEmptyHead

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

Signature

export declare const modifyNonEmptyHead: {
  <A, B>(f: (a: A) => B): (self: readonly [A, ...A[]]) => [A | B, ...(A | B)[]]
  <A, B>(self: readonly [A, ...A[]], f: (a: A) => B): [A | B, ...(A | B)[]]
}

Added in v2.0.0

modifyNonEmptyLast

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

Signature

export declare const modifyNonEmptyLast: {
  <A, B>(f: (a: A) => B): (self: readonly [A, ...A[]]) => [A | B, ...(A | B)[]]
  <A, B>(self: readonly [A, ...A[]], f: (a: A) => B): [A | B, ...(A | B)[]]
}

Added in 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.

Signature

export declare const modifyOption: {
  <A, B>(i: number, f: (a: A) => B): (self: Iterable<A>) => Option<(A | B)[]>
  <A, B>(self: Iterable<A>, i: number, f: (a: A) => B): Option<(A | B)[]>
}

Added in v2.0.0

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.

Signature

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

Added in 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.

Signature

export declare const replace: {
  <B>(i: number, b: B): <A>(self: Iterable<A>) => (B | A)[]
  <A, B>(self: Iterable<A>, i: number, b: B): (A | B)[]
}

Added in v2.0.0

replaceOption

Signature

export declare const replaceOption: {
  <B>(i: number, b: B): <A>(self: Iterable<A>) => Option<(B | A)[]>
  <A, B>(self: Iterable<A>, i: number, b: B): Option<(A | B)[]>
}

Added in 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.

Signature

export declare const rotate: {
  (n: number): <S extends readonly any[] | Iterable<any>>(self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
  <A>(self: readonly [A, ...A[]], n: number): [A, ...A[]]
  <A>(self: Iterable<A>, n: number): A[]
}

Added in v2.0.0

setNonEmptyHead

Change the head, creating a new NonEmptyReadonlyArray.

Signature

export declare const setNonEmptyHead: {
  <B>(b: B): <A>(self: readonly [A, ...A[]]) => [B | A, ...(B | A)[]]
  <A, B>(self: readonly [A, ...A[]], b: B): [A | B, ...(A | B)[]]
}

Added in v2.0.0

setNonEmptyLast

Change the last element, creating a new NonEmptyReadonlyArray.

Signature

export declare const setNonEmptyLast: {
  <B>(b: B): <A>(self: readonly [A, ...A[]]) => [B | A, ...(B | A)[]]
  <A, B>(self: readonly [A, ...A[]], b: B): [A | B, ...(A | B)[]]
}

Added in v2.0.0

union

Signature

export declare const union: {
  <T extends readonly any[] | Iterable<any>>(
    that: T
  ): <S extends readonly any[] | Iterable<any>>(
    self: S
  ) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>
  <A, B>(self: readonly [A, ...A[]], that: readonly B[]): [A | B, ...(A | B)[]]
  <A, B>(self: readonly A[], that: readonly [B, ...B[]]): [A | B, ...(A | B)[]]
  <A, B>(self: Iterable<A>, that: Iterable<B>): (A | B)[]
}

Added in v2.0.0

unionWith

Signature

export declare const unionWith: {
  <S extends readonly any[] | Iterable<any>, T extends readonly any[] | 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: readonly [A, ...A[]],
    that: Iterable<B>,
    isEquivalent: (self: A, that: B) => boolean
  ): [A | B, ...(A | B)[]]
  <A, B>(
    self: Iterable<A>,
    that: readonly [B, ...B[]],
    isEquivalent: (self: A, that: B) => boolean
  ): [A | B, ...(A | B)[]]
  <A, B>(self: Iterable<A>, that: Iterable<B>, isEquivalent: (self: A, that: B) => boolean): (A | B)[]
}

Added in v2.0.0

unzip

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

Signature

export declare const unzip: <
  S extends Iterable<readonly [any, any]> | readonly [readonly [any, any], ...(readonly [any, any])[]]
>(
  self: S
) => S extends readonly [readonly [infer A, infer B], ...(readonly [infer A, infer B])[]]
  ? [[A, ...A[]], [B, ...B[]]]
  : S extends Iterable<readonly [infer A, infer B]>
    ? [A[], B[]]
    : never

Added in 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.

Signature

export declare const zip: {
  <B>(that: readonly [B, ...B[]]): <A>(self: readonly [A, ...A[]]) => [[A, B], ...[A, B][]]
  <B>(that: Iterable<B>): <A>(self: Iterable<A>) => [A, B][]
  <A, B>(self: readonly [A, ...A[]], that: readonly [B, ...B[]]): [[A, B], ...[A, B][]]
  <A, B>(self: Iterable<A>, that: Iterable<B>): [A, B][]
}

Added in 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.

Signature

export declare const zipWith: {
  <B, A, C>(that: readonly [B, ...B[]], f: (a: A, b: B) => C): (self: readonly [A, ...A[]]) => [C, ...C[]]
  <B, A, C>(that: Iterable<B>, f: (a: A, b: B) => C): (self: Iterable<A>) => C[]
  <A, B, C>(self: readonly [A, ...A[]], that: readonly [B, ...B[]], f: (a: A, b: B) => C): [C, ...C[]]
  <B, A, C>(self: Iterable<A>, that: Iterable<B>, f: (a: A, b: B) => C): C[]
}

Added in v2.0.0