Literal Type dan as const di TypeScript, dengan Contoh

Literal type adalah tipe yang hanya punya tepat satu nilai: "up" adalah tipe yang satu-satunya member-nya adalah string "up", dan 404 adalah tipe yang satu-satunya member-nya adalah angka 404. Kalau berdiri sendiri, literal type tidak terlalu berguna. Kalau digabung menjadi union, kamu mendapat variabel yang hanya menerima sekumpulan nilai tertentu dan tidak ada yang lain.

type Direction = "up" | "down" | "left" | "right";

function move(dir: Direction, steps: number) {
  console.log(`moving ${dir} by ${steps}`);
}

move("up", 3);
move("left", 1);

// @ts-expect-error: Argument of type '"north"' is not assignable to parameter of type 'Direction'.
move("north", 1);

Tanpa komentar @ts-expect-error, pemanggilan terakhir adalah error saat kompilasi (TS2345). Dengan komentar itu, program lolos kompilasi dan pemanggilan tersebut tetap berjalan serta mencetak moving north by 1: literal type hanya ada untuk compiler, dan saat runtime nilainya adalah string biasa.

Literal String, Angka, dan Boolean

Nilai string, angka, bigint, atau boolean apa pun bisa ditulis sebagai tipe. Compiler lalu hanya menerima nilai yang persis sama.

let method: "GET" = "GET";
let code: 404 = 404;
let ok: true = true;
let big: 10n = 10n;

type Port = 80 | 443 | 8080;
const port: Port = 443;

boolean sendiri hanyalah union true | false, dan karena itulah narrowing sebuah boolean dengan if (flag) menyisakan false di cabang else.

Union dari Literal

Pemakaian yang umum adalah union yang mencantumkan setiap nilai yang diizinkan. Di dalam fungsi, compiler mempersempit union itu seiring pemeriksaanmu, jadi setiap cabang tahu persis nilai mana yang sedang dipegangnya.

type Size = "sm" | "md" | "lg";

function padding(size: Size): number {
  if (size === "sm") return 4;
  if (size === "md") return 8;
  return 16; // size is "lg" here
}

const sizes: Size[] = ["sm", "md", "lg"];
console.log(sizes.map(padding)); // [ 4, 8, 16 ]

Union dari string literal adalah alternatif TypeScript yang umum untuk enum. Ia tidak memakan biaya apa pun saat runtime, nilainya adalah string biasa yang bisa kamu log dan kirim lewat JSON, dan salah ketik menjadi error kompilasi. Untung ruginya dibahas lebih jauh di enum.

Widening: let vs const

Saat TypeScript menyimpulkan tipe dari sebuah literal, ia melihat apakah nilainya bisa berubah. Variabel const tidak pernah bisa di-assign ulang, jadi tipe literalnya dipertahankan. Variabel let bisa, jadi tipenya dilebarkan menjadi tipe yang umum.

const a = "hello"; // type: "hello"
let b = "hello";   // type: string
b = "bye";         // fine, b is a string

const n = 42;      // type: 42
let m = 42;        // type: number

let c = a;         // type: string (copying a literal into a let widens it)

console.log(a, b, n, m, c); // hello bye 42 42 hello

Arahkan kursor ke setiap nama di editor untuk melihat tipe hasil inferensinya. Kalau kamu ingin let yang hanya berisi nilai tertentu, beri anotasi: let mode: "light" | "dark" = "light".

Kenapa Properti Object Dilebarkan

Properti dari object literal bisa diubah, jadi tipenya juga dilebarkan, bahkan ketika object-nya disimpan di const. Inilah cara paling umum orang tidak sengaja berurusan dengan literal type:

// This does not compile: req.method is string, not "GET" | "POST"
function send(url: string, method: "GET" | "POST") {
  console.log(method, url);
}

const req = { url: "/users", method: "GET" };
send(req.url, req.method);

Compiler melaporkan:

index.ts(7,15): error TS2345: Argument of type 'string' is not assignable to parameter of type '"GET" | "POST"'.

req disimpulkan sebagai { url: string; method: string } karena kode di bagian lain bisa saja menjalankan req.method = "DELETE". Ada tiga cara memperbaikinya:

type Method = "GET" | "POST";

function send(url: string, method: Method) {
  console.log(method, url);
}

// 1. Annotate the object (or the property)
const r1: { url: string; method: Method } = { url: "/users", method: "GET" };

// 2. as const on the whole object: every property becomes readonly and literal
const r2 = { url: "/posts", method: "POST" } as const;

// 3. as const on one property only
const r3 = { url: "/tags", method: "GET" as const };

send(r1.url, r1.method);
send(r2.url, r2.method);
send(r3.url, r3.method);

Pilihan keempat adalah satisfies, yang memeriksa object terhadap sebuah tipe sambil mempertahankan tipe literal propertinya.

as const

as const adalah const assertion. Letakkan setelah sebuah ekspresi, dan compiler akan menyimpulkan tipe paling sempit yang bisa didapat:

• nilai string, angka, dan boolean mempertahankan tipe literalnya
• properti object menjadi readonly
• array literal menjadi tuple readonly dengan panjang tetap

const config = {
  env: "production",
  retries: 3,
  hosts: ["a.example.com", "b.example.com"],
} as const;
// type: { readonly env: "production"; readonly retries: 3;
//         readonly hosts: readonly ["a.example.com", "b.example.com"] }

// @ts-expect-error: Cannot assign to 'env' because it is a read-only property.
config.env = "staging";

const point = [3, 4] as const; // type: readonly [3, 4]
const [x, y] = point;
console.log(config.retries, x + y); // 3 7

Assertion ini hanya berlaku saat kompilasi. JavaScript yang dihasilkan adalah object literal yang sama dengan as const dihapus, jadi tidak ada yang mencegah kode lain mengubahnya saat runtime. Kalau kamu butuh jaminan saat runtime, panggil juga Object.freeze.

Union Type dari Array as const

Pola yang sering dipakai adalah menyimpan nilai-nilai yang diizinkan dalam satu array, yang bisa kamu loop saat runtime, lalu menurunkan union type darinya. (typeof arr)[number] berarti "tipe dari elemen mana pun di arr".

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function isRole(value: string): value is Role {
  return (ROLES as readonly string[]).includes(value);
}

for (const input of ["editor", "owner"]) {
  console.log(input, isRole(input)); // editor true, then owner false
}

Tanpa as const, ROLES akan bertipe string[] dan Role hanya string biasa. Cast ke readonly string[] di isRole dibutuhkan karena includes pada tuple berisi literal hanya menerima literal-literal itu, padahal tujuan fungsinya adalah menguji string yang belum tentu salah satunya. Pola yang sama dengan object berlaku untuk map key/value: const Status = { Active: "active", Banned: "banned" } as const, lalu type Status = (typeof Status)[keyof typeof Status].

Parameter Tipe const

Fungsi generic biasanya melebarkan literal yang kamu kirim. Sejak TypeScript 5.0, kamu bisa menandai parameter tipe dengan const, yang membuat compiler menyimpulkan argumen seolah-olah ditulis dengan as const, tanpa meminta pemanggil menuliskannya.

function plain<T>(value: T) {
  return value;
}

function exact<const T>(value: T) {
  return value;
}

const a = plain({ kind: "circle", sizes: [1, 2] });
// type: { kind: string; sizes: number[] }

const b = exact({ kind: "circle", sizes: [1, 2] });
// type: { readonly kind: "circle"; readonly sizes: readonly [1, 2] }

console.log(a.kind === b.kind); // true

Ini terutama alat untuk pembuat library: definisi route, builder, dan helper schema memakainya agar pemanggil mendapat tipe yang presisi dari literal biasa.

Arti-arti const

Kata kunci const muncul di empat tempat yang berbeda di kode TypeScript:

Tidak satu pun dari mereka membekukan object saat runtime. const obj = { a: 1 } tetap mengizinkan obj.a = 2; hanya meng-assign ulang obj itu sendiri yang menjadi error.