2nd/10_Wiki/Topics/Frontend/Satisfies Operator.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-satisfies-operator	Satisfies Operator	10_Wiki/Topics	verified	self	TS satisfies satisfies keyword Type Satisfies	none	A	0.95	applied	typescript type-system ts-4.9		2026-05-10	pending	language framework TypeScript TypeScript 5.x

Satisfies Operator

매 한 줄

"매 satisfies는 type 을 검증하면서 narrow type 을 보존". TS 4.9 (2022) 도입. as 와 달리 type assertion 이 아니라 type validation — value 의 inferred (narrow) type 은 그대로 유지하면서 declared shape 만 강제. 2026 기준 config object, route map, palette 같은 record 패턴 의 standard.

매 핵심

매 vs Type Annotation

• const x: T = value → x 의 type 은 T (widening)
• const x = value satisfies T → x 의 type 은 inferred narrow type, 단 T 호환 강제

매 vs as

• as 는 unsafe cast (런타임 보장 X)
• satisfies 는 compile-time validation (값 자체의 narrow type 을 잃지 않음)

매 응용

1. Const palette / theme — literal key 보존.
2. Route config — handler signature 검증 + key autocomplete.
3. Discriminated union literal — kind 가 narrow string literal 로 유지.

💻 패턴

Palette: widening 방지

type Color = "red" | "green" | "blue" | `#${string}`;

const palette = {
  primary: "red",
  secondary: "#00ff00",
  accent: "blue",
} satisfies Record<string, Color>;

// palette.primary: "red" (narrow), not Color
const r: "red" = palette.primary;  // OK

Route config + handler 검증

type Route = {
  path: string;
  handler: (req: Request) => Response | Promise<Response>;
};

const routes = {
  home: { path: "/", handler: () => new Response("hi") },
  api: { path: "/api", handler: async (req) => new Response("api") },
} satisfies Record<string, Route>;

// autocomplete on routes.home, routes.api (narrow keys)
routes.home.path;  // string (narrow "/")

Const enum-like with literal narrowing

const status = {
  IDLE: "idle",
  LOADING: "loading",
  ERROR: "error",
} satisfies Record<string, string>;

type Status = (typeof status)[keyof typeof status];
// "idle" | "loading" | "error"

satisfies + as const combo

const config = {
  retries: 3,
  endpoints: ["/a", "/b"],
} as const satisfies {
  retries: number;
  endpoints: readonly string[];
};
// config.retries: 3 (literal), config.endpoints: readonly ["/a","/b"]

Discriminated union event map

type Event =
  | { kind: "click"; x: number; y: number }
  | { kind: "key"; code: string };

const events = [
  { kind: "click", x: 10, y: 20 },
  { kind: "key", code: "Enter" },
] satisfies Event[];

// events[0].x is number; kind narrow to "click"

Generic helper preserving inference

function defineConfig<T extends Record<string, unknown>>(c: T): T {
  return c;
}
// Old way — full T preserved but no shape check.

// satisfies way:
const cfg = {
  port: 3000,
  host: "localhost",
} satisfies { port: number; host: string };
// cfg.port: number (not number literal). add `as const` for literal.

Schema-aligned object (zod-like)

type UserSchema = { id: string; name: string; admin?: boolean };

const seedUser = {
  id: "u1",
  name: "Alice",
  admin: true,
} satisfies UserSchema;

if (seedUser.admin) { /* narrow boolean true */ }

매 결정 기준

상황	Approach
value 의 narrow type 보존 + shape 검증	satisfies
매 값 의 type widening (기본 동작)	: T annotation
매 unsafe cast (last resort)	as T
Literal + readonly + shape	as const satisfies T

기본값: shape 검증이 필요하면 satisfies. 매 as 사용은 minimize.

🔗 Graph

• 부모: TypeScript · Type System
• 변형: as const · Type Assertion · Type Annotation
• 응용: Theme Tokens · Route Definition · Config Objects
• Adjacent: Discriminated Union · Const Assertion

🤖 LLM 활용

언제: Config / palette / route map 작성 시 narrow literal 보존이 필요할 때. 매 schema validation + autocomplete 동시 요구. 언제 X: Function parameter type (annotation 만으로 충분). 매 simple variable typing.

❌ 안티패턴

• as Record<...> cast: 매 unsafe. 매 satisfies 가 safer alternative.
• Annotation 으로 narrow loss: const x: Record<string, Color> = {...} → key narrow 소실.
• satisfies + assignment: let x = v satisfies T; x = "wrong" → 매 narrow type 만 강제, 후속 assignment 는 inferred type 기준.
• Pseudo-runtime check: 매 satisfies 는 compile-time only — runtime validation 은 zod / valibot.

🧪 검증 / 중복

• Verified (TypeScript 4.9 release notes, TS handbook).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — satisfies operator full content