Arrays & tuples

A list where every item is the same kind

A shop page is full of lists: the prices in a cart, the tags on a product, the searches someone made. In JavaScript, a list is an array (Arrays covers them). TypeScript gives every array a type that says what kind of item it holds. Here are three prices, with no type written:

1const prices = [3, 4, 5];2//    ^?3prices.push(6);4console.log(prices);

Line 1 makes an array of three numbers. The query on line 2 shows the type TypeScript inferred: const prices: number[]. Read number[] as "an array of numbers". The square brackets after a type mean "a list of these". Line 3 adds a fourth price with push, and line 4 prints [3, 4, 5, 6].

The type says what goes in the array, not how many items there are. So adding a number is fine, but adding anything else isn't:

1const prices: number[] = [3, 4, 5];2prices.push(6);3prices.push("free");4console.log(prices.length);

Line 1 writes the type itself, prices: number[]. Line 2 pushes 6, a number. Line 3 pushes the text "free", and TypeScript marks it on purpose: Argument of type 'string' is not assignable to parameter of type 'number'. An argument is a value you pass to a function, here to push. The message means "push on this array only takes numbers". When it runs anyway, the text goes in, and line 4 prints 5.

Writing an array type

There are two ways to write an array type. They mean exactly the same thing:

1const tags: string[] = ["tea", "green"];2const prices: Array<number> = [3, 4, 5];3//    ^?4const flags: boolean[] = [true, false];5console.log(tags.length, prices.length, flags.length);

Line 1 writes string[]: an array of strings, for a product's tags. Line 2 writes Array<number>. The angle brackets hold the item type, so read it as "an Array of number". The query on line 3 shows TypeScript treats it as number[], the same type. (Angle brackets like these are called generics, and get lessons of their own later.) Line 4 is an array of booleans. Line 5 prints 2 3 2, the three lengths.

Most code uses the short form, number[]. Pick one and use it everywhere in a project.

Like any value, an array usually doesn't need a type written: TypeScript infers it from the items. Press each button to start the cart with different items, and watch the query on line 2:

1const cart = [3, 4, 5];2//    ^?3cart.push(6);4console.log(cart);

Numbers give number[], and text gives string[], which makes line 3's push(6) an error. Mixed items give a type like (string | number)[]. The | means "or": every item is a string or a number (the Union types lesson covers |). The round brackets matter: (string | number)[] is one array of mixed items, but string | number[] means "a string, or an array of numbers".

There is one array TypeScript can't read a type from: an empty one. Here is a function that starts an empty list of recent searches:

1function recentSearches() {2  const searches = [];3  return searches;4}

Line 2 makes an empty array, and line 3 returns it. There are no items to infer from, and nothing is added before line 3 hands it back, so TypeScript reports, on purpose here: Variable 'searches' implicitly has type 'any[]' in some locations where its type cannot be determined. In plain words: "I can't tell what this array will hold, so I'd have to stop checking it". Line 3 gets a matching error. (If the function pushed strings in before returning, TypeScript would follow the pushes and settle on string[]. Writing the type is still clearer.) The fix is the habit from the last lesson: annotate what TypeScript can't see.

1function recentSearches() {2  const searches: string[] = [];3  return searches;4}5const recent = recentSearches();6recent.push("green tea");7console.log(recent);

Line 2 now says searches is a string[]. The errors are gone. Line 5 calls the function, line 6 pushes a search into the list it gave back, and line 7 prints ["green tea"].

Because TypeScript knows the item type, array methods know it too. The functions you pass to map and find get their parameter types from the array, with no annotation (map, filter, and reduce covers these methods):

1const prices = [3, 4, 5];2const doubled = prices.map((price) => price * 2);3//    ^?4const expensive = prices.find((price) => price > 4);5//    ^?6console.log(doubled, expensive);

On line 2, price is a number because prices is a number[], so price * 2 is number math. The query on line 3 shows map gives back number[]. Line 4 uses find, and the query on line 5 shows number | undefined: a number, or undefined when nothing matches. Line 6 prints [6, 8, 10] 5.

An array type has one gap: it doesn't know how many items there are. Reading past the end gets no error:

1const prices = [3, 4, 5];2const fourth = prices[3];3//    ^?4console.log(fourth);

Line 2 reads prices[3], the fourth item. There are only three. The query on line 3 still says const fourth: number, and there is no error, but line 4 prints undefined. TypeScript assumes every index you read is there. A compiler option called noUncheckedIndexedAccess changes that. This example turns it on; the list under the code shows the option:

1const prices = [3, 4, 5];2const fourth = prices[3];3//    ^?4console.log(fourth.toFixed(2));

Now the query on line 3 says number | undefined, and line 4 gets 'fourth' is possibly 'undefined', on purpose. That's true: when it runs, line 4 throws a TypeError. The option isn't part of strict, so many projects leave it off, and every other example in these lessons does too.

Tuples for fixed shapes

Sometimes a list has a fixed shape: a product name and a quantity, always in that order. A tuple type describes that. You write the type of each position inside square brackets:

1const teaLine: [string, number] = ["Tea", 3];2const [name, quantity] = teaLine;3//     ^?4console.log(name.toUpperCase(), quantity * 2);

Line 1 says teaLine holds exactly two items: item 0 is a string and item 1 is a number. Line 2 takes it apart with destructuring, and the query on line 3 shows const name: string. So on line 4, name.toUpperCase() and quantity * 2 are both allowed, and it prints TEA 6.

From square brackets alone, TypeScript infers an array, not a tuple. (The Literal types lesson shows as const, which changes that.) Try line 1 without a type, with an array type, with the tuple type, and with the tuple in the wrong order:

1const teaLine = ["Tea", 3];2const [name, quantity] = teaLine;3//     ^?4console.log(name.toUpperCase(), quantity * 2);

With no type, or with (string | number)[], TypeScript only knows each item is a string or a number, so both uses on line 4 get errors. With [string, number], it knows which is which, and the errors go away. With [number, string], line 1 gets errors because the values are the wrong way round. A tuple's order is part of its type.

A tuple also knows its length, so it catches the gap an array type has:

1const teaLine: [string, number] = ["Tea", 3];2const cakeLine: [string, number] = ["Cake", 4, 2];3console.log(teaLine[2]);

Both errors are on purpose:

• Line 2 gives cakeLine three items. The message ends with Source has 3 element(s) but target allows only 2: "you gave three, the type takes two". An element is an item in an array.
• Line 3 reads index 2: Tuple type '[string, number]' of length '2' has no element at index '2'. When it runs, it prints undefined.

You'll meet tuples in code you didn't write. Object.entries turns an object into a list of key-and-value pairs, and each pair is a tuple:

1const stock = { tea: 3, cake: 0 };2const rows = Object.entries(stock);3//    ^?4for (const [name, count] of rows) {5  console.log(name, count);6}

Line 1 is the stock of two products. Line 2 calls Object.entries, and the query on line 3 shows [string, number][]: an array of tuples, each a name and a count. Line 4 takes each pair apart in a for…of loop, so name is a string and count is a number. It prints tea 3, then cake 0.

The table below compares the two kinds of list. Read each row as a question, then the answer for each.

Optional and rest elements

Some fixed shapes have a part that may be missing. A color for a page theme is three numbers, red, green, and blue, and sometimes a fourth for how see-through it is. A ? after a tuple element makes it optional:

1type Color = [number, number, number, number?];2 3const orange: Color = [255, 165, 0];4const glass: Color = [255, 165, 0, 0.5];5const [red, green, blue, alpha] = glass;6//                       ^?7console.log(orange.length, glass.length);8//                 ^?

Line 1 gives the shape a name with a type alias, type Color = …, so it can be reused (the Type aliases & interfaces lesson covers them). The number? at the end is the optional element. Line 3 gives orange three numbers, and line 4 gives a see-through glass color four. Both fit. Line 5 takes glass apart, and the query on line 6 shows const alpha: number | undefined: the fourth item may not be there. Line 7 prints 3 4, and the query on line 8 shows length: 3 | 4. TypeScript knows the length is 3 or 4. Optional elements go at the end: a required element can't follow one, so [number?, number] is an error.

Other shapes have a fixed start and then any number of items. A rest element, written ... before an array type, means "any number of these" (like rest syntax in JavaScript). A page's breadcrumb, the trail of links at the top like Home / Shop / Tea, always has at least one page:

1type Breadcrumb = [string, ...string[]];2 3const trail: Breadcrumb = ["Home", "Shop", "Tea"];4const home: Breadcrumb = ["Home"];5const nowhere: Breadcrumb = [];6console.log(trail.join(" / "), home.length);

Line 1 says a Breadcrumb starts with one string, followed by any number of strings: ...string[]. Lines 3 and 4 fit, with three pages and with one. Line 5 tries an empty trail, and TypeScript marks it on purpose: Source has 0 element(s) but target requires 1. A plain string[] would allow [], and code that reads trail[0] would get undefined. Line 6 prints Home / Shop / Tea 1.

The table below shows how many items each type allows. Read each row as: this type, how many items it takes, and a value that fits.

Read-only arrays

Some arrays shouldn't change after they're made, like a product's tags shown on its page. Put readonly before the type, and TypeScript allows reading but not changing:

1const tags: readonly string[] = ["tea", "green"];2tags.push("organic");3tags[0] = "coffee";4const loud = tags.map((tag) => tag.toUpperCase());5console.log(loud);

Line 1 says tags is a readonly string[]. Two lines get errors, on purpose:

• Line 2: Property 'push' does not exist on type 'readonly string[]'. A read-only array type has no methods that change it: no push, pop, sort, or splice.
• Line 3: Index signature in type 'readonly string[]' only permits reading. "Index signature" means reading or writing by position, like tags[0]. You may read it, not store a new value.

Line 4 is fine: map makes a new array and leaves tags alone. Run it anyway, and line 5 prints ["COFFEE", "GREEN", "ORGANIC"]: lines 2 and 3 really did change the array. readonly is a check TypeScript makes, and like every type it's removed before the code runs. You can also write ReadonlyArray<string>; it's the same type.

const and readonly guard different things. const stops the name from getting a different array. readonly stops the array from being changed. The table below compares them. Read each row as: what you try, then what happens with each declaration.

Where readonly helps most is a function's parameter. Passing an array to a function doesn't copy it, so a function that sorts its parameter sorts your array. Switch the parameter type and the method, and watch the cart in the output:

1function cheapestFirst(prices: number[]) {2  return prices.sort((a, b) => a - b);3}4 5const cart = [5, 3, 4];6const sorted = cheapestFirst(cart);7console.log(sorted, cart);

With number[] and sort, there are no errors, but cart comes out sorted: the shopper's order is lost. With readonly number[], TypeScript stops sort on line 2. With toSorted, which sorts a copy (Sorting arrays covers both), the error is gone and cart keeps its order. A readonly parameter is a promise: "this function won't change what you pass in".

Recent searches in a search box

A search box remembers your last three searches, newest first, with no repeats. Here is the function that adds one, with a readonly list coming in and a new list going out:

1function addSearch(recent: readonly string[], term: string): string[] {2  const others = recent.filter((item) => item !== term);3  return [term, ...others].slice(0, 3);4}5 6let recent: readonly string[] = ["tea", "cake"];7recent = addSearch(recent, "scones");8recent = addSearch(recent, "tea");9console.log(recent);

Line by line:

• Line 1: addSearch takes the current searches as a readonly string[], so it can't change them, and promises to give back a string[].
• Line 2 uses filter to make a new array without the new term, so a repeat moves to the front instead of appearing twice. item is a string, inferred from the array.
• Line 3 builds a new array with the term first, then the others, using spread (...), and keeps the first three with slice.
• Line 6 starts the list. It's a let, so the name can take each new list, but each list is read-only. Lines 7 and 8 add scones, then tea again.
• Line 9 prints ["tea", "scones", "cake"]: tea moved to the front, and nothing was changed in place.

Common mix-ups

• "A const array can't change." No. const only stops the name from getting a different array. push and sort still work. Use readonly to stop changes to the items.
• "TypeScript knows how many items my array has." No. prices[3] is a number to TypeScript even when there are only three prices. Tuples know their length; arrays don't.
• "["Tea", 3] is a tuple." No. Without a type, it's inferred as (string | number)[]. Write [string, number] to get a tuple.
• "number[] and Array<number> are different types." No. They're two spellings of the same type.
• "readonly freezes the array while the page runs." No. It's a check TypeScript makes, and it's removed with the other types. Another name for the same array, without readonly, can still change it.
• "An optional tuple element can go anywhere." No. Optional elements go at the end; a required element can't follow one: [number?, number] gets A required element cannot follow an optional element.

Practice exercises

Each exercise is TypeScript. Press Edit & run on the starter code to try your answer: the errors update as you type, the type under the cursor shows below the editor, and the console shows what it prints. Guess first, then use the hints.

1const ratings = [4, 5, 3];2console.log(ratings.length);

1const ratings = [4, 5, 3];2//    ^?3console.log(ratings.length);

const tags: string[] = ["tea", "green"];
tags.push("organic");
tags.push(42);
console.log(tags.length);

1const tags: string[] = ["tea", "green"];2tags.push("organic");3tags.push("loose leaf");4console.log(tags.length);

1const cakeLine = ["Cake", 4];2const [name, price] = cakeLine;3console.log(name.toUpperCase(), price + 1);

1const cakeLine: [string, number] = ["Cake", 4];2const [name, price] = cakeLine;3console.log(name.toUpperCase(), price + 1);

1function emptyCart() {2  const items = [];3  return items;4}5const cart = emptyCart();6cart.push("tea");7console.log(cart);

1function emptyCart() {2  const items: string[] = [];3  return items;4}5const cart = emptyCart();6cart.push("tea");7console.log(cart);

1function cheapest(prices: readonly number[]) {2  prices.sort((a, b) => a - b);3  return prices[0];4}5const cart = [5, 3, 4];6console.log(cheapest(cart), cart);

1function cheapest(prices: readonly number[]) {2  const sorted = prices.toSorted((a, b) => a - b);3  return sorted[0];4}5const cart = [5, 3, 4];6console.log(cheapest(cart), cart);

1type Breadcrumb = string[];2 3const trail: Breadcrumb = [];4console.log(trail[0].toUpperCase());

1type Breadcrumb = [string, ...string[]];2 3const trail: Breadcrumb = ["Home"];4console.log(trail[0].toUpperCase());

Check your understanding

For each question, ask: does the type say what every item is, or what each position is, and can the list be changed? The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• number[] and Array<number> both mean an array of numbers. TypeScript infers the type from the items; annotate an empty array.
• An array type says what every item is, not how many there are, so reading past the end isn't an error.
• A tuple type like [string, number] fixes the length and the type at each position. You write it yourself: square brackets alone give an array.
• ? makes a tuple's last elements optional, and ...string[] adds any number of items, as in [string, ...string[]].
• readonly string[] can be read but not changed. Use it for parameters, and use copying methods like toSorted and map.

Coming next: Object types. It shows how to describe an object's shape: its properties, the ones that can be left out, and the ones that can't change.