Partial y Required en TypeScript: ejemplos y DeepPartial

Partial<T> es un utility type integrado que hace opcionales todas las propiedades de T. Es el tipo natural para una actualización o un patch: quien llama envía solo los campos que cambiaron.

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> es { id?: number; name?: string; email?: string }. El compilador sigue comprobando los campos que sí pasas: { nmae: "x" } o { name: 42 } es un error, y eso es lo que hace a Partial mejor que un parámetro object o any sin más.

Cómo está definido Partial

Partial es un mapped type de una línea de la librería estándar de TypeScript:

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

Para cada clave P de T, declara una propiedad opcional con el mismo tipo. Como recorre keyof T, conserva el readonly de las propiedades que lo tenían. Al ser un tipo normal, no tiene efecto en ejecución: el objeto que se pasa como changes es el mismo en cualquier caso.

Leer de un Partial da T | undefined

Cualquier propiedad de un Partial<T> puede faltar, así que leer una da el tipo de la propiedad más undefined. El compilador te obliga a tratar el caso en que falta:

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 } es la forma habitual de convertir un Partial<Options> de nuevo en un Options completo: primero el spread de los valores por defecto y después los valores recibidos, que los sobrescriben.

El problema del undefined explícito

Una propiedad opcional puede faltar, pero también puede estar presente con el valor undefined. El spread de objetos copia ese undefined encima del valor real, y el tipo del resultado no lo refleja:

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

Esto da problemas cuando un patch se construye a partir de un formulario o de una query string en los que los campos vacíos se convierten en undefined. La opción del compilador exactOptionalPropertyTypes (que no forma parte de strict) convierte { name: undefined } en un error de compilación para name?: string, salvo que escribas name?: string | undefined, y así lo evita desde el origen.

Partial es superficial

Partial solo hace opcionales las propiedades del primer nivel. Un objeto anidado, si lo pasas, tiene que estar 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 propiedad editor es opcional, pero cuando está presente tiene el tipo { fontSize: number; tabSize: number }, sin cambios. Para objetos de configuración, patches de API y datos de prueba muchas veces quieres propiedades opcionales en todos los niveles. Eso necesita un tipo recursivo.

DeepPartial: un Partial recursivo

TypeScript no trae una versión profunda integrada, pero son pocas líneas. Las funciones y los arrays se dejan como están, porque hacer opcionales los elementos de un array permitiría [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: [] }

El tipo es recursivo; la fusión no. applySettings fusiona editor a mano porque el spread de objetos también es superficial. Existen funciones genéricas de fusión profunda en librerías como lodash (merge), y tiparlas es más difícil que el tipo de arriba.

Required: el opuesto de Partial

Required<T> quita el ? de todas las propiedades. Está definido con el modificador -?, que además quita undefined del tipo de cada propiedad:

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

El patrón es el mismo que con Partial, al revés: quien usa una API pasa una configuración flexible, y el código interno trabaja con una versión Required en la que se sabe que existen todos los valores. El spread tiene el mismo agujero que la función de actualización de antes: quien pasa port: undefined de forma explícita sobrescribe el valor por defecto con undefined, y el compilador lo acepta salvo que exactOptionalPropertyTypes esté activado. Required es superficial igual que Partial.

Hacer opcionales u obligatorias solo algunas propiedades

Partial y Required se aplican a todas las propiedades. Para cambiar solo unas pocas, divide el tipo con Pick y Omit y vuelve a juntarlo:

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