Skip to content

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 Added in v2.0.0 Source

Combinators

compact

Added in v2.0.0 Source

Removes all None values from the specified list.

Signature

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

drop

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

Constructs a new empty List<A>.

Alias of nil.

Signature

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

fromIterable

Added in v2.0.0 Source

Creates a new List from an iterable collection of values.

Signature

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

make

Added in v2.0.0 Source

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

Signature

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

nil

Added in v2.0.0 Source

Constructs a new empty List<A>.

Signature

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

of

Added in v2.0.0 Source

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

Signature

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

Conversions

toArray

Added in v2.0.0 Source

Converts the specified List to an Array.

Signature

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

toChunk

Added in v2.0.0 Source

Converts the specified List to a Chunk.

Signature

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

Elements

every

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

Signature

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

Folding

reduce

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

last

Added in v2.0.0 Source

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

Added in v2.0.0 Source

Returns the number of elements contained in the specified List

Signature

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

tail

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

Signature

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

Other

List

Added in v2.0.0 Source

Refinements

isCons

Added in v2.0.0 Source

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

Signature

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

isList

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

Signature

declare const TypeId: unique symbol;

TypeId type

Added in v2.0.0 Source

Signature

type TypeId = typeof TypeId;

Unsafe

unsafeHead

Added in v2.0.0 Source

Unsafely returns the first element of the specified List.

Signature

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

unsafeLast

Added in v2.0.0 Source

Unsafely returns the last element of the specified List.

Signature

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

unsafeTail

Added in v2.0.0 Source

Unsafely returns the tail of the specified List.

Signature

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