Represents a list of elements.

Creates a list of the given elements.

list(0, 1, 2, 3); //=> list(0, 1, 2, 3)

Creates an empty list.

const emptyList = empty(); //=> list()

Takes a single arguments and returns a singleton list that contains it.

of("foo"); //=> list("foo")

Takes two arguments and returns a list that contains them.

pair("foo", "bar"); //=> list("foo", "bar")

Converts an array, an array-like, or an iterable into a list.

from([0, 1, 2, 3, 4]); //=> list(0, 1, 2, 3, 4)
from(new Set([0, 1, 2, 3]); //=> list(0, 1, 2, 3)
from("hello"); //=> list("h", "e", "l", "l", "o"));

Returns a list of numbers between an inclusive lower bound and an exclusive upper bound.

range(3, 8); //=> list(3, 4, 5, 6, 7)

Returns a list of a given length that contains the specified value in all positions.

repeat(1, 7); //=> list(1, 1, 1, 1, 1, 1, 1)
repeat("foo", 3); //=> list("foo", "foo", "foo")

Generates a new list by calling a function with the current index n times.

times(i => i, 5); //=> list(0, 1, 2, 3, 4)
times(i => i * 2 + 1, 4); //=> list(1, 3, 5, 7)
times(() => Math.round(Math.random() * 10), 5); //=> list(9, 1, 4, 3, 4)

Gets the nth element of the list. If n is out of bounds undefined is returned.

const l = list(0, 1, 2, 3, 4);
nth(2, l); //=> 2

Gets the length of a list.

length(list(0, 1, 2, 3)); //=> 4

Returns the first element of the list. If the list is empty the function returns undefined.

first(list(0, 1, 2, 3)); //=> 0
first(list()); //=> undefined

Returns the last element of the list. If the list is empty the function returns undefined.

last(list(0, 1, 2, 3)); //=> 3
last(list()); //=> undefined

Folds a function over a list. Left-associative.

foldl((n, m) => n - m, 1, list(2, 3, 4, 5));
//=> (((1 - 2) - 3) - 4) - 5 === -13

Alias for foldl.

Map each element of list to an applicative, evaluate these applicatives from left to right, and collect the results.

This works with Fantasy Land applicatives.

const l = list(1, 3, 5, 4, 2);
L.scan((n, m) => n + m, 0, l); //=> list(0, 1, 4, 9, 13, 15));
L.scan((s, m) => s + m.toString(), "", l); //=> list("", "1", "13", "135", "1354", "13542")

Evaluate each applicative in the list from left to right, and and collect the results.

L.sequence(Maybe, list(just(1), just(2), just(3))); //=> just(list(1, 2, 3))
L.sequence(Maybe, list(just(1), just(2), nothing())); //=> nothing

Invokes a given callback for each element in the list from left to right. Returns undefined.

This function is very similar to map. It should be used instead of map when the mapping function has side-effects. Whereas map constructs a new list forEach merely returns undefined. This makes forEach faster when the new list is unneeded.

const l = list(0, 1, 2);
forEach(element => console.log(element)); // Prints 0, then 1, and then 2

Concats the strings in the list separated by a specified separator.

join(", ", list("one", "two", "three")); //=> "one, two, three"

Folds a function over a list. Right-associative.

foldr((n, m) => n - m, 5, list(1, 2, 3, 4));
1 - (2 - (3 - (4 - 5))); //=> 3

Alias for foldr.

Returns true if and only if the predicate function returns true for all elements in the given list.

every(isEven, empty()); //=> true
every(isEven, list(2, 4, 6, 8)); //=> true
every(isEven, list(2, 3, 4, 6, 7, 8)); //=> false
every(isEven, list(1, 3, 5, 7)); //=> false

Alias for every.

Returns true if and only if there exists an element in the list for which the predicate returns true.

const isEven = n => n % 2 === 0;
some(isEven, empty()); //=> false
some(isEven, list(2, 4, 6, 8)); //=> true
some(isEven, list(2, 3, 4, 6, 7, 8)); //=> true
some(isEven, list(1, 3, 5, 7)); //=> false

Alias for some.

Returns true if and only if the predicate function returns false for every element in the given list.

none(isEven, empty()); //=> true
none(isEven, list(2, 4, 6, 8)); //=> false
none(isEven, list(2, 3, 4, 6, 7, 8)); //=> false
none(isEven, list(1, 3, 5, 7)); //=> true

Returns the first element for which the predicate returns true. If no such element is found the function returns undefined.

find(isEven, list(1, 3, 5, 6, 7, 8, 9)); //=> 6
find(isEven, list(1, 3, 5, 7, 9)); //=> undefined

Returns the last element for which the predicate returns true. If no such element is found the function returns undefined.

find(isEven, list(1, 3, 5, 6, 7, 8, 9)); //=> 8
find(isEven, list(1, 3, 5, 7, 9)); //=> undefined

Returns the index of the first element in the list that is equal to the given element. If no such element is found -1 is returned.

const l = list(12, 4, 2, 89, 6, 18, 7);
indexOf(12, l); //=> 0
indexOf(89, l); //=> 3
indexOf(10, l); //=> -1

Returns the index of the last element in the list that is equal to the given element. If no such element is found -1 is returned.

const l = L.list(12, 4, 2, 18, 89, 2, 18, 7);
L.lastIndexOf(18, l); //=> 6
L.lastIndexOf(2, l); //=> 5
L.lastIndexOf(12, l); //=> 0

Returns the index of the first element for which the predicate returns true. If no such element is found the function returns -1.

findIndex(isEven, list(1, 3, 5, 6, 7, 9, 10)); //=> 3
findIndex(isEven, list(1, 3, 5, 7, 9)); //=> -1

Returns true if the list contains the specified element. Otherwise it returns false.

includes(3, list(0, 1, 2, 3, 4, 5)); //=> true
includes(3, list(0, 1, 2, 4, 5)); //=> false

Alias for includes.

Returns true if the two lists are equivalent.

equals(list(0, 1, 2, 3), list(0, 1, 2, 3)); //=> true
equals(list("a", "b", "c"), list("a", "z", "c")); //=> false

Returns true if the two lists are equivalent when comparing each pair of elements with the given comparison function.

equalsWith(
(n, m) => n.length === m.length,
list("foo", "hello", "one"),
list("bar", "world", "two")
); //=> true

Converts a list into an array.

toArray(list(0, 1, 2, 3, 4)); //=> [0, 1, 2, 3, 4]

Returns true if the given argument is a list and false otherwise.

isList(list(0, 1, 2)); //=> true
isList([0, 1, 2]); //=> false
isList("string"); //=> false
isList({ foo: 0, bar: 1 }); //=> false

Returns true if the given list is empty and false otherwise.

isEmpty(list()); //=> true
isEmpty(list(0, 1, 2)); //=> false

Prepends an element to the front of a list and returns the new list.

prepend(0, list(1, 2, 3)); //=> list(0, 1, 2, 3)
prepend("h", list("e", "l", "l", "o")); //=> list("h", "e", "l", "l", "o")

Appends an element to the end of a list and returns the new list.

append(3, list(0, 1, 2)); //=> list(0, 1, 2, 3)

Applies a function to each element in the given list and returns a new list of the values that the function return.

map(n => n * n, list(0, 1, 2, 3, 4)); //=> list(0, 1, 4, 9, 16)

Extracts the specified property from each object in the list.

const l = list(
   { foo: 0, bar: "a" },
   { foo: 1, bar: "b" },
   { foo: 2, bar: "c" }
);
pluck("foo", l); //=> list(0, 1, 2)
pluck("bar", l); //=> list("a", "b", "c")

Folds a function over a list from left to right while collecting all the intermediate steps in a resulting list.

const l = list(1, 3, 5, 4, 2);
L.scan((n, m) => n + m, 0, l); //=> list(0, 1, 4, 9, 13, 15));
L.scan((s, m) => s + m.toString(), "", l); //=> list("", "1", "13", "135", "1354", "13542")

Returns a new list that only contains the elements of the original list for which the predicate returns true.

filter(isEven, list(0, 1, 2, 3, 4, 5, 6)); //=> list(0, 2, 4, 6)

Returns a new list that only contains the elements of the original list for which the predicate returns false.

reject(isEven, list(0, 1, 2, 3, 4, 5, 6)); //=> list(1, 3, 5)

Splits the list into two lists. One list that contains all the values for which the predicate returns true and one containing the values for which it returns false.

partition(isEven, list(0, 1, 2, 3, 4, 5)); //=> [(list(0, 2, 4), list(1, 3, 5)]

Applies a list of functions to a list of values.

ap(list((n: number) => n + 2, n => 2 * n, n => n * n), list(1, 2, 3));
//=> list(3, 4, 5, 2, 4, 6, 1, 4, 9)

Flattens a list of lists into a list. Note that this function does not flatten recursively. It removes one level of nesting only.

const nested = list(list(0, 1, 2, 3), list(4), empty(), list(5, 6));
flatten(nested); //=> list(0, 1, 2, 3, 4, 5, 6)

Maps a function over a list and concatenates all the resulting lists together.

flatMap(n => list(n, 2 * n, n * n), list(1, 2, 3)); //=> list(1, 2, 1, 2, 4, 4, 3, 6, 9)

Alias for flatMap.

Concatenates two lists.

concat(list(0, 1, 2), list(3, 4)); //=> list(0, 1, 2, 3, 4)

Returns a list that has the entry specified by the index replaced with the given value.

If the index is out of bounds the given list is returned unchanged.

update(2, "X", list("a", "b", "c", "d", "e")); //=> list("a", "b", "X", "d", "e")

Returns a list that has the entry specified by the index replaced with the value returned by applying the function to the value.

If the index is out of bounds the given list is returned unchanged.

adjust(2, inc, list(0, 1, 2, 3, 4, 5)); //=> list(0, 1, 3, 3, 4, 5)

Returns a slice of a list. Elements are removed from the beginning and end. Both the indices can be negative in which case they will count from the right end of the list.

*
const l = list(0, 1, 2, 3, 4, 5);
slice(1, 4, l); //=> list(1, 2, 3)
slice(2, -2, l); //=> list(2, 3)

Takes the first n elements from a list and returns them in a new list.

take(3, list(0, 1, 2, 3, 4, 5)); //=> list(0, 1, 2)

Takes the first elements in the list for which the predicate returns true.

takeWhile(n => n < 4, list(0, 1, 2, 3, 4, 5, 6)); //=> list(0, 1, 2, 3)
takeWhile(_ => false, list(0, 1, 2, 3, 4, 5)); //=> list()

Takes the last elements in the list for which the predicate returns true.

takeLastWhile(n => n > 2, list(0, 1, 2, 3, 4, 5)); //=> list(3, 4, 5)
takeLastWhile(_ => false, list(0, 1, 2, 3, 4, 5)); //=> list()

Removes the first elements in the list for which the predicate returns true.

dropWhile(n => n < 4, list(0, 1, 2, 3, 4, 5, 6)); //=> list(4, 5, 6)

Returns a new list without repeated elements.

dropRepeats(L.list(0, 0, 1, 1, 1, 2, 3, 3, 4, 4)); //=> list(0, 1, 2, 3, 4)

Returns a new list without repeated elements by using the given function to determine when elements are equal.

dropRepeatsWith(
   (n, m) => Math.floor(n) === Math.floor(m),
   list(0, 0.4, 1.2, 1.1, 1.8, 2.2, 3.8, 3.4, 4.7, 4.2)
); //=> list(0, 1, 2, 3, 4)

Takes the last n elements from a list and returns them in a new list.

takeLast(3, list(0, 1, 2, 3, 4, 5)); //=> list(3, 4, 5)

Splits a list at the given index and return the two sides in a pair. The left side will contain all elements before but not including the element at the given index. The right side contains the element at the index and all elements after it.

const l = list(0, 1, 2, 3, 4, 5, 6, 7, 8);
splitAt(4, l); //=> [list(0, 1, 2, 3), list(4, 5, 6, 7, 8)]

Splits a list at the first element in the list for which the given predicate returns true.

const l = list(0, 1, 2, 3, 4, 5, 6, 7);
splitWhen((n) => n > 3, l); //=> [list(0, 1, 2, 3), list(4, 5, 6, 7)]

Splits the list into chunks of the given size.

splitEvery(2, list(0, 1, 2, 3, 4)); //=> list(list(0, 1), list(2, 3), list(4))

Takes an index, a number of elements to remove and a list. Returns a new list with the given amount of elements removed from the specified index.

const l = list(0, 1, 2, 3, 4, 5, 6, 7, 8);
remove(4, 3, l); //=> list(0, 1, 2, 3, 7, 8)
remove(2, 5, l); //=> list(0, 1, 7, 8)

Returns a new list without the first n elements.

drop(2, list(0, 1, 2, 3, 4, 5)); //=> list(2, 3, 4, 5)

Returns a new list without the last n elements.

dropLast(2, list(0, 1, 2, 3, 4, 5)); //=> list(0, 1, 2, 3)

Returns a new list with the last element removed. If the list is empty the empty list is returned.

pop(list(0, 1, 2, 3)); //=> list(0, 1, 2)

Alias for pop.

Returns a new list with the first element removed. If the list is empty the empty list is returned.

tail(list(0, 1, 2, 3)); //=> list(1, 2, 3)
tail(empty()); //=> list()

Inserts the given element at the given index in the list.

insert(2, "c", list("a", "b", "d", "e")); //=> list("a", "b", "c", "d", "e")

Inserts the given list of elements at the given index in the list.

insertAll(2, list("c", "d"), list("a", "b", "e", "f")); //=> list("a", "b", "c", "d", "e", "f")

Reverses a list.

reverse(list(0, 1, 2, 3, 4, 5)); //=> list(5, 4, 3, 2, 1, 0)

Iterate over two lists in parallel and collect the pairs.

const names = list("a", "b", "c", "d", "e");
const years = list(0, 1, 2, 3, 4, 5, 6);
//=> list(["a", 0], ["b", 1], ["c", 2], ["d", 3], ["e", 4]);

This is like mapping over two lists at the same time. The two lists are iterated over in parallel and each pair of elements is passed to the function. The returned values are assembled into a new list.

The shortest list determines the size of the result.

const names = list("Turing", "Curry");
const years = list(1912, 1900);
zipWith((name, year) => ({ name, year }), names, years);
//=> list({ name: "Turing", year: 1912 }, { name: "Curry", year: 1900 });

Sorts the given list. The list should contain values that can be compared using the < operator or values that implement the Fantasy Land Ord specification.

Performs a stable sort.

sort(list(5, 3, 1, 8, 2)); //=> list(1, 2, 3, 5, 8)
sort(list("e", "a", "c", "b", "d"); //=> list("a", "b", "c", "d", "e")

Sort the given list by comparing values using the given function. The function receieves two values and should return -1 if the first value is stricty larger than the second, 0 is they are equal and 1 if the first values is strictly smaller than the second.

Note that the comparison function is equivalent to the one required by Array.prototype.sort.

Performs a stable sort.

sortWith((a, b) => {
   if (a === b) {
     return 0;
   } else if (a < b) {
     return -1;
   } else {
     return 1;
   }
}, list(5, 3, 1, 8, 2)); //=> list(1, 2, 3, 5, 8)

Sort the given list by passing each value through the function and comparing the resulting value. The function should either return values comparable using < or values that implement the Fantasy Land Ord specification.

Performs a stable sort.

sortBy(
   o => o.n,
   list({ n: 4, m: "foo" }, { n: 3, m: "bar" }, { n: 1, m: "baz" })
); //=> list({ n: 1, m: "baz" }, { n: 3, m: "bar" }, { n: 4, m: "foo" })

sortBy(s => s.length, list("foo", "bar", "ba", "aa", "list", "z"));
//=> list("z", "ba", "aa", "foo", "bar", "list")

Returns a list of lists where each sublist's elements are all equal.

group(list(0, 0, 1, 2, 2, 2, 3, 3)); //=> list(list(0, 0), list(1), list(2, 2, 2), list(3, 3))

Returns a list of lists where each sublist's elements are pairwise equal based on the given comparison function.

Note that only adjacent elements are compared for equality. If all equal elements should be grouped together the list should be sorted before grouping.

const floorEqual = (a, b) => Math.round(a) === Math.round(b);
groupWith(floorEqual, list(1.1, 1.3, 1.8, 2, 2.2, 3.3, 3.4));
//=> list(list(1.1, 1.3), list(1.8, 2, 2.2), list(3.3, 3.4))

const sameLength = (a, b) => a.length === b.length;
groupWith(sameLength, list("foo", "bar", "ab", "bc", "baz"));
//=> list(list("foo", "bar"), list("ab", "bc"), list("baz))

Inserts a separator between each element in a list.

intersperse("n", list("ba", "a", "a")); //=> list("ba", "n", "a", "n", "a")