enum-plus
Version:
A drop-in replacement for native enum. Like native enum but much better!
151 lines (119 loc) • 10.1 kB
Markdown
<!-- markdownlint-disable MD001 MD009 MD033 MD041 -->
[English](./README.md) | [中文](./README.zh-CN.md) | [CHANGELOG](./CHANGELOG.md)
<p align="center">
<a href="https://github.com/shijistar/enum-plus" target="blank">
<img src="https://cdn.jsdelivr.net/gh/shijistar/enum-plus@v3.2.1/public/enum-plus.svg" width="240" alt="enum-plus" />
</a>
</p>
<p align="center">
<strong>Like native enum, but much better!</strong>
</p>
<p align="center">
<strong>A solution for business dictionary management.</strong>
</p>
<br/>
[](https://www.npmjs.com/package/enum-plus)
[](https://www.npmjs.com/package/enum-plus?activeTab=code)
[](https://www.npmjs.com/package/enum-plus)
[](https://deepwiki.com/shijistar/enum-plus)
[](https://app.codecov.io/gh/shijistar/enum-plus)
**Supported Platforms**
[](https://www.npmjs.com/package/enum-plus)
[](https://github.com/shijistar/enum-plus)
[](https://reactnative.dev)
[](https://developers.weixin.qq.com/miniprogram/en/dev/framework)
[](https://docs.taro.zone/en/docs)
[Introduction](https://shijistar.github.io/enum-plus/?path=/docs/introduce--docs) • [Get Started](https://shijistar.github.io/enum-plus/?path=/docs/get-started--docs) • [API Reference](https://shijistar.github.io/enum-plus/?path=/docs/api-reference--docs) • [Global Configuration](https://shijistar.github.io/enum-plus/?path=/docs/global-configuration--docs) • [User Stories](https://shijistar.github.io/enum-plus/?path=/docs/user-stories--docs) • [Plugin System](https://shijistar.github.io/enum-plus/?path=/docs/plugin-system--docs) • [Localization](https://shijistar.github.io/enum-plus/?path=/docs/localization--docs) • [Extensibility](https://shijistar.github.io/enum-plus/?path=/docs/extensibility--docs) • [Best Practices](https://shijistar.github.io/enum-plus/?path=/docs/best-practices--docs) • [Compatibility](https://shijistar.github.io/enum-plus/?path=/docs/compatibility--docs) • [FAQ](https://shijistar.github.io/enum-plus/?path=/docs/faq--docs) • [Full API Reference](./README-FULL.md)
## 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.
`enum-plus` keeps the direct enum-style experience, then adds those runtime capabilities in one place.
It's a front-end business dictionary solution, that provides a lightweight data source. It's part of the front-end infrastructure.
<p align="center">
<a href="https://cdn.jsdelivr.net/gh/shijistar/enum-plus@v3.2.1/public/usage-screenshot-high-v3.mp4" target="_blank">
<img src="https://cdn.jsdelivr.net/gh/shijistar/enum-plus@v3.2.1/public/usage-screenshot-v3.gif" width="500" alt="usage video" />
</a>
</p>
<p align="center">
<sup><em>↑ Click image for HD video ↑</em></sup>
</p>
> 💡 Want to see what enum-plus can do and how it improves productivity? [Open the Full Demo](https://shijistar.github.io/enum-plus/?path=/story/demo-full-demo--playground)
## 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<sup>_ TypeScript_</sup>
- Generates dropdowns from enums, compatible with UI libraries like [Ant Design](https://ant.design/components/overview), [Element Plus](https://element-plus.org/en-US/component/overview), [Material-UI](https://mui.com/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
```bash
npm install enum-plus
```
## Quick example
```ts
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.Review; // 2
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.named.Draft; // { key: 'Draft', value: 1, label: 'Draft', color: 'default' }
StatusEnum.item(1); // { 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
```ts
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](./packages/plugin-react/README.md)
- [@enum-plus/plugin-react-i18next](./packages/plugin-react-i18next/README.md)
- [@enum-plus/plugin-i18next](./packages/plugin-i18next/README.md)
- [@enum-plus/plugin-i18next-vue](./packages/plugin-i18next-vue/README.md)
- [@enum-plus/plugin-vue-i18n](./packages/plugin-vue-i18n/README.md)
- [@enum-plus/plugin-next-international](./packages/plugin-next-international/README.md)
- [@enum-plus/plugin-antd](./packages/plugin-antd/README.md)
## Support
If this project helps you, please consider giving it a [Star ⭐️](https://github.com/shijistar/enum-plus) on GitHub. This will encourage us to continue developing and maintaining this project.