Как перейти на синтаксис типа объекта с точным по умолчанию

Почти полтора года назад мы объявили о наших планах сделать типы объектов точными по умолчанию. Мы постоянно слышим от наших пользователей, что они почти всегда имеют в виду использовать точные типы объектов, поэтому их установка по умолчанию позволяет разработчикам легче выражать свои намерения. В Facebook у нас уже есть несколько внутренних репозиториев, использующих этот параметр, и мы видели, как многие проекты с открытым исходным кодом также принимают новый синтаксис. В конце концов, точное значение по умолчанию станет нормой в Flow, поэтому мы хотим помочь вам создать собственную кодовую базу для типов объектов с точным по умолчанию.

Приведение вашей кодовой базы к точному по умолчанию синтаксис состоит из трех фаз:

Обновление инструментов разработчика. Убедитесь, что все ваши инструменты поддерживают новый синтаксис.
Изменение кода. Обновите свою кодовую базу, чтобы использовать новый синтаксис.
Обновление зависимостей. Обновите все зависимости кода, чтобы использовать новый синтаксис.

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

Обновление зависимостей Dev

Цель: убедиться, что все ваши инструменты разработчика могут анализировать новый синтаксис.

В кодовых базах JavaScript обычно используется тонна инструментов разработки, которые анализируют код. Вот несколько примеров инструментов, которые вы можете использовать, и версий, до которых вам нужно обновить. Если вы попытаетесь использовать синтаксис {...} перед обновлением одного из этих инструментов, то этот инструмент выйдет из строя с ошибкой синтаксического анализа.

Расход ›= 0,84,0 (рекомендуется 0,112,0+)
Babel / Babel Parser / Babel Generator ›= 7.1.5 (рекомендуется 7.4.5+)
Красивее ›= 1,15 (рекомендовать самые свежие)
babel-eslint ›= v11-beta

После обновления всех этих инструментов попробуйте вручную указать явные неточные типы объектов {...} в нескольких местах своей кодовой базы и позвольте автоматическим тестам работать. Если вы столкнетесь с какими-либо сбоями, связанными с анализатором, трассировки стека могут направить вас к другим пакетам, которые вам нужно обновить.

Codemodding

Цель: иметь возможность включить implicit-inexact-object=error в вашем flowconfig, не получая никаких ошибок

После того, как репозиторий настроен для синтаксического анализа новых неявных неточных типов объектов, вы можете приступить к изменению кода вашего кодовая база. Перед включением точного значения по умолчанию необходимо убедиться, что каждый тип объекта в вашей кодовой базе либо явно точный {||}, либо явно неточный {...}. Таким образом, вы можете включить точное значение по умолчанию, не получая никаких новых ошибок.

Есть два способа изменить код вашей базы кода:

Используйте поток-апгрейд. Это попытается обновить всю вашу кодовую базу сразу. Вы можете вызвать flow-upgrade 0.83.0 <YOUR CURRENT VERSION> для запуска codemod.
Используйте jscodeshift напрямую. По нашему опыту, это проще использовать для больших кодовых баз, когда вы не хотите запускать codemod для всей кодовой базы за один раз. Вы можете использовать jscodeshift -t /path/to/transform.js TARGET_DIR для запуска codemod. Получите трансформацию в этой сути.

Оба эти метода могут пропускать некоторые вхождения неявных неточных объектов. Возможно, вам придется выполнить ручной проход вручную после запуска codemods.

подсказки

Если у вас есть файлы, совместно используемые разными репозиториями, добавьте // flowlint ambiguous-object-type:error в начало этих файлов. Это гарантирует, что все типы объектов будут явно точными {||} или явно неточными {...} независимо от настроек по умолчанию. Это гарантирует, что ваши общие файлы всегда будут означать одно и то же в ваших репозиториях, даже если они имеют разные настройки по умолчанию.

Обновление определений библиотеки

Все потоковые типы были обновлены для использования синтаксиса, совместимого с точным по умолчанию. Любое определение типа потока, предназначенное для потока 0.104+, будет использовать только явные точные типы объектов {||} или явные неточные типы объектов {...}.

Завершение codemods

Как только вы сможете включить implicit-inexact-object=error в разделе [lints] в вашей конфигурации flow, не получая никаких ошибок, вы должны перейти к следующему разделу. Убедитесь, что вы отправили это изменение в flowconfig, чтобы другие соавторы не продолжали вводить новые неявные неточные типы объектов.

Обновление зависимостей

Цель: иметь возможность включать точное значение по умолчанию без каких-либо ошибок

Некоторые из ваших зависимостей могут поставляться с собственными .js.flow файлами и не иметь определений с потоковым типом. Эти проекты могут не использовать по умолчанию точно, поэтому в таких случаях у вас есть два варианта:

Добавьте // flowlint ambiguous-object-type:error ко всем типам экспортируемых объектов в этих файлах и передайте изменения.
Сделайте определения в виде потока и используйте там // flowlint ambiguous-object-type:error.

Оба варианта также упростят другим участникам сообщества обновление собственных кодовых баз.

Чтобы найти зависимости, в которых возникают эти проблемы, включите exact_by_default=true в разделе options вашего flowconfig. Если у вас нет ошибок, значит, вы уже готовы к работе. В противном случае просмотрите сообщения, чтобы увидеть, какие пакеты указаны в node_modules справочнике по ошибкам.

После того, как вы исправите все эти ошибки, ваша кодовая база будет официально точной по умолчанию!

Заключение

Удачи с кодмодами! Когда вы закончите, вам будет легче выразить свое намерение в Flow, не попадая в случайные ловушки. Если у вас есть какие-либо вопросы, задавайте их в этом посте, чтобы другие люди, у которых возникли похожие проблемы, могли увидеть, как вы их решаете.

Как перейти на синтаксис типа объекта с точным по умолчанию