Literal type và as const trong TypeScript, kèm ví dụ

Literal type là kiểu chỉ có đúng một giá trị: "up" là kiểu có thành viên duy nhất là chuỗi "up", và 404 là kiểu có thành viên duy nhất là số 404. Đứng riêng thì chúng không hữu ích lắm. Khi ghép thành union, chúng cho bạn một biến chỉ nhận một tập giá trị cố định và không gì khác.

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);

Nếu không có chú thích @ts-expect-error, lời gọi cuối cùng là lỗi biên dịch (TS2345). Có chú thích đó, chương trình biên dịch được, lời gọi vẫn chạy và in ra moving north by 1: literal type chỉ tồn tại với trình biên dịch, còn lúc chạy giá trị là một chuỗi bình thường.

Literal chuỗi, số và boolean

Mọi giá trị chuỗi, số, bigint hay boolean đều có thể viết thành kiểu. Khi đó trình biên dịch chỉ chấp nhận đúng giá trị ấy.

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;

Bản thân boolean chỉ là union true | false, vì vậy khi thu hẹp một boolean bằng if (flag), nhánh else còn lại false.

Union của các literal

Cách dùng phổ biến là một union liệt kê mọi giá trị được phép. Bên trong hàm, trình biên dịch thu hẹp union khi bạn kiểm tra, nên mỗi nhánh biết chính xác nó đang giữ giá trị nào.

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 của các string literal là lựa chọn thay thế enum quen thuộc trong TypeScript. Nó không tốn gì lúc chạy, các giá trị là chuỗi thường mà bạn có thể log ra hay gửi qua JSON, và gõ sai là lỗi biên dịch. Xem thêm về ưu nhược điểm ở trang enum.

Mở rộng kiểu: let và const

Khi TypeScript suy ra kiểu từ một literal, nó xem giá trị có thể thay đổi hay không. Biến const không bao giờ gán lại được, nên giữ literal type. Biến let thì gán lại được, nên kiểu của nó được mở rộng thành kiểu tổng quát.

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

Rê chuột lên từng tên trong trình soạn thảo để xem kiểu được suy ra. Nếu bạn muốn một biến let chỉ giữ một số giá trị nhất định, hãy chú thích kiểu: let mode: "light" | "dark" = "light".

Vì sao thuộc tính của đối tượng bị mở rộng kiểu

Thuộc tính của một object literal có thể thay đổi, nên chúng cũng bị mở rộng kiểu, kể cả khi đối tượng được lưu trong một const. Đây là cách phổ biến nhất để bạn vô tình gặp 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);

Trình biên dịch báo:

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

req được suy ra là { url: string; method: string } vì code phía sau có thể chạy req.method = "DELETE". Có ba cách sửa:

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);

Cách thứ tư là satisfies, vừa kiểm tra đối tượng theo một kiểu vừa giữ literal type cho các thuộc tính.

as const

as const là một const assertion. Đặt nó sau một biểu thức, trình biên dịch sẽ suy ra kiểu hẹp nhất có thể:

• giá trị chuỗi, số và boolean giữ literal type
• thuộc tính của đối tượng thành readonly
• mảng literal thành tuple readonly có độ dài cố định

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 này chỉ có tác dụng lúc biên dịch. JavaScript được sinh ra là chính object literal đó, bỏ đi as const, nên không gì ngăn code khác thay đổi nó lúc chạy. Nếu bạn cần đảm bảo lúc chạy, hãy gọi thêm Object.freeze.

Union type từ một mảng as const

Một mẫu hay gặp là giữ các giá trị được phép trong một mảng, có thể lặp qua lúc chạy, rồi suy ra union type từ mảng đó. (typeof arr)[number] nghĩa là "kiểu của một phần tử bất kỳ trong 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
}

Không có as const, ROLES sẽ là string[] và Role chỉ là string. Phép ép kiểu sang readonly string[] trong isRole là cần thiết vì includes trên tuple các literal chỉ nhận đúng những literal đó, trong khi mục đích của hàm là kiểm tra một chuỗi có thể không thuộc số đó. Mẫu đối tượng tương tự cũng dùng được cho bảng khóa/giá trị: const Status = { Active: "active", Banned: "banned" } as const, rồi type Status = (typeof Status)[keyof typeof Status].

const type parameter

Một hàm generic thường mở rộng kiểu của các literal bạn truyền vào. Từ TypeScript 5.0, bạn có thể đánh dấu một type parameter là const, khiến trình biên dịch suy ra đối số như thể nó có as const, mà không bắt người gọi phải tự viết.

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

Đây chủ yếu là công cụ cho tác giả thư viện: định nghĩa route, builder và các hàm hỗ trợ schema dùng nó để người gọi có kiểu chính xác từ literal thông thường.

Các ý nghĩa của const

Từ khóa const xuất hiện ở bốn chỗ khác nhau trong code TypeScript:

Không cái nào đóng băng đối tượng lúc chạy. const obj = { a: 1 } vẫn cho phép obj.a = 2; chỉ việc gán lại chính obj mới là lỗi.