TypeScript satisfies 연산자: 타입 표기, as와 비교

value satisfies Type은 컴파일 시점에 value가 Type에 맞는지 검사하고, 그다음 값 자체의 더 정밀한 타입은 건드리지 않습니다. 타입 표기라면 그 정밀한 타입을 Type으로 대체했을 것입니다. satisfies는 넓히지 않고 검증합니다.

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도 검사는 합니다. 빠진 색상, bleu 같은 철자 틀린 키, true 같은 값은 그 줄에서 컴파일 오류입니다. TypeScript 4.9부터 있었고, 모든 타입 표기처럼 출력된 JavaScript에서는 제거됩니다.

satisfies가 해결하는 문제

타입 표기를 쓰면 변수의 타입은 곧 그 표기입니다. 컴파일러는 리터럴에서 본 것을 잊습니다. 여기서는 같은 팔레트에 타입 표기를 붙였고, 이제 TypeScript는 green이 문자열이라는 것을 더 이상 모릅니다.

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

컴파일러는 이렇게 보고합니다.

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

TypeScript 4.9 전에는 선택지가 두 가지였습니다. 표기를 붙이고 곳곳에서 손으로 좁히거나(typeof palette.green === "string"), 표기를 생략하고 검사를 포기하는 것입니다. satisfies는 둘 다 줍니다. : Record<ColorName, Color>를 닫는 중괄호 뒤의 satisfies Record<ColorName, Color>로 바꾸면 실행됩니다.

satisfies, 타입 표기, as 비교

같은 설정 객체를 세 가지 방식으로 썼습니다.

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는 빠진 lang을 통과시켰고, asserted.lang은 타입이 string이라고 말하는데도 런타임에는 undefined입니다. 다른 두 줄에서 lang을 지우면 둘 다 TS2741, Property 'lang' is missing in type ...으로 실패합니다.

경험칙: 변수가 선언된 타입을 갖기를 원할 때(다시 대입할 값, 공개 API)는 타입을 표기하고, 검사는 원하지만 값 자체의 타입이 더 유용할 때는 satisfies를 쓰세요.

객체 리터럴의 실수 잡기

satisfies는 초과 속성 검사를 포함한 완전한 대입 가능성 검사를 수행하므로, 키의 오타는 오류가 됩니다.

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'?

검사는 타입 표기처럼 리터럴에 문맥적 타입 도 줍니다. 이것은 두 가지 면에서 중요합니다. 대상 타입이 기대하면 문자열 리터럴이 리터럴 타입으로 유지됩니다. { path: "/", method: "GET" } satisfies Route는 method: "GET"을 갖지만, 표기 없는 같은 객체라면 method: string으로 추론될 것입니다. 그리고 콜백 매개변수가 대상 타입에서 추론됩니다.

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

Record의 키가 알려진 채로 남는다

흔한 용도는 조회 테이블입니다. Record<string, T>로 표기하면 모든 문자열이 유효한 키이고, 오타도 컴파일되어 런타임에 undefined를 반환합니다. satisfies를 쓰면 값은 여전히 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가 쓸모 있는 것은 키가 살아남았기 때문입니다. 타입 표기였다면 그냥 string이었을 것입니다.

정해진 키 집합을 요구하려면 유니언에 대한 Record를 만족시키세요. satisfies Record<"dev" | "prod", string>은 빠진 prod를 TS2741로, 알 수 없는 staging을 TS2353으로 보고합니다.

as const satisfies

as const와 satisfies는 함께 쓸 수 있습니다. as const를 먼저 쓰세요. 값을 리터럴 타입을 가진 깊은 readonly로 만들고, 그다음 satisfies가 그 정확한 값을 검사합니다.

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' ]

각 라우트는 Route에 대해 검사되고(method: "PUT"은 오류입니다), 리터럴 타입의 튜플은 계속 쓸 수 있으므로 Path는 실제 경로들의 유니언입니다. as const 배열은 readonly이므로 대상으로는 readonly Route[](또는 ReadonlyArray<Route>)를 쓰세요.

설정 객체

설정은 satisfies가 제 몫을 하는 곳입니다. 모양은 맞아야 하고, 다른 곳의 코드는 정확한 값을 원합니다.

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

production 항목을 빠뜨리거나, logLevel의 철자를 틀리거나, logLevel: "verbose"라고 쓰면 컴파일러가 정확한 줄을 가리킵니다. 같은 패턴은 *.config.ts 파일에도 잘 맞습니다. export default { ... } satisfies SomeConfig는 파일 전체를 검사하면서도 export된 객체가 리터럴 값을 유지합니다.

satisfies를 쓰지 말아야 할 때

• 변수를 다시 대입할 때. let cfg = { port: 3000 } satisfies { port: number | string }은 cfg에 { port: number } 타입을 주므로, 나중의 cfg = { port: "80" }은 실패합니다(TS2322). 바꿀 변수에는 타입을 표기하세요.
• 일부러 선언된 타입을 원할 때. 함수 반환값이나 API의 일부인 export 상수라면 표기의 타입이 계약이고, 정확한 리터럴 타입을 노출하면 나중의 변경이 호환성을 깨뜨릴 수 있습니다.
• 값이 리터럴이 아닐 때. satisfies는 객체와 배열 리터럴에서 빛납니다. 변수나 호출 결과에 쓰면 평범한 대입 가능성 검사일 뿐이며, 타입 표기가 이미 그것을 줍니다.