mazey 5.0.0 → 5.0.1

package/README.md

@@ -22,7 +22,7 @@ Website: [chengchuu.github.io/mazey](https://chengchuu.github.io/mazey/)
 Use Mazey via [npm](https://www.npmjs.com/package/mazey).
 
 ```bash
-npm install mazey --save
+npm install mazey
 ```
 
 Use Mazey from CDN.
@@ -1138,52 +1138,15 @@ MazeyLog: I am object. {a: 123, b: 456}
 
 ### Scripts
 
-Install Dependencies:
-
-```bash
-npm i
-```
-
-Development:
-
-```bash
-npm run dev
-```
-
-Build:
-
-```bash
-npm run build
-```
-
-Test:
-
-```bash
-npm run test
-```
-
-Documentation:
-
-```bash
-npm run docs
-```
-
-The documentation command builds the production website, playground, and TypeDoc API into `docs`,
-then validates the final SEO and PWA metadata. Use the focused checks while developing:
-
-```bash
-npm run typecheck
-npm run lint
-npm run build:site
-npm run seo:validate
-npm run pwa:validate
-```
-
-Preview the production Pages artifact at `http://127.0.0.1:4173/mazey/`:
-
-```bash
-npm run pwa:preview
-```
+| Command               | Purpose                                                         |
+| --------------------- | --------------------------------------------------------------- |
+| `npm install`         | Install development dependencies.                               |
+| `npm run dev`         | Start the website and playground development server.            |
+| `npm run build`       | Build the publishable package files.                            |
+| `npm test`            | Run the Jest test suite.                                        |
+| `npm run docs`        | Build and validate the complete GitHub Pages artifact.          |
+| `npm run preview`     | Run the full type, lint, build, test, and documentation checks. |
+| `npm run pwa:preview` | Serve the production Pages artifact at the `/mazey/` base path. |
 
 ### Returns
 

package/README.zh-CN.md

@@ -17,7 +17,7 @@ Mazey 是一个面向日常前端开发的函数工具库。前端生态已有
 通过 [npm](https://www.npmjs.com/package/mazey) 安装 Mazey。
 
 ```bash
-npm install mazey --save
+npm install mazey
 ```
 
 通过内容分发网络 (Content Delivery Network，CDN) 使用 Mazey。
@@ -63,6 +63,7 @@ isNumber(z, { isInfinityAsNumber: true }); // 输出: true
 ### 目录
 
 <!-- toc - begin -->
+- [目录](#目录)
 - [加载资源](#加载资源)
   - [loadScript](#loadscript)
   - [loadScriptIfUndefined](#loadscriptifundefined)
@@ -112,6 +113,9 @@ isNumber(z, { isInfinityAsNumber: true }); // 输出: true
   - [getPerformance](#getperformance)
 - [调试](#调试)
   - [genCustomConsole](#gencustomconsole)
+- [开发环境](#开发环境)
+- [脚本](#脚本)
+- [返回值](#返回值)
 <!-- toc - end -->
 
 ### 加载资源

package/lib/index.cjs.js

@@ -1,5 +1,5 @@
 /*!
- * Mazey v5.0.0 https://github.com/chengchuu/mazey
+ * Mazey v5.0.1 https://github.com/chengchuu/mazey
  * (c) 2018-2026 Cheng
  * Released under the MIT License.
  */

package/lib/index.d.ts

@@ -1286,6 +1286,22 @@ declare function isValidDate(value: unknown): boolean;
 /**
  * Return the formatted date string in the given format.
  *
+ * Supported format tokens:
+ *
+ * | Token  | Meaning                                | Range or example |
+ * | ------ | -------------------------------------- | ---------------- |
+ * | `yyyy` | Four-digit year                        | `2022`           |
+ * | `MM`   | Two-digit month                        | `01`–`12`        |
+ * | `dd`   | Two-digit day of the month             | `01`–`31`        |
+ * | `HH`   | Two-digit hour using the 24-hour clock | `00`–`23`        |
+ * | `hh`   | Two-digit hour using the 12-hour clock | `01`–`12`        |
+ * | `mm`   | Two-digit minute                       | `00`–`59`        |
+ * | `ss`   | Two-digit second                       | `00`–`59`        |
+ * | `a`    | Uppercase meridiem indicator           | `AM` or `PM`     |
+ *
+ * The function creates a native `Date` and reads its local date and time
+ * fields. Timestamp output can therefore differ between runtime time zones.
+ *
  * Usage:
  *
  * ```javascript
@@ -1310,9 +1326,9 @@ declare function isValidDate(value: unknown): boolean;
  * Date formatDate value: 02/11/2014
  * ```
  *
- * @param {MazeyDate} dateIns Original Date
- * @param {string} format Format String
- * @returns {string} Return the formatted date string.
+ * @param {MazeyDate} dateIns Original date value. Defaults to the current date and time.
+ * @param {string} format Format string composed of supported format tokens. Defaults to `yyyy-MM-dd`.
+ * @returns {string} The formatted date string.
  * @throws {RangeError} If `dateIns` is not a valid date.
  * @category Util
  */

package/lib/index.esm.js

@@ -1,5 +1,5 @@
 /*!
- * Mazey v5.0.0 https://github.com/chengchuu/mazey
+ * Mazey v5.0.1 https://github.com/chengchuu/mazey
  * (c) 2018-2026 Cheng
  * Released under the MIT License.
  */

package/lib/mazey.min.js

@@ -1,5 +1,5 @@
 /*!
- * Mazey v5.0.0 https://github.com/chengchuu/mazey
+ * Mazey v5.0.1 https://github.com/chengchuu/mazey
  * (c) 2018-2026 Cheng
  * Released under the MIT License.
  */

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "mazey",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "description": "A functional library for daily frontend work.",
   "main": "lib/index.cjs.js",
   "module": "lib/index.esm.js",
   "typings": "lib/index.d.ts",
   "types": "lib/index.d.ts",
   "mainEntryPointFilePath": "lib/index.d.ts",
+  "files": [
+    "README.md",
+    "LICENSE",
+    "lib",
+    "scripts/legacy"
+  ],
   "directories": {
     "lib": "./lib"
   },
@@ -30,8 +36,7 @@
     "pwa:validate": "node scripts/validate-pwa.js",
     "pwa:preview": "npm run docs && node scripts/preview-pages.js",
     "preview": "npm run typecheck && npm run lint && npm run build && npm run test && npm run docs",
-    "release": "npm run preview && cross-env SCRIPTS_NPM_PACKAGE_VERSION=$npm_package_version node ./scripts/release.js",
-    "release:win": "bash scripts/shell/env-win.sh && npm i --registry=https://registry.npmmirror.com && npm run release",
+    "release": "npm run preview && cross-env SCRIPTS_NPM_PACKAGE_VERSION=$npm_package_version node ./scripts/legacy/release.js",
     "skill:sync": "node ./scripts/sync-prefer-mazey-skill.mjs",
     "skill:sync:dry-run": "node ./scripts/sync-prefer-mazey-skill.mjs --dry-run",
     "skill:sync:check": "node ./scripts/sync-prefer-mazey-skill.mjs --check"
@@ -85,8 +90,6 @@
     "@babel/preset-typescript": "^7.23.2",
     "@babel/runtime": "^7.23.2",
     "@babel/runtime-corejs3": "^7.23.2",
-    "@commitlint/cli": "^17.8.1",
-    "@commitlint/config-conventional": "^17.8.1",
     "@rollup/plugin-babel": "^6.0.3",
     "@rollup/plugin-commonjs": "^25.0.7",
     "@rollup/plugin-node-resolve": "^16.0.3",
@@ -106,14 +109,11 @@
     "eslint-plugin-standard": "^4.1.0",
     "execa": "^5.1.1",
     "html-webpack-plugin": "^5.5.3",
-    "husky": "^8.0.3",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
-    "lint-staged": "^14.0.1",
     "markdown-toc": "^1.2.0",
     "mini-css-extract-plugin": "^2.9.2",
     "prettier": "^2.8.8",
-    "prettier-eslint-cli": "^8.0.1",
     "rollup": "^3.29.4",
     "rollup-plugin-cleaner": "^1.0.0",
     "rollup-plugin-copy": "^3.4.0",
@@ -126,11 +126,5 @@
     "webpack": "^5.89.0",
     "webpack-cli": "^5.1.4",
     "webpack-dev-server": "^4.15.1"
-  },
-  "husky": {
-    "hooks": {
-      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS",
-      "pre-commit": "lint-staged"
-    }
   }
 }

package/scripts/legacy/README.md

@@ -0,0 +1,56 @@
+# Legacy scripts
+
+These scripts are retained for compatibility with historical Mazey release
+workflows. New project automation should use the maintained npm scripts and
+GitHub Actions workflows instead.
+
+Mazey does not install the legacy helpers' dependencies for library consumers.
+Install them in the project that uses these scripts:
+
+```bash
+npm install --save-dev date-fns@^2.30.0 execa@^5.1.1 markdown-toc@^1.2.0
+```
+
+The canonical helper import is:
+
+```javascript
+const { release } = require("mazey/scripts/legacy/git-helper.js");
+```
+
+## release
+
+Release this project with an explicit version. The bundled entry point reads
+`SCRIPTS_NPM_PACKAGE_VERSION` or `VERSION`.
+
+Usage:
+
+```javascript
+const pkgVersion = process.env.VERSION;
+release(pkgVersion);
+```
+
+It will be more straightforward if you use the development dependence CrossEnv.
+
+```shell
+# Install
+npm i cross-env -D
+
+# scripts
+cross-env SCRIPTS_NPM_PACKAGE_VERSION=$npm_package_version node ./scripts/legacy/release.js
+```
+
+```javascript
+// release.js
+release();
+```
+
+<!-- @param {string} ver Version
+@returns {void} -->
+
+## generateToc
+
+Generate table of contents for the markdown file.
+
+<!-- @param {string} path Path of markdown file.
+@param {array} options.hiddenHeadings Hidden headings.
+@returns {void} -->

package/scripts/legacy/build-helper.js

@@ -0,0 +1,77 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+/* eslint-disable no-undef */
+const path = require("path");
+const scriptsDirectory = path.resolve(__dirname, "..");
+const _resolve = (_path) => path.resolve(scriptsDirectory, _path);
+const format = require("date-fns/format");
+const toc = require("markdown-toc");
+const fs = require("fs");
+// Generate version: 20210308.072903
+const genVersion = () => {
+  const d = new Date();
+  const version = format(d, "yyyyMMdd.HHmmss");
+  return version;
+};
+const version = genVersion();
+const defaultHiddenHeadings = [
+  "mazey",
+  "Install",
+  "Usage",
+  "Contributing",
+  "License",
+  "API Examples",
+  "Development Environment",
+  "Returns",
+  "Scripts",
+  "Node.js",
+  "TypeScript",
+  "Table of Contents",
+];
+
+/**
+ * Generate table of contents for the markdown file.
+ * 
+ * @param {string} path Path of markdown file.
+ * @param {array} options.hiddenHeadings Hidden headings.
+ * @returns {void}
+ */
+const generateToc = (path = "../README.md", options = {
+  hiddenHeadings: defaultHiddenHeadings,
+}) => {
+  console.log("Generating Table of Contents...");
+  options = Object.assign({
+    hiddenHeadings: defaultHiddenHeadings,
+  }, options);
+  const RMFilePath = _resolve(path);
+  // https://melvingeorge.me/blog/get-all-the-contents-from-file-as-string-nodejs
+  console.log("running...");
+  const buffer = fs.readFileSync(RMFilePath);
+  const fileContent = buffer.toString();
+  // https://github.com/jonschlinkert/markdown-toc
+  const removeUnnecessaryHeadings = (str) => {
+    return !options.hiddenHeadings.some(v => {
+      return str.includes(v);
+    });
+  };
+  let tocContent = toc(fileContent, {
+    filter: removeUnnecessaryHeadings,
+    bullets: [ "-", "-" ],
+  }).content;
+  tocContent = tocContent.replace(/[ ]{4}/gm, "");
+  tocContent = "<!-- toc - begin -->\n" + "- Generated with ❤️\n" + tocContent;
+  tocContent = tocContent + "\n<!-- toc - end -->";
+  // Insert to file.
+  // https://stackoverflow.com/questions/14177087/replace-a-string-in-a-file-with-nodejs
+  let newFileContent = fileContent;
+  // https://stackoverflow.com/questions/1979884/how-to-use-javascript-regex-over-multiple-lines
+  newFileContent = newFileContent.replace(/<!-- toc - begin -->[\s\S]*<!-- toc - end -->/gm, tocContent);
+  console.log("running...");
+  fs.writeFileSync(RMFilePath, newFileContent);
+  console.log("Generating Table of Contents is done.");
+};
+
+module.exports = {
+  _resolve,
+  version,
+  generateToc,
+};

package/scripts/legacy/dev.js

@@ -0,0 +1,6 @@
+/* eslint-disable no-undef, @typescript-eslint/no-var-requires */
+const { generateToc } = require("./build-helper");
+
+(async () => {
+  generateToc();
+})();

package/scripts/legacy/git-helper.js

@@ -0,0 +1,164 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+/* eslint-disable no-undef */
+// Git Helper
+const execa = require("execa");
+
+/**
+ * Release this project with an explicit version or `SCRIPTS_NPM_PACKAGE_VERSION`.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const pkgVersion = process.env.VERSION;
+ * release(pkgVersion);
+ * ```
+ *
+ * It will be more straightforward if you use the development dependence CrossEnv.
+ *
+ * ```shell
+ * # Install
+ * npm i cross-env -D
+ *
+ * # scripts
+ * cross-env SCRIPTS_NPM_PACKAGE_VERSION=$npm_package_version node ./scripts/legacy/release.js
+ * ```
+ *
+ * ```javascript
+ * // release.js
+ * release();
+ * ```
+ *
+ * @param {string} ver Version
+ * @returns {void}
+ */
+async function release (ver, { canGenerateToc = false, generateTocOnly = false, defaultBranch = "main" } = {}) {
+  if (!ver) {
+    ver = process.env.SCRIPTS_NPM_PACKAGE_VERSION;
+  }
+  if (!ver) {
+    console.error("Fail to get the current version.");
+    return;
+  }
+  const { generateToc } = require("./build-helper");
+  const releaseVersion = `v${ver}`;
+  const { stdout: releaseStdout } = await execa("echo", [ `Start release ${releaseVersion}...` ]);
+  console.log(releaseStdout);
+  // Generating Table of Contents
+  if (canGenerateToc) {
+    generateToc();
+  }
+  if (generateTocOnly) {
+    return;
+  }
+  // Commit
+  await gitCommit(`${releaseVersion} stage`);
+  // Marge
+  await gitMergeMain2Release(defaultBranch);
+  // Build
+  await execa("npm", [ "run", "preview" ]);
+  await execa("npm", [ "publish" ]);
+  // Commit Again
+  await gitCommit(releaseVersion);
+  // Push
+  console.log("Pushing to the remote Git...");
+  await gitTagPush(releaseVersion);
+  await gitPush();
+  console.log("All done.");
+}
+
+/**
+ * Push git tag.
+ *
+ * @example
+ * ```
+ * await gitTagPush("v1.0.0");
+ * ```
+ *
+ * @param {string} ver Release version
+ * @returns {boolean} Is success
+ */
+async function gitTagPush (ver = "") {
+  if (!ver) {
+    console.error("Fail to get the current version.");
+    return false;
+  }
+  if (!ver.startsWith("v")) {
+    ver = `v${ver}`;
+  }
+  await execa("git", [ "tag", "-a", `${ver}`, "-m", `Release ${ver}` ]);
+  await execa("git", [ "push", "origin", `refs/tags/${ver}` ]);
+  return true;
+}
+
+/**
+ * Push code.
+ */
+async function gitPush () {
+  try {
+    await execa("git", [ "push" ], { stdio: "pipe" });
+  } catch (error) {
+    console.log("Error:", error.message);
+    const { stdout: currentBranch } = await execa("git", [ "branch", "--show-current" ], { stdio: "pipe" });
+    console.log(`Current Branch: ${currentBranch}`);
+    await execa("git", [ "push", "--set-upstream", "origin", currentBranch ]);
+  }
+  return true;
+}
+
+/**
+ * Merge main to current branch.
+ */
+async function gitMergeMain2Release (defaultBranch = "main") {
+  const currentBranch = await getGitCurrentBranch();
+  await execa("git", [ "checkout", defaultBranch ]);
+  await execa("git", [ "pull" ]);
+  await execa("git", [ "checkout", currentBranch ]);
+  await execa("git", [ "merge", defaultBranch ]);
+  return true;
+}
+
+/**
+ * Alias of `gitMergeMain2Release`.
+ */
+async function gitMergeMaster2Release (defaultBranch = "main") {
+  return await gitMergeMain2Release(defaultBranch);
+}
+
+/**
+ * Get git current branch.
+ */
+async function getGitCurrentBranch () {
+  let currentBranch = "";
+  try {
+    ({ stdout: currentBranch } = await execa("git", [ "branch", "--show-current" ], { stdio: "pipe" }));
+  } catch (error) {
+    ({ stdout: currentBranch } = await execa("git", [ "rev-parse", "--abbrev-ref", "HEAD" ], { stdio: "pipe" }));
+  }
+  console.log(`Current Branch: ${currentBranch}`);
+  return currentBranch;
+}
+
+/**
+ * Commit current code.
+ */
+async function gitCommit (releaseVersion = 0) {
+  const { stdout: diffStdout } = await execa("git", [ "diff" ], { stdio: "pipe" });
+  if (diffStdout) {
+    console.log("Committing changes...");
+    await execa("git", [ "add", "-A" ]);
+    await execa("git", [ "commit", "-m", `release: ${releaseVersion}` ]);
+  } else {
+    console.log("No changes to commit.");
+  }
+  return true;
+}
+
+module.exports = {
+  release,
+  gitPush,
+  gitMergeMaster2Release, // Deprecated
+  gitMergeMain2Release,
+  getGitCurrentBranch,
+  gitCommit,
+  gitTagPush,
+};

package/scripts/legacy/release.js

@@ -0,0 +1,9 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+/* eslint-disable no-undef */
+// release
+const { release } = require("./git-helper.js");
+const pkgVersion = process.env.SCRIPTS_NPM_PACKAGE_VERSION || process.env.VERSION;
+
+console.log("release: SCRIPTS_NPM_PACKAGE_VERSION", process.env.SCRIPTS_NPM_PACKAGE_VERSION);
+
+release(pkgVersion, { canGenerateToc: true, generateTocOnly: true });