Guida TypeScript interattiva: readonly e Readonly

Q: Cosa fa readonly in TypeScript?

readonly segna una proprietà che si può impostare quando l'oggetto viene creato (o nel costruttore di una classe) ma non riassegnare in seguito. Assegnarle un valore dopo è un errore di compilazione, TS2540. È solo un controllo dei tipi: il JavaScript generato non contiene alcuna protezione.

Q: Che differenza c'è tra readonly e const in TypeScript?

const riguarda una variabile: il nome non può puntare a un altro valore, ma l'oggetto che contiene si può ancora modificare. readonly riguarda una proprietà: quella proprietà non si può riassegnare. const user = { name: "Ada" } permette ancora user.name = "x"; una proprietà readonly name no.

Q: Come rendo readonly un array in TypeScript?

Annotalo come readonly T[] o ReadonlyArray (è lo stesso tipo). I metodi che modificano, come push, pop, sort e splice, spariscono dal tipo, e l'assegnazione tramite indice è un errore. I metodi che non modificano, come map, filter e slice, continuano a funzionare e restituiscono array normali.

Q: Readonly è profondo in TypeScript?

No. Readonly e readonly proteggono solo le proprietà di primo livello; gli oggetti e gli array annidati si possono ancora modificare. Usa as const su un letterale, oppure scrivi un tipo ricorsivo DeepReadonly , per una protezione profonda a livello di tipi.

readonly segna una proprietà che si può impostare una sola volta, quando l'oggetto viene creato, e che non viene mai riassegnata. Readonly<T> lo applica a tutte le proprietà di un tipo, e readonly T[] fa lo stesso per gli array:

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 }

L'ultima riga mostra il fatto più importante su readonly: viene controllato dal compilatore, non imposto in fase di esecuzione. L'assegnazione era un errore di compilazione (qui soppresso con @ts-expect-error), eppure il JavaScript generato l'ha eseguita lo stesso. Senza la soppressione, il file non compilerebbe, ed è lì che readonly fa il suo lavoro.

Proprietà readonly

Metti readonly prima del nome di una proprietà in un'interfaccia, in un tipo letterale o in una classe. La proprietà si può inizializzare ma non riassegnare:

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 una classe, un campo readonly si può assegnare nella sua dichiarazione o nel costruttore, e da nessun'altra parte. La forma più breve è una parameter property, constructor(readonly id: string) {}, che dichiara e assegna il campo in un solo passo. La pagina sulle classi tratta campi e costruttori in generale.

Readonly<T>: tutte le proprietà in un colpo solo

Readonly<T> è un utility type che segna tutte le proprietà di T come readonly. È utile per valori che passi in giro ma che non dovrebbero cambiare, come lo stato dell'applicazione:

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 firma della funzione dice a chi legge che addItem restituisce un nuovo stato invece di modificare quello vecchio, e il compilatore obbliga la funzione a rispettarlo. Readonly<T> è definito come il mapped type { readonly [P in keyof T]: T[P] }.

Array readonly: readonly T[] e ReadonlyArray<T>

readonly number[] e ReadonlyArray<number> sono lo stesso tipo. Tolgono tutti i metodi che modificano (push, pop, shift, splice, sort, reverse, fill...) e vietano l'assegnazione tramite indice. I metodi che non modificano restano e restituiscono array normali:

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)

Accettare readonly T[] come parametro è una promessa a chi chiama che non modificherai il suo array. È nella direzione opposta che ci si blocca: un array readonly non si può passare a una funzione che accetta un semplice T[], perché quella funzione potrebbe modificarlo.

// 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 soluzione è cambiare sum perché accetti readonly number[], dato che non modifica nulla. Le funzioni che si limitano a leggere un array dovrebbero sempre accettare il tipo readonly; così accettano entrambi i tipi di array. Se la funzione non è tua, passa una copia: sum([...prices]).

ReadonlyMap e ReadonlySet

Anche le Map e i Set hanno versioni readonly. ReadonlyMap<K, V> ha get, has, size, forEach e gli iteratori ma non set, delete o clear; ReadonlySet<T> non ha add, delete o 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);

Spesso una classe tiene una Map privata modificabile e la espone tramite un getter tipizzato ReadonlyMap, così il codice esterno può leggere i dati ma non modificarli tramite quel riferimento.

readonly è superficiale

readonly e Readonly<T> proteggono solo la proprietà in sé, non l'oggetto o l'array a cui punta:

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> si applica a ogni tipo oggetto annidato, e dato che un mapped type su un tipo array produce un array readonly, members diventa readonly string[]. Resta comunque una promessa a livello di tipi, non una protezione in fase di esecuzione.

Solo in compilazione: modifiche tramite un altro riferimento

Un tipo readonly controlla cosa può fare un riferimento. Un altro riferimento allo stesso oggetto, tipizzato senza readonly, può modificarlo, e TypeScript permette persino di assegnare un tipo readonly a uno modificabile:

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'assegnazione mutable = settings compila perché TypeScript non tiene conto delle proprietà readonly quando controlla se due tipi oggetto sono compatibili; il manuale di TypeScript lo dice esplicitamente, e osserva che le proprietà readonly possono quindi cambiare tramite aliasing. Gli array readonly sono diversi: l'errore TS4104 visto sopra è esattamente quel controllo. Object.freeze impedisce davvero le modifiche in fase di esecuzione: il codice generato gira in strict mode, dove scrivere su una proprietà congelata lancia un TypeError. Come readonly, anche Object.freeze è superficiale.

readonly, const, as const e Object.freeze

as const su un letterale rende readonly ogni proprietà a ogni livello e mantiene i tipi letterali, ed è spesso il modo più facile per ottenere un valore readonly in profondità:

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

	Si applica a	Profondo?	Effetto in esecuzione	Esempio
`const`	un binding di variabile	no	la variabile non si può riassegnare	`const user = {...}`
`readonly`	una proprietà o un tipo array	no	nessuno	`readonly id: string`
`Readonly<T>`	tutte le proprietà di un tipo	no	nessuno	`Readonly<State>`
`as const`	un'espressione letterale	sì	nessuno	`{ ... } as const`
`Object.freeze`	un valore oggetto	no	le scritture falliscono (lanciano in strict mode)	`Object.freeze(obj)`

const e readonly rispondono a domande diverse: const impedisce al nome di puntare altrove, readonly impedisce a una proprietà di cambiare. Le proprietà di un oggetto const si possono ancora riassegnare, a meno che non siano readonly.

Domande frequenti

Cosa fa readonly in TypeScript?

readonly segna una proprietà che si può impostare quando l'oggetto viene creato (o nel costruttore di una classe) ma non riassegnare in seguito. Assegnarle un valore dopo è un errore di compilazione, TS2540. È solo un controllo dei tipi: il JavaScript generato non contiene alcuna protezione.

Che differenza c'è tra readonly e const in TypeScript?

const riguarda una variabile: il nome non può puntare a un altro valore, ma l'oggetto che contiene si può ancora modificare. readonly riguarda una proprietà: quella proprietà non si può riassegnare. const user = { name: "Ada" } permette ancora user.name = "x"; una proprietà readonly name no.

Come rendo readonly un array in TypeScript?

Annotalo come readonly T[] o ReadonlyArray<T> (è lo stesso tipo). I metodi che modificano, come push, pop, sort e splice, spariscono dal tipo, e l'assegnazione tramite indice è un errore. I metodi che non modificano, come map, filter e slice, continuano a funzionare e restituiscono array normali.

Readonly è profondo in TypeScript?

No. Readonly<T> e readonly proteggono solo le proprietà di primo livello; gli oggetti e gli array annidati si possono ancora modificare. Usa as const su un letterale, oppure scrivi un tipo ricorsivo DeepReadonly<T>, per una protezione profonda a livello di tipi.

readonly impedisce le modifiche in fase di esecuzione?

No. I tipi vengono cancellati, quindi in esecuzione una proprietà readonly è una proprietà normale, e il codice con un riferimento modificabile allo stesso oggetto (o JavaScript puro) può ancora cambiarla. Usa Object.freeze quando ti serve una protezione in esecuzione; TypeScript tipizza il suo risultato come Readonly<T>.

Concetti correlati