readonly di TypeScript: Property, Readonly<T> dan Array

readonly menandai property yang hanya boleh diisi sekali, saat object dibuat, dan tidak pernah di-assign ulang. Readonly<T> menerapkannya ke setiap property sebuah tipe, dan readonly T[] melakukan hal yang sama untuk 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 }

Baris terakhir menunjukkan fakta terpenting tentang readonly: ia dicek oleh compiler, bukan ditegakkan saat runtime. Assignment itu adalah error kompilasi (diredam di sini dengan @ts-expect-error), tetapi JavaScript yang dihasilkan tetap menjalankannya. Tanpa peredaman itu, file-nya tidak akan lolos kompilasi, dan di situlah readonly menjalankan tugasnya.

Property readonly

Taruh readonly sebelum nama property di interface, type literal, atau class. Property itu boleh diinisialisasi, tetapi tidak boleh di-assign ulang:

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 }

Di class, field readonly boleh di-assign di deklarasinya atau di constructor, dan tidak di tempat lain. Bentuk paling singkatnya adalah parameter property, constructor(readonly id: string) {}, yang mendeklarasikan dan meng-assign field dalam satu langkah. Halaman class membahas field dan constructor secara umum.

Readonly<T>: Semua Property Sekaligus

Readonly<T> adalah utility type yang menandai setiap property T sebagai readonly. Tipe ini berguna untuk nilai yang kamu teruskan ke mana-mana tetapi tidak boleh diubah, seperti state aplikasi:

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 }

Signature fungsinya memberi tahu pembaca bahwa addItem mengembalikan state baru alih-alih mengubah yang lama, dan compiler memastikan fungsinya menepati janji itu. Readonly<T> didefinisikan sebagai mapped type { readonly [P in keyof T]: T[P] }.

Array Readonly: readonly T[] dan ReadonlyArray<T>

readonly number[] dan ReadonlyArray<number> adalah tipe yang sama. Keduanya menghapus setiap method yang mengubah isi (push, pop, shift, splice, sort, reverse, fill...) dan melarang assignment lewat index. Method yang tidak mengubah isi tetap ada dan mengembalikan array biasa:

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)

Menerima readonly T[] sebagai parameter adalah janji kepada pemanggil bahwa kamu tidak akan mengubah array mereka. Arah sebaliknya yang sering membuat orang bingung: array readonly tidak bisa dikirim ke fungsi yang menerima T[] biasa, karena fungsi itu mungkin mengubah isinya.

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

Perbaikannya adalah mengubah sum supaya menerima readonly number[], karena fungsi itu tidak mengubah apa pun. Fungsi yang hanya membaca array sebaiknya selalu menerima tipe readonly; dengan begitu ia menerima kedua jenis array. Kalau fungsinya bukan milikmu, kirim salinannya: sum([...prices]).

ReadonlyMap dan ReadonlySet

Map dan set juga punya versi readonly. ReadonlyMap<K, V> punya get, has, size, forEach dan iterator, tetapi tidak punya set, delete atau clear; ReadonlySet<T> tidak punya add, delete atau 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);

Sebuah class sering menyimpan Map private yang mutable dan mengeksposnya lewat getter bertipe ReadonlyMap, sehingga kode di luar bisa membaca datanya tetapi tidak bisa mengubahnya lewat referensi itu.

readonly Bersifat Dangkal

readonly dan Readonly<T> hanya melindungi property itu sendiri, bukan object atau array yang dirujuknya:

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> menerapkan dirinya sendiri ke setiap object type yang bersarang, dan karena mapped type atas tipe array menghasilkan array readonly, members menjadi readonly string[]. Ini tetap janji di level tipe, bukan perlindungan saat runtime.

Hanya Saat Kompilasi: Perubahan Lewat Referensi Lain

Tipe readonly mengatur apa yang boleh dilakukan oleh satu referensi. Referensi lain ke object yang sama, yang bertipe tanpa readonly, bisa mengubahnya, dan TypeScript bahkan mengizinkan tipe readonly di-assign ke tipe yang mutable:

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

Assignment mutable = settings lolos kompilasi karena TypeScript tidak memperhitungkan property readonly saat mengecek apakah dua object type kompatibel; TypeScript handbook menyatakannya secara langsung, dan mencatat bahwa property readonly karena itu bisa berubah lewat aliasing. Array readonly berbeda: error TS4104 di atas adalah pengecekan itu. Object.freeze benar-benar mencegah perubahan saat runtime: kode yang dihasilkan berjalan dalam strict mode, dan di sana menulis ke property yang dibekukan akan melempar TypeError. Seperti readonly, Object.freeze juga dangkal.

readonly, const, as const dan Object.freeze

as const pada literal membuat setiap property menjadi readonly di setiap kedalaman dan mempertahankan literal type, yang sering menjadi cara termudah untuk mendapatkan nilai yang readonly secara mendalam:

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

const dan readonly menjawab pertanyaan yang berbeda: const mencegah nama itu menunjuk ke tempat lain, readonly mencegah sebuah property berubah. Property dari object const tetap bisa di-assign ulang kecuali property itu readonly.