الأنواع العامة (Generics) في TypeScript: دوال وأنواع وأصناف

الـ generics معاملات نوع. تعرّف الدالة العامة نوعًا نائبًا، يُسمى عادة T، ويملؤه كل استدعاء، فتحدد الأنواع الداخلة الأنواعَ الخارجة. عندها تعمل دالة واحدة مع الأرقام والنصوص وكائناتك الخاصة، ويبقى كل استدعاء محدد الأنواع بالكامل.

function first<T>(items: T[]): T | undefined {
  return items[0];
}

const n = first([10, 20, 30]);        // T = number, n: number | undefined
const s = first(["ada", "grace"]);    // T = string, s: string | undefined
const u = first([{ id: 1 }]);         // T = { id: number }

console.log(n?.toFixed(1));           // 10.0
console.log(s?.toUpperCase());        // ADA
console.log(u?.id);                   // 1

تعرّف <T> بعد اسم الدالة معامل النوع. يستخدمه items: T[] للمدخل وT | undefined للمخرج، وهذا ما يربط بينهما. لم تكتب number ولا string في أي مكان: استنتجت TypeScript النوع T من الوسيط.

لماذا لا any أو unknown؟

دون الـ generics كنت ستحدد نوع المعامل any أو unknown. كلاهما يقبل أي مصفوفة، وكلاهما يفقد الصلة بين المدخل والمخرج:

function firstAny(items: any[]): any {
  return items[0];
}

function firstUnknown(items: unknown[]): unknown {
  return items[0];
}

function firstGeneric<T>(items: T[]): T | undefined {
  return items[0];
}

const a = firstAny(["x"]);
console.log(typeof a.toFixed);         // undefined: a.toFixed(2) would compile, then throw

const b = firstUnknown(["x"]);
// b.toUpperCase();                    // error TS18046: 'b' is of type 'unknown'.
console.log(typeof b === "string" ? b.toUpperCase() : "?"); // X (after narrowing)

const c = firstGeneric(["x"]);
console.log(c?.toUpperCase());         // X, with no narrowing needed

استنتاج وسائط النوع

عادة تستنتج TypeScript وسائط النوع من القيم التي تمررها. ويمكنك أيضًا كتابتها صراحة بين أقواس زاوية عند الاستدعاء، وهذا ضروري حين لا يذكر أي وسيط T، أو حين يختار الاستنتاج شيئًا لا تريده.

function pair<T>(a: T, b: T): [T, T] {
  return [a, b];
}

function emptyList<T>(): T[] {
  return [];
}

const p1 = pair(1, 2);                      // T inferred as number
const p2 = pair<string | number>(1, "one"); // explicit: mixing allowed
const names = emptyList<string>();          // nothing to infer from, so pass it
names.push("Ada");

console.log(p1, p2, names); // [ 1, 2 ] [ 1, 'one' ] [ 'Ada' ]

نتيجتان من نتائج الاستنتاج تستحقان المعرفة. pair(1, "one") دون الوسيط الصريح خطأ: تستنتج TypeScript T = number من الوسيط الأول ثم تبلّغ Argument of type 'string' is not assignable to parameter of type 'number'. (TS2345). وemptyList() دون أي وسيط تحصل على T = unknown، فتعطي unknown[]، وهذا نادرًا ما تريده.

عدة معاملات نوع

يمكن للدالة أن تعرّف عدد معاملات النوع الذي تحتاجه، مفصولة بفواصل. ويُستنتج كل منها مستقلًا عن الآخر.

function zip<A, B>(left: A[], right: B[]): [A, B][] {
  const length = Math.min(left.length, right.length);
  const out: [A, B][] = [];
  for (let i = 0; i < length; i++) out.push([left[i], right[i]]);
  return out;
}

function mapValues<K extends string, V, R>(obj: Record<K, V>, fn: (value: V) => R): Record<K, R> {
  const out = {} as Record<K, R>;
  for (const key of Object.keys(obj) as K[]) out[key] = fn(obj[key]);
  return out;
}

console.log(zip(["a", "b", "c"], [1, 2]));        // [ [ 'a', 1 ], [ 'b', 2 ] ]
const prices = mapValues({ tea: 2.5, cake: 4 }, (v) => `$${v.toFixed(2)}`);
console.log(prices);                               // { tea: '$2.50', cake: '$4.00' }

تستنتج mapValues ثلاثة أشياء دفعة واحدة: K هو "tea" | "cake"، وV هو number، وR هو string من القيمة المُعادة من الـ callback. أما K extends string فقيد (constraint)، تشرحه الصفحة التالية.

الـ Interfaces والـ Type Aliases العامة

يمكن للأنواع أيضًا أن تأخذ معاملات. تكتب الوسيط حين تستخدم النوع: Box<number>، ApiResponse<User>. ومعظم أنواع المجموعات المدمجة تعمل بهذه الطريقة: Array<T>، وMap<K, V>، وPromise<T>، وRecord<K, V>.

interface ApiResponse<T> {
  status: number;
  data: T;
}

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

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

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0 ? { ok: true, value: n } : { ok: false, error: `bad age: ${text}` };
}

const res: ApiResponse<User[]> = { status: 200, data: [{ id: 1, name: "Ada" }] };
console.log(res.data[0].name);   // Ada

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? r.value + 1 : r.error); // 37, then bad age: abc
}

يبيّن Result<T, E = string> أيضًا معامل نوع افتراضيًا: Result<number> يعني Result<number, string>. ومثل معاملات الدوال الاختيارية، يجب أن تأتي المعاملات ذات القيم الافتراضية بعد المعاملات المطلوبة.

الأصناف العامة

يأخذ الصنف معاملات النوع بعد اسمه، وكل نسخة تثبّتها. ويمكن للحقول والتوابع ومعاملات دالة البناء كلها أن تستخدمها.

class Stack<T> {
  private items: T[] = [];

  push(item: T): void {
    this.items.push(item);
  }

  pop(): T | undefined {
    return this.items.pop();
  }

  peek(): T | undefined {
    return this.items.at(-1);
  }

  get size(): number {
    return this.items.length;
  }
}

const visited = new Stack<string>();
visited.push("/home");
visited.push("/docs");
console.log(visited.pop(), visited.size); // /docs 1

const numbers = new Stack<number>();
numbers.push(42);
// numbers.push("42"); // error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
console.log(numbers.peek()); // 42

إن كانت دالة البناء تأخذ T، يمكنك حذف الوسيط الصريح: new Box(5) يستنتج Box<number>. الأعضاء الثابتة تنتمي إلى الصنف نفسه لا إلى نسخة، فلا يمكنها استخدام معامل النوع الخاص بالصنف (Static members cannot reference class type parameters.، TS2302).

دوال الأسهم العامة وأنواع الدوال

تأتي قائمة معاملات النوع قبل قائمة المعاملات. والصيغة نفسها تصف نوع دالة عامة.

const last = <T>(items: T[]): T | undefined => items[items.length - 1];

type Mapper = <T, R>(items: T[], fn: (item: T) => R) => R[];
const mapAll: Mapper = (items, fn) => items.map(fn);

// In a .tsx file, <T> looks like a JSX tag. Add a trailing comma:
const lastTsx = <T,>(items: T[]) => items[items.length - 1];

استنتاج الأنواع الحرفية بمعاملات نوع const

افتراضيًا يستنتج الـ generic أنواعًا موسّعة: pair("a", "b") يعطي [string, string]. حين تهم القيم الدقيقة (أسماء المسارات، وأسماء الأحداث، وقوائم الأعمدة)، علّم المعامل بـ const (في TypeScript 5.0 وما بعده) فيُستنتج كأن الوسيط مكتوب بـ as const:

function defineColumns<const T extends readonly string[]>(columns: T): T {
  return columns;
}

const loose = ["id", "name"];                  // string[]
const columns = defineColumns(["id", "name"]); // readonly ["id", "name"]

type Column = (typeof columns)[number];        // "id" | "name"
const sortBy: Column = "name";
console.log(columns, sortBy, loose.length);    // [ 'id', 'name' ] name 2

يكتب المستدعي مصفوفة عادية، وتحتفظ الدالة بالأنواع الحرفية.

متى لا تستخدم الـ Generics

يستحق معامل النوع مكانه حين يربط بين شيئين: معامل ونوع القيمة المُعادة، أو معاملين، أو معامل وcallback. إن ظهر T مرة واحدة فقط فلا يضيف شيئًا، والنوع العادي أوضح.

// Pointless: T is used once, so it is just a longer way to write unknown
function logValue<T>(value: T): void {
  console.log(value);
}

// Clearer
function logValueSimple(value: unknown): void {
  console.log(value);
}

// Also pointless: returns T but nothing connects T to an argument,
// so the caller is really just asserting a type
function parseJson<T>(text: string): T {
  return JSON.parse(text);
}

الحالة الأخيرة شائعة ومضللة: يبدو parseJson<User>(text) آمن الأنواع لكنه لا يفحص شيئًا، تمامًا مثل JSON.parse(text) as User. أعد unknown وتحقق من البيانات بدلًا من ذلك. ومن علامات الإفراط الأخرى: معامل نوع يُعطى دائمًا الوسيط نفسه، أو معامل يمكن استبداله بـ union من نوعين معروفين.

للـ generics التي تحتاج إلى معرفة شيء عن T (أن له length، أو أن K مفتاح في T)، القيود بـ extends هي الخطوة التالية.