feat: refactor enum detecting to use ENUM_ITEM and ENUM_COLLECTION symbols

Author: shijistar

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 # enum-plus Changelog
 
+## 2.2.12
+
+2025-5-20
+
+### Features
+
+- ✨ Exports three new symbols `ENUM_ITEM`，`ENUM_ITEMS` and `ENUM_COLLECTION`.
+- ✨ Add `[ENUM_COLLECTION] = true` to the `Enum` class, which is used to indicates that this is as an enum collection.
+- ✨ Add `[ENUM_ITEM] = true` to the `EnumItem` class, which is used to indicates that this is as an enum item.
+- ✨ Add `[ENUM_ITEMS] = true` to the `Enum.items`, which is used to indicates that this is as an enum items array.
+
+### Breaking Changes
+
+- 💣 Remove `[Symbol.toStringTag] = "EnumItem"` from `EnumItem` class. The value of `Object.prototype.toString.call(enumItem)` is changed from `[object EnumItem]` to `[object Object]`. If you are relying on this, please use `enumItem[ENUM_ITEM] === true` instead.
+- 💣 Remove `[Symbol.toStringTag] = "EnumCollection"` from `Enum` class. The value of `Object.prototype.toString.call(enum)` is changed from `[object EnumCollection]` to `[object Array]`. If you are relying on this, please use `enum[ENUM_COLLECTION] === true` instead.
+
 ## 2.2.11
 
 2025-5-15

package.json

@@ -1,6 +1,6 @@
 {
   "name": "enum-plus",
-  "version": "2.2.11",
+  "version": "2.2.12",
   "description": "A drop-in replacement for native enum. Like native enum but much better!",
   "keywords": [
     "enum",

src/enum-collection.ts

@@ -1,5 +1,5 @@
 import { EnumItemClass } from './enum-item';
-import { EnumValuesArray } from './enum-values';
+import { EnumItemsArray } from './enum-values';
 import type {
   BooleanFirstOptionConfig,
   ColumnFilterItem,
@@ -10,14 +10,14 @@ import type {
   EnumKey,
   EnumValue,
   FindEnumKeyByValue,
-  IEnumValues,
+  IEnumItems,
   MenuItemOption,
   ObjectFirstOptionConfig,
   StandardEnumItemInit,
   ToSelectConfig,
   ValueTypeFromSingleInit,
 } from './types';
-import { ITEMS, KEYS, VALUES } from './utils';
+import { ENUM_COLLECTION, ITEMS, KEYS, VALUES } from './utils';
 
 /**
  * **EN:** Enum collection extension base class, used to extend the Enums
@@ -42,10 +42,16 @@ export class EnumCollectionClass<
     V extends EnumValue = ValueTypeFromSingleInit<T[K], K>,
   >
   extends EnumExtensionClass<T, K, V>
-  implements IEnumValues<T, K, V>
+  implements IEnumItems<T, K, V>
 {
-  readonly items!: EnumValuesArray<T, K, V>;
+  readonly items!: EnumItemsArray<T, K, V>;
   readonly keys!: K[];
+  /**
+   * **EN:** A boolean value indicates that this is an enum collection instance.
+   *
+   * **CN:** 布尔值，表示这是一个枚举集合实例
+   */
+  readonly [ENUM_COLLECTION] = true;
 
   constructor(init: T = {} as T, options?: EnumItemOptions) {
     super();
@@ -64,7 +70,7 @@ export class EnumCollectionClass<
     this[Object.keys(init).some((k) => k === 'keys') ? KEYS : 'keys'] = keys;
 
     // Build enum item data
-    const items = new EnumValuesArray<T, K, V>(
+    const items = new EnumItemsArray<T, K, V>(
       init,
       options,
       ...keys.map((key, index) => {
@@ -77,9 +83,6 @@ export class EnumCollectionClass<
     // @ts-expect-error: because use VALUES to avoid naming conflicts in case of 'values' field name is taken
     this[Object.keys(init).some((k) => k === 'values') ? VALUES : 'values'] = items;
 
-    // Override some system methods
-    // @ts-expect-error: because override Object.toString method for better type display
-    this[Symbol.toStringTag] = 'EnumCollection';
     // Override the `instanceof` operator rule
     // @ts-expect-error: because override the instanceof operator
     this[Symbol.hasInstance] = (instance: unknown): boolean => {

src/enum-item.ts

@@ -1,5 +1,6 @@
 import { Enum } from './enum';
 import type { EnumItemInit, EnumItemOptions, EnumKey, EnumValue, ValueTypeFromSingleInit } from './types';
+import { ENUM_ITEM } from './utils';
 
 /**
  * Enum item class
@@ -25,6 +26,12 @@ export class EnumItemClass<
 
   /** Original initialization object */
   readonly raw: T;
+  /**
+   * **EN:** A boolean value indicates that this is an enum item instance.
+   *
+   * **CN:** 布尔值，表示这是一个枚举项实例
+   */
+  [ENUM_ITEM] = true;
 
   #localize: NonNullable<EnumItemOptions['localize']>;
   #localizedProxy = new Proxy(this, {
@@ -96,9 +103,6 @@ export class EnumItemClass<
       return content;
     };
 
-    // Override some system methods
-    // @ts-expect-error: because override Object.toString method to display type more friendly
-    this[Symbol.toStringTag] = 'EnumItem';
     // @ts-expect-error: because override Object.toPrimitive method to return enum value
     this[Symbol.toPrimitive] = (hint: 'number' | 'string' | 'default'): V | string => {
       if (hint === 'number') {

src/enum-values.ts

@@ -10,13 +10,14 @@ import type {
   EnumKey,
   EnumValue,
   FindEnumKeyByValue,
-  IEnumValues,
+  IEnumItems,
   MenuItemOption,
   ObjectFirstOptionConfig,
   ToSelectConfig,
   ValueMap,
   ValueTypeFromSingleInit,
 } from './types';
+import { ENUM_ITEMS } from './utils';
 
 /**
  * Enum items array, mostly are simple wrappers for EnumCollectionClass
@@ -31,13 +32,13 @@ import type {
  *
  * @implements {IEnumValues<T, K, V>}
  */
-export class EnumValuesArray<
+export class EnumItemsArray<
     T extends EnumInit<K, V>,
     K extends EnumKey<T> = EnumKey<T>,
     V extends EnumValue = ValueTypeFromSingleInit<T[K], K>,
   >
   extends Array<EnumItemClass<T[K], K, V>>
-  implements IEnumValues<T, K, V>
+  implements IEnumItems<T, K, V>
 {
   #raw: T;
   #localize: NonNullable<EnumItemOptions['localize']>;
@@ -62,6 +63,12 @@ export class EnumValuesArray<
       return content;
     };
   }
+  /**
+   * **EN:** A boolean value indicates that this is an enum items array.
+   *
+   * **CN:** 布尔值，表示这是一个枚举项数组
+   */
+  [ENUM_ITEMS] = true;
 
   label(keyOrValue?: string | number): string | undefined {
     //  First find by value, then find by key
@@ -199,3 +206,10 @@ export class EnumValuesArray<
     );
   }
 }
+
+/** @deprecated Use `EnumItemsArray` instead */
+export class EnumValuesArray<
+  T extends EnumInit<K, V>,
+  K extends EnumKey<T> = EnumKey<T>,
+  V extends EnumValue = ValueTypeFromSingleInit<T[K], K>,
+> extends EnumItemsArray<T, K, V> {}

src/index.ts

@@ -16,7 +16,7 @@ export type {
 } from './types';
 export type { EnumItemClass } from './enum-item';
 
-export { KEYS, ITEMS, VALUES } from './utils';
+export { KEYS, ITEMS, VALUES, ENUM_ITEM, ENUM_ITEMS, ENUM_COLLECTION } from './utils';
 export { defaultLocalize };
 export { Enum } from './enum';
 

src/types.ts

@@ -63,14 +63,14 @@ export type IEnum<
   T extends EnumInit<K, V>,
   K extends EnumKey<T> = EnumKey<T>,
   V extends EnumValue = ValueTypeFromSingleInit<T[K], K>,
-> = IEnumValues<T, K, V> & {
+> = IEnumItems<T, K, V> & {
   // 初始化对象里的枚举字段
   [key in K]: ValueTypeFromSingleInit<T[key], key, T[K] extends number | undefined ? number : key>;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 } & (T extends { items: any }
     ? {
         // 防止values名称冲突
-        [ITEMS]: EnumItemClass<T[K], K, V>[] & IEnumValues<T, K, V>;
+        [ITEMS]: EnumItemClass<T[K], K, V>[] & IEnumItems<T, K, V>;
       }
     : {
         /**
@@ -84,17 +84,17 @@ export type IEnum<
          *
          * 仅支持 ReadonlyArray<T> 中的只读方法，不支持push、pop等任何修改的方法
          */
-        items: EnumItemClass<T[K], K, V>[] & IEnumValues<T, K, V>;
+        items: EnumItemClass<T[K], K, V>[] & IEnumItems<T, K, V>;
       }) &
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   (T extends { values: any }
     ? {
         // 防止values名称冲突
-        [VALUES]: EnumItemClass<T[K], K, V>[] & IEnumValues<T, K, V>;
+        [VALUES]: EnumItemClass<T[K], K, V>[] & IEnumItems<T, K, V>;
       }
     : {
         /** @deprecated Use `items` instead */
-        values: EnumItemClass<T[K], K, V>[] & IEnumValues<T, K, V>;
+        values: EnumItemClass<T[K], K, V>[] & IEnumItems<T, K, V>;
       }) &
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   (T extends { keys: any }
@@ -123,11 +123,9 @@ export type IEnum<
  *
  * @template T Enum collection initialization data type | 枚举集合初始化数据的类型
  *
- * @export
- *
- * @interface IEnumValues
+ * @interface IEnumItems
  */
-export interface IEnumValues<
+export interface IEnumItems<
   T extends EnumInit<K, V>,
   K extends EnumKey<T> = EnumKey<T>,
   V extends EnumValue = ValueTypeFromSingleInit<T[K], K>,
@@ -361,6 +359,13 @@ export interface IEnumValues<
   rawType: T[K];
 }
 
+/** @deprecated use `IEnumItems` instead */
+export type IEnumValues<
+  T extends EnumInit<K, V>,
+  K extends EnumKey<T> = EnumKey<T>,
+  V extends EnumValue = ValueTypeFromSingleInit<T[K], K>,
+> = IEnumItems<T, K, V>;
+
 // eslint-disable-next-line @typescript-eslint/ban-types
 export type EnumItemLabel = EnumLocaleExtends['LocaleKeys'] | (string & {});
 

src/utils.ts

@@ -6,23 +6,47 @@ import type { EnumItemOptions } from './types';
  *
  * **CN:** 枚举`values`集合的别名。如果枚举中包含了`values`的同名字段，可以通过此Symbol作为字段名来访问
  */
-export const VALUES = Symbol('[values]');
+export const VALUES = Symbol.for('[values]');
 
 /**
  * **EN:** Alias of `items`. If the enum contains a field with the same name as `items`, you can
  * access it by this Symbol as the field name
  *
  * **CN:** 枚举`items`集合的别名。如果枚举中包含了`items`的同名字段，可以通过此Symbol作为字段名来访问
  */
-export const ITEMS = Symbol('[items]');
+export const ITEMS = Symbol.for('[items]');
 
 /**
  * **EN:** Alias of `keys`. If the enum contains a field with the same name as `keys`, you can
  * access it by this Symbol as the field name
  *
  * **CN:** 枚举keys集合的别名。如果枚举中包含了`keys`的同名字段，可以通过此Symbol作为字段名来访问
  */
-export const KEYS = Symbol('[keys]');
+export const KEYS = Symbol.for('[keys]');
+
+/**
+ * **EN:** Check whether the object is an instance of `EnumItem`. If the object has this field and
+ * its value is `true`, it is an `EnumItem` instance.
+ *
+ * **CN:** 判断对象是否 `EnumItem` 实例，如果对象存在此字段且值为`true`，则是 `EnumItem` 实例
+ */
+export const ENUM_ITEM = Symbol.for('[EnumItem]');
+
+/**
+ * **EN:** Check whether the object is an instance of `EnumCollection`. If the object has this field
+ * and its value is `true`, it is an `EnumCollection` instance.
+ *
+ * **CN:** 判断对象是否 `EnumCollection` 实例，如果对象存在此字段且值为`true`，则是 `EnumCollection` 实例
+ */
+export const ENUM_COLLECTION = Symbol.for('[EnumCollection]');
+
+/**
+ * **EN:** Check whether the object is an instance of `EnumItems`. If the object has this field and
+ * its value is `true`, it is an `EnumItems` instance.
+ *
+ * **CN:** 判断对象是否 `EnumItems` 实例，如果对象存在此字段且值为`true`，则是 `EnumItems` 实例
+ */
+export const ENUM_ITEMS = Symbol.for('[EnumItems]');
 
 /**
  * **EN:** Default global localization function, only used to resolve built-in resources into

test/enum-collection.test.ts

@@ -1,4 +1,4 @@
-import { Enum, ITEMS, KEYS, VALUES } from '@enum-plus';
+import { Enum, ENUM_COLLECTION, ITEMS, KEYS, VALUES } from '@enum-plus';
 import { locales, sillyLocalize, StandardWeekConfig } from './data/week-config';
 import { getStandardWeekData } from './data/week-data';
 import { addEnumValuesTestSuite } from './enum-values.test';
@@ -66,7 +66,7 @@ describe('the EnumCollectionClass api', () => {
       )
     );
     expect(strangeEnum.keys).toBe(101);
-    expect(strangeEnum.items.map((i) => i.key)).toEqual(Object.keys(strangeEnumConfig));
+    expect(Array.from(strangeEnum.items).map((i) => i.key)).toEqual(Object.keys(strangeEnumConfig));
 
     const strangerEnumConfig = {
       ...strangeEnumConfig,
@@ -88,10 +88,12 @@ describe('the EnumCollectionClass api', () => {
     expect(toPlainEnums(strangerEnum[VALUES])).toEqual(standardEnumItems);
   });
 
-  test('[toString] should return a friendly name', () => {
+  test('should have [ENUM_COLLECTION] property to indicate that this is an enum collection', () => {
     const week = Enum(StandardWeekConfig);
-    expect(week.toString()).toBe('[object EnumCollection]');
-    expect(Object.prototype.toString.call(week)).toBe('[object EnumCollection]');
+    // @ts-expect-error: because ENUM_COLLECTION is hidden by the interface, but it actually exists
+    expect(week[ENUM_COLLECTION]).toBe(true);
+    // @ts-expect-error: because ENUM_COLLECTION equals Symbol.for('[EnumCollection]')
+    expect(week[Symbol.for('[EnumCollection]')]).toBe(true);
   });
 
   test('enum value/key/label should be success by the [instanceof] operator', () => {

test/enum-item.test.ts

@@ -1,4 +1,4 @@
-import { Enum } from '@enum-plus';
+import { Enum, ENUM_ITEM } from '@enum-plus';
 import { localeEN, StandardWeekConfig } from './data/week-config';
 
 describe('the EnumItemClass api', () => {
@@ -29,11 +29,16 @@ describe('the EnumItemClass api', () => {
     expect(week.values[6].toLocaleString()).toBe(localeEN.Saturday);
   });
 
-  test('[toStringTag] should return a friendly name', () => {
+  test('should have [ENUM_ITEM] property to indicate that this is an enum item', () => {
     const week = Enum(StandardWeekConfig);
-    week.values.forEach((item) => {
-      expect(Object.prototype.toString.call(item)).toBe('[object EnumItem]');
-    });
+    const firstItem = week.items[0];
+    const lastItem = week.items[week.items.length - 1];
+    expect(firstItem[ENUM_ITEM]).toBe(true);
+    // @ts-expect-error: because ENUM_ITEM equals Symbol.for('[EnumItem]')
+    expect(firstItem[Symbol.for('[EnumItem]')]).toBe(true);
+    expect(lastItem[ENUM_ITEM]).toBe(true);
+    // @ts-expect-error: because ENUM_ITEM equals Symbol.for('[EnumItem]')
+    expect(lastItem[Symbol.for('[EnumItem]')]).toBe(true);
   });
 
   test('[valueOf] should return the enum value', () => {