TypeScript Best Practices: 8 כללים עם לפני ואחרי

הכללים הבאים הם אלה שמונעים הכי הרבה באגים בקוד TypeScript אמיתי. כל אחד מציג קודם את הגרסה הנפוצה ואחר כך את הגרסה הטובה יותר, בקוד שאפשר להריץ. הכלל הראשון הכי חשוב: הפסיקו להשתמש ב-any.

השתמשו ב-unknown במקום any

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

// Before: any switches off checking for everything it touches.
function totalAny(items: any): number {
  return items.reduce((sum: number, item: any) => sum + item.price, 0);
}
console.log(totalAny([{ price: 2 }, { cost: 3 }])); // NaN, no error anywhere

// After: take unknown, check once at the boundary, then work with real types.
interface Item {
  price: number;
}

function isItems(value: unknown): value is Item[] {
  return Array.isArray(value) && value.every((i) => typeof i?.price === "number");
}

function total(input: unknown): number {
  if (!isItems(input)) throw new Error("Expected a list of items with prices");
  return input.reduce((sum, item) => sum + item.price, 0);
}

console.log(total([{ price: 2 }, { price: 3 }])); // 5
try {
  total([{ price: 2 }, { cost: 3 }]);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Expected a list of items with prices
}

הגבולות הם המקומות שבהם הטיפוסים כבר לא מובטחים: JSON.parse, תשובות של fetch, localStorage, קלט מטפסים, משתני סביבה והודעות מתהליכים אחרים. בצעו שם ולידציה עם type guard או עם ספריית סכמות, ושאר הקוד יוכל לסמוך על הטיפוסים שלו.

השאירו את strict פעיל

strict הוא ברירת המחדל ב-TypeScript 7; אל תכבו אותו. הוסיפו את הבדיקות שהוא משאיר בחוץ ושתופסות הכי הרבה באגים:

{
    "compilerOptions": {
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "noImplicitOverride": true,
        "noFallthroughCasesInSwitch": true
    }
}

noUncheckedIndexedAccess גורם ל-arr[i] ול-record[key] לכלול undefined, כי זה מה שהם מחזירים לאינדקס חסר. noImplicitOverride מחייב מתודה של תת-מחלקה לכתוב override, ו-noFallthroughCasesInSwitch דוחה case שממשיך ישר לזה שאחריו.

תנו להסקת הטיפוסים לעבוד

תנו הערות טיפוס למה ש-TypeScript לא יכולה לדעת: פרמטרים של פונקציות, וטיפוסי ההחזרה של פונקציות שמודולים אחרים משתמשים בהן. השאירו משתנים מקומיים ופרמטרים של callbacks להסקה. הערת טיפוס מיותרת היא לא רק רעש; היא יכולה להפוך טיפוס לרחב יותר מהערך:

type Status = "active" | "banned";

function setStatus(status: Status): string {
  return `status set to ${status}`;
}

const annotated: string = "active"; // annotation widens the type to string
// @ts-expect-error string is not assignable to Status
setStatus(annotated);

const inferred = "active"; // inferred as the literal type "active"
console.log(setStatus(inferred)); // status set to active

const users = [{ id: 1, name: "Ada" }, { id: 2, name: "Lin" }];
const ids = users.map((u) => u.id); // inferred: number[]
console.log(ids); // [ 1, 2 ]

בלי ההערה @ts-expect-error, הקריאה setStatus(annotated) היא השגיאה TS2345. ה-const שהטיפוס שלו הוסק שומר על טיפוס הליטרל "active", ולכן הוא מתקבל. רחפו מעל משתנה בעורך כדי לראות מה הוסק לפני שאתם מוסיפים טיפוס.

העדיפו union types על פני enums

union של ליטרלים של מחרוזות נותן השלמה אוטומטית ובדיקות ממצות בלי קוד שנוצר. כשצריך גם את רשימת הערכים בזמן ריצה, גזרו את הטיפוס ממערך as const:

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

function canEdit(role: Role): boolean {
  return role !== "viewer";
}

console.log(canEdit("editor"));     // true
console.log(ROLES.filter(canEdit)); // [ 'admin', 'editor' ]

canEdit("owner"); // error TS2345: Argument of type '"owner"' is not assignable to parameter of type '"admin" | "editor" | "viewer"'.

enum Role { Admin, Viewer } מתקמפל לאובייקט עם מיפוי הפוך, ופרמטר של enum מספרי מקבל כל משתנה number, גם כזה שמחזיק ערך שה-enum לא מפרט. בנוסף, enums לא יכולים לרוץ תחת type stripping של Node (TypeScript enum is not supported in strip-only mode). השיקולים מושווים בעמוד enums.

בדקו אובייקטי קונפיגורציה עם satisfies

הערת טיפוס רחב כמו Record<string, Route> על אובייקט בודקת את הערכים שלו אבל שוכחת את המפתחות. satisfies בודק את אותו הדבר ושומר את הטיפוס המדויק:

interface Route {
  path: string;
  auth: boolean;
}

// Annotated: every string key is allowed, so typos are not caught.
const loose: Record<string, Route> = {
  home: { path: "/", auth: false },
};
console.log(loose.hmoe); // undefined, and no compile error

// satisfies: checked against Route, but the exact keys are kept.
const routes = {
  home: { path: "/", auth: false },
  admin: { path: "/admin", auth: true },
} satisfies Record<string, Route>;

console.log(routes.admin.path); // /admin
// @ts-expect-error Property 'hmoe' does not exist
routes.hmoe;

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

תארו מצב עם discriminated unions

אובייקט יחיד עם שדות אופציונליים מאפשר מצבים שלא יכולים לקרות: loading: true יחד עם error, או data חסר אחרי הצלחה. union של אובייקטים עם תגית משותפת מאפשר רק את המצבים האמיתיים, וכל ענף רואה רק את השדות שלו:

type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "error"; message: string };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", "); // data exists only here
    case "error":
      return `Error: ${state.message}`;
    default: {
      const unreachable: never = state; // fails if a case is missing
      return unreachable;
    }
  }
}

console.log(render({ status: "success", data: ["a", "b"] })); // a, b
console.log(render({ status: "error", message: "timeout" }));  // Error: timeout

השורה עם never היא הבדיקה הממצה. כשמישהו מוסיף מצב ושוכח לטפל בו, ה-build נשבר בשורה הזו:

// This does not compile: a new state was added but not handled.
type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "cancelled" };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", ");
    default: {
      const unreachable: never = state;
      return unreachable;
    }
  }
}

console.log(render({ status: "loading" }));

השגיאה היא index.ts(14,13): error TS2322: Type '{ status: "cancelled"; }' is not assignable to type 'never'. היא מציינת את המקרה שלא טופל. הוסיפו case "cancelled": והקוד יעבור קומפילציה.

הימנעו מ-! ומ-as

ה-non-null assertion x! וה-type assertion x as T אומרים לקומפיילר להפסיק לבדוק. אף אחד מהם לא משנה את הערך בזמן ריצה, ולכן assertion שגוי הופך מאוחר יותר לקריסה, רחוק מהסיבה שלה:

interface User {
  name: string;
}

const users = new Map<string, User>([["ada", { name: "Ada" }]]);

// Before: ! and as silence the compiler, and the crash moves to run time.
try {
  console.log(users.get("bob")!.name);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Cannot read properties of undefined (reading 'name')
}
const fake = {} as User;
console.log(fake.name); // undefined, typed as string

// After: handle the missing case where it can happen.
const bob = users.get("bob");
console.log(bob?.name ?? "unknown user"); // unknown user

החליפו את ! ב-?., ב-??, ב-return מוקדם, או בזריקת שגיאה עם הודעה מועילה. החליפו את as ב-type guard שבאמת בודק את הערך. ה-assertion היחיד שתמיד בטוח הוא as const, כי הוא רק הופך טיפוס לצר יותר ולקריאה בלבד. הגדרת lint טובה (no-non-null-assertion ו-no-explicit-any של typescript-eslint) מסמנת את השאר.

הפכו מידע ל-readonly

סמנו מאפיינים ומערכים כ-readonly כשקוד לא אמור לשנות אותם. אז הקומפיילר דוחה push, sort והשמות, ופונקציות מחזירות ערכים חדשים במקום לשנות את הקלט שלהן:

interface Settings {
  readonly theme: "light" | "dark";
  readonly tags: readonly string[];
}

function withTag(settings: Settings, tag: string): Settings {
  // settings.tags.push(tag) would not compile
  return { ...settings, tags: [...settings.tags, tag] };
}

const before: Settings = { theme: "dark", tags: ["a"] };
const after = withTag(before, "b");
console.log(before.tags, after.tags); // [ 'a' ] [ 'a', 'b' ]

// @ts-expect-error Cannot assign to 'theme' because it is a read-only property.
before.theme = "light";

readonly נבדק רק בזמן קומפילציה ורק ברמה אחת לעומק: הוא לא מקפיא את האובייקט בזמן ריצה. זה עדיין מספיק כדי לתפוס את השינוי המקרי של מצב משותף שגורם לרוב הבאגים האלה.