Dobre praktyki TypeScript: 8 zasad z przykładami przed i po

Poniższe zasady zapobiegają największej liczbie błędów w prawdziwym kodzie TypeScript. Każda pokazuje najpierw popularną wersję, a potem lepszą, w kodzie, który możesz uruchomić. Najważniejsza jest pierwsza zasada: przestań używać any.

Używaj unknown zamiast any

any wyłącza sprawdzanie typów dla wartości i wszystkiego, co z niej obliczono. unknown też przyjmuje dowolną wartość, ale musisz ją sprawdzić przed użyciem, a to umieszcza sprawdzenie tam, gdzie dane wchodzą do programu:

// 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
}

Granice to miejsca, w których typy przestają być gwarantowane: JSON.parse, odpowiedzi fetch, localStorage, dane z formularzy, zmienne środowiskowe i wiadomości z innych procesów. Waliduj tam dane strażnikiem typu albo biblioteką schematów, a reszta kodu może ufać swoim typom.

Zostaw strict włączone

strict jest domyślne w TypeScript 7; nie wyłączaj go. Dodaj sprawdzenia, które pomija, a które wyłapują najwięcej błędów:

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

noUncheckedIndexedAccess sprawia, że arr[i] i record[key] zawierają undefined, bo właśnie to zwracają dla brakującego indeksu. noImplicitOverride wymaga, żeby metoda podklasy miała override, a noFallthroughCasesInSwitch odrzuca case, który przechodzi do następnego.

Pozwól działać wnioskowaniu

Dodawaj adnotacje tam, gdzie TypeScript nie może wiedzieć: przy parametrach funkcji i typach zwracanych funkcji, których używają inne moduły. Zmienne lokalne i parametry funkcji zwrotnych zostaw wnioskowaniu. Zbędna adnotacja to nie tylko szum; może uczynić typ szerszym niż wartość:

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 ]

Bez komentarza @ts-expect-error wywołanie setStatus(annotated) to błąd TS2345. Wywnioskowane const zachowuje typ literałowy "active", więc zostaje zaakceptowane. Zanim dodasz typ, najedź w edytorze na zmienną i zobacz, co zostało wywnioskowane.

Wybieraj typy unii zamiast enumów

Unia literałów napisowych daje podpowiadanie i wyczerpujące sprawdzenia bez generowanego kodu. Gdy potrzebujesz też listy wartości w czasie działania, wyprowadź typ z tablicy 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 } kompiluje się do obiektu z odwrotnym mapowaniem, a parametr enuma liczbowego przyjmuje każdą zmienną number, nawet taką, która przechowuje wartość spoza enuma. Enumy nie działają też przy usuwaniu typów w Node (TypeScript enum is not supported in strip-only mode). Wady i zalety porównuje strona o enumach.

Sprawdzaj obiekty konfiguracji przez satisfies

Adnotacja obiektu szerokim typem, takim jak Record<string, Route>, sprawdza jego wartości, ale zapomina klucze. satisfies sprawdza to samo i zachowuje dokładny typ:

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;

Użyj adnotacji, gdy zmienna ma mieć dokładnie zadeklarowany typ (parametr funkcji, wartość, którą przypiszesz ponownie). Użyj satisfies dla tablic wyszukiwania, map tras, tokenów motywu i innych stałych obiektów.

Modeluj stan uniami dyskryminowanymi

Jeden obiekt z opcjonalnymi polami dopuszcza stany, które nie mogą wystąpić: loading: true razem z error albo brak data po sukcesie. Unia obiektów ze wspólnym znacznikiem dopuszcza tylko prawdziwe stany, a każda gałąź widzi tylko własne pola:

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

Linia z never to sprawdzenie wyczerpujące. Gdy ktoś doda stan i zapomni go obsłużyć, kompilacja przerwie się w tej linii:

// 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" }));

Błąd to index.ts(14,13): error TS2322: Type '{ status: "cancelled"; }' is not assignable to type 'never'. Wskazuje nieobsłużony przypadek. Dodaj case "cancelled":, a kod się skompiluje.

Unikaj ! i as

Asercja niepustości x! i asercja typu x as T każą kompilatorowi przestać sprawdzać. Żadna z nich nie zmienia wartości w czasie działania, więc błędna asercja staje się później awarią, daleko od swojej przyczyny:

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

Zastąp ! przez ?., ??, wczesny return albo rzucenie błędu z przydatnym komunikatem. Zastąp as strażnikiem typu, który naprawdę sprawdza wartość. Jedyna zawsze bezpieczna asercja to as const, bo tylko zawęża typ i czyni go tylko do odczytu. Dobra konfiguracja lintera (reguły no-non-null-assertion i no-explicit-any z typescript-eslint) oznacza resztę.

Oznaczaj dane jako readonly

Oznaczaj właściwości i tablice jako readonly, gdy kod nie powinien ich zmieniać. Kompilator odrzuca wtedy push, sort i przypisania, a funkcje zwracają nowe wartości zamiast zmieniać swoje dane wejściowe:

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 jest sprawdzane tylko w czasie kompilacji i tylko na jednym poziomie: nie zamraża obiektu w czasie działania. To i tak wystarcza, żeby wyłapać przypadkową zmianę współdzielonego stanu, która powoduje większość takich błędów.