satisfies trong TypeScript: so với chú thích kiểu và as

value satisfies Type kiểm tra lúc biên dịch rằng value khớp với Type, rồi để nguyên kiểu riêng, chính xác hơn, của giá trị đó. Một chú thích kiểu sẽ thay kiểu chính xác đó bằng Type; satisfies kiểm tra mà không mở rộng kiểu.

type ColorName = "red" | "green" | "blue";
type Color = string | [number, number, number];

const palette = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
} satisfies Record<ColorName, Color>;

// Checked against the Record, yet every property keeps its own type:
console.log(palette.green.toUpperCase());      // #00FF00 (green: string)
console.log(palette.red.map((c) => c / 255));  // [ 1, 0, 0 ] (red: [number, number, number])

satisfies vẫn làm phần kiểm tra: thiếu một màu, gõ sai khóa thành bleu, hoặc một giá trị như true đều là lỗi biên dịch ngay trên dòng đó. Nó có từ TypeScript 4.9 và, giống mọi chú thích kiểu, bị xóa khỏi JavaScript được sinh ra.

Vấn đề mà satisfies giải quyết

Với chú thích kiểu, kiểu của biến chính là chú thích đó. Trình biên dịch quên những gì nó thấy trong literal. Ở đây cùng bảng màu đó được chú thích kiểu, và giờ TypeScript không còn biết green là một chuỗi:

// This does not compile: the annotation widens every property to Color.
type ColorName = "red" | "green" | "blue";
type Color = string | [number, number, number];

const palette: Record<ColorName, Color> = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
};

console.log(palette.green.toUpperCase());

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

index.ts(11,27): error TS2339: Property 'toUpperCase' does not exist on type 'Color'.
  Property 'toUpperCase' does not exist on type '[number, number, number]'.

Trước TypeScript 4.9, bạn chỉ có hai lựa chọn: chú thích kiểu rồi tự thu hẹp kiểu ở khắp nơi (typeof palette.green === "string"), hoặc bỏ chú thích và mất phần kiểm tra. satisfies cho bạn cả hai. Đổi : Record<ColorName, Color> thành satisfies Record<ColorName, Color> sau dấu ngoặc nhọn đóng là code chạy được.

satisfies so với chú thích kiểu và as

Cùng một đối tượng cài đặt, viết theo ba cách:

type Settings = {
  theme: "light" | "dark";
  fontSize: number;
  lang: string;
};

const annotated: Settings = { theme: "dark", fontSize: 14, lang: "en" };
const asserted = { theme: "dark", fontSize: 14 } as Settings; // lang is missing!
const satisfied = { theme: "dark", fontSize: 14, lang: "en" } satisfies Settings;

// annotated.theme: "light" | "dark"   (the annotation's type)
// satisfied.theme: "dark"             (what was actually written)
const isDark: "dark" = satisfied.theme; // fine; annotated.theme would be rejected

console.log(annotated.lang, asserted.lang, satisfied.lang); // en undefined en
console.log(isDark);                                         // dark

as cho phép thiếu lang, và asserted.lang là undefined lúc chạy trong khi kiểu của nó nói là string. Bỏ lang khỏi hai dòng còn lại thì cả hai đều báo lỗi TS2741, Property 'lang' is missing in type ....

Quy tắc chung: dùng chú thích kiểu khi bạn muốn biến mang kiểu đã khai báo (một giá trị bạn sẽ gán lại, một API công khai), và dùng satisfies khi bạn muốn được kiểm tra nhưng kiểu riêng của giá trị hữu ích hơn.

Bắt lỗi trong object literal

satisfies chạy toàn bộ phép kiểm tra khả năng gán, kể cả kiểm tra thuộc tính thừa, nên gõ sai tên khóa là lỗi:

type Route = { path: string; method: "GET" | "POST" };

const home = { path: "/", metod: "GET" } satisfies Route;
// error TS2561: Object literal may only specify known properties, but 'metod' does not exist in type 'Route'. Did you mean to write 'method'?

Phép kiểm tra này cũng cho literal một kiểu ngữ cảnh (contextual type), giống hệt chú thích kiểu. Điều đó quan trọng theo hai cách. Chuỗi literal được giữ là literal type khi kiểu đích cần chúng: { path: "/", method: "GET" } satisfies Route có method: "GET", trong khi cùng đối tượng đó không có chú thích sẽ được suy luận là method: string. Và tham số của callback được suy luận từ kiểu đích:

type Handlers = {
  onSave: (doc: { id: number; title: string }) => string;
  onDelete: (id: number) => boolean;
};

const handlers = {
  onSave: (doc) => `saved #${doc.id}: ${doc.title}`, // doc is typed from Handlers
  onDelete: (id) => id > 0,
} satisfies Handlers;

console.log(handlers.onSave({ id: 7, title: "Notes" })); // saved #7: Notes
console.log(handlers.onDelete(-1));                      // false

Khóa của Record vẫn được biết rõ

Một cách dùng phổ biến là bảng tra cứu. Khi chú thích kiểu là Record<string, T>, mọi chuỗi đều là khóa hợp lệ và một lỗi gõ sai vẫn biên dịch được, rồi trả về undefined lúc chạy. Với satisfies, các giá trị vẫn được kiểm tra với T, nhưng kiểu của biến liệt kê đúng những khóa bạn đã viết:

type Endpoint = { url: string; timeoutMs: number };

const loose: Record<string, Endpoint> = {
  users: { url: "/api/users", timeoutMs: 3000 },
};

const endpoints = {
  users: { url: "/api/users", timeoutMs: 3000 },
  orders: { url: "/api/orders", timeoutMs: 8000 },
} satisfies Record<string, Endpoint>;

console.log(loose.userz?.url); // undefined: the typo compiles
console.log(endpoints.orders.timeoutMs); // 8000

type EndpointName = keyof typeof endpoints; // "users" | "orders"
const endpointName: EndpointName = "users";
console.log(endpoints[endpointName].url); // /api/users

// @ts-expect-error: TS2551 Property 'userz' does not exist on type ... Did you mean 'users'?
endpoints.userz;

keyof typeof endpoints chỉ hữu ích vì các khóa vẫn còn. Với chú thích kiểu, nó sẽ chỉ là string.

Để bắt buộc một tập khóa cố định, hãy dùng satisfies với một Record trên một union: satisfies Record<"dev" | "prod", string> báo thiếu prod bằng TS2741 và báo khóa lạ staging bằng TS2353.

as const satisfies

as const và satisfies kết hợp được với nhau. Viết as const trước: nó khiến giá trị trở thành readonly ở mọi cấp với literal type, rồi satisfies kiểm tra đúng giá trị đó.

type Route = { path: string; method: "GET" | "POST"; auth: boolean };

const routes = [
  { path: "/", method: "GET", auth: false },
  { path: "/login", method: "POST", auth: false },
  { path: "/account", method: "GET", auth: true },
] as const satisfies readonly Route[];

type Path = (typeof routes)[number]["path"]; // "/" | "/login" | "/account"

function link(path: Path): string {
  return `<a href="${path}">`;
}

console.log(link("/account"));                           // <a href="/account">
console.log(routes.filter((r) => r.auth).map((r) => r.path)); // [ '/account' ]

Mỗi route được kiểm tra với Route (một method: "PUT" sẽ là lỗi), và tuple các literal type vẫn dùng được, nên Path là union của các đường dẫn thật. Dùng readonly Route[] (hoặc ReadonlyArray<Route>) làm kiểu đích, vì một mảng as const là readonly.

Đối tượng cấu hình

Cấu hình là nơi satisfies phát huy tác dụng: cấu trúc phải đúng, và code ở chỗ khác cần các giá trị chính xác.

type Env = "development" | "production";

type AppConfig = {
  port: number;
  logLevel: "debug" | "info" | "warn";
  features: Record<string, boolean>;
};

const configs = {
  development: { port: 3000, logLevel: "debug", features: { newCheckout: true } },
  production: { port: 8080, logLevel: "warn", features: { newCheckout: false } },
} satisfies Record<Env, AppConfig>;

function start(env: Env): string {
  const c = configs[env];
  return `${env}: port ${c.port}, log ${c.logLevel}, newCheckout=${c.features.newCheckout}`;
}

console.log(start("development")); // development: port 3000, log debug, newCheckout=true
console.log(start("production"));  // production: port 8080, log warn, newCheckout=false

Quên mục production, gõ sai logLevel, hoặc viết logLevel: "verbose", trình biên dịch sẽ chỉ ra đúng dòng đó. Cách làm này cũng hợp với các tệp *.config.ts: export default { ... } satisfies SomeConfig kiểm tra cả tệp trong khi đối tượng được export vẫn giữ các giá trị literal của nó.

Khi nào không nên dùng satisfies

• Biến sẽ được gán lại. let cfg = { port: 3000 } satisfies { port: number | string } cho cfg kiểu { port: number }, nên lệnh cfg = { port: "80" } sau đó sẽ lỗi (TS2322). Hãy chú thích kiểu cho những biến bạn định thay đổi.
• Bạn cố ý muốn dùng kiểu đã khai báo. Với giá trị trả về của hàm hay một hằng số được export thuộc về API, kiểu của chú thích chính là hợp đồng, và để lộ literal type chính xác có thể khiến những thay đổi sau này gây breaking change.
• Giá trị không phải là literal. satisfies phát huy tốt nhất trên object literal và array literal. Với một biến hay kết quả của một lời gọi hàm, nó chỉ là phép kiểm tra khả năng gán thông thường, thứ mà chú thích kiểu đã cho bạn rồi.