[TYPESCRIPT] Template Literal Types 활용 전략: 문자열을 타입으로 안전하게 조작하는 방법

 

TypeScript를 사용하다 보면 문자열 때문에 타입 안정성이 무너지는 순간을 자주 겪게 됩니다. API 경로, 이벤트 이름, 상태 코드, 로그 타입처럼 “문자열이지만 규칙이 있는 값”들이 대표적입니다.

 

실무에서 흔히 겪는 문제는 다음과 같습니다.

• 문자열 오타로 런타임 에러가 발생한다
• 문자열 규칙이 문서에만 있고 코드에는 없다
• 상수로 관리하려다 오히려 관리 포인트가 늘어난다

 

Template Literal Types는 이런 문제를 해결하기 위해 등장한 기능입니다. 이번 글에서는 Template Literal Types를 “타입 트릭”이 아니라 문자열 규칙을 코드로 고정하는 실무 도구로 사용하는 기준을 정리합니다.

 

개념/배경 설명

Template Literal Types는 문자열 리터럴 타입을 조합해서 새로운 문자열 타입을 만들어내는 기능입니다. JavaScript의 템플릿 문자열과 문법은 비슷하지만, 목적은 전혀 다릅니다.

 

• 값을 만들기 위한 기능이 아니다
• 문자열 패턴을 제한하기 위한 기능이다
• “될 수 있는 문자열”의 집합을 정의한다

 

잘못 사용하면 타입만 복잡해지고, 잘 사용하면 문자열 관련 버그를 구조적으로 제거할 수 있습니다.

 

문자열 상수 대신 패턴을 정의한다

먼저 가장 단순한 사용 사례부터 보겠습니다.

 

// 기존 방식
type EventName =
  | 'USER_CREATED'
  | 'USER_UPDATED'
  | 'ORDER_CREATED';

 

이 방식은 명확하지만, 이벤트가 늘어날수록 관리 비용이 커집니다.

 

// Template Literal Types 활용
type Entity = 'USER' | 'ORDER';
type Action = 'CREATED' | 'UPDATED';

type EventName = `${Entity}_${Action}`;

 

이제 EventName은

• USER_CREATED
• USER_UPDATED
• ORDER_CREATED
• ORDER_UPDATED

 

로 자동 제한됩니다. 새로운 문자열을 추가할 때, 규칙만 추가하면 됩니다.

 

실무 포인트 정리

• 문자열 목록이 아니라 조합 규칙을 만든다
• 중복보다 규칙 표현을 우선한다
• 문자열 의미가 분리될 수 있을 때 적합하다

 

API 경로와 권한 키에 적용한다

Template Literal Types는 API, 권한, 설정 키처럼 “형식이 고정된 문자열”에 특히 효과적입니다.

 

type Resource = 'user' | 'order';
type Method = 'read' | 'write';

type PermissionKey = `${Resource}:${Method}`;

 

이 타입은 다음을 보장합니다.

• user:read
• user:write
• order:read
• order:write

 

오타나 규칙 위반 문자열은 컴파일 단계에서 바로 차단됩니다.

 

실무 포인트 정리

• 권한/설정 문자열은 반드시 규칙이 있다
• 문자열 규칙은 타입으로 고정한다
• 런타임 검증보다 컴파일 검증이 빠르다

 

문자열을 분해해서 다시 조합한다

Template Literal Types는 문자열을 “조합”할 뿐 아니라 “분해”에도 사용할 수 있습니다.

 

type ParseEvent<T> =
  T extends `${infer E}_${infer A}`
    ? { entity: E; action: A }
    : never;

 

이 타입을 사용하면,

 

type Parsed = ParseEvent<'USER_CREATED'>;
// { entity: 'USER'; action: 'CREATED' }

 

문자열 기반 규칙을 타입 레벨에서 구조화할 수 있습니다.

 

실무 포인트 정리

• 문자열을 구조화된 데이터처럼 다룰 수 있다
• 로그 타입, 이벤트 타입에 특히 유용하다
• 분해 로직은 단순할수록 좋다

 

실무에서 바로 쓰는 패턴

다음은 로그 타입을 안전하게 정의하는 예시입니다.

 

type LogDomain = 'AUTH' | 'PAYMENT';
type LogLevel = 'INFO' | 'ERROR';

type LogType = `${LogDomain}_${LogLevel}`;

function log(type: LogType, message: string) {
  // ...
}

 

이제 log 함수는 정해진 로그 타입만 받을 수 있고, 잘못된 문자열은 컴파일 단계에서 차단됩니다.

 

운영/실무에서 자주 겪는 문제

• Template Literal Types를 과도하게 중첩한 경우
• 의미 없는 조합까지 허용되는 구조
• 문자열 규칙보다 타입 구조가 먼저 보이는 코드
• 팀원이 타입을 추적하기 어려운 상황

 

이 문제들은 대부분 “문자열을 보호하려다 타입이 목적이 된 경우”에 발생합니다.

 

실무 권장 체크리스트

• 이 문자열에 명확한 규칙이 존재하는가
• 상수 나열보다 규칙 표현이 더 단순한가
• 허용되면 안 되는 문자열을 실제로 막고 있는가
• 타입 이름만 보고 의도를 이해할 수 있는가
• 팀원이 규칙을 타입에서 바로 파악할 수 있는가

 

---

 

Template Literal Types의 핵심은 문자열을 멋지게 만드는 것이 아니라, 문자열을 실수할 수 없는 값으로 만드는 것입니다.

규칙이 있는 문자열을 문서나 주석에 맡기지 말고, 타입으로 고정하면 문자열은 더 이상 취약한 영역이 아니라 안정적인 인터페이스가 됩니다.