Skip to content
Tutorials Center
My learning

Topics

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.

TypeScript
interface Point {
  readonly x: number;
  readonly y: number;
}
const names: readonly string[] = ["a", "b"];

Try it

TypeScript Readonly properties and arrays

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.

TypeScript Things readonly forbids

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

TypeScript
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[] to string[]: error TS4104.
  • readonly on a local variable or parameter is not allowed; use const for variables.

Usage notes

  • Shallow. Combine Readonly<T> recursively (a custom DeepReadonly) or as const when you need depth.
  • Assignability gap. A readonly property 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, ReadonlySet are the library types for collections without mutators.
  • const vs readonly. const fixes a variable binding; readonly fixes a property. const list = [] can still be pushed to.
  • Parameter properties may carry it: constructor(readonly id: number).
  • Runtime protection. Use Object.freeze if you need real immutability; its typing returns Readonly<T>.
  • Mapped type modifiers. -readonly removes it, +readonly adds it.