readonly في TypeScript: الخصائص و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> نوع أداة يعلّم كل خصائص T كـ readonly. وهو مفيد للقيم التي تمررها ولا يجب أن تتغير، مثل حالة التطبيق:

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 تعيد حالة جديدة بدلًا من تغيير القديمة، ويُلزم المترجم الدالة بذلك. ويُعرَّف 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 في الحسبان عندما تتحقق من توافق نوعي كائن؛ يقول دليل 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.