Partial i Required w TypeScript: przykłady i Deep Partial

Partial<T> to wbudowany typ narzędziowy, który czyni każdą właściwość T opcjonalną. To naturalny typ dla aktualizacji lub łatki: wywołujący wysyła tylko pola, które się zmieniły.

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> to { id?: number; name?: string; email?: string }. Kompilator nadal sprawdza pola, które przekazujesz: { nmae: "x" } czy { name: 42 } to błąd, i właśnie dlatego Partial jest lepszy niż luźny parametr object lub any.

Jak zdefiniowany jest Partial

Partial to jednolinijkowy typ mapowany w bibliotece standardowej TypeScriptu:

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

Dla każdego klucza P z T deklaruje opcjonalną właściwość o tym samym typie. Ponieważ mapuje po keyof T, zachowuje readonly na właściwościach, które je miały. Jako zwykły typ nie ma wpływu na działanie programu: obiekt przekazany jako changes jest w obu przypadkach tym samym obiektem.

Odczyt z Partial daje T | undefined

Każdej właściwości Partial<T> może brakować, więc jej odczyt daje typ właściwości plus undefined. Kompilator każe ci obsłużyć przypadek braku:

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 } to typowy sposób, żeby zamienić Partial<Options> z powrotem w kompletne Options: najpierw rozłóż wartości domyślne, a podane wartości niech je nadpiszą.

Pułapka jawnego undefined

Właściwości opcjonalnej może brakować, ale może też istnieć z wartością undefined. Rozkładanie obiektu kopiuje to undefined na prawdziwą wartość, a typ wyniku tego nie pokazuje:

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' }

To gryzie, gdy łatka powstaje z formularza lub query stringa, w którym puste pola stają się undefined. Opcja kompilatora exactOptionalPropertyTypes (nie jest częścią strict) sprawia, że { name: undefined } to błąd kompilacji dla name?: string, chyba że napiszesz name?: string | undefined, co zapobiega problemowi u źródła.

Partial jest płytki

Partial czyni opcjonalnymi tylko właściwości najwyższego poziomu. Zagnieżdżony obiekt, jeśli go przekazujesz, musi być kompletny:

// 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; }'.

Właściwość editor jest opcjonalna, ale gdy już jest, ma typ { fontSize: number; tabSize: number }, bez zmian. Przy obiektach ustawień, łatkach API i danych testowych często chcesz właściwości opcjonalnych na każdym poziomie. To wymaga typu rekurencyjnego.

DeepPartial: rekurencyjny Partial

TypeScript nie ma wbudowanej głębokiej wersji, ale to kilka linii. Funkcje i tablice zostają bez zmian, bo opcjonalne elementy tablicy pozwoliłyby na [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: [] }

Typ jest rekurencyjny, scalanie już nie. applySettings scala editor ręcznie, bo rozkładanie obiektu też jest płytkie. Generyczna funkcja głębokiego scalania istnieje w bibliotekach takich jak lodash (merge), a jej typowanie jest trudniejsze niż powyższy typ.

Required: przeciwieństwo Partial

Required<T> usuwa ? z każdej właściwości. Jest zdefiniowany z modyfikatorem -?, który usuwa też undefined z typu każdej właściwości:

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 };

Wzorzec jest taki sam jak przy Partial, tylko odwrócony: użytkownicy API przekazują luźną konfigurację, a kod w środku pracuje na wersji Required, w której każda wartość na pewno istnieje. Rozkładanie ma tę samą dziurę co funkcja aktualizująca wyżej: wywołujący, który jawnie przekaże port: undefined, nadpisze wartość domyślną przez undefined, a kompilator to zaakceptuje, chyba że exactOptionalPropertyTypes jest włączone. Required jest płytki tak samo jak Partial.

Tylko niektóre właściwości opcjonalne lub wymagane

Partial i Required działają na każdą właściwość. Aby zmienić tylko kilka, podziel typ przez Pick i Omit i złóż go z powrotem:

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