Literal Types ו-as const ב-TypeScript, עם דוגמאות

literal type הוא טיפוס עם ערך אחד בדיוק: "up" הוא טיפוס שהאיבר היחיד שלו הוא המחרוזת "up", ו-404 הוא טיפוס שהאיבר היחיד שלו הוא המספר 404. לבדם הם לא שימושיים במיוחד. כשמחברים אותם ל-union, מקבלים משתנה שמקבל קבוצה קבועה של ערכים ותו לא.

type Direction = "up" | "down" | "left" | "right";

function move(dir: Direction, steps: number) {
  console.log(`moving ${dir} by ${steps}`);
}

move("up", 3);
move("left", 1);

// @ts-expect-error: Argument of type '"north"' is not assignable to parameter of type 'Direction'.
move("north", 1);

בלי ההערה @ts-expect-error, הקריאה האחרונה היא שגיאה בזמן קומפילציה (TS2345). איתה, התוכנית מתקמפלת, והקריאה עדיין רצה ומדפיסה moving north by 1: literal types קיימים רק בשביל הקומפיילר, ובזמן ריצה הערך הוא מחרוזת רגילה.

Literals של String, Number ו-Boolean

כל ערך של string, number, bigint או boolean אפשר לכתוב כטיפוס. הקומפיילר יקבל אז רק את הערך המדויק הזה.

let method: "GET" = "GET";
let code: 404 = 404;
let ok: true = true;
let big: 10n = 10n;

type Port = 80 | 443 | 8080;
const port: Port = 443;

boolean עצמו הוא פשוט ה-union true | false, ולכן צמצום של boolean עם if (flag) משאיר את false בענף ה-else.

Unions של Literals

השימוש הנפוץ הוא union שמפרט כל ערך מותר. בתוך הפונקציה הקומפיילר מצמצם את ה-union בזמן שאתם בודקים אותו, כך שכל ענף יודע בדיוק איזה ערך יש לו.

type Size = "sm" | "md" | "lg";

function padding(size: Size): number {
  if (size === "sm") return 4;
  if (size === "md") return 8;
  return 16; // size is "lg" here
}

const sizes: Size[] = ["sm", "md", "lg"];
console.log(sizes.map(padding)); // [ 4, 8, 16 ]

union של string literals הוא החלופה המקובלת ל-enum ב-TypeScript. הוא לא עולה כלום בזמן ריצה, הערכים הם מחרוזות רגילות שאפשר להדפיס ללוג ולשלוח ב-JSON, ושגיאת הקלדה היא שגיאת קומפילציה. עוד על היתרונות והחסרונות ב-enums.

Widening: let מול const

כש-TypeScript מסיק טיפוס מ-literal, הוא בודק אם הערך יכול להשתנות. אי אפשר אף פעם להשים ערך חדש למשתנה const, ולכן הוא שומר על ה-literal type. למשתנה let אפשר, ולכן הטיפוס שלו מורחב לטיפוס הכללי.

const a = "hello"; // type: "hello"
let b = "hello";   // type: string
b = "bye";         // fine, b is a string

const n = 42;      // type: 42
let m = 42;        // type: number

let c = a;         // type: string (copying a literal into a let widens it)

console.log(a, b, n, m, c); // hello bye 42 42 hello

רחפו עם העכבר מעל כל שם בעורך כדי לראות את הטיפוס שהוסק. אם אתם רוצים let שמכיל רק ערכים מסוימים, תנו לו annotation: let mode: "light" | "dark" = "light".

למה מאפייני אובייקט מתרחבים

מאפיינים של object literal ניתנים לשינוי, ולכן גם הם מתרחבים, אפילו כשהאובייקט שמור ב-const. זו הדרך הנפוצה ביותר להיתקל ב-literal types בלי כוונה:

// This does not compile: req.method is string, not "GET" | "POST"
function send(url: string, method: "GET" | "POST") {
  console.log(method, url);
}

const req = { url: "/users", method: "GET" };
send(req.url, req.method);

הקומפיילר מדווח:

index.ts(7,15): error TS2345: Argument of type 'string' is not assignable to parameter of type '"GET" | "POST"'.

הטיפוס שמוסק ל-req הוא { url: string; method: string }, כי קוד בהמשך יכול להריץ req.method = "DELETE". יש שלושה תיקונים:

type Method = "GET" | "POST";

function send(url: string, method: Method) {
  console.log(method, url);
}

// 1. Annotate the object (or the property)
const r1: { url: string; method: Method } = { url: "/users", method: "GET" };

// 2. as const on the whole object: every property becomes readonly and literal
const r2 = { url: "/posts", method: "POST" } as const;

// 3. as const on one property only
const r3 = { url: "/tags", method: "GET" as const };

send(r1.url, r1.method);
send(r2.url, r2.method);
send(r3.url, r3.method);

אפשרות רביעית היא satisfies, שבודק את האובייקט מול טיפוס ובאותו זמן שומר על ה-literal types של המאפיינים שלו.

as const

as const הוא const assertion. שימו אותו אחרי ביטוי, והקומפיילר יסיק את הטיפוס הצר ביותר שהוא יכול:

• ערכי string, number ו-boolean שומרים על ה-literal types שלהם
• מאפייני אובייקט הופכים ל-readonly
• array literals הופכים ל-tuples של readonly באורך קבוע

const config = {
  env: "production",
  retries: 3,
  hosts: ["a.example.com", "b.example.com"],
} as const;
// type: { readonly env: "production"; readonly retries: 3;
//         readonly hosts: readonly ["a.example.com", "b.example.com"] }

// @ts-expect-error: Cannot assign to 'env' because it is a read-only property.
config.env = "staging";

const point = [3, 4] as const; // type: readonly [3, 4]
const [x, y] = point;
console.log(config.retries, x + y); // 3 7

ה-assertion קיים רק בזמן קומפילציה. ה-JavaScript שנוצר הוא אותו object literal בלי as const, ולכן שום דבר לא מונע מקוד אחר לשנות אותו בזמן ריצה. אם אתם צריכים הבטחה בזמן ריצה, קראו גם ל-Object.freeze.

טיפוס Union ממערך as const

דפוס נפוץ הוא לשמור את הערכים המותרים במערך אחד, שאפשר לעבור עליו בלולאה בזמן ריצה, ולגזור ממנו את טיפוס ה-union. (typeof arr)[number] פירושו "הטיפוס של כל איבר ב-arr".

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function isRole(value: string): value is Role {
  return (ROLES as readonly string[]).includes(value);
}

for (const input of ["editor", "owner"]) {
  console.log(input, isRole(input)); // editor true, then owner false
}

בלי as const, ROLES היה string[] ו-Role היה string רגיל. ה-cast ל-readonly string[] ב-isRole נחוץ כי includes על tuple של literals מקבל רק את ה-literals האלה, והמטרה של הפונקציה היא לבדוק מחרוזת שאולי אינה אחד מהם. אותו דפוס עם אובייקט עובד גם למפות של מפתח וערך: const Status = { Active: "active", Banned: "banned" } as const, ואז type Status = (typeof Status)[keyof typeof Status].

const Type Parameters

פונקציה גנרית בדרך כלל מרחיבה את ה-literals שמעבירים לה. מאז TypeScript 5.0 אפשר לסמן type parameter כ-const, וכך הקומפיילר מסיק את הארגומנט כאילו היה עליו as const, בלי לבקש מהקורא לכתוב את זה.

function plain<T>(value: T) {
  return value;
}

function exact<const T>(value: T) {
  return value;
}

const a = plain({ kind: "circle", sizes: [1, 2] });
// type: { kind: string; sizes: number[] }

const b = exact({ kind: "circle", sizes: [1, 2] });
// type: { readonly kind: "circle"; readonly sizes: readonly [1, 2] }

console.log(a.kind === b.kind); // true

זה בעיקר כלי לכותבי ספריות: הגדרות routes, builders ו-helpers של סכמות משתמשים בו כדי שהקוראים יקבלו טיפוסים מדויקים מ-literals רגילים.

המשמעויות של const

מילת המפתח const מופיעה בארבעה מקומות שונים בקוד TypeScript:

אף אחד מהם לא מקפיא אובייקט בזמן ריצה. const obj = { a: 1 } עדיין מאפשר obj.a = 2; רק השמה מחדש של obj עצמו היא שגיאה.