feat: enhance enum handling with functional labels

Author: shijistar

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 # enum-plus Changelog
 
+## 3.1.5
+
+2025-11-20
+
+### Features
+
+- ✨ Add `AnyEnum` type as a generic enum type that can be used to represent any enum collection.
+
+### Bug Fixes
+
+- 🐞 Fix the issue where `enum.meta` is always empty in `meta-only` mode.
+
 ## 3.1.4
 
 2025-11-19

src/enum-collection.ts

@@ -127,6 +127,9 @@ export class EnumCollectionClass<
    *   set.
    */
   get name(): string | undefined {
+    if (typeof this.__options__?.name === 'function') {
+      return this.__options__.name(undefined!);
+    }
     const localize = this.__options__?.localize ?? localizer.localize;
     if (typeof localize === 'function') {
       return localize(this.__options__?.name);

src/enum-item.ts

@@ -1,5 +1,12 @@
 import { internalConfig, localizer } from './global-config';
-import type { EnumItemInit, EnumKey, EnumValue, LocalizeInterface, ValueTypeFromSingleInit } from './types';
+import type {
+  EnumItemInit,
+  EnumItemLabel,
+  EnumKey,
+  EnumValue,
+  LocalizeInterface,
+  ValueTypeFromSingleInit,
+} from './types';
 import { IS_ENUM_ITEM } from './utils';
 
 /**
@@ -20,7 +27,7 @@ export class EnumItemClass<
   const P = any,
 > {
   private _options: EnumItemOptions<T, K, V, P> | undefined;
-  private _label: string | undefined;
+  private _label: EnumItemLabel | undefined;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private _localize: (content: string | undefined) => any;
 
@@ -34,10 +41,10 @@ export class EnumItemClass<
    * @param raw The original initialization object | 原始初始化对象
    * @param options Optional settings for the enum item | 枚举项的可选设置
    */
-  constructor(key: K, value: V, label: string, raw: T, options?: EnumItemOptions<T, K, V, P>) {
+  constructor(key: K, value: V, label: EnumItemLabel, raw: T, options?: EnumItemOptions<T, K, V, P>) {
     this.key = key;
     this.value = value;
-    this.label = label;
+    this.label = label as string;
     this.raw = raw;
 
     // Should use _label instead of label closure, to make sure it can be serialized correctly
@@ -62,6 +69,10 @@ export class EnumItemClass<
           const labelPrefix = this._options?.labelPrefix;
           const autoLabel = this._options?.autoLabel ?? internalConfig.autoLabel;
           let localeKey = this._label;
+          if (typeof localeKey === 'function') {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return localeKey(this as any);
+          }
           if (autoLabel && labelPrefix != null) {
             if (typeof autoLabel === 'function') {
               localeKey = autoLabel({

src/enum-items.ts

@@ -3,6 +3,7 @@ import { EnumItemClass } from './enum-item';
 import type {
   EnumInit,
   EnumItemInit,
+  EnumItemLabel,
   EnumKey,
   EnumValue,
   ExactEqual,
@@ -107,7 +108,7 @@ export class EnumItemsArray<
         Object.keys(itemRaw).forEach((k) => {
           const metaKey = k as Exclude<keyof T[keyof T], 'key' | 'value' | 'label'>;
           if (metaKey !== 'key' && metaKey !== 'value' && metaKey !== 'label') {
-            if (!meta[metaKey]) {
+            if (meta[metaKey] == null) {
               meta[metaKey] = [];
             }
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -865,42 +866,42 @@ function parseEnumItem<
   V extends EnumValue,
 >(init: T, key: K): StandardEnumItemInit<V> {
   let value: V;
-  let label: string;
+  let label: EnumItemLabel;
   if (init != null) {
     if (typeof init === 'number' || typeof init === 'string' || typeof init === 'symbol') {
       value = init as V;
-      label = key as string;
+      label = key as EnumItemLabel;
     } else if (typeof init === 'object') {
       // Initialize using object
       if (Object.prototype.toString.call(init) === '[object Object]') {
         if ('value' in init && Object.keys(init).some((k) => k === 'value')) {
           // type of {value, label}
           value = (init.value ?? key) as V;
           if ('label' in init && Object.keys(init).some((k) => k === 'label')) {
-            label = init.label as string;
+            label = init.label!;
           } else {
-            label = key as string;
+            label = key as EnumItemLabel;
           }
         } else if ('label' in init && Object.keys(init).some((k) => k === 'label')) {
           // typeof {label}
           value = key as unknown as V;
-          label = init.label ?? (key as string);
+          label = init.label ?? (key as EnumItemLabel);
         } else {
           // {} empty object
           value = key as unknown as V;
-          label = key as string;
+          label = key as EnumItemLabel;
         }
       } else {
         // Probably Date, RegExp and other primitive types
         value = init as V;
-        label = key as string;
+        label = key as EnumItemLabel;
       }
     } else {
       throw new Error(`Invalid enum item: ${JSON.stringify(init)}`);
     }
   } else {
     value = key as unknown as V;
-    label = key as string;
+    label = key as EnumItemLabel;
   }
   return { value, label };
 }

src/extension.d.ts

@@ -24,6 +24,11 @@ declare module 'enum-plus/extension' {
      *
      * **CN:** 枚举本地化文本的Key值，可以用来增强编辑器的智能提示
      */
-    LocaleKeys: NonNullable<string>;
+    LocaleKeys: // eslint-disable-next-line @typescript-eslint/ban-types
+    | (string & {})
+      | ((
+          // eslint-disable-next-line @typescript-eslint/consistent-type-imports
+          item: import('./enum-item').EnumItemClass<import('./types').StandardEnumItemInit<import('./types').EnumValue>>
+        ) => string | undefined);
   }
 }

src/localize-interface.ts

@@ -1,6 +1,6 @@
 import type { EnumLocaleExtends } from 'enum-plus/extension';
 
 export type LocalizeInterface = (
-  localeKey: EnumLocaleExtends['LocaleKeys'] | undefined
+  localeKey: Exclude<EnumLocaleExtends['LocaleKeys'], (...args: any[]) => string | undefined> | undefined
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 ) => any;

src/utils.ts

@@ -74,6 +74,6 @@ export const IS_ENUM_ITEMS = Symbol.for('[IsEnumItems]');
  *   English, does not provide actual localization functions
  * - **CN:** 默认的全局本地化函数，仅用于将内置资源解析为英文，并不提供实际的本地化功能
  */
-export const defaultLocalize: LocalizeInterface = (content) => {
+export const defaultLocalize: LocalizeInterface = (content): string | undefined => {
   return content;
 };

test/data/week-config.ts

@@ -1,4 +1,5 @@
-import type { defaultLocalize as defaultLocalizeType, Enum as EnumType } from '@enum-plus';
+import type { defaultLocalize as defaultLocalizeType, EnumItemClass, Enum as EnumType } from '@enum-plus';
+import type { EnumValue, StandardEnumItemInit } from '@enum-plus/types';
 
 export const localeEN = {
   'weekDay.name': 'Week Days',
@@ -48,10 +49,12 @@ export let locales: typeof localeEN | typeof localeCN | typeof noLocale = noLoca
 export let lang: 'en-US' | 'zh-CN' | undefined = undefined;
 
 export function getLocales(language: typeof lang) {
-  return language === 'zh-CN' ? getLocales.localeCN : language ? getLocales.localeEN : noLocale;
+  const { localeCN, localeEN, noLocale } = getLocales;
+  return language === 'zh-CN' ? localeCN : language ? localeEN : noLocale;
 }
 getLocales.localeCN = localeCN;
 getLocales.localeEN = localeEN;
+getLocales.noLocale = noLocale;
 
 type getLocalesType = typeof getLocales;
 export function setLang(
@@ -60,9 +63,10 @@ export function setLang(
   getLocales: getLocalesType,
   defaultLocalize: typeof defaultLocalizeType
 ) {
+  const { genSillyLocalizer } = setLang;
   lang = value;
   locales = getLocales(value);
-  Enum.localize = value ? setLang.genSillyLocalizer(value, getLocales, defaultLocalize) : defaultLocalize;
+  Enum.localize = value ? genSillyLocalizer(value, getLocales) : defaultLocalize;
 }
 setLang.genSillyLocalizer = genSillyLocalizer;
 
@@ -81,6 +85,15 @@ export const StandardWeekConfig = {
   Friday: { value: 5, label: noLocale.Friday, status: 'success' },
   Saturday: { value: 6, label: noLocale.Saturday, status: 'error' },
 } as const;
+export const FuncLabelStandardWeekConfig = {
+  Sunday: { value: 0, label: labelLocalizer },
+  Monday: { value: 1, label: labelLocalizer },
+  Tuesday: { value: 2, label: labelLocalizer },
+  Wednesday: { value: 3, label: labelLocalizer },
+  Thursday: { value: 4, label: labelLocalizer },
+  Friday: { value: 5, label: labelLocalizer },
+  Saturday: { value: 6, label: labelLocalizer },
+} as const;
 export const ShortLabelStandardWeekConfig = {
   Sunday: { value: 0, label: 'Sunday' },
   Monday: { value: 1, label: 'Monday' },
@@ -180,41 +193,38 @@ export const WeekMetaOnlyConfig = Object.keys(StandardWeekConfig).reduce(
   {} as { [key in TKey]: Omit<TConfig[key], 'value' | 'label'> }
 );
 
-export function genSillyLocalizer(
-  language: typeof lang,
-  getLocales: getLocalesType,
-  defaultLocalize: typeof defaultLocalizeType
-) {
+export function genSillyLocalizer(language: typeof lang, getLocales: getLocalesType) {
   // should use function here to avoid closure. this is important for the e2e test cases.
   function sillyLocalize(
-    content: (typeof StandardWeekConfig)[keyof typeof StandardWeekConfig]['label'] | NonNullable<string> | undefined
-  ): typeof content {
-    const locales = sillyLocalize.locales;
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    content: (typeof noLocale)[keyof typeof noLocale] | (string & {}) | undefined
+  ): string | undefined {
+    const { locales } = sillyLocalize;
     switch (content) {
       case 'weekDay.name':
-        return locales['weekDay.name'] as typeof content;
+        return locales['weekDay.name'];
       case 'weekday.Sunday':
-        return locales.Sunday as typeof content;
+        return locales.Sunday;
       case 'weekday.Monday':
-        return locales.Monday as typeof content;
+        return locales.Monday;
       case 'weekday.Tuesday':
-        return locales.Tuesday as typeof content;
+        return locales.Tuesday;
       case 'weekday.Wednesday':
-        return locales.Wednesday as typeof content;
+        return locales.Wednesday;
       case 'weekday.Thursday':
-        return locales.Thursday as typeof content;
+        return locales.Thursday;
       case 'weekday.Friday':
-        return locales.Friday as typeof content;
+        return locales.Friday;
       case 'weekday.Saturday':
-        return locales.Saturday as typeof content;
-      case 'boolean.youes':
-        return locales.Yes as typeof content;
+        return locales.Saturday;
+      case 'boolean.Yes':
+        return locales.Yes;
       case 'boolean.No':
-        return locales.No as typeof content;
+        return locales.No;
       case 'date.FirstDay':
-        return locales.FirstDay as typeof content;
+        return locales.FirstDay;
       case 'date.LastDay':
-        return locales.LastDay as typeof content;
+        return locales.LastDay;
       default:
         return content;
     }
@@ -223,6 +233,16 @@ export function genSillyLocalizer(
   return sillyLocalize;
 }
 
+// eslint-disable-next-line @typescript-eslint/ban-types
+export function labelLocalizer(item: EnumItemClass<StandardEnumItemInit<EnumValue>>) {
+  const { genSillyLocalizer, getLocales, noLocale } = labelLocalizer;
+  const localizer = genSillyLocalizer(lang, getLocales);
+  return localizer(noLocale[item.key as keyof typeof noLocale]);
+}
+labelLocalizer.genSillyLocalizer = genSillyLocalizer;
+labelLocalizer.getLocales = getLocales;
+labelLocalizer.noLocale = noLocale;
+
 export function localizeConfigData(
   config: typeof StandardWeekConfig,
   locales: typeof localeEN | typeof localeCN | typeof noLocale
@@ -239,7 +259,8 @@ export function localizeConfigData(
   defaultLocalize?: typeof defaultLocalizeType
 ) {
   if (typeof getLocales === 'function' && defaultLocalize) {
-    const localizer = localizeConfigData.genSillyLocalizer(lang, getLocales, defaultLocalize);
+    const { genSillyLocalizer } = localizeConfigData;
+    const localizer = genSillyLocalizer(lang, getLocales);
     return Object.keys(config).reduce(
       (acc, key) => {
         // @ts-expect-error: because cannot assign to 'value' because it is a read-only property.

test/test-suites/create-enum.ts

@@ -15,7 +15,7 @@ import { toPlainEnums } from '../utils/index';
 const testCreatingEnum = (engine: TestEngineBase<'jest' | 'playwright'>) => {
   engine.describe('Create Enum using static init data', () => {
     engine.test(
-      'Should be created with standard init data',
+      'Should be created with standard init config',
       ({ EnumPlus: { Enum }, WeekConfig: { StandardWeekConfig, locales } }) => {
         const weekEnum = Enum(StandardWeekConfig);
         return { weekEnum, locales };
@@ -24,7 +24,24 @@ const testCreatingEnum = (engine: TestEngineBase<'jest' | 'playwright'>) => {
         engine.expect(weekEnum).toBeDefined();
         engine.expect(weekEnum).not.toBeNull();
         engine.expect(weekEnum?.items?.length).toBe(7);
-        engine.expect(toPlainEnums(weekEnum.items)).toEqual(getStandardWeekData(locales));
+        engine.expect(toPlainEnums(weekEnum?.items)).toEqual(getStandardWeekData(locales));
+      }
+    );
+    engine.test(
+      'Should be created with functional label init config',
+      ({ EnumPlus: { Enum }, WeekConfig: { FuncLabelStandardWeekConfig, locales } }) => {
+        const weekEnum = Enum(FuncLabelStandardWeekConfig);
+        return {
+          weekEnum,
+          items: Array.from(weekEnum.items).map(({ key, value, label }) => ({ key, value, label })),
+          locales,
+        };
+      },
+      ({ weekEnum, items, locales }) => {
+        engine.expect(weekEnum).toBeDefined();
+        engine.expect(weekEnum).not.toBeNull();
+        engine.expect(items.length).toBe(7);
+        engine.expect(items).toEqual(getStandardWeekData(locales));
       }
     );