readonly trong TypeScript: thuộc tính, Readonly<T> và mảng

readonly đánh dấu một thuộc tính chỉ được đặt một lần, khi tạo object, và không bao giờ bị gán lại. Readonly<T> áp dụng nó cho mọi thuộc tính của một kiểu, và readonly T[] làm điều tương tự cho mảng:

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 }

Dòng cuối cho thấy điều quan trọng nhất về readonly: nó được trình biên dịch kiểm tra, chứ không được thực thi lúc chạy. Phép gán là lỗi biên dịch (ở đây bị chặn thông báo bằng @ts-expect-error), nhưng JavaScript được sinh ra vẫn chạy nó. Nếu không có lệnh chặn, tệp sẽ không biên dịch được, và đó chính là lúc readonly làm đúng việc của nó.

Thuộc tính readonly

Đặt readonly trước tên thuộc tính trong một interface, một type literal hoặc một lớp. Thuộc tính có thể được khởi tạo nhưng không thể gán lại:

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 }

Trong một lớp, trường readonly có thể được gán ngay tại khai báo hoặc trong hàm khởi tạo, và không ở đâu khác. Cách viết ngắn nhất là parameter property, constructor(readonly id: string) {}, vừa khai báo vừa gán trường chỉ trong một bước. Trang lớp (class) trình bày về trường và hàm khởi tạo nói chung.

Readonly<T>: mọi thuộc tính cùng lúc

Readonly<T> là một utility type đánh dấu mọi thuộc tính của T là readonly. Nó hữu ích cho những giá trị bạn truyền đi khắp nơi nhưng không nên thay đổi, như state của ứng dụng:

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 }

Chữ ký hàm cho người đọc biết addItem trả về một state mới thay vì sửa state cũ, và trình biên dịch buộc hàm phải giữ đúng điều đó. Readonly<T> được định nghĩa là mapped type { readonly [P in keyof T]: T[P] }.

Mảng chỉ đọc: readonly T[] và ReadonlyArray<T>

readonly number[] và ReadonlyArray<number> là cùng một kiểu. Chúng loại bỏ mọi phương thức làm thay đổi mảng (push, pop, shift, splice, sort, reverse, fill...) và cấm gán theo chỉ số. Các phương thức không làm thay đổi mảng vẫn còn và trả về mảng thông thường:

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)

Nhận readonly T[] làm tham số là lời cam kết với nơi gọi rằng bạn sẽ không sửa mảng của họ. Chiều ngược lại mới là chỗ nhiều người gặp khó: không thể truyền mảng chỉ đọc vào một hàm nhận T[] thông thường, vì hàm đó có thể làm thay đổi mảng.

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

Cách sửa là đổi sum để nhận readonly number[], vì nó không thay đổi gì cả. Hàm chỉ đọc mảng thì luôn nên nhận kiểu readonly; khi đó nó chấp nhận cả hai loại. Nếu hàm không phải của bạn, hãy truyền một bản sao: sum([...prices]).

ReadonlyMap và ReadonlySet

Map và set cũng có phiên bản chỉ đọc. ReadonlyMap<K, V> có get, has, size, forEach và các iterator nhưng không có set, delete hay clear; ReadonlySet<T> không có add, delete hay 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);

Một lớp thường giữ một Map private có thể thay đổi và công khai nó qua một getter có kiểu ReadonlyMap, để code bên ngoài đọc được dữ liệu nhưng không thay đổi được nó qua tham chiếu đó.

readonly chỉ ở mức nông

readonly và Readonly<T> chỉ bảo vệ bản thân thuộc tính, không bảo vệ object hay mảng mà nó trỏ tới:

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> tự áp dụng lại cho mọi kiểu object lồng bên trong, và vì một mapped type trên kiểu mảng tạo ra mảng chỉ đọc, members trở thành readonly string[]. Đây vẫn chỉ là cam kết ở cấp độ kiểu, không phải bảo vệ lúc chạy.

Chỉ có tác dụng lúc biên dịch: thay đổi qua tham chiếu khác

Một kiểu readonly kiểm soát những gì một tham chiếu được phép làm. Một tham chiếu khác tới cùng object, có kiểu không có readonly, vẫn có thể thay đổi nó, và TypeScript thậm chí cho phép gán một kiểu readonly cho một kiểu có thể thay đổi:

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

Phép gán mutable = settings biên dịch được vì TypeScript không tính đến các thuộc tính readonly khi kiểm tra hai kiểu object có tương thích hay không; TypeScript handbook nói rõ điều này, và lưu ý rằng vì thế thuộc tính readonly có thể bị thay đổi qua aliasing. Mảng chỉ đọc thì khác: lỗi TS4104 ở trên chính là phép kiểm tra đó. Object.freeze thực sự ngăn thay đổi lúc chạy: code được sinh ra chạy ở strict mode, nơi ghi vào một thuộc tính đã bị đóng băng sẽ ném ra TypeError. Giống readonly, Object.freeze cũng chỉ ở mức nông.

readonly, const, as const và Object.freeze

as const trên một literal biến mọi thuộc tính thành readonly ở mọi cấp và giữ nguyên literal type, thường là cách dễ nhất để có một giá trị chỉ đọc ở mọi cấp:

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

const và readonly trả lời hai câu hỏi khác nhau: const ngăn tên biến trỏ sang chỗ khác, readonly ngăn một thuộc tính bị thay đổi. Thuộc tính của một object const vẫn có thể bị gán lại, trừ khi chúng là readonly.