TypeScript readonly: מאפיינים, Readonly<T> ומערכים

readonly מסמן מאפיין שאפשר לקבוע פעם אחת, כשהאובייקט נוצר, ואף פעם לא לבצע לו השמה מחדש. Readonly<T> מחיל אותו על כל מאפיין של טיפוס, ו-readonly T[] עושה אותו דבר למערכים:

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 }

השורה האחרונה מראה את העובדה החשובה ביותר על readonly: הקומפיילר בודק אותו, אבל הוא לא נאכף בזמן ריצה. ההשמה הייתה שגיאת קומפילציה (שהושתקה כאן עם @ts-expect-error), ובכל זאת ה-JavaScript שנוצר הריץ אותה. בלי ההשתקה, הקובץ לא היה עובר קומפילציה, ושם readonly עושה את העבודה שלו.

מאפייני readonly

כתבו readonly לפני שם מאפיין ב-interface, בליטרל טיפוס או במחלקה. אפשר לאתחל את המאפיין, אבל אי אפשר לבצע לו השמה מחדש:

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 }

במחלקה, אפשר לבצע השמה לשדה readonly בהצהרה שלו או בבנאי, ובשום מקום אחר. הצורה הקצרה ביותר היא parameter property, constructor(readonly id: string) {}, שמצהירה על השדה ומבצעת לו השמה בצעד אחד. דף המחלקות מכסה שדות ובנאים באופן כללי.

Readonly<T>: כל המאפיינים בבת אחת

Readonly<T> הוא utility type שמסמן כל מאפיין של T כ-readonly. הוא שימושי לערכים שמעבירים ממקום למקום אבל אסור לשנות, כמו state של אפליקציה:

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 }

חתימת הפונקציה אומרת לקורא ש-addItem מחזירה state חדש במקום לשנות את הישן, והקומפיילר מחזיק את הפונקציה להבטחה הזו. Readonly<T> מוגדר כ-mapped type { readonly [P in keyof T]: T[P] }.

מערכים לקריאה בלבד: readonly T[] ו-ReadonlyArray<T>

readonly number[] ו-ReadonlyArray<number> הם אותו טיפוס. הם מסירים כל מתודה משנה (push, pop, shift, splice, sort, reverse, fill...) ואוסרים השמה לפי אינדקס. המתודות שלא משנות נשארות ומחזירות מערכים רגילים:

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)

קבלת readonly T[] כפרמטר היא הבטחה למי שקורא לפונקציה שלא תשנו את המערך שלו. הכיוון השני הוא המקום שבו אנשים נתקעים: אי אפשר להעביר מערך לקריאה בלבד לפונקציה שמקבלת T[] רגיל, כי הפונקציה הזו עלולה לשנות אותו.

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

הפתרון הוא לשנות את sum כך שתקבל readonly number[], כי היא לא משנה כלום. פונקציות שרק קוראות מערך צריכות תמיד לקבל את הטיפוס לקריאה בלבד; כך הן מקבלות את שני הסוגים. אם הפונקציה לא שלכם, העבירו עותק: sum([...prices]).

ReadonlyMap ו-ReadonlySet

גם ל-Maps ול-sets יש גרסאות לקריאה בלבד. ל-ReadonlyMap<K, V> יש get, has, size, forEach והאיטרטורים, אבל אין set, delete או clear; ל-ReadonlySet<T> אין add, delete או 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);

מחלקה לרוב שומרת Map פרטי שניתן לשינוי וחושפת אותו דרך getter מטיפוס ReadonlyMap, כך שקוד חיצוני יכול לקרוא את הנתונים אבל לא לשנות אותם דרך ההפניה הזו.

readonly הוא רדוד

readonly ו-Readonly<T> מגנים רק על המאפיין עצמו, ולא על האובייקט או המערך שהוא מצביע עליו:

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> מפעיל את עצמו על כל טיפוס אובייקט מקונן, ומכיוון ש-mapped type על טיפוס מערך מייצר מערך לקריאה בלבד, members הופך ל-readonly string[]. זו עדיין הבטחה ברמת הטיפוסים, ולא הגנה בזמן ריצה.

רק בזמן קומפילציה: שינוי דרך הפניה אחרת

טיפוס לקריאה בלבד שולט במה שהפניה אחת רשאית לעשות. הפניה אחרת לאותו אובייקט, בלי readonly בטיפוס שלה, יכולה לשנות אותו, ו-TypeScript אפילו מתיר לשייך טיפוס לקריאה בלבד לטיפוס שניתן לשינוי:

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

ההשמה mutable = settings עוברת קומפילציה כי TypeScript לא מתחשב במאפייני readonly כשהוא בודק אם שני טיפוסי אובייקט תואמים; ה-handbook של TypeScript אומר זאת במפורש, ומציין שלכן מאפייני readonly יכולים להשתנות דרך aliasing. מערכים לקריאה בלבד שונים: שגיאת TS4104 שלמעלה היא בדיוק הבדיקה הזו. Object.freeze באמת מונע שינויים בזמן ריצה: הקוד שנוצר רץ ב-strict mode, שבו כתיבה למאפיין מוקפא זורקת TypeError. כמו readonly, גם Object.freeze רדוד.

readonly, const, as const ו-Object.freeze

as const על ליטרל הופך כל מאפיין ל-readonly בכל עומק ושומר על טיפוסים ליטרליים, ולרוב זו הדרך הקלה ביותר לקבל ערך שהוא לקריאה בלבד לעומק:

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

const ו-readonly עונים על שאלות שונות: const מונע מהשם להצביע למקום אחר, readonly מונע ממאפיין להשתנות. למאפיינים של אובייקט const עדיין אפשר לבצע השמה מחדש, אלא אם הם readonly.