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 } はエラーで、それが Partial をゆるい object や any の引数より優れたものにしています。

Partial の定義

Partial はTypeScriptの標準ライブラリにある1行のマップ型です:

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

T の各キー P について、同じ型の省略可能なプロパティを宣言します。keyof T に対してマップするので、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