Docs TypeScript exécutables : readonly et Readonly

Q: À quoi sert readonly en TypeScript ?

readonly marque une propriété qui peut être définie à la création de l'objet (ou dans le constructeur d'une classe) mais pas réaffectée ensuite. L'affecter plus tard est une erreur de compilation, TS2540. Ce n'est qu'une vérification de types : le JavaScript émis ne contient aucune protection.

Q: Quelle est la différence entre readonly et const en TypeScript ?

const concerne une variable : le nom ne peut pas pointer vers une autre valeur, mais l'objet qu'il contient peut toujours être modifié. readonly concerne une propriété : cette propriété ne peut pas être réaffectée. const user = { name: "Ada" } autorise encore user.name = "x" ; une propriété readonly name non.

Q: Comment rendre un tableau readonly en TypeScript ?

Annotez-le comme readonly T[] ou ReadonlyArray (c'est le même type). Les méthodes qui modifient le tableau, comme push, pop, sort et splice, disparaissent du type, et l'affectation par index est une erreur. Les méthodes qui ne modifient rien, comme map, filter et slice, fonctionnent toujours et renvoient des tableaux ordinaires.

Q: Readonly est-il profond en TypeScript ?

Non. Readonly et readonly ne protègent que les propriétés de premier niveau ; les objets et tableaux imbriqués peuvent toujours être modifiés. Utilisez as const sur un littéral, ou écrivez un type récursif DeepReadonly , pour une protection profonde au niveau des types.

Q: readonly empêche-t-il les modifications à l'exécution ?

Non. Les types sont effacés, donc une propriété readonly est une propriété ordinaire à l'exécution, et du code disposant d'une référence modifiable au même objet (ou du JavaScript pur) peut encore la changer. Utilisez Object.freeze quand vous avez besoin d'une protection à l'exécution ; TypeScript type son résultat comme Readonly .

readonly marque une propriété qui peut être définie une fois, à la création de l'objet, et jamais réaffectée. Readonly<T> l'applique à toutes les propriétés d'un type, et readonly T[] fait de même pour les tableaux :

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 }

La dernière ligne montre le fait le plus important à propos de readonly : il est vérifié par le compilateur, pas imposé à l'exécution. L'affectation était une erreur de compilation (supprimée ici avec @ts-expect-error), et pourtant le JavaScript émis l'a exécutée. Sans la suppression, le fichier ne compilerait pas, et c'est là que readonly fait son travail.

Propriétés readonly

Placez readonly devant le nom d'une propriété dans une interface, un type littéral ou une classe. La propriété peut être initialisée mais pas réaffectée :

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 }

Dans une classe, un champ readonly peut être affecté dans sa déclaration ou dans le constructeur, et nulle part ailleurs. La forme la plus courte est une propriété de paramètre, constructor(readonly id: string) {}, qui déclare et affecte le champ en une seule étape. La page sur les classes couvre les champs et les constructeurs en général.

Readonly<T> : toutes les propriétés d'un coup

Readonly<T> est un utility type qui marque toutes les propriétés de T comme readonly. Il est utile pour des valeurs que l'on fait circuler sans devoir les modifier, comme l'état d'une application :

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 }

La signature de la fonction indique au lecteur que addItem renvoie un nouvel état au lieu de modifier l'ancien, et le compilateur oblige la fonction à tenir cette promesse. Readonly<T> est défini comme le mapped type { readonly [P in keyof T]: T[P] }.

Tableaux readonly : readonly T[] et ReadonlyArray<T>

readonly number[] et ReadonlyArray<number> sont le même type. Ils retirent toutes les méthodes qui modifient le tableau (push, pop, shift, splice, sort, reverse, fill...) et interdisent l'affectation par index. Les méthodes qui ne modifient rien restent et renvoient des tableaux ordinaires :

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)

Prendre un readonly T[] en paramètre est une promesse faite aux appelants : vous ne modifierez pas leur tableau. C'est dans l'autre sens que l'on bloque : un tableau readonly ne peut pas être passé à une fonction qui prend un T[] simple, car cette fonction pourrait le modifier.

// 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[]'.

La solution est de faire accepter readonly number[] à sum, puisqu'elle ne modifie rien. Une fonction qui ne fait que lire un tableau devrait toujours prendre le type readonly ; elle accepte alors les deux sortes de tableaux. Si la fonction ne vous appartient pas, passez une copie : sum([...prices]).

ReadonlyMap et ReadonlySet

Les Maps et les sets ont aussi des versions readonly. ReadonlyMap<K, V> possède get, has, size, forEach et les itérateurs, mais pas set, delete ni clear ; ReadonlySet<T> n'a ni add, ni delete, ni 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);

Une classe garde souvent une Map privée modifiable et l'expose via un getter typé ReadonlyMap, pour que le code extérieur puisse lire les données sans pouvoir les modifier par cette référence.

readonly est superficiel

readonly et Readonly<T> ne protègent que la propriété elle-même, pas l'objet ou le tableau vers lequel elle pointe :

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> s'applique à chaque type objet imbriqué, et comme un mapped type appliqué à un type tableau produit un tableau readonly, members devient readonly string[]. Cela reste une promesse au niveau des types, pas une protection à l'exécution.

Seulement à la compilation : la mutation par une autre référence

Un type readonly contrôle ce qu'une référence a le droit de faire. Une autre référence au même objet, typée sans readonly, peut le modifier, et TypeScript autorise même à affecter un type readonly à un type modifiable :

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

L'affectation mutable = settings compile parce que TypeScript ne tient pas compte des propriétés readonly quand il vérifie si deux types objets sont compatibles ; le handbook TypeScript le dit explicitement, et précise que des propriétés readonly peuvent donc changer par aliasing. Les tableaux readonly sont différents : l'erreur TS4104 plus haut est précisément cette vérification. Object.freeze empêche vraiment les modifications à l'exécution : le code émis tourne en mode strict, où écrire dans une propriété gelée lève une TypeError. Comme readonly, Object.freeze est superficiel.

readonly, const, as const et Object.freeze

as const sur un littéral rend toutes les propriétés readonly à toutes les profondeurs et conserve les types littéraux, ce qui est souvent le moyen le plus simple d'obtenir une valeur profondément readonly :

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

	S'applique à	Profond ?	Effet à l'exécution	Exemple
`const`	une liaison de variable	non	la variable ne peut pas être réaffectée	`const user = {...}`
`readonly`	une propriété ou un type tableau	non	aucun	`readonly id: string`
`Readonly<T>`	toutes les propriétés d'un type	non	aucun	`Readonly<State>`
`as const`	une expression littérale	oui	aucun	`{ ... } as const`
`Object.freeze`	une valeur objet	non	les écritures échouent (exception en mode strict)	`Object.freeze(obj)`

const et readonly répondent à des questions différentes : const empêche le nom de pointer ailleurs, readonly empêche une propriété de changer. Les propriétés d'un objet const peuvent toujours être réaffectées, sauf si elles sont readonly.

Questions fréquentes

À quoi sert readonly en TypeScript ?

readonly marque une propriété qui peut être définie à la création de l'objet (ou dans le constructeur d'une classe) mais pas réaffectée ensuite. L'affecter plus tard est une erreur de compilation, TS2540. Ce n'est qu'une vérification de types : le JavaScript émis ne contient aucune protection.

Quelle est la différence entre readonly et const en TypeScript ?

const concerne une variable : le nom ne peut pas pointer vers une autre valeur, mais l'objet qu'il contient peut toujours être modifié. readonly concerne une propriété : cette propriété ne peut pas être réaffectée. const user = { name: "Ada" } autorise encore user.name = "x" ; une propriété readonly name non.

Comment rendre un tableau readonly en TypeScript ?

Annotez-le comme readonly T[] ou ReadonlyArray<T> (c'est le même type). Les méthodes qui modifient le tableau, comme push, pop, sort et splice, disparaissent du type, et l'affectation par index est une erreur. Les méthodes qui ne modifient rien, comme map, filter et slice, fonctionnent toujours et renvoient des tableaux ordinaires.

Readonly est-il profond en TypeScript ?

Non. Readonly<T> et readonly ne protègent que les propriétés de premier niveau ; les objets et tableaux imbriqués peuvent toujours être modifiés. Utilisez as const sur un littéral, ou écrivez un type récursif DeepReadonly<T>, pour une protection profonde au niveau des types.

readonly empêche-t-il les modifications à l'exécution ?

Non. Les types sont effacés, donc une propriété readonly est une propriété ordinaire à l'exécution, et du code disposant d'une référence modifiable au même objet (ou du JavaScript pur) peut encore la changer. Utilisez Object.freeze quand vous avez besoin d'une protection à l'exécution ; TypeScript type son résultat comme Readonly<T>.

Concepts liés