shijistar/enum-plus: A drop-in replacement for native enum. Like native enum, but much better!

English | 中文 | CHANGELOG

A solution for business dictionary management

Like native enum, but much better!

!GitHub License

Supported Platforms

Introduction • Get Started • API Reference • Global Configuration • User Stories • Plugin System • Localization • Extensibility • Best Practices • Compatibility • FAQ • Full API Reference

Why enum-plus

Native enums are great for constants, but product code usually needs more at runtime:

• human-readable label,
• metadata such as color, icon, or permission
• dropdowns, checkboxes, and menus,
• table filters,
• render a label in a table,
• render a badge color,
• localization,
• metadata lookups,
• validation and lookup helpers.

It's a front-end business dictionary solution, that provides a lightweight data source. It's part of the front-end infrastructure.

💡 Want to see what enum-plus can do and how it improves productivity? See Full Demo

Features

• Compatible with the usage of native enums
• Supports multiple data types such as number and string
• Enhanced enum items with display names
• Internationalization support for display names, can be integrated with any i18n library
• Converts values directly into display names, simplifying data display in the UI
• Extensible design, allowing custom metadata fields for enum items
• Plugin system design, extending enum functionality through plugin installations
• Supports type narrowing to enhance type safety^{_  TypeScript_}
• Generates dropdowns from enums, compatible with UI libraries like Ant Design, Element Plus, Material-UI
• Compatible with various environments including Browsers, Node.js, React Native, Taro, and mini-programs
• Supports server-side rendering (SSR)
• Compatible with any front-end development framework, including vanilla projects
• TypeScript‑oriented, providing excellent type inference and code completion capabilities
• Zero dependencies
• Lightweight (min+gzip 2KB+ only)

Installation

npm install enum-plus

Quick example

import { Enum } from 'enum-plus';
const StatusEnum = Enum({
  Draft: { value: 1, label: 'Draft', color: 'default' },
  Review: { value: 2, label: 'In Review', color: 'processing' },
  Published: { value: 3, label: 'Published', color: 'success' },
});
StatusEnum.Draft; // 1
StatusEnum.Review; // 2
StatusEnum.Published; // 3
StatusEnum.label(2); // 'In Review'
StatusEnum.has(2); // true
StatusEnum.keys; // ['Draft', 'Review', 'Published']
StatusEnum.values; // [1, 2, 3]
StatusEnum.labels; // ['Draft', 'In Review', 'Published']
StatusEnum.items; // [{ key: 'Draft', value: 1, label: 'Draft', color: 'default' }, ...]
StatusEnum.item(1); // { key: 'Draft', value: 1, label: 'Draft', color: 'default' }
StatusEnum.named.Draft; // { key: 'Draft', value: 1, label: 'Draft', color: 'default' }
StatusEnum.meta; // { color: [ 'default', 'processing', 'success' ] }
StatusEnum.findBy('color', 'success'); // { key: 'Published', value: 3, label: 'Published', color: 'success' }
StatusEnum.toList({ valueField: 'id', labelField: 'name' }); // [{ id: 1, name: 'Draft' }, ...]
StatusEnum.toMap({ keySelector: 'key', valueSelector: 'value' }); // { Draft: 1, Review: 2, Published: 3 }

i18n

import i18nPlugin from '@enum-plus/plugin-i18next';
import { Enum } from 'enum-plus';
Enum.install(i18nPlugin);
const StatusEnum = Enum({
  Draft: { value: 1, label: 'locales.enums.statusEnum.draft' },
  Review: { value: 2, label: 'locales.enums.statusEnum.review' },
  Published: { value: 3, label: 'locales.enums.statusEnum.published' },
});
StatusEnum.labels; // ['Draft', 'In Review', 'Published'] or ['草稿', '审核中', '已发布']
StatusEnum.label(2); // 'In Review' or '审核中'
StatusEnum.named.Review.label; // 'In Review' or '审核中'

Ecosystem

• @enum-plus/plugin-react
• @enum-plus/plugin-react-i18next
• @enum-plus/plugin-i18next
• @enum-plus/plugin-i18next-vue
• @enum-plus/plugin-vue-i18n
• @enum-plus/plugin-next-international
• @enum-plus/plugin-antd

Support

If this project helps you, please consider giving it a Star ⭐️ on GitHub. This will encourage us to continue developing and maintaining this project.