Utility Types ב-TypeScript: הרשימה המלאה עם דוגמאות

Utility types הם טיפוסים גנריים שמובנים ב-TypeScript והופכים טיפוס אחד לטיפוס אחר. במקום לכתוב טיפוס User שני שבו כל השדות אופציונליים, כותבים Partial<User>; במקום להעתיק שלושה שדות, Pick<User, "id" | "name">. הם גלובליים, כך שלא צריך לייבא אותם.

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) מצהירה על 22 utility types. הסעיפים הבאים מפרטים את כולם, מקובצים לפי סוג הטיפוס שהם עובדים עליו, עם קישור לעמוד המפורט כשיש כזה.

טיפוסי אובייקט: 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 כי ה-utility types האלה מקבלים טיפוס, ו-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 types, למשל `on${Capitalize<E>}` לשמות של event handlers.

Promises: 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>> היא הדרך המקובלת לתת שם לטיפוס התוצאה של פונקציה async בלי להצהיר עליו בנפרד.

שילוב utility types

אפשר לקנן 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' }

קוראים utility type מקונן מבפנים החוצה: Readonly<Pick<Post, "id" | "title">> קודם משאיר שני properties, ואחר כך הופך אותם לקריאה בלבד. מאותם חלקים בונים helper בשם PartialBy שהופך רק חלק מהמפתחות לאופציונליים; עמוד ה-Partial כותב אותו במלואו.

Utility types לא עושים כלום בזמן ריצה

כל utility type נמחק כשהקוד עובר קומפילציה. ערך מטיפוס 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"}

הטיפוס רק מגביל את מה שהקוד שלכם רשאי לקרוא. כדי להסיר שדה מהנתונים, הוציאו אותו עם destructuring כמו בשורות האחרונות, וכדי למנוע שינויים בזמן ריצה השתמשו ב-Object.freeze, לא ב-Readonly. הטיפוסים המובנים הם mapped types ו-conditional types של שורה אחת, כך שבאותם כלים אפשר לכתוב גם utility types משלכם.