Partial e Required em TypeScript: exemplos e Deep Partial

Partial<T> é um utility type embutido que torna opcional toda propriedade de T. É o tipo natural para um update ou patch: quem chama envia só os campos que mudaram.

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 }. O compilador continua verificando os campos que você passa: { nmae: "x" } ou { name: 42 } é erro, e é isso que torna Partial melhor que um parâmetro frouxo do tipo object ou any.

Como Partial é definido

Partial é um mapped type de uma linha na biblioteca padrão do TypeScript:

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

Para cada chave P de T, ele declara uma propriedade opcional com o mesmo tipo. Como ele mapeia sobre keyof T, mantém o readonly nas propriedades que o tinham. Por ser um tipo comum, não tem efeito em tempo de execução: o objeto passado como changes é o mesmo objeto de qualquer jeito.

Ler de um Partial dá T | undefined

Toda propriedade de um Partial<T> pode estar ausente, então ler uma delas dá o tipo da propriedade mais undefined. O compilador obriga você a tratar o caso da ausência:

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 } é o jeito habitual de transformar um Partial<Options> de volta em um Options completo: espalhe os padrões primeiro e deixe os valores recebidos sobrescrevê-los.

A armadilha do undefined explícito

Uma propriedade opcional pode estar ausente, mas também pode estar presente com o valor undefined. O spread de objeto copia esse undefined por cima do valor real, e o tipo do resultado não mostra isso:

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

Isso pega você quando um patch é montado a partir de um formulário ou de uma query string em que campos vazios viram undefined. A opção do compilador exactOptionalPropertyTypes (que não faz parte de strict) torna { name: undefined } um erro de compilação para name?: string, a menos que você escreva name?: string | undefined, o que evita o problema na origem.

Partial é raso

Partial só torna opcionais as propriedades do primeiro nível. Um objeto aninhado, se você o passar, precisa 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; }'.

A propriedade editor é opcional, mas quando está presente tem o tipo { fontSize: number; tabSize: number }, sem mudança. Para objetos de configuração, patches de API e fixtures de teste, muitas vezes você quer propriedades opcionais em todos os níveis. Isso exige um tipo recursivo.

DeepPartial: um Partial recursivo

O TypeScript não tem uma versão profunda embutida, mas ela cabe em poucas linhas. Funções e arrays ficam como estão, porque tornar opcionais os elementos de um array permitiria [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: [] }

O tipo é recursivo; a mesclagem não é. applySettings mescla editor à mão porque o spread de objeto também é raso. Uma função genérica de mesclagem profunda existe em bibliotecas como o lodash (merge), e tipá-la é mais difícil do que o tipo acima.

Required: o oposto de Partial

Required<T> remove o ? de toda propriedade. Ele é definido com o modificador -?, que também remove undefined do tipo de cada propriedade:

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

O padrão é o mesmo de Partial, invertido: quem usa uma API passa uma configuração frouxa, e o código interno trabalha com uma versão Required em que se sabe que todo valor existe. O spread tem o mesmo buraco da função de update acima: quem passa port: undefined explicitamente sobrescreve o padrão com undefined, e o compilador aceita, a menos que exactOptionalPropertyTypes esteja ligado. Required é raso do mesmo jeito que Partial.

Tornando só algumas propriedades opcionais ou obrigatórias

Partial e Required se aplicam a todas as propriedades. Para mudar só algumas, divida o tipo com Pick e Omit e junte de novo:

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