TypeScript Partial und Required: Beispiele und Deep Partial

Partial<T> ist ein eingebauter Utility Type, der jede Eigenschaft von T optional macht. Er ist der natürliche Typ für ein Update oder einen Patch: Der Aufrufer schickt nur die Felder, die sich geändert haben.

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> ist { id?: number; name?: string; email?: string }. Die Felder, die du übergibst, prüft der Compiler trotzdem: { nmae: "x" } oder { name: 42 } ist ein Fehler, und genau das macht Partial besser als einen losen Parameter vom Typ object oder any.

Wie Partial definiert ist

Partial ist ein einzeiliger Mapped Type in der Standardbibliothek von TypeScript:

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

Für jeden Schlüssel P von T deklariert es eine optionale Eigenschaft mit demselben Typ. Weil es über keyof T iteriert, behält es readonly bei Eigenschaften, die es hatten. Als gewöhnlicher Typ hat es keine Wirkung zur Laufzeit: Das als changes übergebene Objekt ist in beiden Fällen dasselbe Objekt.

Lesen aus einem Partial ergibt T | undefined

Jede Eigenschaft eines Partial<T> kann fehlen, also ergibt das Lesen den Eigenschaftstyp plus undefined. Der Compiler zwingt dich, den fehlenden Fall zu behandeln:

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 } ist der übliche Weg, aus einem Partial<Options> wieder ein vollständiges Options zu machen: Zuerst die Standardwerte spreaden und die übergebenen Werte sie überschreiben lassen.

Die Falle mit explizitem undefined

Eine optionale Eigenschaft kann fehlen, sie kann aber auch mit dem Wert undefined vorhanden sein. Der Objekt-Spread kopiert dieses undefined über den echten Wert, und der Ergebnistyp zeigt das nicht:

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

Das beißt, wenn ein Patch aus einem Formular oder einem Query-String gebaut wird, in dem leere Felder zu undefined werden. Die Compiler-Option exactOptionalPropertyTypes (nicht Teil von strict) macht { name: undefined } für name?: string zu einem Compilerfehler, solange du nicht name?: string | undefined schreibst, und verhindert das Problem so an der Quelle.

Partial ist flach

Partial macht nur die Eigenschaften der obersten Ebene optional. Ein verschachteltes Objekt muss, wenn du es übergibst, vollständig sein:

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

Die Eigenschaft editor ist optional, hat aber, sobald sie vorhanden ist, unverändert den Typ { fontSize: number; tabSize: number }. Für Einstellungsobjekte, API-Patches und Test-Fixtures willst du oft optionale Eigenschaften auf jeder Ebene. Dafür braucht es einen rekursiven Typ.

DeepPartial: ein rekursives Partial

TypeScript hat keine eingebaute tiefe Version, aber sie ist in ein paar Zeilen geschrieben. Funktionen und Arrays bleiben, wie sie sind, weil optionale Array-Elemente [undefined] erlauben würden:

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: [] }

Der Typ ist rekursiv, das Zusammenführen nicht. applySettings führt editor von Hand zusammen, weil auch der Objekt-Spread flach ist. Eine generische Funktion für tiefes Zusammenführen gibt es in Bibliotheken wie lodash (merge), und ihre Typisierung ist schwieriger als der Typ oben.

Required: das Gegenteil von Partial

Required<T> entfernt das ? bei jeder Eigenschaft. Definiert ist es mit dem Modifikator -?, der außerdem undefined aus dem Typ jeder Eigenschaft entfernt:

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

Das Muster ist dasselbe wie bei Partial, nur umgekehrt: Nutzer einer API übergeben eine lockere Konfiguration, und der Code im Inneren arbeitet mit einer Required-Version, in der jeder Wert garantiert existiert. Der Spread hat dieselbe Lücke wie die Update-Funktion oben: Ein Aufrufer, der explizit port: undefined übergibt, überschreibt den Standardwert mit undefined, und der Compiler akzeptiert das, solange exactOptionalPropertyTypes nicht aktiv ist. Required ist auf dieselbe Weise flach wie Partial.

Nur einige Eigenschaften optional oder verpflichtend machen

Partial und Required gelten für jede Eigenschaft. Um nur einige zu ändern, teilst du den Typ mit Pick und Omit auf und setzt ihn wieder zusammen:

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