Array overview

The Array module provides tools for working with Typescript’s Array type in a functional way.

In functional jargon, this module provides a monadic interface over Typescript’s Array.

Added in v2.0.0

Table of contents

constructors

makeBy

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

Note. n is normalized to a non negative integer.

Signature

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

Example

import { makeBy } from 'fp-ts/Array'

const double = (i: number): number => i * 2
assert.deepStrictEqual(makeBy(5, double), [0, 2, 4, 6, 8])
assert.deepStrictEqual(makeBy(-3, double), [])
assert.deepStrictEqual(makeBy(4.32164, double), [0, 2, 4, 6])

Added in v2.0.0

of

Given an element of the base type, of builds an Array containing just that element of the base type (this is useful for building a Monad).

Signature

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

Example

import { of } from 'fp-ts/Array'

assert.deepStrictEqual(of('a'), ['a'])

Added in v2.0.0

replicate

Create a Array containing a value repeated the specified number of times.

Note. n is normalized to a non negative integer.

Signature

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

Example

import { replicate } from 'fp-ts/Array'

assert.deepStrictEqual(replicate(3, 'a'), ['a', 'a', 'a'])
assert.deepStrictEqual(replicate(-3, 'a'), [])
assert.deepStrictEqual(replicate(2.985647, 'a'), ['a', 'a'])

Added in v2.0.0

conversions

fromEither

Create an array from an Either. The resulting array will contain the content of the Either if it is Right and it will be empty if the Either is Left.

Signature

export declare const fromEither: <A>(fa: Either<unknown, A>) => A[]

Example

import { fromEither } from 'fp-ts/Array'
import { either } from 'fp-ts'
import { pipe } from 'fp-ts/function'

assert.deepStrictEqual(pipe(either.right('r'), fromEither), ['r'])
assert.deepStrictEqual(pipe(either.left('l'), fromEither), [])

Added in v2.11.0

fromOption

Create an array from an Option. The resulting array will contain the content of the Option if it is Some and it will be empty if the Option is None.

Signature

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

Example

import { fromOption } from 'fp-ts/Array'
import { option } from 'fp-ts'
import { pipe } from 'fp-ts/function'

assert.deepStrictEqual(pipe(option.some('a'), fromOption), ['a'])
assert.deepStrictEqual(pipe(option.none, fromOption), [])

Added in v2.11.0

do notation

Do

Signature

export declare const Do: {}[]

Added in v2.9.0

apS

Signature

export declare const apS: <N, A, B>(
  name: Exclude<N, keyof A>,
  fb: B[]
) => (fa: A[]) => { readonly [K in N | keyof A]: K extends keyof A ? A[K] : B }[]

Added in v2.8.0

bind

Signature

export declare const bind: <N, A, B>(
  name: Exclude<N, keyof A>,
  f: (a: A) => B[]
) => (ma: A[]) => { readonly [K in N | keyof A]: K extends keyof A ? A[K] : B }[]

Added in v2.8.0

bindTo

Signature

export declare const bindTo: <N>(name: N) => <A>(fa: A[]) => { readonly [K in N]: A }[]

Added in v2.8.0

guard

Signature

export declare const guard: (b: boolean) => void[]

Added in v2.11.0

let

Signature

export declare const let: <N, A, B>(
  name: Exclude<N, keyof A>,
  f: (a: A) => B
) => (fa: A[]) => { readonly [K in N | keyof A]: K extends keyof A ? A[K] : B }[]

Added in v2.13.0

error handling

alt

Identifies an associative operation on a type constructor. It is similar to Semigroup, except that it applies to types of kind * -> *.

In case of Array concatenates the inputs into a single array.

Signature

export declare const alt: <A>(that: LazyArg<A[]>) => (fa: A[]) => A[]

Example

import * as A from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

assert.deepStrictEqual(
  pipe(
    [1, 2, 3],
    A.alt(() => [4, 5])
  ),
  [1, 2, 3, 4, 5]
)

Added in v2.0.0

altW

Less strict version of alt.

The W suffix (short for Widening) means that the return types will be merged.

Signature

export declare const altW: <B>(that: LazyArg<B[]>) => <A>(fa: A[]) => (B | A)[]

Example

import * as A from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

assert.deepStrictEqual(
  pipe(
    [1, 2, 3],
    A.altW(() => ['a', 'b'])
  ),
  [1, 2, 3, 'a', 'b']
)

Added in v2.9.0

filtering

compact

Compact an array of Options discarding the None values and keeping the Some values. It returns a new array containing the values of the Some options.

Signature

export declare const compact: <A>(fa: Option<A>[]) => A[]

Example

import { compact } from 'fp-ts/Array'
import { option } from 'fp-ts'

assert.deepStrictEqual(compact([option.some('a'), option.none, option.some('b')]), ['a', 'b'])

Added in v2.0.0

filter

Given an iterating function that is a Predicate or a Refinement, filter creates a new Array containing the elements of the original Array for which the iterating function is true.

Signature

export declare const filter: {
  <A, B extends A>(refinement: Refinement<A, B>): (as: A[]) => B[]
  <A>(predicate: Predicate<A>): <B extends A>(bs: B[]) => B[]
  <A>(predicate: Predicate<A>): (as: A[]) => A[]
}

Example

import { filter } from 'fp-ts/Array'
import { isString } from 'fp-ts/string'

assert.deepStrictEqual(filter(isString)(['a', 1, {}, 'b', 5]), ['a', 'b'])
assert.deepStrictEqual(filter((x: number) => x > 0)([-3, 1, -2, 5]), [1, 5])

Added in v2.0.0

filterMap

Maps an array with an iterating function that returns an Option and it keeps only the Some values discarding the Nones.

Signature

export declare const filterMap: <A, B>(f: (a: A) => Option<B>) => (fa: A[]) => B[]

Example

import { filterMap } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'
import { option } from 'fp-ts'

const f = (s: string) => (s.length === 1 ? option.some(s.toUpperCase()) : option.none)
assert.deepStrictEqual(pipe(['a', 'no', 'neither', 'b'], filterMap(f)), ['A', 'B'])

Added in v2.0.0

filterMapWithIndex

Maps an array with an iterating function that takes the index and the value of each element and returns an Option. It keeps only the Some values discarding the Nones.

Same as filterMap, but with an iterating function which takes also the index as input.

Signature

export declare const filterMapWithIndex: <A, B>(f: (i: number, a: A) => Option<B>) => (fa: A[]) => B[]

Example

import { filterMapWithIndex } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'
import { option } from 'fp-ts'

const f = (i: number, s: string) => (i % 2 === 1 ? option.some(s.toUpperCase()) : option.none)
assert.deepStrictEqual(pipe(['a', 'no', 'neither', 'b'], filterMapWithIndex(f)), ['NO', 'B'])

Added in v2.0.0

filterWithIndex

Same as filter, but passing also the index to the iterating function.

Signature

export declare const filterWithIndex: {
  <A, B extends A>(refinementWithIndex: RefinementWithIndex<number, A, B>): (as: A[]) => B[]
  <A>(predicateWithIndex: PredicateWithIndex<number, A>): <B extends A>(bs: B[]) => B[]
  <A>(predicateWithIndex: PredicateWithIndex<number, A>): (as: A[]) => A[]
}

Example

import { filterWithIndex } from 'fp-ts/Array'

const f = (index: number, x: number) => x > 0 && index <= 2
assert.deepStrictEqual(filterWithIndex(f)([-3, 1, -2, 5]), [1])

Added in v2.0.0

partition

Given an iterating function that is a Predicate or a Refinement, partition creates two new Arrays: right containing the elements of the original Array for which the iterating function is true, left containing the elements for which it is false.

Signature

export declare const partition: {
  <A, B extends A>(refinement: Refinement<A, B>): (as: A[]) => Separated<A[], B[]>
  <A>(predicate: Predicate<A>): <B extends A>(bs: B[]) => Separated<B[], B[]>
  <A>(predicate: Predicate<A>): (as: A[]) => Separated<A[], A[]>
}

Example

import { partition } from 'fp-ts/Array'
import { isString } from 'fp-ts/string'

assert.deepStrictEqual(partition(isString)(['a', 1, {}, 'b', 5]), { left: [1, {}, 5], right: ['a', 'b'] })
assert.deepStrictEqual(partition((x: number) => x > 0)([-3, 1, -2, 5]), { left: [-3, -2], right: [1, 5] })

Added in v2.0.0

partitionMap

Given an iterating function that returns an Either, partitionMap applies the iterating function to each element and it creates two Arrays: right containing the values of Right results, left containing the values of Left results.

Signature

export declare const partitionMap: <A, B, C>(f: (a: A) => Either<B, C>) => (fa: A[]) => Separated<B[], C[]>

Example

import { partitionMap } from 'fp-ts/Array'
import { Either, left, right } from 'fp-ts/Either'

const upperIfString = <B>(x: B): Either<B, string> => (typeof x === 'string' ? right(x.toUpperCase()) : left(x))
assert.deepStrictEqual(partitionMap(upperIfString)([-2, 'hello', 6, 7, 'world']), {
  left: [-2, 6, 7],
  right: ['HELLO', 'WORLD'],
})

Added in v2.0.0

partitionMapWithIndex

Same as partitionMap, but passing also the index to the iterating function.

Signature

export declare const partitionMapWithIndex: <A, B, C>(
  f: (i: number, a: A) => Either<B, C>
) => (fa: A[]) => Separated<B[], C[]>

Example

import { partitionMapWithIndex } from 'fp-ts/Array'
import { Either, left, right } from 'fp-ts/Either'

const upperIfStringBefore3 = <B>(index: number, x: B): Either<B, string> =>
  index < 3 && typeof x === 'string' ? right(x.toUpperCase()) : left(x)
assert.deepStrictEqual(partitionMapWithIndex(upperIfStringBefore3)([-2, 'hello', 6, 7, 'world']), {
  left: [-2, 6, 7, 'world'],
  right: ['HELLO'],
})

Added in v2.0.0

partitionWithIndex

Same as partition, but passing also the index to the iterating function.

Signature

export declare const partitionWithIndex: {
  <A, B extends A>(refinementWithIndex: RefinementWithIndex<number, A, B>): (as: A[]) => Separated<A[], B[]>
  <A>(predicateWithIndex: PredicateWithIndex<number, A>): <B extends A>(bs: B[]) => Separated<B[], B[]>
  <A>(predicateWithIndex: PredicateWithIndex<number, A>): (as: A[]) => Separated<A[], A[]>
}

Example

import { partitionWithIndex } from 'fp-ts/Array'

assert.deepStrictEqual(partitionWithIndex((index, x: number) => index < 3 && x > 0)([-2, 5, 6, 7]), {
  left: [-2, 7],
  right: [5, 6],
})

Added in v2.0.0

separate

Separate an array of Eithers into Lefts and Rights, creating two new arrays: one containing all the left values and one containing all the right values.

Signature

export declare const separate: <A, B>(fa: Either<A, B>[]) => Separated<A[], B[]>

Example

import { separate } from 'fp-ts/Array'
import { either } from 'fp-ts'

assert.deepStrictEqual(separate([either.right('r1'), either.left('l1'), either.right('r2')]), {
  left: ['l1'],
  right: ['r1', 'r2'],
})

Added in v2.0.0

wilt

Signature

export declare const wilt: PipeableWilt1<'Array'>

Added in v2.6.5

wither

Signature

export declare const wither: PipeableWither1<'Array'>

Added in v2.6.5

folding

foldMap

Map and fold an Array. Map the Array passing each value to the iterating function. Then fold the results using the provided Monoid.

Signature

export declare const foldMap: <M>(M: Monoid<M>) => <A>(f: (a: A) => M) => (fa: A[]) => M

Example

import { foldMap } from 'fp-ts/Array'

const monoid = { concat: (a: string, b: string) => a + b, empty: '' }
const f = (s: string) => s.toUpperCase()
assert.deepStrictEqual(foldMap(monoid)(f)(['a', 'b', 'c']), 'ABC')

Added in v2.0.0

foldMapWithIndex

Same as foldMap but passing also the index to the iterating function.

Signature

export declare const foldMapWithIndex: <M>(M: Monoid<M>) => <A>(f: (i: number, a: A) => M) => (fa: A[]) => M

Example

import { foldMapWithIndex } from 'fp-ts/Array'

const monoid = { concat: (a: string, b: string) => a + b, empty: '' }
const f = (index: number, s: string) => `${s.toUpperCase()}(${index})`
assert.deepStrictEqual(foldMapWithIndex(monoid)(f)(['a', 'b', 'c']), 'A(0)B(1)C(2)')

Added in v2.0.0

reduce

Reduces an Array.

reduce executes the supplied iterating function on each element of the array, in order, passing in the element and the return value from the calculation on the preceding element.

The first time that the iterating function is called there is no “return value of the previous calculation”, the initial value is used in its place.

Signature

export declare const reduce: <A, B>(b: B, f: (b: B, a: A) => B) => (fa: A[]) => B

Example

import { reduce } from 'fp-ts/Array'

assert.deepStrictEqual(reduce(5, (acc: number, cur: number) => acc * cur)([2, 3]), 5 * 2 * 3)

Added in v2.0.0

reduceRight

Same as reduce but applied from the end to the start.

Note: the iterating function in this case takes the accumulator as the last argument.

Signature

export declare const reduceRight: <A, B>(b: B, f: (a: A, b: B) => B) => (fa: A[]) => B

Example

import { reduceRight } from 'fp-ts/Array'

assert.deepStrictEqual(reduceRight('', (cur: string, acc: string) => acc + cur)(['a', 'b', 'c']), 'cba')

Added in v2.0.0

reduceRightWithIndex

Same as reduceRight but passing also the index to the iterating function.

Signature

export declare const reduceRightWithIndex: <A, B>(b: B, f: (i: number, a: A, b: B) => B) => (fa: A[]) => B

Example

import { reduceRightWithIndex } from 'fp-ts/Array'

const f = (index: number, cur: unknown, acc: string) => acc + (typeof cur === 'string' ? cur.toUpperCase() + index : '')
assert.deepStrictEqual(reduceRightWithIndex('', f)([2, 'a', 'b', null]), 'B2A1')

Added in v2.0.0

reduceWithIndex

Same as reduce but passing also the index to the iterating function.

Signature

export declare const reduceWithIndex: <A, B>(b: B, f: (i: number, b: B, a: A) => B) => (fa: A[]) => B

Example

import { reduceWithIndex } from 'fp-ts/Array'

const f = (index: number, acc: string, cur: unknown) => acc + (typeof cur === 'string' ? cur.toUpperCase() + index : '')
assert.deepStrictEqual(reduceWithIndex('', f)([2, 'a', 'b', null]), 'A1B2')

Added in v2.0.0

instances

Alt

Signature

export declare const Alt: Alt1<'Array'>

Added in v2.7.0

Alternative

Signature

export declare const Alternative: Alternative1<'Array'>

Added in v2.7.0

Applicative

Signature

export declare const Applicative: Applicative1<'Array'>

Added in v2.7.0

Apply

Signature

export declare const Apply: Apply1<'Array'>

Added in v2.10.0

Chain

Signature

export declare const Chain: Chain1<'Array'>

Added in v2.10.0

ChainRecBreadthFirst

Signature

export declare const ChainRecBreadthFirst: ChainRec1<'Array'>

Added in v2.11.0

ChainRecDepthFirst

Signature

export declare const ChainRecDepthFirst: ChainRec1<'Array'>

Added in v2.11.0

Compactable

Signature

export declare const Compactable: Compactable1<'Array'>

Added in v2.7.0

Extend

Signature

export declare const Extend: Extend1<'Array'>

Added in v2.7.0

Filterable

Signature

export declare const Filterable: Filterable1<'Array'>

Added in v2.7.0

FilterableWithIndex

Signature

export declare const FilterableWithIndex: FilterableWithIndex1<'Array', number>

Added in v2.7.0

Foldable

Signature

export declare const Foldable: Foldable1<'Array'>

Added in v2.7.0

FoldableWithIndex

Signature

export declare const FoldableWithIndex: FoldableWithIndex1<'Array', number>

Added in v2.7.0

FromEither

Signature

export declare const FromEither: FromEither1<'Array'>

Added in v2.11.0

Functor

Signature

export declare const Functor: Functor1<'Array'>

Added in v2.7.0

FunctorWithIndex

Signature

export declare const FunctorWithIndex: FunctorWithIndex1<'Array', number>

Added in v2.7.0

Monad

Signature

export declare const Monad: Monad1<'Array'>

Added in v2.7.0

Pointed

Signature

export declare const Pointed: Pointed1<'Array'>

Added in v2.10.0

Traversable

Signature

export declare const Traversable: Traversable1<'Array'>

Added in v2.7.0

TraversableWithIndex

Signature

export declare const TraversableWithIndex: TraversableWithIndex1<'Array', number>

Added in v2.7.0

Unfoldable

Signature

export declare const Unfoldable: Unfoldable1<'Array'>

Added in v2.7.0

Witherable

Signature

export declare const Witherable: Witherable1<'Array'>

Added in v2.7.0

Zero

Signature

export declare const Zero: Zero1<'Array'>

Added in v2.11.0

getDifferenceMagma

Get a Magma for Array where the concat function is the differnce between the first and the second array, i.e. the result contains all the elements of the first array for which their is no equal element in the second array according to the Eq provided.

Signature

export declare const getDifferenceMagma: <A>(E: Eq<A>) => Magma<A[]>

Example

import { getDifferenceMagma } from 'fp-ts/Array'
import { Eq } from 'fp-ts/number'

const S = getDifferenceMagma<number>(Eq)
assert.deepStrictEqual(S.concat([1, 2], [2, 3]), [1])

Added in v2.11.0

getEq

Derives an Eq over the Array of a given element type from the Eq of that type. The derived Eq defines two arrays as equal if all elements of both arrays are compared equal pairwise with the given E. In case of arrays of different lengths, the result is non equality.

Signature

export declare const getEq: <A>(E: Eq<A>) => Eq<A[]>

Example

import * as S from 'fp-ts/string'
import { getEq } from 'fp-ts/Array'

const E = getEq(S.Eq)
assert.strictEqual(E.equals(['a', 'b'], ['a', 'b']), true)
assert.strictEqual(E.equals(['a'], []), false)

Added in v2.0.0

getIntersectionSemigroup

Get a Semigroup based on the intersection of the elements of Arrays. Only elements present in the two arrays which are equal according to the provided Eq are included in the result.

Signature

export declare const getIntersectionSemigroup: <A>(E: Eq<A>) => Semigroup<A[]>

Example

import { getIntersectionSemigroup } from 'fp-ts/Array'
import { Eq } from 'fp-ts/number'

const S = getIntersectionSemigroup<number>(Eq)
assert.deepStrictEqual(S.concat([1, 2], [2, 3]), [2])

Added in v2.11.0

getMonoid

Returns a Monoid for Array<A> based on the concatenation of Arrays.

Signature

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

Example

import { getMonoid } from 'fp-ts/Array'

const M = getMonoid<number>()
assert.deepStrictEqual(M.concat([1, 2], [3, 4]), [1, 2, 3, 4])

Added in v2.0.0

getOrd

Derives an Ord over the Array of a given element type from the Ord of that type. The ordering between two such arrays is equal to: the first non equal comparison of each arrays elements taken pairwise in increasing order, in case of equality over all the pairwise elements; the longest array is considered the greatest, if both arrays have the same length, the result is equality.

Signature

export declare const getOrd: <A>(O: Ord<A>) => Ord<A[]>

Example

import { getOrd } from 'fp-ts/Array'
import * as S from 'fp-ts/string'

const O = getOrd(S.Ord)
assert.strictEqual(O.compare(['b'], ['a']), 1)
assert.strictEqual(O.compare(['a'], ['a']), 0)
assert.strictEqual(O.compare(['a'], ['b']), -1)

Added in v2.0.0

getSemigroup

Get a Semigroup based on the concatenation of Arrays. See also getMonoid.

Signature

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

Example

import { getSemigroup } from 'fp-ts/Array'

const S = getSemigroup<number>()
assert.deepStrictEqual(S.concat([1, 2], [2, 3]), [1, 2, 2, 3])

Added in v2.10.0

getShow

getShow makes a Show for an Array<A> from a Show for an A.

Signature

export declare const getShow: <A>(S: Show<A>) => Show<A[]>

Example

import { getShow } from 'fp-ts/Array'

const numShow = { show: (n: number) => (n >= 0 ? `${n}` : `(${-n})`) }
assert.deepStrictEqual(getShow(numShow).show([-2, -1, 0, 1]), '[(2), (1), 0, 1]')

Added in v2.0.0

getUnionMonoid

Get a Monoid based on the union of the elements of Arrays. Elements which equal according to the provided Eq are included only once in the result.

Signature

export declare const getUnionMonoid: <A>(E: Eq<A>) => Monoid<A[]>

Example

import { getUnionMonoid } from 'fp-ts/Array'
import { Eq } from 'fp-ts/number'

const M = getUnionMonoid<number>(Eq)
assert.deepStrictEqual(M.concat([1, 2], [2, 3]), [1, 2, 3])
assert.deepStrictEqual(M.empty, [])

Added in v2.11.0

getUnionSemigroup

Get a Semigroup based on the union of the elements of Arrays. Elements which equal according to the provided Eq are included only once in the result. See also getUnionMonoid.

Signature

export declare const getUnionSemigroup: <A>(E: Eq<A>) => Semigroup<A[]>

Example

import { getUnionSemigroup } from 'fp-ts/Array'
import { Eq } from 'fp-ts/number'

const S = getUnionSemigroup<number>(Eq)
assert.deepStrictEqual(S.concat([1, 2], [2, 3]), [1, 2, 3])

Added in v2.11.0

legacy

chain

Alias of flatMap.

Signature

export declare const chain: <A, B>(f: (a: A) => B[]) => (ma: A[]) => B[]

Added in v2.0.0

lifting

fromEitherK

Signature

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

Added in v2.11.0

fromOptionK

Signature

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

Added in v2.11.0

fromPredicate

Create an array with one element, if the element satisfies the predicate, otherwise it returns an empty array.

Signature

export declare function fromPredicate<A, B extends A>(refinement: Refinement<A, B>): (a: A) => Array<B>
export declare function fromPredicate<A>(predicate: Predicate<A>): <B extends A>(b: B) => Array<B>
export declare function fromPredicate<A>(predicate: Predicate<A>): (a: A) => Array<A>

Example

import { fromPredicate } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'
import { isString } from 'fp-ts/string'

assert.deepStrictEqual(pipe('a', fromPredicate(isString)), ['a'])
assert.deepStrictEqual(pipe(7, fromPredicate(isString)), [])

assert.deepStrictEqual(
  pipe(
    7,
    fromPredicate((x) => x > 0)
  ),
  [7]
)
assert.deepStrictEqual(
  pipe(
    -3,
    fromPredicate((x) => x > 0)
  ),
  []
)

Added in v2.11.0

mapping

flap

Given an input an Array of functions, flap returns an Array containing the results of applying each function to the given input.

Signature

export declare const flap: <A>(a: A) => <B>(fab: ((a: A) => B)[]) => B[]

Example

import { flap } from 'fp-ts/Array'

const funs = [(n: number) => `Double: ${n * 2}`, (n: number) => `Triple: ${n * 3}`, (n: number) => `Square: ${n * n}`]
assert.deepStrictEqual(flap(4)(funs), ['Double: 8', 'Triple: 12', 'Square: 16'])

Added in v2.10.0

map

map can be used to turn functions (a: A) => B into functions (fa: Array<A>) => Array<B>. In practice it applies the base function to each element of the array and collects the results in a new array.

Signature

export declare const map: <A, B>(f: (a: A) => B) => (fa: A[]) => B[]

Example

import { map } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

const f = (n: number) => n * 2
assert.deepStrictEqual(pipe([1, 2, 3], map(f)), [2, 4, 6])

Added in v2.0.0

mapWithIndex

Same as map, but the iterating function takes both the index and the value of the element.

Signature

export declare const mapWithIndex: <A, B>(f: (i: number, a: A) => B) => (fa: A[]) => B[]

Example

import { mapWithIndex } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

const f = (i: number, s: string) => `${s} - ${i}`
assert.deepStrictEqual(pipe(['a', 'b', 'c'], mapWithIndex(f)), ['a - 0', 'b - 1', 'c - 2'])

Added in v2.0.0

pattern matching

foldLeft

Alias of matchLeft.

Signature

export declare const foldLeft: <A, B>(onEmpty: LazyArg<B>, onNonEmpty: (head: A, tail: A[]) => B) => (as: A[]) => B

Added in v2.0.0

foldRight

Alias of matchRight.

Signature

export declare const foldRight: <A, B>(onEmpty: LazyArg<B>, onNonEmpty: (init: A[], last: A) => B) => (as: A[]) => B

Added in v2.0.0

match

Takes an array, if the array is empty it returns the result of onEmpty, otherwise it passes the array to onNonEmpty and returns the result.

Signature

export declare const match: <B, A>(onEmpty: LazyArg<B>, onNonEmpty: (as: NEA.NonEmptyArray<A>) => B) => (as: A[]) => B

Example

import { match } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

const matcher = match(
  () => 'No elements',
  (as) => `Found ${as.length} element(s)`
)
assert.deepStrictEqual(pipe([1, 2, 3, 4], matcher), 'Found 4 element(s)')
assert.deepStrictEqual(pipe([], matcher), 'No elements')

Added in v2.11.0

matchLeft

Takes an array, if the array is empty it returns the result of onEmpty, otherwise it passes the array to onNonEmpty broken into its first element and remaining elements.

Signature

export declare const matchLeft: <B, A>(onEmpty: LazyArg<B>, onNonEmpty: (head: A, tail: A[]) => B) => (as: A[]) => B

Example

import { matchLeft } from 'fp-ts/Array'

const len: <A>(as: Array<A>) => number = matchLeft(
  () => 0,
  (_, tail) => 1 + len(tail)
)
assert.strictEqual(len([1, 2, 3]), 3)

Added in v2.10.0

matchLeftW

Less strict version of matchLeft. It will work when onEmpty and onNonEmpty have different return types.

Signature

export declare const matchLeftW: <B, A, C>(
  onEmpty: LazyArg<B>,
  onNonEmpty: (head: A, tail: A[]) => C
) => (as: A[]) => B | C

Example

import { matchLeftW } from 'fp-ts/Array'

const f = matchLeftW(
  () => 0,
  (head: string, tail: string[]) => `Found "${head}" followed by ${tail.length} elements`
)
assert.strictEqual(f(['a', 'b', 'c']), 'Found "a" followed by 2 elements')
assert.strictEqual(f([]), 0)

Added in v2.11.0

matchRight

Takes an array, if the array is empty it returns the result of onEmpty, otherwise it passes the array to onNonEmpty broken into its initial elements and the last element.

Signature

export declare const matchRight: <B, A>(onEmpty: LazyArg<B>, onNonEmpty: (init: A[], last: A) => B) => (as: A[]) => B

Example

import { matchRight } from 'fp-ts/Array'

const len: <A>(as: Array<A>) => number = matchRight(
  () => 0,
  (head, _) => 1 + len(head)
)
assert.strictEqual(len([1, 2, 3]), 3)

Added in v2.10.0

matchRightW

Less strict version of matchRight. It will work when onEmpty and onNonEmpty have different return types.

Signature

export declare const matchRightW: <B, A, C>(
  onEmpty: LazyArg<B>,
  onNonEmpty: (init: A[], last: A) => C
) => (as: A[]) => B | C

Example

import { matchRightW } from 'fp-ts/Array'

const f = matchRightW(
  () => 0,
  (head: string[], tail: string) => `Found ${head.length} elements folllowed by "${tail}"`
)
assert.strictEqual(f(['a', 'b', 'c']), 'Found 2 elements folllowed by "c"')
assert.strictEqual(f([]), 0)

Added in v2.11.0

matchW

Less strict version of match.

The W suffix (short for Widening) means that the handler return types will be merged.

Signature

export declare const matchW: <B, A, C>(
  onEmpty: LazyArg<B>,
  onNonEmpty: (as: NEA.NonEmptyArray<A>) => C
) => (as: A[]) => B | C

Example

import { matchW } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

const matcherW = matchW(
  () => 'No elements',
  (as) => as.length
)
assert.deepStrictEqual(pipe([1, 2, 3, 4], matcherW), 4)
assert.deepStrictEqual(pipe([], matcherW), 'No elements')

Added in v2.11.0

refinements

isEmpty

Test whether an array is empty

Signature

export declare const isEmpty: <A>(as: A[]) => as is []

Example

import { isEmpty } from 'fp-ts/Array'

assert.strictEqual(isEmpty([]), true)
assert.strictEqual(isEmpty(['a']), false)

Added in v2.0.0

isNonEmpty

Test whether an array is non empty narrowing down the type to NonEmptyArray<A>

Signature

export declare const isNonEmpty: <A>(as: A[]) => as is NEA.NonEmptyArray<A>

Example

import { isNonEmpty } from 'fp-ts/Array'

assert.strictEqual(isNonEmpty([]), false)
assert.strictEqual(isNonEmpty(['a']), true)

Added in v2.0.0

sequencing

chainFirst

Composes computations in sequence, using the return value of one computation to determine the next computation and keeping only the result of the first.

Signature

export declare const chainFirst: <A, B>(f: (a: A) => B[]) => (first: A[]) => A[]

Example

import * as A from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

assert.deepStrictEqual(
  pipe(
    [1, 2, 3],
    A.chainFirst(() => ['a', 'b'])
  ),
  [1, 1, 2, 2, 3, 3]
)
assert.deepStrictEqual(
  pipe(
    [1, 2, 3],
    A.chainFirst(() => [])
  ),
  []
)

Added in v2.0.0

chainRecBreadthFirst

Signature

export declare const chainRecBreadthFirst: <A, B>(f: (a: A) => Either<A, B>[]) => (a: A) => B[]

Added in v2.11.0

chainRecDepthFirst

Signature

export declare const chainRecDepthFirst: <A, B>(f: (a: A) => Either<A, B>[]) => (a: A) => B[]

Added in v2.11.0

chainWithIndex

Same as chain, but passing also the index to the iterating function.

Signature

export declare const chainWithIndex: <A, B>(f: (i: number, a: A) => B[]) => (as: A[]) => B[]

Example

import { chainWithIndex, replicate } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

const f = (index: number, x: string) => replicate(2, `${x}${index}`)
assert.deepStrictEqual(pipe(['a', 'b', 'c'], chainWithIndex(f)), ['a0', 'a0', 'b1', 'b1', 'c2', 'c2'])

Added in v2.7.0

flatMap

Composes computations in sequence, using the return value of one computation to determine the next computation.

In other words it takes a function f that produces an array from a single element of the base type A and returns a new function which applies f to each element of the input array (like map) and, instead of returning an array of arrays, concatenates the results into a single array (like flatten).

Signature

export declare const flatMap: {
  <A, B>(f: (a: A, i: number) => B[]): (ma: A[]) => B[]
  <A, B>(ma: A[], f: (a: A, i: number) => B[]): B[]
}

Example

import { flatMap, map, replicate } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

const f = (n: number) => replicate(n, `${n}`)
assert.deepStrictEqual(pipe([1, 2, 3], map(f)), [['1'], ['2', '2'], ['3', '3', '3']])
assert.deepStrictEqual(pipe([1, 2, 3], flatMap(f)), ['1', '2', '2', '3', '3', '3'])

Added in v2.14.0

flatten

Takes an array of arrays of A and flattens them into an array of A by concatenating the elements of each array in order.

Signature

export declare const flatten: <A>(mma: A[][]) => A[]

Example

import { flatten } from 'fp-ts/Array'

assert.deepStrictEqual(flatten([['a'], ['b', 'c'], ['d', 'e', 'f']]), ['a', 'b', 'c', 'd', 'e', 'f'])

Added in v2.5.0

traverseWithIndex

Same as traverse but passing also the index to the iterating function.

Signature

export declare const traverseWithIndex: PipeableTraverseWithIndex1<'Array', number>

Example

import { traverseWithIndex } from 'fp-ts/Array'
import { Applicative, left, right } from 'fp-ts/Either'

const f = (index: number, x: unknown) =>
  typeof x === 'string' ? right(x.toUpperCase() + index) : left(new Error('not a string'))
assert.deepStrictEqual(traverseWithIndex(Applicative)(f)(['a', 'b']), right(['A0', 'B1']))
assert.deepStrictEqual(traverseWithIndex(Applicative)(f)(['a', 5]), left(new Error('not a string')))

Added in v2.6.3

traversing

sequence

sequence takes an Array where elements are HKT<A> (higher kinded type) and, using an applicative of that HKT, returns an HKT of Array<A>. E.g. it can turn an Array<Either<Error, string>> into an Either<Error, Array<string>>.

sequence requires an Applicative of the HKT you are targeting, e.g. to turn an Array<Either<E, A>> into an Either<E, Array<A>>, it needs an Applicative for Either, to to turn an Array<Option<A>> into an Option<Array<A>>, it needs an Applicative for Option.

Signature

export declare const sequence: Sequence1<'Array'>

Example

import { sequence } from 'fp-ts/Array'
import { Applicative, left, right } from 'fp-ts/Either'

assert.deepStrictEqual(sequence(Applicative)([right('a'), right('b')]), right(['a', 'b']))
assert.deepStrictEqual(
  sequence(Applicative)([right('a'), left(new Error('not a string'))]),
  left(new Error('not a string'))
)

Added in v2.6.3

traverse

Given an iterating function that returns a HKT (higher kinded type), traverse applies the iterating function to each element of the Array and then sequence-s the results using the provided Applicative.

E.g. suppose you have an Array and you want to format each element with a function that returns a result or an error as f = (a: A) => Either<Error, B>, using traverse you can apply f to all elements and directly obtain as a result an Either<Error,Array<B>> i.e. an Array<B> if all the results are B, or an Error if some of the results are Errors.

Signature

export declare const traverse: PipeableTraverse1<'Array'>

Example

import { traverse } from 'fp-ts/Array'
import { Applicative, left, right } from 'fp-ts/Either'

const f = (x: unknown) => (typeof x === 'string' ? right(x.toUpperCase()) : left(new Error('not a string')))
assert.deepStrictEqual(traverse(Applicative)(f)(['a', 'b']), right(['A', 'B']))
assert.deepStrictEqual(traverse(Applicative)(f)(['a', 5]), left(new Error('not a string')))

Added in v2.6.3

type lambdas

URI

Signature

export declare const URI: 'Array'

Added in v2.0.0

URI (type alias)

Signature

export type URI = typeof URI

Added in v2.0.0

unsafe

unsafeDeleteAt

Signature

export declare const unsafeDeleteAt: <A>(i: number, as: A[]) => A[]

Added in v2.0.0

unsafeInsertAt

Signature

export declare const unsafeInsertAt: <A>(i: number, a: A, as: A[]) => NEA.NonEmptyArray<A>

Added in v2.0.0

unsafeUpdateAt

Signature

export declare const unsafeUpdateAt: <A>(i: number, a: A, as: A[]) => A[]

Added in v2.0.0

utils

Spanned (interface)

Type returned by spanLeft composed of an init array and a rest array.

Signature

export interface Spanned<I, R> {
  init: Array<I>
  rest: Array<R>
}

Added in v2.10.0

ap

Signature

export declare const ap: <A>(fa: A[]) => <B>(fab: ((a: A) => B)[]) => B[]

Example

import { ap, map, of } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

// a curried function with 3 input parameteres
const f = (s1: string) => (n: number) => (s2: string) => s1 + n + s2

// let's use `ap` to iterate `f` over an array for each input parameter
assert.deepStrictEqual(pipe(['a', 'b'], map(f), ap([1, 2]), ap(['😀', '😫', '😎'])), [
  'a1😀',
  'a1😫',
  'a1😎',
  'a2😀',
  'a2😫',
  'a2😎',
  'b1😀',
  'b1😫',
  'b1😎',
  'b2😀',
  'b2😫',
  'b2😎',
])

// given Array implements the Applicative interface with the `of` method,
// we can write exactly the same thing in a more symmetric way
// using `of` on `f` and `ap` on each array in input
assert.deepStrictEqual(
  pipe(of(f), ap(['a', 'b']), ap([1, 2]), ap(['😀', '😫', '😎'])),
  pipe(['a', 'b'], map(f), ap([1, 2]), ap(['😀', '😫', '😎']))
)

Added in v2.0.0

apFirst

Combine two effectful actions, keeping only the result of the first.

Signature

export declare const apFirst: <B>(second: B[]) => <A>(first: A[]) => A[]

Added in v2.5.0

apSecond

Combine two effectful actions, keeping only the result of the second.

Signature

export declare const apSecond: <B>(second: B[]) => <A>(first: A[]) => B[]

Added in v2.5.0

append

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

Signature

export declare const append: <A>(end: A) => (init: A[]) => NEA.NonEmptyArray<A>

Example

import { append } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

assert.deepStrictEqual(pipe([1, 2, 3], append(4)), [1, 2, 3, 4])

Added in v2.10.0

appendW

Less strict version of append.

Signature

export declare const appendW: <A, B>(end: B) => (init: A[]) => NEA.NonEmptyArray<A | B>

Example

import { appendW } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

assert.deepStrictEqual(pipe([1, 2, 3], appendW('d')), [1, 2, 3, 'd'])

Added in v2.11.0

chop

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

Signature

export declare const chop: <A, B>(f: (as: NEA.NonEmptyArray<A>) => [B, A[]]) => (as: A[]) => B[]

Example

import { Eq } from 'fp-ts/Eq'
import * as A from 'fp-ts/Array'
import * as N from 'fp-ts/number'
import { pipe } from 'fp-ts/function'

const group = <A>(S: Eq<A>): ((as: Array<A>) => Array<Array<A>>) => {
  return A.chop((as) => {
    const { init, rest } = pipe(
      as,
      A.spanLeft((a: A) => S.equals(a, as[0]))
    )
    return [init, rest]
  })
}
assert.deepStrictEqual(group(N.Eq)([1, 1, 2, 3, 3, 4]), [[1, 1], [2], [3, 3], [4]])

Added in v2.0.0

chunksOf

Splits an array into length-n pieces. The last piece will be shorter if n does not evenly divide the length of the array. 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 xs.

Signature

export declare const chunksOf: (n: number) => <A>(as: A[]) => NEA.NonEmptyArray<A>[]

Example

import { chunksOf } from 'fp-ts/Array'

assert.deepStrictEqual(chunksOf(2)([1, 2, 3, 4, 5]), [[1, 2], [3, 4], [5]])

Added in v2.0.0

comprehension

Array comprehension.

[ f(x, y, ...) | x ← xs, y ← ys, ..., g(x, y, ...) ]

Signature

export declare function comprehension<A, B, C, D, R>(
  input: [Array<A>, Array<B>, Array<C>, Array<D>],
  f: (a: A, b: B, c: C, d: D) => R,
  g?: (a: A, b: B, c: C, d: D) => boolean
): Array<R>
export declare function comprehension<A, B, C, R>(
  input: [Array<A>, Array<B>, Array<C>],
  f: (a: A, b: B, c: C) => R,
  g?: (a: A, b: B, c: C) => boolean
): Array<R>
export declare function comprehension<A, B, R>(
  input: [Array<A>, Array<B>],
  f: (a: A, b: B) => R,
  g?: (a: A, b: B) => boolean
): Array<R>
export declare function comprehension<A, R>(input: [Array<A>], f: (a: A) => R, g?: (a: A) => boolean): Array<R>

Example

import { comprehension } from 'fp-ts/Array'
import { tuple } from 'fp-ts/function'

assert.deepStrictEqual(
  comprehension(
    [
      [1, 2, 3],
      ['a', 'b'],
    ],
    tuple,
    (a, b) => (a + b.length) % 2 === 0
  ),
  [
    [1, 'a'],
    [1, 'b'],
    [3, 'a'],
    [3, 'b'],
  ]
)

Added in v2.0.0

concat

Signature

export declare const concat: <A>(second: A[]) => (first: A[]) => A[]

Added in v2.11.0

concatW

Signature

export declare const concatW: <B>(second: B[]) => <A>(first: A[]) => (B | A)[]

Added in v2.11.0

copy

This function takes an array and makes a new array containing the same elements.

Signature

export declare const copy: <A>(as: A[]) => A[]

Added in v2.0.0

deleteAt

Delete the element at the specified index, creating a new array, or returning None if the index is out of bounds.

Signature

export declare const deleteAt: (i: number) => <A>(as: A[]) => Option<A[]>

Example

import { deleteAt } from 'fp-ts/Array'
import { some, none } from 'fp-ts/Option'

assert.deepStrictEqual(deleteAt(0)([1, 2, 3]), some([2, 3]))
assert.deepStrictEqual(deleteAt(1)([]), none)

Added in v2.0.0

difference

Creates an array of array values not included in the other given array using a Eq for equality comparisons. The order and references of result values are determined by the first array.

Signature

export declare function difference<A>(E: Eq<A>): {
  (xs: Array<A>): (ys: Array<A>) => Array<A>
  (xs: Array<A>, ys: Array<A>): Array<A>
}

Example

import { difference } from 'fp-ts/Array'
import * as N from 'fp-ts/number'
import { pipe } from 'fp-ts/function'

assert.deepStrictEqual(pipe([1, 2], difference(N.Eq)([2, 3])), [1])

Added in v2.0.0

dropLeft

Creates a new Array which is a copy of the input dropping a max number of elements from the start.

Note. n is normalized to a non negative integer.

Signature

export declare const dropLeft: (n: number) => <A>(as: A[]) => A[]

Example

import { dropLeft } from 'fp-ts/Array'

assert.deepStrictEqual(dropLeft(2)([1, 2, 3]), [3])
assert.deepStrictEqual(dropLeft(5)([1, 2, 3]), [])
assert.deepStrictEqual(dropLeft(0)([1, 2, 3]), [1, 2, 3])
assert.deepStrictEqual(dropLeft(-2)([1, 2, 3]), [1, 2, 3])

Added in v2.0.0

dropLeftWhile

Creates a new Array which is a copy of the input dropping the longest initial subarray for which all element satisfy the specified predicate.

Signature

export declare function dropLeftWhile<A, B extends A>(refinement: Refinement<A, B>): (as: Array<A>) => Array<B>
export declare function dropLeftWhile<A>(predicate: Predicate<A>): <B extends A>(bs: Array<B>) => Array<B>
export declare function dropLeftWhile<A>(predicate: Predicate<A>): (as: Array<A>) => Array<A>

Example

import { dropLeftWhile } from 'fp-ts/Array'

assert.deepStrictEqual(dropLeftWhile((n: number) => n % 2 === 1)([1, 3, 2, 4, 5]), [2, 4, 5])

Added in v2.0.0

dropRight

Creates a new Array which is a copy of the input dropping a max number of elements from the end.

Note. n is normalized to a non negative integer.

Signature

export declare const dropRight: (n: number) => <A>(as: A[]) => A[]

Example

import { dropRight } from 'fp-ts/Array'

assert.deepStrictEqual(dropRight(2)([1, 2, 3]), [1])
assert.deepStrictEqual(dropRight(5)([1, 2, 3]), [])
assert.deepStrictEqual(dropRight(0)([1, 2, 3]), [1, 2, 3])
assert.deepStrictEqual(dropRight(-2)([1, 2, 3]), [1, 2, 3])

Added in v2.0.0

duplicate

duplicate returns an array containing the whole input Array, then to the input Array dropping the first element, then to the input Array dropping the first two elements, etc.

Signature

export declare const duplicate: <A>(wa: A[]) => A[][]

Example

import { duplicate } from 'fp-ts/Array'

assert.deepStrictEqual(duplicate(['a', 'b', 'c']), [['a', 'b', 'c'], ['b', 'c'], ['c']])

Added in v2.0.0

elem

Test if a value is a member of an Array. Takes a Eq<A> as a single argument which returns the function to use to search for a value of type A in an Array<A>.

Signature

export declare const elem: <A>(E: Eq<A>) => { (a: A): (as: A[]) => boolean; (a: A, as: A[]): boolean }

Example

import { elem } from 'fp-ts/Array'
import * as N from 'fp-ts/number'
import { pipe } from 'fp-ts/function'

assert.strictEqual(pipe([1, 2, 3], elem(N.Eq)(2)), true)
assert.strictEqual(pipe([1, 2, 3], elem(N.Eq)(0)), false)

Added in v2.0.0

every

every tells if the provided predicate holds true for every element in the Array.

Signature

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

Example

import { every } from 'fp-ts/Array'

assert.equal(every((x: number) => x >= 0)([1, 2, 3]), true)
assert.equal(every((x: number) => x >= 0)([-1, 2, 3]), false)

Added in v2.9.0

exists

Alias of some

Signature

export declare const exists: <A>(predicate: Predicate<A>) => (as: A[]) => as is NEA.NonEmptyArray<A>

Added in v2.11.0

extend

Given an iterating function that takes Array<A> as input, extend returns an array containing the results of the iterating function applied to the whole input Array, then to the input Array without the first element, then to the input Array without the first two elements, etc.

Signature

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

Example

import { extend } from 'fp-ts/Array'

const f = (a: string[]) => a.join(',')
assert.deepStrictEqual(extend(f)(['a', 'b', 'c']), ['a,b,c', 'b,c', 'c'])

Added in v2.0.0

filterE

Filter values inside a context.

Signature

export declare const filterE: FilterE1<'Array'>

Added in v2.11.0

findFirst

Find the first element which satisfies a predicate (or a refinement) function. It returns an Option containing the element or None if not found.

Signature

export declare function findFirst<A, B extends A>(refinement: Refinement<A, B>): (as: Array<A>) => Option<B>
export declare function findFirst<A>(predicate: Predicate<A>): <B extends A>(bs: Array<B>) => Option<B>
export declare function findFirst<A>(predicate: Predicate<A>): (as: Array<A>) => Option<A>

Example

import { findFirst } from 'fp-ts/Array'
import { some } from 'fp-ts/Option'

type X = {
  readonly a: number
  readonly b: number
}

assert.deepStrictEqual(
  findFirst((x: X) => x.a === 1)([
    { a: 1, b: 1 },
    { a: 1, b: 2 },
  ]),
  some({ a: 1, b: 1 })
)

Added in v2.0.0

findFirstMap

Given a selector function which takes an element and returns an option, this function applies the selector to each element of the array and returns the first Some result. Otherwise it returns None.

Signature

export declare const findFirstMap: <A, B>(f: (a: A) => Option<B>) => (as: A[]) => Option<B>

Example

import { findFirstMap } from 'fp-ts/Array'
import { some, none } from 'fp-ts/Option'

interface Person {
  readonly name: string
  readonly age: number
}

const persons: Array<Person> = [
  { name: 'John', age: 16 },
  { name: 'Mary', age: 45 },
  { name: 'Joey', age: 28 },
]

const nameOfPersonAbove18 = (p: Person) => (p.age <= 18 ? none : some(p.name))
const nameOfPersonAbove70 = (p: Person) => (p.age <= 70 ? none : some(p.name))
assert.deepStrictEqual(findFirstMap(nameOfPersonAbove18)(persons), some('Mary'))
assert.deepStrictEqual(findFirstMap(nameOfPersonAbove70)(persons), none)

Added in v2.0.0

findIndex

findIndex returns an Option containing the first index for which a predicate holds. It returns None if no element satisfies the predicate. Similar to findFirst but returning the index instead of the element.

Signature

export declare const findIndex: <A>(predicate: Predicate<A>) => (as: A[]) => Option<number>

Example

import { findIndex } from 'fp-ts/Array'
import { some, none } from 'fp-ts/Option'

assert.deepStrictEqual(findIndex((n: number) => n === 2)([1, 2, 3]), some(1))
assert.deepStrictEqual(findIndex((n: number) => n === 2)([]), none)

Added in v2.0.0

findLast

Find the last element which satisfies a predicate function. It returns an Option containing the element or None if not found.

Signature

export declare function findLast<A, B extends A>(refinement: Refinement<A, B>): (as: Array<A>) => Option<B>
export declare function findLast<A>(predicate: Predicate<A>): <B extends A>(bs: Array<B>) => Option<B>
export declare function findLast<A>(predicate: Predicate<A>): (as: Array<A>) => Option<A>

Example

import { findLast } from 'fp-ts/Array'
import { some } from 'fp-ts/Option'

type X = {
  readonly a: number
  readonly b: number
}

assert.deepStrictEqual(
  findLast((x: X) => x.a === 1)([
    { a: 1, b: 1 },
    { a: 1, b: 2 },
  ]),
  some({ a: 1, b: 2 })
)

Added in v2.0.0

findLastIndex

Returns the index of the last element of the list which matches the predicate. It returns an Option containing the index or None if not found.

Signature

export declare const findLastIndex: <A>(predicate: Predicate<A>) => (as: A[]) => Option<number>

Example

import { findLastIndex } from 'fp-ts/Array'
import { some, none } from 'fp-ts/Option'

interface X {
  readonly a: number
  readonly b: number
}
const xs: Array<X> = [
  { a: 1, b: 0 },
  { a: 1, b: 1 },
]
assert.deepStrictEqual(findLastIndex((x: { readonly a: number }) => x.a === 1)(xs), some(1))
assert.deepStrictEqual(findLastIndex((x: { readonly a: number }) => x.a === 4)(xs), none)

Added in v2.0.0

findLastMap

Given a selector function which takes an element and returns an option, this function applies the selector to each element of the array starting from the end and returns the last Some result. Otherwise it returns None.

Signature

export declare const findLastMap: <A, B>(f: (a: A) => Option<B>) => (as: A[]) => Option<B>

Example

import { findLastMap } from 'fp-ts/Array'
import { some, none } from 'fp-ts/Option'

interface Person {
  readonly name: string
  readonly age: number
}

const persons: Array<Person> = [
  { name: 'John', age: 16 },
  { name: 'Mary', age: 45 },
  { name: 'Joey', age: 28 },
]

const nameOfPersonAbove18 = (p: Person) => (p.age <= 18 ? none : some(p.name))
const nameOfPersonAbove70 = (p: Person) => (p.age <= 70 ? none : some(p.name))
assert.deepStrictEqual(findLastMap(nameOfPersonAbove18)(persons), some('Joey'))
assert.deepStrictEqual(findLastMap(nameOfPersonAbove70)(persons), none)

Added in v2.0.0

Get the first element in an array, or None if the array is empty

Signature

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

Example

import { head } from 'fp-ts/Array'
import { some, none } from 'fp-ts/Option'

assert.deepStrictEqual(head([1, 2, 3]), some(1))
assert.deepStrictEqual(head([]), none)

Added in v2.0.0

init

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

Signature

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

Example

import { init } from 'fp-ts/Array'
import { some, none } from 'fp-ts/Option'

assert.deepStrictEqual(init([1, 2, 3]), some([1, 2]))
assert.deepStrictEqual(init([]), none)

Added in v2.0.0

insertAt

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

Signature

export declare const insertAt: <A>(i: number, a: A) => (as: A[]) => Option<NEA.NonEmptyArray<A>>

Example

import { insertAt } from 'fp-ts/Array'
import { some } from 'fp-ts/Option'

assert.deepStrictEqual(insertAt(2, 5)([1, 2, 3, 4]), some([1, 2, 5, 3, 4]))

Added in v2.0.0

intercalate

Places an element in between members of an Array, then folds the results using the provided Monoid.

Signature

export declare const intercalate: <A>(M: Monoid<A>) => (middle: A) => (as: A[]) => A

Example

import * as S from 'fp-ts/string'
import { intercalate } from 'fp-ts/Array'

assert.deepStrictEqual(intercalate(S.Monoid)('-')(['a', 'b', 'c']), 'a-b-c')

Added in v2.12.0

intersection

Creates an array of unique values that are included in all given arrays using a Eq for equality comparisons. The order and references of result values are determined by the first array.

Signature

export declare function intersection<A>(E: Eq<A>): {
  (xs: Array<A>): (ys: Array<A>) => Array<A>
  (xs: Array<A>, ys: Array<A>): Array<A>
}

Example

import { intersection } from 'fp-ts/Array'
import * as N from 'fp-ts/number'
import { pipe } from 'fp-ts/function'

assert.deepStrictEqual(pipe([1, 2], intersection(N.Eq)([2, 3])), [2])

Added in v2.0.0

intersperse

Creates a new Array placing an element in between members of the input Array.

Signature

export declare const intersperse: <A>(middle: A) => (as: A[]) => A[]

Example

import { intersperse } from 'fp-ts/Array'

assert.deepStrictEqual(intersperse(9)([1, 2, 3, 4]), [1, 9, 2, 9, 3, 9, 4])

Added in v2.9.0

isOutOfBound

Test whether an array contains a particular index

Signature

export declare const isOutOfBound: <A>(i: number, as: A[]) => boolean

Example

import { isOutOfBound } from 'fp-ts/Array'

assert.strictEqual(isOutOfBound(1, ['a', 'b', 'c']), false)
assert.strictEqual(isOutOfBound(-1, ['a', 'b', 'c']), true)
assert.strictEqual(isOutOfBound(3, ['a', 'b', 'c']), true)

Added in v2.0.0

last

Get the last element in an array, or None if the array is empty

Signature

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

Example

import { last } from 'fp-ts/Array'
import { some, none } from 'fp-ts/Option'

assert.deepStrictEqual(last([1, 2, 3]), some(3))
assert.deepStrictEqual(last([]), none)

Added in v2.0.0

lefts

Takes an Array of Either and produces a new Array containing the values of all the Left elements in the same order.

Signature

export declare const lefts: <E, A>(as: Either<E, A>[]) => E[]

Example

import { lefts } from 'fp-ts/Array'
import { left, right } from 'fp-ts/Either'

assert.deepStrictEqual(lefts([right(1), left('foo'), right(2)]), ['foo'])

Added in v2.0.0

lookup

This function provides a safe way to read a value at a particular index from an array. It returns a none if the index is out of bounds, and a some of the element if the index is valid.

Signature

export declare const lookup: { (i: number): <A>(as: A[]) => Option<A>; <A>(i: number, as: A[]): Option<A> }

Example

import { lookup } from 'fp-ts/Array'
import { some, none } from 'fp-ts/Option'
import { pipe } from 'fp-ts/function'

assert.deepStrictEqual(pipe([1, 2, 3], lookup(1)), some(2))
assert.deepStrictEqual(pipe([1, 2, 3], lookup(3)), none)

Added in v2.0.0

modifyAt

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

Signature

export declare const modifyAt: <A>(i: number, f: (a: A) => A) => (as: A[]) => Option<A[]>

Example

import { modifyAt } from 'fp-ts/Array'
import { some, none } from 'fp-ts/Option'

const double = (x: number): number => x * 2
assert.deepStrictEqual(modifyAt(1, double)([1, 2, 3]), some([1, 4, 3]))
assert.deepStrictEqual(modifyAt(1, double)([]), none)

Added in v2.0.0

prepend

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

Signature

export declare const prepend: <A>(head: A) => (tail: A[]) => NEA.NonEmptyArray<A>

Example

import { prepend } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

assert.deepStrictEqual(pipe([2, 3, 4], prepend(1)), [1, 2, 3, 4])

Added in v2.10.0

prependAll

Creates a new Array, prepending an element to every member of the input Array.

Signature

export declare const prependAll: <A>(middle: A) => (as: A[]) => A[]

Example

import { prependAll } from 'fp-ts/Array'

assert.deepStrictEqual(prependAll(9)([1, 2, 3, 4]), [9, 1, 9, 2, 9, 3, 9, 4])

Added in v2.10.0

prependW

Less strict version of prepend.

Signature

export declare const prependW: <A, B>(head: B) => (tail: A[]) => NEA.NonEmptyArray<A | B>

Example

import { prependW } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

assert.deepStrictEqual(pipe([2, 3, 4], prependW('a')), ['a', 2, 3, 4])

Added in v2.11.0

reverse

Reverse an array, creating a new array

Signature

export declare const reverse: <A>(as: A[]) => A[]

Example

import { reverse } from 'fp-ts/Array'

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

Added in v2.0.0

rights

Takes an Array of Either and produces a new Array containing the values of all the Right elements in the same order.

Signature

export declare const rights: <E, A>(as: Either<E, A>[]) => A[]

Example

import { rights } from 'fp-ts/Array'
import { right, left } from 'fp-ts/Either'

assert.deepStrictEqual(rights([right(1), left('foo'), right(2)]), [1, 2])

Added in v2.0.0

rotate

Creates a new Array rotating the input Array by n steps.

Signature

export declare const rotate: (n: number) => <A>(as: A[]) => A[]

Example

import { rotate } from 'fp-ts/Array'

assert.deepStrictEqual(rotate(2)([1, 2, 3, 4, 5]), [4, 5, 1, 2, 3])

Added in v2.0.0

scanLeft

Same as reduce but it carries over the intermediate steps

Signature

export declare const scanLeft: <A, B>(b: B, f: (b: B, a: A) => B) => (as: A[]) => NEA.NonEmptyArray<B>

Example

import { scanLeft } from 'fp-ts/Array'

assert.deepStrictEqual(scanLeft(10, (b, a: number) => b - a)([1, 2, 3]), [10, 9, 7, 4])

Added in v2.0.0

scanRight

Fold an array from the right, keeping all intermediate results instead of only the final result

Signature

export declare const scanRight: <A, B>(b: B, f: (a: A, b: B) => B) => (as: A[]) => NEA.NonEmptyArray<B>

Example

import { scanRight } from 'fp-ts/Array'

assert.deepStrictEqual(scanRight(10, (a: number, b) => b - a)([1, 2, 3]), [4, 5, 7, 10])

Added in v2.0.0

size

Calculate the number of elements in a Array.

Signature

export declare const size: <A>(as: A[]) => number

Example

import { size } from 'fp-ts/Array'

assert.strictEqual(size(['a', 'b', 'c']), 3)

Added in v2.10.0

some

some tells if the provided predicate holds true at least for one element in the Array.

Signature

export declare const some: <A>(predicate: Predicate<A>) => (as: A[]) => as is NEA.NonEmptyArray<A>

Example

import { some } from 'fp-ts/Array'

assert.equal(some((x: number) => x >= 0)([1, 2, 3]), true)
assert.equal(some((x: number) => x >= 10)([1, 2, 3]), false)

Added in v2.9.0

sort

Sort the elements of an array in increasing order, creating a new array

Signature

export declare const sort: <B>(O: Ord<B>) => <A extends B>(as: A[]) => A[]

Example

import { sort } from 'fp-ts/Array'
import * as N from 'fp-ts/number'

assert.deepStrictEqual(sort(N.Ord)([3, 2, 1]), [1, 2, 3])

Added in v2.0.0

sortBy

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

Signature

export declare const sortBy: <B>(ords: Ord<B>[]) => <A extends B>(as: A[]) => A[]

Example

import { sortBy } from 'fp-ts/Array'
import { contramap } from 'fp-ts/Ord'
import * as S from 'fp-ts/string'
import * as N from 'fp-ts/number'
import { pipe } from 'fp-ts/function'

interface Person {
  readonly name: string
  readonly age: number
}
const byName = pipe(
  S.Ord,
  contramap((p: Person) => p.name)
)
const byAge = pipe(
  N.Ord,
  contramap((p: Person) => p.age)
)

const sortByNameByAge = sortBy([byName, byAge])

const persons = [
  { name: 'a', age: 1 },
  { name: 'b', age: 3 },
  { name: 'c', age: 2 },
  { name: 'b', age: 2 },
]
assert.deepStrictEqual(sortByNameByAge(persons), [
  { name: 'a', age: 1 },
  { name: 'b', age: 2 },
  { name: 'b', age: 3 },
  { name: 'c', age: 2 },
])

Added in v2.0.0

spanLeft

Split an array into two parts:

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

Signature

export declare function spanLeft<A, B extends A>(refinement: Refinement<A, B>): (as: Array<A>) => Spanned<B, A>
export declare function spanLeft<A>(predicate: Predicate<A>): <B extends A>(bs: Array<B>) => Spanned<B, B>
export declare function spanLeft<A>(predicate: Predicate<A>): (as: Array<A>) => Spanned<A, A>

Example

import { spanLeft } from 'fp-ts/Array'

const isOdd = (n: number) => n % 2 === 1
assert.deepStrictEqual(spanLeft(isOdd)([1, 3, 2, 4, 5]), { init: [1, 3], rest: [2, 4, 5] })
assert.deepStrictEqual(spanLeft(isOdd)([0, 2, 4, 5]), { init: [], rest: [0, 2, 4, 5] })
assert.deepStrictEqual(spanLeft(isOdd)([1, 3, 5]), { init: [1, 3, 5], rest: [] })

Added in v2.0.0

splitAt

Splits an Array into two pieces, the first piece has max n elements.

Signature

export declare const splitAt: (n: number) => <A>(as: A[]) => [A[], A[]]

Example

import { splitAt } from 'fp-ts/Array'

assert.deepStrictEqual(splitAt(2)([1, 2, 3, 4, 5]), [
  [1, 2],
  [3, 4, 5],
])

Added in v2.0.0

tail

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

Signature

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

Example

import { tail } from 'fp-ts/Array'
import { some, none } from 'fp-ts/Option'

assert.deepStrictEqual(tail([1, 2, 3]), some([2, 3]))
assert.deepStrictEqual(tail([]), none)

Added in v2.0.0

takeLeft

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

Note. n is normalized to a non negative integer.

Signature

export declare const takeLeft: (n: number) => <A>(as: A[]) => A[]

Example

import { takeLeft } from 'fp-ts/Array'

assert.deepStrictEqual(takeLeft(2)([1, 2, 3, 4, 5]), [1, 2])
assert.deepStrictEqual(takeLeft(7)([1, 2, 3, 4, 5]), [1, 2, 3, 4, 5])
assert.deepStrictEqual(takeLeft(0)([1, 2, 3, 4, 5]), [])
assert.deepStrictEqual(takeLeft(-1)([1, 2, 3, 4, 5]), [1, 2, 3, 4, 5])

Added in v2.0.0

takeLeftWhile

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

Signature

export declare function takeLeftWhile<A, B extends A>(refinement: Refinement<A, B>): (as: Array<A>) => Array<B>
export declare function takeLeftWhile<A>(predicate: Predicate<A>): <B extends A>(bs: Array<B>) => Array<B>
export declare function takeLeftWhile<A>(predicate: Predicate<A>): (as: Array<A>) => Array<A>

Example

import { takeLeftWhile } from 'fp-ts/Array'

assert.deepStrictEqual(takeLeftWhile((n: number) => n % 2 === 0)([2, 4, 3, 6]), [2, 4])

Added in v2.0.0

takeRight

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

Note. n is normalized to a non negative integer.

Signature

export declare const takeRight: (n: number) => <A>(as: A[]) => A[]

Example

import { takeRight } from 'fp-ts/Array'

assert.deepStrictEqual(takeRight(2)([1, 2, 3, 4, 5]), [4, 5])
assert.deepStrictEqual(takeRight(7)([1, 2, 3, 4, 5]), [1, 2, 3, 4, 5])
assert.deepStrictEqual(takeRight(0)([1, 2, 3, 4, 5]), [])
assert.deepStrictEqual(takeRight(-1)([1, 2, 3, 4, 5]), [1, 2, 3, 4, 5])

Added in v2.0.0

unfold

unfold takes a function f which returns an Option of a tuple containing an outcome value and an input for the following iteration. unfold applies f to the initial value b and then recursively to the second element of the tuple contained in the returned option of the previous calculation until f returns Option.none.

Signature

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

Example

import { unfold } from 'fp-ts/Array'
import { option } from 'fp-ts'

const f = (n: number) => {
  if (n <= 0) return option.none
  const returnValue = n * 2
  const inputForNextRound = n - 1
  return option.some([returnValue, inputForNextRound] as const)
}
assert.deepStrictEqual(unfold(5, f), [10, 8, 6, 4, 2])

Added in v2.6.6

union

Creates an array of unique values, in order, from all given arrays using a Eq for equality comparisons

Signature

export declare function union<A>(E: Eq<A>): {
  (xs: Array<A>): (ys: Array<A>) => Array<A>
  (xs: Array<A>, ys: Array<A>): Array<A>
}

Example

import { union } from 'fp-ts/Array'
import * as N from 'fp-ts/number'
import { pipe } from 'fp-ts/function'

assert.deepStrictEqual(pipe([1, 2], union(N.Eq)([2, 3])), [1, 2, 3])

Added in v2.0.0

uniq

Creates a new Array removing duplicate elements, keeping the first occurrence of an element, based on a Eq<A>.

Signature

export declare const uniq: <A>(E: Eq<A>) => (as: A[]) => A[]

Example

import { uniq } from 'fp-ts/Array'
import * as N from 'fp-ts/number'

assert.deepStrictEqual(uniq(N.Eq)([1, 2, 1]), [1, 2])

Added in v2.0.0

unzip

The function is reverse of zip. Takes an array of pairs and return two corresponding arrays

Signature

export declare const unzip: <A, B>(as: [A, B][]) => [A[], B[]]

Example

import { unzip } from 'fp-ts/Array'

assert.deepStrictEqual(
  unzip([
    [1, 'a'],
    [2, 'b'],
    [3, 'c'],
  ]),
  [
    [1, 2, 3],
    ['a', 'b', 'c'],
  ]
)

Added in v2.0.0

updateAt

Change the element at the specified index, creating a new array, or returning None if the index is out of bounds.

Signature

export declare const updateAt: <A>(i: number, a: A) => (as: A[]) => Option<A[]>

Example

import { updateAt } from 'fp-ts/Array'
import { some, none } from 'fp-ts/Option'

assert.deepStrictEqual(updateAt(1, 1)([1, 2, 3]), some([1, 1, 3]))
assert.deepStrictEqual(updateAt(1, 1)([]), none)

Added in v2.0.0

zero

Makes an empty Array, useful for building a Monoid

Signature

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

Added in v2.7.0

zip

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

Signature

export declare function zip<B>(bs: Array<B>): <A>(as: Array<A>) => Array<[A, B]>
export declare function zip<A, B>(as: Array<A>, bs: Array<B>): Array<[A, B]>

Example

import { zip } from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'

assert.deepStrictEqual(pipe([1, 2, 3], zip(['a', 'b', 'c', 'd'])), [
  [1, 'a'],
  [2, 'b'],
  [3, 'c'],
])

Added in v2.0.0

zipWith

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

Signature

export declare const zipWith: <A, B, C>(fa: A[], fb: B[], f: (a: A, b: B) => C) => C[]

Example

import { zipWith } from 'fp-ts/Array'

assert.deepStrictEqual(
  zipWith([1, 2, 3], ['a', 'b', 'c', 'd'], (n, s) => s + n),
  ['a1', 'b2', 'c3']
)

Added in v2.0.0

zone of death

array

This instance is deprecated, use small, specific instances instead. For example if a function needs a Functor instance, pass A.Functor instead of A.array (where A is from import A from 'fp-ts/Array')

Signature

export declare const array: FunctorWithIndex1<'Array', number> &
  Monad1<'Array'> &
  Unfoldable1<'Array'> &
  Alternative1<'Array'> &
  Extend1<'Array'> &
  FilterableWithIndex1<'Array', number> &
  FoldableWithIndex1<'Array', number> &
  TraversableWithIndex1<'Array', number> &
  Witherable1<'Array'>

Added in v2.0.0

cons

Use prepend instead.

Signature

export declare const cons: typeof NEA.cons

Added in v2.0.0

empty

Use a new [] instead.

Signature

export declare const empty: never[]

Added in v2.0.0

prependToAll

Use prependAll instead

Signature

export declare const prependToAll: <A>(middle: A) => (as: A[]) => A[]

Added in v2.9.0

range

Use NonEmptyArray module instead.

Signature

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

Added in v2.0.0

snoc

Use append instead.

Signature

export declare const snoc: <A>(init: A[], end: A) => NEA.NonEmptyArray<A>

Added in v2.0.0