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

---
id: wiki-2026-0508-satisfies-operator
title: Satisfies Operator
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [TS satisfies, satisfies keyword, Type Satisfies]
duplicate_of: none
source_trust_level: A
confidence_score: 0.95
verification_status: applied
tags: [typescript, type-system, ts-4.9]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript
  framework: 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 방지
```typescript
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 검증
```typescript
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
```typescript
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
```typescript
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
```typescript
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
```typescript
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)
```typescript
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]] · [[TypeScript 타입 시스템 (TypeScript Type System)|Type System]]
- 변형: [[as const]] · [[Type Assertion]]
- 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 |