Partial وRequired في TypeScript: أمثلة وDeepPartial

Partial<T> نوع أداة مدمج يجعل كل خصائص 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. والنشر ينسخ تلك 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 } دون تغيير. وفي كائنات الإعدادات وتحديثات 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 لكن بالعكس: يمرر مستخدمو الواجهة إعدادات فضفاضة، ويعمل الكود في الداخل على نسخة 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