[Перевод] Нецелевое использование утверждающих функций в TypeScript
Это ужасный (но очень полезный) хак, который я придумал для добавления типов в старый код. Вчера мой коллега, работающий над добавлением типов в одну из наших основных библиотек на LinkedIn, спросил меня, как быть со старым (и уже не рекомендуемым) паттерном. В качестве одного из вариантов решения мы попробовали применить утверждающую функцию. вразрез с её предназначением. В конечном итоге нам не удалось добиться конкретно желаемого 1, но мне этот паттерн показался достаточно интересным, чтобы им поделиться.
Мотивация
Предположим, у вас есть старый JS API, который зависит от мутирования передаваемого ему объекта. В идиоматическом TS я бы порекомендовал создать полностью новый объект, используя некую форму композиции — декорирование, делегирование и т.д. Однако в некоторых сценариях нельзя внести изменения, не нарушив работу множества потребителей, в связи с чем необходимо предоставить рабочий TS API (возможно, на время создания более подходящего API для перехода). В таком случае можно использовать функцию asserts для моделирования этого поведения в системе типов.
Утверждающие функции
Эти функции используются в TS для выполнения определённой проверки аргументов, выбрасывая в случае её провала ошибку. Каноническим примером здесь будет assert из Node:
assert(someCondition, "Message if it fails");
В данном случае, если someCondition окажется ложен, функция вместо возвращения результата выбросит ошибку. TS позволяет нам смоделировать такое поведение путём указания, что функция утверждает условие, представленное someCondition:
declare function assert(value: unknown, error: string | Error): asserts value;
То есть она утверждает, что аргумент value должен быть true, и в противном случае — результат не возвращает. После вызова assert TS благодаря анализу потока управления знает, является ли переданный предикат истинным. Этот приём можно использовать с любыми предикатами, чтобы получить больше информации о типах, с которыми вы работаете:
function rejectNonStrings(value: unknown) {
assert(typeof value === 'string', "It wasn't a string!");
// Теперь этот тип проходит проверку, потому что TS знает, что ‘value’ является `string`:
console.log(value.length);
}
Этого базового примера для целей статьи вполне хватит: теперь у нас есть достаточно информации, чтобы понять, как можно использовать asserts не по назначению для решения совершенно иной задачи. Если вы хотите углубиться в тему более детально, ознакомьтесь с соответствующей документацией Microsoft и статьёй Мариуса Шульца «Assertion Functions in TypeScript».
Нецелевое применение
В качестве упрощённого примера я использую базовый класс Person и функцию, которая изменяет его, добавляя адрес. В JS:
class Person {
constructor(age, name) {
this.age = age;
this.name = name;
}
}
function addAddress(person, address) {
person.address = address;
}
let me = new Person(34, 'Chris');
addAddress(me, '1234 Some St., Example City, CO 00000');
console.log(me.address);
При изначальном преобразовании этого кода в TS компилятор сообщит нам, что реализация addAddress небезопасна.
class Person {
age: number;
name?: string | undefined;
constructor(age: number, name?: string | undefined) {
this.age = age;
this.name = name;
}
}
function addAddress(person: Person, address: string): void {
person.address = address;
// ^^^^^^^ Свойство 'address' не существует в типе 'Person'.
}
let me = new Person(34, 'Chris');
addAddress(me, '1234 Some St., Example City, CO 00000');
console.log(me.address);
// ^^^^^^^ Свойство 'address' не существует в типе 'Person'.
Можно ввести интерфейс, который будет представлять Person с адресом, и выполнить безопасное «расширяющее» приведение типа:
class Person {
// образец реализации
}
interface PersonWithAddress extends Person {
address: string;
}
function addAddress(person: Person, address: string) {
// БЕЗОПАСНОСТЬ: TS допустит это, только если `person` *может* быть сужен или расширен до
// этого типа. Сужение окажется небезопасным; расширение же строго безопасно,
// но не в том смысле, в котором его поддерживает TS. Код остаётся безопасным только потому, что мы
// сразу инициализируем полностью новые поля.
(person as PersonWithAddress).address = address;
}
Работает! …но только внутри тела функции. На стороне вызова тот факт, что элемент Person теперь содержит поле address, по-прежнему остаётся незаметен:
console.log(me.address);
// ^^^^^^^ Свойство 'address' не существует в типе 'Person'.
Именно здесь мы прибегаем к приёму asserts, которому и посвящена статья. Можно обновить addAddress, утвердив, что передаваемый person фактически является типом PersonWithAddress:
function addAddress(
person: Person,
address: string
): asserts person is PersonWithAddress {
(person as PersonWithAddress).address = address;
}
Теперь при вызове addAddress TS узнаёт о существовании поля address:
addAddress(me, '1234 Some St., Example City, CO 00000');
console.log(me.address);
Всё благодаря утверждению, что вызов addAddress также указывает на наличие в me поля адреса. Заметьте, что это не совсем верно…но по факту соответствует правильной семантике. Если хотите поиграться сами, то можете открыть этот пример в песочнице TS.
Оговорки
Первое и самое важное: это небезопасно. Компилятор не будет проверять вашу работу. Так бывает всегда при использовании утверждающих функций (а также функций защиты типов), но в данном случае этот нюансы заслуживает отдельного выделения. Мы следуем на LinkedIn норме, согласно которой аннотируем подобные моменты комментариями //БЕЗОПАСНОСТЬ: — эту идею мы позаимствовали из подхода сообщества Rust к работе с блоками unsafe. (Можете заметить это в коде выше).
Правило таково: если реализация включает приведение типа, то легитимность этого приведения необходимо хорошо объяснить, чтобы будущие мейнтейнеры могли сохранить эти инварианты. И, конечно же, если у вас есть возможность избежать использования приведений, так и поступайте –, но как минимум изолируйте их и закомментируйте.
Второе — это поможет только в том случае, если утверждающая функция будет частью обычного потока управления. Подобные мутации на уровне типов не задерживаются на всю жизнь объекта, как это бывает со значениями среды выполнения. Например, если у вас есть два метода класса, один из которых использует утверждающую функцию для обновления this, другой метод ничего об этом знать не будет:
class Person {
// существующая реализация...
addAddress(address: string): this is PersonWithAddress {
this.address = address;
}
addHobbies(hobbies: string[]): this is PersonWithHobbies {
this.hobbies = hobbies;
}
describe(): string {
let base = `${this.name} is a ${this.age}-year-old`;
let location = `living in ${this.address}`;
// ^^^^^^^ не существует!
let listFormatter =
new Intl.ListFormat('en', { style: 'long', type: 'conjunction' });
let hobbies = listFormatter.format(this.hobbies);
// ^^^^^^^ не существует!
return `${base} ${location}, who likes to do ${hobbies}`;
}
}
Третье — подобное мутирование объектов негативно сказывается на быстродействии: виртуальные машины JS лучше всего оптимизируют объекты с согласующимися формами, а этот приём их согласованность нарушает.
Если говорить в целом, то единственной причиной использовать этот подход может стать моделирование существующих API, которые действуют подобным образом, и при этом у вас нет возможности их изменить.
Обобщение нецелевого использования
На деле можно обобщить этот приём до утилиты, представляющей подобные операции расширения на основе мутации:
function extend(
value: T,
extension: U
): asserts value is T & U {
Object.assign(value, extension);
}
Это позволит нам работать подобным образом с любыми типами объектов:
let person = {
name: 'Chris',
age: 34,
};
// Работает!
