Read-only arrays in Typescript - Deep Dive

Overview - Read-only arrays

What is it?

Read-only arrays in TypeScript are arrays that cannot be changed after they are created. This means you cannot add, remove, or modify elements in these arrays. They help keep data safe by preventing accidental changes. You use them when you want to make sure the list stays the same throughout your program.

Why it matters

Without read-only arrays, it is easy to accidentally change data that should stay fixed, causing bugs that are hard to find. Read-only arrays protect important data by making it impossible to change, which helps programs run more reliably and safely. This is especially useful in large projects where many parts of the code use the same data.

Where it fits

Before learning read-only arrays, you should understand basic arrays and how to use them in TypeScript. After mastering read-only arrays, you can learn about immutability in objects and advanced type features like readonly tuples and readonly mapped types.

Mental Model

Core Idea

A read-only array is like a sealed box of items you can look at but cannot open or change.

Think of it like...

Imagine a photo album that is glued shut. You can see all the pictures inside, but you cannot add new photos, remove old ones, or rearrange them. This keeps the album exactly as it was when sealed.

Read-only Array
┌─────────────────────────────┐
│ [item1, item2, item3, ...]  │
│  (cannot add, remove, or     │
│   change items)              │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Basic arrays in TypeScript

Concept: Learn what arrays are and how to use them in TypeScript.

An array is a list of items stored in order. You can create an array like this: const numbers: number[] = [1, 2, 3]; You can add, remove, or change items: numbers.push(4); // adds 4 numbers[0] = 10; // changes first item to 10

Result

You get a list of numbers you can change freely.

Understanding normal arrays is essential because read-only arrays build on this idea but add restrictions.

2

Foundation

What is immutability?

Concept: Immutability means data cannot be changed after creation.

When data is immutable, you cannot modify it. For example, strings in JavaScript are immutable: const name = "Alice"; // You cannot change characters inside 'name'. Immutability helps avoid bugs by keeping data safe.

Result

You understand that some data types cannot be changed, which helps keep programs predictable.

Knowing immutability helps you appreciate why read-only arrays exist and how they improve code safety.

3

Intermediate

Declaring read-only arrays

🤔Before reading on: do you think you can change elements in a read-only array like a normal array? Commit to your answer.

Concept: TypeScript allows you to declare arrays as read-only using the 'readonly' keyword.

You can declare a read-only array like this: const readonlyNumbers: readonly number[] = [1, 2, 3]; Trying to change it causes errors: readonlyNumbers.push(4); // Error readonlyNumbers[0] = 10; // Error

Result

The array cannot be changed after creation, and TypeScript will warn you if you try.

Understanding how to declare read-only arrays is key to using immutability in your code.

4

Intermediate

Using ReadonlyArray<T> type

🤔Before reading on: do you think 'readonly T[]' and 'ReadonlyArray' are the same or different? Commit to your answer.

Concept: TypeScript provides a built-in generic type 'ReadonlyArray' as an alternative way to declare read-only arrays.

You can write: const readonlyStrings: ReadonlyArray = ["a", "b", "c"]; This works the same as 'readonly string[]'. Both prevent changes: readonlyStrings.pop(); // Error readonlyStrings[1] = "z"; // Error

Result

You can use either syntax to create read-only arrays, depending on style preference.

Knowing both syntaxes lets you read and write code more flexibly and understand different codebases.

5

Intermediate

Read-only arrays and methods

🤔Before reading on: do you think methods like 'map' or 'filter' change the original read-only array? Commit to your answer.

Concept: Read-only arrays allow methods that do not modify the array but disallow those that do.

Methods like 'map', 'filter', and 'slice' return new arrays and do not change the original: const newArray = readonlyNumbers.map(x => x * 2); But methods like 'push', 'pop', 'splice' cause errors: readonlyNumbers.push(5); // Error

Result

You can safely use non-mutating methods on read-only arrays to create new arrays.

Understanding which methods are safe helps you work with read-only arrays without errors.

6

Advanced

Readonly arrays in function parameters

🤔Before reading on: do you think passing a read-only array to a function prevents the function from changing it? Commit to your answer.

Concept: Using read-only arrays as function parameters enforces that the function cannot modify the array.

Example: function printItems(items: readonly string[]) { items.forEach(item => console.log(item)); // items.push('new'); // Error } This guarantees the function only reads the array.

Result

Functions become safer and clearer about their intentions when using read-only arrays.

Knowing this helps you write functions that do not accidentally change input data, improving reliability.

7

Expert

TypeScript readonly arrays and structural typing

🤔Before reading on: do you think a normal array can be assigned to a read-only array variable without error? Commit to your answer.

Concept: TypeScript's structural typing allows normal arrays to be assigned to read-only array types, but not vice versa, enabling flexible but safe code.

Example: const normalArray: number[] = [1, 2, 3]; const roArray: readonly number[] = normalArray; // Allowed But: const roArray2: readonly number[] = [4, 5, 6]; const normalArray2: number[] = roArray2; // Error This means you can use normal arrays where read-only is expected, but not the other way around.

Result

You understand how TypeScript balances flexibility and safety with read-only arrays.

Knowing this prevents common assignment errors and helps design APIs that accept read-only inputs safely.

Under the Hood

Read-only arrays in TypeScript are a compile-time feature enforced by the type system. At runtime, they are normal JavaScript arrays without any special behavior. The TypeScript compiler checks your code and prevents any operations that would modify a read-only array. This means the safety is guaranteed only during development and compilation, not at runtime.

Why designed this way?

TypeScript was designed to add safety without changing JavaScript's runtime behavior. By enforcing read-only arrays only at compile time, it avoids performance costs and complexity in JavaScript engines. This design allows gradual adoption and compatibility with existing JavaScript code.

TypeScript Code
┌─────────────────────────────┐
│ const ro: readonly number[] │
│ = [1, 2, 3];                │
└─────────────┬───────────────┘
              │
              ▼
Compile-time check
┌─────────────────────────────┐
│ Prevent mutations like push │
│ or assignment to elements   │
└─────────────┬───────────────┘
              │
              ▼
JavaScript runtime
┌─────────────────────────────┐
│ Normal array [1, 2, 3]      │
│ No runtime restrictions     │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Can you modify a read-only array at runtime using JavaScript methods? Commit to yes or no.

Common Belief: Read-only arrays prevent any changes to the array at runtime.

Reality: Read-only arrays only prevent changes at compile time in TypeScript. At runtime, they are normal arrays and can be changed if you bypass type checks.

Why it matters: Assuming runtime immutability can lead to bugs if code modifies arrays through unsafe means, breaking assumptions about data safety.

Quick: Is 'readonly T[]' exactly the same as 'ReadonlyArray'? Commit to yes or no.

Common Belief: The two syntaxes are completely different and incompatible.

Reality: 'readonly T[]' and 'ReadonlyArray' are two ways to express the same read-only array type and are interchangeable.

Why it matters: Confusing these can cause unnecessary complexity or errors when reading or writing TypeScript code.

Quick: Can you assign a read-only array to a normal array variable without error? Commit to yes or no.

Common Belief: You can freely assign read-only arrays to normal arrays and vice versa.

Reality: You can assign normal arrays to read-only array variables, but not the other way around, to prevent unsafe mutations.

Why it matters: Misunderstanding this can cause type errors or unsafe code that breaks immutability guarantees.

Quick: Do methods like 'map' or 'filter' modify read-only arrays? Commit to yes or no.

Common Belief: All array methods are blocked on read-only arrays.

Reality: Non-mutating methods like 'map' and 'filter' are allowed and return new arrays; only mutating methods are blocked.

Why it matters: Knowing this helps you use read-only arrays effectively without confusion or unnecessary workarounds.

Expert Zone

1

Read-only arrays are a compile-time construct only; runtime code can still mutate arrays if type safety is bypassed.

2

Assigning a normal array to a read-only array variable is safe because it only restricts usage, but the original array can still be mutated elsewhere.

3

Readonly arrays do not guarantee deep immutability; objects inside the array can still be changed unless they are also marked readonly.

When NOT to use

Avoid read-only arrays when you need to modify the array after creation, such as adding or removing items dynamically. Instead, use normal arrays or immutable data structures from libraries like Immutable.js for deep immutability.

Production Patterns

In production, read-only arrays are often used in API parameters to signal that functions should not modify input data. They are also used in Redux state management to enforce immutability and prevent accidental state changes.

Connections

Immutable data structures

Read-only arrays are a simple form of immutability, while immutable data structures provide deeper guarantees.

Understanding read-only arrays helps grasp the basics of immutability, which is crucial for working with complex immutable data libraries.

Functional programming

Functional programming emphasizes immutability and pure functions, which align with using read-only arrays.

Knowing read-only arrays supports writing safer, side-effect-free functions common in functional programming.

Access control in security

Read-only arrays enforce 'read-only' access at the type level, similar to how security systems restrict write permissions.

Recognizing this connection shows how programming concepts mirror real-world access control principles to protect data.

Common Pitfalls

#1 Trying to modify a read-only array directly causes errors.

Wrong approach:

const arr: readonly number[] = [1, 2, 3];
arr.push(4); // Error: Property 'push' does not exist on type 'readonly number[]'.

Correct approach:

const arr: readonly number[] = [1, 2, 3];
const newArr = [...arr, 4]; // Create a new array instead

Root cause:

Misunderstanding that read-only arrays cannot be changed and expecting normal array methods to work.

#2 Assuming read-only arrays prevent runtime changes.

Wrong approach:

const arr: readonly number[] = [1, 2, 3];
(arr as number[]).push(4); // No compile error, but mutates array

Correct approach:

Avoid casting away readonly; use immutable patterns or libraries to enforce runtime immutability.

Root cause:

Confusing compile-time type safety with runtime behavior.

#3 Assigning a read-only array to a normal array variable causes errors.

Wrong approach:

const roArr: readonly number[] = [1, 2, 3];
const normalArr: number[] = roArr; // Error

Correct approach:

const roArr: readonly number[] = [1, 2, 3];
const normalArr: readonly number[] = roArr; // Allowed
// Or copy: const normalArr2 = [...roArr];

Root cause:

Not understanding TypeScript's assignment rules for readonly types.

Key Takeaways

Read-only arrays in TypeScript prevent changes to arrays at compile time, helping keep data safe and predictable.

They are declared using 'readonly T[]' or 'ReadonlyArray', both meaning the same thing.

Read-only arrays allow non-mutating methods like 'map' and 'filter' but block mutating methods like 'push' and 'pop'.

The immutability is only enforced by the TypeScript compiler, not at runtime, so care is needed to avoid unsafe mutations.

Understanding read-only arrays is a stepping stone to mastering immutability and safer programming patterns.