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.

Practice

1. What does a readonly array in TypeScript do?

easy

A. Only prevents changing the array length

B. Allows adding new elements but not removing existing ones

C. Makes the array elements optional

D. Prevents any changes to the array elements after creation

Solution

1. Step 1: Understand the readonly keyword

   The readonly keyword before an array type means the array cannot be changed after it is created.

2. Step 2: Effects on the array

   This means you cannot add, remove, or modify elements in the array once it is set.

3. Final Answer:

   Prevents any changes to the array elements after creation -> Option D

4. Quick Check:

   readonly arrays are immutable [OK]

Hint: Readonly arrays block all changes to elements [OK]

Common Mistakes:

• Thinking readonly only blocks length changes
• Assuming elements can be modified individually
• Confusing readonly with optional elements

2. Which of the following is the correct syntax to declare a read-only array of numbers in TypeScript?

easy

A. let nums: readonly number[] = [1, 2, 3];

B. let nums: number[] readonly = [1, 2, 3];

C. let nums: number readonly[] = [1, 2, 3];

D. let nums: number[] = readonly [1, 2, 3];

Solution

1. Step 1: Recall the correct readonly syntax

   In TypeScript, readonly comes before the array type, like readonly number[].

2. Step 2: Check each option

   let nums: readonly number[] = [1, 2, 3]; uses readonly number[], which is correct syntax. Others place readonly incorrectly.

3. Final Answer:

   let nums: readonly number[] = [1, 2, 3]; -> Option A

4. Quick Check:

   readonly before type [OK]

Hint: Put readonly before the array type, not after [OK]

Common Mistakes:

• Placing readonly after the array brackets
• Using readonly as a variable modifier
• Trying to put readonly inside the array literal

3. What will be the output of this TypeScript code?

const arr: readonly string[] = ['a', 'b', 'c'];
// arr.push('d');
console.log(arr.length);

medium

A. 4

B. undefined

C. 3

D. Error: Property 'push' does not exist on type 'readonly string[]'

Solution

1. Step 1: Understand the array declaration

   The array arr is declared as readonly string[] with 3 elements: 'a', 'b', 'c'.

2. Step 2: Check the commented out push and output

   The push line is commented out, so it does not run. The length remains 3.

3. Final Answer:

   3 -> Option C

4. Quick Check:

   Readonly array length unchanged = 3 [OK]

Hint: Commented push means length stays same [OK]

Common Mistakes:

• Assuming push works on readonly arrays
• Expecting length to increase despite push commented
• Confusing runtime errors with compile-time errors

4. Identify the error in this TypeScript code using a read-only array:

const nums: readonly number[] = [1, 2, 3];
nums[0] = 10;

medium

A. Type 'number' is not assignable to type 'readonly number[]'

B. Cannot assign to '0' because it is a read-only property

C. Syntax error: missing semicolon

D. No error, code runs fine

Solution

1. Step 1: Understand the readonly array behavior

   The array nums is readonly, so its elements cannot be changed after creation.

2. Step 2: Analyze the assignment to an element

   Trying to assign nums[0] = 10 causes an error because elements are read-only.

3. Final Answer:

   Cannot assign to '0' because it is a read-only property -> Option B

4. Quick Check:

   Readonly elements cannot be changed [OK]

Hint: Readonly arrays block element assignment [OK]

Common Mistakes:

• Thinking only array structure is readonly, not elements
• Ignoring TypeScript error messages
• Assuming semicolon missing causes error

5. Given a function that accepts a read-only array, which of these operations inside the function is allowed?

function process(items: readonly number[]) {
  // Which line is valid?
  // A) items.push(5);
  // B) items[0] = 10;
  // C) const first = items[0];
  // D) items.length = 0;
}

hard

A. const first = items[0];

B. items.push(5);

C. items[0] = 10;

D. items.length = 0;

Solution

1. Step 1: Understand read-only array restrictions

   Read-only arrays do not allow modifying methods like push, element assignment, or length changes.

2. Step 2: Check each operation

   Only reading elements, like const first = items[0];, is allowed. Others cause errors.

3. Final Answer:

   const first = items[0]; -> Option A

4. Quick Check:

   Reading elements allowed, modifying disallowed [OK]

Hint: Readonly arrays allow reading, not modifying [OK]

Common Mistakes:

• Trying to push or assign elements in readonly arrays
• Attempting to change array length
• Confusing read-only with mutable arrays