Точні типи TypeScript: Сувора відповідність форм об'єктів для надійного коду

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

Розуміння структурної типізації TypeScript

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

Наприклад:

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

const myPoint = { x: 10, y: 20, z: 30 };

function printPoint(point: Point) {
  console.log(`X: ${point.x}, Y: ${point.y}`);
}

printPoint(myPoint); // Це працює нормально, навіть якщо myPoint має властивість 'z'

У цьому сценарії TypeScript дозволяє передати `myPoint` до `printPoint`, оскільки він містить необхідні властивості `x` та `y`, хоча й має зайву властивість `z`. Хоча така гнучкість може бути зручною, вона також може призводити до непомітних помилок, якщо ви ненавмисно передаєте об'єкти з несподіваними властивостями.

Проблема із зайвими властивостями

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

interface Config {
  apiUrl: string;
  timeout: number;
}

function setup(config: Config) {
  console.log(`API URL: ${config.apiUrl}`);
  console.log(`Timeout: ${config.timeout}`);
}

const myConfig = { apiUrl: "https://api.example.com", timeout: 5000, typo: true };

setup(myConfig); // TypeScript тут не скаржиться!

console.log(myConfig.typo); // виводить true. Зайва властивість існує непомітно

У цьому прикладі `myConfig` має зайву властивість `typo`. TypeScript не викликає помилки, оскільки `myConfig` все ще задовольняє інтерфейс `Config`. Однак одрук ніколи не виявляється, і застосунок може поводитися не так, як очікувалося, якщо `typo` мало бути `typoo`. Ці, на перший погляд, незначні проблеми можуть перерости у великі головні болі під час налагодження складних застосунків. Відсутня або неправильно написана властивість може бути особливо важко виявити при роботі з об'єктами, вкладеними в інші об'єкти.

Підходи до забезпечення точних типів у TypeScript

Хоча справжні "точні типи" не доступні безпосередньо в TypeScript, ось кілька технік для досягнення подібних результатів та забезпечення суворішої відповідності форм об'єктів:

1. Використання тверджень типу з Omit

Допоміжний тип Omit дозволяє створювати новий тип, виключаючи певні властивості з існуючого типу. У поєднанні з твердженням типу це може допомогти запобігти зайвим властивостям.

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

const myPoint = { x: 10, y: 20, z: 30 };

// Створюємо тип, що включає лише властивості Point
const exactPoint: Point = myPoint as Omit & Point;

// Помилка: Тип '{ x: number; y: number; z: number; }' неможливо призначити типу 'Point'.
// Об'єктний літерал може вказувати лише відомі властивості, а 'z' не існує в типі 'Point'.

function printPoint(point: Point) {
  console.log(`X: ${point.x}, Y: ${point.y}`);
}


//Виправлення
const myPointCorrect = { x: 10, y: 20 };
const exactPointCorrect: Point = myPointCorrect as Omit & Point;
printPoint(exactPointCorrect);

Цей підхід викликає помилку, якщо `myPoint` має властивості, які не визначені в інтерфейсі `Point`.

Пояснення: `Omit` створює тип, який виключає всі ключі, присутні в `Point`, з типу `myPoint`. Потім `& Point` перетинає цей тип з типом `Point`, по суті вимагаючи, щоб об'єкт відповідав типу `Point`. Застосовуючи твердження до цього комбінованого типу, компілятор перевіряє наявність зайвих властивостей і видає помилку, якщо такі знайдені. Це змушує нас оголошувати правильну форму при початковому визначенні нашого об'єкта.

2. Використання функції для створення об'єктів

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

interface Config {
  apiUrl: string;
  timeout: number;
}

function createConfig(config: Config): Config {
  return {
    apiUrl: config.apiUrl,
    timeout: config.timeout,
  };
}

const myConfig = createConfig({ apiUrl: "https://api.example.com", timeout: 5000 });

//Це не скомпілюється:
//const myConfigError = createConfig({ apiUrl: "https://api.example.com", timeout: 5000, typo: true });
//Аргумент типу '{ apiUrl: string; timeout: number; typo: true; }' неможливо призначити параметру типу 'Config'.
// Об'єктний літерал може вказувати лише відомі властивості, а 'typo' не існує в типі 'Config'.

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

3. Використання охоронців типів

Охоронці типів (type guards) — це функції, які звужують тип змінної в межах певної області видимості. Хоча вони не запобігають безпосередньо зайвим властивостям, вони можуть допомогти вам явно перевіряти їх і вживати відповідних заходів.

interface User {
  id: number;
  name: string;
}

function isUser(obj: any): obj is User {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    'id' in obj && typeof obj.id === 'number' &&
    'name' in obj && typeof obj.name === 'string' &&
    Object.keys(obj).length === 2 // перевірка кількості ключів. Примітка: крихко і залежить від точної кількості ключів User.
  );
}

const potentialUser1 = { id: 123, name: "Alice" };
const potentialUser2 = { id: 456, name: "Bob", extra: true };

if (isUser(potentialUser1)) {
  console.log("Valid User:", potentialUser1.name);
} else {
  console.log("Invalid User");
}

if (isUser(potentialUser2)) {
  console.log("Valid User:", potentialUser2.name); //Сюди виконання не дійде
} else {
  console.log("Invalid User");
}

У цьому прикладі охоронець типу `isUser` перевіряє не тільки наявність необхідних властивостей, але й їхні типи та *точну* кількість властивостей. Цей підхід є більш явним і дозволяє вам коректно обробляти недійсні об'єкти. Однак перевірка кількості властивостей є крихкою. Щоразу, коли `User` отримує/втрачає властивості, перевірку потрібно оновлювати.

4. Використання Readonly та as const

Хоча `Readonly` запобігає зміні існуючих властивостей, а `as const` створює кортеж або об'єкт лише для читання, де всі властивості є глибоко read-only і мають літеральні типи, їх можна використовувати для створення суворішого визначення та перевірки типів у поєднанні з іншими методами. Проте, жоден з них сам по собі не запобігає зайвим властивостям.

interface Options {
  width: number;
  height: number;
}

//Створюємо тип Readonly
type ReadonlyOptions = Readonly;

const options: ReadonlyOptions = { width: 100, height: 200 };

//options.width = 300; //помилка: Неможливо присвоїти 'width', оскільки це властивість лише для читання.

//Використання as const
const config = { api_url: "https://example.com", timeout: 3000 } as const;

//config.timeout = 5000; //помилка: Неможливо присвоїти 'timeout', оскільки це властивість лише для читання.

//Однак зайві властивості все ще дозволені:
const invalidOptions: ReadonlyOptions = { width: 100, height: 200, depth: 300 }; //немає помилки. Все ще дозволяє зайві властивості.


interface StrictOptions {
  readonly width: number;
  readonly height: number;
}

//Тепер це викличе помилку:
//const invalidStrictOptions: StrictOptions = { width: 100, height: 200, depth: 300 };
//Тип '{ width: number; height: number; depth: number; }' неможливо призначити типу 'StrictOptions'.
//  Об'єктний літерал може вказувати лише відомі властивості, а 'depth' не існує в типі 'StrictOptions'.

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

5. Використання бібліотек (наприклад, Zod, io-ts)

Бібліотеки, такі як Zod та io-ts, пропонують потужні можливості валідації типів під час виконання та визначення схем. Ці бібліотеки дозволяють вам визначати схеми, які точно описують очікувану форму ваших даних, включаючи запобігання зайвим властивостям. Хоча вони додають залежність часу виконання, вони пропонують дуже надійне та гнучке рішення.

Приклад з Zod:

import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});

type User = z.infer;

const validUser = { id: 1, name: "John" };
const invalidUser = { id: 2, name: "Jane", extra: true };

const parsedValidUser = UserSchema.parse(validUser);
console.log("Parsed Valid User:", parsedValidUser);

try {
  const parsedInvalidUser = UserSchema.parse(invalidUser);
  console.log("Parsed Invalid User:", parsedInvalidUser); // Цей код не буде виконано
} catch (error) {
  console.error("Validation Error:", error.errors);
}

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

Найкращі практики для забезпечення точних типів

Ось кілька найкращих практик, які слід враховувати при забезпеченні суворішої відповідності форм об'єктів у TypeScript:

• Обирайте правильну техніку: Найкращий підхід залежить від ваших конкретних потреб та вимог проєкту. Для простих випадків може вистачити тверджень типу з `Omit` або фабричних функцій. Для складніших сценаріїв або коли потрібна валідація під час виконання, розгляньте використання бібліотек, таких як Zod або io-ts.
• Будьте послідовними: Застосовуйте обраний підхід послідовно по всій вашій кодовій базі для підтримки єдиного рівня безпеки типів.
• Документуйте свої типи: Чітко документуйте свої інтерфейси та типи, щоб повідомити іншим розробникам очікувану форму ваших даних.
• Тестуйте свій код: Пишіть юніт-тести для перевірки того, що ваші обмеження типів працюють належним чином, і що ваш код коректно обробляє недійсні дані.
• Враховуйте компроміси: Забезпечення суворішої відповідності форм об'єктів може зробити ваш код надійнішим, але також може збільшити час розробки. Зважте переваги та витрати й оберіть підхід, який найбільше підходить для вашого проєкту.
• Поступове впровадження: Якщо ви працюєте над великою існуючою кодовою базою, розгляньте можливість поступового впровадження цих технік, починаючи з найкритичніших частин вашого застосунку.
• Надавайте перевагу інтерфейсам над псевдонімами типів при визначенні форм об'єктів: Інтерфейси зазвичай є кращими, оскільки вони підтримують злиття оголошень, що може бути корисним для розширення типів у різних файлах.

Приклади з реального світу

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

• Корисні навантаження запитів до API: Надсилаючи дані до API, вкрай важливо переконатися, що корисне навантаження відповідає очікуваній схемі. Застосування точних типів може запобігти помилкам, спричиненим надсиланням несподіваних властивостей. Наприклад, багато API для обробки платежів надзвичайно чутливі до несподіваних даних.
• Файли конфігурації: Файли конфігурації часто містять велику кількість властивостей, і одруки можуть бути поширеними. Використання точних типів може допомогти виявити ці одруки на ранній стадії. Якщо ви налаштовуєте розташування серверів у хмарному розгортанні, одрук у налаштуванні локації (наприклад, eu-west-1 замість eu-wet-1) буде надзвичайно важко налагодити, якщо його не виявити одразу.
• Конвеєри перетворення даних: При перетворенні даних з одного формату в інший важливо забезпечити, щоб вихідні дані відповідали очікуваній схемі.
• Черги повідомлень: Надсилаючи повідомлення через чергу повідомлень, важливо переконатися, що корисне навантаження повідомлення є дійсним і містить правильні властивості.

Приклад: Конфігурація інтернаціоналізації (i18n)

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

interface Translation {
  greeting: string;
  farewell: string;
}

interface I18nConfig {
  locale: string;
  translations: Translation;
}

const englishConfig: I18nConfig = {
  locale: "en-US",
  translations: {
    greeting: "Hello",
    farewell: "Goodbye"
  }
};


//Це буде проблемою, оскільки існує зайва властивість, яка непомітно вносить помилку.
const spanishConfig: I18nConfig = {
  locale: "es-ES",
  translations: {
    greeting: "Hola",
    farewell: "Adiós",
    typo: "unintentional translation"
  }
};

//Рішення: Використання Omit
const spanishConfigCorrect: I18nConfig = {
  locale: "es-ES",
  translations: {
    greeting: "Hola",
    farewell: "Adiós"
  } as Omit & Translation
};

Без точних типів одрук у ключі перекладу (наприклад, додавання поля `typo`) може залишитися непоміченим, що призведе до відсутності перекладів в інтерфейсі користувача. Забезпечуючи суворішу відповідність форм об'єктів, ви можете виявляти ці помилки під час розробки та запобігати їх потраплянню в продакшн.

Висновок

Хоча TypeScript не має вбудованих "точних типів", ви можете досягти подібних результатів, використовуючи комбінацію функцій та технік TypeScript, таких як твердження типу з `Omit`, фабричні функції, охоронці типів, `Readonly`, `as const` та зовнішні бібліотеки, як-от Zod та io-ts. Забезпечуючи суворішу відповідність форм об'єктів, ви можете покращити надійність свого коду, запобігти поширеним помилкам і зробити ваші застосунки більш надійними. Не забувайте обирати підхід, який найкраще відповідає вашим потребам, і бути послідовними у його застосуванні по всій вашій кодовій базі. Ретельно розглядаючи ці підходи, ви можете отримати більший контроль над типами вашого застосунку та підвищити його довгострокову підтримку.