@oxi/list@1.2.0
Built and signed on GitHub Actions
Built and signed on GitHub Actions

latest

oxitools/list

Immutable list with a bunch of useful manipulation methods

JSR Score

100%

Published

6 months ago (1.2.0)

@oxi/list

List

class List

implements Iterable<T>

Represents an immutable list of items. The List class provides a variety of methods to perform operations on lists such as mapping, filtering, and reducing. This class is designed to offer a functional approach to list manipulation.

Constructors

new



List(array: ReadonlyArray<T>)

Creates an instance of List from a ReadonlyArray. This constructor is private and is only meant to be used internally by the class.

Type Parameters

The type of elements in the list.

Properties

readonly



size: number

Returns the number of elements in the list.

Methods



[Symbol.iterator](): Iterator<T>



append(...items: ReadonlyArray<T>): List<T>

Appends new elements to the end of the list and returns a new List.



at(index: number): Option<T>

Retrieves the element at the specified index. Negative indices count from the end of the list. Wraps the result in an Option<T>, which is Some<T> if an element is found, or None if the index is out of bounds.



chunk(size: number): List<T[]>

Splits the list into chunks of the specified size and returns a new list of these chunks.



clone(deep?: boolean): List<T>

Creates a shallow or deep clone of the list. structuredClone must be available in the environment to perform a deep clone.



compact(): List<NonNullable<T>>

Filters out null and undefined values from the list and returns a new list of all truthy values as well as 'falsy' values like 0 (zero), '' (empty string), and false that are not null or undefined.



compactMap<U>(callback: (item: T,
index: number,
) => U): List<NonNullable<U>>

Maps each item using a callback function and filters out any null or undefined values in the same pass.



concat(...items: ReadonlyArray<Iterable<T>>): List<T>

Concatenates all the elements in the provided lists into a single list.



countBy<K extends string>(callback: (item: T,
index: number,
) => K): Record<K, number>

Groups the elements of the list according to a callback function and returns the count of elements in each group.



difference(other: List<T>): List<T>

Returns a new list containing only the elements from this list that are not present in the provided list.



drop(count: number): List<T>

Drops the first count elements from the list and returns a new list containing the remaining elements.



dropFirst(): List<T>

Drops the first element from the list and returns a new list containing the remaining elements.



dropLast(): List<T>

Drops the last element from the list and returns a new list containing the remaining elements.



dropWhile(predicate: (item: T,
index: number,
) => boolean): List<T>

Drops elements from the list as long as the predicate returns true and returns a new list with the remaining elements.



each(callback: (item: T,
index: number,
) => void): this

Performs the specified action for each element in the list.



enumerate(): List<[number, T]>

Creates a new list containing tuples of each element in the list and its index.



every(predicate: (item: T,
index: number,
) => boolean): boolean

Determines whether all elements of the list satisfy the specified condition.



filter<U extends T>(predicate: (item: T,
index: number,
) => item is U): List<U>



filter(predicate: (item: T,
index: number,
) => boolean): List<T>



find(predicate: (item: T,
index: number,
) => boolean): Option<T>

Finds the first element in the list satisfying a predicate, if any. Wraps the result in an Option<T>, which is Some<T> if an element is found that satisfies the predicate, or None if no such element exists.



findIndex(predicate: (item: T,
index: number,
) => boolean): Option<number>

Finds the index of the first element in the list that satisfies the provided testing function. Wraps the result in an Option<number>, which is Some<number> if an element satisfying the predicate is found, or None if no such element exists.



findLast(predicate: (item: T,
index: number,
) => boolean): Option<T>

Finds the last element in the list satisfying a predicate, if any. Wraps the result in an Option<T>, which is Some<T> if an element is found that satisfies the predicate from the end of the list, or None if no such element exists.



findLastIndex(predicate: (item: T,
index: number,
) => boolean): Option<number>

Finds the index of the last element in the list that satisfies the provided testing function. Wraps the result in an Option<number>, which is Some<number> if an index is found that satisfies the predicate from the end of the list, or None if no such index exists.



first(): Option<T>

Returns the first element of the list wrapped in an Option<T>. If the list is empty, it returns None.



flat<D extends number>(depth?: D): List<FlatArray<T[], D>>

Flattens the list up to a specified depth and returns a new list.



flatMap<U>(callback: (item: T,
index: number,
) => U | ReadonlyArray<U>): List<U>

Maps each element using a callback function and flattens the result into a new list.



groupBy<K extends string>(callback: (item: T,
index: number,
) => K): Record<K, T[]>

Groups the elements of the list according to a callback function and returns an object.



has(item: T): boolean

Checks if the list contains a specific element.



insertAt(index: number,
item: T,
): List<T>

Inserts an item at the specified index and returns a new list. Negative indices count from the end of the list.



intersection(other: List<T>): List<T>

Creates a new list that is the intersection of the current list and another list.



isEmpty(): boolean

Checks if the list is empty.



isNotEmpty(): boolean

Checks if the list is not empty.



last(): Option<T>

Returns the last element of the list wrapped in an Option<T>. If the list is empty, it returns None.



map<U>(callback: (item: T,
index: number,
) => U): List<U>

Maps each element in the list using a transformation function and returns a new list of the transformed elements.



move(src: number,
dst: number,
): List<T>

Moves an element from one position to another within the list and returns a new list. Negative indices count from the end of the list.



partition<U extends T>(predicate: (item: T,
index: number,
) => item is U): [List<U>, List<Exclude<T, U>>]

Partitions the elements of the list into two groups based on a type-guard predicate. The first group contains all elements for which the predicate returns true (of type U), and the second group contains all the elements for which it returns false (type Exclude<T, U>).



partition(predicate: (item: T,
index: number,
) => boolean): [List<T>, List<T>]

Partitions the elements of the list into two groups based on a boolean-returning predicate. The first group contains all elements for which the predicate returns true, and the second group contains all the elements for which it returns false.



prepend(...items: ReadonlyArray<T>): List<T>

Adds new elements to the beginning of the list and returns a new list.



random(): Option<T>

Returns a random element from the list wrapped in an Option<T>. If the list is empty, it returns None.

This method selects a random element using a uniform distribution, meaning each element has an equal chance of being selected.



reduce<U>(initialValue: U,
callback: (accumulator: U,
current: T,
) => U,
): U

Reduces the list to a single value using a reducer function and an initial accumulator value.



reduceRight<U>(initialValue: U,
callback: (accumulator: U,
current: T,
) => U,
): U

Reduces the list to a single value using a reducer function and an initial accumulator value, starting from the right.



removeAt(index: number): List<T>

Removes the element at the specified index and returns a new list. Negative indices count from the end of the list.



replaceAt(index: number,
item: T,
): List<T>

Replaces the element at the specified index with a new value and returns a new list. Negative indices count from the end of the list.



reverse(): List<T>

Reverses the order of the elements in the list and returns a new list.



rotate(count: number): List<T>

Rotates the elements of the List by the specified number of positions. Positive values rotate to the right, negative values rotate to the left.



shuffle(permutations?: number): List<T>

Randomly shuffles the elements of the list a specified number of times and returns a new list. If no number of permutations is specified, the list will be shuffled once by default.



slice(start?: number,
end?: number,
): List<T>

Creates a slice of the list from start up to, but not including, end and returns a new list.



some(predicate: (item: T,
index: number,
) => boolean): boolean

Checks if at least one element in the list passes the test implemented by the provided function.



sort(compareFn?: (a: T,
b: T,
) => number): List<T>

Sorts the elements of the list according to the order specified by the compare function and returns a new list.



splice(start: number,
deleteCount?: number | undefined,
): List<T>



splice(start: number,
deleteCount: number,
...items: ReadonlyArray<T>,
): List<T>



swap(aIndex: number,
bIndex: number,
): List<T>

Swaps two elements in the list by their indexes and returns a new list.



take(count: number): List<T>

Returns a new list containing the first count elements from the list.



takeWhile(predicate: (item: T,
index: number,
) => boolean): List<T>

Returns a new list with elements taken from the beginning as long as the predicate returns true.



toArray(): T[]

Converts the list into a standard JavaScript array.



toJSON(): T[]

Converts the list into a JSON string representation. This method is used by JSON.stringify.



toSet(): Set<T>

Converts the list into a standard JavaScript set.



toString(): string

Returns a string representing the list and its elements.



union(other: List<T>): List<T>

Creates a new list that is the union of the current list and another list, excluding duplicate elements.



unique(): List<T>

Returns a new list with all duplicate elements removed.



uniqueBy<K extends string | number>(callback: (item: T,
index: number,
) => K): List<T>

Returns a new list with all duplicate elements removed, based on the result of the callback function.



updateAt(index: number,
callback: (item: T,
index: number,
) => T,
): List<T>

Updates the element at the specified index using a callback function and returns a new list.



zip<U>(other: List<U>): List<[T, U]>

Combines two lists by pairing up their elements and returns a new list containing pairs.

Static Methods



empty<T>(): List<T>

Creates an empty List.



from<T>(iterable: Iterable<T> | ArrayLike<T>): List<T>

Creates a new List from an iterable object or array-like object.



isList(value: unknown): value is List<unknown>

Checks if a value is a List instance.



of<T>(...items: ReadonlyArray<T>): List<T>

Creates a new List instance from a spread of items.



range(from: number,
to: number,
step?: number,
): List<number>

Creates a new List containing a range of numbers.

Add Package

deno add jsr:@oxi/list

Import symbol

import { List } from "@oxi/list";

---- OR ----

Import directly with a jsr specifier

import { List } from "jsr:@oxi/list";

Add Package

npx jsr add @oxi/list

Import symbol

import { List } from "@oxi/list";

Add Package

yarn dlx jsr add @oxi/list

Import symbol

import { List } from "@oxi/list";

Add Package

pnpm dlx jsr add @oxi/list

Import symbol

import { List } from "@oxi/list";

Add Package

bunx jsr add @oxi/list

Import symbol

import { List } from "@oxi/list";

@oxi/list@1.2.0Built and signed on GitHub ActionsBuilt and signed on GitHub Actions

Constructors

Type Parameters

Properties

Methods

Static Methods

@oxi/list@1.2.0
Built and signed on GitHub Actions
Built and signed on GitHub Actions