Ограничения дженериков и теория вариативности (Variance)

+-------------------------------------------------------------------------+
|                        ИЕРАРХИЯ ПОДТИПОВ (Subtyping)                    |
|                        Admin  <:  User  <:  Entity                      |
+-------------------------------------------------------------------------+
| 1. КОВАРИАНТНОСТЬ (out T) - Направление сохраняется:                   |
|    Producer<Admin>       <:   Producer<User>      <:  Producer<Entity>  |
|    (Безопасно: читатель User гарантированно получит поля User)         |
+-------------------------------------------------------------------------+
| 2. КОНТРАВАРИАНТНОСТЬ (in T) - Направление ОБРАЩАЕТСЯ:                  |
|    Consumer<Entity>      <:   Consumer<User>      <:  Consumer<Admin>   |
|    (Безопасно: обработчик Entity готов принять и User, и Admin)         |
+-------------------------------------------------------------------------+
| 3. ИНВАРИАНТНОСТЬ (in out T) - Приведение ЗАПРЕЩЕНО:                    |
|    Box<Admin>            !=   Box<User>           !=  Box<Entity>       |
|    (Защита от мутаций: запись Entity в Box<Admin> сломала бы типы)     |
+-------------------------------------------------------------------------+

export interface Entity {
  id: string;
}

export interface User extends Entity {
  email: string;
}

export interface Admin extends User {
  permissions: string[];
}

// Дженерик помечен аннотацией 'out': T используется только на вывод
export interface ReadonlyCollection<out T> {
  getById(id: string): T | undefined;
  getAll(): readonly T[];
}

declare let adminCollection: ReadonlyCollection<Admin>;
declare let userCollection: ReadonlyCollection<User>;

// КОВАРИАНТНОСТЬ: Admin <: User => ReadonlyCollection<Admin> <: ReadonlyCollection<User>
// Это полностью безопасно: любой метод возвращает как минимум поля User!
userCollection = adminCollection; // Валидно

const user = userCollection.getById("user-1");
if (user) {
  console.log(user.email); // Корректный доступ
}

import { Entity, User, Admin } from './covariance';

// Дженерик помечен аннотацией 'in': T используется только на вход
export interface Serializer<in T> {
  serialize(data: T): string;
}

declare let entitySerializer: Serializer<Entity>;
declare let userSerializer: Serializer<User>;
declare let adminSerializer: Serializer<Admin>;

// КОНТРАВАРИАНТНОСТЬ: Entity <: User => Serializer<Entity> <: Serializer<User>
// Сериализатор Entity умеет работать с любым Entity.
// Значит, ему можно безопасно передать User или Admin!
userSerializer = entitySerializer; // Валидно!

// Обратное присваивание НЕДОПУСТИМО и вызовет ошибку типов:
// entitySerializer = userSerializer; // Ошибка TS2322!
// userSerializer ожидает поля email, которых нет у базового Entity.

import { User, Admin } from './covariance';

export interface Storage<in out T> {
  read(id: string): T;
  write(item: T): void;
}

declare let adminStorage: Storage<Admin>;
declare let userStorage: Storage<User>;

// ИНВАРИАНТНОСТЬ: Присваивание запрещено в обе стороны!
// userStorage = adminStorage; // Ошибка TS2322!
// adminStorage = userStorage; // Ошибка TS2322!

// ПОЧЕМУ? Анализ разрушения системы типов при гипотетическом допущении:
function unsafeDemonstration(store: Storage<User>, plainUser: User) {
  // Если бы присваивание 'userStorage = adminStorage' было валидным,
  // то через ссылку userStorage мы смогли бы записать обычного User в хранилище Admin!
  store.write(plainUser); 
  // Теперь adminStorage содержит обычного User, у которого отсутствует поле permissions.
  // При вызове adminStorage.read().permissions возник бы runtime TypeError!
}

import { User, Admin } from './covariance';

// 1. Метод интерфейса: исторически БИВАРИАНТЕН
interface EventListenerMethod<T> {
  handle(event: T): void;
}

// 2. Функциональное свойство: строго КОНТРАВАРИАНТНО
interface EventListenerProperty<T> {
  handle: (event: T) => void;
}

declare let adminMethodListener: EventListenerMethod<Admin>;
declare let userMethodListener: EventListenerMethod<User>;

declare let adminPropListener: EventListenerProperty<Admin>;
declare let userPropListener: EventListenerProperty<User>;

// Методная бивариантность допускает опасное присваивание:
adminMethodListener = userMethodListener; // Валидно (контравариантно)
userMethodListener = adminMethodListener; // Валидно! (БИВАРИАНТНОСТЬ - потенциальный runtime crash)

// Строгое функциональное свойство блокирует опасное присваивание:
adminPropListener = userPropListener; // Валидно (контравариантно: User <: Admin)
// userPropListener = adminPropListener; // ОШИБКА TS2322! Заблокировано компилятором.