enum-plus: A TypeScript Enhanced Enum Library for Frontend Development

Introduction

enum-plus is a lightweight, zero‑dependency TypeScript library that enhances native enums. It is fully compatible with the basic enum usage while adding features such as custom display text, UI binding, and localization, making it a direct replacement for native enums.

Key Features

Full compatibility with native enum syntax.

Supports number, string and other data types.

Customizable display text for each enum item.

Built‑in localization support.

Conversion of enum values to display text.

Extensible design allowing custom fields on enum items.

Binding to UI libraries (Ant Design, ElementPlus, Material‑UI, etc.) with one‑line code.

Node.js and SSR support.

Zero dependencies, works with any frontend framework.

100 % TypeScript implementation with full type inference.

Small bundle size (≈2 KB gzipped).

Installation

npm install enum-plus

Enum Definition Formats

1. Basic format (similar to native enum)

import { Enum } from 'enum-plus';
const Week = Enum({
  Sunday: 0,
  Monday: 1,
} as const);
Week.Monday; // 1

2. Standard format (recommended)

import { Enum } from 'enum-plus';
const Week = Enum({
  Sunday: { value: 0, label: '星期日' },
  Monday: { value: 1, label: '星期一' },
} as const);
Week.Sunday; // 0
Week.label(0); // 星期日

3. Array format (dynamic creation)

import { Enum } from 'enum-plus';
const petTypes = await getPetsData(); // [{ value: 1, key: 'dog', label: '狗' }, ...]
const PetTypes = Enum(petTypes);

4. Native enum conversion

enum init {
  Sunday = 0,
  Monday,
  Tuesday,
  // ...
}
const Week = Enum(init);
Week.Sunday; // 0
Week.label('Sunday'); // Sunday

API

Enum values : Week.Sunday , Week.Monday

items : read‑only array of all enum items, suitable for Ant Design data source.

keys : read‑only array of enum keys.

label(valueOrKey) : returns the display text, respects localization.

key(value) : returns the enum key or undefined .

has(valueOrKey) : checks existence.

toSelect() : returns array of { label, value } with optional default element.

toMenu() : returns array of { key, label } for Ant Design Menu or Dropdown .

toFilter() : returns array of { text, value } for table column filters.

toValueMap() : returns map object for Ant Design Pro form fields.

raw() : overloaded method to get the original init object or a single item’s raw data.

valueType / keyType (TypeScript only): union types of all enum values or keys for type‑safe declarations.

Localization

enum-plus does not embed i18n itself but accepts a localize function when creating an enum or via the global Enum.localize . This function translates the label field according to the current language, allowing integration with libraries such as i18next.

const sillyLocalize = (content) => {
  if (lang === 'zh-CN') {
    switch (content) {
      case 'week.sunday': return '星期日';
      case 'week.monday': return '星期一';
      default: return content;
    }
  } else {
    // en
    // ...
  }
};
const Week = Enum(
  { Sunday: { value: 0, label: 'week.sunday' }, Monday: { value: 1, label: 'week.monday' } },
  { localize: sillyLocalize }
);

Global Extension

Custom methods can be added to all enum instances via Enum.extends . Example methods toMySelect and reversedItems are shown.

Enum.extends({
  toMySelect(this) {
    return this.items.map(item => ({ value: item.value, title: item.label }));
  },
  reversedItems(this) {
    return this.items.reverse();
  },
});
Week.toMySelect(); // [{ value: 0, title: '星期日' }, ...]

Compatibility

enum-plus works in browser environments (with polyfills such as core‑js), modern bundlers (Webpack 5+, Vite, Rollup) targeting ES2020, and older bundlers falling back to ES2016. Node.js support requires at least ES2016 (Node 7.x+).

Conclusion

The library provides a comprehensive, type‑safe way to work with enums in frontend projects, offering UI binding, localization, and extensibility while remaining lightweight and framework‑agnostic.