readonly
Arrays and Tuples: When Immutability Saves You and When It Fights You
This article was written with the assistance of AI, under human supervision and review.
Most readonly bugs stem from misunderstanding what the type actually prevents. Developers mark an array readonly
, ship it to production, and discover that nested objects still mutate freely—or that function parameters reject their readonly values entirely. The failure mode here is subtle but expensive: you get type safety where you don't need it and vulnerability where you do.
The problem isn't that readonly
is broken. The problem is that teams treat it as a deep immutability guarantee when TypeScript enforces it only at the surface. This creates a false sense of security that explodes during code review or, worse, at runtime.
The correct pattern requires understanding three layers: what readonly
actually protects, where type widening sabotages you, and when deep immutability patterns justify their cost. Apply these correctly and your type system catches mutation bugs before deployment. Skip them and you're debugging object reference issues in production.
readonly
modifier prevents reassignment and mutation methods on arrays and tuples, but only at the first level—nested objects remain mutable unless explicitly typed.ReadonlyArray<T>
and readonly T[]
are functionally identical; prefer the latter for brevity in variable declarations and the former in generic constraints where clarity matters.readonly
from literals unless you use as const
assertions or explicit type annotations, creating silent vulnerabilities.DeepReadonly
utility types or as const
assertions, both of which impose ergonomic and inference costs that don't always justify the safety gain.readonly
strictness and developer ergonomics depends on domain risk—financial calculations demand it, UI component props rarely need it.TypeScript provides two syntaxes for readonly arrays: ReadonlyArray<T>
and readonly T[]
. Both compile to identical runtime code and impose the same compile-time restrictions. The distinction is purely ergonomic.
The readonly T[]
syntax mirrors the standard array syntax with a modifier prefix. This makes it readable in variable declarations and return types. The ReadonlyArray<T>
form communicates intent more clearly in generic constraints and interface definitions where you want to emphasize that the type itself is readonly, not just a specific instance.
// Both prevent mutation methods
const numbersA: readonly number[] = [1, 2, 3];
const numbersB: ReadonlyArray<number> = [1, 2, 3];
// Both compile-time errors
numbersA.push(4); // Error: Property 'push' does not exist
numbersB[0] = 99; // Error: Index signature only permits reading
// Both allow reading
const first = numbersA[0]; // Valid: 1
const length = numbersB.length; // Valid: 3
The type system strips mutation methods (push
, pop
, shift
, unshift
, splice
, sort
, reverse
) from the readonly interface. Index access for reading remains available, but index assignment is forbidden. This creates a type-level guarantee that the array structure cannot change.
The failure mode appears when developers assume readonly
prevents all changes. It doesn't. It prevents changes to the array container, not changes within the contained values. This distinction is critical.
The implication here is that readonly
works best for primitive arrays where individual elements can't be mutated anyway. For object arrays, you need a second layer of protection.
Tuples in TypeScript represent fixed-length arrays with specific types at each index. Adding readonly
to a tuple locks both the structure and the individual element assignments.
// Mutable tuple
type Config = [string, number, boolean];
const config: Config = ["production", 8080, true];
config[0] = "staging"; // Valid mutation
config.push("extra"); // Error: Tuple length is 3
// Readonly tuple
type ReadonlyConfig = readonly [string, number, boolean];
const readonlyConfig: ReadonlyConfig = ["production", 8080, true];
readonlyConfig[0] = "staging"; // Error: Cannot assign to readonly index
readonlyConfig.push("extra"); // Error: Property 'push' does not exist
The readonly tuple pattern provides stronger guarantees than readonly arrays because the type system enforces both the expected structure and element immutability. This makes readonly tuples ideal for function return values where you want to communicate both "this has exactly three elements" and "you cannot modify them."
The real-world application appears in React hooks. The useState
hook returns a readonly tuple [state, setState]
to prevent accidental reassignment of the setter function. Without readonly, developers could inadvertently write state[1] = someOtherFunction
, breaking the state update mechanism.
// Practical readonly tuple for coordinate pairs
type Coordinate = readonly [x: number, y: number];
function calculateDistance(a: Coordinate, b: Coordinate): number {
// Cannot accidentally mutate the input coordinates
const dx = b[0] - a[0];
const dy = b[1] - a[1];
return Math.sqrt(dx * dx + dy * dy);
}
const origin: Coordinate = [0, 0];
const point: Coordinate = [3, 4];
const distance = calculateDistance(origin, point); // 5
The pattern scales to labeled tuples where you want named access without creating a full object interface. This provides tuple structure with object-like documentation at the type level.
The most expensive readonly misconception is that it provides deep immutability. It doesn't. TypeScript's readonly
modifier is shallow—it prevents mutation of the array container but not the objects inside it.
interface User {
id: string;
name: string;
permissions: string[];
}
const users: readonly User[] = [
{ id: "1", name: "Alice", permissions: ["read"] },
{ id: "2", name: "Bob", permissions: ["read", "write"] }
];
// This is blocked (good)
users.push({ id: "3", name: "Charlie", permissions: [] }); // Error
// This is allowed (bad)
users[0].name = "Alicia"; // Valid mutation
users[1].permissions.push("admin"); // Valid mutation
The readonly modifier only prevents reassignment of array indices and structural operations like push
. The objects at each index remain fully mutable. This matters because the type system gives you a false positive—it says "this is readonly" while half the data structure is still vulnerable.
The implication here is that readonly arrays of objects require a second layer of protection. You need to make the object properties themselves readonly.
interface ReadonlyUser {
readonly id: string;
readonly name: string;
readonly permissions: readonly string[];
}
const users: readonly ReadonlyUser[] = [
{ id: "1", name: "Alice", permissions: ["read"] },
{ id: "2", name: "Bob", permissions: ["read", "write"] }
];
// Now all mutations are blocked
users[0].name = "Alicia"; // Error: Cannot assign to readonly property
users[1].permissions.push("admin"); // Error: Property 'push' does not exist
This pattern works but introduces ergonomic cost. Every interface in your type hierarchy needs explicit readonly
annotations. For deep object graphs, this becomes verbose quickly.
The tradeoff is between safety and maintainability. If the data structure is critical—configuration objects, financial records, audit logs—the verbosity pays for itself. If you're protecting UI component props that change every render, the cost exceeds the benefit.
TypeScript's type widening strips readonly
from literal arrays during function calls unless you explicitly prevent it. This creates a silent mismatch where your readonly array becomes mutable the moment it crosses a function boundary.
function processItems(items: string[]): void {
items.push("extra"); // Mutates the input
}
const tags = ["typescript", "readonly"] as const;
processItems(tags); // Error: readonly string[] not assignable to string[]
The type system correctly rejects this because processItems
expects a mutable array and you're passing a readonly one. The frustration comes from the opposite direction—when you want to pass a readonly array to a function that shouldn't mutate it but declares a mutable parameter anyway.
The correct solution is to declare function parameters as readonly when they don't need mutation rights. This communicates intent and accepts both mutable and readonly arrays.
function processItems(items: readonly string[]): void {
// Can read but not mutate
console.log(items.length);
// items.push("extra"); // Error: Property 'push' does not exist
}
const tags = ["typescript", "readonly"] as const;
processItems(tags); // Valid
processItems(["javascript", "node"]); // Also valid
The failure mode appears in third-party library types. If a library function declares items: string[]
instead of items: readonly string[]
, you're forced to either cast away readonly or copy the array. Both options defeat the type safety you wanted.
The pragmatic approach is to annotate your own function parameters as readonly and accept that external libraries may require workarounds. The type system can't protect you from someone else's API design.
When shallow readonly isn't enough, TypeScript provides two patterns for deep immutability: recursive utility types and as const
assertions.
A DeepReadonly
utility type applies readonly recursively to every property and nested array in an object graph.
type DeepReadonly<T> = {
readonly [P in keyof T]: T[P] extends (infer U)[]
? readonly DeepReadonly<U>[]
: T[P] extends object
? DeepReadonly<T[P]>
: T[P];
};
interface NestedConfig {
database: {
host: string;
port: number;
credentials: {
username: string;
password: string;
};
};
features: string[];
}
const config: DeepReadonly<NestedConfig> = {
database: {
host: "localhost",
port: 5432,
credentials: {
username: "admin",
password: "secret"
}
},
features: ["auth", "logging"]
};
// All levels are now readonly
config.database.host = "remote"; // Error
config.database.credentials.password = "new"; // Error
config.features.push("metrics"); // Error
This pattern provides true immutability guarantees at the cost of type complexity. The DeepReadonly
type is recursive and can degrade inference performance on large object graphs. Use it for configuration objects and domain models where mutation is never valid.
The as const
assertion provides a simpler alternative for literal values. It infers the narrowest possible type with readonly applied at every level.
// Without as const
const configA = {
timeout: 5000,
retries: [1, 2, 5, 10]
};
// Type: { timeout: number; retries: number[]; }
// With as const
const configB = {
timeout: 5000,
retries: [1, 2, 5, 10]
} as const;
// Type: { readonly timeout: 5000; readonly retries: readonly [1, 2, 5, 10]; }
The as const
approach locks everything down—both the object properties and the array elements become literal types. This creates the strongest possible immutability guarantee but also the least flexible type. You can't assign a variable to a property that expects the literal 5000
if that variable is typed as number
.
The tradeoff is between type narrowing and reusability. Use as const
for configuration constants that truly never change. Use DeepReadonly
for data structures where you need immutability with normal type flexibility.
The decision to use readonly involves three competing concerns: type safety, developer ergonomics, and runtime performance.
TypeScript's readonly modifier has zero runtime cost. It exists only at compile time and compiles away completely. The performance consideration is type-checking speed, not execution speed. Deep readonly types with complex recursion can slow down the type checker on large codebases, but the impact is usually negligible until you hit hundreds of deeply nested types.
The ergonomic cost comes from annotation burden and type compatibility issues. Every function that accepts a readonly parameter needs the annotation. Every interface needs explicit readonly properties. This verbosity compounds in large codebases where readonly spreads virally—once you mark one type readonly, every type that touches it needs the same treatment to avoid type errors.
The practical approach is to apply readonly based on domain risk, not as a blanket policy.
High-risk domains where readonly pays for itself:
Medium-risk domains where shallow readonly is sufficient:
Low-risk domains where readonly adds no value:
The failure mode is cargo-culting readonly everywhere because "immutability is good." That's true in principle but counterproductive when the annotation burden exceeds the safety benefit. The goal is to prevent bugs that matter, not to achieve 100% readonly coverage.
When you do use readonly, document why that specific data structure requires immutability. If you can't articulate the mutation risk you're preventing, you probably don't need readonly there.
No—readonly
only prevents mutations at the level where it's applied. For arrays, it blocks structural operations like push
and index assignment, but nested objects remain fully mutable unless their properties are also marked readonly. This shallow enforcement is the most common source of readonly bugs.
Both are functionally identical and compile to the same code. Use readonly T[]
for brevity in variable declarations and return types. Use ReadonlyArray<T>
in generic constraints or interface definitions where you want to emphasize that the type itself enforces immutability.
Use as const
for literal values where you want the narrowest possible type with deep immutability. Use explicit readonly
annotations when you need immutability with normal type flexibility—for example, when a function parameter should accept any readonly array, not just a specific literal.
No—readonly
is a compile-time-only feature that disappears during compilation. The only performance consideration is type-checking speed for complex recursive readonly types, which rarely matters unless you have hundreds of deeply nested structures.
You either change the function signature to accept readonly T[]
(correct solution) or cast away readonly using as T[]
(pragmatic workaround for third-party APIs). Copying the array works but defeats the purpose of the immutability guarantee and adds runtime cost.
TypeScript's readonly modifier prevents array mutations at compile time, but only when developers understand its shallow enforcement and type widening behavior. The pattern works for primitive arrays and tuples without extra effort. For nested objects, it requires recursive readonly types or const assertions, both of which impose ergonomic costs that don't always justify the safety gain.
The tradeoff between readonly strictness and developer productivity depends on domain risk. Financial calculations and configuration objects demand deep immutability. UI component props and temporary state rarely need it. The failure mode is treating readonly as a universal best practice instead of a targeted tool.
Apply readonly where mutation creates real consequences—data corruption, audit failures, protocol violations. Skip it where the annotation burden exceeds the risk. That distinction separates codebases with meaningful type safety from codebases with readonly everywhere and bugs anyway.
That covers the essential patterns for TypeScript readonly arrays and tuples. Apply these in production and the difference will be immediate.