Partial và Required trong TypeScript: ví dụ và DeepPartial

Partial<T> là một utility type có sẵn, biến mọi thuộc tính của T thành tùy chọn. Đây là kiểu tự nhiên cho một bản cập nhật hay patch: nơi gọi chỉ gửi những trường đã thay đổi.

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> là { id?: number; name?: string; email?: string }. Trình biên dịch vẫn kiểm tra những trường bạn truyền vào: { nmae: "x" } hay { name: 42 } đều là lỗi, và đó là điều làm Partial tốt hơn một tham số object lỏng lẻo hay any.

Partial được định nghĩa thế nào

Partial là một mapped type chỉ một dòng trong thư viện chuẩn của TypeScript:

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

Với mỗi khóa P của T, nó khai báo một thuộc tính tùy chọn có cùng kiểu. Vì ánh xạ qua keyof T, nó giữ nguyên readonly trên những thuộc tính đã có. Là một kiểu thông thường, nó không ảnh hưởng gì lúc chạy: object được truyền vào làm changes vẫn là object đó.

Đọc từ Partial nhận T | undefined

Mọi thuộc tính của Partial<T> đều có thể vắng mặt, nên đọc một thuộc tính sẽ nhận kiểu của nó cộng thêm undefined. Trình biên dịch buộc bạn xử lý trường hợp thiếu:

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 } là cách thường dùng để biến Partial<Options> trở lại thành Options đầy đủ: spread giá trị mặc định trước rồi để các giá trị được truyền vào ghi đè lên.

Cái bẫy undefined tường minh

Một thuộc tính tùy chọn có thể vắng mặt, nhưng cũng có thể có mặt với giá trị undefined. Object spread chép undefined đó đè lên giá trị thật, và kiểu kết quả không cho thấy điều này:

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

Lỗi này hay xảy ra khi bản patch được tạo từ một form hoặc query string, nơi các trường trống trở thành undefined. Tùy chọn trình biên dịch exactOptionalPropertyTypes (không thuộc strict) biến { name: undefined } thành lỗi biên dịch với name?: string, trừ khi bạn viết name?: string | undefined, nhờ đó chặn được vấn đề ngay từ gốc.

Partial chỉ ở mức nông

Partial chỉ biến các thuộc tính ở cấp ngoài cùng thành tùy chọn. Một object lồng bên trong, nếu bạn truyền vào, vẫn phải đầy đủ:

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

Thuộc tính editor là tùy chọn, nhưng khi có mặt thì nó có kiểu { fontSize: number; tabSize: number }, không đổi. Với object cài đặt, bản patch cho API và dữ liệu mẫu cho test, bạn thường muốn thuộc tính tùy chọn ở mọi cấp. Điều đó cần một kiểu đệ quy.

DeepPartial: Partial đệ quy

TypeScript không có sẵn phiên bản sâu, nhưng viết nó chỉ mất vài dòng. Hàm và mảng được giữ nguyên, vì biến phần tử mảng thành tùy chọn sẽ cho phép [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: [] }

Kiểu thì đệ quy; còn phép gộp thì không. applySettings gộp editor bằng tay vì object spread cũng chỉ ở mức nông. Hàm deep merge generic có trong các thư viện như lodash (merge), và việc khai báo kiểu cho nó khó hơn kiểu ở trên.

Required: ngược lại với Partial

Required<T> bỏ ? khỏi mọi thuộc tính. Nó được định nghĩa bằng modifier -?, và modifier này cũng loại undefined khỏi kiểu của từng thuộc tính:

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

Mẫu này giống với Partial, chỉ đảo ngược: người dùng API truyền vào một cấu hình lỏng, còn code bên trong làm việc với phiên bản Required mà mọi giá trị đều chắc chắn tồn tại. Phép spread ở đây có cùng lỗ hổng với hàm cập nhật ở trên: nơi gọi truyền port: undefined một cách tường minh sẽ ghi đè giá trị mặc định bằng undefined, và trình biên dịch chấp nhận điều đó trừ khi bật exactOptionalPropertyTypes. Required cũng chỉ ở mức nông giống như Partial.

Chỉ biến một số thuộc tính thành tùy chọn hoặc bắt buộc

Partial và Required áp dụng cho mọi thuộc tính. Để chỉ thay đổi vài thuộc tính, hãy tách kiểu bằng Pick và Omit rồi ghép lại:

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