// Стало ✅
const users = new Map<string, number>(); // чётко: ключ — строка, значение — число
users.set('anna', 28);

type Status = 'active' | 'blocked';
const [status, setStatus] = useState<Status>('active'); // сужаем до нужных значений

Зачем:

• Ошибки ловятся на этапе компиляции, а не в продакшене

• Код становится понятнее: сразу видно, какие данные допустимы

• Легче рефакторить: если поменять тип - компилятор покажет все места, где нужно поправить

// Достаточно ✅
const ROLE = 'admin'; // выводится как 'admin' (литерал), а не просто string
const items = new Map([['x', 1]]); // выводится Map<string, number>
const [loaded, setLoaded] = useState(false); // выводится boolean

Правило: Указывайте тип явно только тогда, когда это помогает сузить тип. Во всех остальных случаях - доверяйте TypeScript.

// Безопасно ✅
const removeFirst = (list: ReadonlyArray<User>)

Почему важно:

• Меньше багов из-за побочных эффектов

• Легче тестировать и отлаживать

// Чётко и безопасно ✅ — через объединение с дискриминатором
type AdminAccount = {
  role: 'admin';
  id: number;
  email: string;
  permissions: readonly string[];
};

type GuestAccount = {
  role: 'guest';
  tempToken: string;
};

type Account = AdminAccount | GuestAccount; // компилятор знает, какие поля где есть

Плюсы:

• Ясно, какие данные обязательны в каждом сценарии

• Нет лишнего ?. в коде

• Ошибки «поля не существует» ловятся сразу

// Стало: один явный статус — понятно ✅
type RequestSuccess = { status: 'success'; data: Product[] };
type RequestLoading = { status: 'loading' };
type RequestError = { status: 'error'; message: string };

type Request = RequestSuccess | RequestLoading | RequestError;

// Теперь компилятор проверит, что вы обработали все случаи:
const render = (req: Request) => {
  switch (req.status) {
    case 'success': return <List items={req.data} />; // req.data точно есть
    case 'loading': return <Spinner />;
    case 'error': return <Error msg={req.message} />; // req.message точно есть
    // забыли случай? — компилятор предупредит!
  }
};

Зачем:

• Убирает неопределённость: в каждом состоянии известны точные поля

• Exhaustiveness check: если добавили новый статус - компилятор заставит обработать его везде

• Код самодокументируется

// ✅ Идеально: и значения «заморожены», и типы проверены
const ROLES = ['viewer', 'editor', 'admin'] as const satisfies readonly Role[];

Что даёт:

• as const - делает значения readonly и сужает типы до литералов

• satisfies - проверяет, что значения соответствуют ожидаемому типу, но не «расширяет» их

• Вместе - максимальная безопасность без потери удобства

// Стало ✅ — только допустимые значения
type ApiPath = 'users' | 'posts' | 'comments';
type ApiEndpoint = `/api/${ApiPath}`; // "/api/users" | "/api/posts" | "/api/comments"

const endpoint: ApiEndpoint = '/api/users'; // ✅
const bad: ApiEndpoint = '/api/usrers'; // ❌ Ошибка компиляции!

Где ещё полезно:

• Ключи локализации: translation.${Page}.${Key}

• CSS-классы: ${Color}-${Shade} => 'blue-400' | 'red-200'

• SQL-запросы: SELECT ${Column} FROM ${Table}

// ✅ unknown требует явной проверки перед использованием
const data: unknown = apiCall();

// Вариант 1: тип-гард
if (typeof data === 'object' && data !== null && 'userName' in data) {
  const name = (data as { userName: string }).userName;
}

// Вариант 2: утверждение типа (только если уверены!)
const name = (data as { userName: string }).userName;

Правило: unknown - безопасная альтернатива any. Всегда сужайте тип перед использованием.

// ✅ Безопасно: проверяем перед использованием
if (user.avatar !== null) {
  render(user.avatar);
}

Когда допустимо:

• Работаете с чужой библиотекой, где типы неточные

• Только после явной проверки (type guard)

• С комментарием, почему это необходимо

// ✅ @ts-expect-error — если ошибка уйдёт, компилятор предупредит, что комментарий лишний
// @ts-expect-error: legacyFunc принимает число, а не строку — поправим в v2
const result = legacyFunc('test');

Почему важно: @ts-expect-error - самодокументирующийся и самопроверяющийся. Не даёт забыть про технический долг.

// ✅ type — универсальнее
type Status = 'ok' | 'error';
type User = { name: string; status: Status };

Правило: Используйте type по умолчанию. interface- только когда нужно расширение (declaration merging), например, для глобальных типов.

// ✅ Generic-синтаксис читается лучше, особенно с readonly
const list: ReadonlyArray<string> = ['a', 'b'];
const matrix: Array<Array<number>> = [[1, 2], [3, 4]];

Плюсы Array<T>:

• Однообразный стиль во всём проекте

• Легче читать вложенные типы

• Явно видно, что это массив, а не что-то другое

// ✅ Чётко: это только тип, в рантайме не нужно
import type { User } from './types';

Зачем:

• Уменьшает размер бандла (tree-shaking)

• Явно разделяет «код» и «типы»

• Помогает избежать циклических зависимостей

// ✅ Объект с понятными ключами — легко читать и менять
createOrder({
  method: 'client',
  validate: false,
  minLines: 60,
  maxLines: 120,
  default: null,
  log: true,
  timeout: 2000,
});

Бонус: Можно добавить as const satisfies для проверки допустимых значений параметров.

Правило:

• ✅ В публичных API, хуках, утилитах - указывайте явно (защита от случайных изменений)

• ⚪ Во внутренней логике - можно довериться выводу типов, если код простой

// Публичный хук — тип важен
export const useUsers = (): { users: User[]; loading: boolean } => { ... }

// Внутренняя вспомогательная функция — вывод типов ок
const formatName = (user: User) => `${user.firstName} ${user.lastName}`;

// ✅ Одно поле — одно значение — никаких сомнений
type OrderState = 'pending' | 'processing' | 'confirmed' | 'cancelled';
const state: OrderState = 'pending';

Результат:

• Невозможно невалидное состояние

• Компоненты рендерятся через switch - компилятор проверит полноту

• Легче добавлять новые статусы

Простое правило:

• null - значение есть, но оно «пустое» (например, аватарка не загружена)

• undefined - значения нет вообще (поле не передано, не инициализировано)

type Profile = {
  avatar: string | null; // может быть пустым, но поле всегда есть
  bio?: string; // может вообще отсутствовать в объекте
};

Зачем: Чёткая семантика помогает избегать багов и делает код самодокументирующимся.

Акронимы: ApiUrl, не APIURL; FaqList, не FAQList.

Правило:

• ❌ Не пишите, что делает код - это должно быть видно из имён и структуры

• ✅ Пишите, почему сделано именно так - если причина неочевидна

// ❌ Бесполезно
// Умножаем на 60, чтобы получить минуты
const minutes = seconds * 60;

// ✅ Полезно
// Используем кэширование, потому что API лимитирует 100 запросов/мин
// См. тикет #4421
const data = await fetchWithCache(endpoint);

TSDoc: Используйте для публичных API, хуков, утилит - чтобы IDE показывала подсказки.

 modules/
 └──  ProductPage/
     ├──  index.tsx          # Точка входа
     ├──  components/        # Только для этой страницы
     │   ├── ProductCard/
     │   └── PriceBadge/
     ├──  hooks/             # useProductData, useWishlist
     ├──  utils/             # formatProductPrice
     └──  api/               # fetchProduct, updateCart

Принцип: Группируйте по фичам, а не по типам файлов.

Импорт:

• ./Component - если файл рядом

• @/modules/ProductPage/utils - если из другого модуля

Почему:

• Удалили фичу - удалили папку, и всё

• Перенесли фичу - не надо править 20 импортов

• Новый разработчик быстро находит, где что