Array

Array<T> · T[]

The ordered list. Array<T> holds elements of one type, grows and shrinks on demand, and carries the richest method collection in the standard library. Half the methods below return new arrays; the other half edit in place — knowing which is which is the whole game.

Usage

Literals to build, methods to derive. Reach for the non-mutating variants unless you mean to edit in place.

const nums = [1, 2, 3];                          // literal — this one, always
const doubled = nums.map((n) => n * 2);          // new array, nums untouched
const last = nums.at(-1);                        // 3 — from the end
const sorted = [...nums].sort((a, b) => a - b);  // copy first: sort mutates

How it works

An array is an object with a live length. Reading it counts elements; writing it truncates or extends the array, leaving holes where nothing was ever assigned.

Methods split into two families. push, pop, splice, sort, and reverse edit in place — note sort returning this, the same array back. Their ES2023 twins — toSorted, toReversed, toSpliced, and with — return new arrays instead.

Arrays are generic: map and filter derive new element types from your callbacks, and a type-guard predicate lets filter narrow unions for you. Elements compare by reference when they are objects, which is why includes finds NaN but never the object literal you just built.

Instance API

Everything on Array.prototype, grouped by job. T is the element type.

38 methods

length: number: Property. Live element count; writing it truncates or extends.
at(index: number): T | undefined: Element at the index. Negatives count back from the end.
includes(searchElement: T, fromIndex?: number): boolean: Whether the element occurs. Uses SameValueZero, so NaN matches.
indexOf(searchElement: T, fromIndex?: number): number: First index of the element, or -1.
lastIndexOf(searchElement: T, fromIndex?: number): number: Last index of the element, or -1.

find(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): T | undefined: First element passing the test, or undefined.
findIndex(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): number: Index of the first passing element, or -1.
findLast(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): T | undefined: Like find, searching from the end.
findLastIndex(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): number: Like findIndex, searching from the end.

every(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): boolean: Whether all elements pass. Vacuously true when empty.
some(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): boolean: Whether at least one element passes.

map<U>(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any): U[]: A new array with each element mapped. The workhorse.
filter(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): T[]: A new array with only the passing elements.
flat<A, D extends number = 1>(this: A, depth?: D): FlatArray<A, D>[]: Flattens nested arrays to the given depth.
flatMap<U>(callback: (value: T, index: number, array: T[]) => U | readonly U[], thisArg?: any): U[]: Maps, then flattens one level. Made for one-to-many.
slice(start?: number, end?: number): T[]: A shallow copy of a section. Negatives count from the end.
concat(...items: ConcatArray<T>[]): T[]: A new array joining arrays and values. Prefer spread.

sort(compareFn?: (a: T, b: T) => number): this: Sorts in place and returns the same array. No comparator means string order.
toSorted(compareFn?: (a: T, b: T) => number): T[]: Like sort, but returns a new array and leaves this one alone.
reverse(): this: Reverses in place and returns the same array.
toReversed(): T[]: Like reverse, but returns a new array.

push(...items: T[]): number: Appends and returns the new length.
pop(): T | undefined: Removes and returns the last element.
shift(): T | undefined: Removes and returns the first element.
unshift(...items: T[]): number: Prepends and returns the new length.
splice(start: number, deleteCount?: number, ...items: T[]): T[]: Deletes and inserts at an index. Returns what was removed.
fill(value: T, start?: number, end?: number): this: Fills a range with one value. Same array back.
copyWithin(target: number, start: number, end?: number): this: Copies a slice onto itself. Same array back.

reduce(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): U: Folds left into one value. Also overloaded without an initial value.
reduceRight(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): U: Like reduce, folding from the right.
join(separator?: string): string: Joins every element into one string, comma by default.

forEach(callbackfn: (value: T, index: number, array: T[]) => void, thisArg?: any): void: Runs the callback per element. Returns nothing; prefer for...of for control flow.
entries(): IterableIterator<[number, T]>: Iterator of index-element pairs.
keys(): IterableIterator<number>: Iterator of indices.
values(): IterableIterator<T>: Iterator of elements.
[Symbol.iterator](): IterableIterator<T>: Makes the array work with for...of and spread.

toString(): string: Joins with commas. Same as join() with no separator.
toLocaleString(): string: Like toString, but elements localize first.

Static API

Called on Array itself. For checking and building arrays rather than working inside them.

Array.isArray(arg: any): arg is any[]: The reliable array check. A type guard, so it narrows.
Array.from<T>(iterable: Iterable<T> | ArrayLike<T>): T[]: Builds an array from anything iterable or array-like.
Array.of<T>(...items: T[]): T[]: Builds an array from arguments. No new Array(n) length trap.