Перечисления Flow

Перечисления Flow определяют фиксированный набор констант, которые образуют собственный тип.

В отличие от других возможностей Flow, перечисления Flow существуют как значения во время выполнения, а также как типы.

Для начала ознакомьтесь с разделом как включить перечисления Flow в проекте.

Преимущества​

Перечисления обладают рядом преимуществ по сравнению с существующими подходами:

• Меньше повторений: объявления перечислений задают и тип, и значение перечисления.
• Повышение производительности Flow: для перечислений гарантирована высокая производительность проверки типов, в отличие от объединений, проверка типов которых в некоторых ситуациях может быть затратной.
• Новые возможности: перечисления имеют cast метод, который безопасно преобразует примитивный тип в тип перечисления.
• Повышение безопасности: перечисления определяют собственный тип, который не приводит неявно другие типы к себе и сам не приводится к другим типам (например, к типам string), а также требуют исчерпывающей проверки в операторах switch. Эти свойства помогают предотвращать логические ошибки.

Краткое руководство​

Определение перечислений​

Перечисление с именем Status и тремя элементами: Active, Paused и Off.

enum Status {
  Active,
  Paused,
  Off,
}

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

enum Status {
  Active = 'active',
  Paused = 'paused',
  Off = 'off',
}

Можно использовать и числа:

enum Status {
  Active = 1,
  Paused = 2,
  Off = 3,
}

Значения должны быть уникальными литералами одного типа. Дополнительную информацию см. в полной документации по определению перечислений.

Использование перечислений​

Обращайтесь к элементам перечисления через точку, используйте имя перечисления в аннотации типа и преобразуйте перечисление в тип его представления и обратно:

enum Status {
  Active,
  Paused,
  Off,
}
declare const someString: string;


// Access an enum member with dot access:
Status.Active;


// Use the enum name as a type annotation:
const status: Status = Status.Active;


// Cast from the representation type (in this case, a `string`) to the enum type:
const maybeStatus: Status | void = Status.cast(someString);


// Provide a default value with the `??` operator:
const statusWithDefault: Status = Status.cast(someString) ?? Status.Off;


// Cast an enum type to its representation type (must be done explicitly):
status as string;

Подробнее о других методах перечислений, в том числе isValid, members и getName.

Проверки перечислений в операторах switch являются исчерпывающими — мы проверяем, что учтены все элементы:

enum Status {
  Active,
  Paused,
  Off,
}
const status: Status = Status.Active;


switch (status) { // Error: incomplete exhaustive check
  case Status.Active:  break;
  case Status.Paused: break;
  // We forgot to add `case: Status.Off:` here, resulting in the error.
  // Using `default:` would also work to check all remaining members.
}

Подробнее об исчерпывающей проверке перечислений.

Дополнительную информацию см. в полной документации по использованию перечислений.

Включение перечислений​

Чтобы включить перечисления Flow в проекте:

1. Начиная с Flow v0.317, они включены по умолчанию. В более ранних версиях добавьте enums=true в .flowconfig в разделе [options].
2. Добавьте Babel-трансформацию babel-plugin-transform-flow-enums в зависимости для разработки и конфигурацию Babel. Она преобразует объявления перечислений в вызовы среды выполнения.
3. Добавьте пакет среды выполнения flow-enums-runtime в производственные зависимости.

Также рекомендуем включить следующие правила ESLint, чтобы предотвратить распространённые проблемы с операторами switch:

• no-fallthrough: предотвращает случайный пропуск операторов break.
• no-case-declarations: предотвращает объявления с лексической областью видимости в ветках switch без блока.

Дополнительные правила ESLint для перечислений Flow доступны в eslint-plugin-fb-flow.

Когда использовать перечисления Flow​

Если раньше вы определяли объединённый тип из литералов, вместо него можно использовать перечисление. Например, вместо

type Status =
  | 'Active'
  | 'Paused'
  | 'Off';


const x: Status = 'Active';

или

const Status = Object.freeze({
  Active: 'Active',
  Paused: 'Paused',
  Off: 'Off',
});
type StatusType = keyof typeof Status;
const x: StatusType = Status.Active;

можно использовать:

enum Status {
  Active,
  Paused,
  Off,
}
const x: Status = Status.Active;

Подробнее о переносе устаревших шаблонов перечислений JavaScript на перечисления Flow см. в разделе переход с устаревших шаблонов.

Когда не следует использовать перечисления Flow​

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