TypeScript type alias: מילת המפתח type עם דוגמאות

Type alias נותן שם לטיפוס. כותבים type Name = ..., ומאותו רגע אפשר להשתמש ב-Name בכל מקום שבו מצופה טיפוס. בניגוד ל-interface, alias יכול לתת שם לכל טיפוס שהוא, לא רק למבני אובייקטים.

type UserId = string;                         // a primitive
type Point = { x: number; y: number };        // an object shape
type Status = "active" | "banned";            // a union of literals
type Pair = [string, number];                 // a tuple
type Formatter = (value: number) => string;   // a function

const id: UserId = "u_42";
const start: Point = { x: 0, y: 0 };
const current: Status = "active";
const entry: Pair = ["score", 90];
const money: Formatter = (v) => `$${v.toFixed(2)}`;

console.log(id, start, current, entry, money(3.5));
// u_42 { x: 0, y: 0 } active [ 'score', 90 ] $3.50

Aliases קיימים רק בזמן קומפילציה. ה-JavaScript שנוצר לא מכיל אף אחת משורות ה-type האלה.

תחביר

type Name = SomeType;
type Name<T> = SomeTypeUsing<T>;       // generic
export type Name = SomeType;           // exported from a module

לפי המוסכמה, השמות נכתבים ב-PascalCase. הצד הימני הוא כל ביטוי טיפוס, ו-alias יכול להשתמש ב-aliases אחרים, כולל בעצמו (ראו טיפוסים רקורסיביים בהמשך). ה-alias זמין בכל ה-scope שבו הוא מוצהר, גם מעל שורת ההצהרה, כי טיפוסים נבדקים בזמן קומפילציה ולא מורצים לפי הסדר כמו const או let.

טיפוסי אובייקטים

עבור מבנה של אובייקט, alias ו-interface נכתבים כמעט באותה צורה. ה-alias משתמש ב-= ובדרך כלל מסתיים בנקודה-פסיק.

type User = {
  id: number;
  name: string;
  email?: string;           // optional
  readonly createdAt: string; // cannot be reassigned
};

type Admin = User & { permissions: string[] }; // extend with an intersection

const root: Admin = {
  id: 1,
  name: "root",
  createdAt: "2024-03-15",
  permissions: ["*"],
};

console.log(`${root.name} can do ${root.permissions.join(", ")}`); // root can do *

alias לא יכול להשתמש ב-extends; ה-intersection עם & ממלא את התפקיד הזה. בדיקות מאפיינים עודפים, מאפיינים אופציונליים ומאפייני readonly עובדים בדיוק כמו ב-interfaces. במה מהשניים לבחור למבני אובייקטים מוסבר בעמוד interface מול type.

Unions, tuples ופונקציות

אלה המקרים שרק alias יכול לתת להם שם, והסיבה העיקרית ש-type קיים. alias של union מפרט את האפשרויות, alias של tuple קובע את האורך ואת טיפוסי האיברים של מערך, ו-alias של פונקציה מתאר חתימה.

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number };

type Span = [start: number, end: number]; // labeled tuple elements

type Transform = (shape: Shape, factor: number) => Shape;

const scale: Transform = (shape, factor) =>
  shape.kind === "circle"
    ? { kind: "circle", radius: shape.radius * factor }
    : { kind: "rect", width: shape.width * factor, height: shape.height * factor };

const r: Span = [10, 20];
console.log(scale({ kind: "circle", radius: 2 }, 3)); // { kind: 'circle', radius: 6 }
console.log(r[1] - r[0]);                              // 10

ב-scale הפרמטרים לא צריכים הערות טיפוס: ה-alias Transform מספק את הטיפוסים שלהם. התחביר של tuples מוסבר בעמוד tuples, וצמצום של unions בעמוד union types.

Type aliases גנריים

פרמטרי טיפוס מאפשרים ל-alias אחד לעבוד עם טיפוסים רבים. יכולים להיות להם ערכי ברירת מחדל, בדיוק כמו לפרמטרים של פונקציה.

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

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

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? `age ${r.value}` : r.error);
}
// age 36
// not an age: abc

Result<number> משתמש בברירת המחדל E = string. aliases גנריים קטנים כמו type Nullable<T> = T | null או type Dict<T> = Record<string, T> נפוצים בקוד אמיתי. גם טיפוסי העזר המובנים (Partial<T>, Pick<T, K>, ReturnType<F>) הם aliases גנריים, שמוצהרים בספרייה הסטנדרטית.

Aliases הם שמות, לא טיפוסים חדשים

alias לא יוצר טיפוס נפרד. הוא שם שני לטיפוס שבצד הימני, והקומפיילר מתייחס לשניהם כזהים. שני aliases של string ניתנים להחלפה לגמרי:

type UserId = string;
type OrderId = string;

function cancelOrder(id: OrderId) {
  console.log("cancelling", id);
}

const user: UserId = "u_42";
cancelOrder(user); // compiles: UserId and OrderId are both just string

הקוד מדפיס cancelling u_42 בלי שגיאה, וזה בדיוק הבאג ש-alias לא יכול למנוע. ה-alias עדיין עוזר לקוראים (פרמטר מטיפוס OrderId אומר יותר מ-string), אבל אם בלבול בין שני מזהים חייב להיות שגיאת קומפילציה, השתמשו ב-branded type כמו string & { readonly __brand: "OrderId" }.

Type aliases רקורסיביים

alias יכול להפנות לעצמו, וכך מתארים עצים, רשימות מקוננות ו-JSON:

type Json =
  | string
  | number
  | boolean
  | null
  | Json[]
  | { [key: string]: Json };

type TreeNode = {
  value: number;
  children: TreeNode[];
};

function sum(node: TreeNode): number {
  return node.value + node.children.reduce((total, child) => total + sum(child), 0);
}

const tree: TreeNode = {
  value: 1,
  children: [
    { value: 2, children: [] },
    { value: 3, children: [{ value: 4, children: [] }] },
  ],
};

const payload: Json = { ok: true, items: [1, "two", null], meta: { page: 1 } };

console.log(sum(tree));               // 10
console.log(JSON.stringify(payload)); // {"ok":true,"items":[1,"two",null],"meta":{"page":1}}

ה-alias Json דוחה ערכים ש-JSON לא יכול לייצג: השמה של { when: new Date() } או { f: undefined } ל-Json היא שגיאת קומפילציה (TS2322).

טיפוסים מתוך ערכים: typeof

כשערך כבר קיים, אפשר לתת שם לטיפוס שלו במקום לכתוב אותו מחדש. אופרטור הטיפוסים typeof קורא את הטיפוס של משתנה, ואפשר לשלב אותו עם אופרטורים אחרים:

const defaults = { retries: 3, verbose: false, level: "info" };

type Options = typeof defaults;
// { retries: number; verbose: boolean; level: string }

type OptionKey = keyof typeof defaults;
// "retries" | "verbose" | "level"

function start(port: number) {
  return { port, startedAt: new Date() };
}
type Server = ReturnType<typeof start>;
// { port: number; startedAt: Date }

הערך נשאר מקור האמת היחיד: הוסיפו מאפיין ל-defaults ו-Options יתעדכן בהתאם. עוד על כך בעמוד typeof.

ייצוא וייבוא של aliases

מייצאים ומייבאים aliases כמו ערכים. import type מבהיר שמיובא רק טיפוס, ולכן ה-import תמיד מוסר מפלט ה-JavaScript:

// shapes.ts
export type Point = { x: number; y: number };
export type Shape = { kind: "circle"; center: Point; radius: number };

// main.ts
import type { Point, Shape } from "./shapes.js";

const p: Point = { x: 1, y: 2 };