feat: add enums.findBy method to find enum items by built-in fields and custom meta fields

shijistar · shijistar · commit f6345b788ee4 · 2025-07-21T14:21:38.000+08:00
diff --git a/e2e/specs/enum-items.spec.ts b/e2e/specs/enum-items.spec.ts
diff --git a/enum-plus-v3.md b/enum-plus-v3.md
@@ -1,5 +1,7 @@
 # enum-plus v3.0 - A Major Update
 
+### ■■■■■■■■■■■■■■■■■■□□ (90%)
+
 ## Features
 
 ### Codebase
@@ -8,14 +10,18 @@
 - [x] Remove deprecated `enum.menus`
 - [x] Remove deprecated `enum.filters`
 - [x] Remove deprecated `enum.valuesEnum`
+- [x] 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`
 - [x] Change the behavior of `enum.values`, now it returns an array of the member raw values. Use `enum.items` for the old behavior.
 - [x] Add `enum.labels` property, which returns an readonly array of the member labels.
-- [ ] Add `enum.find` method, which allows searching for enum items by specific field, including _meta_ fields (i.e. custom fields).
+- [x] Add `enum.findBy` method, which allows searching for enum items by built-in fields, and the custom _meta_ fields.
 - [ ] Add `enum.meta` object to aggregate all custom fields defined in the enum. The keys are the field names, and values are the raw values of each field. It's a good way of accessing custom fields without iterating through the enum items.
 - [x] Add `enum.toList`, method which is an alternative of `toSelect`、`toMenu`、`toFilter`. The latter methods are moving out of the core library and will be available as plugins.
 - [ ] Add `enum.toMap` as an alternative of `enum.toValueMap`.
 - [x] Add `Enum.isEnum` method to check if an object is an instance of `Enum`.
-- [ ] Add type assertion for `instanceof` check of EnumCollection.
+- [x] Add type assertion for `instanceof` check of EnumCollection.
 - [x] Simplify the enum initialization that no longer requires `as const` assertion. _by @otomad_
 - [x] Release the `UMD` module format of `enum-plus` in `umd` folder.
 - [x] Reuse one copy of testing code for both `Jest` and `e2e` testing.
diff --git a/src/enum-collection.ts b/src/enum-collection.ts
@@ -51,7 +51,11 @@ export class EnumCollectionClass<
    * - **EN:** A boolean value indicates that this is an enum collection instance.
    * - **CN:** 布尔值，表示这是一个枚举集合实例
    */
-  readonly [IS_ENUM] = true;
+  // Do not use readonly field here, because don't want print this field in Node.js
+  // eslint-disable-next-line @typescript-eslint/class-literal-property-style
+  get [IS_ENUM](): true {
+    return true;
+  }
   [Symbol.hasInstance]<T>(instance: T): instance is Extract<T, K | V> {
     return instance instanceof this.items;
   }
@@ -151,6 +155,11 @@ export class EnumCollectionClass<
     return this.items.has(keyOrValue);
   }
 
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  findBy(...rest: Parameters<EnumItemsArray<T, K, V>['findBy']>): any {
+    return this.items.findBy(...rest);
+  }
+
   toList(): ListItem<V, 'value', 'label'>[];
   toList<
     FOV extends string | ((item: EnumItemClass<T[K], K, V>) => string),
diff --git a/src/enum-item.ts b/src/enum-item.ts
@@ -44,7 +44,7 @@ export class EnumItemClass<
    * - **EN:** A boolean value indicates that this is an enum item instance.
    * - **CN:** 布尔值，表示这是一个枚举项实例
    */
-  readonly [IS_ENUM_ITEM] = true;
+  private readonly [IS_ENUM_ITEM] = true;
   /**
    * Auto convert to a correct primitive type. This method is called when the object is used in a
    * context that requires a primitive value.
@@ -55,7 +55,8 @@ export class EnumItemClass<
    *
    * @returns V | string
    */
-  [Symbol.toPrimitive](this: EnumItemClass<T, K, V>, hint: 'number' | 'string' | 'default'): V | string {
+  // @ts-expect-error: because don't want show `Symbol` in vscode's intellisense, it should work in background
+  private [Symbol.toPrimitive](this: EnumItemClass<T, K, V>, hint: 'number' | 'string' | 'default'): V | string {
     if (hint === 'number') {
       // for cases like Number(value) or +value
       return this.valueOf();
diff --git a/src/enum-items.ts b/src/enum-items.ts
@@ -5,7 +5,10 @@ import type {
   EnumKey,
   EnumValue,
   FindEnumKeyByValue,
+  FindKeyByMeta,
   FindLabelByValue,
+  FindValueByKey,
+  FindValueByMeta,
   ListItem,
   MenuItemOption,
   PrimitiveOf,
@@ -26,7 +29,7 @@ import { IS_ENUM_ITEMS } from './utils';
  * @implements {IEnumValues<T, K, V>}
  */
 export class EnumItemsArray<
-    T extends EnumInit<K, V>,
+    const T extends EnumInit<K, V>,
     K extends EnumKey<T> = EnumKey<T>,
     V extends EnumValue = ValueTypeFromSingleInit<T[K], K>,
   >
@@ -38,7 +41,11 @@ export class EnumItemsArray<
    * - **EN:** A boolean value indicates that this is an enum items array.
    * - **CN:** 布尔值，表示这是一个枚举项数组
    */
-  readonly [IS_ENUM_ITEMS] = true;
+  // Do not use readonly field here, because don't want print this field in Node.js
+  // eslint-disable-next-line @typescript-eslint/class-literal-property-style
+  get [IS_ENUM_ITEMS](): true {
+    return true;
+  }
 
   /**
    * Instantiate an enum items array
@@ -127,6 +134,41 @@ export class EnumItemsArray<
     return this.some((i) => i.value === keyOrValue || i.key === keyOrValue);
   }
 
+  findBy<FK extends 'key' | 'value' | 'label' | Exclude<keyof T[keyof T], 'key' | 'value' | 'label'>, FV>(
+    field: FK,
+    value: FV
+  ): FK extends 'key'
+    ? FV extends K
+      ? // @ts-expect-error: because the type infer is not clever enough, FV here should be one of K
+        EnumItemClass<T[FV], FV, FindValueByKey<T, FV>>
+      : EnumItemClass<T[K], K, V> | undefined
+    : FK extends 'value'
+      ? FV extends V
+        ? // @ts-expect-error: because the type infer is not clever enough, FV here should be one of V
+          EnumItemClass<T[FindEnumKeyByValue<T, FV>], FindEnumKeyByValue<T, FV>, FV>
+        : EnumItemClass<T[K], K, V> | undefined
+      : FK extends 'label'
+        ? EnumItemClass<T[K], K, V> | undefined
+        : // @ts-expect-error: because the type infer is not clever enough, FK here should be one of keyof Raw
+          FV extends T[keyof T][FK]
+          ? // @ts-expect-error: because the type infer is not clever enough, FV here should be one of T[keyof T][FK]
+            EnumItemClass<T[FindKeyByMeta<T, FK, FV>], FindKeyByMeta<T, FK, FV>, FindValueByMeta<T, FK, FV>>
+          : EnumItemClass<T[K], K, V> | undefined {
+    return this.find((item) => {
+      if (field === 'key' || field === 'value') {
+        return item[field as keyof typeof item] === value;
+      } else if (field === 'label') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (item.raw as any)?.label === value || item.label === value;
+      } else {
+        // For other fields, use the raw object to find
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (item.raw as any)?.[field] === value;
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }) as any;
+  }
+
   toList(): ListItem<V, 'value', 'label'>[];
   toList<
     FOV extends string | ((item: EnumItemClass<T[K], K, V>) => string),
@@ -341,6 +383,37 @@ export interface IEnumItems<
    */
   has(keyOrValue?: string | V): boolean;
 
+  /**
+   * **EN:** Find an enumeration item by key or value, or by custom meta fields
+   *
+   * **CN:** 通过key或value查找枚举项，或通过自定义元字段查找
+   *
+   * @param field The field to search by | 要查找的字段
+   * @param value The value to search | 要查找的值
+   *
+   * @returns The found enumeration item or undefined if not found | 找到的枚举项，如果未找到则返回 undefined
+   */
+  findBy<FK extends 'key' | 'value' | 'label' | Exclude<keyof T[keyof T], 'key' | 'value' | 'label'>, FV>(
+    field: FK,
+    value: FV
+  ): FK extends 'key'
+    ? FV extends K
+      ? // @ts-expect-error: because the type infer is not clever enough, FV here should be one of K
+        EnumItemClass<T[FV], FV, FindValueByKey<T, FV>>
+      : EnumItemClass<T[K], K, V> | undefined
+    : FK extends 'value'
+      ? FV extends V
+        ? // @ts-expect-error: because the type infer is not clever enough, FV here should be one of V
+          EnumItemClass<T[FindEnumKeyByValue<T, FV>], FindEnumKeyByValue<T, FV>, FV>
+        : EnumItemClass<T[K], K, V> | undefined
+      : FK extends 'label'
+        ? EnumItemClass<T[K], K, V> | undefined
+        : // @ts-expect-error: because the type infer is not clever enough, FK here should be one of keyof Raw
+          FV extends T[keyof T][FK]
+          ? // @ts-expect-error: because the type infer is not clever enough, FV here should be one of T[keyof T][FK]
+            EnumItemClass<T[FindKeyByMeta<T, FK, FV>], FindKeyByMeta<T, FK, FV>, FindValueByMeta<T, FK, FV>>
+          : EnumItemClass<T[K], K, V> | undefined;
+
   /**
    * - **EN:** Generate an object array containing all enumeration items
    * - **CN:** 生成一个对象数组，包含所有的枚举项
diff --git a/src/enum.ts b/src/enum.ts
@@ -201,7 +201,8 @@ export type IEnum<
      * - **EN:** A boolean value indicates that this is an Enum.
      * - **CN:** 布尔值，表示这是一个枚举类
      */
-    [IS_ENUM]: true;
+    // this flag exists but is removed from interface, as it's replaced with isEnum method
+    // [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>;
diff --git a/src/index.ts b/src/index.ts
@@ -8,6 +8,8 @@ export type {
   MenuItemOption,
   ColumnFilterItem,
   FindEnumKeyByValue,
+  FindValueByKey,
+  FindLabelByValue,
   ArrayToMap,
 } from './types';
 export type { LocalizeInterface } from './localize-interface';
diff --git a/src/types.ts b/src/types.ts
@@ -174,6 +174,35 @@ export type FindLabelByValue<T, V extends EnumValue, RAW = T[FindEnumKeyByValue<
   ? string
   : FindEnumKeyByValue<T, V>;
 
+/**
+ * - **EN:** Find the value of the enumeration item by key
+ * - **CN:** 通过key查找枚举项的值
+ *
+ * @template T Enum collection initialization data type | 枚举集合初始化数据的类型
+ * @template K Enum key type | 枚举key的类型
+ */
+export type FindValueByKey<T, K extends EnumKey<T>> = T[K] extends EnumValue
+  ? T[K]
+  : T[K] extends StandardEnumItemInit<infer V>
+    ? V
+    : T[K] extends ValueOnlyEnumItemInit<infer V>
+      ? V
+      : T[K] extends LabelOnlyEnumItemInit
+        ? K
+        : T[K] extends CompactEnumItemInit
+          ? K
+          : T[K] extends undefined
+            ? K
+            : never;
+
+export type FindKeyByMeta<T, MK extends keyof T[keyof T], MV> = {
+  [K in keyof T]: T[K] extends Record<MK, MV> ? K : never;
+}[keyof T];
+
+export type FindValueByMeta<T, MK extends keyof T[keyof T], MV> = {
+  [K in keyof T]: T[K] extends Record<MK, MV> ? T[K][MK] : never;
+}[keyof T];
+
 export type PrimitiveOf<T> = T extends string
   ? string
   : T extends number
diff --git a/test/test-suites/enum-collection.ts b/test/test-suites/enum-collection.ts
@@ -63,6 +63,10 @@ const testEnumCollection = (engine: TestEngineBase) => {
         engine.expect(week.label(1)).toBe(week.items.label(1));
         engine.expect(week.key(1)).toBe(week.items.key(1));
         engine.expect(week.has(1)).toBe(week.items.has(1));
+        engine.expect(week.findBy('key', 'Monday')).toBe(week.items.findBy('key', 'Monday'));
+        engine.expect(week.findBy('value', 1)).toBe(week.items.findBy('value', 1));
+        engine.expect(week.findBy('label', 'weekday.monday')).toBe(week.items.findBy('label', 'weekday.monday'));
+        engine.expect(week.findBy('status', 'success')).toBe(week.items.findBy('status', 'success'));
         engine.expect(week.raw()).toBe(week.items.raw());
         engine.expect(week.toList()).toEqual(week.items.toList());
         engine.expect(week.toMenu()).toEqual(week.items.toMenu());
@@ -166,7 +170,7 @@ const testEnumCollection = (engine: TestEngineBase) => {
       ({ 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);
+        engine.expect(IS_ENUM_IN_NODE in week && 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);
       }
diff --git a/test/test-suites/enum-items.ts b/test/test-suites/enum-items.ts
@@ -54,6 +54,38 @@ export function addEnumValuesTestSuite(engine: TestEngineBase) {
     }
   );
 
+  engine.test(
+    'enums.find should be able to find enum item by key, value or custom meta fields',
+    ({ EnumPlus: { Enum }, WeekConfig: { StandardWeekConfig, WeekCompactConfig } }) => {
+      const weekEnum = Enum(StandardWeekConfig);
+      const compactWeekEnum = Enum(WeekCompactConfig);
+      return { weekEnum, compactWeekEnum };
+    },
+    ({ weekEnum, compactWeekEnum }) => {
+      engine.expect(weekEnum.findBy('key', 'Monday')).toBe(weekEnum.items[1]);
+      engine.expect(weekEnum.findBy('key', 'Saturday')).toBe(weekEnum.items[6]);
+      engine.expect(weekEnum.findBy('key', 'Invalid Key')).toBe(undefined);
+      engine.expect(weekEnum.findBy('value', 1)).toBe(weekEnum.items[1]);
+      engine.expect(weekEnum.findBy('value', 6)).toBe(weekEnum.items[6]);
+      engine.expect(weekEnum.findBy('value', 99)).toBe(undefined);
+      engine.expect(weekEnum.findBy('label', 'weekday.monday')).toBe(weekEnum.items[1]);
+      engine.expect(weekEnum.findBy('label', 'weekday.saturday')).toBe(weekEnum.items[6]);
+      engine.expect(weekEnum.findBy('label', 'Invalid Label')).toBe(undefined);
+      engine.expect(compactWeekEnum.findBy('key', 'Monday')).toBe(compactWeekEnum.items[1]);
+      engine.expect(compactWeekEnum.findBy('key', 'Invalid Key')).toBe(undefined);
+      engine.expect(compactWeekEnum.findBy('value', 1)).toBe(undefined);
+      engine.expect(compactWeekEnum.findBy('value', 99)).toBe(undefined);
+      engine.expect(compactWeekEnum.findBy('label', 'weekday.monday')).toBe(undefined);
+
+      // Custom meta field
+      engine.expect(weekEnum.findBy('status', 'error')).toEqual(weekEnum.items[0]);
+      engine.expect(weekEnum.findBy('status', 'warning')).toEqual(weekEnum.items[1]);
+      engine.expect(weekEnum.findBy('status', 'success')).toEqual(weekEnum.items[3]);
+      engine.expect(weekEnum.findBy('status', 'invalid')).toEqual(undefined);
+      engine.expect(compactWeekEnum.findBy('status' as 'key', 'success')).toEqual(undefined);
+    }
+  );
+
   engine.test(
     'enums.toList should generate an object array',
     ({ EnumPlus: { Enum }, WeekConfig: { StandardWeekConfig, locales } }) => {
diff --git a/test/utils/serialize-javascript.ts b/test/utils/serialize-javascript.ts
@@ -7,17 +7,17 @@
  *    reference can't. If it's a class, set the closures to the class properties, and use 'this' to
  *    access them. If it's a normal function, set the closures to the function reference, and use
  *    the function name to access them.
- * 2. Do not use `function.bind`, because the bound function body is hidden. The `toString` method just
- *    returns `[native code]`.
- * 3. Do not use anonymous Symbols in both object keys and values. Use system predefined Symbols
+ * 2. Do not use anonymous Symbols in both object keys and values. Use system predefined Symbols
  *    instead or use `Symbol.for` to create a Symbol. The anonymous Symbols can't be serialized and
  *    event cannot be created.
- * 4. No direct or indirect circular references are allowed.
- * 5. For classes, should avoid private properties and methods, because they are not accessible from
+ * 3. No direct or indirect circular references are allowed.
+ * 4. For classes, should avoid private properties and methods, because they are not accessible from
  *    outside and can't be serialized. Please use a normal property or method instead, and starts
  *    with `_` to indicate it's a private member. If you are using TypeScript, you can use the
  *    `private` keyword to declare as private, which looks a little better.
- * 6. Class constructors will be dropped.
+ * 5. Class constructors will be dropped.
+ * 6. All native methods will be dropped, as `toString` method just returns `[native code]`.
+ * 7. Do not use `function.bind`, because the bound functions become native methods.
  */
 
 const TokenStart = '$SJS$';
@@ -287,8 +287,9 @@ function getDeserializeJavascriptCode(result: SerializedResult, options: Interna
   patches.forEach(({ path, context }) => {
     const sourceObj = path?.length ? get(deserializeResult, path) : deserializeResult;
     if (sourceObj) {
+      const sourceKeys = getFullKeys(sourceObj);
       getFullKeys(context).forEach((key) => {
-        if (sourceObj[key] == null) {
+        if (!sourceKeys.includes(key) || sourceObj[key] == null) {
           sourceObj[key] = context[key];
         }
       });
