List

A data type for immutable linked lists representing ordered collections of elements of type A.

This data type is optimal for last-in-first-out (LIFO), stack-like access patterns. If you need another access pattern, for example, random access or FIFO, consider using a collection more suited to this than List.

Performance

Time: List has O(1) prepend and head/tail access. Most other operations are O(n) on the number of elements in the list. This includes the index-based lookup of elements, length, append and reverse.
Space: List implements structural sharing of the tail list. This means that many operations are either zero- or constant-memory cost.

47 exports Since v2.0.0 Source

Combinators

compact

Since v2.0.0

Removes all None values from the specified list.

Signature

declare function compact<A>(self: List<Option<A>>): List<A>

drop

Since v2.0.0

Drops the first n elements from the specified list.

Signature

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

filter

Since v2.0.0

Filters a list using the specified predicate.

Signature

declare const filter: {
  <A, B>(refinement: Refinement<NoInfer<A>, B>): (self: List<A>) => List<B>;
  <A>(predicate: Predicate<NoInfer<A>>): (self: List<A>) => List<A>;
  <A, B>(self: List<A>, refinement: Refinement<A, B>): List<B>;
  <A>(self: List<A>, predicate: Predicate<A>): List<A>;
}

filterMap

Since v2.0.0

Filters and maps a list using the specified partial function. The resulting list may be smaller than the input list due to the possibility of the partial function not being defined for some elements.

Signature

declare const filterMap: {
  <A, B>(f: (a: A) => Option<B>): (self: List<A>) => List<B>;
  <A, B>(self: List<A>, f: (a: A) => Option<B>): List<B>;
}

forEach

Since v2.0.0

Applies the specified function to each element of the List.

Signature

declare const forEach: {
  <A, B>(f: (a: A) => B): (self: List<A>) => void;
  <A, B>(self: List<A>, f: (a: A) => B): void;
}

partition

Since v2.0.0

Partition a list into two lists, where the first list contains all elements that did not satisfy the specified predicate, and the second list contains all elements that did satisfy the specified predicate.

Signature

declare const partition: {
  <A, B>(refinement: Refinement<NoInfer<A>, B>): (self: List<A>) => [excluded: List<Exclude<A, B>>, satisfying: List<B>];
  <A>(predicate: Predicate<NoInfer<A>>): (self: List<A>) => [excluded: List<A>, satisfying: List<A>];
  <A, B>(self: List<A>, refinement: Refinement<A, B>): [excluded: List<Exclude<A, B>>, satisfying: List<B>];
  <A>(self: List<A>, predicate: Predicate<A>): [excluded: List<A>, satisfying: List<A>];
}

partitionMap

Since v2.0.0

Partition a list into two lists, where the first list contains all elements for which the specified function returned a Left, and the second list contains all elements for which the specified function returned a Right.

Signature

declare const partitionMap: {
  <A, B, C>(f: (a: A) => Either<C, B>): (self: List<A>) => [left: List<B>, right: List<C>];
  <A, B, C>(self: List<A>, f: (a: A) => Either<C, B>): [left: List<B>, right: List<C>];
}

splitAt

Since v2.0.0

Splits the specified list into two lists at the specified index.

Signature

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

take

Since v2.0.0

Takes the specified number of elements from the beginning of the specified list.

Signature

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

Concatenating

append

Since v2.0.0

Appends the specified element to the end of the List, creating a new Cons.

Signature

declare const append: {
  <B>(element: B): <A>(self: List<A>) => Cons<B | A>;
  <A, B>(self: List<A>, element: B): Cons<A | B>;
}

appendAll

Since v2.0.0

Concatenates two lists, combining their elements. If either list is non-empty, the result is also a non-empty list.

Signature

declare const appendAll: {
  <S extends List<any>, T extends List<any>>(that: T): (self: S) => OrNonEmpty<S, T, Infer<S> | Infer<T>>;
  <A, B>(self: List<A>, that: Cons<B>): Cons<A | B>;
  <A, B>(self: Cons<A>, that: List<B>): Cons<A | B>;
  <A, B>(self: List<A>, that: List<B>): List<A | B>;
}

Example

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

assert.deepStrictEqual(
  List.make(1, 2).pipe(List.appendAll(List.make("a", "b")), List.toArray),
  [1, 2, "a", "b"]
)

prepend

Since v2.0.0

Prepends the specified element to the beginning of the list.

Signature

declare const prepend: {
  <B>(element: B): <A>(self: List<A>) => Cons<B | A>;
  <A, B>(self: List<A>, element: B): Cons<A | B>;
}

prependAll

Since v2.0.0

Prepends the specified prefix list to the beginning of the specified list. If either list is non-empty, the result is also a non-empty list.

Signature

declare const prependAll: {
  <S extends List<any>, T extends List<any>>(that: T): (self: S) => OrNonEmpty<S, T, Infer<S> | Infer<T>>;
  <A, B>(self: List<A>, that: Cons<B>): Cons<A | B>;
  <A, B>(self: Cons<A>, that: List<B>): Cons<A | B>;
  <A, B>(self: List<A>, that: List<B>): List<A | B>;
}

Example

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

assert.deepStrictEqual(
  List.make(1, 2).pipe(List.prependAll(List.make("a", "b")), List.toArray),
  ["a", "b", 1, 2]
)

prependAllReversed

Since v2.0.0

Prepends the specified prefix list (in reverse order) to the beginning of the specified list.

Signature

declare const prependAllReversed: {
  <B>(prefix: List<B>): <A>(self: List<A>) => List<B | A>;
  <A, B>(self: List<A>, prefix: List<B>): List<A | B>;
}

Constructors

cons

Since v2.0.0

Constructs a new List.Cons<A> from the specified head and tail values.

Signature

declare function cons<A>(head: A, tail: List<A>): Cons<A>

empty

Since v2.0.0

Constructs a new empty List<A>.

Alias of nil.

Signature

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

fromIterable

Since v2.0.0

Creates a new List from an iterable collection of values.

Signature

declare function fromIterable<A>(prefix: Iterable<A>): List<A>

make

Since v2.0.0

Constructs a new List<A> from the specified values.

Signature

declare function make<Elements extends readonly [any, any]>(...elements: Elements): Cons<Elements[number]>

nil

Since v2.0.0

Constructs a new empty List<A>.

Signature

declare function nil<A = never>(): List<A>

of

Since v2.0.0

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

Signature

declare function of<A>(value: A): Cons<A>

Conversions

toArray

Since v2.0.0

Converts the specified List to an Array.

Signature

declare function toArray<A>(self: List<A>): Array<A>

toChunk

Since v2.0.0

Converts the specified List to a Chunk.

Signature

declare function toChunk<A>(self: List<A>): Chunk<A>

Elements

every

Since v2.0.0

Check if a predicate holds true for every List element.

Signature

declare const every: {
  <A, B>(refinement: Refinement<NoInfer<A>, B>): (self: List<A>) => self is List<B>;
  <A>(predicate: Predicate<A>): (self: List<A>) => boolean;
  <A, B>(self: List<A>, refinement: Refinement<A, B>): self is List<B>;
  <A>(self: List<A>, predicate: Predicate<A>): boolean;
}

findFirst

Since v2.0.0

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

Signature

declare const findFirst: {
  <A, B>(refinement: Refinement<NoInfer<A>, B>): (self: List<A>) => Option<B>;
  <A>(predicate: Predicate<NoInfer<A>>): (self: List<A>) => Option<A>;
  <A, B>(self: List<A>, refinement: Refinement<A, B>): Option<B>;
  <A>(self: List<A>, predicate: Predicate<A>): Option<A>;
}

reverse

Since v2.0.0

Returns a new list with the elements of the specified list in reverse order.

Signature

declare function reverse<A>(self: List<A>): List<A>

some

Since v2.0.0

Check if a predicate holds true for some List element.

Signature

declare const some: {
  <A>(predicate: Predicate<NoInfer<A>>): (self: List<A>) => self is Cons<A>;
  <A>(self: List<A>, predicate: Predicate<A>): self is Cons<A>;
}

Equivalence

getEquivalence

Since v2.0.0

Signature

declare function getEquivalence<A>(isEquivalent: Equivalence<A>): Equivalence<List<A>>

Folding

reduce

Since v2.0.0

Folds over the elements of the list using the specified function, using the specified initial value.

Signature

declare const reduce: {
  <Z, A>(zero: Z, f: (b: Z, a: A) => Z): (self: List<A>) => Z;
  <A, Z>(self: List<A>, zero: Z, f: (b: Z, a: A) => Z): Z;
}

reduceRight

Since v2.0.0

Folds over the elements of the list using the specified function, beginning with the last element of the list, using the specified initial value.

Signature

declare const reduceRight: {
  <Z, A>(zero: Z, f: (accumulator: Z, value: A) => Z): (self: List<A>) => Z;
  <Z, A>(self: List<A>, zero: Z, f: (accumulator: Z, value: A) => Z): Z;
}

Getters

head

Since v2.0.0

Returns the first element of the specified list, or None if the list is empty.

Signature

declare function head<A>(self: List<A>): Option<A>

last

Since v2.0.0

Returns the last element of the specified list, or None if the list is empty.

Signature

declare function last<A>(self: List<A>): Option<A>

size

Since v2.0.0

Returns the number of elements contained in the specified List

Signature

declare function size<A>(self: List<A>): number

tail

Since v2.0.0

Returns the tail of the specified list, or None if the list is empty.

Signature

declare function tail<A>(self: List<A>): Option<List<A>>

Mapping

map

Since v2.0.0

Applies the specified mapping function to each element of the list.

Signature

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

Models

Cons

interface

Since v2.0.0

Signature

interface Cons<out A> extends NonEmptyIterable<A>, Equal, Pipeable, Inspectable {
  readonly _tag: "Cons";
  readonly [TypeId]: typeof TypeId;
  readonly head: A;
  readonly tail: List<A>;
}

List

type

Since v2.0.0

Represents an immutable linked list of elements of type A.

A List is optimal for last-in-first-out (LIFO), stack-like access patterns. If you need another access pattern, for example, random access or FIFO, consider using a collection more suited for that other than List.

Signature

type List<A> = Cons<A> | Nil<A>

Nil

interface

Since v2.0.0

Signature

interface Nil<out A> extends Iterable<A>, Equal, Pipeable, Inspectable {
  readonly _tag: "Nil";
  readonly [TypeId]: typeof TypeId;
}

Signature

declare function isCons<A>(self: List<A>): self is Cons<A>

isList

Since v2.0.0

Returns true if the specified value is a List, false otherwise.

Signature

declare const isList: {
  <A>(u: Iterable<A>): u is List<A>;
  (u: unknown): u is List<unknown>;
}

isNil

Since v2.0.0

Returns true if the specified value is a List.Nil<A>, false otherwise.

Signature

declare function isNil<A>(self: List<A>): self is Nil<A>

Sequencing

flatMap

Since v2.0.0

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

Signature

declare const flatMap: {
  <S extends List<any>, T extends List<any>>(f: (a: Infer<S>, i: number) => T): (self: S) => AndNonEmpty<S, T, Infer<T>>;
  <A, B>(self: Cons<A>, f: (a: A, i: number) => Cons<B>): Cons<B>;
  <A, B>(self: List<A>, f: (a: A, i: number) => List<B>): List<B>;
}

Symbol

TypeId

Since v2.0.0

Signature

declare const TypeId: unique symbol

TypeId

type

Since v2.0.0

Signature

type TypeId = typeof TypeId

Unsafe

unsafeHead

Since v2.0.0

Unsafely returns the first element of the specified List.

Signature

declare function unsafeHead<A>(self: List<A>): A

unsafeLast

Since v2.0.0

Unsafely returns the last element of the specified List.

Signature

declare function unsafeLast<A>(self: List<A>): A

unsafeTail

Since v2.0.0

Unsafely returns the tail of the specified List.

Signature

declare function unsafeTail<A>(self: List<A>): List<A>