Docs ejecutables de TypeScript: readonly y Readonly

Q: ¿Qué hace readonly en TypeScript?

readonly marca una propiedad que se puede asignar al crear el objeto (o en el constructor de una clase) pero no reasignar después. Asignarle un valor más tarde es un error de compilación, TS2540. Es solo una comprobación de tipos: el JavaScript generado no contiene ninguna protección.

Q: ¿Qué diferencia hay entre readonly y const en TypeScript?

const tiene que ver con una variable: el nombre no puede apuntar a otro valor, pero el objeto que contiene se puede seguir cambiando. readonly tiene que ver con una propiedad: esa propiedad no se puede reasignar. const user = { name: "Ada" } sigue permitiendo user.name = "x"; una propiedad readonly name no.

Q: ¿Cómo hago un array readonly en TypeScript?

Anótalo como readonly T[] o ReadonlyArray (es el mismo tipo). Los métodos que modifican, como push, pop, sort y splice, desaparecen del tipo, y asignar por índice es un error. Los métodos que no modifican, como map, filter y slice, siguen funcionando y devuelven arrays normales.

Q: ¿Readonly es profundo en TypeScript?

No. Readonly y readonly solo protegen las propiedades del primer nivel; los objetos y arrays anidados se pueden seguir cambiando. Usa as const sobre un literal, o escribe un tipo recursivo DeepReadonly , para tener protección profunda a nivel de tipos.

readonly marca una propiedad que se puede asignar una vez, al crear el objeto, y nunca reasignar. Readonly<T> lo aplica a todas las propiedades de un tipo, y readonly T[] hace lo mismo con los 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 }

La última línea muestra lo más importante de readonly: lo comprueba el compilador, no se hace cumplir en ejecución. La asignación era un error de compilación (aquí suprimido con @ts-expect-error), y aun así el JavaScript generado la ejecutó. Sin la supresión, el archivo no compilaría, y ahí es donde readonly hace su trabajo.

Propiedades readonly

Pon readonly delante del nombre de una propiedad en una interfaz, en un tipo literal o en una clase. La propiedad se puede inicializar pero no reasignar:

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 }

En una clase, un campo readonly se puede asignar en su declaración o en el constructor, y en ningún otro sitio. La forma más corta es una parameter property, constructor(readonly id: string) {}, que declara y asigna el campo en un solo paso. La página de clases trata los campos y los constructores en general.

Readonly<T>: todas las propiedades a la vez

Readonly<T> es un utility type que marca todas las propiedades de T como readonly. Es útil para valores que pasas de un sitio a otro pero que no se deben cambiar, como el estado de una aplicación:

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 de la función le dice a quien la lee que addItem devuelve un estado nuevo en lugar de cambiar el anterior, y el compilador obliga a la función a cumplirlo. Readonly<T> se define como el mapped type { readonly [P in keyof T]: T[P] }.

Arrays readonly: readonly T[] y ReadonlyArray<T>

readonly number[] y ReadonlyArray<number> son el mismo tipo. Quitan todos los métodos que modifican (push, pop, shift, splice, sort, reverse, fill...) y prohíben la asignación por índice. Los métodos que no modifican se mantienen y devuelven arrays normales:

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)

Recibir readonly T[] como parámetro es una promesa a quien llama de que no modificarás su array. La otra dirección es donde la gente se atasca: un array readonly no se puede pasar a una función que recibe un T[] normal, porque esa función podría 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 solución es cambiar sum para que acepte readonly number[], ya que no modifica nada. Las funciones que solo leen un array deberían recibir siempre el tipo readonly; así aceptan los dos tipos de array. Si la función no es tuya, pásale una copia: sum([...prices]).

ReadonlyMap y ReadonlySet

Los Maps y los sets también tienen versiones readonly. ReadonlyMap<K, V> tiene get, has, size, forEach y los iteradores, pero no set, delete ni clear; ReadonlySet<T> no tiene add, 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);

Es habitual que una clase guarde un Map privado modificable y lo exponga mediante un getter tipado como ReadonlyMap, para que el código de fuera pueda leer los datos pero no cambiarlos a través de esa referencia.

readonly es superficial

readonly y Readonly<T> solo protegen la propiedad en sí, no el objeto o el array al que apunta:

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> se aplica a sí mismo sobre cada tipo objeto anidado y, como un mapped type sobre un tipo array produce un array readonly, members pasa a ser readonly string[]. Sigue siendo una promesa a nivel de tipos, no una protección en ejecución.

Solo en compilación: cambios a través de otra referencia

Un tipo readonly controla lo que puede hacer una referencia. Otra referencia al mismo objeto, tipada sin readonly, puede cambiarlo, y TypeScript incluso permite asignar un tipo readonly a uno modificable:

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

La asignación mutable = settings compila porque TypeScript no tiene en cuenta las propiedades readonly al comprobar si dos tipos objeto son compatibles; el handbook de TypeScript lo dice directamente, y señala que por eso las propiedades readonly pueden cambiar a través de alias. Con los arrays readonly es distinto: el error TS4104 de antes es justamente esa comprobación. Object.freeze sí impide cambios en ejecución: el código generado se ejecuta en modo estricto, donde escribir en una propiedad congelada lanza un TypeError. Igual que readonly, Object.freeze es superficial.

readonly, const, as const y Object.freeze

as const sobre un literal hace readonly todas las propiedades a cualquier profundidad y conserva los tipos literales, y a menudo es la forma más fácil de conseguir un valor readonly en profundidad:

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

	Se aplica a	¿Profundo?	Efecto en ejecución	Ejemplo
`const`	la asignación de una variable	no	la variable no se puede reasignar	`const user = {...}`
`readonly`	una propiedad o un tipo array	no	ninguno	`readonly id: string`
`Readonly<T>`	todas las propiedades de un tipo	no	ninguno	`Readonly<State>`
`as const`	una expresión literal	sí	ninguno	`{ ... } as const`
`Object.freeze`	un valor objeto	no	las escrituras fallan (lanzan un error en modo estricto)	`Object.freeze(obj)`

const y readonly responden a preguntas distintas: const impide que el nombre apunte a otro sitio, readonly impide que una propiedad cambie. Las propiedades de un objeto const se pueden seguir reasignando salvo que sean readonly.

Preguntas frecuentes

¿Qué hace readonly en TypeScript?

readonly marca una propiedad que se puede asignar al crear el objeto (o en el constructor de una clase) pero no reasignar después. Asignarle un valor más tarde es un error de compilación, TS2540. Es solo una comprobación de tipos: el JavaScript generado no contiene ninguna protección.

¿Qué diferencia hay entre readonly y const en TypeScript?

const tiene que ver con una variable: el nombre no puede apuntar a otro valor, pero el objeto que contiene se puede seguir cambiando. readonly tiene que ver con una propiedad: esa propiedad no se puede reasignar. const user = { name: "Ada" } sigue permitiendo user.name = "x"; una propiedad readonly name no.

¿Cómo hago un array readonly en TypeScript?

Anótalo como readonly T[] o ReadonlyArray<T> (es el mismo tipo). Los métodos que modifican, como push, pop, sort y splice, desaparecen del tipo, y asignar por índice es un error. Los métodos que no modifican, como map, filter y slice, siguen funcionando y devuelven arrays normales.

¿Readonly es profundo en TypeScript?

No. Readonly<T> y readonly solo protegen las propiedades del primer nivel; los objetos y arrays anidados se pueden seguir cambiando. Usa as const sobre un literal, o escribe un tipo recursivo DeepReadonly<T>, para tener protección profunda a nivel de tipos.

¿readonly impide cambios en tiempo de ejecución?

No. Los tipos se borran, así que en ejecución una propiedad readonly es una propiedad normal, y el código con una referencia modificable al mismo objeto (o JavaScript normal) puede cambiarla. Usa Object.freeze cuando necesites protección en ejecución; TypeScript tipa su resultado como Readonly<T>.

Conceptos relacionados