Файлы объявлений

Что такое файл объявления?

Давайте рассмотрим более общий, а иногда и более удобный способ объявления типов для модулей: файлы объявления.

Существует два возможных случая использования, в зависимости от того, существует ли файл реализации или нет.

В первом случае экспортируемые типы модуля объявляются в файле объявления <FILENAME>.flow, который находится в той же директории, что и соответствующий файл реализации <FILENAME>. Файл объявления полностью затеневает сопутствующую реализацию. Другими словами, Flow полностью проигнорирует <FILENAME> и просто прочитает <FILENAME>.flow вместо этого.

Во втором случае файл реализации отсутствует полностью. Файл объявления <FILENAME>.flow обрабатывается так, как будто его имя <FILENAME>.

Обратите внимание, что расширение .flow применяется как к файлам .js, так и к файлам .json. Соответствующие файлы объявления имеют расширения .js.flow и .json.flow, соответственно.

Теперь давайте рассмотрим пример первого случая, описанного выше. Предположим, что у нас есть следующий код в файле src/LookBeforeYouLeap.js:

// @flow
import { isLeapYear } from "./Misc";
if (isLeapYear("2020")) console.log("Yay!");

и предположим, что src/Misc.js имеет несовместимую реализацию isLeapYear:

// @flow
export function isLeapYear(year: number): boolean {
  return year % 4 == 0; // yeah, this is approximate
}

Если теперь мы создадим файл объявления src/Misc.js.flow, объявления в нем будут использоваться вместо кода в src/Misc.js. Допустим, у нас есть следующие объявления в src/Misc.js.flow.

ПРИМЕЧАНИЕ: Синтаксис объявлений в файле объявления такой же, как и в разделе «Создание определений библиотек» на странице создания определений библиотек.

// @flow
declare export function isLeapYear(year: string): boolean;

Что, по вашему мнению, произойдет?

Правильно, вызов isLeapYear в src/LookBeforeYouLeap.js пройдет проверку типов, так как параметр year ожидает тип string в файле объявления.

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

Встраивание объявлений в обычный код

Иногда полезно встраивать объявления как часть исходного кода файла реализации.

В следующем примере, скажем, вы хотите завершить написание функции fooList без необходимости предварительно смоделировать ее зависимости: функцию foo, которая принимает number и возвращает string, и класс List, у которого есть метод map. Вы можете сделать это, включив объявления для List и foo:

declare class List<T> {
  map<U>(f: (x: T) => U): List<U>;
}
declare function foo(n: number): string;

function fooList(ns: List<number>): List<string> {
  return ns.map(foo);
}

Просто не забудьте заменить объявления соответствующими реализациями.