feat: enhance raw method typing in enums, bump to 2.2.10

Author: shijistar

CHANGELOG.md

@@ -2,19 +2,25 @@
 
 # enum-plus Changelog
 
-## Unreleased
+## 2.2.10
+
+2025-5-14
 
 ### Features
 
--
+- ✨ Enhance the type inference of the `raw` method. When the input value matches a specific enum item, it only returns the raw object of that enum item instead of returning the raw objects of all enum items.
+
+### Bug Fixes
+
+- 🐞 The output `lib` directory structure is incorrect. This will break legacy Node.js applications using the `CommonJS` module spec, while modern Node.js applications using the `NodeNext` module spec remain unaffected. This issue was introduced in `v2.2.7`. For node.js applications, it's strongly recommended to upgrade.
 
 ## 2.2.9
 
 2025-4-20
 
 ### Features
 
-- 🛠 emit a warning while trying to modify an `EnumItem`
+- 🛠 Emit a warning while trying to modify an `EnumItem`
 
 ### Bug Fixes
 
@@ -26,7 +32,7 @@
 
 ### Bug Fixes
 
-- 🐞 fix `exports` configuration for moduleResolution `ESNext`
+- 🐞 Fix `exports` configuration for moduleResolution `ESNext`
 
 ## 2.2.7
 
@@ -62,7 +68,7 @@
 
 ### Features
 
-- 🛠 supports global type extension for enum localization keys, providing better editor intelligence awareness
+- 🛠 Support global type extension for enum localization keys, providing better editor intelligence awareness
 
 ## 2.2.3
 
@@ -78,97 +84,97 @@
 
 ### Features
 
-- 🛠 change the return type of `Enum.options.getKey`
-- 📖 update docs
+- 🛠 Change the return type of `Enum.options.getKey`
+- 📖 Update docs
 
 ## 2.2.1
 
 2025-2-10
 
-- 📖 update docs
+- 📖 Update docs
 
 ## 2.2.0
 
 2025-2-9
 
 ### Features
 
-- 🔥 support initializing Enum with native enums
-- 🔥 adds `items` array, deprecated the _`values`_ array. Reduces package size.
+- 🔥 Support initializing Enum with native enums
+- 🔥 Add `items` array, deprecated the _`values`_ array. Reduces package size.
 
 ## 2.1.1
 
 2025-2-8
 
 ### Bug Fixes
 
-- 🐞 fix typing error in `EnumExtension` interface
+- 🐞 Fix typing error in `EnumExtension` interface
 
 ## 2.1.0
 
 2025-2-8
 
-> **Note:** this version has a typing issue, please use `v2.1.1`
+> **Note:** This version has a typing issue, please use `v2.1.1`
 
 ### Features
 
-- 🔥 add `toSelect` method, deprecated the _`options`_ method
-- 🔥 add `toMenu` method, deprecated the _`menus`_ method
-- 🔥 add `toFilter` method, deprecated the _`filters`_ method
-- 🔥 add `toValueMap` method, the _`valuesEnum`_ method
-- 🔥 support global extension, custom methods can be added to Enums
+- 🔥 Add `toSelect` method, deprecated the _`options`_ method
+- 🔥 Add `toMenu` method, deprecated the _`menus`_ method
+- 🔥 Add `toFilter` method, deprecated the _`filters`_ method
+- 🔥 Add `toValueMap` method, the _`valuesEnum`_ method
+- 🔥 Support global extension, custom methods can be added to Enums
 
 ## 2.0.3
 
 2025-2-6
 
 ### Features
 
-- 🛠 downgrade EcmaScript version to `ES2015`
+- 🛠 Downgrade EcmaScript version to `ES2015`
 
 ## 2.0.2
 
 2025-2-3
 
 ### Features
 
-- 🔥 the `firstOption` of `options` method supports localization
+- 🔥 The `firstOption` of `options` method supports localization
 
 ## 2.0.1
 
 2025-2-2
 
 ### Features
 
-- 🔥 support for enum text localization
+- 🔥 Support for enum text localization
   - the `Enum` method now accepts a `localize` option that can be used to localize the enum text
   - you can also set the `Enum.localize` static method to localize all enums in a lower priority
-- 🔥 add `menus` method
+- 🔥 Add `menus` method
 
 ### Breaking Changes
 
-- 💣 all parameters after the first of the `Enum` method has been changed to an `options` object
+- 💣 All parameters after the first of the `Enum` method has been changed to an `options` object
 
 ## 1.0.3
 
 2023-11-14
 
-- 🛠 if an enum is created from array, both the `enum.raw` or `enumItem.raw` methods return the original array item
+- 🛠 Both the `enum.raw` or `enumItem.raw` methods return the original array item, if an enum is created from array,
 
 ## 1.0.2
 
 2023-07-31
 
-- 🆕 added `rawType` accessor
+- 🆕 Add `rawType` accessor
 
 ## 1.0.1
 
 2023-03-09
 
-- 🆕 added a new `filters` method that returns an array of enumerated items that can be passed directly to the `Column.filters` of the AntDesign Table component as a list of filtered items for the column
+- 🆕 Add a new `filters` method that returns an array of enumerated items that can be passed directly to the `Column.filters` of the AntDesign Table component as a list of filtered items for the column
 
 - ## 1.0.0
 
 2022-10-08
 
-- 🆕 the first release of `enum-plus` library
+- 🆕 The first release of `enum-plus` library

package.json

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

src/enum-collection.ts

@@ -9,6 +9,7 @@ import type {
   EnumItemOptions,
   EnumKey,
   EnumValue,
+  FindEnumKeyByValue,
   IEnumValues,
   MenuItemOption,
   ObjectFirstOptionConfig,
@@ -157,11 +158,13 @@ export class EnumCollectionClass<
   }
 
   raw(): T;
-  raw(keyOrValue: V | K): T[K];
-  raw(value: unknown): T[K] | undefined;
-  raw(value?: unknown): T | T[K] | undefined {
-    if (value !== undefined) {
-      return this.items.raw(value);
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  raw<IK extends V | K | Exclude<EnumValue, string> | (string & {})>(
+    keyOrValue: IK
+  ): IK extends K ? T[IK] : IK extends V ? T[FindEnumKeyByValue<T, IK>] : T[K] | undefined;
+  raw<IK extends EnumValue>(value?: IK | unknown): T | T[K] | T[FindEnumKeyByValue<T, IK>] | undefined {
+    if (value != null) {
+      return this.items.raw(value as keyof T | EnumValue) as T[K];
     } else {
       return this.items.raw();
     }

src/enum-values.ts

@@ -9,6 +9,7 @@ import type {
   EnumItemOptions,
   EnumKey,
   EnumValue,
+  FindEnumKeyByValue,
   IEnumValues,
   MenuItemOption,
   ObjectFirstOptionConfig,
@@ -155,9 +156,11 @@ export class EnumValuesArray<
   }
 
   raw(): T;
-  raw(keyOrValue: V | K): T[K];
-  raw(value: unknown): T[K] | undefined;
-  raw(value?: V | K): T | T[K] | undefined {
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  raw<IK extends V | K | Exclude<EnumValue, string> | (string & {})>(
+    keyOrValue: IK
+  ): IK extends K ? T[IK] : IK extends V ? T[FindEnumKeyByValue<T, IK>] : T[K] | undefined;
+  raw<IK extends EnumValue>(value?: IK | unknown): T | T[K] | T[FindEnumKeyByValue<T, IK>] | undefined {
     if (value == null) {
       // Return the original initialization object
       return this.#raw;

src/types.ts

@@ -307,10 +307,10 @@ export interface IEnumValues<
    *
    * @param keyOrValue Enum key or value | 枚举key或value
    */
-  // eslint-disable-next-line @typescript-eslint/method-signature-style
-  raw(keyOrValue: V | K): T[K];
-  // eslint-disable-next-line @typescript-eslint/method-signature-style
-  raw(value: unknown): T[K] | undefined;
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  raw<IK extends V | K | Exclude<EnumValue, string> | (string & {})>(
+    keyOrValue: IK
+  ): IK extends K ? T[IK] : IK extends V ? T[FindEnumKeyByValue<T, IK>] : T[K] | undefined;
 
   /**
    * **EN:** The data type of all enumeration values
@@ -553,3 +553,24 @@ export type ValueTypeFromEnumInit<T, K extends EnumKey<T> = EnumKey<T>> =
                   : T extends OmitEnumInit<K> // format: {foo: undefined, bar: undefined}
                     ? K
                     : K; // Unknown format, use key as value
+
+export type FindEnumKeyByValue<T, V extends EnumValue> = {
+  // ValueOnly { foo:1, bar:2 }
+  [K in keyof T]: T[K] extends V
+    ? K
+    : // Standard: { foo:{ value:1 }, bar:{ value:2 } }
+      // @ts-expect-error: because need to force check T[K]['value'], event value field does not exist
+      T[K]['value'] extends V
+      ? K
+      : // LabelOnly: { foo:{ label: 'foo' }, bar:{ label: 'bar' } }
+        object extends T[K]
+        ? K extends V
+          ? K
+          : never
+        : // KeyOnly: { foo: undefined, bar: undefined }
+          undefined extends T[K]
+          ? K extends V
+            ? K
+            : never
+          : never;
+}[keyof T];