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

Для удобства далее буду называть enum по-русски — энумы.

Для чего используется enum

Энумы (“перечисление”, сокращение от enumerable) — это тип данных в TypeScript, который представляет собой набор фиксированных, именованных констант.

Он используется для создания ограниченного списка значений (например, дней недели, статусов заказа или ролей пользователей) вместо использования случайных чисел или строк.

Часто энумы используются при описании типов данных, приходящих с бэкенда.

Например:

export const enum OrganizationType {
  FACTORY = 'FACTORY',
  OFFICE = 'OFFICE',
}

Распространенной практикой является писать ключи и значения энумов в SCREAMING_SNAKE_CASE, так как они являются литеральными константами.

Энумы можно объявить через enum и const enum. Второй вариант часто является предпочтительным, так как обычный энум компилируется в JavaScript-объект, а const enum полностью удаляется при компиляции, подставляя значения напрямую в код. const enum имеет смысл использовать, если не планируется обращение к ключу через значение (в описываемом сценарии это обычно это не нужно).

Использование энумов для выпадающих списков

Частый пример использования энумов – для создания выпадающих списков, когда значения берутся из слоя API.

Для отображения выпадающего списка требуется массив объектов с полями value и label (они могут называться чуть по-другому в зависимости от проекта или используемой библиотеки). value — это значение энума, label — текст, который будет отображаться в выпадающем списке.

const organizationTypeOptions: DropdownOption[] = [
  { value: OrganizationType.FACTORY, label: 'Фабрика' },
  { value: OrganizationType.OFFICE, label: 'Офис' },
] as const;

Далее этот массив передается в компонент, монтирующий выпадающий список.

Проблемы использования энумов для выпадающих списков

Когда я разрабатывал свой текущий проект, часто писал код, показанный выше.

Энумы объявлялись в слое, описывающем API бэкенда, затем импортировались в компоненты приложения. В компонентах объявлялись объекты, хранящие value и label для отображения списков.

Это работало, но с появлением большого количества списков стали заметны три проблемы.

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

Во-вторых, при изменении списка значений приходилось редактировать минимум два файла: файл с энумом и файл с маппингом (хорошо еще, если последний нигде не дублировался).

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

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

Как решить эти недостатки конфигом-константой

В результате рефакторинга у меня получился объект-константа, перечисляющий все ключи и значения выпадающих списков. Выглядел он примерно так:

export const enumConfig = {
  Organization: {
    type: [
      { value: OrganizationType.FACTORY, label: 'Фабрика' },
      { value: OrganizationType.OFFICE, label: 'Офис' },
    ],
  },
  Person: {
    type: [
      { value: 'EMPLOYEE', label: 'Сотрудник' },
      { value: 'OUTSOURCER', label: 'Аутсорсер' },
    ],
    status: [
      { value: 'WORKING', label: 'Работает' },
      { value: 'DAY_OFF', label: 'Выходной' },
    ],
  },
} as const;

Отдельно подчеркну объявление объекта as const: это очень важно для иммутабельности и строгой типизации. С as const тип Person.type[0].value станет не просто string, а именно'EMPLOYEE'.

Рефакторинг в слое API бэкенда

Были отредактированы файлы типов в слое API бэкенда:

Было:

export const enum PersonType {
    EMPLOYEE = 'EMPLOYEE',
    OUTSOURCER = 'OUTSOURCER',
    GUEST = 'GUEST',
}

Стало:

export type PersonType = typeof enumConfig.Person.type[number]['value'];

Этот синтаксис создает тип TypeScript, автоматически извлекая все возможные значения из массива в объекте.

Модуль с методами для работы с объектом-константой

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

/**
 * Совместим с типом DropdownOption.
 */
type EnumConfigItem = { 
  value: string; 
  label: string; 
};

/**
 * Создает объект-маппинг, где ключи равны `value` элементов массива.
 *
 * @example
 * const statuses = [
 *   { value: 'ACTIVE', label: 'Активен' },
 *   { value: 'PENDING', label: 'Ожидает' },
 * ] as const;
 * const Status = getEnumMap(statuses);
 * // Результат: { ACTIVE: 'ACTIVE', PENDING: 'PENDING' }
 * // Тип Status.ACTIVE будет строго 'ACTIVE'
 */
export const getEnumMap = <T extends readonly EnumConfigItem[]>(items: T) => {
  return Object.fromEntries(items.map((item) => [item.value, item.value])) as {
    [K in T[number]['value']]: K;
  };
};

/**
 * Преобразует массив опций в объект-словарь, где ключом является `value`, а значением — весь исходный объект опции. Используется для указания дефолтной опции при инициализации выпадающего списка.
 *
 * @example Использование
 * const roleMap = getEnumDropdownOptions(enumConfig.User.Role);
 * // Результат:
 * // {
 * //   ADMIN: { value: 'ADMIN', label: 'Администратор' },
 * //   USER: { value: 'USER', label: 'Пользователь' },
 * // }
 * 
 * @example Применение для указания дефолтной опции в списке
 * export const userRoleDropdownOptions = getEnumDropdownOptions(enumConfig.User.Role);
 * export const defaultUserRole: EnumConfigItem = userRoleDropdownOptions.ADMIN;
 */
export const getEnumDropdownOptions = <T extends readonly EnumConfigItem[]>(items: T) => {
  return Object.fromEntries(items.map((item) => [item.value, item])) as {
    [K in T[number]['value']]: Extract<T[number], { value: K }>;
  };
};

/**
 * Находит и возвращает `label` элемента по его `value`.
 *
 * @example
 * const types = [{ value: 'OFFICE', label: 'Офис' }] as const;
 * const label = getEnumLabel({ items: types, value: 'OFFICE' }); // Возвращает: 'Офис'
 */
export const getEnumLabel = <
  TItems extends readonly EnumConfigItem[],
  TValue extends TItems[number]['value'],
>(
  params: GetEnumLabelParams<TItems, TValue>,
): string => {
  const { items, value, fallback } = params;
  const matchedItem = items.find((item) => item.value === value);

  if (matchedItem) return matchedItem.label;

  return fallback ?? value;
};

Использование объекта-константы для создания выпадающих списков в компонентах

Ниже пример кода, как можно использовать объект-константу для создания выпадающего списка и указания дефолтных значений.

const personStatusesEnum = getEnumValues(enumConfig.Person.status);
const personStatusDropdownOptions = getEnumDropdownOptions(enumConfig.Person.status);

export const personStatusOptionsList: DropdownOption[] = [...enumConfig.Person.status];

export const defaultPersonStatus: DropdownOption =
  personStatusDropdownOptions.WORKING;

export const defaultPerson = {
  status: personStatusesEnum.WORKING,
};

Проверка на дублирование ключей value

Перечисляемые значения в конфиге хранятся как массив объектов. В связи с этим возникает риск дублирования ключей value. Этого можно избежать при помощи магии TypeScript.

type EnumConfigItem = { readonly value: string; readonly label: string };

/** Проверяет уникальность `value` в кортеже опций; при дубликате возвращает строку-ошибку. */
type UniqueEnumValues<
  T extends readonly EnumConfigItem[],
  Seen extends string = never,
> = T extends readonly [infer Head, ...infer Rest]
  ? Head extends EnumConfigItem
    ? Head['value'] extends Seen
      ? `Duplicate enum value "${Head['value'] & string}"`
      : Rest extends readonly EnumConfigItem[]
        ? UniqueEnumValues<Rest, Seen | Head['value']>
        : true
    : true
  : true;

type ValidateEnumField<T> = T extends readonly EnumConfigItem[]
  ? UniqueEnumValues<T> extends true
    ? T
    : UniqueEnumValues<T>
  : T;

type ValidatedEnumConfig<T extends Record<string, Record<string, unknown>>> = {
  [Entity in keyof T]: {
    [Field in keyof T[Entity]]: ValidateEnumField<T[Entity][Field]>;
  };
};

const enumConfigSource = {
  Organization: {
    type: [
      { value: OrganizationType.FACTORY, label: 'Фабрика' },
      { value: OrganizationType.OFFICE, label: 'Офис' },
    ],
  },
  // прочие блоки перечисляемых значений
}

export const enumConfig: ValidatedEnumConfig<typeof enumConfigSource> = enumConfigSource;

При возникновении дублирующихся value в каком-либо массиве редакторы кода (например, VS Code или Cursor) подсветят ошибку на последней строчке этого кода, и в контекстном меню будет сообщение о дублирующемся поле.

Имеет ли смысл расширить этот подход на все энумы в приложении?

После рефакторинга выпадающих списков я стал смотреть на оставшиеся энумы и думать, имеет ли смысл их тоже упаковать в этот конфиг.

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

А вот энумы из слоя API бэкенда, даже если им в моменте не требуются лейблы, кажутся очень привлекательной целью для переноса в конфиг. Можно адаптировать показанный в статье код, сделав лейблы необязательными, а при запросе отсутствующего лейбла подставлять значение value как фоллбэк.

Напоследок

С точки зрения архитектуры приложения, конфиг перечисляемых значений может относиться к слою API или к слою entities, если в проекте используется FSD (Feature-Sliced Design). Хотя справочник объединяет в себе модель и человекочитаемые значения, он не нарушает принципа разделения модели и представления, пока сам не начинает знать о конкретных компонентах.

Если в проекте нужна интернационализация, имеет смысл хранить в полях label не отдельные строки, а labelKey, а логику интернационализации размещать в отдельные модули.

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