TypeScript로 타입 있는 설정 로더를 만들 때는 보통 YAML 파일과 손으로 쓴 인터페이스가 짝이 되는데, 둘은 시간이 갈수록 어긋납니다. 이 변환기는 yaml 라이브러리(YAML 1.2 코어 스키마)로 파일을 읽고 앵커와 병합 키를 펼친 뒤, 발견한 모든 매핑에 대해 선언을 씁니다. 그래서 타입은 입력한 글자가 아니라 yaml.parse 같은 로더가 런타임에 돌려주는 값을 설명합니다.
같은 위치의 값은 하나로 합쳐 추론합니다. 매핑 목록은 모든 항목의 키를 합친 인터페이스 하나가 되고, 일부 항목에 없는 키는 key?: T로 적히며, null은 타입을 망가뜨리지 않고 | null을 더합니다. 루트 타입 이름(기본 ApiResponse), interface와 type 별칭, export와 readonly 켜고 끄기, 알 수 없는 값을 unknown으로 할지 any로 할지 정할 수 있습니다.
입력하는 동안 결과가 갱신되며 API 응답, 앵커와 병합 키, 엣지 케이스 예제가 있습니다. 모든 처리는 브라우저에서 이루어지고 업로드되지 않으며 입력은 20MiB까지입니다.
사용 방법
YAML 붙여 넣기 또는 예제 고르기
문서를 붙여 넣거나
.yaml파일을 편집기에 끌어다 놓고, 예제 칩을 고를 수도 있습니다. 루트는 매핑이든 목록이든 괜찮고 주석은 무시합니다.루트 타입 이름 정하기
루트 타입 이름 칸에 이름을 씁니다. 중첩 인터페이스는 경로를 따라
ApiResponseLimits처럼 이름이 붙고, 내려받는 파일 이름도 루트 이름을 따라ApiResponse.ts처럼 정해집니다.선언 방식 고르기
선언 방식에서 interface와 type 별칭 중 하나를 고릅니다. export 키워드와 readonly 속성 스위치는 모든 선언 앞의 접두어를 바꾸고, 알 수 없는 값 옵션은 타입을 알 수 없는 값에
unknown과any중 무엇을 쓸지 정합니다.문서 옵션과 병합 키 설정
여러 문서가 든 파일은 목록이 됩니다. 자동 모드에서 문서 둘이면 배열 루트, 항상 배열은 문서 하나도 배열로 감싸고, 첫 문서만은 첫 문서만 남기며 알림을 보여 줍니다. 병합 키(<<) 펼치기는 물려받은 키가 타입에 나타날지 정합니다.
선언 확인 후 복사
루트가 먼저 나오고 중첩 타입은 만난 순서대로 이어집니다.
?표시와| null유니온이 파일에 대해 아는 내용과 맞는지 확인한 뒤 코드를 복사하거나.ts파일로 내려받습니다.
작동 원리
YAML 값이 TypeScript 타입이 되는 방식
타입은 표기가 아니라 파싱된 값에서 정해집니다. YAML 1.2 코어 스키마에서는 true와 false만 불리언이므로 debug: no는 string입니다. 2026-10-01 같은 날짜도 문자열이고, 정수와 실수는 모두 number라서 1.0과 1은 같은 타입입니다.
한 위치의 타입은 거기서 본 모든 값으로 정해집니다. 타입이 하나면 T[], 여럿이면 (A | B)[]가 되고 null은 유니온에 더해집니다. 늘 null뿐인 위치는 null, 빈 목록은 unknown[]입니다(any 옵션이면 any[]).
| YAML | TypeScript | 비고 |
|---|---|---|
| service: api | string | |
| port: 8080, cpu: 0.5, ratio: 1.0 | number | 정수와 실수를 구분하지 않음 |
| debug: no, flag: yes | string | 불리언은 YAML 1.1에서만 |
| enabled: true | boolean | |
| when: 2026-10-01 | string | 코어 스키마에는 타임스탬프 타입이 없음 |
| region: ~ (단독) | null | 문자열과 함께 나오면 string | null |
| tags: [web, edge] | string[] | |
| a: [1, two, null] | (string | number | null)[] | 섞인 목록은 유니온 |
| limits: {cpu: 0.5} | interface ApiResponseLimits | 경로에서 이름을 만듦 |
| 일부 항목에 없는 키 | key?: T | 같은 위치에 매핑이 둘 이상 있어야 함 |
| 12345678901234567890 | string | 2^53을 넘으면 텍스트로 유지하고 알림 표시 |
병합 키, 별칭, 여러 문서
별칭은 추론 전에 복사본으로 펼쳐지고 병합 키도 기본으로 펼쳐지므로, dev: {<<: *defaults, database: app_dev}는 defaults의 속성에 database를 더한 모양이 됩니다. 병합 키 펼치기를 끄면 인터페이스에 "<<"라는 속성이 생기고 그 타입은 중첩 인터페이스입니다. 엄격한 YAML 1.2 로더가 보는 모습과 같습니다.
---로 나뉜 여러 문서는 목록으로 읽습니다. 문서마다 키가 다른 매핑이면 키가 하나의 항목 인터페이스로 합쳐지고, 모든 문서에 있지 않은 키는 선택 속성이 됩니다. 끝의 ---는 문서가 아닙니다. YAML 1.1의 단어나 옛 8진수는 특별 취급하지 않아서 yes는 문자열이고 0123은 숫자 123입니다.
이름 짓기, 충돌, 따옴표
중첩 인터페이스 이름은 부모 이름에 PascalCase 키를 붙여 만들고, 목록 항목은 키의 단수형을 씁니다(items는 ApiResponseItem). 두 경로가 같은 이름을 만들면 먼저 만든 것을 덮어쓰지 않고 나중 것에 숫자 접미사를 붙여서 속성이 사라지지 않게 합니다.
^[A-Za-z_$][A-Za-z0-9_$]*$에 맞는 속성 이름은 그대로 쓰고, my-key나 a b처럼 맞지 않는 것은 큰따옴표로 감싸므로 대괄호 표기로 접근해야 합니다. 빈 매핑은 빈 인터페이스가 됩니다.
실제 예시
service: api
port: 8080
debug: no
tags: [web, edge]
limits:
cpu: 0.5
region: ~export interface ApiResponse {
service: string;
port: number;
debug: string;
tags: string[];
limits: ApiResponseLimits;
}
export interface ApiResponseLimits {
cpu: number;
region: null;
}debug: no는 YAML 1.2에서 문자열이고, 다른 값과 함께 나오지 않는 null은 null로 적습니다.
- name: Ada
role: dev
- name: Bo
role: ops
tags: [x, y]
- name: Cy
role: nullexport type ApiResponse = ApiResponseItem[];
export interface ApiResponseItem {
name: string;
role: string | null;
tags?: string[];
}루트가 목록이면 type 별칭과 항목 인터페이스 하나가 나옵니다. tags는 두 레코드에 없어서 선택 속성이고, role은 한 레코드가 null이라 string | null입니다.
defaults: &d
adapter: postgres
pool: 5
dev:
<<: *d
database: app_dev
prod:
<<: *d
pool: 20
ssl: trueexport interface ApiResponse {
defaults: ApiResponseDefaults;
dev: ApiResponseDev;
prod: ApiResponseProd;
}
export interface ApiResponseDefaults {
adapter: string;
pool: number;
}
export interface ApiResponseDev {
adapter: string;
pool: number;
database: string;
}
export interface ApiResponseProd {
adapter: string;
pool: number;
ssl: boolean;
}dev와 prod는 병합 키로 adapter와 pool을 받습니다. 병합 키 펼치기를 끄면 둘 다 "<<"라는 속성을 대신 갖게 됩니다.
a: 1
---
b: twoexport type ApiResponse = ApiResponseItem[];
export interface ApiResponseItem {
a?: number;
b?: string;
}자동 모드는 문서 둘을 배열로 만들고, 각 키가 한쪽 문서에만 있으므로 둘 다 선택 속성입니다. 첫 문서만을 고르면 a가 필수인 일반 인터페이스가 나옵니다.
a: [1, two, null]
"my-key": 1
b: [[1], [2]]
big: 9007199254740993
item: {}export interface ApiResponse {
a: (string | number | null)[];
"my-key": number;
b: number[][];
big: string;
item: ApiResponseItem;
}
export interface ApiResponseItem {}큰 정수는 string이고 정확한 텍스트로 유지했다는 알림이 나옵니다. 하이픈이 든 키는 따옴표로 감싸고 빈 매핑은 빈 인터페이스가 됩니다.
region: ~
empty: []
id: 7export type Config = {
readonly region: null;
readonly empty: any[];
readonly id: number;
};선언 방식을 type 별칭으로, readonly 속성을 켜고, 알 수 없는 값을 any로 정한 경우입니다. 바뀌는 것은 출력 모양뿐이고 추론된 형태는 같습니다.
자주 하는 실수
선택 키는 매핑이 둘 이상이어야 나옴
같은 위치의 일부 매핑에 키가 없을 때만 선택 키가 됩니다. 매핑이 하나면 비교할 대상이 없어 모든 키가 필수입니다. 레코드를 여러 개 붙여 넣거나
?를 직접 붙이세요.샘플이 타입의 완전함을 보장하지 않음
샘플의 모든 레코드에 값이 있으면
| null은 생기지 않습니다. 샘플에서는~인데 운영에서는 문자열인 키는null로 추론됩니다. 고르지 않은 경우를 샘플에 넣거나 결과를 고치세요.정수와 실수는 모두 number
1.0과1은 같은 타입이고, 2^53을 넘는 값은 자바스크립트 숫자가 자릿수를 잃으므로string이 됩니다. ID를 문자열로 할지는 내 계약에서 따로 정하세요.런타임 로더도 같은 규칙이어야 함
js-yaml 기본 모드나 PyYAML 등은
yes,0123,<<를 다르게 읽을 수 있습니다. 타입을 채우는 로더가 이 변환기와 같은 규칙인지 확인하거나 값을 따옴표로 감싸세요.사전처럼 쓴 매핑은 넓은 인터페이스가 됨
u1: {...},u2: {...}처럼 ID를 키로 쓴 매핑은Record<string, T>가 아니라 키마다 속성이 하나씩 생깁니다. 이런 부분은 직접 고치세요.날짜는 문자열
YAML 타임스탬프는 코어 스키마와 같이 여기서도
string입니다. 실제 날짜가 필요하면 코드에서Date.parse나 스키마 라이브러리를 쓰세요.
자주 묻는 질문
최상위가 목록인 YAML도 되나요?
네. 루트 목록은 export type ApiResponse = ApiResponseItem[];와 항목 인터페이스가 됩니다. 문서가 여러 개인 파일도 자동 모드에서는 이런 목록으로 바뀝니다.
yes가 왜 string인가요?
YAML 1.2 코어 스키마에서는 true와 false만 불리언입니다. yes, no, on, off는 일반 문자열이라서, 생성된 타입이 1.2 로더가 돌려주는 값과 일치합니다.
null은 어떻게 타입이 정해지나요?
한 위치가 늘 null이면 null입니다. 같은 위치에 문자열, 숫자, 객체가 함께 나오면 string | null 같은 유니온이 됩니다. 키가 아예 없는 경우는 별개이고 ?가 붙습니다.
선택 속성도 만들어 주나요?
네. 같은 위치의 매핑 중 일부에 키가 없을 때, 예를 들어 한 목록의 항목들이나 한 파일의 문서들 사이에서 key?: T로 적습니다.
병합 키가 타입에서도 펼쳐지나요?
기본값은 펼침입니다. <<: *anchor로 물려받은 키가 일반 속성으로 나옵니다. 병합 키 펼치기를 끄면 그 자리에 "<<" 속성이 나옵니다.
interface 대신 type 별칭을 쓸 수 있나요?
네. 선언 방식을 type 별칭으로 바꾸면 되고, 루트가 목록이면 항상 type으로 씁니다. export 키워드와 readonly 속성은 따로 켜고 끌 수 있습니다.
YAML이 업로드되나요?
아니요. 파싱과 타입 생성은 모두 브라우저 탭 안에서 실행되며 서버로 전송되지 않습니다. 입력은 20MiB까지입니다.
마지막 업데이트: