TypeScript Partial ו-Required: דוגמאות ו-Deep Partial

Partial<T> הוא utility type מובנה שהופך כל מאפיין של T לאופציונלי. זה הטיפוס הטבעי לעדכון או ל-patch: מי שקורא לפונקציה שולח רק את השדות שהשתנו.

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 הוא mapped type של שורה אחת בספרייה הסטנדרטית של 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. object spread מעתיק את ה-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' }

זה נושך כש-patch נבנה מטופס או מ-query string שבהם שדות ריקים הופכים ל-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 }, בלי שינוי. לאובייקטי הגדרות, ל-patches של API ול-fixtures של בדיקות, לעתים קרובות רוצים מאפיינים אופציונליים בכל רמה. לשם כך צריך טיפוס רקורסיבי.

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 ידנית כי גם object spread הוא רדוד. פונקציית deep merge גנרית קיימת בספריות כמו 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 שבה ידוע שכל ערך קיים. ל-spread יש אותו חור כמו בפונקציית העדכון שלמעלה: מי שמעביר 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