Utility Types في TypeScript: القائمة الكاملة مع الأمثلة

أنواع الأدوات (utility types) أنواع generic مدمجة في TypeScript تحوّل نوعًا إلى نوع آخر. بدلًا من كتابة نوع User ثانٍ كل حقوله اختيارية، تكتب Partial<User>؛ وبدلًا من نسخ ثلاثة حقول، تكتب Pick<User, "id" | "name">. إنها عامة (global)، فلا حاجة إلى استيرادها.

interface User {
  id: number;
  name: string;
  email: string;
  password: string;
}

type UserPatch = Partial<User>;                 // every field optional
type UserCard = Pick<User, "id" | "name">;      // only id and name
type PublicUser = Omit<User, "password">;       // everything but password
type UsersById = Record<number, PublicUser>;    // an object keyed by id

const patch: UserPatch = { email: "new@example.com" };
const card: UserCard = { id: 1, name: "Ada" };
const users: UsersById = {
  1: { id: 1, name: "Ada", email: "ada@example.com" },
};

console.log(patch, card, users[1].email);
// { email: 'new@example.com' } { id: 1, name: 'Ada' } ada@example.com

عندما يتغير User تتبعه الأنواع المشتقة الأربعة كلها. تعرّف المكتبة القياسية في TypeScript (lib.es5.d.ts) اثنين وعشرين نوع أداة. تسردها الأقسام التالية جميعًا، مجمّعة حسب نوع الأنواع التي تعمل عليها، مع رابط إلى الصفحة المفصلة حيث توجد.

أنواع الكائنات: Partial وRequired وReadonly وPick وOmit وRecord

interface Config {
  host: string;
  port?: number;
  debug?: boolean;
}

const defaults: Required<Omit<Config, "host">> = { port: 8080, debug: false };

function withDefaults(config: Config): Readonly<Required<Config>> {
  return { ...defaults, ...config };
}

const cfg = withDefaults({ host: "localhost", debug: true });
console.log(cfg); // { port: 8080, debug: true, host: 'localhost' }
// cfg.port = 1 would be error TS2540: Cannot assign to 'port' because it is a read-only property.

Required<T> هو عكس Partial<T>؛ تشرح صفحة Partial الاثنين، بما في ذلك قيمة undefined الصريحة التي يسمح بمرورها نشر (spread) كهذا.

أنواع union: Exclude وExtract وNonNullable

type Status = "draft" | "review" | "published" | "archived";

type Live = Exclude<Status, "draft" | "archived">; // "review" | "published"
type Mixed = string | number | (() => void);
type Callable = Extract<Mixed, (...args: never[]) => unknown>; // () => void

function lookup(id: number): string | undefined {
  return id === 1 ? "Ada" : undefined;
}
type Found = NonNullable<ReturnType<typeof lookup>>; // string

const s: Live = "review";
const run: Callable = () => console.log("called");
const found: Found = lookup(1) ?? "nobody";
run();
console.log(s, found); // review Ada

تعمل هذه الثلاثة على unions لا على الكائنات. وهذا هو الفرق الأساسي بينها وبين Pick وOmit، اللذين يأخذان نوع كائن وقائمة من مفاتيحه.

أنواع الدوال والأصناف: Parameters وReturnType وغيرهما

function createOrder(customer: string, items: string[], express = false) {
  return { customer, items, express, total: items.length * 10 };
}

type OrderArgs = Parameters<typeof createOrder>; // [customer: string, items: string[], express?: boolean | undefined]
type Order = ReturnType<typeof createOrder>;     // { customer: string; items: string[]; express: boolean; total: number }

const args: OrderArgs = ["Ada", ["book", "pen"]];
const order: Order = createOrder(...args);
console.log(order.total, order.express); // 20 false

class Point {
  constructor(public x: number, public y: number) {}
}
const coords: ConstructorParameters<typeof Point> = [3, 4];
const p: InstanceType<typeof Point> = new Point(...coords);
console.log(p); // Point { x: 3, y: 4 }

نحتاج إلى typeof createOrder لأن هذه الأدوات تأخذ نوعًا، وcreateOrder قيمة. والأمر نفسه مع الأصناف: typeof Point هو نوع المُنشئ، بينما Point وحده كنوع يعني نوع النسخة.

يتحكم NoInfer في المصدر الذي يأخذ منه النوع العام نوعه:

function pickColor<C extends string>(colors: C[], fallback: NoInfer<C>): C {
  return colors[0] ?? fallback;
}

console.log(pickColor(["red", "green"], "green")); // red
// @ts-expect-error: "blue" is not "red" | "green"
pickColor(["red", "green"], "blue");

بدون NoInfer تستنتج TypeScript النوع C من الوسيطين معًا وتوسّعه إلى "red" | "green" | "blue"، فيُقبل الخطأ الإملائي في القيمة الاحتياطية.

أنواع النصوص: Uppercase وLowercase وCapitalize وUncapitalize

هذه الأربعة مدمجة في المترجم بدلًا من أن تكون مكتوبة بـ TypeScript، وأكثر ما تفيد داخل أنواع template literal، مثل `on${Capitalize<E>}` لأسماء معالجات الأحداث.

الوعود: Awaited

async function fetchUser(id: number) {
  return { id, name: "Ada" };
}

type Pending = ReturnType<typeof fetchUser>;           // Promise<{ id: number; name: string }>
type User = Awaited<ReturnType<typeof fetchUser>>;      // { id: number; name: string }

async function main() {
  const user: User = await fetchUser(1);
  const all: User[] = await Promise.all([fetchUser(2), fetchUser(3)]);
  console.log(user.name, all.map((u) => u.id)); // Ada [ 2, 3 ]
}
main();

Awaited<ReturnType<typeof fn>> هو الطريقة المعتادة لتسمية نوع نتيجة دالة غير متزامنة دون تعريفه منفصلًا.

الجمع بين utility types

تتداخل أنواع الأدوات. وبعض التركيبات تتكرر بما يكفي لتستحق الحفظ:

interface Post {
  id: number;
  title: string;
  body: string;
  tags: string[];
}

// Create: everything except the server-generated id
type NewPost = Omit<Post, "id">;
// Update: id required, everything else optional
type PostUpdate = Pick<Post, "id"> & Partial<Omit<Post, "id">>;
// A lookup table of read-only summaries
type PostIndex = Record<number, Readonly<Pick<Post, "id" | "title">>>;

const created: NewPost = { title: "Hello", body: "...", tags: [] };
const update: PostUpdate = { id: 1, title: "Hello again" };
const index: PostIndex = { 2: { id: 2, title: "Idea" } };
console.log(created.title, update, index[2]);
// Hello { id: 1, title: 'Hello again' } { id: 2, title: 'Idea' }

اقرأ نوع الأداة المتداخل من الداخل إلى الخارج: Readonly<Pick<Post, "id" | "title">> يُبقي أولًا خاصيتين، ثم يجعلهما للقراءة فقط. والأجزاء نفسها تبني مساعدًا PartialBy يجعل بعض المفاتيح فقط اختيارية؛ وتكتبه صفحة Partial كاملًا.

utility types لا تفعل شيئًا وقت التشغيل

كل نوع أداة يُحذف عند ترجمة الكود. القيمة من النوع Omit<User, "password"> قد تحمل كلمة مرور وقت التشغيل إذا كان الكائن الذي جاءت منه يحملها:

interface User {
  name: string;
  password: string;
}

const full: User = { name: "Ada", password: "hunter2" };

const leaky: Omit<User, "password"> = full; // allowed: extra properties are fine
console.log(JSON.stringify(leaky)); // {"name":"Ada","password":"hunter2"}

const { password, ...safe } = full;          // this actually removes it
console.log(JSON.stringify(safe));  // {"name":"Ada"}

النوع يحدّ فقط مما يُسمح لكودك بقراءته. لحذف حقل من البيانات، أخرجه بالتفكيك كما في الأسطر الأخيرة، ولمنع التعديل وقت التشغيل استخدم Object.freeze لا Readonly. الأنواع المدمجة mapped types وconditional types من سطر واحد، فالأدوات نفسها تتيح لك كتابة أنواعك الخاصة.