Перечисления в TypeScript: использование и лучшие практики

// Опасный подход
if (user.role === "ADMIN") {
  // Логика для администратора
}

enum UserRole {
  Admin = "ADMIN",
  Editor = "EDITOR",
  Viewer = "VIEWER"
}
 
if (user.role === UserRole.Admin) {
  // Безопасная логика для администратора
}

// Обычный объект
const Roles = {
  Admin: "ADMIN",
  User: "USER"
};
 
// С объектом TS не помешает сделать ошибку
let role = Roles.Admin;
role = "SUPERADMIN"; // Никакой ошибки!
 
// Enum
enum UserRole {
  Admin = "ADMIN",
  User = "USER"
}
 
let role2: UserRole = UserRole.Admin;
role2 = "SUPERADMIN"; // Ошибка типа!

enum Direction {
  Up,
  Down,
  Left,
  Right
}

enum Direction {
  Up,    // 0
  Down,  // 1
  Left,  // 2
  Right  // 3
}
 
console.log(Direction.Up);    // 0
console.log(Direction.Right); // 3

enum Status {
  Success = 1,
  Failure,     // 2
  Pending      // 3
}

enum Status {
  Success = 1,
  Failure = 2  
}
 
console.log(Status.Success); // 1
console.log(Status[1]);      // "Success"

enum Message {
  Success = "ОПЕРАЦИЯ_ВЫПОЛНЕНА",
  Failure = "ОШИБКА_ВЫПОЛНЕНИЯ",
  Pending = "ОБРАБОТКА"
}
 
console.log(Message.Success); // "ОПЕРАЦИЯ_ВЫПОЛНЕНА" 
console.log(Message["ОПЕРАЦИЯ_ВЫПОЛНЕНА"]); // undefined - обратного отображения нет!

enum Mixed {
  No = 0,
  Yes = "YES"
}

enum MathConstants {
  Pi = 3.14,
  Euler = Math.E,           // Вычисляемое значение
  Golden = (1 + Math.sqrt(5)) / 2  // Формула золотого сечения
}
 
enum Incremental {
  A = 1,
  B = A * 2,      // Используем предыдущее значение
  C = B * 2
}

const enum Direction {
  Up,
  Down,
  Left,
  Right
}
 
let move = Direction.Up;

enum Example {
  // Постоянные члены
  A = 1, 
  B = A * 2,
  
  // Вычисляемые члены  
  C = Math.random(),
  D = Date.now()
}

enum UserRole {
  Admin = "ADMIN",
  User = "USER",
  Guest = "GUEST"
}
 
function checkAccess(role: UserRole) {
  switch (role) {
    case UserRole.Admin:
      return { canCreate: true, canEdit: true, canDelete: true };
    case UserRole.User:
      return { canCreate: true, canEdit: true, canDelete: false };
    case UserRole.Guest:
      return { canCreate: false, canEdit: false, canDelete: false };
    default:
      // TypeScript поможет убедиться, что мы обработали все возможные роли
      const exhaustiveCheck: never = role;
      throw new Error(`Необработанная роль: ${exhaustiveCheck}`);
  }
}
 
// Использование
const permissions = checkAccess(UserRole.User);
console.log(permissions.canDelete); // false

enum ApiResponseStatus {
  Success = 200,
  BadRequest = 400,
  Unauthorized = 401,
  NotFound = 404,
  ServerError = 500
}
 
async function fetchData(url: string) {
  try {
    const response = await fetch(url);
    
    if (response.status === ApiResponseStatus.Success) {
      return await response.json();
    } else if (response.status === ApiResponseStatus.Unauthorized) {
      // Перенаправляем на страницу входа
      redirectToLogin();
    } else if (response.status === ApiResponseStatus.ServerError) {
      // Показываем сообщение об ошибке сервера
      showServerErrorNotification();
    }
    // ... другие обработчики
  } catch (error) {
    console.error("Network error:", error);
  }
}

enum OrderStatus {
  Created = "CREATED",
  PaymentPending = "PAYMENT_PENDING",
  Paid = "PAID",
  Processing = "PROCESSING",
  Shipped = "SHIPPED",
  Delivered = "DELIVERED",
  Cancelled = "CANCELLED"
}
 
class Order {
  private status: OrderStatus = OrderStatus.Created;
  
  public pay(): void {
    if (this.status === OrderStatus.Created || this.status === OrderStatus.PaymentPending) {
      this.status = OrderStatus.Paid;
      this.notifyUser("Оплата получена");
    } else {
      throw new Error("Невозможно оплатить заказ в текущем статусе");
    }
  }
  
  public ship(): void {
    if (this.status === OrderStatus.Paid || this.status === OrderStatus.Processing) {
      this.status = OrderStatus.Shipped;
      this.notifyUser("Заказ отправлен");
    } else {
      throw new Error("Невозможно отправить заказ в текущем статусе");
    }
  }
  
  // Другие методы управления жизненным циклом
  
  private notifyUser(message: string): void {
    console.log(`Уведомление пользователя: ${message}`);
  }
}

enum ThemeMode {
  Light = "light",
  Dark = "dark",
  System = "system"
}
 
enum NotificationType {
  Email = "email",
  Push = "push",
  SMS = "sms",
  None = "none"
}
 
class UserPreferences {
  constructor(
    public theme: ThemeMode = ThemeMode.System,
    public notificationMethod: NotificationType = NotificationType.Push
  ) {}
  
  applyTheme(): void {
    switch (this.theme) {
      case ThemeMode.Light:
        document.body.classList.add('light-theme');
        document.body.classList.remove('dark-theme');
        break;
      case ThemeMode.Dark:
        document.body.classList.add('dark-theme');
        document.body.classList.remove('light-theme');
        break;
      case ThemeMode.System:
        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
        document.body.classList.add(prefersDark ? 'dark-theme' : 'light-theme');
        document.body.classList.remove(prefersDark ? 'light-theme' : 'dark-theme');
        break;
    }
  }
}
 
// Использование
const userPrefs = new UserPreferences(ThemeMode.Dark, NotificationType.Email);
userPrefs.applyTheme();

// Вместо enum можно использовать union тип  
type Direction = "up" | "down" | "left" | "right";
 
function move(direction: Direction) {
  switch (direction) {
    case "up": return { x: 0, y: -1 };
    case "down": return { x: 0, y: 1 };
    case "left": return { x: -1, y: 0 };
    case "right": return { x: 1, y: 0 };
  }
}
 
// Использование
const vector = move("up");

const Directions = {
  Up: "UP",
  Down: "DOWN", 
  Left: "LEFT",
  Right: "RIGHT"
} as const;
 
type Direction = typeof Directions[keyof typeof Directions];
 
function move(direction: Direction) {
  // ...
}
 
move(Directions.Up); // Работает
move("UP"); // Тоже работает
move("SIDEWAYS"); // Ошибка компиляции

enum LoadingState {
  Initial = "INITIAL",
  Loading = "LOADING",
  Success = "SUCCESS",
  Error = "ERROR"
}
 
const DataFetcher: React.FC = () => {
  const [state, setState] = useState<LoadingState>(LoadingState.Initial);
  const [data, setData] = useState<any>(null);
  const [error, setError] = useState<string | null>(null);
  
  useEffect(() => {
    const fetchData = async () => {
      setState(LoadingState.Loading);
      try {
        const response = await fetch('https://api.example.com/data');
        if (!response.ok) throw new Error('Network response was not ok');
        const result = await response.json();
        setData(result);
        setState(LoadingState.Success);
      } catch (err) {
        setError(err.message);
        setState(LoadingState.Error);
      }
    };
    
    fetchData();
  }, []);
  
  // Рендеринг на основе состояния
  if (state === LoadingState.Initial || state === LoadingState.Loading) {
    return <div>Загрузка...</div>;
  }
  
  if (state === LoadingState.Error) {
    return <div>Ошибка: {error}</div>;
  }
  
  return <div>Данные загружены: {JSON.stringify(data)}</div>;
};

// TypeScript
enum Direction {
  Up,
  Down,
  Left,
  Right
}

enum UserRole {
  Admin = 1,
  User = 2,
  Guest = 3
}
 
console.log(UserRole[1]); // Выведет "Admin"

enum Direction {
  Up,
  Down
}
 
// TypeScript это пропустит без ошибок!
let dir: Direction = 10;

enum Status {
  Active = "ACTIVE",
  Suspended = "SUSPENDED"
}
 
const user = {
  name: "John",
  status: Status.Active
};
 
// Сериализация - работает нормально
const serialized = JSON.stringify(user);
console.log(serialized); // {"name":"John","status":"ACTIVE"}
 
// Десериализация - теряем связь с enum
const deserialized = JSON.parse(serialized);
console.log(deserialized.status === Status.Active); // true, но это просто строка
 
// А вот проверки не сработают
if (deserialized.status instanceof Status) { // ОШИБКА: Status - не конструктор
  // ...
}

function isValidStatus(status: string): status is Status {
  return Object.values(Status).includes(status as Status);
}
 
const deserialized = JSON.parse(serialized);
if (isValidStatus(deserialized.status)) {
  // Теперь TypeScript знает, что это валидное значение Status
  const validStatus: Status = deserialized.status;
}

// Разработчик A добавляет:
enum UserStatus {
  Active,
  Inactive,
  Pending
}
 
// Разработчик B в другой ветке добавляет:
enum UserStatus {
  Active,
  Inactive,
  Blocked
}

enum ActionType {
  Increment = "INCREMENT",
  Decrement = "DECREMENT"
}
 
// Хук useCallback может не работать как ожидается
const handleIncrement = useCallback(() => {
  dispatch({ type: ActionType.Increment });
}, [ActionType.Increment]); // ActionType.Increment - объект, а не примитив

// Менее эффективно (обращение к объекту)
if (status === UserStatus.Active) { ... }
 
// Более эффективно (сравнение примитивов)
if (status === "ACTIVE") { ... }

enum Features {
  Basic = "BASIC",
  Pro = "PRO",
  Enterprise = "ENTERPRISE"
}
 
// Если используется только одно значение
const userFeature = Features.Basic;

// Хороший подход
enum PaymentMethod {
  CreditCard = "CREDIT_CARD",
  PayPal = "PAYPAL",
  BankTransfer = "BANK_TRANSFER"
}
 
// Избегайте, если нет особых причин
enum PaymentMethod {
  CreditCard, // 0
  PayPal,     // 1
  BankTransfer // 2
}

// Обычное перечисление создает объект
enum Color {
  Red = "RED",
  Green = "GREEN",
  Blue = "BLUE"
}
 
// const enum подставляет значения напрямую
const enum OptimizedColor {
  Red = "RED",
  Green = "GREEN",
  Blue = "BLUE"
}
 
// В JavaScript превратится в:
// let normalColor = Color.Red;    // let normalColor = Color.Red;
// let fastColor = OptimizedColor.Red; // let fastColor = "RED";
let normalColor = Color.Red;
let fastColor = OptimizedColor.Red;

// Избегайте этого
enum Mixed {
  Zero = 0,
  One = 1,
  Yes = "YES",
  No = "NO"
}

// Лучше так
enum Numbers {
  Zero = 0,
  One = 1
}
 
enum Answers {
  Yes = "YES",
  No = "NO"
}

// Легкая альтернатива для простых случаев
type CardinalDirection = "north" | "south" | "east" | "west";
 
function move(direction: CardinalDirection) {
  // ...
}
 
move("north"); // OK
move("northwest"); // Ошибка компиляции

// Гибкая альтернатива с хорошей производительностью
const HttpStatus = {
  OK: 200,
  Created: 201,
  BadRequest: 400,
  NotFound: 404,
  ServerError: 500
} as const;
 
// Создаем тип из значений объекта
type HttpStatusCode = typeof HttpStatus[keyof typeof HttpStatus];
 
function handleResponse(status: HttpStatusCode) {
  if (status === HttpStatus.OK) {
    // ...
  }
}

enum TaskStatus {
  ToDo = "TODO",
  InProgress = "IN_PROGRESS",
  OnHold = "ON_HOLD",
  Done = "DONE"
}
 
function getNextStatus(current: TaskStatus): TaskStatus {
  switch (current) {
    case TaskStatus.ToDo:
      return TaskStatus.InProgress;
    case TaskStatus.InProgress:
      return TaskStatus.Done;
    case TaskStatus.OnHold:
      return TaskStatus.InProgress;
    case TaskStatus.Done:
      return TaskStatus.Done;
    default:
      // Если добавят новый статус и забудут обновить эту функцию,
      // TypeScript выдаст ошибку
      const exhaustiveCheck: never = current;
      throw new Error(`Необработанный статус: ${exhaustiveCheck}`);
  }
}

namespace AppConstants {
  export enum Theme {
    Light = "LIGHT",
    Dark = "DARK",
    System = "SYSTEM"
  }
  
  export enum Language {
    English = "en",
    Spanish = "es",
    French = "fr",
    German = "de"
  }
  
  export enum Currency {
    USD = "USD",
    EUR = "EUR",
    GBP = "GBP"
  }
}
 
// Использование
const userPrefs = {
  theme: AppConstants.Theme.Dark,
  language: AppConstants.Language.English
};

enum PermissionLevel {
  None = 0,
  Read = 1,
  Write = 2,
  Admin = 3
}
 
// Вспомогательные функции для проверки прав
function hasReadAccess(level: PermissionLevel): boolean {
  return level >= PermissionLevel.Read;
}
 
function hasWriteAccess(level: PermissionLevel): boolean {
  return level >= PermissionLevel.Write;
}
 
function isAdmin(level: PermissionLevel): boolean {
  return level === PermissionLevel.Admin;
}
 
// Использование
function editDocument(user: User, document: Document) {
  if (!hasWriteAccess(user.permissionLevel)) {
    throw new Error("У вас нет прав на редактирование");
  }
  
  // Логика редактирования...
}

/**
 * Статусы выполнения задачи в системе управления проектами.
 * 
 * @remarks
 * Статус BLOCKED не отображается в UI для обычных пользователей,
 * но используется для аналитики и системных операций.
 */
enum TaskStatus {
  /** Задача создана, но работа еще не началась */
  New = "NEW",
  
  /** Задача в процессе выполнения */
  InProgress = "IN_PROGRESS",
  
  /** Задача приостановлена из-за внешних зависимостей */
  Blocked = "BLOCKED",
  
  /** Работа над задачей завершена */
  Completed = "COMPLETED"
}

enum ProductCategory {
  Electronics = "ELECTRONICS",
  Clothing = "CLOTHING",
  Books = "BOOKS",
  HomeGoods = "HOME_GOODS"
}
 
// Проверка значения из API
function isValidCategory(category: string): category is ProductCategory {
  return Object.values(ProductCategory).includes(category as ProductCategory);
}
 
// Использование
async function fetchProducts(categoryFromUrl: string) {
  if (!isValidCategory(categoryFromUrl)) {
    throw new Error(`Недопустимая категория: ${categoryFromUrl}`);
  }
  
  const category: ProductCategory = categoryFromUrl; // Теперь TypeScript знает, что это валидная категория
  const response = await api.getProducts({ category });
  // ...
}

enum FilterOption {
  ShowAll = "SHOW_ALL",
  Active = "ACTIVE",
  Completed = "COMPLETED",
  Deleted = "DELETED"
}
 
// Создаем кнопки фильтрации для каждого варианта
function generateFilterButtons() {
  return Object.values(FilterOption).map(option => {
    const button = document.createElement('button');
    button.textContent = option;
    button.addEventListener('click', () => applyFilter(option));
    return button;
  });
}
 
function applyFilter(filter: FilterOption) {
  // Логика фильтрации...
}
 
// Получаем все кнопки
const filterButtons = generateFilterButtons();
// Добавляем их на страницу
filterButtons.forEach(button => document.getElementById('filters').appendChild(button));