Помилки у TypeScript, які робить кожен розробник (і як їх виправити)

TypeScript швидко став індустріальним стандартом для фронтенд- та фулстек-розробки. Він обіцяє принести безпеку типів, надійний рефакторинг та самодокументований код у динамічний світ JavaScript. При правильному використанні TypeScript працює як суворий, але корисний колега, який допомагає виявляти помилки ще до того, як код потрапить у продакшн.

Проте багато розробників сприймають TypeScript лише як набір обмежень, які потрібно обійти, а не як систему, з якою варто співпрацювати. Використовуючи лазівки для вимкнення перевірок, зловживаючи приведенням типів або створюючи надмірно складні дженерики, команди отримують код, який успішно компілюється, але все одно падає під час виконання. У цьому детальному матеріалі ми розберемо найпоширеніші архітектурні та синтаксичні помилки при роботі з TypeScript, з'ясуємо причини їх виникнення та впровадимо професійні рішення для забезпечення повної безпеки типів.

---

1. Зловживання типом any та перехід до безпечного unknown

Тип any - це фактично кнопка вимкнення компілятора. Коли ви позначаєте змінну цим типом, ви наказуєте TypeScript повністю ігнорувати перевірку типів для неї та будь-яких пов'язаних з нею виразів. Це повертає ваш проект до стану звичайного JavaScript.

// Небезпечна практика: вимикає всі захисні механізми компілятора
function processUserData(user: any) {
  // Якщо об'єкт user або вкладений об'єкт settings дорівнює undefined, програма впаде в рантаймі
  const theme = user.settings.theme.toLowerCase();
  console.log(`Встановлення теми: ${theme}`);
}

Якщо тип вхідних даних заздалегідь невідомий (наприклад, при отриманні відповіді від стороннього API або парсингу файлів), використання any створює серйозну вразливість. Замість цього використовуйте тип unknown. Він також дозволяє приймати будь-які значення, але компілятор вимагатиме від вас виконати звуження типів (type narrowing) або валідацію перед проведенням будь-яких операцій зі змінною.

Звуження типів через користувацькі захисники (User-Defined Type Guards)

Для безпечної роботи зі змінними типу unknown можна створити функцію-захисник за допомогою ключового слова is:

interface UserProfile {
  id: string;
  settings: {
    theme: string;
  };
}

// Користувацький захисник типу
function isUserProfile(value: unknown): value is UserProfile {
  if (typeof value !== 'object' || value === null) {
    return false;
  }
  
  const candidate = value as Record<string, unknown>;
  
  if (typeof candidate.id !== 'string') {
    return false;
  }
  
  if (typeof candidate.settings !== 'object' || candidate.settings === null) {
    return false;
  }
  
  const settingsCandidate = candidate.settings as Record<string, unknown>;
  return typeof settingsCandidate.theme === 'string';
}

function processSafeUserData(rawInput: unknown) {
  if (isUserProfile(rawInput)) {
    // У цьому блоці TypeScript гарантує, що rawInput відповідає типу UserProfile
    const theme = rawInput.settings.theme.toLowerCase();
    console.log(`Встановлення теми: ${theme}`);
  } else {
    console.error("Отримано невалідний формат профілю користувача");
  }
}

Заміна any на unknown змушує вас обробляти потенційні невідповідності даних на рівні виконання, що робить ваш додаток стійким до непередбачуваних помилок.

---

2. Зловживання приведенням типів (as) та рантайм-валідація через Zod

Приведення типів за допомогою ключового слова as повідомляє компілятору: "Я знаю краще за тебе, просто повір мені". Хоча цей інструмент іноді необхідний при роботі з методами DOM або застарілими бібліотеками, розробники часто використовують його лише для того, щоб швидко приховати помилки компіляції.

interface DBUser {
  id: string;
  email: string;
  role: 'admin' | 'editor' | 'viewer';
}

// Дуже небезпечно: ми припускаємо, що відповідь з сервера точно відповідає DBUser
const fetchUserFromAPI = async (id: string): Promise<DBUser> => {
  const response = await fetch(`/api/users/${id}`);
  const data = await response.json();
  return data as DBUser; 
};

Якщо структура відповіді від API зміниться або поверне порожнє значення, об'єкт не відповідатиме інтерфейсу DBUser, що призведе до помилок штибу Cannot read properties of undefined під час виконання програми.

Використання рантайм-парсингу замість приведення типів

Для безпечного імпорту зовнішніх даних найкраще використовувати бібліотеки для рантайм-валідації схем, наприклад Zod. Це гарантує повну відповідність типів часу компіляції реальним даним у рантаймі.

import { z } from 'zod';

// Описуємо схему валідації для виконання в рантаймі
const DBUserSchema = z.object({
  id: z.string(),
  email: z.string().email(),
  role: z.union([
    z.literal('admin'),
    z.literal('editor'),
    z.literal('viewer')
  ])
});

// Автоматично виводимо тип TypeScript зі схеми
type DBUser = z.infer<typeof DBUserSchema>;

const fetchSafeUserFromAPI = async (id: string): Promise<DBUser> => {
  const response = await fetch(`/api/users/${id}`);
  const rawData = await response.json();
  
  // Перевіряємо структуру даних у реальному часі, викидаючи виняток у разі помилки
  const validatedUser = DBUserSchema.parse(rawData);
  return validatedUser;
};

Завдяки переходу від примусового приведення типів до перевірки схем ви створюєте надійний захисний бар'єр на межах вашої системи, відсікаючи некоректні дані на ранніх етапах.

---

3. Надмірне ускладнення дженериків замість простого поліморфізму

Дженерики є потужним засобом створення гнучкого коду, проте їх часто використовують там, де звичайний інтерфейс чи об'єднання типів виглядали б набагато простіше та читабельніше.

Розглянемо приклад надмірно ускладненого дженерика:

// Занадто складно та нечитабельно
function getRecordId<T extends { id: string }>(record: T): string {
  return record.id;
}

Використання дженерика тут не дає жодних переваг, оскільки функція не використовує параметр типу для зв'язку вхідних даних з типом поверненого значення. Вона завжди повертає звичайний рядок. Ми можемо спростити цей код за допомогою поліморфізму інтерфейсів:

interface Identifiable {
  id: string;
}

// Проста та зрозуміла альтернатива
function getRecordIdSimple(record: Identifiable): string {
  return record.id;
}

Коли насправді потрібні дженерики

Дженерики слід застосовувати лише тоді, коли існує чітка залежність між типами різних аргументів функції або між типами аргументів та значенням, яке повертає функція. Наприклад:

// Коректне використання дженериків: пов'язує тип елементів масиву з типом результату трансформації
function mapRecord<T, U>(items: T[], transformer: (item: T) => U): U[] {
  return items.map(transformer);
}

Перед додаванням дженерика <T> до сигнатури функції запитайте себе: чи допомагає цей параметр зв'язати два чи більше елементи функції? Якщо ні, краще використовувати звичайні інтерфейси.

---

4. Нерозуміння структурної типізації та пастка додаткових властивостей

TypeScript базується на концепції структурної типізації (її ще називають "качиною типізацією"). Якщо два об'єкти мають однакову форму (набір властивостей та їх типи), вони вважаються сумісними, незалежно від способу їх створення.

interface Point2D {
  x: number;
  y: number;
}

function printCoordinates(point: Point2D) {
  console.log(`Координати: x: ${point.x}, y: ${point.y}`);
}

const point3D = { x: 10, y: 20, z: 30 };
printCoordinates(point3D); // Компілюється без жодних проблем!

Оскільки об'єкт point3D містить властивості x та y, він повністю задовольняє контракт інтерфейсу Point2D. Однак поведінка TypeScript змінюється, якщо передати об'єктний літерал безпосередньо у функцію (це називається перевіркою додаткових властивостей - excess property checking):

// Помилка: Об'єктний літерал може містити лише відомі властивості, 'z' не існує в 'Point2D'
printCoordinates({ x: 10, y: 20, z: 30 });

Цей механізм призначений для виявлення випадкових друкарських помилок. Проте він часто викликає подив у розробників, які не розуміють, чому збереження об'єкта в окрему змінну перед передачею вирішує цю проблему.

Безпечне використання індексних сигнатур

Якщо ваш об'єкт має підтримувати динамічний набір додаткових полів, ви можете явно вказати це за допомогою індексної сигнатури:

interface DynamicPoint {
  x: number;
  y: number;
  [key: string]: unknown; // Дозволяє додавати будь-які інші властивості
}

function printDynamicCoordinates(point: DynamicPoint) {
  console.log(`Координати: x: ${point.x}, y: ${point.y}`);
}

// Тепер компілюється без помилок навіть при передачі літералу безпосередньо
printDynamicCoordinates({ x: 10, y: 20, z: 30 });

---

5. Засилля необов'язкових полів проти розрізнюваних об'єднань (Discriminated Unions)

При моделюванні станів додатку розробники часто створюють один великий інтерфейс, роблячи всі його поля необов'язковими для репрезентації різних етапів виконання асинхронних операцій.

// Небезпечна модель стану
interface FetchState {
  data?: string;
  error?: string;
  isLoading: boolean;
}

Такий підхід створює простір для виникнення неможливих станів. Наприклад, коли одночасно присутні і дані data, і помилка error, або коли isLoading дорівнює false, але жодного результату чи помилки немає. Код, який використовує такий стан, перетворюється на купу вкладених перевірок.

// Написання логіки обробки стає заплутаним і схильним до помилок
function renderState(state: FetchState) {
  if (state.isLoading) {
    return "Завантаження...";
  }
  if (state.error) {
    return `Помилка: ${state.error}`;
  }
  if (state.data) {
    return `Дані: ${state.data}`;
  }
  return "Невідомий стан"; // Сигнал про погану архітектуру
}

Моделювання станів за допомогою Discriminated Unions

Набагато кращим підходом є використання розрізнюваних об'єднань. Ми додаємо спільне поле-ідентифікатор (дискримінант) для розділення станів на взаємовиключні типи:

type FetchState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: string }
  | { status: 'error'; error: Error };

function renderSafeState(state: FetchState) {
  switch (state.status) {
    case 'idle':
      return "Готовий до завантаження";
    case 'loading':
      return "Завантаження...";
    case 'success':
      // TypeScript автоматично звужує тип до стану Success
      return `Дані: ${state.data}`;
    case 'error':
      // TypeScript автоматично звужує тип до стану Error
      return `Помилка: ${state.error.message}`;
  }
}

Така архітектура виключає можливість створення некоректного стану на етапі написання коду, позбавляє від зайвих перевірок та спрощує бізнес-логіку додатку.

---

6. Проблеми вбудованого типу Omit та впровадження StrictOmit

TypeScript містить багато корисних допоміжних типів, таких як Pick, Omit та Exclude. Однак вбудований тип Omit має суттєвий недолік: він дозволяє вказати для видалення будь-який ключ, навіть якщо його взагалі немає у вихідному об'єкті.

interface UserConfig {
  theme: string;
  notifications: boolean;
  version: number;
}

// Компілятор мовчить, хоча ключа 'nonExistentKey' не існує в UserConfig
type TruncatedConfig = Omit<UserConfig, 'version' | 'nonExistentKey'>;

Це призводить до проблем під час рефакторингу. Якщо ви перейменуєте або видалите властивість у вихідному інтерфейсі UserConfig, тип Omit не покаже жодної помилки, залишаючи застарілі та неіснуючі ключі в коді.

Створення власного типу StrictOmit

Ми можемо створити свій тип, який перевірятиме, щоб список ключів для видалення був підмножиною ключів вихідного типу:

// Оголошуємо StrictOmit з перевіркою ключів через keyof
type StrictOmit<T, K extends keyof T> = Omit<T, K>;

// Тепер компілятор покаже помилку, якщо вказати неіснуючий ключ
type SafeConfig = StrictOmit<UserConfig, 'version' | 'nonExistentKey'>;

                   Порівняння Omit та StrictOmit
                   
+------------------------------------+------------------------------------+
  Omit<UserConfig, 'invalidKey'>     | StrictOmit<UserConfig, 'invalidKey'>
+------------------------------------+------------------------------------+
  Компілюється без помилок           | Викликає помилку компіляції        
  Ігнорує неіснуючі ключі            | Змушує оновлювати ключі при рефакторі
  Створює ризик застарілих мапінгів  | Гарантує цілісність структури типів
+------------------------------------+------------------------------------+

Використання StrictOmit замість стандартного типу захищає вашу кодову базу від накопичення застарілих зв'язків при структурних змінах.

---

7. Побічні ефекти мутабельності та переваги readonly

Для створення чистої та передбачуваної архітектури функції не повинні змінювати свої аргументи. За замовчуванням об'єкти та масиви в TypeScript є мутабельними, що створює ризик появи прихованих багів у стані вашого додатку.

interface Cart {
  items: string[];
}

function clearCartItem(cart: Cart, index: number) {
  // Пряма мутація вихідного масиву
  cart.items.splice(index, 1); 
}

Щоб запобігти випадковим змінам даних, завжди оголошуйте інтерфейси та масиви як read-only.

Використання readonly та ReadonlyArray

Застосування ключового слова readonly до полів інтерфейсів та використання ReadonlyArray<T> (або скороченого запису readonly T[]) блокує виклик мутуючих методів на етапі компіляції:

interface ImmutableCart {
  readonly items: readonly string[];
}

function safeClearCartItem(cart: ImmutableCart, index: number): ImmutableCart {
  // cart.items.splice(index, 1); // Помилка: Метод 'splice' не існує для типу 'readonly string[]'
  
  // Повертаємо новий об'єкт замість модифікації наявного
  return {
    items: cart.items.filter((_, idx) => idx !== index)
  };
}

Такий підхід стимулює писати чисті функції без побічних ефектів, що чудово узгоджується з принципами сучасної декларативної розробки.

Уникаючи цих поширених помилок, ви зможете перетворити TypeScript із джерела постійного роздратування та боротьби з компілятором на надійний автоматизований інструмент контролю якості вашої кодової бази.