김신건의 로그 - 위키 / typescript

[TypeScript] Conditional Types

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

Conditional Type 은 T extends U ? X : Y 형태로 타입 레벨에서 조건 분기를 표현합니다. infer 키워드로 매칭된 타입을 추출하고, union 에 대해서는 자동 분배 (distributive) 됩니다. Utility type 대부분이 이 위에 구현되어 있습니다.

기본

type IsString<T> = T extends string ? true : false;

type A = IsString<"hello">;    // true
type B = IsString<42>;          // false
type C = IsString<string>;      // true

T extends U 는 T 가 U 에 할당 가능한가 (subtype).

조건 분기 흐름

다이어그램 1: T extends U 분기 트리

flowchart TD
    START["T extends U ?"]
    START -->|"T가 U 서브타입"| YES["결과 타입: X"]
    START -->|"T가 U 서브타입 아님"| NO["결과 타입: Y"]
    YES --> EX1["IsString of string: true 반환"]
    YES --> EX2["NonNullable: T 그대로 반환"]
    NO --> EX3["IsString of number: false 반환"]
    NO --> EX4["NonNullable: never 반환"]

다이어그램 2: infer 추론 흐름

flowchart LR
    CT["F extends Pattern infer R ?"]
    CT -->|"매칭 성공"| INF["infer R: 타입 캡처"]
    CT -->|"매칭 실패"| NEV["never"]
    INF --> E1["ReturnType: 반환 위치의 R"]
    INF --> E2["FirstArg: 첫 인자 위치의 A"]
    INF --> E3["Awaited: Promise 내부의 U"]
    E1 --> R1["fn(): string에서 R = string"]
    E2 --> R2["fn(name: string)에서 A = string"]
    E3 --> R3["Promise of string에서 U = string"]

예: 표준 utility 재구현

`NonNullable`

type NonNullable<T> = T extends null | undefined ? never : T;

type A = NonNullable<string | null>;   // string
type B = NonNullable<number | undefined>;   // number

`Exclude`

type Exclude<T, U> = T extends U ? never : T;

type A = Exclude<"a" | "b" | "c", "a">;   // "b" | "c"

`Extract`

type Extract<T, U> = T extends U ? T : never;

type A = Extract<string | number | boolean, string | number>;   // string | number

Distributive Conditional Types

Type parameter 가 naked 하게 있으면 union 에 대해 자동 분배:

type ToArray<T> = T extends any ? T[] : never;

type A = ToArray<string | number>;
// = (string extends any ? string[] : never)
// | (number extends any ? number[] : never)
// = string[] | number[]

주의: 이는 자주 원치 않는 결과.

type A = ToArray<string | number>;   // string[] | number[]
type B = (string | number)[];         // (string | number)[]
// A ≠ B

(string | number)[] 를 원하면 tuple 로 감싸 분배 방지:

type ToArrayNonDist<T> = [T] extends [any] ? T[] : never;

type A = ToArrayNonDist<string | number>;   // (string | number)[]

`infer` 키워드

조건 안에서 특정 위치의 타입을 추출:

type ReturnType<F> = F extends (...args: any[]) => infer R ? R : never;

type A = ReturnType<() => string>;              // string
type B = ReturnType<(x: number) => number[]>;    // number[]
type C = ReturnType<{foo: string}>;              // never

infer R 은 위치의 타입을 R 이라는 이름으로 캡처.

예제

type FirstArg<F> = F extends (arg: infer A, ...args: any[]) => any ? A : never;

type A = FirstArg<(name: string, age: number) => void>;   // string

type ArrayElement<T> = T extends (infer E)[] ? E : never;

type B = ArrayElement<number[]>;    // number
type C = ArrayElement<string[]>;    // string

type Unwrap<T> = T extends Promise<infer U> ? U : T;

type D = Unwrap<Promise<string>>;    // string
type E = Unwrap<number>;              // number

재귀 (`Awaited`)

type Awaited<T> = T extends Promise<infer U> ? Awaited<U> : T;

type A = Awaited<Promise<Promise<Promise<string>>>>;   // string

조건 분기 심화

함수 오버로드 감지

type LastOverload<F> =
  F extends {
    (...args: infer A1): infer R1;
    (...args: infer A2): infer R2;
    (...args: infer A3): infer R3;
  } ? (...args: A3) => R3 :
  F extends {
    (...args: infer A1): infer R1;
    (...args: infer A2): infer R2;
  } ? (...args: A2) => R2 :
  F extends (...args: infer A) => infer R ? (...args: A) => R : never;

TypeScript 는 conditional 로 오버로드 signature 를 마지막 것만 매칭하는 한계가 있음.

tuple 분해

type Head<T extends any[]> = T extends [infer H, ...any[]] ? H : never;
type Tail<T extends any[]> = T extends [any, ...infer R] ? R : never;

type A = Head<[1, 2, 3]>;    // 1
type B = Tail<[1, 2, 3]>;    // [2, 3]

재귀 tuple 처리

type Length<T extends readonly any[]> = T["length"];
type Reverse<T extends any[]> =
  T extends [infer F, ...infer R] ? [...Reverse<R>, F] : [];

type A = Reverse<[1, 2, 3]>;   // [3, 2, 1]

type Concat<A extends any[], B extends any[]> = [...A, ...B];

type X = Concat<[1, 2], [3, 4]>;   // [1, 2, 3, 4]

Distributive union filtering

type OnlyStrings<T> = T extends string ? T : never;

type A = OnlyStrings<string | number | boolean>;   // string

| never 는 원 타입으로 흡수 (union 에서 never 제거).

조건부 필드 매칭

type PickByValue<T, V> = {
  [K in keyof T as T[K] extends V ? K : never]: T[K];
};

type User = {id: number; name: string; age: number};
type Nums = PickByValue<User, number>;   // {id: number; age: number}

Mapped type + conditional + key remapping 조합.

Higher-order utility

type OverrideProps<T, U> = Omit<T, keyof U> & U;

type A = {x: number; y: string};
type B = {y: number; z: boolean};

type C = OverrideProps<A, B>;   // {x: number; y: number; z: boolean}

Type-level parser

type ParseInt<S extends string> =
  S extends `${infer N extends number}` ? N : never;

type A = ParseInt<"42">;    // 42

type Split<S extends string, D extends string> =
  S extends `${infer H}${D}${infer R}` ? [H, ...Split<R, D>] : [S];

type B = Split<"a,b,c", ",">;   // ["a", "b", "c"]

Template literal type + conditional + infer 로 컴파일 타임 문자열 파싱.

Chain of conditionals

type TypeName<T> =
  T extends string ? "string" :
  T extends number ? "number" :
  T extends boolean ? "boolean" :
  T extends undefined ? "undefined" :
  T extends null ? "null" :
  T extends Function ? "function" :
  "object";

type A = TypeName<"hi">;    // "string"
type B = TypeName<42>;       // "number"

함정

[!WARNING] Distributive 함정. Union type parameter 는 자동 분배. 원치 않으면 [T] extends [U] 로 tuple 감쌈.

[!CAUTION] 재귀 깊이 제한. TypeScript 는 재귀 conditional 을 약 50 단계 정도로 제한. 너무 깊으면 컴파일 오류.

[!WARNING] infer 는 조건 안에서만. type X = infer Y 는 오류. T extends ... infer ... 구조.

[!IMPORTANT] 성능. 복잡한 conditional 은 컴파일 시간 급증. 벤치마크 (tsc —extendedDiagnostics).

[!CAUTION] never 흡수. A | never = A, A & never = never. Conditional 에서 필터링 결과 확인 필요.

[TypeScript] Generics

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

Generics 는 타입을 파라미터화하는 문법입니다. 함수, 클래스, 인터페이스, type alias 가 재사용 가능 하면서도 타입 안전 하도록 만듭니다. Java 의 generic, C++ 의 template 유사.

왜 필요한가

Generic 없이:

function identity(x: any): any {
  return x;
}

const s = identity("hello");   // s: any (타입 손실)

Generic 사용:

function identity<T>(x: T): T {
  return x;
}

const s = identity("hello");   // s: "hello" (또는 string)
const n = identity(42);        // n: 42 (또는 number)

컴파일러가 T 를 호출 인자에서 추론.

개념 흐름

다이어그램 1: 제네릭 인스턴스화

flowchart TD
    GF["Generic Function of T"]
    GF -->|"string 인자로 호출"| S["T = string"]
    GF -->|"number 인자로 호출"| N["T = number"]
    GF -->|"boolean 인자로 호출"| B["T = boolean"]
    S --> R1["반환 타입: string"]
    N --> R2["반환 타입: number"]
    B --> R3["반환 타입: boolean"]

다이어그램 2: 제약, 기본값, variance

flowchart TB
    T["Type Parameter T"]
    T --> C["제약 extends"]
    T --> D["기본값 Default"]
    T --> V["분산 Variance"]
    C -->|"T extends U"| C1["U 서브타입만 허용"]
    C --> C2["예: T extends object"]
    C --> C3["예: T extends keyof U"]
    D -->|"T = DefaultType"| D1["T 생략시 기본값 사용"]
    V --> V1["공변: 출력 위치"]
    V --> V2["반변: 입력 위치"]

Generic 함수

function first<T>(arr: T[]): T | undefined {
  return arr[0];
}

const s = first(["a", "b"]);      // string | undefined
const n = first([1, 2]);           // number | undefined

명시적 타입 지정도 가능:

const x = first<number>([1, 2, 3]);

대개 추론이 정확하므로 생략.

여러 type parameter

function pair<A, B>(a: A, b: B): [A, B] {
  return [a, b];
}

const p = pair("hello", 42);   // [string, number]

Generic arrow function

const identity = <T,>(x: T): T => x;

.tsx 파일에서는 <T> 가 JSX 와 헷갈리므로 <T,> 나 <T extends unknown> 로 명확히.

Constraint (extends)

Type parameter 에 제약을 걸어 특정 속성/타입만 허용:

function longest<T extends {length: number}>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

longest("hello", "hi");            // OK
longest([1, 2, 3], [4]);            // OK
longest(1, 2);                       // 오류: number 는 length 없음

keyof constraint

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

const user = {name: "kim", age: 30};
const name = getProperty(user, "name");     // string
const age = getProperty(user, "age");       // number
getProperty(user, "email");                  // 오류

keyof T 는 T 의 속성 이름 union.

여러 constraint

function merge<T extends object, U extends object>(a: T, b: U): T & U {
  return {...a, ...b};
}

Default type

interface Container<T = string> {
  value: T;
}

const c1: Container = {value: "hello"};      // T = string
const c2: Container<number> = {value: 42};    // T = number

React 의 useState<T = undefined> 같은 패턴에서 자주 사용.

Generic Interface

interface Repository<T> {
  find(id: number): Promise<T | null>;
  save(item: T): Promise<void>;
  delete(id: number): Promise<void>;
}

class UserRepo implements Repository<User> {
  async find(id: number): Promise<User | null> { ... }
  async save(user: User): Promise<void> { ... }
  async delete(id: number): Promise<void> { ... }
}

Generic Type Alias

type Result<T, E = Error> =
  | {ok: true; value: T}
  | {ok: false; error: E};

function parse<T>(input: string): Result<T> {
  try {
    return {ok: true, value: JSON.parse(input)};
  } catch (e) {
    return {ok: false, error: e as Error};
  }
}

Rust 의 Result 유사.

Generic Class

class Stack<T> {
  private items: T[] = [];

  push(item: T): void {
    this.items.push(item);
  }

  pop(): T | undefined {
    return this.items.pop();
  }

  peek(): T | undefined {
    return this.items[this.items.length - 1];
  }
}

const s = new Stack<number>();
s.push(1);
s.push(2);
s.pop();     // 2 (number)

Generic Constraint 심화

Constraint + default

function fetchAll<T extends Fetchable = User>(): Promise<T[]> {
  ...
}

Constraint with union

function serialize<T extends string | number>(x: T): string {
  return String(x);
}

Generic + literal type

function log<T extends string>(level: T, msg: string): void {
  console.log(`[${level}] ${msg}`);
}

const level = log("INFO", "message");   // T = "INFO"

Generic Parameter 로 함수 오버로드 대체

// 오버로드
function process(x: string): string;
function process(x: number): number;
function process(x: any): any {
  return x;
}

// Generic
function process<T extends string | number>(x: T): T {
  return x;
}

infer 키워드

Conditional type 안에서 타입을 추출:

type ReturnType<F> = F extends (...args: any[]) => infer R ? R : never;

type A = ReturnType<() => string>;              // string
type B = ReturnType<(x: number) => number[]>;    // number[]

type FirstArg<F> = F extends (arg: infer A, ...args: any[]) => any ? A : never;
type X = FirstArg<(name: string, age: number) => void>;   // string

type Awaited<T> = T extends Promise<infer U> ? Awaited<U> : T;
type Y = Awaited<Promise<Promise<string>>>;     // string

자세한 것은 [[ts-conditional-types|Conditional Types]] 참조.

`const` type parameter (TS 5.0+)

Generic 이 리터럴 타입을 유지하도록:

function fruits<const T extends string[]>(items: T): T {
  return items;
}

const f = fruits(["apple", "banana"]);
//    ^^ readonly ["apple", "banana"]  (literal 유지)

이 없으면:

const f = fruits(["apple", "banana"]);
//    ^^ string[]  (넓혀짐)

`NoInfer<T>` (TS 5.4+)

Type inference 를 특정 파라미터에서 막음:

function createConfig<T>(defaults: T, overrides: NoInfer<Partial<T>>): T {
  return {...defaults, ...overrides};
}

createConfig({name: "kim", age: 30}, {name: "lee"});
// T 는 defaults 에서만 추론, overrides 는 T 에 종속

Generic 성능 팁

재귀 제한: 재귀 generic 은 컴파일 시간 증가. 필요시 depth counter.
Union 분배: T extends U ? X : Y 에서 T 가 union 이면 자동 분배. 원치 않으면 [T] extends [U] 감쌈.
Alias 로 캐시: 자주 쓰는 조합은 alias 로 이름 붙이면 컴파일러가 캐시.

실전 예시

React useState

function useState<T>(initial: T): [T, (v: T) => void] {
  // ...
}

const [count, setCount] = useState(0);    // T = number
const [name, setName] = useState("");     // T = string

배열 map/filter

function map<T, U>(arr: T[], fn: (x: T) => U): U[] {
  return arr.map(fn);
}

const doubled = map([1, 2, 3], x => x * 2);      // number[]
const strs = map([1, 2, 3], x => x.toString());   // string[]

Async wrapper

async function retry<T>(
  fn: () => Promise<T>,
  attempts: number = 3,
  delay: number = 1000,
): Promise<T> {
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === attempts - 1) throw e;
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error("unreachable");
}

const result = await retry(() => fetchUser(id));

Event emitter

type EventMap = {
  click: {x: number; y: number};
  keydown: {key: string};
  submit: {data: object};
};

class Emitter<E extends Record<string, any>> {
  private handlers: {[K in keyof E]?: ((v: E[K]) => void)[]} = {};

  on<K extends keyof E>(event: K, handler: (v: E[K]) => void): void {
    (this.handlers[event] ||= []).push(handler);
  }

  emit<K extends keyof E>(event: K, value: E[K]): void {
    this.handlers[event]?.forEach(h => h(value));
  }
}

const e = new Emitter<EventMap>();
e.on("click", (v) => console.log(v.x, v.y));   // v 는 {x, y} 로 좁혀짐
e.emit("click", {x: 10, y: 20});

함정

[!WARNING] <T> 를 .tsx 에서. <T>() => x 는 JSX 로 파싱됨. <T,> (콤마) 또는 <T extends unknown>.

[!CAUTION] Constraint 없이 T 를 사용. function f<T>(x: T) { x.foo(); } 는 T 에 foo 가 있다는 보장 없어 오류. T extends {foo(): void} 로 constraint.

[!WARNING] Generic 은 런타임에 없음. if (x instanceof T) 같은 것 불가. T 는 컴파일 시만.

[!IMPORTANT] Type inference 우선. 명시적 <Type> 지정을 남발하지 마세요. 추론이 정확할 때가 대부분.

[!CAUTION] Union 분배 함정. T extends string ? "yes" : "no" 에서 T = string | number 면 "yes" | "no" 됨. 원치 않으면 tuple 로 감싸기.

[TypeScript] Utility Types

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

Utility Types 는 TypeScript 표준 라이브러리에 포함된 미리 정의된 generic 타입 들입니다. 기존 타입을 변형/구성하는 흔한 패턴을 제공하며, mapped/conditional 타입으로 구현되어 있습니다.

유틸리티 타입 계보

다이어그램 1: Object 변형 유틸리티 타입

flowchart LR
    MT["Mapped Type 구현"]
    CT["Conditional Type 구현"]
    MT --> P["Partial of T"]
    MT --> RQ["Required of T"]
    MT --> RO["Readonly of T"]
    MT --> PI["Pick of T, K"]
    MT --> OM["Omit of T, K"]
    CT --> EX["Exclude of T, U"]
    CT --> ET["Extract of T, U"]
    CT --> NN["NonNullable of T"]
    PI -->|"여집합"| OM

다이어그램 2: 함수/Promise 유틸리티 타입

flowchart TD
    F["Function F"] --> RT["ReturnType of F"]
    F --> PR["Parameters of F"]
    RT --> R1["반환 타입 추출"]
    PR --> R2["매개변수 tuple 추출"]
    P1["Promise of string"] -->|"단층 unwrap"| AW["Awaited of T"]
    P2["Promise of Promise of number"] -->|"재귀 unwrap"| AW
    AW --> R3["최종 내부 타입"]

Object 변형

`Partial<T>` - 모든 필드를 optional

interface User {id: number; name: string; email: string}

type UserUpdate = Partial<User>;
// = {id?: number; name?: string; email?: string}

function update(id: number, patch: Partial<User>): void { ... }

구현:

type Partial<T> = {[K in keyof T]?: T[K]};

`Required<T>` - 모든 필드를 required

interface Config {port?: number; debug?: boolean}

type StrictConfig = Required<Config>;
// = {port: number; debug: boolean}

구현:

type Required<T> = {[K in keyof T]-?: T[K]};

-? 는 optional 을 제거.

`Readonly<T>` - 모든 필드를 readonly

type Point = {x: number; y: number};
type FrozenPoint = Readonly<Point>;

const p: FrozenPoint = {x: 1, y: 2};
p.x = 5;   // 오류

Shallow only. 중첩 객체는 여전히 mutable. Deep readonly 는 type-fest 의 ReadonlyDeep.

필드 선택

`Pick<T, K>` - 특정 필드만

type User = {id: number; name: string; email: string; password: string};

type UserPublic = Pick<User, "id" | "name" | "email">;
// = {id: number; name: string; email: string}

`Omit<T, K>` - 특정 필드 제외

type UserPublic = Omit<User, "password">;
// = {id: number; name: string; email: string}

type UserUpdate = Omit<User, "id">;

Omit 은 Pick + Exclude 조합.

Record (사전)

`Record<K, V>` - K 키의 사전

type UserRoles = Record<string, "admin" | "user" | "guest">;

const roles: UserRoles = {
  alice: "admin",
  bob: "user",
};

// 리터럴 키
type Status = Record<"pending" | "active" | "closed", number>;
// = {pending: number; active: number; closed: number}

구현:

type Record<K extends keyof any, T> = {[P in K]: T};

Union 조작

`Exclude<T, U>` - T 에서 U 제거

type Direction = "north" | "south" | "east" | "west";
type Horizontal = Exclude<Direction, "north" | "south">;
// = "east" | "west"

`Extract<T, U>` - T 에서 U 와 겹치는 것만

type Value = string | number | boolean | null;
type Primitive = Extract<Value, string | number>;
// = string | number

`NonNullable<T>` - null / undefined 제거

type Maybe = string | null | undefined;
type Value = NonNullable<Maybe>;
// = string

Function 관련

`ReturnType<F>` - 함수 반환 타입

function fetch(): Promise<User> { ... }

type FetchResult = ReturnType<typeof fetch>;
// = Promise<User>

`Parameters<F>` - 함수 매개변수 타입 (tuple)

function log(level: string, msg: string, data?: object): void { ... }

type LogParams = Parameters<typeof log>;
// = [string, string, object?]

function proxy(...args: Parameters<typeof log>): void {
  log(...args);
}

`ConstructorParameters<C>` - 생성자 매개변수

class User {
  constructor(name: string, age: number) {}
}

type UserArgs = ConstructorParameters<typeof User>;
// = [string, number]

`InstanceType<C>` - 클래스 인스턴스 타입

class User { constructor(name: string) {} }

type UserInstance = InstanceType<typeof User>;
// = User

typeof Class 는 constructor 타입, InstanceType 은 그 인스턴스.

`ThisParameterType<F>` / `OmitThisParameter<F>`

function fn(this: string): number { return this.length }

type T = ThisParameterType<typeof fn>;    // string
type F = OmitThisParameter<typeof fn>;    // () => number

Promise 관련

`Awaited<T>` - Promise 를 unwrap (재귀)

type A = Awaited<Promise<string>>;              // string
type B = Awaited<Promise<Promise<number>>>;      // number (재귀)
type C = Awaited<string>;                        // string (non-Promise 는 그대로)

async function getUser(): Promise<User> { ... }

type User = Awaited<ReturnType<typeof getUser>>;   // User

TS 4.5+.

String 조작

`Uppercase<S>`, `Lowercase<S>`, `Capitalize<S>`, `Uncapitalize<S>`

type A = Uppercase<"hello">;       // "HELLO"
type B = Lowercase<"HELLO">;        // "hello"
type C = Capitalize<"hello">;       // "Hello"
type D = Uncapitalize<"Hello">;     // "hello"

// Template literal 과 조합
type EventName<T extends string> = `on${Capitalize<T>}`;
type ClickEvent = EventName<"click">;  // "onClick"

자세한 것은 [[ts-template-literal-types|Template Literal Types]] 참조.

Composition 예시

type User = {
  id: number;
  email: string;
  password: string;
  createdAt: Date;
  updatedAt: Date;
};

// 생성 시: 모든 필드 필수, id/timestamp 자동
type UserCreateInput = Omit<User, "id" | "createdAt" | "updatedAt">;

// 갱신 시: id 제외 + Partial
type UserUpdateInput = Partial<Omit<User, "id" | "createdAt" | "updatedAt">>;

// 응답 시: 민감 필드 제외
type UserResponse = Omit<User, "password">;

// Public read-only
type UserPublicRO = Readonly<Pick<User, "id" | "email">>;

실전 patterns

API endpoint 정의

type Endpoints = {
  "GET /users": {response: User[]};
  "GET /users/:id": {params: {id: string}; response: User};
  "POST /users": {body: UserCreateInput; response: User};
  "PATCH /users/:id": {params: {id: string}; body: UserUpdateInput; response: User};
};

type Method<E extends keyof Endpoints> =
  E extends `${infer M} ${string}` ? M : never;

type ExtractParams<E> = E extends {params: infer P} ? P : never;
type ExtractBody<E> = E extends {body: infer B} ? B : never;
type ExtractResponse<E> = E extends {response: infer R} ? R : never;

form input mapping

type FormInputs<T> = {
  [K in keyof T]: {
    label: string;
    type: T[K] extends boolean ? "checkbox" :
          T[K] extends number ? "number" :
          "text";
    required: undefined extends T[K] ? false : true;
  };
};

type UserFormInputs = FormInputs<User>;

`type-fest` 확장

Sindre Sorhus 의 type-fest 는 표준 utility 로 부족한 것들을 추가:

ReadonlyDeep: 깊은 readonly
PartialDeep: 깊은 partial
SetOptional<T, K>: 특정 필드만 optional
SetRequired<T, K>: 특정 필드만 required
Merge<A, B>: 두 타입 병합 (B 우선)
CamelCase<S>, SnakeCase<S>, KebabCase<S>
Simplify<T>: 표시 단순화
Except<T, K>: 엄격한 Omit
ValueOf<T>: T 의 값 타입 union
Entries<T>: [key, value] tuple 배열

만들기 있어 유용

DeepReadonly

type DeepReadonly<T> = {
  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
};

DeepPartial

type DeepPartial<T> = {
  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
};

PickByValue (값 타입으로 필드 선택)

type PickByValue<T, V> = {
  [K in keyof T as T[K] extends V ? K : never]: T[K];
};

type User = {id: number; name: string; age: number};
type Numeric = PickByValue<User, number>;   // {id: number; age: number}

KeysOfType

type KeysOfType<T, V> = {
  [K in keyof T]: T[K] extends V ? K : never;
}[keyof T];

type NumberKeys = KeysOfType<User, number>;   // "id" | "age"

RequireAtLeastOne

type RequireAtLeastOne<T, Keys extends keyof T = keyof T> =
  Pick<T, Exclude<keyof T, Keys>>
  & {
      [K in Keys]-?:
        Required<Pick<T, K>>
        & Partial<Pick<T, Exclude<Keys, K>>>
  }[Keys];

함정

[!WARNING] Readonly 는 shallow. 중첩 객체는 여전히 mutable.

[!CAUTION] Omit 은 union 에 배타적. Omit<A | B, "id"> 는 A 와 B 각각에서 id 제거가 아니라 공통 필드만 유지. 원하는 게 각 case 별 제거면 distributive helper.

[!WARNING] Record<string, T> 는 index signature. keyof 하면 string. 명시적 유한 union 이 필요하면 리터럴 union 을 keys 로.

[!IMPORTANT] Utility type 은 매번 재계산 가능. 자주 쓰는 조합은 alias 로 저장해 컴파일러 캐시 활용.

[!CAUTION] ReturnType<T> 은 T 가 함수 타입일 때만. typeof someFunction 형태로 감싸는 것 자주 필요.

[TypeScript] Declaration Files (.d.ts)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Declaration File (.d.ts) 은 타입 정보만 담은 파일입니다. 실행 코드 없이 함수, 클래스, 변수, 모듈의 타입 시그니처 만 선언합니다. JavaScript 라이브러리를 TypeScript 에서 안전하게 사용하기 위한 다리 역할을 합니다.

자동 생성: tsc --declaration 시 .ts 소스에서 .d.ts 자동 생성 (라이브러리 배포용)
수동 작성: 순수 JS 라이브러리에 타입 부여

기본 문법

// mylib.d.ts
declare function greet(name: string): string;
declare const VERSION: string;
declare class Client {
  constructor(url: string);
  send(msg: string): Promise<void>;
}

declare 는 “이것은 런타임에 존재한다고 가정하고 타입만 부여” 를 의미. Emit 안 됨.

Ambient Module

외부 (npm) 모듈 타입 선언:

// mylib.d.ts
declare module "cool-lib" {
  export function coolFn(x: number): string;
  export const version: string;
  export default class Cool {
    constructor(opts: {debug?: boolean});
    activate(): Promise<void>;
  }
}

이후:

와일드카드 모듈

// assets.d.ts
declare module "*.png" {
  const url: string;
  export default url;
}

declare module "*.svg" {
  import type {ComponentProps, FC} from "react";
  const svg: FC<ComponentProps<"svg">>;
  export default svg;
}

// 사용
import logo from "./logo.png";       // logo: string
import Icon from "./icon.svg";        // Icon: React component

Ambient Variable

declare const process: {
  env: Record<string, string | undefined>;
};

declare const window: Window & {
  myGlobal?: string;
};

이런 것들은 lib.dom.d.ts, @types/node 등이 이미 제공.

Global Augmentation

기존 전역 타입 확장:

// global.d.ts
export {};  // 이 파일을 모듈로 표시 (declare global 사용에 필요)

declare global {
  interface Window {
    myApp: {
      version: string;
      init(): void;
    };
  }

  interface String {
    reverse(): string;   // String prototype 확장
  }

  namespace NodeJS {
    interface ProcessEnv {
      NEXT_PUBLIC_API_URL: string;
      DATABASE_URL: string;
    }
  }
}

process.env.DATABASE_URL 이 타입 안전. Undefined 없음.

Module Augmentation

기존 npm 모듈 확장:

// express-augment.d.ts
import "express";   // 원본 모듈 로드

declare module "express" {
  interface Request {
    userId?: string;
    auth?: {token: string};
  }
}

이제 req.userId, req.auth 를 어디서든 접근 가능. 인증 미들웨어 패턴에 필수.

JSX augmentation (React)

// custom-elements.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    "my-widget": {color?: string; size?: "sm" | "md" | "lg"};
  }
}

// 사용
<my-widget color="red" size="md" />

Web Component 사용 시 유용.

Declaration Merging

같은 이름의 interface / namespace 를 여러 파일에서 선언하면 자동 병합:

// file1.d.ts
interface Config {port: number}

// file2.d.ts
interface Config {host: string}

// = interface Config {port: number; host: string}

Interface merge 만 됨. Type alias 는 안 됨.

Types-only import in .d.ts

Declaration 파일 안에서 타입 가져오기:

// mylib.d.ts

declare module "mylib" {
  export function middleware(req: Request, res: Response): void;
}

Triple slash directive (legacy)

/// <reference path="./other.d.ts" />
/// <reference types="node" />

지양. import type 이나 tsconfig types 배열로 대체.

DefinitelyTyped

Community 유지 npm 패키지 타입 저장소. @types/* 스코프로 배포.

npm install --save-dev @types/node @types/express @types/react

라이브러리가 자체 타입을 포함하면 @types 불필요. package.json 의 types / typings 필드로 지정.

라이브러리 자체 타입 포함

{
  "name": "mylib",
  "main": "dist/index.js",
  "types": "dist/index.d.ts"
}

tsc --declaration 로 emit 한 .d.ts 를 types 로 노출.

Types 조회 순서

Import 시 TypeScript 는:

자체 .d.ts (package.json 의 types)
@types/{name} 패키지
찾을 수 없음 -> noImplicitAny 상태에 따라 오류 또는 any

`declaration: true` (라이브러리 빌드)

{
  "compilerOptions": {
    "declaration": true,           // .d.ts 생성
    "declarationMap": true,         // .d.ts.map (IDE go-to-definition)
    "emitDeclarationOnly": false,   // .js 도 emit
    "outDir": "./dist"
  }
}

rollup + dts plugin (bundle .d.ts)

큰 라이브러리는 .d.ts 를 하나로 번들:

npm i -D rollup-plugin-dts

// rollup.config.js

export default {
  input: "./dist/index.d.ts",
  output: [{file: "./dist/bundled.d.ts", format: "es"}],
  plugins: [dts()],
};

실전: env vars 타입

// env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: "development" | "production" | "test";
    DATABASE_URL: string;
    SECRET_KEY: string;
    PORT?: string;
  }
}

process.env.DATABASE_URL 이 string 으로 (undefined 없이). 물론 실제 undefined 방어는 별도.

실전: CSS Modules

// css-modules.d.ts
declare module "*.module.css" {
  const classes: {readonly [key: string]: string};
  export default classes;
}

declare module "*.module.scss" {
  const classes: {readonly [key: string]: string};
  export default classes;
}

// 사용

<button className={styles.primary}>Click</button>

실전: Vite 환경

// vite-env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_URL: string;
  readonly VITE_APP_NAME: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

함정

[!WARNING] declare global 은 module 안에만. 파일이 module (import / export 포함) 이어야 함. 상단에 export {}; 트릭.

[!CAUTION] Ambient 는 컴파일 시만. 실제 런타임에 그 module 이 없으면 오류. 파일 매핑 (webpack, vite alias) 필요.

[!WARNING] @types 버전 불일치. 라이브러리 버전과 다른 @types 버전이면 타입 오류. npm-check-updates 로 동기화.

[!IMPORTANT] 자체 타입 포함 시 @types 무시하도록. package.json 의 types 필드가 최우선.

[!CAUTION] JSDoc 도 있음. .d.ts 대신 JSDoc 으로 타입 부여 가능 (@type, @param). 순수 JS 라이브러리 문서화에 활용.

[TypeScript] Decorators

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Decorator 는 class, method, accessor, property, parameter 에 부착되는 함수로 그 대상을 검사/수정할 수 있습니다. TypeScript 는 두 가지 데코레이터 시스템을 지원합니다.

TC39 Stage 3 decorators (TypeScript 5.0+, 표준화 예정): experimentalDecorators: false (기본)
Legacy experimental decorators (TypeScript 1.5+, experimentalDecorators: true): 기존 Angular/NestJS 스타일

두 시스템은 완전히 다른 API. 프로젝트에서 하나만 선택.

Stage 3 Decorators (TypeScript 5.0+)

Class Decorator

function logged<T extends new (...args: any[]) => any>(
  target: T,
  context: ClassDecoratorContext,
): T {
  return class extends target {
    constructor(...args: any[]) {
      super(...args);
      console.log(`Created ${context.name}`);
    }
  };
}

@logged
class Person {
  constructor(public name: string) {}
}

new Person("kim");   // "Created Person"

context 는 metadata:

interface ClassDecoratorContext {
  kind: "class";
  name: string | undefined;
  addInitializer(initializer: () => void): void;
  metadata: DecoratorMetadata;
}

Method Decorator

function log<This, Args extends any[], Return>(
  target: (this: This, ...args: Args) => Return,
  context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
  const name = String(context.name);
  return function(this: This, ...args: Args): Return {
    console.log(`[${name}] called with`, args);
    const result = target.apply(this, args);
    console.log(`[${name}] returned`, result);
    return result;
  };
}

class Calculator {
  @log
  add(a: number, b: number): number {
    return a + b;
  }
}

new Calculator().add(1, 2);
// [add] called with [1, 2]
// [add] returned 3

Field Decorator

function bounded<This, Value>(
  target: undefined,
  context: ClassFieldDecoratorContext<This, Value>,
): (this: This, initial: Value) => Value {
  const name = context.name;
  return function(initial: Value): Value {
    Object.defineProperty(this, name, {
      value: initial,
      writable: false,
    });
    return initial;
  };
}

class Config {
  @bounded
  version = "1.0.0";
}

Getter / Setter Decorator

function readOnly<This, Value>(
  target: () => Value,
  context: ClassGetterDecoratorContext<This, Value>,
): () => Value {
  return target;
}

class User {
  @readOnly
  get name() {
    return "kim";
  }
}

Accessor Decorator (TC39 새 문법)

accessor 키워드로 auto-implemented getter/setter:

function loggedAccessor<This, Value>(
  target: {get: () => Value; set: (v: Value) => void},
  context: ClassAccessorDecoratorContext<This, Value>,
) {
  return {
    get() {
      console.log("get", context.name);
      return target.get.call(this);
    },
    set(v: Value) {
      console.log("set", context.name, v);
      target.set.call(this, v);
    },
  };
}

class User {
  @loggedAccessor
  accessor name = "kim";
}

Decorator with Options (Factory)

function throttle(ms: number) {
  return function<This, Args extends any[], Return>(
    target: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext,
  ) {
    let last = 0;
    return function(this: This, ...args: Args): Return | undefined {
      const now = Date.now();
      if (now - last < ms) return;
      last = now;
      return target.apply(this, args);
    };
  };
}

class Api {
  @throttle(1000)
  fetch() { ... }
}

Legacy Decorators (experimentalDecorators)

tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Class Decorator

function sealed(constructor: Function) {
  Object.seal(constructor);
  Object.seal(constructor.prototype);
}

@sealed
class Config {}

Method Decorator

function log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const original = descriptor.value;
  descriptor.value = function(...args: any[]) {
    console.log(`[${propertyKey}]`, args);
    return original.apply(this, args);
  };
}

class Calculator {
  @log
  add(a: number, b: number): number {
    return a + b;
  }
}

target: class prototype (instance method) 또는 class 자체 (static)
propertyKey: method name
descriptor: PropertyDescriptor (value, writable, …)

Property Decorator

function readOnly(target: any, propertyKey: string) {
  Object.defineProperty(target, propertyKey, {writable: false});
}

class User {
  @readOnly
  id = 1;
}

Parameter Decorator

function required(target: any, propertyKey: string, parameterIndex: number) {
  // 메타데이터 기록. 실제 검증은 method decorator 에서
}

class Api {
  fetch(@required id: string) { ... }
}

emitDecoratorMetadata

Reflect API 로 타입 메타데이터 조회 가능 (파라미터 타입 등). reflect-metadata 폴리필 필요:


function inject(target: any, propertyKey: string, parameterIndex: number) {
  const types = Reflect.getMetadata("design:paramtypes", target, propertyKey);
  console.log("param types:", types);
}

NestJS / TypeORM 등의 핵심 원리 이지만, 표준 (Stage 3) 은 아님. Angular, TypeORM 은 여전히 legacy 사용.

Stage 3 vs Legacy 요약

기준	Stage 3	Legacy
표준	TC39 표준화 진행 중	TypeScript 실험적
활성화	기본 (5.0+)	`experimentalDecorators: true`
파라미터 데코레이터	미지원	지원
메타데이터	`context.metadata`	`reflect-metadata`
Angular / NestJS 호환	아직 X	O
미래 지향	O	X (deprecated 예정)

결론: 새 프로젝트는 Stage 3, 기존 Angular/NestJS 는 legacy 유지.

실전 예시

Autobind (this binding)

function autobind<This, Args extends any[], Return>(
  target: (this: This, ...args: Args) => Return,
  context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
  const methodName = String(context.name);
  context.addInitializer(function(this: This) {
    (this as any)[methodName] = (target as any).bind(this);
  });
}

class Button {
  label = "click me";

  @autobind
  handleClick() {
    console.log(this.label);
  }
}

const b = new Button();
const handler = b.handleClick;
handler();   // "click me" (this 유실 없음)

Retry decorator

function retry(times: number, delay: number) {
  return function<This, Args extends any[], Return>(
    target: (this: This, ...args: Args) => Promise<Return>,
    context: ClassMethodDecoratorContext,
  ) {
    return async function(this: This, ...args: Args): Promise<Return> {
      let lastError: unknown;
      for (let i = 0; i < times; i++) {
        try {
          return await target.apply(this, args);
        } catch (e) {
          lastError = e;
          await new Promise(r => setTimeout(r, delay));
        }
      }
      throw lastError;
    };
  };
}

class Api {
  @retry(3, 1000)
  async fetchUser(id: number): Promise<User> {
    return fetch(`/users/${id}`).then(r => r.json());
  }
}

Memoize

function memoize<This, Args extends any[], Return>(
  target: (this: This, ...args: Args) => Return,
  context: ClassMethodDecoratorContext,
) {
  const cache = new Map<string, Return>();
  return function(this: This, ...args: Args): Return {
    const key = JSON.stringify(args);
    if (cache.has(key)) return cache.get(key)!;
    const result = target.apply(this, args);
    cache.set(key, result);
    return result;
  };
}

class Fibonacci {
  @memoize
  compute(n: number): number {
    return n <= 1 ? n : this.compute(n - 1) + this.compute(n - 2);
  }
}

함정

[!WARNING] Stage 3 vs Legacy 는 완전히 다른 API. 섞어 쓰면 안 되고, tsconfig 에서 하나 선택.

[!CAUTION] Legacy 는 미래에 제거될 수도 있음. NestJS 등이 아직 마이그레이션 안 됐으니 당장 걱정은 없지만 장기 프로젝트는 주의.

[!WARNING] Stage 3 는 아직 브라우저 native 지원 미미. Babel/TypeScript 트랜스파일 필요.

[!IMPORTANT] Decorator 는 자동 호출 시점. Class 정의 시 실행. Instance 마다 실행 X. 초기화 로직은 context.addInitializer 활용.

[!CAUTION] 디버깅 어려움. Decorator 로 감싸진 method 는 stack trace 가 복잡. Sourcemap 유지.

[TypeScript] Enums

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Enum 은 여러 관련 상수를 하나의 이름 아래 그룹화하는 TypeScript 기능입니다. Numeric enum, string enum, const enum, heterogeneous enum 등 여러 변종이 있으며, 최근에는 enum 을 지양하고 union literal 이나 as const 객체를 쓰는 편이 관용 이 되고 있습니다.

Numeric Enum

기본 형태. 값이 정수로 자동 할당.

enum Direction {
  Up,       // 0
  Down,     // 1
  Left,     // 2
  Right,    // 3
}

const d = Direction.Up;   // 0

명시적 값:

enum Status {
  OK = 200,
  BadRequest = 400,
  Unauthorized = 401,
  NotFound = 404,
  ServerError = 500,
}

Reverse mapping

Numeric enum 은 값 -> 이름 역방향도 자동 생성:

console.log(Status[200]);   // "OK"
console.log(Status[404]);   // "NotFound"

컴파일된 JS:

var Status;
(function (Status) {
    Status[Status["OK"] = 200] = "OK";
    Status[Status["BadRequest"] = 400] = "BadRequest";
})(Status || (Status = {}));

String Enum

값이 문자열. Reverse mapping 없음.

enum Direction {
  Up = "UP",
  Down = "DOWN",
  Left = "LEFT",
  Right = "RIGHT",
}

console.log(Direction.Up);      // "UP"
console.log(Direction["UP"]);    // undefined (reverse mapping 없음)

디버깅 시 값이 명시적이라 numeric enum 보다 유리.

Heterogeneous Enum

숫자/문자열 혼합. 실전에서 지양.

enum Mixed {
  A = 1,
  B = "yes",
}

Const Enum

const enum 은 컴파일 시 inline 됩니다. 런타임 객체가 없음.

const enum Direction {
  Up,
  Down,
  Left,
  Right,
}

const d = Direction.Up;

컴파일 결과:

const d = 0 /* Direction.Up */;

Pros:

런타임 오버헤드 없음
트리 셰이킹 우수

Cons:

isolatedModules: true 하에서 사용 불가 (esbuild/swc/Babel 이 파일 단위 트랜스파일이라 다른 파일의 const enum 참조 불가)
라이브러리 배포 시 문제 (사용자가 참조 불가)

결론: 모던 프로젝트에서는 사실상 사용 불가. as const 객체가 대안.

Computed Members

enum FileAccess {
  None,
  Read = 1 << 1,        // 2
  Write = 1 << 2,        // 4
  ReadWrite = Read | Write,   // 6
  Length = "abc".length,       // 3 (compile-time computed)
}

Bitwise flag 에 유용하지만 코드 리뷰가 힘들어짐.

Enum 의 문제점

1. `isolatedModules` 하에서 `const enum` 불가

esbuild, swc, Babel 이 fail. 모던 툴체인에서 큰 제약.

2. Numeric enum 은 타입 안전성이 부족

enum Direction { Up, Down }

function move(d: Direction): void { ... }

move(Direction.Up);   // OK
move(100);             // 오류 아님! (numeric 이면 any number 허용될 수 있음)

TypeScript 5.0+ 부터는 조금 더 엄격해졌지만 여전히 함정 존재.

3. Reverse mapping 은 종종 유출

Numeric enum 의 reverse mapping 은 원치 않을 때가 많음.

const values = Object.values(Status);
// = ["OK", "BadRequest", ..., 200, 400, ...]  (문자열 + 숫자)

4. 트리 셰이킹 실패

일반 enum (non-const) 은 런타임 객체를 만들어 트리 셰이킹 안 됨. 큰 enum 은 번들 크기 증가.

대안 1: Union Literal

가장 간단하고 관용적:

type Direction = "up" | "down" | "left" | "right";

function move(d: Direction): void { ... }

move("up");         // OK
move("northwest");  // 오류

// Exhaustive check
function opposite(d: Direction): Direction {
  switch (d) {
    case "up": return "down";
    case "down": return "up";
    case "left": return "right";
    case "right": return "left";
  }
}

Pros:

런타임 오버헤드 없음 (그냥 문자열)
Structural typing 과 잘 맞음
isolatedModules OK
트리 셰이킹 완벽

Cons:

값 목록을 조회하기 힘듦 (Object.values(enum) 대안이 없음)

대안 2: `as const` Object

값 목록도 필요하면:

const Direction = {
  Up: "up",
  Down: "down",
  Left: "left",
  Right: "right",
} as const;

type Direction = typeof Direction[keyof typeof Direction];
// = "up" | "down" | "left" | "right"

function move(d: Direction): void { ... }

move(Direction.Up);   // OK
move("up");            // OK

// 값 열거
Object.values(Direction);   // ["up", "down", "left", "right"]

Pros:

런타임 객체 존재 (Object.keys, Object.values)
타입 안전 (union 로 좁혀짐)
as const 로 정확한 리터럴 타입
isolatedModules OK
트리 셰이킹 OK (import 되지 않으면 제거)

Cons:

코드가 살짝 장황

이 방식이 2020년대 관용의 정답.

Union + Object 실전 예시

export const HTTP_STATUS = {
  OK: 200,
  BAD_REQUEST: 400,
  UNAUTHORIZED: 401,
  NOT_FOUND: 404,
  SERVER_ERROR: 500,
} as const;

export type HttpStatus = typeof HTTP_STATUS[keyof typeof HTTP_STATUS];
// = 200 | 400 | 401 | 404 | 500

function respond(status: HttpStatus): void { ... }
respond(HTTP_STATUS.OK);   // OK
respond(200);               // OK (literal 이라)
respond(300);               // 오류

Union + Function 헬퍼

export type Role = "admin" | "editor" | "viewer";

export const ROLES: Role[] = ["admin", "editor", "viewer"];

export function isRole(x: unknown): x is Role {
  return typeof x === "string" && ROLES.includes(x as Role);
}

Enum 유지가 여전히 나은 케이스

legacy 프로젝트 이미 enum 다수 사용 중
NestJS / Angular 데코레이터와 결합
양방향 매핑 (numeric <-> string 이름) 이 자주 필요
Bitwise flag (실전에서는 여전히 유용)

Enum 리팩토링

// Before
enum Direction { Up, Down, Left, Right }

// After (마이그레이션)
export const Direction = {
  Up: 0,
  Down: 1,
  Left: 2,
  Right: 3,
} as const;
export type Direction = typeof Direction[keyof typeof Direction];

이 이전은 usage 코드 변경 없이 진행 (Direction.Up 그대로 작동).

Enum 을 iterable 로 만들기

enum Direction { Up, Down, Left, Right }

const directions = Object.values(Direction).filter(
  v => typeof v === "number"
) as Direction[];

for (const d of directions) {
  console.log(d);
}

이 필터가 필요한 이유가 numeric enum 의 reverse mapping 때문. 그래서 as const 객체가 더 깔끔.

함정

[!WARNING] isolatedModules 하에서 const enum 오류. esbuild, Vite, Next.js 대부분에서 사용 불가.

[!CAUTION] Numeric enum 은 임의 숫자 허용 위험. TS 5.0+ 개선되었지만 완전히 안전한 것은 아님.

[!WARNING] Enum 을 export 하는 라이브러리. 사용자의 프로젝트에서 다르게 취급될 수 있음 (const enum 의 문제). String union 이 안전한 API.

[!IMPORTANT] 새 코드는 as const object 또는 union literal. Enum 은 legacy / 특수 케이스만.

[!CAUTION] Reverse mapping 유출. Object.values(numericEnum) 는 값 + 이름 모두. 필터 필요.

[TypeScript] Interfaces

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Interface 는 객체의 shape (형태) 을 정의하는 TypeScript 문법입니다. 필드, 메서드, 인덱스 시그니처, 호출 시그니처를 선언하며, extends 로 상속하고 declaration merging 으로 확장할 수 있습니다.

기본 사용

interface User {
  id: number;
  name: string;
  email: string;
}

const u: User = {id: 1, name: "kim", email: "a@b.com"};

function greet(user: User): string {
  return `Hi, ${user.name}`;
}

Optional / Readonly / Index Signature

interface Config {
  readonly host: string;         // 재할당 금지
  port: number;
  debug?: boolean;                // optional
  [key: string]: any;             // index signature (임의 키)
}

readonly: shallow readonly. 필드 자체는 재할당 못 하지만 필드가 객체면 그 내부는 변경 가능.
?: 필드가 없거나 undefined 일 수 있음.
[key: string]: T: 임의의 문자열 키에 T 값 허용.

함수 시그니처

Method 스타일

interface Calculator {
  add(a: number, b: number): number;
  subtract(a: number, b: number): number;
}

Function 필드 스타일

interface Calculator {
  add: (a: number, b: number) => number;
  subtract: (a: number, b: number) => number;
}

두 방식은 대부분 상호 교환. Method 스타일은 strictFunctionTypes 하에서 bivariance (덜 엄격), function 필드는 contravariance (엄격). 대개 함수 필드가 더 안전.

Call signature (전체 객체가 호출 가능)

interface Formatter {
  (input: string): string;         // 호출 시그니처
  prefix: string;                   // 필드도 함께
}

const f: Formatter = Object.assign(
  (s: string) => `[${s}]`,
  {prefix: "["}
);

Construct signature

interface Constructor {
  new (name: string): Person;
}

function factory(C: Constructor, name: string): Person {
  return new C(name);
}

extends (상속)

interface Animal {
  name: string;
  age: number;
}

interface Dog extends Animal {
  breed: string;
  bark(): void;
}

const d: Dog = {name: "Rex", age: 3, breed: "Shiba", bark: () => {}};

여러 인터페이스 상속:

interface Swimmer { swim(): void; }
interface Runner { run(): void; }
interface Triathlete extends Swimmer, Runner {
  bike(): void;
}

Class implements

interface Greetable {
  name: string;
  greet(): string;
}

class Person implements Greetable {
  constructor(public name: string) {}
  greet(): string {
    return `Hi, ${this.name}`;
  }
}

주의: implements 는 검사만. 실제 필드/메서드는 클래스가 스스로 구현. 상속 (extends class) 과 다름.

Declaration Merging

같은 이름의 interface 를 여러 번 선언하면 자동 병합:

interface Window {
  myGlobal: string;
}

// 다른 파일
interface Window {
  anotherGlobal: number;
}

// 결과
Window = {myGlobal: string; anotherGlobal: number}

이 특성 덕분에 module augmentation 이 가능. 라이브러리 타입 확장:

// express-extension.d.ts
declare module "express" {
  interface Request {
    userId?: string;
  }
}

// 이제 어디서든
req.userId = "abc";

Type alias 는 이 기능 없음. type X = ... 을 두 번 선언하면 오류.

Interface vs Type Alias

거의 상호 교환. 차이점:

기준	Interface	Type Alias
Declaration merging	✓	✗
Union / Intersection	Intersection 만 (`extends`)	둘 다 (`
Primitive alias	✗	✓ (`type ID = string`)
Mapped/Conditional 표현	✗	✓
성능	살짝 유리 (컴파일러 최적화)	대부분 무시할 수준

관용:

Object shape 라면 interface (일관성)
Union, mapped, conditional, primitive alias 면 type
라이브러리 사용자에게 확장 가능성을 제공하고 싶으면 interface
확장 불가로 봉인하고 싶으면 type

Extending Type Alias

Interface 는 type alias 를 extends 가능:

type Point = {x: number; y: number};

interface Point3D extends Point {
  z: number;
}

Type alias 는 & 로 합성:

type Point3D = Point & {z: number};

Generic Interface

interface Repository<T> {
  find(id: number): Promise<T | null>;
  save(item: T): Promise<void>;
  delete(id: number): Promise<void>;
}

class UserRepository implements Repository<User> {
  async find(id: number): Promise<User | null> { ... }
  async save(user: User): Promise<void> { ... }
  async delete(id: number): Promise<void> { ... }
}

자세한 것은 [[ts-generics|Generics]] 참조.

Hybrid Type

interface Counter {
  (): number;              // 함수로 호출
  count: number;           // 필드
  reset(): void;           // 메서드
}

function makeCounter(): Counter {
  const c: any = () => c.count++;
  c.count = 0;
  c.reset = () => { c.count = 0 };
  return c;
}

jQuery 등 오래된 라이브러리의 API 를 타이핑할 때 유용.

Interface for JSON Schema

interface ApiResponse<T> {
  status: "ok" | "error";
  data?: T;
  error?: string;
}

interface User {
  id: number;
  email: string;
  createdAt: string;    // ISO date
}

type UserResponse = ApiResponse<User>;

주의: interface 는 컴파일 시 검사만. 런타임에는 실제 검증 안 함. 외부 데이터는 zod / valibot 같은 런타임 검증기 병용.


const UserSchema = z.object({
  id: z.number(),
  email: z.string().email(),
  createdAt: z.string(),
});

type User = z.infer<typeof UserSchema>;   // 스키마에서 타입 추론

const user = UserSchema.parse(rawJson);   // 런타임 검증

Interface 로 함수 오버로드

interface Cake {
  (name: string): string;
  (name: string, layers: number): string;
  (name: string, layers: number, flavor: string): string;
}

const bake: Cake = (name: string, layers?: number, flavor?: string) => {
  ...
};

bake("chocolate");
bake("vanilla", 3);
bake("carrot", 2, "cinnamon");

excess property check

객체 리터럴을 직접 전달할 때 정의되지 않은 필드를 갖고 있으면 오류:

interface Config {
  host: string;
  port: number;
}

const c: Config = {host: "localhost", port: 80, debug: true};   // 오류

이 검사를 우회하려면:

변수 저장 후 전달 (const raw = {..., debug: true}; const c: Config = raw;)
Index signature 추가 ([k: string]: any)
Type assertion ({...} as Config) - 지양

함정

[!WARNING] readonly 는 shallow. readonly items: Item[] 이어도 items[0].name = "..." 는 허용. 완전한 immutable 이 필요하면 readonly Item[] + 각 필드도 readonly.

[!CAUTION] Declaration merging 의 함정. 실수로 같은 이름 interface 를 두 번 정의하면 조용히 merge 되어 예상 밖 동작. 명확한 파일/모듈 스코프.

[!WARNING] implements 는 상속이 아님. 실제 상속은 extends class. interface implements 는 타입 검사만.

[!IMPORTANT] Excess property check 는 리터럴에만 작동. 변수를 먼저 만들면 회피 가능하지만 대개 실제 버그 신호.

[!CAUTION] Structural typing 이므로 이름은 무의미. interface User { name: string } 와 interface Product { name: string } 는 상호 대체 가능. 진짜 nominal 이 필요하면 branded type (type UserId = string & {__brand: "UserId"}).

[TypeScript] Mapped Types

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Mapped Type 은 기존 타입의 각 필드를 순회 ([K in keyof T]) 하며 새 타입을 생성하는 문법입니다. readonly, ? modifier 를 붙이거나 제거 (-readonly, -?) 하고, as clause 로 키 이름을 재작명할 수 있습니다.

기본 구조

type MappedType<T> = {
  [K in keyof T]: T[K];
};

이는 T 를 그대로 복사. 여기에 변형을 추가:

type ReadOnly<T> = {
  readonly [K in keyof T]: T[K];
};

type Optional<T> = {
  [K in keyof T]?: T[K];
};

type Nullable<T> = {
  [K in keyof T]: T[K] | null;
};

type Stringified<T> = {
  [K in keyof T]: string;
};

Modifier 추가/제거

`readonly` / `-readonly`

type Immutable<T> = {readonly [K in keyof T]: T[K]};
type Mutable<T> = {-readonly [K in keyof T]: T[K]};

type A = Immutable<{x: number}>;   // {readonly x: number}
type B = Mutable<A>;                // {x: number}

`?` / `-?`

type Partial<T> = {[K in keyof T]?: T[K]};
type Required<T> = {[K in keyof T]-?: T[K]};

type A = Partial<{x: number}>;     // {x?: number}
type B = Required<A>;               // {x: number}

Key remapping (`as`)

TypeScript 4.1+ 부터 키 이름 재작명 가능.

type Prefixed<T> = {
  [K in keyof T as `get_${string & K}`]: () => T[K];
};

type User = {id: number; name: string};
type UserGetters = Prefixed<User>;
// = {get_id: () => number; get_name: () => string}

조건부 키 필터

never 반환 시 필드 제거:

type OmitNever<T> = {
  [K in keyof T as T[K] extends never ? never : K]: T[K];
};

type A = {x: number; y: never; z: string};
type B = OmitNever<A>;   // {x: number; z: string}

필드 이름으로 필터

type OnlyEndingWithId<T> = {
  [K in keyof T as K extends `${string}Id` ? K : never]: T[K];
};

type A = {name: string; userId: number; postId: number; active: boolean};
type B = OnlyEndingWithId<A>;   // {userId: number; postId: number}

값 타입으로 필터

type PickByValue<T, V> = {
  [K in keyof T as T[K] extends V ? K : never]: T[K];
};

type A = {id: number; name: string; age: number; active: boolean};
type B = PickByValue<A, number>;   // {id: number; age: number}

`as const` 와 결합

const CONFIG = {host: "localhost", port: 8080} as const;
type Config = typeof CONFIG;       // {readonly host: "localhost"; readonly port: 8080}
type Keys = keyof Config;           // "host" | "port"
type Values = Config[Keys];         // "localhost" | 8080

여러 필드에서 유래한 타입

type MakeGetterSetter<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
} & {
  [K in keyof T as `set${Capitalize<string & K>}`]: (v: T[K]) => void;
};

type User = {name: string; age: number};
type UserAccessors = MakeGetterSetter<User>;
// = {getName: () => string; getAge: () => number;
//    setName: (v: string) => void; setAge: (v: number) => void}

Deep transformation

DeepReadonly

type DeepReadonly<T> = {
  readonly [K in keyof T]: T[K] extends object
    ? DeepReadonly<T[K]>
    : T[K];
};

type A = {user: {name: string; age: number}};
type B = DeepReadonly<A>;
// = {readonly user: {readonly name: string; readonly age: number}}

DeepPartial

type DeepPartial<T> = {
  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
};

DeepReplace type

type Replace<T, From, To> = {
  [K in keyof T]: T[K] extends From ? To :
    T[K] extends object ? Replace<T[K], From, To> :
    T[K];
};

type A = {a: number; b: {c: number; d: string}};
type B = Replace<A, number, string>;
// = {a: string; b: {c: string; d: string}}

Union 을 union of key 로

type ToKeyValueUnion<T> = {
  [K in keyof T]: {key: K; value: T[K]};
}[keyof T];

type User = {id: number; name: string; email: string};
type Entry = ToKeyValueUnion<User>;
// = {key: "id"; value: number}
//   | {key: "name"; value: string}
//   | {key: "email"; value: string}

[keyof T] 인덱싱으로 union 화.

Enum 뒤집기

type Reverse<T> = {
  [K in keyof T as T[K] extends string | number ? T[K] : never]: K;
};

const COLORS = {RED: "red", GREEN: "green", BLUE: "blue"} as const;
type Colors = typeof COLORS;
type Reversed = Reverse<Colors>;
// = {red: "RED"; green: "GREEN"; blue: "BLUE"}

Tuple 매핑

type MapTuple<T extends any[], U> = {
  [K in keyof T]: U;
};

type A = MapTuple<[1, 2, 3], string>;   // [string, string, string]

type NullableTuple<T extends any[]> = {
  [K in keyof T]: T[K] | null;
};

type B = NullableTuple<[string, number]>;   // [string | null, number | null]

Tuple 도 keyof 대상. keyof [1, 2, 3] 은 "0" | "1" | "2" | "length" | ... 를 포함.

실전: form 스키마

type FormSchema<T> = {
  [K in keyof T]: {
    label: string;
    type: T[K] extends boolean ? "checkbox" :
          T[K] extends number ? "number" :
          T[K] extends Date ? "date" :
          "text";
    required: T[K] extends undefined ? false : true;
    default?: T[K];
  };
};

type User = {name: string; age: number; admin?: boolean; birth: Date};
type UserForm = FormSchema<User>;

실전: SQL row -> object

type SnakeToCamel<S extends string> =
  S extends `${infer H}_${infer R}` ? `${H}${Capitalize<SnakeToCamel<R>>}` : S;

type CamelKeys<T> = {
  [K in keyof T as SnakeToCamel<string & K>]: T[K];
};

type Row = {user_id: number; created_at: Date; is_active: boolean};
type Camel = CamelKeys<Row>;
// = {userId: number; createdAt: Date; isActive: boolean}

함정

[!WARNING] [K in keyof T] 는 keyof T 를 매번 재계산. 성능 이슈 시 alias 로 저장.

[!CAUTION] as never 로 필드 제거는 조건적. Non-conditional 에서는 무의미.

[!WARNING] DeepReadonly 는 primitive 를 만나면 정지. Array/Function 처리에 주의 (Array 는 object 로 매칭됨 -> 원치 않은 결과 가능).

[!IMPORTANT] keyof T 는 string | number | symbol. 문자열 조작 (template literal) 시 string & K 로 좁혀야 함.

[!CAUTION] 재귀 depth. DeepReadonly 등 재귀는 TypeScript 제한 (50 단계) 에 걸릴 수 있음.

[TypeScript] Modules (import/export, moduleResolution)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

TypeScript 모듈 시스템은 ES Modules (ESM) 를 기본 언어 모델로 삼되, CommonJS (CJS) 를 상호운용성 (interop) 계층으로 지원합니다. moduleResolution 옵션이 어떻게 파일을 찾을지, module 이 어떻게 emit 할지를 결정하며, TypeScript 5.0 의 verbatimModuleSyntax 는 마술을 최소화합니다.

import / export 기본

Named export

// utils.ts
export function add(a: number, b: number): number { return a + b; }
export function sub(a: number, b: number): number { return a - b; }
export const PI = 3.14;

// main.ts

Default export

// user.ts
export default class User {
  constructor(public name: string) {}
}

// main.ts

default 는 남용 지양. Named export 가 명확 (rename 안전, tree-shaking 좋음).

Re-export

// index.ts (barrel)
export * from "./utils";
export * from "./models";
export {default as User} from "./user";
export type {ApiResponse} from "./types";

Namespace import


utils.add(1, 2);

Side effect import

import "./polyfill";   // 부수효과만

Type-only import / export

Type 만 import 하면 컴파일 시 제거됨 -> 런타임 부담 없음.



// 함수 안에서 타입만 사용
function process(u: User): string {
  return u.name;
}

혼합:

`verbatimModuleSyntax: true` (TS 5.0+)

TS 5.0+ 권장. type 없는 import 는 실제 런타임에 유지, type 은 제거. 마술 없음.

// verbatimModuleSyntax: true
import {LoggerOptions} from "./logger";       // LoggerOptions 가 값이면 유지, 타입만이면 오류
import type {LoggerOptions} from "./logger";  // 확실히 타입만

모듈 형식 (module)

tsconfig.json 의 module 옵션은 emit 형식:

값	emit
`commonjs`	`require`, `module.exports`
`esnext` / `es2020` / `es2022`	ES modules (`import`, `export`)
`nodenext` / `node16`	파일 확장자 / package.json 에 따라 자동
`amd`, `umd`, `system`	브라우저 legacy
`preserve` (TS 5.4+)	원본 그대로 (esbuild 등에게 위임)

모듈 해석 (moduleResolution)

파일 경로를 어떻게 찾을지:

값	특성
`node` (legacy)	Node.js require 알고리즘 (CJS)
`node16` / `nodenext`	Node 16+ ESM 지원 (package.json `type`, `exports` 존중)
`bundler` (TS 5.0+)	번들러 (Webpack, Vite, esbuild) 규칙, ESM 형식 파일 확장자 없음
`classic` (legacy)	매우 오래된 스타일, 사용 안 함

`bundler` (권장, 웹앱)

Vite, Next.js, Webpack, esbuild 등이 실제 해석. TS 는 검사만.

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,     // .ts 확장자 명시 허용
    "noEmit": true                            // 번들러가 emit
  }
}

`nodenext` (Node.js 앱)

Node.js 16+ 의 실제 ESM 규칙 준수:

.mjs / .cjs 확장자
package.json 의 "type": "module" / "type": "commonjs"
exports 필드 (conditional exports)
ESM 에서는 파일 확장자 명시 필수 (import "./util.js", 실제 파일은 .ts 여도 .js)

{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext"
  }
}

`.js` 확장자 문제

nodenext / node16 하에서 ESM import 는 컴파일된 파일 이름 (.js) 을 참조:

// src/main.ts
import {util} from "./util.js";   // 실제 파일은 util.ts, 컴파일 후 util.js

// 아래는 오류

TypeScript 5.0+ allowImportingTsExtensions 로 .ts 도 명시 가능 (하지만 emit 은 안 함, 번들러에게 위임).

Path Aliases (`paths`)

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"]
    }
  }
}

중요: TypeScript 는 검사만. 런타임 (또는 번들러) 도 같은 alias 해석 필요:

Vite: resolve.alias 자동으로 tsconfig 읽음 (vite-tsconfig-paths 플러그인)
Webpack: resolve.alias 수동
Next.js: tsconfig.json 자동
Node.js (러ntime): tsconfig-paths 폴리필 필요

`isolatedModules`

{"isolatedModules": true}

각 파일이 독립적으로 컴파일 가능해야 함 (esbuild/swc/Babel 이 파일 단위로 트랜스파일 하기 때문). 활성화 시:

const enum 사용 시 오류 (다른 파일에서 참조 불가) -> Union literal 로 대체
default export re-export: export {default} from "./x" 는 OK, export default from "./x" 는 불가
네임스페이스 (namespace) 로 인한 컴파일 부작용 감지

관용: isolatedModules: true 는 프로덕션 필수.

`esModuleInterop`

CJS 모듈을 ESM 스타일로 import 하도록:

{"esModuleInterop": true}

// esModuleInterop: false

const app = express();   // 오류: express 는 default export 아님

// esModuleInterop: true

const app = express();   // OK, TypeScript 가 자동 wrap

`allowSyntheticDefaultImports`

esModuleInterop 을 활성화하면 자동. 명시적으로 켤 수도.

Namespace (legacy)

namespace Utils {
  export function add(a: number, b: number): number { return a + b; }
}

Utils.add(1, 2);

Deprecated 스타일. ES modules 등장 이전의 module 시스템. 새 코드에서는 사용 안 함.

Module 안의 Ambient Declaration

// global.d.ts
declare global {
  interface Window {
    myGlobal: string;
  }
}

// 사용
window.myGlobal;

Ambient 는 [[ts-declaration-files|Declaration Files]] 참조.

`import.meta`

ESM 의 표준. Module URL 등 접근.

console.log(import.meta.url);   // "file:///.../main.js"

// Node.js ESM
if (import.meta.url === `file://${process.argv[1]}`) {
  main();
}

Vite:

if (import.meta.env.DEV) { ... }
if (import.meta.hot) { ... }   // HMR

Dynamic import

const module = await import("./heavy");
module.foo();

Code splitting 의 기본. Type:

type ModuleType = typeof import("./heavy");
const module: ModuleType = await import("./heavy");

실전 tsconfig (2026 표준)

Bundler (Web app, Next.js, Vite)

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "esnext",
    "moduleResolution": "bundler",
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "strict": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "lib": ["ES2022", "DOM"],
    "paths": {"@/*": ["src/*"]}
  },
  "include": ["src/**/*"]
}

Node.js (backend, CLI)

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "esModuleInterop": true,
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "sourceMap": true,
    "lib": ["ES2022"]
  },
  "include": ["src/**/*"]
}

함정

[!WARNING] nodenext 하에서 확장자 필수. import "./util" 은 오류. import "./util.js". 이는 TS 컴파일 후 .js 파일을 찾기 때문.

[!CAUTION] isolatedModules 없이 esbuild/swc 사용 위험. Const enum, namespace 등이 조용히 잘못 컴파일.

[!WARNING] paths 는 runtime 해석에 자동 반영 안 됨. 번들러 / Node.js 도 같은 alias 해석 지원 필요.

[!IMPORTANT] verbatimModuleSyntax 를 켜세요. TS 5.0+ 강력 권장. Emit 결과의 예측성 향상.

[!CAUTION] CJS <-> ESM 경계. Node.js 에서 CJS 파일이 ESM import 하려면 dynamic import 필요. require("esm-only-package") 는 오류.

[!WARNING] Barrel file (index.ts) 남용. Tree-shaking 저해, 빌드 느려짐, 순환 import. 큰 앱에서는 지양.

[TypeScript] Primitive Types

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Primitive Types 는 TypeScript 의 가장 기본 타입 계열입니다. JavaScript 의 7가지 primitive 값 + 특수 타입 (void, never, unknown, any) 을 포함합니다.

타입	값 예시	언제
`string`	`"hello"`	문자열
`number`	`42`, `3.14`	정수/실수 (double)
`boolean`	`true`, `false`	참거짓
`bigint`	`9007199254740993n`	임의 정밀도 정수
`symbol`	`Symbol()`	고유 식별자
`null`	`null`	명시적 null
`undefined`	`undefined`	값 없음
`void`	리턴 없음	함수 반환
`never`	없음	절대 발생하지 않음
`unknown`	모든 값	타입 모름 (안전)
`any`	모든 값	타입 검사 해제 (위험)

string

let s: string = "hello";
let s2 = "world";                    // 추론
const name = "kim";                  // literal type: "kim"

// Template literal
let greeting = `Hello, ${name}`;

Literal type: const 로 선언된 문자열은 정확한 문자열 리터럴 타입 이 됩니다.

let a: string = "hello";      // string
const b = "hello";            // "hello" (literal type)

number

let x: number = 42;
let y: number = 3.14;
let z: number = 0xFF;         // 헥스
let w: number = 0b1010;       // 이진
let v: number = 1_000_000;    // 구분자

const PI = 3.14;              // literal 3.14

JavaScript 는 정수/실수 구분 없음. 모두 64-bit double.

boolean

let flag: boolean = true;
const isReady = false;        // literal false

bigint

임의 정밀도 정수. n 접미사.

let big: bigint = 9007199254740993n;
let big2 = BigInt(123);

// number 와 혼합 불가
big + 1;         // 오류
big + 1n;        // OK

언제: DB primary key, blockchain wei, 큰 timestamp.

symbol

고유 식별자. 두 symbol 은 절대 동등하지 않음.

const s1 = Symbol("foo");
const s2 = Symbol("foo");
s1 === s2;    // false

// 객체의 unique key 로
const KEY = Symbol();
const obj = {[KEY]: "value"};

Symbol.iterator, Symbol.asyncIterator 등 well-known symbol 이 프로토콜 정의.

null / undefined

두 값이 유사하지만 미묘하게 다름:

undefined: 변수가 초기화되지 않음, 함수 리턴 없음
null: 명시적 으로 값 없음

let x: string | null = null;
let y: string | undefined;

if (x != null) {
  x.toUpperCase();    // null 과 undefined 모두 배제
}

strictNullChecks (기본 활성) 하에서는 string 타입에 null/undefined 를 못 넣음. 명시적 union 필요.

void

함수가 아무것도 반환하지 않음:

function log(msg: string): void {
  console.log(msg);
}

const cb: () => void = () => 42;   // OK, void 는 반환 값 무시

void 리턴 타입 함수의 반환값은 사실상 무시 (() => any 와 다름). 콜백 시그니처에 유용.

never

절대 발생하지 않는 값:

function throwError(msg: string): never {
  throw new Error(msg);
}

function loop(): never {
  while (true) {}
}

Exhaustive check

type Shape = {kind: "circle", r: number} | {kind: "square", s: number};

function area(s: Shape): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.r ** 2;
    case "square": return s.s ** 2;
    default:
      const _exhaustive: never = s;    // 새 case 추가 시 컴파일 오류
      return _exhaustive;
  }
}

Discriminated union 의 모든 case 를 다뤘음을 컴파일러가 검증.

never 는 모든 타입의 subtype

type Result = never | number;   // number 로 축약

unknown

타입을 모른다 는 것을 안전하게 표현. any 대체.

let x: unknown = JSON.parse(rawJson);

// 바로 사용 불가
x.toUpperCase();          // 오류

// narrowing 후 사용
if (typeof x === "string") {
  x.toUpperCase();        // OK
}

if (typeof x === "object" && x !== null && "name" in x) {
  console.log(x.name);
}

언제: 외부 데이터 (JSON.parse, API 응답, event.data). 검증 후 좁혀서 사용.

any

타입 검사 해제. 위험.

let x: any = 5;
x = "string";
x.foo.bar();       // 컴파일 통과, 런타임 오류

언제 (제한적으로 허용):

마이그레이션 임시 회피
진짜로 타입을 알 수 없고 검증 안 할 때
noImplicitAny: false 는 위험

unknown 이 대개 더 안전한 대안.

Anti-pattern: any[], Record<string, any>, Function 남용.

Union 조합

let id: string | number = "abc";
id = 42;

function print(v: string | number | boolean): void {
  console.log(v);
}

자세한 것은 [[ts-union-intersection|Union / Intersection]] 참조.

Literal Type

let status: "pending" | "active" | "closed" = "pending";

type Direction = "north" | "south" | "east" | "west";

function move(dir: Direction): void {
  ...
}

move("north");       // OK
move("northwest");   // 오류

Enum 대신 자주 사용됨 (자세한 것은 [[ts-enums|Enums]] 참조)
상수의 타입을 그대로 표현

Object literal type

let user: {name: string, age: number} = {name: "kim", age: 30};

// Optional
let config: {debug?: boolean, port: number} = {port: 8000};

// Readonly
let point: {readonly x: number, readonly y: number} = {x: 1, y: 2};
point.x = 5;   // 오류

// Index signature
let scores: {[key: string]: number} = {alice: 90, bob: 85};

Interface 나 type alias 로 이름 붙이는 편이 관용.

Array

let ns: number[] = [1, 2, 3];
let ns2: Array<number> = [1, 2, 3];    // 동일

let matrix: number[][] = [[1, 2], [3, 4]];

// Readonly
let ro: readonly number[] = [1, 2, 3];
ro.push(4);       // 오류

Tuple

let pair: [string, number] = ["a", 1];
pair[0].toUpperCase();
pair[1].toFixed(2);

// Optional
let mixed: [string, number?] = ["a"];

// Named tuple
let range: [start: number, end: number] = [0, 100];

// Rest in tuple
let strs: [string, ...number[]] = ["a", 1, 2, 3];

자주 하는 실수

실수 1: `Number` (대문자)

let x: Number = 5;    // Boxed wrapper 타입, 사용 안 함
let y: number = 5;    // 정답 (primitive)

String, Boolean, Object 도 마찬가지. 대문자는 wrapper 객체 타입, 소문자가 primitive.

실수 2: `Object`

let x: Object = {};   // 거의 아무거나
let y: object = {};   // primitive 아닌 것
let z: {} = {};       // null/undefined 제외 모든 것

이 셋은 미묘하게 다르며 대개 원하는 건 명시적 shape ({name: string}) 이거나 Record<K, V>.

실수 3: `any` 남용

function f(x: any): any {
  return x.foo();
}

이 함수 안에서는 무엇이든 가능. 호출부에도 any 가 퍼짐. unknown 이나 정확한 시그니처로 대체.

함정

[!WARNING] any 는 감염됩니다. any 를 리턴하는 함수의 결과는 any. any 로부터 파생된 것들 모두 any. 초기부터 unknown 을 습관화.

[!CAUTION] null vs undefined. API 응답에서 필드가 없음 (undefined) 과 명시적 null 은 다름. 둘 다 처리하려면 x ?? default (nullish coalescing).

[!WARNING] Number.isNaN 을 씁시다. 전역 isNaN("abc") 은 true (문자열도 강제 형변환). Number.isNaN 만 정확한 NaN 검사.

[!IMPORTANT] bigint 는 JSON 안 됨. JSON.stringify(1n) 오류. 문자열 직렬화 후 파싱 필요.

[!CAUTION] unknown narrowing 을 잊지 마세요. unknown 은 안전하지만 그만큼 사용 전에 검증 필수.

[TypeScript] Strict Mode & tsconfig

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Strict Mode 는 여러 엄격한 타입 검사 플래그를 한 번에 켜는 tsconfig.json 옵션 (strict: true) 입니다. 강력한 타입 안전성을 제공하지만, 기존 코드베이스에는 대량의 오류를 발생시킬 수 있어 도입 시 계획이 필요합니다.

`strict: true` 로 켜지는 것

{
  "compilerOptions": {
    "strict": true
  }
}

이는 다음을 모두 활성화합니다:

noImplicitAny
strictNullChecks
strictFunctionTypes
strictBindCallApply
strictPropertyInitialization
noImplicitThis
useUnknownInCatchVariables
alwaysStrict

각각을 개별로 켜기도 가능.

`noImplicitAny`

암묵적 any 를 금지.

function log(msg) {            // 오류: msg 의 타입이 any
  console.log(msg);
}

function log(msg: string) {    // OK
  console.log(msg);
}

함정: 마이그레이션 초기에는 많은 오류. // @ts-nocheck 나 파일 단위 any 로 임시 완화.

`strictNullChecks`

null 과 undefined 를 값 있는 타입에 포함 안 함.

let name: string = null;       // 오류
let name: string | null = null;   // OK

function greet(name: string) { ... }
greet(null);                    // 오류
greet(undefined);               // 오류

Array.prototype.find 등이 자동으로 T | undefined 리턴:

const users = [{id: 1}, {id: 2}];
const found = users.find(u => u.id === 3);
found.id;   // 오류: found 는 undefined 일 수 있음

if (found) {
  found.id;   // OK
}

가장 중요한 옵션. 반드시 켜세요.

`strictFunctionTypes`

함수 매개변수 타입을 contravariant 로 검사 (더 엄격).

type Animal = {name: string};
type Dog = {name: string; bark(): void};

let f: (a: Animal) => void = (d: Dog) => d.bark();   // 오류 (strictFunctionTypes)

이 옵션 없이는 bivariant (덜 엄격) 로 허용됨. 안전성을 위해 켜세요.

예외: method 시그니처 (interface X { method(a: A): void }) 는 여전히 bivariant. 함수 필드 (interface X { method: (a: A) => void }) 만 strict.

`strictBindCallApply`

fn.call, fn.apply, fn.bind 를 엄격 검사.

function greet(name: string, age: number) { ... }

greet.call(null, "kim", 30);    // OK
greet.call(null, "kim");         // 오류: age 누락
greet.call(null, "kim", "thirty");   // 오류: age 타입 불일치

`strictPropertyInitialization`

Class field 가 constructor 에서 반드시 초기화.

class User {
  name: string;                  // 오류: constructor 에서 초기화 안 함
  email: string = "";             // OK: 기본값
  age!: number;                   // OK: definite assignment (외부에서 초기화 보장)

  constructor(name: string) {
    this.name = name;             // OK: constructor 에서
  }
}

`noImplicitThis`

this 의 타입이 암묵적 any 인 경우 오류.

function bad() {
  console.log(this.x);   // 오류: this 가 any
}

function good(this: {x: number}) {
  console.log(this.x);   // OK
}

`useUnknownInCatchVariables`

catch 절의 예외를 any 대신 unknown 으로.

try {
  ...
} catch (e) {
  e.message;              // 오류 (useUnknownInCatchVariables)
  if (e instanceof Error) {
    e.message;            // OK
  }
}

TS 4.4+ 에 도입. strict: true 로 자동 활성.

`alwaysStrict`

Emit 되는 JS 에 "use strict" 자동 삽입 + parse 시 strict mode.

Strict 외 자주 켜는 옵션

`noUncheckedIndexedAccess`

배열/객체 인덱스 접근이 T | undefined 를 리턴.

const arr: number[] = [1, 2, 3];
const x = arr[0];   // strict 만: number
                     // + noUncheckedIndexedAccess: number | undefined

const map: Record<string, string> = {};
const y = map["nokey"];   // + noUncheckedIndexedAccess: string | undefined

실전에서는 배열 접근이 자주 undefined 를 반환하므로 켜는 편이 안전. 하지만 for loop 등 이미 안전한 접근도 오류.

`noImplicitReturns`

함수의 모든 경로가 값을 리턴해야 함.

function example(x: boolean): string {
  if (x) return "yes";
  // 오류: else 경로가 return 없음
}

`noFallthroughCasesInSwitch`

Switch case 의 fall-through 를 오류.

switch (x) {
  case 1:
    doA();
    // 오류: break/return 없이 다음 case 로 떨어짐
  case 2:
    doB();
    break;
}

`noUnusedLocals`, `noUnusedParameters`

미사용 변수/파라미터 오류.

function f(a: number, b: number) {   // 오류: b 미사용
  return a * 2;
}

ESLint 로 처리하는 편이 관용 (더 유연).

`exactOptionalPropertyTypes`

x?: T 를 undefined 명시적 할당 금지.

type Opts = {debug?: boolean};

const o: Opts = {debug: undefined};   // 오류 (exactOptionalPropertyTypes)

미묘하지만 실전 케이스가 있어 켜는 프로젝트도 있음.

`noPropertyAccessFromIndexSignature`

Index signature 필드는 .foo 대신 ["foo"] 만 허용:

const obj: {[key: string]: string} = {a: "1"};

obj.a;         // 오류 (noPropertyAccessFromIndexSignature)
obj["a"];      // OK

명시적 필드와 index signature 를 구분하여 오타 방지.

권장 (2026 표준)

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "esnext",
    "moduleResolution": "bundler",
    "lib": ["ES2022", "DOM"],
    "jsx": "react-jsx",

    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true,

    "esModuleInterop": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "forceConsistentCasingInFileNames": true,

    "noEmit": true
  },
  "include": ["src/**/*"]
}

skipLibCheck: true 는 node_modules 의 .d.ts 검사 스킵 (성능). 대부분의 프로젝트에서 켜는 편.

Strict 도입 전략

1. 신규 프로젝트

처음부터 strict: true. 코드가 자연스럽게 strict 를 준수.

2. 기존 프로젝트

점진 도입:

Step 1: noImplicitAny: false 로 시작, 다른 strict 옵션 하나씩:

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": false
  }
}

Step 2: 파일별 // @ts-strict-ignore 로 opt-out (커스텀 도구 필요) 또는 // @ts-nocheck 로 개별 무시.

Step 3: 도구 (ts-migrate, type-coverage) 로 커버리지 측정, 점진 개선.

Step 4: 전 코드가 strict 준수하면 noImplicitAny: true 로.

3. tsc-baseline

에러를 기록해두고 새 오류만 실패시키는 도구. git bisect 스타일로 점진 개선.

성능 최적화

skipLibCheck: true: node_modules .d.ts 검사 스킵
incremental: true: .tsbuildinfo 캐시로 재컴파일 가속
composite: true: project reference 활성화 (모노레포)
--extendedDiagnostics: 컴파일 시간 프로파일

함정

[!WARNING] skipLibCheck: false 는 방대한 시간 소비. @types/* 안의 오류까지 검사. 특별한 이유 없으면 true.

[!CAUTION] strictPropertyInitialization + Reflect / DI. NestJS, TypeORM 등이 constructor 밖에서 필드 초기화하면 오류. ! 로 assert.

[!WARNING] noUncheckedIndexedAccess 는 광범위 영향. 모든 배열 인덱스 접근이 T | undefined. for-of 나 map 로 안전 접근하는 편이 관용.

[!IMPORTANT] strict 를 부분 활성화하면 명시. strict: true + 개별 false override 는 리팩토링 시 잊기 쉬움. 명시적 리스트가 유지보수 유리.

[!CAUTION] Emit 대상과 lib 불일치. target: "ES2022" + lib: ["ES2015"] 은 이상. lib 은 최소 target 이상.

[TypeScript] Template Literal Types

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Template Literal Type 은 TypeScript 4.1 에서 도입된 문법으로, JavaScript template literal 처럼 백틱과 ${...} 를 이용해 타입 레벨 에서 문자열을 조합/조작합니다. Union 분배, 내장 문자열 utility, mapped type / conditional type 조합으로 강력한 정적 계산이 가능합니다.

기본

type World = "world";
type Greeting = `hello ${World}`;   // "hello world"

type Cardinal = "north" | "south" | "east" | "west";
type Quadrant = `${Cardinal}-${Cardinal}`;
// = "north-north" | "north-south" | ... 총 16개

Union 안에서 자동 분배 (cartesian product).

내장 문자열 utility

Uppercase<S>
Lowercase<S>
Capitalize<S>: 첫 글자 대문자
Uncapitalize<S>: 첫 글자 소문자

type A = Uppercase<"hello">;      // "HELLO"
type B = Lowercase<"HELLO">;       // "hello"
type C = Capitalize<"hello">;      // "Hello"
type D = Uncapitalize<"Hello">;    // "hello"

Event Handler 이름

type EventName<T extends string> = `on${Capitalize<T>}`;

type A = EventName<"click">;       // "onClick"
type B = EventName<"mouseover">;    // "onMouseover"

Mapped 와 조합:

type EventHandlers<E extends string> = {
  [K in E as `on${Capitalize<K>}`]: (e: Event) => void;
};

type Handlers = EventHandlers<"click" | "hover" | "submit">;
// = {onClick: (e: Event) => void; onHover: ...; onSubmit: ...}

URL / Route 타이핑

type Route = `/users/${string}` | `/posts/${number}`;

const r1: Route = "/users/kim";        // OK
const r2: Route = "/posts/42";          // OK
const r3: Route = "/comments/1";        // 오류

Path parameter 추출

type ExtractParams<S extends string> =
  S extends `${string}:${infer P}/${infer R}`
    ? P | ExtractParams<R>
    : S extends `${string}:${infer P}`
    ? P
    : never;

type A = ExtractParams<"/users/:id/posts/:postId">;
// = "id" | "postId"

type RouteParams<S extends string> = {
  [K in ExtractParams<S>]: string;
};

type P = RouteParams<"/users/:id/posts/:postId">;
// = {id: string; postId: string}

Type-safe routing 의 기반.

Case conversion

SnakeToCamel

type SnakeToCamel<S extends string> =
  S extends `${infer H}_${infer R}`
    ? `${H}${Capitalize<SnakeToCamel<R>>}`
    : S;

type A = SnakeToCamel<"user_id">;           // "userId"
type B = SnakeToCamel<"created_at_utc">;     // "createdAtUtc"

CamelToSnake

type CamelToSnake<S extends string> =
  S extends `${infer H}${infer T}`
    ? T extends Uncapitalize<T>
      ? `${Uncapitalize<H>}${CamelToSnake<T>}`
      : `${Uncapitalize<H>}_${CamelToSnake<T>}`
    : S;

type A = CamelToSnake<"userId">;     // "user_id"
type B = CamelToSnake<"getName">;     // "get_name"

KebabCase, ScreamingSnake 등

type-fest 라이브러리에 이미 정의되어 있음. 재발명하기보다는 lookup.

Numeric parsing

type ParseInt<S extends string> =
  S extends `${infer N extends number}` ? N : never;

type A = ParseInt<"42">;    // 42
type B = ParseInt<"3.14">;   // 3.14
type C = ParseInt<"foo">;    // never

TypeScript 4.8+ 에서 ${infer N extends number} 문법으로 문자열을 숫자로 파싱 가능.

String Split

type Split<S extends string, D extends string> =
  S extends `${infer H}${D}${infer R}` ? [H, ...Split<R, D>] : [S];

type A = Split<"a,b,c", ",">;    // ["a", "b", "c"]
type B = Split<"1.2.3", ".">;    // ["1", "2", "3"]

String Join

type Join<T extends string[], D extends string> =
  T extends [] ? "" :
  T extends [infer F extends string] ? F :
  T extends [infer F extends string, ...infer R extends string[]]
    ? `${F}${D}${Join<R, D>}`
    : never;

type A = Join<["a", "b", "c"], "-">;   // "a-b-c"

실전: CSS unit

type CssUnit = "px" | "em" | "rem" | "%" | "vh" | "vw";
type CssValue = `${number}${CssUnit}` | `${number}` | "auto" | "inherit";

const v1: CssValue = "10px";      // OK
const v2: CssValue = "auto";       // OK
const v3: CssValue = "10bar";      // 오류

실전: Environment variable

type EnvKey = `NEXT_PUBLIC_${string}`;

function getEnv<K extends EnvKey>(key: K): string | undefined {
  return process.env[key];
}

getEnv("NEXT_PUBLIC_API_URL");   // OK
getEnv("DATABASE_URL");           // 오류

실전: SQL 유사

type SqlWhere<T> = {
  [K in keyof T]?: T[K] | `${string}${T[K] extends string ? "LIKE" : ""}${string}`;
};

// ... 실용성 낮음, 예시 정도

Distributive with template literal

type Prefix<S extends string> = `prefix_${S}`;

type A = Prefix<"a" | "b" | "c">;   // "prefix_a" | "prefix_b" | "prefix_c"

Union 이 자동 분배되어 각 요소에 대해 template 적용.

Cartesian product

type Combinations<A extends string, B extends string> = `${A}-${B}`;

type A = Combinations<"foo" | "bar", "1" | "2">;
// = "foo-1" | "foo-2" | "bar-1" | "bar-2"

함정

[!WARNING] 재귀 depth 제한 (50 정도). 매우 긴 문자열 파싱은 실패.

[!CAUTION] ${string} 은 모든 문자열 매칭. Loose 함. ${number} 로 명시하는 편이 안전.

[!WARNING] Capitalize<T> 는 T 가 string 이어야 함. Capitalize<string & K> 로 좁힘.

[!IMPORTANT] 성능. 대규모 template literal type 은 컴파일 시간 급증. Alias 로 캐시.

[!CAUTION] Runtime 에는 없음. Template literal type 은 컴파일 시만. 실제 문자열 조작은 JavaScript 로.

[TypeScript] Type Aliases

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Type Alias 는 타입에 이름을 붙이는 TypeScript 문법 (type Name = ...). Interface 는 객체 shape 만 표현하지만, type alias 는 모든 타입 표현식 (primitive, union, intersection, tuple, mapped, conditional 등) 에 이름을 붙일 수 있습니다.

기본 사용

type UserId = number;
type UserName = string;

type Point = {
  x: number;
  y: number;
};

type Callback = (result: string) => void;

type Direction = "north" | "south" | "east" | "west";

언제 type, 언제 interface

두 문법이 겹치는 영역이 넓지만, type 만 할 수 있는 것 이 많습니다.

type 만 할 수 있는 것

1. Primitive alias:

type EmailAddress = string;
type Duration = number;   // seconds

2. Union type:

type Status = "loading" | "success" | "error";
type Value = string | number | null;

3. Intersection type:

type Timestamped = {createdAt: Date; updatedAt: Date};
type User = {id: number; name: string};
type TimestampedUser = User & Timestamped;

4. Tuple:

type Point = [number, number];
type NamedPoint = [name: string, x: number, y: number];

5. Mapped type:

type ReadonlyUser = {readonly [K in keyof User]: User[K]};

6. Conditional type:

type Extract<T, U> = T extends U ? T : never;

7. Template literal type:

type Greeting = `Hello, ${string}`;

8. Utility type composition:

type PartialUser = Partial<User>;
type UserKeys = keyof User;

interface 만 할 수 있는 것

1. Declaration merging:

interface Window { myGlobal: string }
interface Window { another: number }
// = merged

2. Module augmentation (라이브러리 확장):

declare module "express" {
  interface Request {
    userId?: string;
  }
}

3. class implements 에 잘 맞음 (type 도 되지만 관용은 interface).

관용 선택 규칙

Object shape 이고 확장 필요 없음 -> type
Object shape 이고 declaration merging 필요 -> interface
Primitive alias, tuple, union, intersection, mapped, conditional -> type
라이브러리 사용자에게 확장 가능성 열어두기 -> interface
API response type (외부 데이터) -> type (zod schema 와 짝)

일관성 있게 선택. 팀 프로젝트는 한 스타일로 통일 이 무엇보다 중요 (ESLint 로 강제 가능).

Type Alias 는 새 타입이 아님

type UserId = number;
type ProductId = number;

const uid: UserId = 1;
const pid: ProductId = uid;   // OK! 둘 다 그냥 number

Type alias 는 별칭 이지 새 nominal type 이 아닙니다. 진짜 구분이 필요하면 branded type:

type Brand<T, B> = T & {__brand: B};
type UserId = Brand<number, "UserId">;
type ProductId = Brand<number, "ProductId">;

function createUserId(n: number): UserId { return n as UserId; }
function createProductId(n: number): ProductId { return n as ProductId; }

const uid = createUserId(1);
const pid: ProductId = uid;   // 오류

__brand 는 실제 필드가 아님 (컴파일 시 삭제). 순수 타입 트릭.

Generic Type Alias

type Nullable<T> = T | null;
type Optional<T> = T | undefined;
type Maybe<T> = T | null | undefined;

type ApiResponse<T> = {
  status: "ok" | "error";
  data?: T;
  error?: string;
};

type PromiseOrValue<T> = T | Promise<T>;

자세한 것은 [[ts-generics|Generics]] 참조.

Recursive Type Alias

type Json =
  | string
  | number
  | boolean
  | null
  | Json[]
  | {[key: string]: Json};

const value: Json = {
  name: "kim",
  age: 30,
  hobbies: ["read", "hike"],
  meta: {active: true},
};

Tree 구조도 재귀 표현:

type TreeNode<T> = {
  value: T;
  children: TreeNode<T>[];
};

Discriminated Union

type Shape =
  | {kind: "circle"; radius: number}
  | {kind: "square"; side: number}
  | {kind: "rectangle"; width: number; height: number};

function area(s: Shape): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.radius ** 2;
    case "square": return s.side ** 2;
    case "rectangle": return s.width * s.height;
  }
}

kind 필드 (discriminant) 로 union 을 좁힘. TypeScript 가 각 case 에서 정확한 타입으로 narrow.

자세한 것은 [[ts-narrowing|Type Narrowing]] 참조.

Function Type

type Handler = (event: Event) => void;
type Predicate<T> = (item: T) => boolean;
type Comparator<T> = (a: T, b: T) => -1 | 0 | 1;
type Middleware = (req: Request, res: Response, next: () => void) => void;

Generic:

type Mapper<T, U> = (item: T) => U;

const toString: Mapper<number, string> = (n) => n.toString();

Type Alias 안에서 keyof, typeof

type User = {id: number; name: string; email: string};

type UserKeys = keyof User;                    // "id" | "name" | "email"
type UserValues = User[keyof User];            // number | string
type UserIdType = User["id"];                  // number

// typeof 로 값에서 타입 추출
const CONFIG = {host: "localhost", port: 8080} as const;
type Config = typeof CONFIG;                   // {readonly host: "localhost", readonly port: 8080}
type ConfigKeys = keyof typeof CONFIG;         // "host" | "port"

as const 는 리터럴 타입 유지에 매우 유용.

Mapped Type

Object 의 모든 필드를 변형:

type Readonly<T> = {readonly [K in keyof T]: T[K]};
type Partial<T> = {[K in keyof T]?: T[K]};
type Required<T> = {[K in keyof T]-?: T[K]};
type Nullable<T> = {[K in keyof T]: T[K] | null};

자세한 것은 [[ts-mapped-types|Mapped Types]] 참조.

Conditional Type

type IsString<T> = T extends string ? true : false;
type A = IsString<"hi">;      // true
type B = IsString<42>;         // false

type ReturnType<F> = F extends (...args: any[]) => infer R ? R : never;
type X = ReturnType<() => number>;    // number

자세한 것은 [[ts-conditional-types|Conditional Types]] 참조.

Template Literal Type

type Greeting = `Hello, ${string}`;
type CssUnit = `${number}${"px" | "em" | "%"}`;

type EventName<T extends string> = `on${Capitalize<T>}`;
type ClickEvent = EventName<"click">;         // "onClick"

자세한 것은 [[ts-template-literal-types|Template Literal Types]] 참조.

Utility Type Composition

type User = {id: number; email: string; password: string; role: string};

type UserPublic = Omit<User, "password">;
type UserUpdate = Partial<Omit<User, "id">>;
type UserRole = Pick<User, "role">;
type UserKeys = keyof User;

자세한 것은 [[ts-utility-types|Utility Types]] 참조.

Type Alias 성능

같은 표현식을 여러 곳에서 반복하지 말고 alias 로 이름 붙이는 편이 컴파일 성능에 유리. 특히 mapped/conditional 조합은 캐시 히트가 중요.

// 반복 확장 (느림)
type A = {x: {a: number; b: string}; y: {a: number; b: string}; z: {a: number; b: string}};

// alias 로 캐시 (빠름)
type Inner = {a: number; b: string};
type A = {x: Inner; y: Inner; z: Inner};

함정

[!WARNING] Type alias 는 새 타입이 아님. Branded type 없이 type UserId = number 는 다른 number 와 호환.

[!CAUTION] Recursive type 은 컴파일 성능 영향. 재귀 깊이가 깊거나 조건 분기가 많으면 느려짐. 필요시 Depth 파라미터로 재귀 제한.

[!WARNING] as const 를 잊으면 리터럴이 넓어짐. const CONFIG = {port: 8080} 은 {port: number} 로 넓혀짐. Literal 유지하려면 as const.

[!IMPORTANT] Interface vs Type 을 팀에서 통일. 두 방식 섞이면 리팩토링 혼란. ESLint @typescript-eslint/consistent-type-definitions.

[!CAUTION] type X = {} & Y 같은 no-op intersection 은 컴파일러가 그대로 유지. 성능 손실.

[TypeScript] Type Narrowing (Type Guards)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Type Narrowing 은 TypeScript 컴파일러가 제어 흐름 분석 (control flow analysis) 을 통해 특정 위치에서 값의 타입을 더 좁게 추론하는 기능입니다. typeof, instanceof, in, 리터럴 비교, 사용자 정의 type guard 로 union 을 각 branch 별 구체 타입으로 좁힙니다.

`typeof` narrowing

primitive 타입 (string, number, boolean, bigint, symbol, undefined, object, function) 검사.

function padLeft(padding: number | string, input: string): string {
  if (typeof padding === "number") {
    return " ".repeat(padding) + input;   // padding: number
  }
  return padding + input;                  // padding: string
}

`instanceof` narrowing

class Cat { meow() {} }
class Dog { bark() {} }

function pet(x: Cat | Dog): void {
  if (x instanceof Cat) {
    x.meow();     // x: Cat
  } else {
    x.bark();     // x: Dog
  }
}

함정: interface 는 instanceof 못 씀 (런타임에 없음). class 여야 함.

`in` operator

객체에 특정 필드가 있는지 검사.

type Cat = {meow(): void};
type Dog = {bark(): void};

function pet(x: Cat | Dog): void {
  if ("meow" in x) {
    x.meow();     // x: Cat
  } else {
    x.bark();     // x: Dog
  }
}

Interface (런타임 정보 없음) 에도 적용 가능.

Truthiness narrowing

function getLength(s: string | null | undefined): number {
  if (s) {
    return s.length;    // s: string (null, undefined, "" 배제)
  }
  return 0;
}

주의: if (s) 는 falsy 모두 배제. "", 0, false, NaN, null, undefined. 명시적으로 원하는 것만 배제:

if (s !== null && s !== undefined) { ... }
if (s != null) { ... }              // == null 은 null + undefined

Equality narrowing

리터럴 비교로 좁힘:

function example(x: string | number, y: string | boolean): void {
  if (x === y) {
    // 둘 다 string 이어야 == 가능
    x.toUpperCase();   // x: string
    y.toUpperCase();   // y: string
  }
}

Discriminated Union

Union 의 각 case 에 리터럴 필드 (discriminant) 를 두어 좁힘.

type Shape =
  | {kind: "circle"; radius: number}
  | {kind: "square"; side: number};

function area(s: Shape): number {
  if (s.kind === "circle") {
    return Math.PI * s.radius ** 2;   // s: {kind: "circle", radius: number}
  }
  return s.side ** 2;                  // s: {kind: "square", side: number}
}

자세한 것은 [[ts-union-intersection|Union / Intersection]] 참조.

Assignment narrowing

let x: string | number;
x = "hello";
x.toUpperCase();     // x: string
x = 42;
x.toFixed(2);         // x: number

Assignment 이후 실제 타입으로 좁혀짐. 이 좁힘은 다음 재할당까지 유효.

Control flow analysis

TypeScript 는 return, throw, continue 등을 인식.

function process(x: string | null): string {
  if (x === null) {
    throw new Error("null!");
  }
  return x.toUpperCase();    // x: string (null 은 throw 로 배제됨)
}

User-Defined Type Guard (`is`)

함수의 return type 을 arg is Type 으로 선언하면 컴파일러가 그 함수를 type guard 로 인식.

interface Cat { meow(): void }
interface Dog { bark(): void }

function isCat(x: Cat | Dog): x is Cat {
  return "meow" in x;
}

function pet(x: Cat | Dog): void {
  if (isCat(x)) {
    x.meow();     // x: Cat
  } else {
    x.bark();     // x: Dog
  }
}

실전 예시

function isNonNull<T>(v: T | null | undefined): v is T {
  return v != null;
}

const users = [user1, null, user3, undefined, user5];
const validUsers = users.filter(isNonNull);
// validUsers: User[] (User | null | undefined 에서 좁혀짐)

배열 filter narrowing (TS 5.5+)

TypeScript 5.5 부터는 filter 안 predicate 를 자동으로 type guard 로 인식:

const validUsers = users.filter((u): u is User => u != null);
// 또는 5.5+ 에서는 자동
const validUsers = users.filter(u => u != null);

Assertion Function (`asserts`)

함수가 조건 검증에 실패하면 예외 던짐. 이후 코드는 조건이 참이라고 가정.

function assertNumber(x: unknown): asserts x is number {
  if (typeof x !== "number") {
    throw new Error("not a number");
  }
}

function process(x: unknown): void {
  assertNumber(x);
  x.toFixed(2);    // x: number (이 시점부터 좁혀짐)
}

assertNever (exhaustive check)

function assertNever(x: never): never {
  throw new Error(`unexpected: ${x}`);
}

function area(s: Shape): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.radius ** 2;
    case "square": return s.side ** 2;
    default: return assertNever(s);
  }
}

새 case 를 추가하면 컴파일 시 오류. Discriminated union 의 필수 도구.

비타 - Node.js assert 모듈과 통합


function process(x: unknown): void {
  assert(typeof x === "string");
  x.toUpperCase();    // x: string
}

node:assert 는 asserts 를 반환하므로 자동 narrowing 대상.

Array narrowing

function last<T>(arr: T[]): T | undefined {
  if (arr.length > 0) {
    return arr[arr.length - 1];   // 여전히 T | undefined
  }
  return undefined;
}

arr.length > 0 은 배열의 element 타입에 영향 없음 (T[] 여도 arr[i] 는 T | undefined 로 좁혀지지 않음. 그럼에도 접근 가능한 이유는 strictNullChecks 만으로는 noUncheckedIndexedAccess 없이 배열 접근이 T 로 낙관 취급됨).

noUncheckedIndexedAccess: true 활성 시 arr[i] 는 T | undefined.

in-operator narrowing 심화

TS 4.9+: in 이 optional 필드도 좁힘.

type Cat = {meow(): void; name?: string};
type Dog = {bark(): void; name?: string};

function example(x: Cat | Dog): void {
  if ("meow" in x) {
    x.meow();
    // x.name?: string  (optional 필드)
  }
}

Class field narrowing

class Animal {
  static isCat(x: Animal): x is Cat {
    return x instanceof Cat;
  }
}

Static method 로 type guard.

함정

[!WARNING] typeof null === "object". null 검사는 별도. if (typeof x === "object" && x !== null).

[!CAUTION] instanceof 는 class 만. Interface, type alias 로 정의된 것에는 못 씀.

[!WARNING] User-defined type guard 는 신뢰의 문제. function isCat(x): x is Cat { return true } 도 컴파일 통과. 실제 검증을 정확히 해야.

[!IMPORTANT] asserts 는 반드시 예외 던지거나 return 안 함. 반환하면 assertion 이 아님. never 반환 타입도 고려.

[!CAUTION] Truthiness narrowing 의 부작용. if (x) 는 falsy 모두 배제. "", 0 이 유효값이면 명시적 != null 사용.

[!WARNING] in narrowing 은 상속 필드 못 검사. Prototype chain 상 없어도 in 은 true. Own property 만 체크는 Object.hasOwn.

[TypeScript] Union & Intersection Types

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Union Type (A | B): A 이거나 B (또는 둘 다) 인 값
Intersection Type (A & B): A 이면서 B 인 값

두 조합은 TypeScript 의 타입 시스템에서 가장 자주 쓰이는 도구입니다.

Union Type

let id: string | number = "abc";
id = 42;
id = true;    // 오류

function print(v: string | number): void {
  console.log(v);
}

Union 사용 시 narrowing 필요

function print(v: string | number): void {
  v.toUpperCase();          // 오류: number 에는 없음

  if (typeof v === "string") {
    v.toUpperCase();        // OK: string 으로 좁혀짐
  } else {
    v.toFixed(2);           // OK: number
  }
}

자세한 것은 [[ts-narrowing|Type Narrowing]] 참조.

Union 의 공통 부분

여러 타입의 공통 필드/메서드만 union 그 자체에서 접근 가능:

type Cat = {name: string; meow(): void};
type Dog = {name: string; bark(): void};

function greet(pet: Cat | Dog): void {
  console.log(pet.name);   // OK: 둘 다 name 가짐
  pet.meow();               // 오류: Dog 에는 meow 없음
}

Discriminated Union (Tagged Union)

Union 의 각 case 에 공통 리터럴 필드 (discriminant) 를 두어 TypeScript 가 case 별로 정확히 좁힘:

type Shape =
  | {kind: "circle"; radius: number}
  | {kind: "square"; side: number}
  | {kind: "rectangle"; width: number; height: number};

function area(s: Shape): number {
  switch (s.kind) {
    case "circle":
      return Math.PI * s.radius ** 2;       // s: {kind: "circle", radius: number}
    case "square":
      return s.side ** 2;                    // s: {kind: "square", side: number}
    case "rectangle":
      return s.width * s.height;             // s: {kind: "rectangle", ...}
  }
}

Exhaustive check (never)

function area(s: Shape): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.radius ** 2;
    case "square": return s.side ** 2;
    case "rectangle": return s.width * s.height;
    default:
      const _exhaustive: never = s;
      return _exhaustive;
  }
}

// 새 case 추가 시
type Shape = ... | {kind: "triangle"; base: number; height: number};

// _exhaustive: never = s  ->  s 가 triangle 이라 never 에 할당 불가 = 컴파일 오류

새 case 를 놓치지 않게 하는 강력한 패턴.

Result / Either

type Result<T, E = Error> =
  | {ok: true; value: T}
  | {ok: false; error: E};

async function fetchUser(id: number): Promise<Result<User>> {
  try {
    const user = await api.getUser(id);
    return {ok: true, value: user};
  } catch (e) {
    return {ok: false, error: e as Error};
  }
}

const r = await fetchUser(1);
if (r.ok) {
  console.log(r.value.name);   // r: {ok: true, value: User}
} else {
  console.error(r.error);       // r: {ok: false, error: Error}
}

Rust 의 Result 패턴을 그대로.

Intersection Type

type Named = {name: string};
type Aged = {age: number};

type Person = Named & Aged;

const p: Person = {name: "kim", age: 30};

여러 interface 병합

interface HasId {id: number}
interface HasCreatedAt {createdAt: Date}
interface HasName {name: string}

type Entity = HasId & HasCreatedAt & HasName;

Mixin 스타일

type Loggable = {log(): void};
type Cacheable = {cache(): void};

class Service implements Loggable & Cacheable {
  log(): void { ... }
  cache(): void { ... }
}

Intersection with union

type A = {x: number} | {y: number};
type B = {z: number};

type C = A & B;
// = ({x: number} & {z: number}) | ({y: number} & {z: number})
// = {x: number, z: number} | {y: number, z: number}

Distributive.

함정: 충돌하는 필드

type A = {value: string};
type B = {value: number};

type C = A & B;    // C.value: string & number = never
const c: C = {value: "hi"};    // 오류 (never 에 할당 불가)

같은 필드 이름에 호환 안 되는 타입이 있으면 never.

Union vs Intersection 의미론

Union (|):

값 관점: A 값들의 집합 ∪ B 값들의 집합
타입 관점: A 이거나 B (알려진 것보다 적은 정보)
접근: 공통 필드만 안전

Intersection (&):

값 관점: A 값들의 집합 ∩ B 값들의 집합
타입 관점: A 이면서 B (더 많은 정보)
접근: A 의 모든 것 + B 의 모든 것

직관 정리:

개인 = 학생 ∨ 회사원 (union)
학생회장 = 학생 ∧ 리더 (intersection)

함수 매개변수의 union / intersection

Contravariance: 매개변수는 반전됨.

type F1 = (x: string) => void;
type F2 = (x: number) => void;

type Both1 = F1 | F2;    // (x: string) => void  |  (x: number) => void
type Both2 = F1 & F2;    // (x: string & number) => void = (x: never) => void

& 로 조합된 함수는 더 넓은 인자 를 받아야 함 (실제 호출 가능한 값이 좁아짐).

리턴 타입은 covariance:

type G1 = () => {a: number};
type G2 = () => {b: string};

type Return1 = G1 | G2;      // () => {a: number} | () => {b: string}
type Return2 = G1 & G2;      // () => {a: number} & {b: string} = {a, b}

Nullable 패턴

type Nullable<T> = T | null;
type Optional<T> = T | undefined;
type Maybe<T> = T | null | undefined;

function parseId(s: string): Maybe<number> {
  const n = parseInt(s, 10);
  return isNaN(n) ? null : n;
}

`keyof` union

keyof T 는 T 의 필드 이름 union:

type User = {id: number; name: string; email: string};
type UserKeys = keyof User;    // "id" | "name" | "email"

function get<K extends UserKeys>(user: User, key: K): User[K] {
  return user[key];
}

실전: State machine

type State =
  | {status: "idle"}
  | {status: "loading"; requestId: string}
  | {status: "success"; data: string}
  | {status: "error"; error: Error};

function reducer(state: State, action: Action): State {
  switch (state.status) {
    case "idle":
      if (action.type === "fetch") {
        return {status: "loading", requestId: action.id};
      }
      return state;
    case "loading":
      if (action.type === "success") {
        return {status: "success", data: action.data};
      }
      if (action.type === "fail") {
        return {status: "error", error: action.error};
      }
      return state;
    // ...
  }
}

각 status 별로 접근 가능한 필드가 자동으로 좁혀짐.

실전: Options 병합

type BaseOptions = {name: string};
type WithTimeout = {timeout: number};
type WithRetry = {retry: number; retryDelay: number};

type Options =
  | BaseOptions
  | (BaseOptions & WithTimeout)
  | (BaseOptions & WithRetry)
  | (BaseOptions & WithTimeout & WithRetry);

// 또는 단순화
type Options = BaseOptions & Partial<WithTimeout> & Partial<WithRetry>;

함정

[!WARNING] Discriminant 없는 union 은 좁히기 어려움. A | B 두 shape 이 겹치면 typeof 로 안 됨. Discriminant field (kind, type) 추가가 관용.

[!CAUTION] {value: string} & {value: number} = never. 호환 안 되는 필드 병합은 never. 실수로 발생하면 조용히 오류.

[!WARNING] Union 분배 (extends). T extends U ? X : Y 에서 T 가 union 이면 자동 분배. 원치 않으면 [T] extends [U] 로 tuple.

[!IMPORTANT] Function overload 대신 union. 매개변수가 여러 타입이면 union 시그니처 하나로 표현 가능한 경우 많음.

[!CAUTION] Intersection 은 나열 순서와 무관. A & B = B & A. 필드 충돌 시 우측이 이긴다고 오해 금물.

TypeScript

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

TypeScript 는 Microsoft 가 2012년 발표한 JavaScript 의 상위 집합 프로그래밍 언어입니다. 정적 타입 시스템, 인터페이스, 제네릭, enum, 데코레이터, 모듈 시스템 등을 추가하며, 컴파일 시 순수 JavaScript 로 변환됩니다.

핵심 원리: TypeScript 는 JavaScript + 타입 어노테이션. 런타임에는 타입이 지워집니다 (type erasure). 타입은 오직 컴파일 시 정적 검사와 IDE 지원 목적입니다.

왜 TypeScript 인가

1. 정적 타입 검사

function greet(name: string): string {
  return `Hello, ${name}`;
}

greet(42);   // 컴파일 오류

버그를 컴파일 시점에 잡습니다. 대규모 코드베이스에서 리팩토링, 함수 시그니처 변경 안전성이 크게 향상.

2. IDE 지원

자동완성 (엄밀한 시그니처 기반)
Rename symbol (다중 파일 안전)
Go to definition
Find all references
Inline hint

3. 명세로서의 타입

함수 시그니처가 문서 역할. function process(items: Item[], options?: Options): Promise<Result[]> 만 봐도 사용법 이해.

4. 마이그레이션 유연성

점진 도입: .js 를 .ts 로 하나씩 변환
any 로 임시 회피 후 점진 좁히기
JSDoc 로 순수 JS 에도 부분 타입 지원

5. 방대한 생태계

DefinitelyTyped: 8,000+ npm 패키지의 타입 정의
주요 프레임워크 (React, Vue, Angular, Next.js, NestJS, Deno, Bun) 가 TS first

Hello World

npm install -D typescript
npx tsc --init          # tsconfig.json 생성

// hello.ts
const greeting: string = "Hello, TypeScript";
console.log(greeting);

interface User {
  id: number;
  name: string;
}

function greet(user: User): string {
  return `Hi, ${user.name}`;
}

greet({id: 1, name: "kim"});

npx tsc hello.ts        # -> hello.js
node hello.js

컴파일 파이프라인

[.ts / .tsx 소스]
     ↓ tsc (또는 esbuild, swc, bun)
[.js / .jsx]
     ↓ 번들러 (Webpack, Vite, esbuild, Rollup)
[번들.js]

tsc: 공식 컴파일러. 타입 검사 + JS 생성.
esbuild / swc: 매우 빠른 컴파일러. 타입 검사 없이 JS 변환만 (검사는 tsc --noEmit 별도).
bun: 자체 컴파일러 + 런타임.
ts-node, tsx: 개발 시 즉시 실행.

관용: 프로덕션은 tsc (검사) + esbuild/vite (번들) 조합. tsc 는 검사만 하고, 실제 변환은 빠른 도구.

타입 시스템 개요

TypeScript 의 타입 시스템은 structural typing (“duck typing” 정적 버전).

interface Named { name: string }
interface Aged { age: number }

class Person {
  name: string = "";
  age: number = 0;
}

const p: Named = new Person();   // OK, Person 이 name 을 가짐
const a: Aged = new Person();    // OK, Person 이 age 를 가짐

Java/C# 의 nominal typing (이름 기반) 과 다름. 이름이 아니라 shape (형태) 로 판단.

주요 타입 카테고리

[[ts-primitive-types|Primitive]]: string, number, boolean, bigint, symbol, null, undefined, void, never, unknown, any
Object: {name: string}, Record<K, V>
Array: number[], Array<number>
Tuple: [string, number]
Function: (a: number, b: number) => number
Union / Intersection: A | B, A & B (참고: [[ts-union-intersection|Union/Intersection]])
[[ts-generics|Generic]]: <T>, <T extends string>
Literal: "hello", 42, true
Template Literal: `hello_${string}` (참고: [[ts-template-literal-types|Template Literal Types]])
Enum (참고: [[ts-enums|Enums]])

3가지 특별 타입

`any`

모든 타입 무시. 타입 안전성을 끔.

let x: any = 5;
x = "hello";
x.foo.bar();   // 컴파일 통과, 런타임 오류

any 는 급한 마이그레이션 시 임시 도구. 프로덕션 코드에서 남용 금지. strict 모드에서 amberflex enabled 하는 것이 관용.

`unknown`

타입을 모른다. 하지만 any 와 달리 narrowing 없이 사용 불가:

let x: unknown = 5;
x.toUpperCase();          // 오류: unknown 에는 접근 불가

if (typeof x === "string") {
  x.toUpperCase();        // OK: narrowing 후
}

외부에서 오는 값 (JSON.parse, API 응답) 은 any 대신 unknown 을 쓰고 검증 후 좁히는 것이 안전.

`never`

절대 발생하지 않는 값. 오류 던지는 함수, exhaustive check 에 쓰임.

function assertNever(x: never): never {
  throw new Error(`Unexpected: ${x}`);
}

type Shape = {kind: "circle", r: number} | {kind: "square", s: number};

function area(s: Shape) {
  switch (s.kind) {
    case "circle": return Math.PI * s.r ** 2;
    case "square": return s.s ** 2;
    default: return assertNever(s);   // 새 case 추가 시 컴파일 오류
  }
}

tsconfig.json

TypeScript 프로젝트 설정. 핵심 옵션:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "esnext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,               // esbuild 가 emit 하는 경우
    "jsx": "react-jsx",
    "lib": ["ES2022", "DOM"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

자세한 것은 [[ts-strict-mode|Strict Mode & tsconfig]] 참조.

주요 문법 요약

변수 타입

let name: string = "kim";
let age: number = 30;
let isAdmin: boolean = false;
let ids: number[] = [1, 2, 3];
let user: {name: string, age: number} = {name: "kim", age: 30};

타입 추론 (inference) 이 강력하므로 대개 명시 불필요:

const name = "kim";     // 자동으로 string 리터럴 타입
let count = 0;          // let 은 number

함수

function add(a: number, b: number): number {
  return a + b;
}

const multiply = (a: number, b: number): number => a * b;

// 매개변수 기본값
function greet(name: string = "world"): string {
  return `Hello, ${name}`;
}

// Optional
function log(msg: string, level?: string): void {
  ...
}

// Rest
function sum(...nums: number[]): number {
  return nums.reduce((a, b) => a + b, 0);
}

클래스

class Animal {
  protected name: string;
  private _id: number;

  constructor(name: string) {
    this.name = name;
    this._id = Math.random();
  }

  greet(): void {
    console.log(`Hi, ${this.name}`);
  }
}

class Dog extends Animal {
  bark(): void {
    console.log("Woof!");
  }
}

Constructor parameter properties:

class User {
  constructor(
    public name: string,
    private age: number,
    readonly id: number,
  ) {}
}
// name, age, id 자동으로 인스턴스 필드

인터페이스 vs Type alias

interface User {
  id: number;
  name: string;
}

type User = {
  id: number;
  name: string;
};

거의 상호 교환. 차이점은 [[ts-interfaces|Interfaces]] 와 [[ts-type-aliases|Type Aliases]] 참조.

자주 쓰는 도구

eslint + @typescript-eslint: 린트
prettier: 포매팅
vitest / jest: 테스트
zod / valibot / arktype: 런타임 검증 + 타입 추론
tsx / ts-node / bun run: 즉시 실행
type-fest: 유용한 유틸 타입 모음
tsc-baseline: 대량 오류 baseline

TypeScript 언어 발전 (최근)

5.0 (2023): 표준 Decorators (TC39 Stage 3), const type parameter, all-in-one moduleResolution
5.1 (2023): @returns return type
5.2 (2023): using (explicit resource management)
5.3 (2023): Import attributes
5.4 (2024): NoInfer<T> 타입
5.5 (2024): Inferred type predicates, Set methods
5.6 (2024): Disallowed nullish and truthy checks
5.7 (2024): Path Rewriting, checks for never-initialized variables
6.0 (2025+ 예정)

Release note 는 TypeScript 사이트 참조.

TypeScript vs 다른 언어

기준	TS	Flow	Dart	Kotlin
관계	JS 상위 집합	JS 상위 집합	별개 언어	JVM 언어
채택	지배적	감소	Flutter 특화	Android/서버
타입 시스템	강력, 실용적	유사	유사	유사
트랜스파일	JS	JS	JS/native	JVM/JS/native

결론: 2020년대 웹/Node.js 프로젝트의 사실상 표준.

김신건의 로그 - 위키 / typescript

[TypeScript] Conditional Types

정의

기본

조건 분기 흐름

예: 표준 utility 재구현

NonNullable

Exclude

Extract

Distributive Conditional Types

infer 키워드

예제

재귀 (Awaited)

조건 분기 심화

함수 오버로드 감지

tuple 분해

재귀 tuple 처리

Distributive union filtering

조건부 필드 매칭

Higher-order utility

Type-level parser

Chain of conditionals

함정

관련 위키

[TypeScript] Generics

정의

왜 필요한가

개념 흐름

Generic 함수

여러 type parameter

Generic arrow function

Constraint (extends)

keyof constraint

여러 constraint

Default type

Generic Interface

Generic Type Alias

Generic Class

Generic Constraint 심화

Constraint + default

Constraint with union

Generic + literal type

Generic Parameter 로 함수 오버로드 대체

infer 키워드

const type parameter (TS 5.0+)

NoInfer<T> (TS 5.4+)

Generic 성능 팁

실전 예시

React useState

배열 map/filter

Async wrapper

Event emitter

함정

관련 위키

[TypeScript] Utility Types

정의

유틸리티 타입 계보

Object 변형

Partial<T> - 모든 필드를 optional

Required<T> - 모든 필드를 required

Readonly<T> - 모든 필드를 readonly

필드 선택

Pick<T, K> - 특정 필드만

Omit<T, K> - 특정 필드 제외

Record (사전)

Record<K, V> - K 키의 사전

Union 조작

Exclude<T, U> - T 에서 U 제거

Extract<T, U> - T 에서 U 와 겹치는 것만

NonNullable<T> - null / undefined 제거

Function 관련

ReturnType<F> - 함수 반환 타입

Parameters<F> - 함수 매개변수 타입 (tuple)

ConstructorParameters<C> - 생성자 매개변수

InstanceType<C> - 클래스 인스턴스 타입

ThisParameterType<F> / OmitThisParameter<F>

Promise 관련

Awaited<T> - Promise 를 unwrap (재귀)

String 조작

Uppercase<S>, Lowercase<S>, Capitalize<S>, Uncapitalize<S>

`NonNullable`

`Exclude`

`Extract`

`infer` 키워드

재귀 (`Awaited`)

`const` type parameter (TS 5.0+)

`NoInfer<T>` (TS 5.4+)

`Partial<T>` - 모든 필드를 optional

`Required<T>` - 모든 필드를 required

`Readonly<T>` - 모든 필드를 readonly

`Pick<T, K>` - 특정 필드만

`Omit<T, K>` - 특정 필드 제외

`Record<K, V>` - K 키의 사전

`Exclude<T, U>` - T 에서 U 제거

`Extract<T, U>` - T 에서 U 와 겹치는 것만

`NonNullable<T>` - null / undefined 제거

`ReturnType<F>` - 함수 반환 타입

`Parameters<F>` - 함수 매개변수 타입 (tuple)

`ConstructorParameters<C>` - 생성자 매개변수

`InstanceType<C>` - 클래스 인스턴스 타입

`ThisParameterType<F>` / `OmitThisParameter<F>`

`Awaited<T>` - Promise 를 unwrap (재귀)

`Uppercase<S>`, `Lowercase<S>`, `Capitalize<S>`, `Uncapitalize<S>`

`type-fest` 확장

`declaration: true` (라이브러리 빌드)

1. `isolatedModules` 하에서 `const enum` 불가