TypeScript: генерики, утилітарні типи та звуження

Що таке генерик і яку проблему він розвʼязує?

Генерик (generic) — це тип, параметризований іншим типом: він приймає тип-аргумент так само, як функція приймає значення-аргумент. Потрібен він тоді, коли один хелпер має працювати з різними формами даних, а жорсткий тип змусив би або дублювати функцію під кожну сутність, або зісковзнути на any й розгубити всі перевірки. Візьми функцію, що повертає перший елемент масиву: з підписом first<T>(items: T[]): T | undefined вона тримає зв'язок «що на вході — те й на виході», тож для масиву чисел віддасть number | undefined, а для рядків — string | undefined. Якби замість T стояло any[], результат став би any, і автодоповнення з контролем типів зникли б саме там, де мали захищати. У тестовому коді на генериках стоять типобезпечні білдери фікстур і хелпери на кшталт pick, що приймають будь-яку сутність.

Як TypeScript визначає, чим є T під час виклику генерика?

Здебільшого компілятор виводить (inference) тип-аргумент сам зі значень, які ти передав, — писати first<number>([1, 2]) руками майже ніколи не доводиться. Дав масив чисел — T став number, дав рядки — string. Явна вказівка тип-аргументу в кутових дужках потрібна лише там, де вивести його нема звідки: порожній контейнер або значення, з якого форму не видно. Додатково існує тип за замовчуванням — function make<T = string>() підставить string, якщо підстав вивести щось інше немає. Тобто порядок такий: спершу явний тип-аргумент, тоді виведення зі значень, а вже потім дефолт.

Навіщо в генериках extends і чим воно відрізняється від успадкування класів?

extends у генериках задає обмеження (constraint) — мінімальний контракт, якому тип-аргумент мусить відповідати, а не ієрархію «батько-нащадок». Голий T не дає жодних гарантій: усередині функції не можна читати ні .id, ні .length, бо T — будь-що. Запис T extends { id: number } каже компілятору «T — будь-який тип, сумісний із цією формою», і тоді всередині доступне item.id, а на виході зберігається повний тип елемента з усіма полями, не обрізаний до { id: number }. Плутанина з класовим extends тут головна пастка на співбесіді: це «підтип / сумісний із», а не наслідування реалізації. На цьому ж механізмі побудована половина утилітарних типів.

Що таке звуження типів (narrowing) і як компілятор його виконує?

Звуження — це коли на підставі перевірок у коді TypeScript у конкретній гілці бачить тип вужчий за оголошений. Union на кшталт string | number описує кілька форм одразу, але .toFixed() є лише в number, тож поки тип не звужено, компілятор не дасть викликати метод однієї з форм. Робить це аналіз потоку керування (control flow analysis): після if (typeof value === "number") у тілі if змінна вже точно number, а в гілці else — string. Тобто ти не переконуєш компілятор словами, а він сам читає твої перевірки й перераховує тип по ходу виконання. Практично це те, що дає безпечно розібрати відповідь мережі чи User | null, не хапаючись за as.

Які є способи звуження і коли кожен доречний?

Базовий набір: typeof x === "..." для union примітивів (string, number, boolean тощо), x instanceof C для класів і вбудованих обʼєктів (Error, Date), "key" in x для union обʼєктів різної форми, truthiness-перевірка if (x) щоб відсіяти null/undefined, порівняння x === "passed" для union літералів і Array.isArray(x) для випадку T | T[]. Вибір диктує те, що саме треба розрізнити: примітиви — typeof, класи — instanceof, обʼєкти-«сирці» без класу — in або кастомний guard. Окремо стоїть дискримінований union, де розрізняють за спільним полем-міткою. Знати межі кожного важливо: неправильний інструмент дає або помилку компіляції, або тихо неправильне звуження.

Чому typeof не годиться для розрізнення обʼєктів?

Бо для всього обʼєктного typeof повертає однакове "object": і typeof {}, і typeof [], і typeof null дають рядок, з якого форму не відновити (null взагалі історична аномалія). Тому union на кшталт User | Order через typeof розрізнити неможливо — обидва «object». Тут вмикається in (перевірка за наявним полем: "email" in x) або instanceof (перевірка за прототипом класу). Останній працює лише з тим, що створено через new і має відповідний прототип, тож годиться для Error чи власних класів, але не для розпарсеного JSON — у нього прототип звичайний, і payload instanceof User завжди false. Для «сирих» обʼєктів залишаються in і кастомний type guard.

Що таке дискримінований union і чому він зручний для API-відповідей?

Дискримінований union (discriminated union) — це union обʼєктів, у кожному з яких є спільне поле-мітка з літеральним типом, наприклад status: "ok" проти status: "error". Перевірка цієї мітки звужує весь обʼєкт: після if (res.status === "ok") компілятор знає, що є res.data, а в іншій гілці — що є res.message. Це найнадійніший спосіб типізувати «або успіх, або помилка» — саме та форма, у якій найчастіше приходять відповіді бекенду. Перевага перед перевіркою окремих полів у тому, що мітка одна й вона керує всією формою: не треба гадати, які поля сумісні між собою. У тестах це дає читати data чи message без as і без ризику звернутися до поля, якого в цій гілці немає.

Що таке кастомний type guard і як працює предикат x is T?

Коли вбудованих typeof/in/instanceof замало, логіку перевірки виносять у функцію-охоронець (type guard), яка замість boolean повертає особливий тип-предикат value is T. Це обіцянка компілятору: «якщо я повернула true, вважай значення типом T». Усередині ти перевіряєш руками (бо приймаєш unknown), а на місці виклику компілятор довіряє результату й звужує тип у гілці if. Приклад — isUser(value): value is User, що перевіряє наявність числового id і рядкового email. Ключове застереження: за коректність тіла відповідаєш ти, не компілятор — якщо предикат бреше, звуження теж бреше, і баг випливе в рантаймі. Саме тому для зовнішніх даних часто беруть схемні валідатори замість ручних guardʼів.

Чим assertion-функція (asserts x is T) відрізняється від звичайного type guard?

Type guard повертає прапорець, який ти сам перевіряєш у if; assertion-функція нічого не повертає, а кидає виняток, якщо умова не виконана. Її підпис — function assertUser(value: unknown): asserts value is User, і після її виклику решта коду вже працює зі звуженим типом без обгортання в if. Це зручно на межі підготовки даних: одна перевірка на вході — і далі гарантований тип по всьому тілу. Різниця в стилі керування: guard дає розгалуження (if (isUser(x)) {...} else {...}), assertion — «або далі з правильним типом, або падаємо тут-таки зі зрозумілою помилкою». В API-тестах assertion зручний тим, що перетворює «сервер повернув не те» на явний фейл на межі, а не на загадкове undefined через пʼять рядків.

Чим as відрізняється від satisfies?

as — це твердження типу (type assertion), наказ компілятору «повір, тут саме цей тип» без жодної перевірки в рантаймі; він лише вимикає власний контроль TypeScript і нічого не конвертує. satisfies (з TypeScript 4.9) — навпаки, перевіряє, що значення відповідає типу, але не розширює виведений тип до нього, тобто зберігає точну, вузьку форму з конкретними ключами й літералами. Порівняй мапу роутів: const a: Routes = {...} і const a = {...} as Routes віддають широкий Record<string, string>, тож звернення до неіснуючого ключа компілятор пропустить; а const b = {...} satisfies Routes зловить помилку в самому обʼєкті й лишить точні типи полів. Коротко: анотація і as дають широкий тип, satisfies перевіряє форму й тримає вузький. Сильна відповідь додає, що as небезпечний на результаті JSON.parse, бо може мовчки збрехати.

Чому as User на відповіді API — погана ідея?

Тому що as не валідує нічого в рантаймі — він лише глушить перевірки компілятора саме на межі із зовнішнім світом, де вони найпотрібніші. Написав const data = await res.json() as User — і компілятор повірить, що там User, навіть якщо сервер змінив форму: data.email спокійно скомпілюється, а в рантаймі дасть undefined або впаде глибше й незрозуміло. Виглядає як типізація відповіді, а фактично це розписка «я знаю краще», що знімає захист. Правильний підхід — прийняти відповідь як unknown і звузити її type guardʼом чи assertion-функцією, а в бойовому коді — схемним валідатором (zod, ajv), який дає і рантайм-перевірку, і статичний тип з одного джерела. Тоді помилка «прийшло не те» стає явною й локалізованою на вході.

Що робить as const і навіщо він потрібен?

as const — особлива форма твердження, яка робить літерали максимально вузькими й readonly: const status = "passed" as const дає тип "passed", а не string, а ["smoke", "api"] as const — readonly ["smoke", "api"], а не string[]. Без нього TypeScript «розширює» літерали до загального типу, і ти втрачаєш конкретику, потрібну для дискримінованих union чи ключів. Типовий кейс — константа-обʼєкт, з якої потім виводять тип: const roles = { admin: 1, guest: 2 } as const дозволяє написати keyof typeof roles і отримати "admin" | "guest". Тобто as const — це не «вимкнути перевірку», як звичайний as, а «зафіксувати найточніший можливий тип». Це один із небагатьох випадків, де as доречний і безпечний.

Що таке keyof і typeof на рівні типів, і що дає їх зв'язка?

keyof T повертає union літеральних типів усіх ключів обʼєкта: для { id: number; email: string } це "id" | "email". Оператор typeof у контексті типу (не плутати з рантайм-typeof зі звуження) бере тип із наявного значення: type Config = typeof config виведе форму обʼєкта-константи. Разом keyof typeof obj дає union ключів обʼєкта, для якого окремого типу не оголошено, — стандартний спосіб не дублювати тип руками, а вивести його з константи. На цьому будують типобезпечні хелпери: getField<T, K extends keyof T>(obj, key): T[K] не дасть передати неіснуючий ключ і поверне точний тип поля через індексований доступ T[K], а не any. Головна цінність — джерело істини одне: змінилося значення, автоматично оновився й тип.

Розкажи про Partial, Pick, Omit, Record, ReturnType — де застосовував у тестах?

Це вбудовані генерики, що виводять похідні типи з базового. Partial<T> робить усі поля опційними — основа білдера фікстур: buildUser(overrides: Partial<User> = {}) зливає часткові оверрайди з дефолтами. Pick<T, K> лишає тільки перелічені ключі (вузький DTO — Pick<User, "id" | "email">), Omit<T, K> навпаки прибирає їх (тіло на створення без серверного id — Omit<User, "id">). Record<K, V> описує мапу «ключ → значення» (наприклад Record<Role, User>), а ReturnType<F> дає тип, що повертає функція, — зручно взяти тип фікстури просто з фабрики: ReturnType<typeof buildUser>. Головна вигода — одне джерело істини: зміниш базовий User, і всі похідні форми оновляться самі. Для async-фабрик додають Awaited<ReturnType<typeof f>>, щоб розгорнути Promise<User> до User.

Що повертає response.json() і як безпечно типізувати відповідь API?

І в fetch, і в Playwright response.json() повертає any (у fetch — Promise<any>), а any тихо вимикає перевірки: body.usr.email з одруком спокійно скомпілюється й впаде лише в рантаймі. Дисципліна — не довіряти цьому any, а прийняти відповідь як unknown і звузити її явно: type guardʼом, assertion-функцією або схемним валідатором. Тоді помилка «сервер повернув не ту форму» стає видимою на межі, а не спливає загадковим undefined глибше в тесті. Категорично не варто підмінювати перевірку на as User — це той самий вимкнений захист, лише замаскований. Для реальних проєктів межу зазвичай тримають zod/ajv: одна схема дає і рантайм-валідацію, і статичний тип (z.infer), тож вони не розходяться між собою.

Як типізують фікстури в Playwright через test.extend?

test.extend — генерик: його тип-параметр описує форму фікстур, які ти додаєш, тож оголосивши base.extend<Fixtures>({...}), ти отримуєш автодоповнення полів прямо в тесті. Наприклад, з type Fixtures = { authUser: User; apiToken: string } у тілі тесту authUser типізовано як User, а apiToken — як string, і IDE підказує їхні поля замість мовчання. Замість описувати тип фікстури руками часто виводять його з фабрики через ReturnType<typeof buildUser> — тоді зміна фабрики автоматично протікає в тип фікстури, і вони не розсинхронюються. Це та сама ідея одного джерела істини, що й з утилітарними типами. Практична вигода: помилку в назві поля фікстури компілятор ловить ще до запуску тесту, а не в рантаймі як undefined.

Три кейси, у яких генерики, звуження й утилітарні типи вирішують, чи впаде тест зрозуміло, чи спливе загадковим undefined: типобезпечний білдер фікстур на Partial<T>, безпечний розбір відповіді API через unknown + assertion-функцію, і вибір між as та satisfies для набору тестових даних. Скрізь — що робити і чому саме так.

Кейс 1. Білдер фікстур: Partial<T> + виведення типу з фабрики

Тестам потрібен User, але кожен кейс хоче свій нюанс: тут role: "guest", там прострочений email. Описувати повний обʼєкт у кожному тесті — шум і дублювання; приймати «будь-який обʼєкт» — втратити перевірки. Правильна форма — фабрика з дефолтами, що бере часткові оверрайди через Partial<User>.

type User = { id: number; email: string; role: "admin" | "guest" };

const defaultUser: User = { id: 1, email: "a@test.io", role: "admin" };

function buildUser(overrides: Partial<User> = {}): User {
  return { ...defaultUser, ...overrides };
}

const guest = buildUser({ role: "guest" });   // решта полів — з дефолтів
const typo = buildUser({ rol: "guest" });      // помилка компіляції: немає ключа rol

Далі тип фікстури не описуємо руками, а виводимо з фабрики — тоді зміна buildUser протікає в тип автоматично:

type BuiltUser = ReturnType<typeof buildUser>;   // User, без ручного дублювання

// для async-фабрики розгортаємо Promise
async function buildUserAsync() {
  return buildUser({ role: "admin" });
}
type BuiltAsync = Awaited<ReturnType<typeof buildUserAsync>>;   // теж User

Що дивитися і чому:

• Partial<User>, а не User, у параметрі оверрайдів. Оверрайди — часткові за визначенням, тож повний User змусив би передавати всі поля щоразу. Але межа тонка: якщо функція вимагає, щоб поле точно було, Partial там — дірка, через яку undefined розійдеться по коду.
• rol замість role компілятор ловить одразу. Це і є сенс типізованого білдера проти голого обʼєкта: одрук у ключі оверрайду червоніє на компіляції, а не стає мовчазним undefined у тесті.
• ReturnType<typeof buildUser> — одне джерело істини. Додаси в User поле — фабрика й похідний тип оновляться разом. Продублюєш тип руками — рано чи пізно він розійдеться з фабрикою, і саме це видасть плутаний фейл.

Кейс 2. Відповідь API: unknown + assertion замість as User

response.json() у Playwright і fetch віддає any, а any тихо пропускає будь-яке звернення до полів. Спокуса — дописати as User і читати body.email. Проблема: as нічого не перевіряє, тож коли бекенд змінить форму, тест впаде не на межі, а десь глибше й незрозуміло. Дисципліна — прийняти як unknown і звузити явно.

type User = { id: number; email: string };

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    typeof (value as Record<string, unknown>).id === "number" &&
    typeof (value as Record<string, unknown>).email === "string"
  );
}

function assertUser(value: unknown): asserts value is User {
  if (!isUser(value)) throw new Error("Відповідь не має форми User");
}

У самому тесті assertion ставить чіткий барʼєр на вході:

import { test, expect } from "@playwright/test";

test("GET /user повертає обʼєкт форми User", async ({ request }) => {
  const res = await request.get("https://app.example.com/api/user/1");
  expect(res.status()).toBe(200);

  const raw: unknown = await res.json();
  assertUser(raw);                       // кине зрозумілу помилку, якщо форма не та
  expect(raw.email).toBe("a@test.io");   // тут raw вже звужено до User
});

Що дивитися і чому:

• unknown, а не any, на вході. any вимкнув би перевірки мовчки; unknown змушує звузити тип, перш ніж читати поля, — компілятор не дасть звернутися до raw.email без guardʼа.
• assertUser перетворює «прийшло не те» на явний фейл. Помилка каже, що зламалася саме форма відповіді, і падає на межі. Без цього одрук сервера usr замість user виліз би через кілька рядків як undefined, і час пішов би на хибний слід.
• instanceof тут не спрацював би. res.json() дає звичайний обʼєкт без прототипу класу User, тож raw instanceof User завжди false — розрізняти форму можна лише через in / перевірку полів, як у isUser.
• У бойовому коді межу тримають zod/ajv. Ручний guard старіє: додаси в User поле, а isUser його не перевірятиме. Схема дає рантайм-перевірку й тип (z.infer) з одного джерела, тож вони не розходяться.

Коли форм відповіді кілька, надійніше типізувати їх дискримінованим union і звужувати за міткою:

type ApiResult =
  | { status: "ok"; data: User }
  | { status: "error"; message: string };

function readResult(res: ApiResult): User | null {
  if (res.status === "ok") return res.data;   // звужено до успіху
  console.warn(res.message);                    // звужено до помилки
  return null;
}

Кейс 3. Набір тестових даних: as vs satisfies

Є мапа фікстур «роль → користувач». Хочеться і перевірки, що значення правильної форми, і збереження точних ключів, щоб звернення до неіснуючої ролі впало на компіляції. Порівняймо три способи звʼязати обʼєкт із типом:

const users = {
  admin: buildUser({ role: "admin" }),
  guest: buildUser({ role: "guest" }),
} satisfies Record<string, User>;

users.admin;     // ок, тип User
users.manager;   // помилка компіляції: такого ключа немає

Що дивитися і чому:

• Анотація й as розширюють тип до Record<string, User>. Тоді users.manager компілятор пропустить, бо Record дозволяє будь-який рядковий ключ, — а в рантаймі це undefined і плутаний фейл у тесті, що звернувся до неіснуючої фікстури.
• satisfies перевіряє форму й лишає вузький тип. Кожне значення звіряється з User, але точні ключі (admin, guest) зберігаються, тож звернення до manager червоніє одразу.
• as тут — найгірший варіант. Він не перевіряє навіть форму значень: якщо в обʼєкт закрадеться поле не з User, as це проковтне. Для наборів даних, конфігів і мап роутів дефолт — satisfies, а as лишай для випадків, де компілятор об'єктивно не може вивести тип сам (наприклад, DOM-елемент).

Генерики й extends

• Розумію, що генерик — тип, параметризований типом: тримає зв'язок «тип входу = тип виходу» (first<T>(items: T[]): T | undefined) і рятує від дублювання функцій чи скочування на any[], що цей зв'язок рве.
• Знаю, що тип-аргумент здебільшого виводиться зі значень (inference), явно в кутових дужках його вказують лише коли вивести нема звідки, і що є дефолтний тип-параметр <T = string>.
• Розумію extends у генериках як обмеження (constraint) — мінімальний контракт, а не успадкування класів.
• Можу пояснити, що T extends { id: number } відкриває доступ до .id усередині й водночас зберігає повний тип елемента на виході.

Звуження типів (narrowing)

• Розумію, що звуження робить аналіз потоку керування: після перевірки тип у гілці вужчий за оголошений.
• Знаю набір інструментів: typeof (примітиви), instanceof (класи), in (обʼєкти різної форми), truthiness, порівняння літералів, Array.isArray.
• Можу пояснити, чому typeof безсилий на обʼєктах (усе — "object") і чому instanceof завжди false на розпарсеному JSON — для «сирих» обʼєктів потрібні in або кастомний guard.
• Можу описати дискримінований union (спільне поле-мітка) і чому це найнадійніша типізація «успіх або помилка».

Type guards і assertion-функції

• Знаю синтаксис предиката value is T і що на місці виклику компілятор довіряє результату й звужує тип.
• Пам'ятаю, що за коректність тіла guardʼа відповідаю я, не компілятор: збрешеш — звуження теж збреше в рантаймі, тому ручні guardʼи старіють, а zod/ajv тримають тип і перевірку з одного джерела.
• Розрізняю type guard (повертає прапорець для if) і assertion-функцію asserts x is T (кидає виняток, звужує далі без if).

Утилітарні типи

• Знаю, що роблять Partial, Required, Pick, Omit, Record, ReturnType; типовий кейс — білдер фікстур на Partial<T> і DTO на створення через Omit<T, "id">.
• Розумію головну цінність — одне джерело істини (зміна базового типу протікає в усі похідні), і знаю Awaited<ReturnType<typeof f>> для розгортання Promise<User> в async-фабриках.

keyof, typeof і індексований доступ

• Розрізняю рантайм-typeof (звуження значень) і typeof на рівні типів (вивести тип із значення).
• Знаю, що keyof T дає union літеральних ключів, keyof typeof obj — ключі константи без окремого типу, а T[K] — тип значення під ключем (основа типобезпечного getField).

as vs satisfies

• Розрізняю as (наказ без рантайм-перевірки, широкий тип, може збрехати) і satisfies (перевірка форми зі збереженням вузького типу — точні ключі й літерали).
• Знаю as const як безпечну форму: фіксує найвужчий readonly-тип для дискримінованих union і ключів.
• Можу пояснити, чому as User на JSON.parse/response.json() знімає захист саме там, де він найпотрібніший.

Типізація фікстур і API-відповідей

• Знаю, що test.extend<Fixtures> — генерик, і як він дає автодоповнення полів фікстур у тесті.
• Пам'ятаю, що response.json() віддає any — приймаю як unknown і звужую guardʼом/схемою, а тип фікстури виводжу з фабрики (ReturnType<typeof buildUser>), не дублюю руками.