TypeScript Array: Types, Arrays of Objects, map and filter

A TypeScript array type is the element type followed by []: string[] is an array of strings, number[] an array of numbers. The generic spelling Array<string> is the same type. Once an array is typed, every element you add and every element you read has that type.

const names: string[] = ["Ada", "Grace"];
const scores: Array<number> = [90, 85, 72]; // same as number[]

names.push("Alan");
// @ts-expect-error: Argument of type 'number' is not assignable to parameter of type 'string'.
names.push(42);

const first: string = names[0];
const total = scores.reduce((sum, s) => sum + s, 0); // number

console.log(names, first, total);

The @ts-expect-error line is a compile error (TS2345). Here it is marked as expected so the block still runs, and since types are erased, the 42 really is pushed at runtime: the output shows it.

string[] vs Array<string>

Pick one style for a codebase. typescript-eslint's array-type rule defaults to T[].

Arrays of Objects

Describe the element with a type alias or interface, then use Type[]. Everything read out of the array is checked against that shape.

type User = { id: number; name: string; admin: boolean };

const users: User[] = [
    { id: 1, name: "Ada", admin: true },
    { id: 2, name: "Grace", admin: false },
    { id: 3, name: "Alan", admin: false },
];

users.push({ id: 4, name: "Linus", admin: false });

const admins = users.filter((u) => u.admin);       // User[]
const names = users.map((u) => u.name);            // string[]
const byId = users.find((u) => u.id === 2);        // User | undefined

console.log(admins.length, names);
console.log(byId?.name ?? "not found"); // Grace

An object literal pushed into users must match User exactly: a missing admin or a misspelled property is a compile error.

Typed map, filter, reduce and find

The array methods are generic, so their results carry types. What each method does at runtime is covered on the JavaScript array methods page; the types are what TypeScript adds:

const prices = [4.5, 12, 8.25];

const labels = prices.map((p) => `$${p.toFixed(2)}`); // string[]
console.log(labels); // [ '$4.50', '$12.00', '$8.25' ]

const expensive = prices.find((p) => p > 100); // number | undefined
console.log(expensive ?? "none"); // none

// reduce's result type comes from the initial value,
// or from a type argument when the initial value is just {}
const byInitial = ["apple", "avocado", "banana"].reduce<Record<string, string[]>>(
    (acc, word) => {
        (acc[word[0]] ??= []).push(word);
        return acc;
    },
    {},
);
console.log(byInitial); // { a: [ 'apple', 'avocado' ], b: [ 'banana' ] }

// filter narrows when the callback is a type check
const raw = [1, undefined, 3, undefined];
const defined = raw.filter((n) => n !== undefined); // number[]
console.log(defined); // [ 1, 3 ]

The last example works because TypeScript (since 5.5) infers that (n) => n !== undefined is a type predicate, so filter returns number[] rather than (number | undefined)[]. For checks it cannot infer, write the predicate yourself: filter((x): x is User => x !== null).

Arrays That Hold More Than One Type

A union element type allows a mix. A union of array types does not:

const mixed: (string | number)[] = [1, "two", 3]; // each element: string or number

let ids: string[] | number[] = [1, 2, 3]; // all numbers...
ids = ["a", "b"];                          // ...or all strings

// @ts-expect-error: (string | number)[] is not assignable to string[] | number[]
ids = [1, "b"];

for (const item of mixed) {
    // narrow each element before using type-specific methods
    console.log(typeof item === "string" ? item.toUpperCase() : item.toFixed(1));
}

When positions have fixed types, like a [name, age] pair, use a tuple instead: [string, number] knows that index 0 is a string and index 1 is a number, where (string | number)[] does not.

Readonly Arrays

readonly T[] removes every method that mutates the array. Use it for parameters a function should not change, and for constants.

// This does not compile: readonly arrays have no push.
function average(values: readonly number[]): number {
    values.push(0);
    return values.reduce((a, b) => a + b, 0) / values.length;
}

console.log(average([2, 4, 6]));

index.ts(3,12): error TS2339: Property 'push' does not exist on type 'readonly number[]'.

Delete the push line and the block prints 4. A mutable number[] can always be passed where readonly number[] is expected, so readonly parameters cost callers nothing. The check is compile-time only: at runtime it is an ordinary array. To sort a readonly array, sort a copy: [...values].sort().

The includes Pitfall with Literal Arrays

as const turns an array into a readonly tuple of literal types. That is useful for a list of allowed values, but its includes then only accepts those literals:

const COLORS = ["red", "green", "blue"] as const;
type Color = (typeof COLORS)[number]; // "red" | "green" | "blue"

function isColor(value: string): value is Color {
    // COLORS.includes(value) is error TS2345: 'string' is not assignable
    // to '"blue" | "green" | "red"'. Widen the array for the check:
    return (COLORS as readonly string[]).includes(value);
}

const input: string = "green";
if (isColor(input)) {
    const c: Color = input; // narrowed to Color
    console.log("valid color:", c);
}
console.log(isColor("purple")); // false

Wrapping the check in a type guard (value is Color) means the widening happens once, and callers get a narrowed value back.

Indexing and Empty Arrays

Reading arr[i] gives type T, even when i is out of range and the runtime value is undefined. at(i) is typed T | undefined, and the compiler option noUncheckedIndexedAccess makes plain indexing return T | undefined too.

const queue: string[] = []; // annotate empty arrays

const head = queue[0];     // type string, value undefined
const last = queue.at(-1); // type string | undefined

console.log(head, last);            // undefined undefined
console.log(last?.toUpperCase());   // undefined, safely

queue[0].toUpperCase() would compile and then throw a TypeError at runtime. Prefer at(), a length check, or noUncheckedIndexedAccess when an index may be missing.