feat: rename IS_ENUM_COLLECTION symbol

Author: shijistar

CHANGELOG.md

@@ -53,7 +53,7 @@ const MyEnum = Enum({
   - `enums.filters`
   - `enums.valuesEnum`
 - Please use the new methods `Enum.items`, `Enum.toSelect`, `Enum.toMenu`, `Enum.toFilter`, and `Enum.toValueMap` instead, which are introduced since `v2.1.0`.
-- `ENUM_COLLECTION` symbol is renamed to `IS_ENUM_COLLECTION`.
+- `ENUM_COLLECTION` symbol is renamed to `IS_ENUM`.
 - `ENUM_ITEM` symbol is renamed to `IS_ENUM_ITEM`.
 - `ENUM_ITEMS` symbol is renamed to `IS_ENUM_ITEMS`.
 - `EnumValuesArray` interface is renamed to `EnumItemsArray`.

migrate-from-v2.md

@@ -4,6 +4,14 @@
 
 The `enum.values` property was originally planned for removal, but after some discussions, we decided to restore it and change its function: it now represents an array of the member raw values. Therefore, if you are still using the old `values`, please change to the `enum.items` instead.
 
+## 🛠 Symbols changed
+
+The following symbols have been renamed to better reflect their purpose:
+
+- `ENUM_COLLECTION` is now `IS_ENUM`
+- `ENUM_ITEM` is now `IS_ENUM_ITEM`
+- `ENUM_ITEMS` is now `IS_ENUM_ITEMS`
+
 ## 🛠 AntDesign oriented methods have been moved
 
 The following methods are removed from the core library and moved to the `enum-plus-plugin-antd` package. Please install the package and use them from there.

src/enum-collection.ts

@@ -18,7 +18,7 @@ import type {
   ValueTypeFromSingleInit,
 } from './types';
 import type { IS_ENUM_ITEMS } from './utils';
-import { IS_ENUM_COLLECTION, ITEMS, KEYS, LABELS, VALUES } from './utils';
+import { IS_ENUM, ITEMS, KEYS, LABELS, VALUES } from './utils';
 
 /**
  * - **EN:** Enum collection extension base class, used to extend the Enums
@@ -51,7 +51,7 @@ export class EnumCollectionClass<
    * - **EN:** A boolean value indicates that this is an enum collection instance.
    * - **CN:** 布尔值，表示这是一个枚举集合实例
    */
-  readonly [IS_ENUM_COLLECTION] = true;
+  readonly [IS_ENUM] = true;
   [Symbol.hasInstance](this: EnumCollectionClass<T, K, V>, instance: unknown): boolean {
     // intentionally use == to support both number and string format value
     return this.items.some(

src/enum.ts

@@ -12,7 +12,7 @@ import type {
   LocalizeInterface,
   ValueTypeFromSingleInit,
 } from './types';
-import type { IS_ENUM_COLLECTION, ITEMS, KEYS, LABELS, VALUES } from './utils';
+import type { IS_ENUM, ITEMS, KEYS, LABELS, VALUES } from './utils';
 
 export interface EnumInterface {
   /**
@@ -88,6 +88,8 @@ export interface EnumInterface {
    * > 根据不同的环境或技术框架，返回值可能是字符串以外类型，例如可能是一个组件以支持动态语言切换，而枚举项的`label`也会随之变化。
    */
   localize: LocalizeInterface | undefined;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  isEnum<T>(value: T): value is IEnum<any, any, any>;
   /**
    * - **EN:** Add global extension methods to the enum, and all enum instances will have these new
    *   extension methods
@@ -122,7 +124,7 @@ export type IEnum<
      * - **EN:** A boolean value indicates that this is an enum collection instance.
      * - **CN:** 布尔值，表示这是一个枚举集合实例
      */
-    [IS_ENUM_COLLECTION]: true;
+    [IS_ENUM]: true;
   } & {
     // Add enum item values, just like native enums
     [key in K]: ValueTypeFromSingleInit<T[key], key, T[K] extends number | undefined ? number : key>;

src/index.ts

@@ -15,6 +15,6 @@ export type { ToListConfig, IEnumItems } from './enum-items';
 export type { EnumItemClass, EnumItemOptions } from './enum-item';
 export type { IEnum, EnumInterface, EnumInitOptions } from './enum';
 
-export { KEYS, ITEMS, VALUES, LABELS, IS_ENUM_ITEM, IS_ENUM_ITEMS, IS_ENUM_COLLECTION, defaultLocalize } from './utils';
+export { KEYS, ITEMS, VALUES, LABELS, IS_ENUM_ITEM, IS_ENUM_ITEMS, IS_ENUM, defaultLocalize } from './utils';
 export type { PluginFunc } from './enum';
 export { Enum } from './enum';

src/utils.ts

@@ -36,23 +36,20 @@ export const LABELS = Symbol.for('[labels]');
 export const RAW = Symbol.for('[raw]');
 
 /**
- * - **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` 实例
+ * - **CN:** 判断对象是否 `EnumItem` 实例
+ * - **EN:** Check whether the object is an `EnumItem` instance
  */
 export const IS_ENUM_ITEM = Symbol.for('[IsEnumItem]');
 
 /**
- * - **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` 实例
+ * - **EN:** Check whether the object is an enum type
+ * - **CN:** 判断对象是否枚举类型
  */
-export const IS_ENUM_COLLECTION = Symbol.for('[IsEnumCollection]');
+export const IS_ENUM = Symbol.for('[IsEnum]');
 
 /**
- * - **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` 实例
+ * - **EN:** Check whether the object is an `EnumItems` collection array
+ * - **CN:** 判断对象是否 `EnumItems` 集合数组
  */
 export const IS_ENUM_ITEMS = Symbol.for('[IsEnumItems]');
 

test/test-suites/enum-collection.ts

@@ -1,4 +1,4 @@
-import { defaultLocalize, IS_ENUM_COLLECTION as IS_ENUM_COLLECTION_IN_NODE } from '@enum-plus';
+import { defaultLocalize, IS_ENUM as IS_ENUM_IN_NODE } from '@enum-plus';
 import type TestEngineBase from '../engines/base';
 import { toPlainEnums } from '../utils/index';
 import { addEnumValuesTestSuite } from './enum-items';
@@ -159,16 +159,16 @@ const testEnumCollection = (engine: TestEngineBase) => {
 
     engine.test(
       'should have [ENUM_COLLECTION] property to indicate that this is an enum collection',
-      ({ EnumPlus: { Enum, IS_ENUM_COLLECTION }, WeekConfig: { StandardWeekConfig } }) => {
+      ({ EnumPlus: { Enum, IS_ENUM }, WeekConfig: { StandardWeekConfig } }) => {
         const week = Enum(StandardWeekConfig);
-        return { week, IS_ENUM_COLLECTION };
+        return { week, IS_ENUM };
       },
-      ({ week, IS_ENUM_COLLECTION }) => {
-        // @ts-expect-error: because IS_ENUM_COLLECTION is hidden by the interface, but it actually exists
-        engine.expect(week[IS_ENUM_COLLECTION]).toBe(true);
-        engine.expect(week[IS_ENUM_COLLECTION_IN_NODE]).toBe(true);
-        // @ts-expect-error: because IS_ENUM_COLLECTION and Symbol.for('[IsEnumCollection]') are equal
-        engine.expect(week[Symbol.for('[IsEnumCollection]')]).toBe(true);
+      ({ week, IS_ENUM }) => {
+        // @ts-expect-error: because IS_ENUM is hidden by the interface, but it actually exists
+        engine.expect(week[IS_ENUM]).toBe(true);
+        engine.expect(week[IS_ENUM_IN_NODE]).toBe(true);
+        // @ts-expect-error: because IS_ENUM and Symbol.for('[IsEnum]') are equal
+        engine.expect(week[Symbol.for('[IsEnum]')]).toBe(true);
       }
     );