Файлы деклараций

Файл деклараций — это файл .flow (например, Misc.js.flow), в котором объявляются типы модуля отдельно от его реализации .js. Когда файл .flow находится рядом с файлом реализации с таким же именем, Flow игнорирует файл реализации и вместо него считывает файл деклараций. Используйте файл деклараций, чтобы добавить типы в модуль, который вы не можете или не хотите аннотировать напрямую, — например, в сгенерированный код, код, который должен оставаться обычным JavaScript, или модуль, типы которого вы хотите переопределить.

Что такое файл деклараций?​

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

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

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

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

Файлы деклараций могут перекрывать как файлы реализации .js, так и файлы реализации .json; соответствующие расширения файлов деклараций — .js.flow и .json.flow.

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

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

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

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 находятся следующие объявления.

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

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);
}

Только не забудьте заменить объявления полноценными реализациями.

Создание файлов деклараций​

Сам исполняемый файл flow не создаёт файлы деклараций. Отдельный npm-пакет flow-api-translator решает эту задачу: получив исходный файл Flow, он создаёт файл деклараций .js.flow или файл TypeScript .d.ts. Это наиболее близкий аналог режимов tsc --declaration и --emitDeclarationOnly в TypeScript.

См. также​

• Определения библиотек — объявление типов для сторонних npm-пакетов
• Типы модулей — импорт и экспорт типов между модулями
• .flowconfig [declarations] — настройка режима деклараций для стороннего кода