الأنواع المعيّنة (Mapped Types) في TypeScript: الصيغة والمعدّلات

النوع المعيّن يبني نوع كائن جديدًا بالمرور على مجموعة من المفاتيح. يعني { [K in keyof T]: boolean } «لكل مفتاح K في T، خاصية اسمها K من النوع boolean»:

type Features = {
  darkMode: string;
  search: number;
  export: string[];
};

// Same keys as T, every property turned into a boolean
type Flags<T> = { [K in keyof T]: boolean };

const enabled: Flags<Features> = {
  darkMode: true,
  search: false,
  export: true,
};

console.log(enabled); // { darkMode: true, search: false, export: true }
// Leaving out "export" would be error TS2741: Property 'export' is missing

أضف مفتاحًا إلى Features فيطلبه Flags<Features> أيضًا. الأنواع المعيّنة تعمل وقت الترجمة فقط: تصف الكائنات ولا تنشئها.

الصيغة

للنوع المعيّن ثلاثة أجزاء: متغير مفتاح، وunion من المفاتيح للمرور عليها، ونوع الخاصية الذي قد يستخدم متغير المفتاح.

type MappedType = {
  [K in Keys]: PropertyType; // K takes each member of Keys in turn
};

يمكن أن يكون Keys أي union من النصوص أو الأرقام أو الرموز (symbols). ولا يلزم أن يأتي من keyof:

type Size = "small" | "medium" | "large";

type PriceTable = { [S in Size]: number };
// { small: number; medium: number; large: number }

const prices: PriceTable = { small: 3, medium: 4, large: 5 };

for (const size of ["small", "large"] as const) {
  console.log(size, prices[size]);
}
// small 3
// large 5

هذا بالضبط ما يفعله Record<Size, number>؛ فـ Record نوع معيّن من سطر واحد. ويمكن لنوع الخاصية أن يستخدم المفتاح: ينسخ { [K in keyof T]: T[K] } نوع كل خاصية عبر وصول مفهرس، ويجعل { [K in keyof T]: T[K] | null } كل خاصية قابلة لأن تكون null.

المعدّلات: readonly و? مع + و-

يمكن للنوع المعيّن إضافة المعدّلين readonly والاختياري (?) إلى كل الخصائص دفعة واحدة أو حذفهما. ضع + للإضافة (وهو الافتراضي حين لا تكتب شيئًا) و- للحذف:

type Account = {
  readonly id: number;
  email?: string;
};

type Mutable<T> = { -readonly [K in keyof T]: T[K] };
type AllRequired<T> = { [K in keyof T]-?: T[K] };
type Frozen<T> = { +readonly [K in keyof T]: T[K] };

const editable: Mutable<Account> = { id: 1 };
editable.id = 2; // allowed: readonly was removed

const complete: AllRequired<Account> = { id: 1, email: "a@b.co" };
// { id: 1 } alone would be error TS2741: Property 'email' is missing

const frozen: Frozen<{ n: number }> = { n: 1 };
// @ts-expect-error: Cannot assign to 'n' because it is a read-only property
frozen.n = 2;

console.log(editable, complete, frozen);
// { id: 2 } { id: 1, email: 'a@b.co' } { n: 2 }

يبيّن السطر الأخير أن readonly مجرد قاعدة وقت الترجمة: بُلّغ عن الإسناد (وأُسكت هنا بـ @ts-expect-error)، لكن JavaScript الناتج نفّذه رغم ذلك. ولا يكتفي -? بحذف علامة الاستفهام: بل يحذف أيضًا undefined من نوع الخاصية، فيرفض AllRequired<Account> القيمة { id: 1, email: undefined } بالخطأ error TS2322: Type 'undefined' is not assignable to type 'string'.

كيف تُبنى Partial وReadonly وPick وRecord

أنواع الأدوات المدمجة التي تعيد تشكيل الكائنات أنواع معيّنة. هذه هي التعريفات من الملف lib.es5.d.ts الخاص بـ TypeScript نفسها:

type Partial<T> = { [P in keyof T]?: T[P] };
type Required<T> = { [P in keyof T]-?: T[P] };
type Readonly<T> = { readonly [P in keyof T]: T[P] };
type Pick<T, K extends keyof T> = { [P in K]: T[P] };
type Record<K extends keyof any, T> = { [P in K]: T };

قراءتها تمرين جيد: يمر Pick على المفاتيح التي تمررها فقط، ويتجاهل Record أي نوع مصدر ويعطي كل مفتاح نوع القيمة نفسه. أما Omit فليس نوعًا معيّنًا مستقلًا: إنه Pick<T, Exclude<keyof T, K>>. ويسردها كلها مرجع أنواع الأدوات.

إعادة تسمية المفاتيح بـ as

عبارة as بعد المفتاح تغيّر اسم الخاصية. ومع أنواع القوالب النصية (template literal types) يمكنها توليد أسماء جديدة من الأسماء القديمة:

type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};

type Person = { name: string; age: number };

// { getName: () => string; getAge: () => number }
const person: Getters<Person> = {
  getName: () => "Ada",
  getAge: () => 36,
};

console.log(person.getName(), person.getAge()); // Ada 36

وُضع string & K لأن keyof T قد يتضمن مفاتيح number وsymbol، وCapitalize لا يقبل إلا النصوص. يحتفظ التقاطع (intersection) بالمفاتيح النصية ويحذف الباقي.

تصفية المفاتيح بـ never

إذا أنتجت عبارة as النوع never لمفتاح ما، يُحذف ذلك المفتاح. ومع نوع شرطي يمكنك الإبقاء على الخصائص أو حذفها بحسب نوعها:

type DataOnly<T> = {
  [K in keyof T as T[K] extends (...args: any[]) => unknown ? never : K]: T[K];
};

class Invoice {
  constructor(public id: number, public total: number) {}
  format(): string {
    return `#${this.id}: ${this.total.toFixed(2)}`;
  }
}

// { id: number; total: number }  (format is gone)
const data: DataOnly<Invoice> = { id: 7, total: 19.5 };

console.log(data);                        // { id: 7, total: 19.5 }
console.log(new Invoice(7, 19.5).format()); // #7: 19.50

أنواع مثل DataOnly مفيدة لوصف ما يبقى بعد JSON.stringify أو ما يعدّله نموذج إدخال: الحقول دون التوابع.

أي المعدّلات تُحفظ

النوع المعيّن على keyof T لنوع ما T يُسمى متماثل الشكل (homomorphic)، وهو ينسخ معدّلي readonly و? لكل خاصية من T. أما النوع المعيّن على union عادي من المفاتيح فيبدأ دون أي معدّلات:

type Account = { readonly id: number; email?: string };

type Copy<T> = { [K in keyof T]: T[K] };
type A = Copy<Account>;
// { readonly id: number; email?: string }  (modifiers kept)

type B = { [K in "id" | "email"]: Account[K] };
// { id: number; email: string | undefined }  (email is required now)

لا يزال B يحمل undefined في نوع email، لأن Account["email"] يتضمنه، لكن الخاصية نفسها لم تعد اختيارية: يُرفض { id: 1 }. ولهذا تمر Partial<T> وأخواتها على keyof T: فهي تحتفظ بكل ما لا تغيّره صراحة.

النوع المعيّن المتماثل الشكل العام حين يُطبَّق على مصفوفة أو tuple ينتج مصفوفة أو tuple، لا كائنًا بمفاتيح رقمية. Readonly<string[]> هو readonly string[]، ومع type Box<T> = { [K in keyof T]: { value: T[K] } } يكون Box<[string, number]> هو [{ value: string }, { value: number }].

الأنواع المعيّنة وكود وقت التشغيل

لأن النوع المعيّن يصف الكائن فقط، تحتاج الدالة التي تبني هذا الكائن إلى حلقة خاصة بها وقت التشغيل. ثم يصف النوع نتيجتها:

type Validators<T> = { [K in keyof T]: (value: T[K]) => boolean };

type SignUp = { email: string; age: number };

const rules: Validators<SignUp> = {
  email: (v) => v.includes("@"), // v is string
  age: (v) => v >= 13,           // v is number
};

function validate(form: SignUp): string[] {
  const failed: string[] = [];
  for (const key of Object.keys(rules) as (keyof SignUp)[]) {
    const ok = key === "email" ? rules.email(form.email) : rules.age(form.age);
    if (!ok) failed.push(key);
  }
  return failed;
}

console.log(validate({ email: "ada@example.com", age: 36 })); // []
console.log(validate({ email: "nope", age: 9 }));             // [ 'email', 'age' ]

تحصل الـ callbacks على أنواع معاملاتها من النوع المعيّن (v من النوع string في إحداها وnumber في الأخرى) دون أي توصيف. وإن جئت إلى هنا تبحث عن الصنف Map لا عن تحويل الأنواع، فراجع Map في TypeScript.