A drop-in replacement library for enum, tiny and powerful, like native enum but much more than that
Like native
enum, but much better than that!
⬇️ Introduction | Features | Installation | Enum Definition | API | Usage | Localization | Global Extension ⬇️
enum-plus is an enhanced enum library that is fully compatible with the basic usage of native enum, while supporting extending display text, binding to UI components, and providing rich extension methods. It is a lightweight, zero-dependency, 100% TypeScript implementation tool that is suitable for a variety of front-end frameworks and supports localization.
After extending the display name of the enum item, it can be used to generate dropdowns, checkboxes, and other components 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.
What other exciting features are there? Please continue to explore the technical documentation below!
enum usagenumber and stringInstall using npm:
npm install enum-plus
Install using pnpm:
pnpm add enum-plus
Install using bun:
bun add enum-plus
Or using yarn:
yarn add enum-plus
Create an enum, enum values support both number and string types
import { Enum } from 'enum-plus';
const Week = Enum({
Sunday: 0,
Monday: 1,
} as const);
Week.Monday; // 1
import { Enum } from 'enum-plus';
const Week = Enum({
Sunday: 'Sun',
Monday: 'Mon',
} as const);
Week.Monday; // 'Mon'
import { Enum } from 'enum-plus';
const Week = Enum({
Sunday: { value: 0, label: 'Sunday' }, // this example does not consider localization
Monday: { value: 1, label: 'Monday' }, // this example does not consider localization
} as const);
Week.Monday; // 1
Week.label(1); // Monday (this is display text, not key)
import { Enum } from 'enum-plus';
const Week = Enum({
Sunday: { label: 'Sunday' }, // Equivalent to { value: "Sunday", label: 'Sunday' }
Monday: { label: 'Monday' }, // Equivalent to { value: "Monday", label: 'Monday' }
} as const);
Week.Monday; // 'Monday'
Week.label(/*key*/ 'Monday'); // Monday, output display text
Sometimes we need to create an enum dynamically using data returned by an api, in this case, we can use an array to initialize the enum
```js
import { Enum } from 'enum-plus';
const petTypes = await getPetsData();
// [ { id: 1, code: 'dog', name: 'Dog' },
// { id: 2, code: 'cat', name: 'Cat' },
// { id: 3, code: 'rabbit', name: 'Rabbit' } ];
const PetTypes = Enum(petTypes, {
getValue: 'id',
getLabel: 'name',
getKey: 'code', // Optional, if omitted, value is used as Key as fallback
});
Week.values; // Output is:
// [ { value: 1, label: 'Dog', key: 'dog' },
// { value: 2, label: 'Cat', key: 'cat' },
// { value: 3, label: 'Rabbit', key: 'rabbit' } ]
Enum.XXX
Like native enum, pick a value of an enum item from the enum type
Week.Monday; // 1
Week.Sunday; // 0
{value, label, key, raw}[]
Get a read-only array containing all enum items, which can be easily traversed. Since it conforms to the data specification of AntDesign components, it supports one-click conversion of enums into components such as dropdowns and checkboxes, with just a single line of code. For more details, please refer to the examples below.
string[]
Get a read-only array containing all Key of the enum items
[Function] label(keyOrValue?: string | number): string | undefined
Get the display text of an enum item based on a certain enum value or Key. If localization is setup, the localized text will be returned.
Week.label(1); // Monday
Week.label('Monday'); // Monday (this is label, not key)
[Function] key(value?: string | number): string | undefined
Get the Key of an enum item based on the enum value, if the Key is not found, return undefined.
Week.key(1); // Monday (this is key, not label)
[Function] has(keyOrValue?: string | number): boolean
Determine whether a certain enum item (value or Key) exists
Week.has(1); // true
Week.has('Sunday'); // true
Week.has(9); // false
Week.has('Birthday'); // false
[Function] toSelect(config?: OptionsConfig): {value, label}[]
toSelect is similar to values, both return an array containing all enum items. The difference is that the elements returned by toSelect only contain the label and value fields. At the same time, the toSelect method supports inserting a default element at the beginning of the array, which is generally used for the default option of components such as dropdowns, representing all, none, or unlimited, etc., of course, you can also customize this default option
[Function] toMenu(): { key, label }[]
Generate an object array that can be bound to the Menu, Dropdown components of Ant Design
import { Menu } from 'antd';
<Menu items={Week.toMenu()} />;
The data format is:
[
{ key: 0, label: 'Sunday' },
{ key: 1, label: 'Monday' },
];
[Function] toFilter(): { text, value }[]
Generate an array of filters that can be passed directly to the Column.filters of the Ant Design Table component as a list of filtered items for the column, displaying a dropdown filter box in the table header to filter table data
The data format is:
[
{ text: 'Sunday', value: 0 },
{ text: 'Monday', value: 1 },
];
[Function] toValueMap(): Record<V, { text: string }>
Generate an enum collection object that conforms to the Ant Design Pro specification, which can be passed to components like ProFormField, ProTable
The data format is:
{
0: { text: 'Sunday' },
1: { text: 'Monday' },
}
[Override^1] raw(): Record<K, T[K]>
[Override^2] raw(keyOrValue: V | K): T[K]
The first overload without parameters returns the initialization object of the enum collection, which is used to initialize the Enum original init object.
The second overload method is used to process a single enum item. Get the original initialization object of the enum item based on the enum value or enum Key, that is, the return value of the first method is part of the return value of the second method. In addition, if additional extension fields are added to the enum item, they can also be obtained in this way
const Week = Enum({
Sunday: { value: 0, label: 'Sunday' },
Monday: { value: 1, label: 'Monday' },
} as const);
Week.raw(); // { Sunday: { value: 0, label: 'Sunday' }, Monday: { value: 1, label: 'Monday' } }
Week.raw(0); // { value: 0, label: 'Sunday' }
Week.raw('Monday'); // { value: 1, label: 'Monday' }
value1 | value2 | ...
In TypeScript, get a union type containing all enum values, used to narrow the data type of variables or component properties, avoid using number, string and other overly broad types, improve code readability and type safety
const weekValue: typeof Week.valueType = 1;
const weeks: (typeof Week.valueType)[] = [0, 1];
type WeekValues = typeof Week.valueType; // 0 | 1
Note that this is only a TypeScript type, which can only be used to constrain types and cannot be called at runtime, calling at runtime will throw an exception
key1 | key2 | ...
Similar to valueType, get a union type containing all enum Keys
const weekKey: typeof Week.keyType = 'Monday';
const weekKeys: (typeof Week.keyType)[] = ['Sunday', 'Monday'];
type WeekKeys = typeof Week.keyType; // 'Sunday' | 'Monday'
Note that this is only a TypeScript type, which can only be used to constrain types and cannot be called at runtime, calling at runtime will throw an exception
{ value: V, label: string, [...] }
Similar to the raw method without parameters, but the raw method supports runtime calls, while rawType can only be used to constrain types
Note that this is only a TypeScript type, which can only be used to constrain types and cannot be called at runtime, calling at runtime will throw an exception
const Week = Enum({
Sunday: { value: 0, label: 'Sunday' },
Monday: { value: 1, label: 'Monday' },
} as const);
Week.Monday; // 1
Week.Sunday; // 0
In the code editor, hover over an enum item to display detailed Jsdoc comments about the enum item, without having to go back to the enum definition. In addition, when entering HttpCodes., the editor will automatically prompt the enum item list, switch enum items through the up and down keys, and you can also see the detailed Jsdoc comments of each one.
const HttpCodes = Enum({
/** Code400: Bad Request. The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing) */
E400: { value: 400, label: 'Bad Request' },
/** Code400: Unauthorized. The client must authenticate itself to get the requested response */
E401: { value: 401, label: 'Unauthorized' },
/** Code403: Forbidden. The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the server knows the client's identity */
E403: { value: 0, label: 'Forbidden' },
/** Code404: Not Found. The server can not find the requested resource. In a browser, this means the URL is not recognized */
E404: { value: 1, label: 'Not Found' },
} as const);
HttpCodes.E404; // Hover over E404 to display full Jsdoc comments
In the above example, the interpretation of Http status is referenced from MDN
Week.values; // Output is:
// [
// { value: 0, label: 'Sunday', key: 'Sunday', raw: { value: 0, label: 'Sunday' } },
// { value: 1, label: 'Monday', key: 'Monday', raw: { value: 1, label: 'Monday' } },
// ]
Week.values[0].value; // 0
Week.has(1); // true
Week.values.some(item => item.value === 1); // true
1 instance of Week; // true
instanceof operator1 instance of Week // true
"1" instance of Week // true
"Monday" instance of Week // true
Week.values.length; // 2
Week.values.map((item) => item.value); // [0, 1], ✅ Traversable
Week.values.forEach((item) => {}); // ✅ Traversable
for (let item of Week.values) {
// ✅ Traversable
}
Week.values.push({ value: 2, label: 'Tuesday' }); // ❌ Not modifiable
Week.values.splice(0, 1); // ❌ Not modifiable
Week.values[0].label = 'foo'; // ❌ Not modifiable
Week.label(1); // Monday
Week.label(Week.Monday); // Monday
Week.label('Monday'); // Monday
Week.key(1); // 'Monday', this is label, not key
Week.key(Week.Monday); // 'Monday', this is label, not key
Week.key(9); // undefined, because it does not exist
const Week = Enum({
Sunday: { value: 0, label: 'Sunday', active: true, disabled: false },
Monday: { value: 1, label: 'Monday', active: false, disabled: true },
} as const);
Week.raw(0).active // true
Week.raw(Week.Sunday).active // true
Week.raw('Sunday').active // true
values can be consumed as the data source (here uses Select as examples)
Ant Design | Arco Design Select
import { Select } from 'antd';
<Select options={Week.values} />;
Material-UI Select
import { MenuItem, Select } from '@mui/material';
<Select>
{Week.values.map((item) => (
<MenuItem key={item.value} value={item.value}>
{item.label}
</MenuItem>
))}
</Select>;
Kendo UI Select
import { DropDownList } from '@progress/kendo-react-dropdowns';
<DropDownList data={Week.values} textField="label" dataItemKey="value" />;
ElementPlus Select
<el-select>
<el-option v-for="item in Week.values" v-bind="item" />
</el-select>
Ant Design Vue | Arc Design Select
<a-select :options="Week.values" />
Vuetify Select
<v-select :items="Week.values" item-title="label" />
Angular Material Select
HTML
<mat-select>
<mat-option *ngFor="let item of Week.values" [value]="item.value">{{ item.label }}</mat-option>
</mat-select>
NG-ZORRO Select
HTML
<nz-select>
<nz-option *ngFor="let item of Week.values" [nzValue]="item.value">{{ item.label }}</nz-option>
</nz-select>
toSelect method is similar to values, but is allowed to add a default option at the top. The default option can be a boolean value or a custom object.
{ value: '', label: 'All' }, the display name only supports English. If you need localization, please parse and process the built-in resource key enum-plus.options.all in the localization method. For more details about localization, please refer to the Localization section<Select options={Week.toSelect({ firstOption: true })} />
// [
// { value: '', label: 'All' },
// { value: 0, label: 'Sunday' },
// { value: 1, label: 'Monday' }
// ]
// Add custom option at the top
<Select options={Week.toSelect({ firstOption: { value: 0, label: 'Unlimited' } })} />
toMenu method can generate data sources for Ant Design Menu, Dropdown components, the format is: { key: number|string, label: string } []
import { Menu } from 'antd';
<Menu items={Week.toMenu()} />;
toFilter method can generate an object array for binding the column filter function to the table, displaying a dropdown filter box in the table header to filter table data. The object structure follows the data specification of Ant Design Table component, the format is: { text: string, value: number|string } []import { Table } from 'antd';
const columns = [
{
title: 'week',
dataIndex: 'week',
filters: Week.toFilter(),
},
];
// Add column filter at table header
<Table columns={columns} />;
toValueMap method can generate data sources for ProFormFields, ProTable components of Ant Design Pro, which is a data structure similar to Map, the format is: { [key: number|string]: { text: string } }import { ProTable } from '@ant-design/pro-components';
<ProFormSelect valueEnum={Week.valuesEnum()} />;
const myWeek = Enum({
...Week.raw(),
Friday: { value: 5, label: 'Friday' },
Saturday: { value: 6, label: 'Saturday' },
});
By using the valueType type constraint, you can narrow the field type from the broad number or string type to a limited sequence of enum values, which not only reduces the possibility of erroneous assignments, but also improves the readability of the code.
const weekValue: number = 8; // 👎 Any number can be assigned to the week enum, even if it is wrong
const weekName: string = 'Birthday'; // 👎 Any string can be assigned to the week enum, even if it is wrong
const badWeekValue: typeof Week.valueType = 8; // ❌ Type error, 8 is not a valid week enum value
const badWeekName: typeof Week.keyType = 'Birthday'; // ❌ Type error, 'Birthday' is not a valid week enum name
const goodWeekValue: typeof Week.valueType = 1; // ✅ Type correct, 1 is a valid week enum value
const goodWeekName: typeof Week.keyType = 'Monday'; // ✅ Type correct, 'Monday' is a valid week enum name
type FooProps = {
value?: typeof Week.valueType; // 👍 Component property type constraint, prevent erroneous assignment, and also prompt which values are valid
names?: (typeof Week.keyType)[]; // 👍 Component property type constraint, prevent erroneous assignment, and also prompt which values are valid
};
Here are some edge cases for using enums. As seen from the above examples, we can quickly access enum items through Week.XXX, but what if the key of an enum item conflicts with the name of an enum method?
We know that there are methods like label, key, toSelect on the enum type. If they have the same name as an enum item, the enum item's value has a higher priority and will override these methods. But don't worry, you can access them under values. Please refer to the code example below:
const Week = Enum({
foo: { value: 1 },
bar: { value: 2 },
keys: { value: 3 }, // Naming conflict
label: { value: 4 }, // Naming conflict
} as const);
Week.keys; // 3, enum item has higher priority and will override the method
Week.label; // 4, enum item has higher priority and will override the method
// You can access these methods through values 🙂
Week.values.keys // ['foo', 'bar', 'keys', 'label']
Week.values.label(1); // 'foo'
An even more extreme case, what if values conflicts with the name of an enum item? Don't worry, you can still access the values array through an alias field. Refer to the example below:
import { VALUES } from 'enum-plus';
const Week = Enum({
foo: { value: 1 },
bar: { value: 2 },
values: { value: 3 }, // Naming conflict
} as const);
Week.values; // 3, enum item has higher priority and will override values
Week[VALUES]; // VALUES is an alias Symbol
// [
// { value: 1, key: 'foo', label: 'foo' },
// { value: 2, key: 'bar', label: 'bar' },
// { value: 3, key: 'values', label: 'values' }
// ]
// Equivalent to the original Week.values 🙂
enum-plus does not provide internationalization functionality itself, but supports custom localization methods through the localize optional parameter. You can declare a localization method in your project to convert the input enum label into the corresponding localized text. You need to maintain the language yourself and return the corresponding text for the current language in the localize method. If possible, it is strongly recommended that you use a popular internationalization library, such as i18next
Here is a simple example, but the first method is not a good practice because it is not flexible enough, and is only used to demonstrate basic functionality
import { Enum } from 'enum-plus';
import i18next from 'i18next';
import Localize from './Localize';
let lang = 'zh-CN';
const setLang = (l: string) => {
lang = l;
};
// ❌ This is not a good example, just to demonstrate basic functionality, please use other methods later
const sillyLocalize = (content: string) => {
if (lang === 'zh-CN') {
switch (content) {
case 'enum-plus.options.all':
return '全部';
case 'week.sunday':
return '星期日';
case 'week.monday':
return '星期一';
default:
return content;
}
} else {
switch (content) {
case 'enum-plus.options.all':
return 'All';
case 'week.sunday':
return 'Sunday';
case 'week.monday':
return 'Monday';
default:
return content;
}
}
};
// ✅ Recommended to use i18next or other internationalization libraries
const i18nLocalize = (content: string | undefined) => i18next.t(content);
// ✅ Or encapsulate it into a basic component
const componentLocalize = (content: string | undefined) => <Localize value={content} />;
const Week = Enum(
{
Sunday: { value: 0, label: 'week.sunday' },
Monday: { value: 1, label: 'week.monday' },
} as const,
{
localize: sillyLocalize,
// localize: i18nLocalize, // 👍 Recommended to use i18n
// localize: componentLocalize, // 👍 Recommended to use component
}
);
setLang('zh-CN');
Week.label(1); // 星期一
setLang('en-US');
Week.label(1); // Monday
Setting each enum type individually can be cumbersome. You can also set localization globally using the Enum.localize method. If both static settings and initialization options are provided, the initialization options take precedence.
Enum.localize = sillyLocalize;
Enum has provided some helpful methods, but if these methods are not enough to you, you can add custom extension functions via the Enum.extend method. These extension methods will be added to all enum types, even if the enum type has been created before the extension, it will take effect immediately
App.ts
Enum.extend({
isWeekend() {
return this.value === 0 || this.value === 6;
},
reversedValues(this: ReturnType<typeof Enum>) {
return this.values.reverse();
},
});
If you are using TypeScript, you probably need to further extend the enum type declaration to get better type hints. Create or edit a declaration file in your project (e.g. global.d.ts) and extend the global type. This file can be placed in the root directory of the project or any other directory, just make sure TypeScript can find it
global.d.ts
import type { EnumItemInit } from 'enum-plus';
import type { EnumItemClass } from 'enum-plus/lib/enum-item';
declare global {
export interface EnumExtension<T, K, V> {
isWeekend: (value: number) => boolean;
reversedValues: () => EnumItemClass<EnumItemInit<V>, K, V>[];
}
}
Please note that you are not required to import types such as EnumItemInit and EnumItemClass, they are only used in this example to provide better type hints
EnumExtension is a generic interface that accepts three type parameters, which are:
T: Initialization object of the enum typeK: Key value of the enum itemV: Value of the enum itemIf you want to provide more friendly type hints in the extension methods, you may need to use these type parameters. These are all optional, if your extension method is as simple as isWeekend, you can completely ignore them
FAQs
A drop-in replacement for enum, like native enum but much better!
The npm package enum-plus receives a total of 0 weekly downloads. As such, enum-plus popularity was classified as not popular.
We found that enum-plus demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.
Security News
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.