TypeScript Reference ยท Keywords and Declarations
TypeScript readonly modifier
Reference for the TypeScript readonly modifier: read-only properties, readonly arrays and tuples, the Readonly<T> utility, shallow behavior and as const.
readonly tells the compiler that a property may be set only when the object is created, never reassigned afterwards. It applies to class fields, interface and type properties, index signatures, and, as a type operator, to arrays and tuples (readonly string[], readonly [number, number]).
It is a compile-time check. Nothing is frozen at runtime, and the restriction is shallow: a readonly property holding an object still lets you change that object's own fields.
interface Point { readonly x: number; readonly y: number; } const names: readonly string[] = ["a", "b"];
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
readonly prop: Type; // property in class, interface, type literal readonly [key: string]: Type; // index signature readonly T[] / ReadonlyArray<T> // array readonly [A, B] // tuple Readonly<T> // all properties of T made readonly
| Form | Effect |
|---|---|
readonly prop |
Assignment is allowed only in the declaring class's constructor or in the field initializer. |
readonly T[] |
Removes mutating methods (push, pop, splice, sort, index assignment) from the type. |
readonly [A, B] |
A tuple whose elements cannot be reassigned. |
Readonly<T> |
Mapped type that adds readonly to every property of T (one level deep). |
as const |
Infers literal types and makes arrays, tuples and object properties readonly, deeply. |
Errors
- Assigning to a read-only property: error TS2540 ("Cannot assign to 'x' because it is a read-only property").
- Calling a mutating method on a read-only array: error TS2339 (the method does not exist on the readonly type).
- Assigning
readonly string[]tostring[]: error TS4104. readonlyon a local variable or parameter is not allowed; useconstfor variables.
Usage notes
- Shallow. Combine
Readonly<T>recursively (a customDeepReadonly) oras constwhen you need depth. - Assignability gap. A
readonlyproperty is assignable to a mutable one.{ readonly x: number }can be passed where{ x: number }is expected, because TypeScript does not treat readonly as part of identity. This is a known unsoundness. - Defensive APIs. Accept
readonly T[]in parameters when you do not mutate. Callers can pass either kind of array. ReadonlyArray<T>,ReadonlyMap,ReadonlySetare the library types for collections without mutators.constvsreadonly.constfixes a variable binding;readonlyfixes a property.const list = []can still be pushed to.- Parameter properties may carry it:
constructor(readonly id: number). - Runtime protection. Use
Object.freezeif you need real immutability; its typing returnsReadonly<T>. - Mapped type modifiers.
-readonlyremoves it,+readonlyadds it.