TypeScript Generics: פונקציות, טיפוסים ומחלקות גנריים

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 הוא אילוץ, והוא מוסבר בעמוד הבא.

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

כברירת מחדל גנרי מסיק טיפוסים מורחבים: 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

מי שקורא לפונקציה כותב מערך רגיל, והפונקציה שומרת על טיפוסי הליטרל.

מתי לא להשתמש בגנריקס

פרמטר טיפוס מצדיק את מקומו כשהוא מקשר בין שני דברים: פרמטר וטיפוס ההחזרה, שני פרמטרים, או פרמטר ו-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 של שני טיפוסים ידועים.

לגנריקס שצריכים לדעת משהו על T (שיש לו length, או ש-K הוא מפתח של T), אילוצים עם extends הם השלב הבא.