feat: implement a new version of serialize-javascript, much powerful than before

Author: shijistar

.gitignore

@@ -4,6 +4,8 @@ es-legacy
 umd
 tslib
 tses
+src/version.ts
+test/utils/version.ts
 types-legacy/*/*.d.ts
 node_modules
 npm-debug.log

e2e/specs/version.spec.ts

@@ -0,0 +1,4 @@
+import playwright from '../../test/engines/playwright';
+import testVersion from '../../test/test-suites/version';
+
+testVersion(playwright);

enum-plus-v3.md

@@ -52,6 +52,10 @@
 - `enum.valuesEnum` method is removed, use `enum.toValueMap` instead.
 - The behavior of `enum.values` is changed. Use `enum.items` for the old behavior.
 
+## Misc
+
+- The warning message for trying to modify enum items has been removed. First, in order to avoid circular references within enum items (which would affect serialization), we removed the internal `proxy` and used `getter/setter` instead. However, this brought about another problem: when printing enum items in the browser console or node.js, the `key`, `value`, and `label` cannot display their values, but show `[Getter/Setter]` instead. This somewhat affects the debugging experience. Sorry @yyz945947732, you introduced this feature, which is very good, but after weighing the pros and cons, we still had to remove this feature.
+
 ## Bug Fixes
 
 - Fix the issue where sourcemap files under the `lib` directory could not be parsed.

package-lock.json

@@ -115,14 +115,17 @@
   ],
   "scripts": {
     "build": "run-p build:*",
-    "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",
+    "build:es": "run-s gv task:build-es task:update-es-enum task:add-es-extensions task:add-umd-banner",
+    "build:es-legacy": "cross-env LEGACY=1 run-s gv task:build-es-legacy task:update-es-legacy-enum task:add-umd-banner task:add-es-legacy-extensions",
+    "build:lib": "run-s gv ts2lib task:copy-lib task:copy-dts task:types-legacy",
+    "build:tses": "run-s gv ts2es task:add-tses-extensions",
+    "clean": "shx rm -rf lib es es-legacy umd tses tslib types-legacy/pre-v5/*.d.ts",
     "e2e": "run-s task:bundle-e2e task:run-e2e",
     "e2e:debug": "run-s task:bundle-e2e task:run-e2e-debug",
     "e2e:ui": "run-s task:bundle-e2e task:run-e2e-ui",
-    "prepare": "husky",
+    "gv": "node scripts/generate-version.js",
+    "init-husky": "husky",
+    "prepare": "run-s gv init-husky",
     "prepare-legacy-node": "node ./scripts/prepare-legacy.js",
     "prepublishOnly": "run-s build test-all",
     "task:add-es-extensions": "tsx scripts/add-esm-extensions.ts es",
@@ -147,8 +150,8 @@
     "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",
-    "test-node-esm": "run-s build:tses task:jest-esm",
+    "test-node-cjs": "run-s build:lib ts2lib task:jest-cjs",
+    "test-node-esm": "run-s build:es build:tses task:jest-esm",
     "ts2es": "tsc -p tsconfig.es.json",
     "ts2lib": "tsc -p tsconfig.lib.json"
   },

package.json

@@ -21,7 +21,7 @@ function processDir(dir: string) {
     } else if (file.endsWith('.js')) {
       let content = readFileSync(fullPath, 'utf8');
       content = content.replace(/from\s+(['"])([./][^'"]+)['"]/g, (match, quote, importPath) => {
-        if (!importPath.endsWith('.js')) {
+        if (!importPath.endsWith('.js') && !importPath.endsWith('.json')) {
           return `from ${quote}${importPath}.js${quote}`;
         }
         return match;

scripts/add-esm-extensions.ts

@@ -0,0 +1,34 @@
+const path = require('path');
+const fs = require('fs');
+
+const root = path.resolve(__dirname, '..');
+
+generate(path.join(root, 'src/version.ts'));
+generate(path.join(root, 'test/utils/version.ts'));
+
+/** @param {string} outFile */
+function generate(outFile) {
+  try {
+    const pkgPath = path.join(root, 'package.json');
+    const pkgRaw = fs.readFileSync(pkgPath, 'utf8');
+    const pkg = JSON.parse(pkgRaw);
+    const version = pkg.version;
+    if (!version || typeof version !== 'string') {
+      throw new Error('Missing version field in package.json');
+    }
+
+    const content = `export const version = '${version}';\n`;
+
+    if (fs.existsSync(outFile)) {
+      const existing = fs.readFileSync(outFile, 'utf8');
+      if (existing !== content) {
+        fs.writeFileSync(outFile, content, 'utf8');
+      }
+    } else {
+      fs.writeFileSync(outFile, content, 'utf8');
+    }
+  } catch (err) {
+    console.error('Error generating version.ts:', err);
+    process.exitCode = 1;
+  }
+}

scripts/generate-version.js

@@ -1,5 +1,4 @@
 import { nodeResolve } from '@rollup/plugin-node-resolve';
-import { cpSync, readFileSync, writeFileSync } from 'fs';
 import { rollup } from 'rollup';
 
 async function build() {
@@ -26,60 +25,40 @@ async function build() {
   });
 
   // Bundle serialize-javascript
-  const serializePath = './e2e/fixtures/scripts/serialize-javascript.js';
-  changeFormat('./tslib/test/utils/serialize-javascript.js', serializePath, 'SerializeJavascript');
   const serializeJavascript = await rollup({
-    input: serializePath,
+    input: 'tses/test/utils/serialize-javascript.js',
     plugins: [nodeResolve()],
   });
   await serializeJavascript.write({
     file: 'e2e/fixtures/scripts/serialize-javascript-bundle.js',
     format: 'iife',
+    name: 'SerializeJavascript',
   });
 
   // Bundle week-config
-  const weekConfigPath = './e2e/fixtures/scripts/week-config.js';
-  changeFormat('./tslib/test/data/week-config.js', weekConfigPath, 'WeekConfig', (content) => {
-    return content.replace('require("../src")', 'window.EnumPlus');
-  });
   const weekConfig = await rollup({
-    input: weekConfigPath,
+    input: 'tses/test/data/week-config.js',
     plugins: [nodeResolve()],
   });
   await weekConfig.write({
     file: 'e2e/fixtures/scripts/week-config-bundle.js',
     format: 'iife',
+    name: 'WeekConfig',
   });
 
   // Bundle week-data
-  const weekDataPath = './e2e/fixtures/scripts/week-data.js';
-  changeFormat('./tslib/test/data/week-data.js', weekDataPath, 'WeekData');
   const weekDataConfig = await rollup({
-    input: weekDataPath,
+    input: 'tses/test/data/week-data.js',
     plugins: [nodeResolve()],
   });
   await weekDataConfig.write({
     file: 'e2e/fixtures/scripts/week-data-bundle.js',
     format: 'iife',
+    name: 'WeekData',
   });
 }
 
 build().catch((e) => {
   console.error(e);
   process.exit(1);
 });
-
-function changeFormat(src: string, dest: string, name: string, replacer?: (content: string) => string) {
-  cpSync(src, dest, {
-    force: true,
-  });
-  let content = readFileSync(dest, 'utf-8');
-  content = `var exports = {};\n` + content;
-  if (name) {
-    content += `\n window.${name} = exports;`;
-  }
-  if (replacer) {
-    content = replacer(content);
-  }
-  writeFileSync(dest, content);
-}

scripts/make-e2e-bundle.ts

@@ -42,7 +42,8 @@ export class EnumCollectionClass<
   implements
     Omit<IEnumItems<T, K, V>, typeof IS_ENUM_ITEMS | typeof ITEMS | typeof KEYS | typeof VALUES | 'labels' | 'meta'>
 {
-  private __options__: EnumItemOptions | undefined;
+  private readonly __options__: EnumItemOptions | undefined;
+  // used for e2e serialization
   private readonly __items__!: EnumItemsArray<T, K, V>;
 
   constructor(init: T = {} as T, options?: EnumItemOptions) {
@@ -87,7 +88,9 @@ export class EnumCollectionClass<
     Object.defineProperty(this, keys.includes('labels') ? LABELS : 'labels', {
       enumerable: true,
       configurable: false,
-      get: () => items.labels,
+      get: function (this: EnumCollectionClass<T, K, V>) {
+        return this.__items__.labels;
+      },
     });
 
     Object.freeze(this);

src/enum-collection.ts

@@ -16,6 +16,9 @@ export class EnumItemClass<
   V extends EnumValue = ValueTypeFromSingleInit<T, K>,
 > {
   private _options: EnumItemOptions | undefined;
+  private _label: string | undefined;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private _localize: (content: string | undefined) => any;
 
   /**
    * Instantiate an enum item
@@ -31,64 +34,61 @@ export class EnumItemClass<
     this.value = value;
     this.label = label;
     this.raw = raw;
-    const isNode = typeof process !== 'undefined' && process && process.versions && process.versions.node != null;
-    // Do not use class field here, because don't want print this field in Node.js
-    Object.defineProperty(this, '_options', {
-      value: options,
+
+    Object.defineProperty(this, '_label', {
+      value: label,
       writable: false,
       enumerable: false,
       configurable: false,
     });
     Object.defineProperties(this, {
       value: {
-        // To print pretty in Node.js console
-        ...(isNode
-          ? {
-              value,
-              writable: false,
-            }
-          : /* istanbul ignore next */ {
-              get: /* istanbul ignore next */ () => value,
-              set: /* istanbul ignore next */ () => console.warn(this._readonlyPropWarning('value')),
-            }),
+        value,
+        writable: false,
         enumerable: true,
         configurable: false,
       },
       label: {
-        get: () => this._localize(label) ?? label,
-        set: () => console.warn(this._readonlyPropWarning('label')),
+        get: function (this: EnumItemClass<T, K, V>) {
+          return this._localize(this._label) ?? this._label;
+        },
         enumerable: true,
         configurable: false,
       },
       key: {
-        // To print pretty in Node.js console
-        ...(isNode
-          ? {
-              value: key,
-              writable: false,
-            }
-          : /* istanbul ignore next */ {
-              get: /* istanbul ignore next */ () => key,
-              set: /* istanbul ignore next */ () => console.warn(this._readonlyPropWarning('key')),
-            }),
+        value: key,
+        writable: false,
         enumerable: true,
         configurable: false,
       },
       raw: {
-        // To print pretty in Node.js console
-        ...(isNode
-          ? {
-              value: raw,
-              writable: false,
-            }
-          : /* istanbul ignore next */ {
-              get: /* istanbul ignore next */ () => raw,
-              set: /* istanbul ignore next */ () => console.warn(this._readonlyPropWarning('raw')),
-            }),
+        value: raw,
+        writable: false,
         enumerable: true,
         configurable: false,
       },
     });
+    // Do not use class field here, because don't want print this field in Node.js
+    Object.defineProperty(this, '_options', {
+      value: options,
+      writable: false,
+      enumerable: false,
+      configurable: false,
+    });
+    this._localize = undefined!;
+    Object.defineProperty(this, '_localize', {
+      value: function (this: EnumItemClass<T, K, V>, content: string | undefined) {
+        const localize = this._options?.localize ?? localizer.localize;
+        if (typeof localize === 'function') {
+          return localize(content);
+        }
+        return content;
+      },
+      writable: false,
+      enumerable: false,
+      configurable: false,
+    });
+
     Object.freeze(this);
   }
 
@@ -149,21 +149,9 @@ export class EnumItemClass<
     return this.valueOf();
   }
 
-  // should use function here to avoid closure. this is important for the e2e test cases.
-  private _localize(content: string | undefined) {
-    const localize = this._options?.localize ?? localizer.localize;
-    if (typeof localize === 'function') {
-      return localize(content);
-    }
-    return content;
-  }
-  private _readonlyPropWarning(name: string) {
-    return `Cannot modify property "${name}" on EnumItem. EnumItem instances are readonly and should not be mutated.`;
-  }
-
   // The priority of the toString method is lower than the valueOf method
   toString() {
-    return this._localize(this.label);
+    return this.label;
   }
   toLocaleString() {
     return this.toString();