Интуиция вариантности

Три отношения, один вопрос

Пусть Dog extends Animal (каждая Dog — это Animal). Вариантность спрашивает: для конструктора типа F<_> как F<Dog> относится к F<Animal>?

• Ковариантно — F<Dog> присваиваем F<Animal> (подтипизация течёт в ту же сторону). Производители только-чтение.
• Контравариантно — F<Animal> присваиваем F<Dog> (подтипизация течёт в обратную сторону). Потребители входа.
• Инвариантно — ни в одну сторону; только точные совпадения.
• Бивариантно — принимаются обе стороны (несоундно; TS делает это намеренно в одном месте).

Вместе эти четыре случая покрывают любую позицию, которую может занимать переменная типа: производит ли конструктор типа, потребляет или делает и то и другое — это и определяет, какое направление безопасно. Следующие три раздела покажут каждый случай на реальном TypeScript, включая тот, где TS сознательно выбирает несоундный вариант.

Почему параметры функций контравариантны

Функция, принимающая Animal, может подменить функцию, принимающую Dog, — потому что всё, что передаёт ей Dog, передаёт корректный Animal. Обратное небезопасно:

type Animal = { name: string };
type Dog = { name: string; bark(): void };

const feedAnimal = (a: Animal) => a.name;
let feedDog: (d: Dog) => string;

feedDog = feedAnimal; // ок — Dog ЕСТЬ Animal, feedAnimal с ним справится
// небезопасное направление:
let feedAnimal2: (a: Animal) => string;
const handleDog = (d: Dog) => d.bark();
// feedAnimal2 = handleDog;
// Error (под strictFunctionTypes): handleDog нужен bark(), но его могут
//        вызвать с обычным Animal без bark.

Принимать более широкий вход безопасно; принимать вход уже, чем обещает слот, — это дыра: вызов с более широким значением, которое слот допускает, коснулся бы отсутствующих членов. Поэтому параметры самостоятельных функций контравариантны.

Почему массивы (несоундно) ковариантны

TypeScript считает Array<Dog> присваиваемым Array<Animal>, хотя массивы изменяемы — намеренная, известная несоундность ради эргономики:

const dogs: Dog[] = [{ name: "Rex", bark: () => {} }];
const animals: Animal[] = dogs; // разрешено — ковариантные массивы
animals.push({ name: "Whiskers" }); // кладём не-Dog в Dog[]!
dogs[1].bark();
// Рантайм: bark is not a function — система типов нас не остановила.

Соундная система сделала бы позицию изменяемого элемента инвариантной. TS выбирает ковариантность, потому что преобладает чтение из массивов, а полная инвариантность была бы мучительна. Знать о существовании этой дыры — сеньорский вывод.

Ловушка бивариантных методов

Теперь баг из хука. strictFunctionTypes (TS 2.6) делает параметры самостоятельных типов-функций контравариантными — но по замыслу это не распространяется на параметры методов, которые остаются бивариантными. Одинаково выглядящие объявления ведут себя по-разному:

// tsconfig: { "strictFunctionTypes": true }
type Handler = (e: Event) => void;

// Синтаксис МЕТОДА — параметр БИВАРИАНТЕН (ловушка):
interface BusMethod {
  on(handler: (e: Event) => void): void;
}
// Синтаксис СВОЙСТВА — параметр КОНТРАВАРИАНТЕН (проверяется):
interface BusProp {
  on: (handler: (e: Event) => void) => void;
}

declare const m: BusMethod;
declare const p: BusProp;

const narrow = (e: MouseEvent) => e.button;

m.on(narrow); // ✅ НЕТ ОШИБКИ — параметр метода бивариантен (несоундно!)
p.on(narrow);
// ❌ Error: '(e: MouseEvent) => number' не присваиваем '(e: Event) => void'
//    Типы параметров 'e' несовместимы:
//    в 'Event' отсутствуют свойства 'MouseEvent' (button, ...).

Единственное отличие — сокращение метода (on(...)) против свойства, хранящего функцию (on: (...) => ...). Форма метода пропускает слишком узкий обработчик MouseEvent, поэтому при диспетчеризации обычного Event поле e.button оказывается undefined. Поэтому методы Array.prototype и многие DOM/event API принимают колбэки, технически слишком узкие, — бивариантность вшита в форму объявления метода.

Аннотации вариантности: in / out (TS 4.7)

TS 4.7 позволяет заявить намеренную вариантность параметра типа через in (контравариантно) и out (ковариантно). Проверяющий затем сверяет, что ваше использование соответствует — а ещё аннотация документирует намерение и может ускорить проверку:

interface Producer<out T> {  // T встречается только в позициях вывода
  get(): T;
}
interface Consumer<in T> {   // T встречается только в позициях ввода
  set(value: T): void;
}
interface Box<in out T> {    // T и читается, и пишется → инвариантно
  get(): T;
  set(value: T): void;
}

// Если объявить `out`, но затем написать T во входной позиции, получите:
interface Bad<out T> {
  set(value: T): void;
// Error: тип 'T' объявлен ковариантным ('out'), но встречается
//        в контравариантной позиции.  (примерно)
}

Аннотации не меняют правила присваиваемости, которые проверяющий уже выводит; они позволяют утвердить и навязать намеренную вариантность, ловя ошибку, например, добавления сеттера к типу, который вы обещали как чистого производителя.

Числа и версии за этими дырами

Каждое из этих поведений привязано к конкретному релизу, и даты важны, когда читаешь tsconfig или гоняешься за вопросом «почему это вообще когда-то проходило проверку». Бивариантные параметры методов и несоундная ковариантность массивов предшествуют strict-режиму целиком. strictFunctionTypes появился в TS 2.6 (окт 2017) и ужесточил отдельные параметры функциональных типов до контравариантных — но намеренно оставил параметры метод-сокращений и конструкторов бивариантными, и это ровно та дыра, которой пользуется зачин. Аннотации вариантности in/out появились в TS 4.7 (май 2022). Так что баг с обработчиком, проскользнувший через слот-метод, — не дефект компилятора для багрепорта, а девятилетний задокументированный компромисс, и "strictFunctionTypes": false (или отсутствие strict: true) молча расширяет дыру на все параметры функций.

У аннотаций есть и измеренный выигрыш в производительности — поэтому крупные кодовые базы внедряют их сверх документационной ценности. Вывод вариантности для глубоко рекурсивного дженерик-типа — работа, которую проверяющий повторяет; указание out T / in T позволяет ему пропустить этот вывод и использовать вашу декларацию напрямую. Команда TS сообщала, что аннотации вариантности и связанные изменения кэширования заметно сократили время структурного сравнения на тяжёлых дженерик-типах — порядка десятков процентов времени проверки на худших рекурсивных типах — а это разница между отзывчивым редактором и тормозящим на большой схеме или глубоко дженериковом типе ORM. Аннотация, таким образом, — три вещи сразу: документация, страховка корректности против неверно объявленного производителя/потребителя и подсказка проверяющему, способная отыграть время проверки.