TypeScript Partial과 Required 사용법: 예제와 DeepPartial

Partial<T>는 T의 모든 속성을 선택적으로 만드는 내장 유틸리티 타입입니다. 호출하는 쪽이 바뀐 필드만 보내는 업데이트나 패치에 자연스럽게 맞는 타입입니다.

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

function updateUser(user: User, changes: Partial<User>): User {
  return { ...user, ...changes };
}

const ada: User = { id: 1, name: "Ada", email: "ada@example.com" };

const renamed = updateUser(ada, { name: "Ada Lovelace" });
const moved = updateUser(ada, { email: "ada@analytical.org" });

console.log(renamed); // { id: 1, name: 'Ada Lovelace', email: 'ada@example.com' }
console.log(moved.email); // ada@analytical.org

Partial<User>는 { id?: number; name?: string; email?: string }입니다. 컴파일러는 넘긴 필드는 여전히 검사하므로 { nmae: "x" }나 { name: 42 }는 오류입니다. 이것이 느슨한 object나 any 매개변수보다 Partial이 나은 이유입니다.

Partial의 정의

Partial은 TypeScript 표준 라이브러리에 있는 한 줄짜리 매핑된 타입입니다.

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

T의 각 키 P에 대해 같은 타입의 선택적 속성을 선언합니다. keyof T를 매핑하므로 원래 readonly였던 속성은 readonly로 유지됩니다. 평범한 타입이라 런타임 효과는 없습니다. changes로 넘긴 객체는 어느 쪽이든 같은 객체입니다.

Partial에서 읽으면 T | undefined가 된다

Partial<T>의 모든 속성은 없을 수 있으므로, 읽으면 속성 타입에 undefined가 더해집니다. 컴파일러는 없는 경우를 처리하도록 요구합니다.

interface Options {
  retries: number;
  timeoutMs: number;
  verbose: boolean;
}

const defaults: Options = { retries: 3, timeoutMs: 5000, verbose: false };

function connect(opts: Partial<Options> = {}) {
  const retries = opts.retries ?? defaults.retries; // number
  // opts.timeoutMs * 2 would be error TS18048: 'opts.timeoutMs' is possibly 'undefined'.
  const full: Options = { ...defaults, ...opts };
  console.log(retries, full);
}

connect({ verbose: true });
// 3 { retries: 3, timeoutMs: 5000, verbose: true }
connect();
// 3 { retries: 3, timeoutMs: 5000, verbose: false }

{ ...defaults, ...opts }는 Partial<Options>를 다시 완전한 Options로 만드는 흔한 방법입니다. 기본값을 먼저 펼치고, 넘어온 값이 그것을 덮어쓰게 합니다.

명시적 undefined 함정

선택적 속성은 없을 수도 있지만 undefined 값으로 존재할 수도 있습니다. 객체 스프레드는 그 undefined를 실제 값 위에 복사하고, 결과 타입에는 그것이 드러나지 않습니다.

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

function update(user: User, changes: Partial<User>): User {
  return { ...user, ...changes };
}

const u = update({ name: "Ada", email: "ada@example.com" }, { name: undefined });
console.log(u);             // { name: undefined, email: 'ada@example.com' }
console.log(typeof u.name); // undefined, although the type says string

// Fix: drop undefined values before merging
function updateSafe(user: User, changes: Partial<User>): User {
  const defined = Object.fromEntries(
    Object.entries(changes).filter(([, v]) => v !== undefined),
  ) as Partial<User>;
  return { ...user, ...defined };
}
console.log(updateSafe({ name: "Ada", email: "ada@example.com" }, { name: undefined }));
// { name: 'Ada', email: 'ada@example.com' }

빈 필드가 undefined가 되는 폼이나 쿼리 문자열로 패치를 만들 때 이 문제가 생깁니다. exactOptionalPropertyTypes 컴파일러 옵션(strict에 포함되지 않음)을 켜면 name?: string | undefined라고 쓰지 않는 한 name?: string에 대한 { name: undefined }가 컴파일 오류가 되어 원천적으로 막아 줍니다.

Partial은 얕다

Partial은 최상위 속성만 선택적으로 만듭니다. 중첩 객체를 넘긴다면 그 객체는 완전해야 합니다.

// This does not compile: Partial only reaches the first level
interface Settings {
  theme: string;
  editor: { fontSize: number; tabSize: number };
}

const patch: Partial<Settings> = {
  editor: { fontSize: 16 },
};
console.log(patch);

index.ts(8,3): error TS2741: Property 'tabSize' is missing in type '{ fontSize: number; }' but required in type '{ fontSize: number; tabSize: number; }'.

editor 속성은 선택적이지만, 일단 있으면 타입은 그대로 { fontSize: number; tabSize: number }입니다. 설정 객체, API 패치, 테스트 픽스처에서는 모든 단계의 속성이 선택적이기를 바라는 경우가 많습니다. 그러려면 재귀 타입이 필요합니다.

DeepPartial: 재귀적인 Partial

TypeScript에는 깊게 적용되는 내장 버전이 없지만 몇 줄이면 만들 수 있습니다. 배열 요소를 선택적으로 만들면 [undefined]가 허용되므로 함수와 배열은 그대로 둡니다.

type DeepPartial<T> =
  T extends (...args: any[]) => unknown ? T :
  T extends readonly unknown[] ? T :
  T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } :
  T;

interface Settings {
  theme: string;
  editor: { fontSize: number; tabSize: number };
  recent: string[];
}

const defaults: Settings = {
  theme: "dark",
  editor: { fontSize: 14, tabSize: 2 },
  recent: [],
};

function applySettings(base: Settings, patch: DeepPartial<Settings>): Settings {
  return { ...base, ...patch, editor: { ...base.editor, ...patch.editor } };
}

const patch: DeepPartial<Settings> = { editor: { fontSize: 16 } }; // OK now
console.log(applySettings(defaults, patch));
// { theme: 'dark', editor: { fontSize: 16, tabSize: 2 }, recent: [] }

타입은 재귀적이지만 병합은 그렇지 않습니다. 객체 스프레드도 얕기 때문에 applySettings는 editor를 직접 병합합니다. 범용 깊은 병합 함수는 lodash(merge) 같은 라이브러리에 있으며, 그 타입 지정은 위의 타입보다 어렵습니다.

Required: Partial의 반대

Required<T>는 모든 속성에서 ?를 제거합니다. -? 수정자로 정의되며, 이 수정자는 각 속성 타입에서 undefined도 제거합니다.

interface ServerConfig {
  host: string;
  port?: number;
  tls?: boolean;
}

type ResolvedConfig = Required<ServerConfig>; // { host: string; port: number; tls: boolean }

function resolve(config: ServerConfig): ResolvedConfig {
  return { port: 80, tls: false, ...config };
}

const cfg = resolve({ host: "example.com", tls: true });
console.log(cfg.port + 1, cfg.tls); // 81 true
// @ts-expect-error: Property 'tls' is missing in type '{ host: string; port: number; }'
const incomplete: ResolvedConfig = { host: "a", port: 1 };

패턴은 Partial과 같고 방향만 반대입니다. API 사용자는 느슨한 설정을 넘기고, 내부 코드는 모든 값이 존재한다고 알려진 Required 버전으로 작업합니다. 이 스프레드에도 위의 업데이트 함수와 같은 구멍이 있습니다. 호출하는 쪽이 port: undefined를 명시적으로 넘기면 기본값이 undefined로 덮어써지고, exactOptionalPropertyTypes가 꺼져 있으면 컴파일러는 이를 받아들입니다. Required도 Partial과 같은 방식으로 얕습니다.

일부 속성만 선택적 또는 필수로 만들기

Partial과 Required는 모든 속성에 적용됩니다. 몇 개만 바꾸려면 Pick과 Omit으로 타입을 나눈 뒤 다시 합칩니다.

type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;

interface Post {
  id: number;
  title: string;
  body?: string;
}

type NewPost = PartialBy<Post, "id">;      // id optional, title required, body optional
type Published = RequiredBy<Post, "body">; // body now required