قيود الـ Generics في TypeScript: extends وkeyof T

قيد الـ generic يحدد ما يمكن أن يكونه معامل النوع. لا يقبل <T extends { length: number }> إلا الأنواع التي لها length رقمية (النصوص، والمصفوفات، وكائناتك الخاصة)، وبسبب هذا الضمان يُسمح للدالة بقراءة .length.

function longest<T extends { length: number }>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

console.log(longest("apple", "fig"));        // apple
console.log(longest([1, 2, 3], [4]));        // [ 1, 2, 3 ]
console.log(longest({ length: 2, tag: "x" }, { length: 5, tag: "y" })); // { length: 5, tag: 'y' }

// @ts-expect-error: Argument of type 'number' is not assignable to parameter of type '{ length: number; }'.
longest(10, 20);

نوع القيمة المُعادة لا يزال T، وليس { length: number }: تمرير مصفوفتين من الأرقام يعيد number[]، وتحتفظ الكائنات بالخاصية tag. القيد يصف الحد الأدنى؛ ونوع المستدعي يبقى محفوظًا.

لماذا نحتاج إلى القيود

داخل دالة عامة، قد يكون T غير المقيد أي شيء: نصًا، أو رقمًا، أو null، أو دالة. لذلك لا تسمح TypeScript إلا بما يعمل على كل الأنواع، وهو تقريبًا لا شيء.

// This does not compile: T could be number or undefined, which have no length.
function longest<T>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

console.log(longest("apple", "fig"));

يطبع المترجم:

index.ts(3,12): error TS2339: Property 'length' does not exist on type 'T'.
index.ts(3,24): error TS2339: Property 'length' does not exist on type 'T'.

الحل أن تقول ما تحتاج إليه: <T extends { length: number }>. تحوّل القيود «أي نوع» إلى «أي نوع يملك هذا»، وهذا عادة ما تعنيه الدالة العامة.

التقييد بـ Interface

يمكن أن يكون القيد أي نوع، بما في ذلك interface أو type alias موجود لديك. تعمل الدالة عندها مع أي شيء يملك هذه الأعضاء على الأقل، وتظل تعيد النوع الكامل للمستدعي.

interface HasId {
  id: number;
}

function byId<T extends HasId>(items: T[], id: number): T | undefined {
  return items.find((item) => item.id === id);
}

function indexById<T extends HasId>(items: T[]): Map<number, T> {
  return new Map(items.map((item) => [item.id, item]));
}

const users = [
  { id: 1, name: "Ada", role: "admin" },
  { id: 2, name: "Grace", role: "editor" },
];

const found = byId(users, 2);
console.log(found?.name);              // Grace (found keeps name and role)
console.log(indexById(users).get(1));  // { id: 1, name: 'Ada', role: 'admin' }

قارن ذلك بنوع معامل عادي: function byId(items: HasId[], id: number): HasId | undefined تقبل المصفوفات نفسها، لكن النتيجة HasId فقط، فيكون found.name خطأ. أما النسخة العامة فتمرر النوع الكامل.

K extends keyof T: الوصول الآمن إلى الخصائص

أشيع قيد هو الذي يربط بين معاملي نوع. يقول K extends keyof T إن K يجب أن يكون أحد أسماء خصائص T، وT[K] هو نوع تلك الخاصية.

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

function pluck<T, K extends keyof T>(items: T[], key: K): T[K][] {
  return items.map((item) => item[key]);
}

const book = { title: "Dune", year: 1965, tags: ["sci-fi"] };

const year = getProperty(book, "year");   // number
const title = getProperty(book, "title"); // string
console.log(year + 1, title.toUpperCase()); // 1966 DUNE

const books = [book, { title: "Emma", year: 1815, tags: [] }];
console.log(pluck(books, "year"));        // [ 1965, 1815 ]

// @ts-expect-error: Argument of type '"author"' is not assignable to parameter of type '"tags" | "title" | "year"'.
getProperty(book, "author");

المفتاح المكتوب خطأً أو غير الموجود خطأ ترجمة، ونوع القيمة المُعادة يتبع المفتاح: "year" يعطي number، و"title" يعطي string. تشرح صفحة keyof العامل keyof نفسه، بما في ذلك سلوكه مع توقيعات الفهرسة.

التقييد بالأنواع البدائية

يمكن أن يكون القيد نوعًا بدائيًا أو union منها. ومن الآثار الجانبية المفيدة: حين يكون T extends string (أو number) تستنتج TypeScript النوع الحرفي للوسيط بدل توسيعه.

function maxOf<T extends number | bigint>(values: T[]): T {
  return values.reduce((a, b) => (b > a ? b : a)); // < and > work on the constraint
}

function createEvent<T extends string>(name: T): { type: T } {
  return { type: name };
}

console.log(maxOf([3, 9, 4]));           // 9
console.log(maxOf([10n, 2n]));           // 10n

const evt = createEvent("user.saved");   // evt: { type: "user.saved" }
const same: "user.saved" = evt.type;     // the literal survived
console.log(same);                       // user.saved

دون القيد يعيد createEvent("user.saved") النوع { type: string }: هنا توسّع TypeScript القيمة الحرفية التي استنتجتها لـ T إلى string. ومع T extends string تُحفظ القيمة الحرفية، وهكذا تحصل أدوات الأحداث والتوجيه ذات الأنواع على أسماء دقيقة من وسائط نصية عادية.

أخطاء شائعة

إعادة شيء يطابق القيد فقط. الدالة التي تعيد T يجب أن تعيد T، لا أي قيمة تناسب القيد:

interface HasId {
  id: number;
}

function reset<T extends HasId>(item: T): T {
  return { id: item.id };
}
// error TS2322: Type '{ id: number; }' is not assignable to type 'T'.
//   '{ id: number; }' is assignable to the constraint of type 'T', but 'T' could be
//   instantiated with a different subtype of constraint 'HasId'.

إن كان T هو { id: number; name: string } فالكائن الجديد بلا name، فليس T. أعد نسخة من المدخل بالنشر، return { ...item, id: 0 };، التي تحتفظ بكل الخصائص، أو صرّح بأن نوع القيمة المُعادة HasId إن كان هذا كل ما تنتجه.

تمرير وسيط نوع يخالف القيد. وسائط النوع الصريحة تُفحص أيضًا: مع function scale<T extends number>(x: T) يفشل الاستدعاء scale<string>("2") بالرسالة Type 'string' does not satisfy the constraint 'number'. (TS2344).

التقييد حين لا تحتاج إلى generic. إن ظهر T في المعامل فقط، فإن function print<T extends HasId>(item: T): void هي مجرد function print(item: HasId): void بصيغة زائدة. القيود مهمة حين يظهر T أيضًا في نوع القيمة المُعادة أو في معامل آخر.

القيود مع القيم الافتراضية

يمكن أن يكون لمعامل النوع قيد وقيمة افتراضية معًا. ويجب أن تستوفي القيمة الافتراضية القيد.

interface Store<TState extends object = Record<string, unknown>> {
  get(): TState;
  set(next: Partial<TState>): void;
}

type AnyStore = Store;                              // Store<Record<string, unknown>>
type CounterStore = Store<{ count: number }>;       // fine
type BadStore = Store<number>;
// error TS2344: Type 'number' does not satisfy the constraint 'object'.

تظهر الكلمة المفتاحية extends نفسها أيضًا في الأنواع الشرطية، T extends string ? A : B، حيث تكون اختبارًا لا تقييدًا؛ وتشرح صفحة الأنواع الشرطية هذه الصيغة.