Partial e Required in TypeScript: esempi e DeepPartial

Partial<T> è un utility type integrato che rende opzionali tutte le proprietà di T. È il tipo naturale per un aggiornamento o una patch: chi chiama invia solo i campi che sono cambiati.

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 }. Il compilatore controlla comunque i campi che passi: { nmae: "x" } o { name: 42 } è un errore, ed è questo che rende Partial migliore di un parametro generico object o any.

Come è definito Partial

Partial è un mapped type di una sola riga nella libreria standard di TypeScript:

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

Per ogni chiave P di T, dichiara una proprietà opzionale con lo stesso tipo. Dato che itera su keyof T, mantiene readonly sulle proprietà che lo avevano. Essendo un tipo come un altro, non ha effetti in fase di esecuzione: l'oggetto passato come changes è lo stesso oggetto in ogni caso.

Leggere da un Partial dà T | undefined

Ogni proprietà di un Partial<T> può mancare, quindi leggerne una dà il tipo della proprietà più undefined. Il compilatore ti obbliga a gestire il caso in cui manca:

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 } è il modo abituale per trasformare un Partial<Options> di nuovo in un Options completo: prima fai lo spread dei valori predefiniti e poi lascia che i valori passati li sovrascrivano.

Il problema dell'undefined esplicito

Una proprietà opzionale può mancare, ma può anche essere presente con il valore undefined. Lo spread degli oggetti copia quell'undefined sopra il valore reale, e il tipo del risultato non lo mostra:

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

Questo morde quando una patch viene costruita da un modulo o da una query string in cui i campi vuoti diventano undefined. L'opzione del compilatore exactOptionalPropertyTypes (non fa parte di strict) rende { name: undefined } un errore di compilazione per name?: string a meno che tu non scriva name?: string | undefined, e così lo impedisce alla fonte.

Partial è superficiale

Partial rende opzionali solo le proprietà di primo livello. Un oggetto annidato, se lo passi, deve essere completo:

// 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 proprietà editor è opzionale, ma quando è presente ha tipo { fontSize: number; tabSize: number }, invariato. Per oggetti di impostazioni, patch di API e fixture di test spesso vuoi proprietà opzionali a ogni livello. Per questo serve un tipo ricorsivo.

DeepPartial: un Partial ricorsivo

TypeScript non ha una versione profonda integrata, ma bastano poche righe. Funzioni e array restano come sono, perché rendere opzionali gli elementi di un array permetterebbe [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: [] }

Il tipo è ricorsivo; l'unione no. applySettings unisce editor a mano perché anche lo spread degli oggetti è superficiale. Una funzione generica di deep merge esiste in librerie come lodash (merge), e la sua tipizzazione è più difficile del tipo qui sopra.

Required: l'opposto di Partial

Required<T> toglie il ? da tutte le proprietà. È definito con il modificatore -?, che toglie anche undefined dal tipo di ogni proprietà:

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

Lo schema è lo stesso di Partial, al contrario: chi usa un'API passa una configurazione parziale, e il codice interno lavora con una versione Required in cui ogni valore esiste di sicuro. Lo spread ha la stessa falla della funzione di aggiornamento vista sopra: un chiamante che passa port: undefined in modo esplicito sovrascrive il valore predefinito con undefined, e il compilatore lo accetta a meno che exactOptionalPropertyTypes non sia attivo. Required è superficiale proprio come Partial.

Rendere opzionali o obbligatorie solo alcune proprietà

Partial e Required si applicano a tutte le proprietà. Per cambiarne solo alcune, dividi il tipo con Pick e Omit e poi rimettilo insieme:

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