Partial et Required en TypeScript : exemples et DeepPartial

Partial<T> est un utility type intégré qui rend optionnelles toutes les propriétés de T. C'est le type naturel d'une mise à jour ou d'un patch : l'appelant n'envoie que les champs qui ont changé.

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> vaut { id?: number; name?: string; email?: string }. Le compilateur vérifie toujours les champs que vous passez : { nmae: "x" } ou { name: 42 } est une erreur, et c'est ce qui rend Partial meilleur qu'un paramètre object ou any trop permissif.

Comment Partial est défini

Partial est un mapped type d'une ligne dans la bibliothèque standard de TypeScript :

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

Pour chaque clé P de T, il déclare une propriété optionnelle du même type. Comme il parcourt keyof T, il conserve readonly sur les propriétés qui l'avaient. Étant un type ordinaire, il n'a aucun effet à l'exécution : l'objet passé comme changes est le même dans tous les cas.

Lire un Partial donne T | undefined

Chaque propriété d'un Partial<T> peut être absente, donc en lire une donne le type de la propriété plus undefined. Le compilateur vous oblige à gérer le cas de l'absence :

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 } est la façon habituelle de retransformer un Partial<Options> en Options complet : étalez d'abord les valeurs par défaut et laissez les valeurs fournies les remplacer.

Le piège du undefined explicite

Une propriété optionnelle peut être absente, mais elle peut aussi être présente avec la valeur undefined. Le spread d'objet copie ce undefined par-dessus la vraie valeur, et le type du résultat ne le montre pas :

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

Ce piège se déclenche quand un patch est construit à partir d'un formulaire ou d'une query string où les champs vides deviennent undefined. L'option de compilation exactOptionalPropertyTypes (qui ne fait pas partie de strict) fait de { name: undefined } une erreur de compilation pour name?: string, sauf si vous écrivez name?: string | undefined, ce qui règle le problème à la source.

Partial est superficiel

Partial ne rend optionnelles que les propriétés de premier niveau. Un objet imbriqué, si vous le passez, doit être complet :

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

La propriété editor est optionnelle, mais une fois présente elle a le type { fontSize: number; tabSize: number }, inchangé. Pour des objets de paramètres, des patchs d'API et des fixtures de test, on veut souvent des propriétés optionnelles à tous les niveaux. Il faut pour cela un type récursif.

DeepPartial : un Partial récursif

TypeScript n'a pas de version profonde intégrée, mais elle tient en quelques lignes. Les fonctions et les tableaux sont laissés tels quels, car rendre optionnels les éléments d'un tableau autoriserait [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: [] }

Le type est récursif ; la fusion ne l'est pas. applySettings fusionne editor à la main, car le spread d'objet est lui aussi superficiel. Des fonctions génériques de fusion profonde existent dans des bibliothèques comme lodash (merge), et leur typage est plus difficile que le type ci-dessus.

Required : l'inverse de Partial

Required<T> retire le ? de chaque propriété. Il est défini avec le modificateur -?, qui retire aussi undefined du type de chaque propriété :

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

Le schéma est le même qu'avec Partial, inversé : les utilisateurs d'une API passent une configuration souple, et le code interne travaille avec une version Required où chaque valeur est assurée d'exister. Le spread a le même trou que la fonction de mise à jour plus haut : un appelant qui passe port: undefined explicitement écrase la valeur par défaut avec undefined, et le compilateur l'accepte sauf si exactOptionalPropertyTypes est activé. Required est superficiel de la même façon que Partial.

Rendre seulement certaines propriétés optionnelles ou obligatoires

Partial et Required s'appliquent à toutes les propriétés. Pour n'en changer que quelques-unes, découpez le type avec Pick et Omit puis recomposez-le :

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