feat: enhance UMD module support with legacy version and update build scripts

Author: shijistar

.fatherrc.ts

@@ -1,9 +1,16 @@
 import { defineConfig } from 'father';
 
+const legacy = process.env.LEGACY === '1';
 export default defineConfig({
-  esm: { input: 'src', output: 'es', transformer: 'babel' },
-  umd: { entry: 'src', output: 'umd' },
+  esm: { input: 'src', output: legacy ? 'es-legacy' : 'es', transformer: 'babel' },
+  umd: {
+    entry: 'src',
+    name: 'EnumPlus',
+    output: {
+      path: 'umd',
+      filename: legacy ? 'enum-plus-legacy.min' : 'enum-plus.min',
+    },
+  },
   sourcemap: true,
-  targets: { chrome: 80 },
-  plugins: ['./scripts/plugin-legacy-mode.ts'],
+  targets: legacy ? { ie: 11 } /* ES2015 */ : { chrome: 80 } /* ES2020 */,
 });

.github/actions/replace-url/action.yml …thub/actions/replace-path-url/action.yml.github/actions/replace-url/action.yml renamed to .github/actions/replace-path-url/action.yml .github/actions/replace-url/action.yml renamed to .github/actions/replace-path-url/action.yml

@@ -43,25 +43,35 @@ jobs:
         run: |
           cp -r umd/ umd-zip/
           mv umd-zip/enum-plus.min.js umd-zip/enum-plus.umd.min.js
+          mv umd-zip/enum-plus-legacy.min.js umd-zip/enum-plus-legacy.umd.min.js
           gzip -9 umd-zip/enum-plus.umd.min.js
+          gzip -9 umd-zip/enum-plus-legacy.umd.min.js
           cp -r umd/ umd-zip-full/
-          cd umd-zip-full
-          tar -cvf ../enum-plus.umd.tar.gz *
-          cd ..
+          mkdir -p umd-zip-full/modern
+          mkdir -p umd-zip-full/legacy
+          mv umd-zip-full/enum-plus.min.js* umd-zip-full/modern
+          mv umd-zip-full/enum-plus-legacy.min.js* umd-zip-full/legacy
+          cd umd-zip-full/modern
+          tar -cvf ../../enum-plus.umd.tar.gz *
+          cd ../legacy
+          tar -cvf ../../enum-plus-legacy.umd.tar.gz *
+          cd ../..
 
       - name: Add Assets to Release
         uses: softprops/action-gh-release@v1
         with:
           files: |
             umd-zip/enum-plus.umd.min.js.gz
+            umd-zip/enum-plus-legacy.umd.min.js.gz
             enum-plus.umd.tar.gz
+            enum-plus-legacy.umd.tar.gz
           token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Replace relative image url to cdn.jsdelivr.net
         uses: ./.github/actions/replace-img-url
 
       - name: Replace download url to the releasing version
-        uses: ./.github/actions/replace-url
+        uses: ./.github/actions/replace-path-url
         with:
           version: ${{ github.event.release.tag_name }}
 
@@ -125,7 +135,7 @@ jobs:
 
       - name: Replace download url to the NPM latest version
         if: github.event.release.prerelease == false
-        uses: ./.github/actions/replace-url
+        uses: ./.github/actions/replace-path-url
         with:
           version: ${{ steps.get_latest_version_after_publish.outputs.LATEST_VERSION }}
 

.github/workflows/npm-publish.yml

@@ -14,7 +14,8 @@
 - 🔥 introduce an official plugin `enum-plus-plugin` that provides a collection of highly shareable plugins.
   - These plugins are designed to work in all scenarios and environments (including browser and Node.js), without introducing dependencies on third-party frameworks, component libraries, or platforms.
   - If you have a good idea that might be specific to a certain framework or platform rather than universally applicable, we recommend creating a new plugin project (e.g., `enum-plus-plugin-xxx`). We are happy to see that, and hope that you submit a PR to `enum-plus-plugin` to link your project back.
-- ✨ Includes the `UMD` module format in this release, which allows you to use `enum-plus` in a browser environment without the need for a module bundler. This is particularly useful for quick prototyping or when working with legacy codebases that do not support modern module systems. You can find them in the `umd` directory of the package. They can also be downloaded in [github release](https://github.com/shijistar/enum-plus/releases) assets.
+- ✨ Add the `UMD` module format in this release, which allows you to use `enum-plus` in a browser environment without the need for a module bundler. Two versions are provided: `enum-plus.min.js` (ES2020) for modern browsers and `enum-plus-legacy.min.js` (ES2015) for legacy browsers.
+  . This is particularly useful for quick prototyping or when working with legacy codebases that do not support modern module systems. You can find them in the `umd` directory of the package. They can also be downloaded in [github release](https://github.com/shijistar/enum-plus/releases) assets.
 
 ### Breaking Changes
 
@@ -26,6 +27,10 @@
   - `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`.
 
+### Bug Fixes
+
+- 🐞 Fix sourcemap resolution issues in CommonJS mode
+
 ## 2.3.0
 
 2025-5-23

CHANGELOG.md

@@ -19,7 +19,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/enum-plus.svg?color=007ec6&cacheSeconds=86400)](https://www.npmjs.com/package/enum-plus)
 ![GitHub License](https://img.shields.io/github/license/shijistar/enum-plus?label=License&color=%23F68F1E&cacheSeconds=86400)
 
-⬇️  [Introduction](#introduction) | [Features](#features) | [Installation](#installation) | [Enum Initialization](#enum-initialization) | [API](#api) | [Usage](#usage) | [Naming Conventions](#naming-convention-best-practices) | [Localization](#localization) | [Extensibility](#extensibility) | [Q&A](#qa)  ⬇️
+⬇️  [Introduction](#introduction) | [Features](#features) | [Installation](#installation) | [Enum Initialization](#enum-initialization) | [API](#api) | [Usage](#usage) | [Naming Conventions](#naming-convention-best-practices) | [Localization](#localization) | [Extensibility](#extensibility) | [Compatibility](#compatibility) | [Q&A](#qa)  ⬇️
 
 ## Introduction
 
@@ -78,19 +78,27 @@ yarn add enum-plus
 - The specific version:
 
 ```html
+<!-- ES2020 modern version -->
 <script src="https://cdn.jsdelivr.net/npm/enum-plus@v3.0.0/umd/enum-plus.min.js"></script>
+<!-- ES2015 legacy version -->
+<script src="https://cdn.jsdelivr.net/npm/enum-plus@v3.0.0/umd/enum-plus-legacy.min.js"></script>
 ```
 
 - The latest version:
 
 ```html
+<!-- ES2020 modern version -->
 <script src="https://cdn.jsdelivr.net/npm/enum-plus/umd/enum-plus.min.js"></script>
+<!-- ES2015 legacy version -->
+<script src="https://cdn.jsdelivr.net/npm/enum-plus/umd/enum-plus-legacy.min.js"></script>
 ```
 
 ⬇️ **Download**:
 
 - [enum-plus.umd.min.js.gz](https://github.com/shijistar/enum-plus/releases/download/v3.0.0/enum-plus.umd.min.js.gz) (~2kB gzipped)
 - [enum-plus.umd.tar.gz](https://github.com/shijistar/enum-plus/releases/download/v3.0.0/enum-plus.umd.tar.gz) (Full package with sourcemap)
+- [enum-plus-legacy.umd.min.js.gz](https://github.com/shijistar/enum-plus/releases/download/v3.0.0/enum-plus-legacy.umd.min.js.gz)
+- [enum-plus-legacy.umd.tar.gz](https://github.com/shijistar/enum-plus/releases/download/v3.0.0/enum-plus-legacy.umd.tar.gz)
 
 > You can also download them in [github release](https://github.com/shijistar/enum-plus/releases) assets
 
@@ -912,19 +920,27 @@ If you want to provide more friendly type hints in the extension methods, you ma
 
 ## Compatibility
 
-- **Browser Environments**:
+enum-plus is designed to be compatible with a wide range of environments, including modern browsers, Node.js, and various build tools. Below are the compatibility details for different environments:
 
-  - **Modern Bundlers**: With bundlers supporting the [exports](https://nodejs.org/api/packages.html#exports-sugar) field (Webpack 5+, Vite, Rollup), enum-plus targets `ES2020`. For broader browser support, transpile to earlier syntax using `@babel/preset-env` during your build process.
+### Browser Environments
 
-  - **Legacy Bundlers**: For tools without `exports` field support (like Webpack 4), enum-plus automatically falls back to the `main` field entry point, which targets `ES2016`.
+- **Modern Bundlers**: For bundlers supporting the [exports](https://nodejs.org/api/packages.html#exports-sugar) field (such as webpack 5+, vite, rollup), `es` directory is imported, which targets `ES2020`. For broader browser support, you can transpile to earlier syntax using `@babel/preset-env` during your build process.
 
-  - **Polyfill Strategy**: enum-plus ships without polyfills to minimize bundle size. For legacy browser support, incorporate:
+- **Legacy Bundlers**: For bundlers without [exports](https://nodejs.org/api/packages.html#exports-sugar) field support (like Webpack 4), this library automatically falls back to the `main` field entry point, and `es-legacy` directory is imported, which targets `ES2015`.
 
-    - `core-js`
-    - `@babel/preset-env` with appropriate `useBuiltIns` settings
-    - Alternative polyfill implementations
+- **UMD Version**: For direct browser usage or static projects without bundlers, enum-plus provides UMD version that can be included via a `<script>` tag. The `umd` directory contains two versions:
+  - `enum-plus.min.js`: Targets **`ES2020`**, suitable for modern browsers.
+  - `enum-plus-legacy.min.js`: Targets **`ES2015`**, suitable for older browsers.
 
-- **Node.js Compatibility**: enum-plus requires a minimum of `ES2016` features, compatible with Node.js `v7.x` and above.
+> **Polyfill Strategy**: enum-plus ships without polyfills to minimize bundle size. For legacy browser support, you can include the following tools as needed:
+>
+> - `core-js`
+> - `@babel/preset-env` with appropriate `useBuiltIns` settings
+> - Alternative polyfill implementations
+
+### **Node.js Environments**
+
+enum-plus requires a minimum of `ES2016` features, compatible with Node.js `v7.x` and above
 
 ---
 

README.md

@@ -78,19 +78,27 @@ yarn add enum-plus
 - 特定版本:
 
 ```html
+<!-- ES2020 现代版本 -->
 <script src="https://cdn.jsdelivr.net/npm/enum-plus@v3.0.0/umd/enum-plus.min.js"></script>
+<!-- ES2015 兼容版本 -->
+<script src="https://cdn.jsdelivr.net/npm/enum-plus@v3.0.0/umd/enum-plus-legacy.min.js"></script>
 ```
 
 - 最新版本:
 
 ```html
+<!-- ES2020 现代版本 -->
 <script src="https://cdn.jsdelivr.net/npm/enum-plus/umd/enum-plus.min.js"></script>
+<!-- ES2015 兼容版本 -->
+<script src="https://cdn.jsdelivr.net/npm/enum-plus/umd/enum-plus-legacy.min.js"></script>
 ```
 
 ⬇️ **下载文件**:
 
 - [enum-plus.umd.min.js.gz](https://github.com/shijistar/enum-plus/releases/download/v3.0.0/enum-plus.umd.min.js.gz) (~2kB gzipped)
 - [enum-plus.umd.tar.gz](https://github.com/shijistar/enum-plus/releases/download/v3.0.0/enum-plus.umd.tar.gz) (完整包，包含 sourcemap)
+- [enum-plus-legacy.umd.min.js.gz](https://github.com/shijistar/enum-plus/releases/download/v3.0.0/enum-plus-legacy.umd.min.js.gz)
+- [enum-plus-legacy.umd.tar.gz](https://github.com/shijistar/enum-plus/releases/download/v3.0.0/enum-plus-legacy.umd.tar.gz)
 
 > 你也可以去 [Github 发布](https://github.com/shijistar/enum-plus/releases) 中下载这些文件
 
@@ -910,22 +918,28 @@ declare global {
 
 ## 兼容性
 
-enum-plus 提供了完善的兼容性支持。
+enum-plus 设计之初就考虑了广泛的兼容性需求，可无缝运行于各类环境，包括现代浏览器、Node.js 以及多种构建工具。下面详细说明各环境的兼容性情况：
 
-- **浏览器环境**：
+### 浏览器环境
 
-  - **现代打包工具**：对于支持 [exports](https://nodejs.org/api/packages.html#exports-sugar) 字段的打包工具（如 Webpack 5+、Vite、Rollup），enum-plus 的目标是 **`ES2020`**。如果需要更广泛的浏览器支持，可以在构建过程中使用 `@babel/preset-env` 转译为更早期的语法。
+- **现代打包工具**：对于支持 [exports](https://nodejs.org/api/packages.html#exports-sugar) 字段的打包工具（如 webpack 5+、vite、rollup），引入的是`es`目录，对应的 EcmaScript 版本是 **`ES2020`**。如果需要更广泛的浏览器支持，可以在构建过程中使用 `@babel/preset-env` 转译为更早期的语法。
 
-  - **旧版打包工具**：对于不支持 `exports` 字段的工具（如 Webpack 4），enum-plus 会自动回退到 `main` 字段的入口点，其目标是 **`ES2016`**。
+- **旧版打包工具**：对于不支持 [exports](https://nodejs.org/api/packages.html#exports-sugar) 字段的工具（如 webpack 4），enum-plus 会自动回退到 `main` 字段的入口点，引入的是`es-legacy`目录，对应的 EcmaScript 版本是 **`ES2015`**。
 
-  - **Polyfill 策略**：为了最小化包的体积，enum-plus 不包含任何 polyfill。如果需要支持旧版浏览器，可以引入以下内容：
+- **UMD版本**：为了方便在浏览器中直接使用，或者方便在没有打包工具的静态项目中使用，enum-plus 还提供了 UMD 版本，可以通过 `<script>` 标签引入。`umd` 目录下提供了两种版本：
 
-    - `core-js`
-    - 配置适当的 `@babel/preset-env` 和 `useBuiltIns` 设置
-    - 其他替代的 polyfill 实现
-    -
+  - `enum-plus.min.js`：对应的 EcmaScript 版本是 **`ES2020`**，适用于现代浏览器
+  - `enum-plus-legacy.min.js`：对应的 EcmaScript 版本是 **`ES2015`**，适用于旧版浏览器
 
-- **Node.js 兼容性**：enum-plus 需要至少 **`ES2016`** 的特性，兼容 Node.js `v7.x` 及以上版本。
+> **Polyfill 策略**：为了最小化包的体积，enum-plus 不包含任何 polyfill。如果需要支持旧版浏览器，可以自行引入以下工具：
+>
+> - `core-js`
+> - 配置适当的 `@babel/preset-env` 和 `useBuiltIns` 设置
+> - 其他替代的 polyfill 实现
+
+### Node.js 环境
+
+在 Node.js 环境下，enum-plus 提供的 EcmaScript 版本是 **`ES2016`**，可以兼容 Node.js `v7.x` 及以上版本
 
 ---
 

README.zh-CN.md

@@ -87,8 +87,8 @@
   ],
   "scripts": {
     "build": "run-p build:*",
-    "build:es": "run-s task:build-es task:add-umd-header",
-    "build:es-legacy": "cross-env LEGACY=1 father build",
+    "build:es": "run-s task:build-es task:add-umd-banner",
+    "build:es-legacy": "cross-env LEGACY=1 run-s task:build-es-legacy task:add-umd-banner",
     "build:lib": "run-s ts2lib task:copy-dts task:copy-lib",
     "e2e": "run-s task:bundle-e2e task:run-e2e",
     "e2e:debug": "run-s task:bundle-e2e task:run-e2e-debug",
@@ -97,8 +97,9 @@
     "prepare-legacy-node13": "node ./scripts/prepare-legacy.js node13",
     "prepare-legacy-node15": "node ./scripts/prepare-legacy.js node15",
     "prepublishOnly": "run-s build test",
-    "task:add-umd-header": "tsx scripts/add-umd-header-comments.ts",
+    "task:add-umd-banner": "tsx scripts/add-umd-banner.ts",
     "task:build-es": "father build",
+    "task:build-es-legacy": "father build",
     "task:bundle-e2e": "tsx scripts/make-e2e-bundle.ts",
     "task:copy-dts": "shx cp ./src/*.d.ts ./lib",
     "task:copy-lib": "tsx scripts/copy-lib.ts",

package.json

@@ -0,0 +1,25 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import packageJson from '../package.json';
+
+const headerComment = (legacy: boolean) => `/**
+ * ${packageJson.name} (${legacy ? 'ES2015' : 'ES2020'} version)
+ * ${packageJson.description}
+ *
+ * @version: ${packageJson.version}
+ * @author: ${packageJson.author}
+ * @link ${packageJson.homepage}
+ */`;
+
+if (process.env.LEGACY === '1') {
+  const legacyFilePath = './umd/enum-plus-legacy.min.js';
+  if (existsSync(legacyFilePath)) {
+    const legacyJsContent = readFileSync(legacyFilePath, 'utf8');
+    writeFileSync(legacyFilePath, `${headerComment(true)}\n${legacyJsContent}`);
+  }
+} else {
+  const filePath = './umd/enum-plus.min.js';
+  if (existsSync(filePath)) {
+    const umdJsContent = readFileSync(filePath, 'utf8');
+    writeFileSync(filePath, `${headerComment(false)}\n${umdJsContent}`);
+  }
+}