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. ```mermaid flowchart LR A("Developer marks array readonly") --> B("Nested objects mutate silently") B --> C("Production bug surfaces") style C stroke:#ef4444,fill:#450a0a,color:#fca5a5 ``` 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. ```mermaid flowchart LR A("Developer marks array readonly") --> B("Enforce readonly at every layer") B --> C("Type system blocks mutations") style C stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` ## Key Takeaways - TypeScript's `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` and `readonly T[]` are functionally identical; prefer the latter for brevity in variable declarations and the former in generic constraints where clarity matters. - Type widening during function calls strips `readonly` from literals unless you use `as const` assertions or explicit type annotations, creating silent vulnerabilities. - Deep immutability requires recursive `DeepReadonly` utility types or `as const` assertions, both of which impose ergonomic and inference costs that don't always justify the safety gain. - The tradeoff between `readonly` strictness and developer ergonomics depends on domain risk—financial calculations demand it, UI component props rarely need it. ## Understanding readonly Arrays: ReadonlyArray vs readonly T[] TypeScript provides two syntaxes for readonly arrays: `ReadonlyArray` 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` 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. ```typescript // Both prevent mutation methods const numbersA: readonly number[] = [1, 2, 3]; const numbersB: ReadonlyArray = [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. ```mermaid flowchart TD A("readonly modifier applied") --> B("Array structure operations blocked") A --> C("Element read operations allowed") B --> D("push, pop, splice rejected") C --> E("Index access, length permitted") style D stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style E stroke:#7c9cf0,fill:#142544,color:#eaf2ff ``` 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. ## Readonly Tuples: Fixed Structure with Immutability Guarantees 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. ```typescript // 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. ```typescript // 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 Shallow Trap: Why readonly Doesn't Protect Nested Objects 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. ```typescript 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. ```mermaid flowchart LR A("readonly array declared") --> B("Array structure protected") A --> C("Nested objects mutable") C --> D("Silent mutation bug") style D stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 ``` The implication here is that readonly arrays of objects require a second layer of protection. You need to make the object properties themselves readonly. ```typescript 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. ## When readonly Fights You: Type Widening and Function Parameter Hell 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. ```typescript 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. ```mermaid flowchart LR A("readonly array literal") --> B("Function expects mutable") B --> C("Type error blocks call") C --> D("Developer removes readonly or casts") style D stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 ``` 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. ```typescript 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. ## Deep Immutability Patterns: DeepReadonly and const Assertions 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. ```typescript type DeepReadonly = { readonly [P in keyof T]: T[P] extends (infer U)[] ? readonly DeepReadonly[] : T[P] extends object ? DeepReadonly : T[P]; }; interface NestedConfig { database: { host: string; port: number; credentials: { username: string; password: string; }; }; features: string[]; } const config: DeepReadonly = { 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. ```typescript // 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. ## Real-World Tradeoffs: Performance, Ergonomics, and When to Skip readonly 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. ```mermaid flowchart LR A("Choose readonly strategy") --> B{Domain risk} B -->|High| C("Full readonly enforcement") B -->|Medium| D("Shallow readonly") B -->|Low| E("Skip readonly") C --> F("Configuration, financial data") D --> G("API responses, cache entries") E --> H("Temporary UI state") style C stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style E stroke:#7c9cf0,fill:#142544,color:#eaf2ff ``` 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:** - Application configuration objects that should never mutate after initialization - Financial calculations where mutating intermediate values creates audit failures - State snapshots for undo/redo systems where preserving history is critical - API contracts where mutation breaks the protocol **Medium-risk domains where shallow readonly is sufficient:** - API response objects where you read values but don't need deep immutability - Cache entries where the cache key is readonly but the value can be mutable - Event logs where the log entry structure is readonly but individual fields can be processed **Low-risk domains where readonly adds no value:** - Temporary UI component state that changes every render - Builder patterns where mutation is the intended API - Internal implementation details of a module where mutation is controlled 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. ## Frequently Asked Questions ### Does readonly prevent all mutations in TypeScript? 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. ### Should I use ReadonlyArray or readonly T[] syntax? Both are functionally identical and compile to the same code. Use `readonly T[]` for brevity in variable declarations and return types. Use `ReadonlyArray` in generic constraints or interface definitions where you want to emphasize that the type itself enforces immutability. ### When should I use as const instead of readonly? 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. ### Does readonly have any runtime performance cost? 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. ### How do I pass a readonly array to a function that expects a mutable array? 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. ## Conclusion 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.

Posts tagged “arrays”

TypeScript readonly Arrays and Tuples: When Immutability Saves You and When It Fights You