feat: implement enum.values and enum.labels

Author: shijistar

CHANGELOG.md

@@ -53,6 +53,9 @@ 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_ITEM` symbol is renamed to `IS_ENUM_ITEM`.
+- `ENUM_ITEMS` symbol is renamed to `IS_ENUM_ITEMS`.
 - `EnumValuesArray` interface is renamed to `EnumItemsArray`.
 - `IEnumValues` interface is renamed to `IEnumItems`.
 

e2e/specs/enum-values.spec.ts

@@ -1,4 +1,4 @@
 import playwright from '../../test/engines/playwright';
-import testEnumValues from '../../test/test-suites/enum-values';
+import testEnumValues from '../../test/test-suites/enum-items';
 
 testEnumValues(playwright);

enum-plus-v3.md

@@ -8,12 +8,15 @@
 - [x] Remove deprecated `enum.menus`
 - [x] Remove deprecated `enum.filters`
 - [x] Remove deprecated `enum.valuesEnum`
-- [ ] Change the behavior of `enum.values`, now it returns an array of the member raw values. Use `enum.items` for the old behavior.
-- [ ] Add `enum.labels` property, which returns an readonly array of the member labels.
+- [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).
 - [ ] 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`.
+<!-- - [ ] 增加isEnum方法，为instanceof增加断言 -->
+- [ ] Add `Enum.isEnum` method to check if an object is an instance of `Enum`.
+- [ ] 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.

jest.config.js

@@ -7,7 +7,7 @@ module.exports = {
   collectCoverage: true,
   collectCoverageFrom: ['src/**/*.{ts,tsx}'],
   coverageReporters: ['json', 'lcov', 'text', 'clover'],
-  coveragePathIgnorePatterns: ['src/types.ts', 'src/localize-interface.ts', 'src/extension.ts'],
+  coveragePathIgnorePatterns: ['src/types.ts', 'src/localize-interface.ts', 'src/extension.d.ts'],
   moduleNameMapper: {
     '^@enum-plus/(.*)$': '<rootDir>/src/$1',
     '^@enum-plus': '<rootDir>/src',

package.json

@@ -115,8 +115,8 @@
   ],
   "scripts": {
     "build": "run-p build:*",
-    "build:es": "run-s task:build-es task:add-umd-banner task:add-es-extensions",
-    "build:es-legacy": "cross-env LEGACY=1 run-s task:build-es-legacy task:add-umd-banner task:add-es-legacy-extensions",
+    "build:es": "run-s task:build-es task:update-es-enum task:add-es-extensions task:add-umd-banner",
+    "build:es-legacy": "cross-env LEGACY=1 run-s task:build-es-legacy task:update-es-legacy-enum task:add-umd-banner task:add-es-legacy-extensions",
     "build:lib": "run-s ts2lib task:copy-lib task:copy-dts task:types-legacy",
     "build:tses": "run-s ts2es task:add-tses-extensions",
     "e2e": "run-s task:bundle-e2e task:run-e2e",
@@ -141,6 +141,10 @@
     "task:run-e2e-debug": "playwright test --debug",
     "task:run-e2e-ui": "playwright test --ui",
     "task:types-legacy": "tsx scripts/gen-legacy-type.ts",
+    "task:update-es-enum": "tsx scripts/update-enum-ts.ts es",
+    "task:update-es-legacy-enum": "tsx scripts/update-enum-ts.ts es-legacy",
+    "task:update-lib-enum": "tsx scripts/update-enum-ts.ts lib",
+    "task:update-tses-enum": "tsx scripts/update-enum-ts.ts tses",
     "test": "npm run task:jest",
     "test-all": "run-s task:jest test-node-cjs test-node-esm e2e",
     "test-node-cjs": "run-s ts2lib task:jest-cjs",

scripts/update-enum-ts.ts

@@ -0,0 +1,22 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const directory = process.argv[2];
+/*
+ * This script adds .js extensions to `import` paths in output javascript files.
+ *
+ * Have tried the babel-plugin-add-import-extension plugin, but encountered "Maximum call stack size exceeded" error.
+ * So changed to a post-build processing approach instead.
+ */
+
+if (directory) {
+  processEnumTs(directory);
+}
+
+function processEnumTs(dir: string) {
+  const enumPath = join(dir, 'enum.d.ts');
+  let content = readFileSync(enumPath, 'utf8');
+  content = content.replace(/\/\/\/ <reference types=["']([^"']+)["'] \/>/g, '').trimStart();
+  content = `import './extension';\n` + content;
+  writeFileSync(enumPath, content);
+}

src/enum-collection.ts

@@ -17,7 +17,8 @@ import type {
   StandardEnumItemInit,
   ValueTypeFromSingleInit,
 } from './types';
-import { ENUM_COLLECTION, ITEMS, KEYS } from './utils';
+import type { IS_ENUM_ITEMS } from './utils';
+import { IS_ENUM_COLLECTION, ITEMS, KEYS, LABELS, VALUES } from './utils';
 
 /**
  * - **EN:** Enum collection extension base class, used to extend the Enums
@@ -41,16 +42,16 @@ export class EnumCollectionClass<
     V extends EnumValue = ValueTypeFromSingleInit<T[K], K>,
   >
   extends EnumExtensionClass<T, K, V>
-  implements IEnumItems<T, K, V>
+  implements Omit<IEnumItems<T, K, V>, typeof IS_ENUM_ITEMS>
 {
-  private _options: EnumItemOptions | undefined;
+  private __options__: EnumItemOptions | undefined;
   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;
+  readonly [IS_ENUM_COLLECTION] = 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(
@@ -69,45 +70,65 @@ export class EnumCollectionClass<
    *   set.
    */
   get name(): string | undefined {
-    const localize = this._options?.localize ?? localizer.localize;
+    const localize = this.__options__?.localize ?? localizer.localize;
     if (typeof localize === 'function') {
-      return localize(this._options?.name);
+      return localize(this.__options__?.name);
     }
-    return this._options?.name;
+    return this.__options__?.name;
   }
 
   constructor(init: T = {} as T, options?: EnumItemOptions) {
     super();
-    this._options = options;
+    this.__options__ = options;
+
+    // Generate keys array
     // exclude number keys with a "reverse mapping" value, it means those "reverse mapping" keys of number enums
     const keys = Object.keys(init).filter(
       (k) => !(/^-?\d+$/.test(k) && k === `${init[init[k as K] as K] ?? ''}`)
     ) as K[];
     const parsed = keys.map((key) => parseEnumItem<EnumItemInit<V>, K, V>(init[key], key));
     keys.forEach((key, index) => {
       const { value } = parsed[index];
-      // @ts-expect-error: because of dynamically define property
+      // @ts-expect-error: because of dynamic property
       this[key] = value;
     });
     Object.freeze(keys);
     // @ts-expect-error: because use KEYS to avoid naming conflicts in case of 'keys' field name is taken
     this[Object.keys(init).some((k) => k === 'keys') ? KEYS : 'keys'] = keys;
 
-    // Build enum item data
+    // Generate values array
+    const values = parsed.map((item) => item.value);
+    Object.freeze(values);
+    // @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'] = values;
+
+    // Generate enum items array
     const items = new EnumItemsArray<T, K, V>(
       init,
-      this._options,
+      this.__options__,
       ...keys.map((key, index) => {
         const { value, label } = parsed[index];
-        return new EnumItemClass<T[K], K, V>(key, value, label, init[key], this._options);
+        return new EnumItemClass<T[K], K, V>(key, value, label, init[key], this.__options__);
       })
     );
+    Object.freeze(items);
     // @ts-expect-error: because use ITEMS to avoid naming conflicts in case of 'items' field name is taken
     this[Object.keys(init).some((k) => k === 'items') ? ITEMS : 'items'] = items;
 
+    // Generate labels array
+    Object.defineProperty(this, Object.keys(init).some((k) => k === 'labels') ? LABELS : 'labels', {
+      enumerable: true,
+      configurable: false,
+      get: () => {
+        // Cannot save to static array because labels may be localized contents
+        // Should not use `items` in the closure because the getter function cannot be fully serialized
+        return ((this as unknown as { [ITEMS]: EnumItemsArray<T, K, V> })[ITEMS] ?? this.items).map(
+          (item) => item.label
+        );
+      },
+    });
+
     Object.freeze(this);
-    Object.freeze(this.items);
-    Object.freeze(this.keys);
   }
 
   label<KV extends V | K | NonNullable<PrimitiveOf<V>> | NonNullable<PrimitiveOf<K>> | undefined>(keyOrValue: KV) {

src/enum-item.ts

@@ -1,6 +1,6 @@
 import { localizer } from './localize';
 import type { EnumItemInit, EnumKey, EnumValue, LocalizeInterface, ValueTypeFromSingleInit } from './types';
-import { ENUM_ITEM } from './utils';
+import { IS_ENUM_ITEM } from './utils';
 
 /**
  * Enum item class
@@ -44,7 +44,7 @@ export class EnumItemClass<
    * - **EN:** A boolean value indicates that this is an enum item instance.
    * - **CN:** 布尔值，表示这是一个枚举项实例
    */
-  readonly [ENUM_ITEM] = true;
+  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.
@@ -120,8 +120,8 @@ export class EnumItemClass<
         enumerable: true,
         configurable: false,
       },
-      [ENUM_ITEM]: {
-        value: this[ENUM_ITEM],
+      [IS_ENUM_ITEM]: {
+        value: this[IS_ENUM_ITEM],
         writable: false,
         enumerable: true,
         configurable: false,

src/enum-items.ts

@@ -12,7 +12,7 @@ import type {
   ValueMap,
   ValueTypeFromSingleInit,
 } from './types';
-import { ENUM_ITEMS } from './utils';
+import { IS_ENUM_ITEMS } from './utils';
 
 /**
  * Enum items array, mostly are simple wrappers for EnumCollectionClass
@@ -33,12 +33,12 @@ export class EnumItemsArray<
   extends Array<EnumItemClass<T[K], K, V>>
   implements IEnumItems<T, K, V>
 {
-  private _raw: T;
+  private __raw__: T;
   /**
    * - **EN:** A boolean value indicates that this is an enum items array.
    * - **CN:** 布尔值，表示这是一个枚举项数组
    */
-  readonly [ENUM_ITEMS] = true;
+  readonly [IS_ENUM_ITEMS] = true;
 
   /**
    * Instantiate an enum items array
@@ -50,7 +50,7 @@ export class EnumItemsArray<
    */
   constructor(raw: T, options: EnumItemOptions | undefined, ...items: EnumItemClass<T[K], K, V>[]) {
     super(...items);
-    this._raw = raw;
+    this.__raw__ = raw;
   }
 
   label<KV extends V | K | NonNullable<PrimitiveOf<V>> | NonNullable<PrimitiveOf<K>> | undefined>(
@@ -99,11 +99,11 @@ export class EnumItemsArray<
   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;
+      return this.__raw__;
     } else {
-      if (Object.keys(this._raw).some((k) => k === (value as string))) {
+      if (Object.keys(this.__raw__).some((k) => k === (value as string))) {
         // Find by key
-        return this._raw[value as K];
+        return this.__raw__[value as K];
       }
       // Find by value
       const itemByValue = this.find((i) => i.value === value);
@@ -215,6 +215,11 @@ export interface IEnumItems<
   K extends EnumKey<T> = EnumKey<T>,
   V extends EnumValue = ValueTypeFromSingleInit<T[K], K>,
 > {
+  /**
+   * - **EN:** A boolean value indicates that this is an enum items array.
+   * - **CN:** 布尔值，表示这是一个枚举项数组
+   */
+  [IS_ENUM_ITEMS]: true;
   /**
    * - **EN:** The enum collection name, supports localization.
    *

src/enum.ts

@@ -12,7 +12,7 @@ import type {
   LocalizeInterface,
   ValueTypeFromSingleInit,
 } from './types';
-import type { ITEMS, KEYS } from './utils';
+import type { IS_ENUM_COLLECTION, ITEMS, KEYS, LABELS, VALUES } from './utils';
 
 export interface EnumInterface {
   /**
@@ -118,6 +118,12 @@ export type IEnum<
   V extends EnumValue = ValueTypeFromSingleInit<T[K], K>,
 > = IEnumItems<T, K, V> &
   EnumExtension<T, K, V> & {
+    /**
+     * - **EN:** A boolean value indicates that this is an enum collection instance.
+     * - **CN:** 布尔值，表示这是一个枚举集合实例
+     */
+    [IS_ENUM_COLLECTION]: true;
+  } & {
     // Add enum item values, just like native enums
     [key in K]: ValueTypeFromSingleInit<T[key], key, T[K] extends number | undefined ? number : key>;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -165,6 +171,52 @@ export type IEnum<
          * > 仅支持 `ReadonlyArray<T>` 中的只读方法，不支持push、pop等任何修改的方法
          */
         readonly keys: K[];
+      }) &
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (T extends { values: any }
+    ? {
+        /**
+         * - **EN:** Alias for the `values` array, when any enum key conflicts with `values`, you can
+         *   access all enum values through this alias
+         * - **CN:** `values`数组的别名，当任何枚举的key与`values`冲突时，可以通过此别名访问所有枚举项的values
+         */
+        readonly [VALUES]: V[];
+      }
+    : {
+        /**
+         * - **EN:** Get all values of the enumeration items as an array
+         *
+         * > Only supports read-only methods in `ReadonlyArray<T>`, does not support push, pop, and
+         * > any modification methods
+         *
+         * - **CN:** 获取枚举项的全部values列表
+         *
+         * > 仅支持 `ReadonlyArray<T>` 中的只读方法，不支持push、pop等任何修改的方法
+         */
+        readonly values: V[];
+      }) &
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (T extends { labels: any }
+    ? {
+        /**
+         * - **EN:** Alias for the `labels` array, when any enum key conflicts with `labels`, you can
+         *   access all enum labels through this alias
+         * - **CN:** `labels`数组的别名，当任何枚举的key与`labels`冲突时，可以通过此别名访问所有枚举项的labels
+         */
+        readonly [LABELS]: string[];
+      }
+    : {
+        /**
+         * - **EN:** Get all labels of the enumeration items as an array
+         *
+         * > Only supports read-only methods in `ReadonlyArray<T>`, does not support push, pop, and
+         * > any modification methods
+         *
+         * - **CN:** 获取枚举项的全部labels列表
+         *
+         * > 仅支持 `ReadonlyArray<T>` 中的只读方法，不支持push、pop等任何修改的方法
+         */
+        readonly labels: string[];
       });
 
 export const Enum = (<