TypeScript readonly: Eigenschaften, Readonly<T> und Arrays

readonly markiert eine Eigenschaft, die einmal gesetzt werden kann, beim Erzeugen des Objekts, und nie neu zugewiesen wird. Readonly<T> wendet das auf jede Eigenschaft eines Typs an, und readonly T[] tut dasselbe für Arrays:

interface Point {
  readonly x: number;
  readonly y: number;
}

const origin: Point = { x: 0, y: 0 };
// @ts-expect-error: Cannot assign to 'x' because it is a read-only property
origin.x = 5;

const config: Readonly<{ host: string; port: number }> = { host: "localhost", port: 8080 };
const ports: readonly number[] = [80, 443];

console.log(config.host, ports.length); // localhost 2
console.log(origin);                    // { x: 5, y: 0 }

Die letzte Zeile zeigt das Wichtigste an readonly: Der Compiler prüft es, zur Laufzeit wird es nicht durchgesetzt. Die Zuweisung war ein Compilerfehler (hier mit @ts-expect-error unterdrückt), und trotzdem hat das erzeugte JavaScript sie ausgeführt. Ohne die Unterdrückung würde die Datei nicht kompilieren, und genau dort erledigt readonly seine Aufgabe.

readonly-Eigenschaften

Setze readonly vor einen Eigenschaftsnamen in einem Interface, einem Typliteral oder einer Klasse. Die Eigenschaft kann initialisiert, aber nicht neu zugewiesen werden:

class Invoice {
  readonly id: string;
  readonly createdAt = "2024-03-15";
  total = 0;

  constructor(id: string) {
    this.id = id; // allowed: the constructor may initialize readonly fields
  }

  add(amount: number) {
    this.total += amount; // fine: total is not readonly
    // this.id = "x" would be error TS2540: Cannot assign to 'id' because it is a read-only property.
  }
}

const inv = new Invoice("INV-7");
inv.add(19.5);
console.log(inv); // Invoice { id: 'INV-7', createdAt: '2024-03-15', total: 19.5 }

In einer Klasse kann ein readonly-Feld in seiner Deklaration oder im Konstruktor zugewiesen werden, sonst nirgends. Die kürzeste Form ist eine Parameter Property, constructor(readonly id: string) {}, die das Feld in einem Schritt deklariert und zuweist. Die Seite zu Klassen behandelt Felder und Konstruktoren allgemein.

Readonly<T>: jede Eigenschaft auf einmal

Readonly<T> ist ein Utility Type, der jede Eigenschaft von T als readonly markiert. Das ist nützlich für Werte, die du weitergibst, die aber nicht verändert werden sollen, etwa den Zustand einer Anwendung:

interface State {
  user: string;
  cart: string[];
  total: number;
}

function addItem(state: Readonly<State>, item: string, price: number): State {
  // state.total += price would be error TS2540
  return { ...state, cart: [...state.cart, item], total: state.total + price };
}

const s0: State = { user: "ada", cart: [], total: 0 };
const s1 = addItem(s0, "book", 12);
const s2 = addItem(s1, "pen", 2);

console.log(s0.cart, s2); // [] { user: 'ada', cart: [ 'book', 'pen' ], total: 14 }

Die Signatur der Funktion sagt dem Leser, dass addItem einen neuen Zustand zurückgibt, statt den alten zu ändern, und der Compiler hält die Funktion daran fest. Readonly<T> ist als der Mapped Type { readonly [P in keyof T]: T[P] } definiert.

Readonly-Arrays: readonly T[] und ReadonlyArray<T>

readonly number[] und ReadonlyArray<number> sind derselbe Typ. Sie entfernen jede verändernde Methode (push, pop, shift, splice, sort, reverse, fill...) und verbieten die Zuweisung per Index. Die nicht verändernden Methoden bleiben und geben gewöhnliche Arrays zurück:

const scores: readonly number[] = [42, 7, 19];

const doubled = scores.map((s) => s * 2);        // number[] (a new, mutable array)
const sorted = [...scores].sort((a, b) => a - b); // copy first, then sort the copy
const top = scores.slice(0, 2);

// @ts-expect-error: Property 'push' does not exist on type 'readonly number[]'
scores.push(1);

console.log(doubled, sorted, top); // [ 84, 14, 38 ] [ 7, 19, 42 ] [ 42, 7 ]
console.log(scores);               // [ 42, 7, 19, 1 ]  (push ran: types are erased)

Wenn du readonly T[] als Parameter nimmst, versprichst du Aufrufern, ihr Array nicht zu verändern. In der anderen Richtung bleiben viele hängen: Ein readonly-Array lässt sich nicht an eine Funktion übergeben, die ein einfaches T[] nimmt, weil diese Funktion es verändern könnte.

// This does not compile: a readonly array cannot go where a mutable one is expected
function sum(values: number[]): number {
  return values.reduce((a, b) => a + b, 0);
}

const prices: readonly number[] = [3, 4, 5];
console.log(sum(prices));

index.ts(7,17): error TS4104: The type 'readonly number[]' is 'readonly' and cannot be assigned to the mutable type 'number[]'.

Die Lösung ist, sum so zu ändern, dass es readonly number[] akzeptiert, weil es nichts verändert. Funktionen, die ein Array nur lesen, sollten immer den readonly-Typ nehmen; dann akzeptieren sie beide Arten. Gehört dir die Funktion nicht, übergib eine Kopie: sum([...prices]).

ReadonlyMap und ReadonlySet

Auch Maps und Sets haben readonly-Versionen. ReadonlyMap<K, V> hat get, has, size, forEach und die Iteratoren, aber kein set, delete oder clear; ReadonlySet<T> hat kein add, delete oder clear:

const prices: ReadonlyMap<string, number> = new Map([
  ["tea", 2.5],
  ["coffee", 3.2],
]);
const admins: ReadonlySet<string> = new Set(["ada"]);

console.log(prices.get("tea"), prices.size, admins.has("ada")); // 2.5 2 true

// @ts-expect-error: Property 'set' does not exist on type 'ReadonlyMap<string, number>'
prices.set("juice", 4);

Eine Klasse hält oft eine private, veränderbare Map und gibt sie über einen Getter vom Typ ReadonlyMap nach außen, sodass äußerer Code die Daten lesen, aber über diese Referenz nicht ändern kann.

readonly ist flach

readonly und Readonly<T> schützen nur die Eigenschaft selbst, nicht das Objekt oder Array, auf das sie zeigt:

interface Team {
  readonly name: string;
  readonly members: string[];
  readonly lead: { name: string };
}

const team: Readonly<Team> = { name: "Core", members: ["ada"], lead: { name: "ada" } };

team.members.push("linus"); // allowed: the array itself is not readonly
team.lead.name = "linus";   // allowed: only the lead property is readonly
// team.members = [] would be error TS2540

console.log(team); // { name: 'Core', members: [ 'ada', 'linus' ], lead: { name: 'linus' } }

type DeepReadonly<T> = T extends (...args: any[]) => unknown ? T
  : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
  : T;

const frozenTeam: DeepReadonly<Team> = team;
// @ts-expect-error: Property 'push' does not exist on type 'readonly string[]'
frozenTeam.members.push("grace");

DeepReadonly<T> wendet sich selbst auf jeden verschachtelten Objekttyp an, und weil ein Mapped Type über einen Array-Typ ein readonly-Array erzeugt, wird members zu readonly string[]. Es bleibt ein Versprechen auf Typebene, kein Schutz zur Laufzeit.

Nur beim Kompilieren: Änderungen über eine andere Referenz

Ein readonly-Typ steuert, was eine Referenz tun darf. Eine andere Referenz auf dasselbe Objekt, ohne readonly typisiert, kann es ändern, und TypeScript erlaubt sogar, einen readonly-Typ einem veränderbaren zuzuweisen:

interface Settings {
  readonly theme: string;
}

const settings: Settings = { theme: "dark" };
const mutable: { theme: string } = settings; // allowed, no error
mutable.theme = "light";

console.log(settings.theme); // light

// Runtime protection needs Object.freeze
const locked = Object.freeze({ theme: "dark" }); // typed Readonly<{ theme: "dark" }>
try {
  (locked as { theme: string }).theme = "light";
} catch (e) {
  console.log((e as Error).name); // TypeError
}
console.log(locked.theme); // dark

Die Zuweisung mutable = settings kompiliert, weil TypeScript readonly-Eigenschaften nicht berücksichtigt, wenn es prüft, ob zwei Objekttypen kompatibel sind; das TypeScript-Handbuch sagt das ausdrücklich und weist darauf hin, dass sich readonly-Eigenschaften deshalb über Aliasing ändern können. Bei readonly-Arrays ist das anders: Der Fehler TS4104 oben ist genau diese Prüfung. Object.freeze verhindert Änderungen wirklich zur Laufzeit: Der erzeugte Code läuft im Strict Mode, in dem das Schreiben auf eine eingefrorene Eigenschaft einen TypeError wirft. Wie readonly ist Object.freeze flach.

readonly, const, as const und Object.freeze

as const bei einem Literal macht jede Eigenschaft auf jeder Ebene readonly und behält Literaltypen, und das ist oft der einfachste Weg zu einem tief schreibgeschützten Wert:

const theme = { mode: "dark", sizes: [12, 14] } as const;
// { readonly mode: "dark"; readonly sizes: readonly [12, 14] }

const und readonly beantworten verschiedene Fragen: const verhindert, dass der Name woandershin zeigt, readonly verhindert, dass sich eine Eigenschaft ändert. Die Eigenschaften eines const-Objekts lassen sich weiterhin neu zuweisen, solange sie nicht readonly sind.