Лучшие практики TypeScript: 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, ввод из форм, переменные окружения и сообщения от других процессов. Проверяйте данные там защитником типа или библиотекой схем, и остальной код сможет доверять своим типам.

Не выключайте strict

В TypeScript 7 strict включён по умолчанию; не выключайте его. Добавьте проверки, которые он не включает и которые ловят больше всего ошибок:

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

noUncheckedIndexedAccess заставляет arr[i] и record[key] включать undefined, а именно это они и возвращают для отсутствующего индекса. noImplicitOverride требует, чтобы метод подкласса был помечен override, а noFallthroughCasesInSwitch отвергает case, который проваливается в следующий.

Доверяйте выводу типов

Аннотируйте то, чего TypeScript знать не может: параметры функций и возвращаемые типы функций, которыми пользуются другие модули. Типы локальных переменных и параметров колбэков оставьте выводу. Лишняя аннотация это не только шум; она может сделать тип шире значения:

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", поэтому принимается. Прежде чем добавлять тип, наведите курсор на переменную в редакторе и посмотрите, что было выведено.

Предпочитайте объединения типов перечислениям

Объединение строковых литералов даёт автодополнение и проверку полноты без сгенерированного кода. Если список значений нужен ещё и во время выполнения, выведите тип из массива 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 нет. Кроме того, enum не работают при удалении типов в Node (TypeScript enum is not supported in strip-only mode). Плюсы и минусы сравниваются на странице enum.

Проверяйте объекты конфигурации через 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 для таблиц поиска, карт маршрутов, токенов темы и других константных объектов.

Моделируйте состояние размеченными объединениями

Один объект с опциональными полями допускает невозможные состояния: loading: true вместе с error или отсутствие data после успеха. Объединение объектов с общей меткой допускает только реальные состояния, и каждая ветка видит только свои поля:

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 это проверка полноты. Если кто-то добавит состояние и забудет его обработать, сборка сломается на этой строке:

// 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 утверждение x! и утверждение типа x as T велят компилятору прекратить проверку. Ни то, ни другое не меняет значение во время выполнения, поэтому ошибочное утверждение позже превращается в падение, далеко от своей причины:

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 на защитник типа, который действительно проверяет значение. Единственное всегда безопасное утверждение это as const, потому что оно только сужает тип и делает его доступным лишь для чтения. Хорошая настройка линтера (правила 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 проверяется только во время компиляции и только на один уровень вглубь: во время выполнения объект не замораживается. Но этого достаточно, чтобы поймать случайное изменение общего состояния, из-за которого и возникает большинство таких ошибок.