Partial и Required в TypeScript: примеры и DeepPartial

Partial<T> это встроенный служебный тип, который делает каждое свойство T необязательным. Это естественный тип для обновления или патча: вызывающий код передаёт только изменившиеся поля.

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 }. Компилятор по-прежнему проверяет поля, которые вы передаёте: { nmae: "x" } или { name: 42 } это ошибка, и именно поэтому Partial лучше расплывчатого параметра object или any.

Как определён Partial

Partial это однострочный сопоставленный тип в стандартной библиотеке TypeScript:

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

Для каждого ключа P из T он объявляет необязательное свойство того же типа. Поскольку он перебирает keyof T, он сохраняет readonly у свойств, где он был. Это обычный тип, поэтому он не влияет на выполнение: объект, переданный как changes, в любом случае один и тот же.

Чтение из Partial даёт T | undefined

Любое свойство Partial<T> может отсутствовать, поэтому его чтение даёт тип свойства плюс undefined. Компилятор заставляет обработать случай отсутствия:

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 } это обычный способ превратить Partial<Options> обратно в полный Options: сначала развернуть значения по умолчанию, а затем позволить переданным значениям их переопределить.

Ловушка явного undefined

Необязательное свойство может отсутствовать, но может и присутствовать со значением undefined. Развёртывание объекта копирует это undefined поверх настоящего значения, а тип результата этого не показывает:

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

Это кусается, когда патч собирается из формы или строки запроса, где пустые поля становятся undefined. Параметр компилятора exactOptionalPropertyTypes (не входит в strict) делает { name: undefined } ошибкой компиляции для name?: string, если не написать name?: string | undefined, и это предотвращает проблему в источнике.

Partial поверхностный

Partial делает необязательными только свойства верхнего уровня. Вложенный объект, если вы его передаёте, должен быть полным:

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

Свойство editor необязательное, но если оно есть, его тип { fontSize: number; tabSize: number } не изменился. Для объектов настроек, патчей API и тестовых данных часто нужны необязательные свойства на каждом уровне. Для этого нужен рекурсивный тип.

DeepPartial: рекурсивный Partial

Встроенной глубокой версии в TypeScript нет, но она пишется в несколько строк. Функции и массивы остаются как есть, потому что необязательные элементы массива разрешили бы [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: [] }

Тип рекурсивный, а слияние нет. applySettings сливает editor вручную, потому что развёртывание объекта тоже поверхностное. Обобщённая функция глубокого слияния есть в библиотеках вроде lodash (merge), и её типизация сложнее, чем у типа выше.

Required: противоположность Partial

Required<T> убирает ? у каждого свойства. Он определён с модификатором -?, который ещё и убирает undefined из типа каждого свойства:

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

Приём тот же, что с Partial, только наоборот: пользователи API передают расплывчатую конфигурацию, а код внутри работает с версией Required, где о каждом значении известно, что оно есть. У развёртывания та же дыра, что у функции обновления выше: вызывающий код, который явно передаёт port: undefined, перезаписывает значение по умолчанию на undefined, и компилятор это принимает, если не включён exactOptionalPropertyTypes. Required поверхностный так же, как Partial.

Необязательными или обязательными только некоторые свойства

Partial и Required применяются ко всем свойствам. Чтобы изменить только несколько, разделите тип через Pick и Omit и соберите его обратно:

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