You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`enum-plus` is an enhanced enum library that is fully compatible with the native `enum` and extends it with powerful features such as display text, localization, UI control binding, enum items traversal, and more useful extension methods. This lightweight, zero-dependency, TypeScript library works with any front-end framework.
26
+
`enum-plus` is an enhanced enum library that is fully compatible with the native `enum` and extends it with powerful features such as display text, localization, UI control binding, enum members traversal, and more useful extension methods. This lightweight, zero-dependency, TypeScript library works with any front-end framework.
26
27
27
-
With the extended display text capability, enum items can be used to generate dropdowns, checkboxes, and other UI controls with a single line of code. By using the extension methods of the enum, you can easily traverse the array of enum items, get the display text of a certain enum value, determine whether a value exists, etc. The display text of the enum item supports localization, which can return the corresponding text according to the current language environment, making the display text of the enum item more flexible and more in line with user needs.
28
+
With the extended display text capability, enum members can be used to generate dropdowns, checkboxes, and other UI controls with a single line of code. By using the extension methods of the enum, you can easily traverse the array of enum members, get the display text of a certain enum value, determine whether a value exists, etc. The display text of the enum member supports localization, which can return the corresponding text according to the current language environment, making the display text of the enum member more flexible and more in line with user needs.
28
29
29
30
What other exciting features are there? Please continue to explore! Or you can check out this usage video first.
30
31
@@ -36,10 +37,10 @@ What other exciting features are there? Please continue to explore! Or you can c
36
37
37
38
- Full compatibility with native `enum` behavior
38
39
- Support for multiple data types including `number` and `string`
39
-
- Enhanced enum items with customizable display text
40
+
- Enhanced enum members with customizable display text
40
41
- Built-in localization capabilities that integrate with any i18n library
41
42
- Streamlined conversion from enum values to human-readable display text
42
-
- Extensible design allowing unlimited custom fields on enum items
43
+
- Extensible design allowing unlimited custom fields on enum members
43
44
- Seamless integration with any UI libraries like [Ant Design](https://ant.design/components/overview), [ElementPlus](https://element-plus.org/en-US/component/overview.html), [Material-UI](https://mui.com/material-ui), in a single line of code
44
45
- Complete Node.js compatibility with SSR support
45
46
- Zero dependencies - pure JavaScript implementation usable in any front-end framework
@@ -110,7 +111,7 @@ Week.Monday; // 'Mon'
110
111
111
112
### 3. Standard Format (Recommended)
112
113
113
-
The standard format includes both a `value` and a `label`for each enumitem. This is the most commonly used format and is recommended for most cases. This format allows you to specify a display text for each enumitem, which can be used inUI components.
114
+
The standard format includes both a `value` and a `label`for each enummember. This is the most commonly used format and is recommended for most cases. This format allows you to specify a display text for each enummember, which can be used inUI components.
114
115
115
116
```js
116
117
import { Enum } from 'enum-plus';
@@ -197,23 +198,23 @@ Week.Monday; // 1
197
198
198
199
`{ value, label, key, raw }[]`
199
200
200
-
Returns a read-only array of all enum items. The array structure conforms to [Ant Design](https://ant.design/components/select#usage-upgrade) component specifications, which makes it possible to generate dropdown menus, checkboxes, and other UI controls with just one line of code. For more details, please refer to the usage examples below.
201
+
Returns a read-only array of all enum members. The array structure conforms to [Ant Design](https://ant.design/components/select#usage-upgrade) component specifications, which makes it possible to generate dropdown menus, checkboxes, and other UI controls with just one line of code. For more details, please refer to the usage examples below.
201
202
202
203
---
203
204
204
205
### 💎 keys
205
206
206
207
`string[]`
207
208
208
-
Returns a read-only array of all enum item `key`(s)
209
+
Returns a read-only array of all enum member `key`(s)
`toSelect` is similar to `items`, both return an array of all enum items. The difference is that the elements returned by `toSelect` only contain the `label` and `value` fields, no other extra fields. At the same time, the `toSelect` method allows inserting a default element at the beginning of the array, which is generally used for the default option (which means _all_, _none_, or _unlimited_, etc) of select control. Of course, you can customize this default option.
258
+
`toSelect` is similar to `items`, both return an array of all enum members. The difference is that the elements returned by `toSelect` only contain the `label` and `value` fields, no other extra fields. At the same time, the `toSelect` method allows inserting a default element at the beginning of the array, which is generally used for the default option (which means _all_, _none_, or _unlimited_, etc) of select control. Of course, you can customize this default option.
Returns an array of all enum items that conforms to [Ant Design](https://ant.design/components/menu) specifications. It's used to generate the `Menu`, `Dropdown` controls, in a single line of code.
266
+
Returns an array of all enum members that conforms to [Ant Design](https://ant.design/components/menu) specifications. It's used to generate the `Menu`, `Dropdown` controls, in a single line of code.
266
267
267
268
```js
268
269
import { Menu } from 'antd';
@@ -285,7 +286,7 @@ The data format is:
285
286
286
287
<sup>**_\[Function]_**</sup> `toFilter(): { text, value }[]`
287
288
288
-
Returns an array ofenumitems that can pass directly to the [Ant Design](https://ant.design/components/table#table-demo-head) Table component as `filters` property of a column. This is used to add a dropdown filter box in the table header to filter table data.
289
+
Returns an array ofenummembers that can pass directly to the [Ant Design](https://ant.design/components/table#table-demo-head) Table component as `filters` property of a column. This is used to add a dropdown filter box in the table header to filter table data.
289
290
290
291
The data format is:
291
292
@@ -323,9 +324,9 @@ The data format is:
323
324
324
325
The `raw` method is used to return the original initialization object of the enum collection, which is the object used to create the enum.
325
326
326
-
The second overload method is used to return the original initialization object of a single enumitem.
327
+
The second overload method is used to return the original initialization object of a single enummember.
327
328
328
-
The main purpose of the `raw` method is to get the extended custom fields of the enumitems. Unlimited number of custom fields are allowed.
329
+
The main purpose of the `raw` method is to get the extended custom fields of the enummembers. Unlimited number of custom fields are allowed.
329
330
330
331
```js
331
332
const Week = Enum({
@@ -403,7 +404,7 @@ Week.Monday; // 1
403
404
404
405
---
405
406
406
-
#### Supports JSDoc comments on enumitems
407
+
#### Supports JSDoc comments on enummembers
407
408
408
409
Supports inline documentation through JSDoc, allowing developers to view detailed comments by simply hovering over enum values in the editor.
409
410
@@ -424,7 +425,7 @@ You can see that this hover functionality reveals both documentation and enum va
When working with enums, a common edge case occurs when an enum item's key conflicts with built-in method names. While we typically access enum values through `Week.XXX` notation, complications arise when these keys overlap with enum methods.
720
+
When working with enums, a common edge case occurs when an enum member's key conflicts with built-in method names. While we typically access enum values through `Week.XXX` notation, complications arise when these keys overlap with enum methods.
720
721
721
-
The enum library provides several utility methods like `label`, `key`, and `toSelect`. When an enum item shares a name with these methods, the enum item takes precedence, effectively overriding the utility method. However, this doesn't mean you lose access to those methods - they remain available through the `items` collection, ensuring all functionality is preserved regardless of naming conflicts. Please refer to the code example below:
722
+
The enum library provides several utility methods like `label`, `key`, and `toSelect`. When an enum member shares a name with these methods, the enum member takes precedence, effectively overriding the utility method. However, this doesn't mean you lose access to those methods - they remain available through the `items` collection, ensuring all functionality is preserved regardless of naming conflicts. Please refer to the code example below:
722
723
723
724
```js
724
725
const Week = Enum({
@@ -728,14 +729,14 @@ const Week = Enum({
728
729
label: { value:4 }, // Naming conflict
729
730
} as const);
730
731
731
-
Week.keys; // 3, enum item has higher priority and will override the method
732
-
Week.label; // 4, enum item has higher priority and will override the method
732
+
Week.keys; // 3, enum member has higher priority and will override the method
733
+
Week.label; // 4, enum member has higher priority and will override the method
733
734
// You can still access these methods through Enum.items 🙂
For an even more extreme edge case where the items property itself conflicts with an enum item name, a solution is still available. In such scenarios, you can access the items array through a Symbol-based alias field that guarantees access regardless of naming conflicts. Consider the following example:
739
+
For an even more extreme edge case where the items property itself conflicts with an enum member name, a solution is still available. In such scenarios, you can access the items array through a Symbol-based alias field that guarantees access regardless of naming conflicts. Consider the following example:
739
740
740
741
```js
741
742
import { ITEMS } from'enum-plus';
@@ -746,7 +747,7 @@ const Week = Enum({
746
747
items: { value:3 }, // Naming conflict
747
748
} as const);
748
749
749
-
Week.items; // 3, enum item has higher priority and will override items
750
+
Week.items; // 3, enum member has higher priority and will override items
750
751
Week[ITEMS]; // ITEMS is an alias Symbol
751
752
// [
752
753
// { value: 1, key: 'foo', label: 'foo' },
@@ -758,6 +759,17 @@ Week[ITEMS]; // ITEMS is an alias Symbol
758
759
759
760
---
760
761
762
+
## Naming Convention Best Practices
763
+
764
+
1. **Enum Type Naming:** Use `PascalCase` and append with the `Enum` suffix (e.g., _WeekEnum_, _ColorEnum_).
765
+
2. **Enum Member Naming:** Use `PascalCase` for enum members(e.g., _WeekEnum.Sunday_, _ColorEnum.Red_). This naming style highlights the immutability and static nature of enum members, and ensures they appear at the top in IDE IntelliSense suggestions for easier selection.
766
+
3. **Semantic Clarity:** Ensure enum and member names have clear semantics. Good semantic naming serves as self-documentation, making code intent explicit and reducing cognitive overhead.
767
+
4. **Single Responsibility Principle:** Each enum type should represent a single, cohesive set of related constants. Avoiding overlapping responsibilities between different enum types.
768
+
5. **Provide JSDoc Comments:** Provide JSDoc comments for each enum member and the enum type itself, explaining their purpose and usage. Comprehensive documentation enables IDE hover tooltips and improves code readability and maintainability.
769
+
6. **Internationalization Architecture:** Plan for internationalization from the outset by leveraging the library’s built-in [localization](#localization) features. A well-designed internationalization architecture minimizes future refactoring and facilitates global scalability.
770
+
771
+
---
772
+
761
773
## Localization
762
774
763
775
While `enum-plus` doesn't include built-in internationalization capabilities, it offers flexible localization through the optional `localize` parameter. This allows you to implement a custom localization function that transforms enum `label` values into appropriate translated text based on the current language context. The language state management remains your responsibility, with your `localize` method determining which localized text to return. For production applications, we strongly recommend leveraging established internationalization libraries such as `i18next` rather than creating custom solutions.
@@ -870,8 +882,8 @@ Please note that you are not required to import types such as `EnumItemInit` and
870
882
`EnumExtension` is a generic interface that accepts three type parameters, which are:
871
883
872
884
- `T`: Initialization object of the enum type (e.g., the object passed to `Enum()`)
873
-
- `K`: Key of the enum item (e.g., Sunday, Monday)
874
-
- `V`: Value of the enum items
885
+
- `K`: Key of the enum member (e.g., Sunday, Monday)
886
+
- `V`: Value of the enum members
875
887
876
888
If you want to provide more friendly type hints in the extension methods, you may need to use these type parameters. However these are all optional, if you don't need them, you can omit them.
0 commit comments