mazey 5.9.2 → 5.10.1

package/README.md

@@ -78,8 +78,12 @@ There are some examples maintained by hand below. For more information, please c
   - [windowLoaded](#windowloaded)
 - [Util](#util)
   - [isNumber](#isnumber)
+  - [isNullish](#isnullish)
   - [isJSONString](#isjsonstring)
   - [parseJsonSafe](#parsejsonsafe)
+  - [isCNMobileNumber](#iscnmobilenumber)
+  - [escapeHTML and unescapeHTML](#escapehtml-and-unescapehtml)
+  - [truncateByWeightedLength](#truncatebyweightedlength)
   - [escapeHtmlAttribute](#escapehtmlattribute)
   - [sha256Hex](#sha256hex)
   - [isValidData](#isvaliddata)
@@ -108,6 +112,7 @@ There are some examples maintained by hand below. For more information, please c
   - [toJavaScriptGlobalName](#tojavascriptglobalname)
   - [derivePackageMetadata](#derivepackagemetadata)
 - [URL](#url)
+  - [getURLPathExtension](#geturlpathextension)
   - [getQueryParam](#getqueryparam)
   - [getUrlParam](#geturlparam)
   - [getHashQueryParam](#gethashqueryparam)
@@ -121,19 +126,19 @@ There are some examples maintained by hand below. For more information, please c
   - [Storage Helpers](#storage-helpers)
 - [DOM](#dom)
   - [Class Helpers](#class-helpers)
-  - [hide and show](#hide-and-show)
+  - [hideElements and showElements](#hideelements-and-showelements)
   - [isValidCssSelector](#isvalidcssselector)
   - [resolveElementTarget](#resolveelementtarget)
   - [extractElementText](#extractelementtext)
   - [injectStyle](#injectstyle)
-  - [genStyleString](#genstylestring)
+  - [createCSSRule](#createcssrule)
   - [newLine](#newline)
 - [Event](#event)
   - [onEvent](#onevent)
 - [Calculate and Formula](#calculate-and-formula)
   - [calculateAspectRatio](#calculateaspectratio)
   - [calculateCAGR](#calculatecagr)
-  - [inRate](#inrate)
+  - [randomBoolean](#randomboolean)
   - [longestComSubstring](#longestcomsubstring)
   - [longestComSubsequence](#longestcomsubsequence)
 - [Browser Information](#browser-information)
@@ -152,6 +157,7 @@ There are some examples maintained by hand below. For more information, please c
   - [isWindows](#iswindows)
   - [isLinux](#islinux)
   - [getBrowserInfo](#getbrowserinfo)
+  - [getBrowserClassNames](#getbrowserclassnames)
   - [isSafePWAEnv](#issafepwaenv)
   - [isStandalonePWA](#isstandalonepwa)
   - [listenMediaQueryChanges](#listenmediaquerychanges)
@@ -293,6 +299,9 @@ Load Success: load
 
 ### Util
 
+Use native `Date.now()` to get the current epoch time in milliseconds. The
+former `mNow()` helper remains available as a deprecated compatibility API.
+
 #### isNumber
 
 Check whether a value is an allowed numeric primitive. Optional constraints can
@@ -323,6 +332,21 @@ true false false true false true true false
 reversed bounds return `false`. Existing non-finite-number behavior is unchanged
 when `integer`, `min`, and `max` are omitted.
 
+#### isNullish
+
+Check whether a value is exactly `undefined` or `null`. Other falsy values are
+not nullish.
+
+```javascript
+isNullish(undefined); // true
+isNullish(null); // true
+isNullish(false); // false
+isNullish(0); // false
+isNullish(""); // false
+```
+
+`isUdfOrNul` remains available as a deprecated alias of `isNullish`.
+
 #### isJSONString
 
 Check whether it is a valid JSON string.
@@ -354,6 +378,55 @@ const fallback = parseJsonSafe("invalid", {});
 console.log(data, fallback);
 ```
 
+#### isCNMobileNumber
+
+Check the Chinese mobile-number format: `1` followed by ten digits. This checks
+format only, without verifying assigned prefixes, ownership, or reachability.
+
+```javascript
+import { isCNMobileNumber } from "mazey";
+
+isCNMobileNumber("13800138000"); // true
+isCNMobileNumber("+8613800138000"); // false
+```
+
+`isValidPhoneNumber` and `isMobile` remain deprecated aliases.
+
+#### escapeHTML and unescapeHTML
+
+Escape six HTML-sensitive characters or decode that fixed entity set in one
+pass. These helpers do not sanitize arbitrary HTML or validate URLs.
+`unescapeHTML` preserves unrecognized entities.
+
+```javascript
+import { escapeHTML, unescapeHTML } from "mazey";
+
+escapeHTML('<b title="x">A&B</b>');
+// '&lt;b title=&quot;x&quot;&gt;A&amp;B&lt;&#x2F;b&gt;'
+unescapeHTML("&lt;b&gt;A&amp;B&lt;&#x2F;b&gt;");
+// "<b>A&B</b>"
+```
+
+`sanitizeInput` and `unsanitizeInput` remain deprecated aliases. The legacy
+`unsanitize` alias also remains available.
+
+#### truncateByWeightedLength
+
+Truncate by weighted UTF-16 length: code units from `U+0000` through `U+00FF`
+count as one; all other code units count as two. Optional truncation text is
+appended after the limit. This does not measure bytes or rendered width and can
+split surrogate pairs.
+
+```javascript
+import { truncateByWeightedLength } from "mazey";
+
+truncateByWeightedLength("Hello世界", 7); // "Hello世"
+truncateByWeightedLength("Hello世界", 7, { hasDot: true }); // "Hello世..."
+```
+
+`cutZHString` remains a deprecated alias. The legacy `truncateZHString` and
+`cutCHSString` signatures retain their boolean `hasDot` argument.
+
 #### escapeHtmlAttribute
 
 Escape text for use inside a quoted HTML attribute without escaping `/`.
@@ -893,6 +966,23 @@ manifest.
 
 ### URL
 
+#### getURLPathExtension
+
+Extract a file extension from a URL or path, excluding query and fragment text.
+This helper does not detect MIME types or inspect file contents.
+It preserves the existing string-based behavior: `archive.tar.gz` returns
+`tar.gz`, and an origin-only input such as `https://example.com` returns `com`.
+
+```javascript
+import { getURLPathExtension } from "mazey";
+
+getURLPathExtension("https://example.com/image.png?width=200#preview"); // "png"
+getURLPathExtension("/images/photo.jpg"); // "jpg"
+getURLPathExtension("/images/photo"); // ""
+```
+
+`getUrlFileType` remains a deprecated alias.
+
 #### getQueryParam
 
 Get the query param's value of the current Web URL(`location.search`).
@@ -1139,29 +1229,31 @@ addClass(dom, "test");
 removeClass(dom, "test");
 ```
 
-#### hide and show
+#### hideElements and showElements
 
 Hide or show a CSS selector, one element, or an iterable or array-like element
 collection. Both helpers return the original target, so a caller can retain its
 own chaining convention. Duplicate elements are changed only once, and invalid
 selectors or unsupported values are ignored.
 
-`hide()` preserves a visible element's inline `display` value. `show()` restores
-that value, or recovers the element's normal display when a stylesheet would
-otherwise keep it hidden.
+`hideElements()` preserves a visible element's inline `display` value.
+`showElements()` restores that value, or recovers the element's normal display
+when a stylesheet would otherwise keep it hidden.
 
 ```javascript
-import { hide, show } from "mazey";
+import { hideElements, showElements } from "mazey";
 
 const notices = document.querySelectorAll(".notice");
 
-hide(notices);
-show(notices);
+hideElements(notices);
+showElements(notices);
 
-hide("#temporary-message");
-show(document.querySelector("#temporary-message"));
+hideElements("#temporary-message");
+showElements(document.querySelector("#temporary-message"));
 ```
 
+`hide` and `show` remain available as deprecated aliases.
+
 #### isValidCssSelector
 
 Check whether a value is a CSS selector supported by the supplied query root.
@@ -1243,18 +1335,18 @@ Output:
 <style>body { background-color: #444; }</style>
 ```
 
-Example 3: Combine `genStyleString` and `injectStyle` to add multiple styles at once.
+Example 3: Combine `createCSSRule` and `injectStyle` to add multiple styles at once.
 
 ```javascript
-import { genStyleString, injectStyle } from "mazey";
+import { createCSSRule, injectStyle } from "mazey";
 
-const xStyle = genStyleString(
+const xStyle = createCSSRule(
   ".footer>.x-wish>a:first-child" +
   ",div.wish-flex>a[href^='https://github.com/chengchuu']" +
   ",.m-hide",
   [ "display: none" ]
 );
-const yStyle = genStyleString(
+const yStyle = createCSSRule(
   ".footer>.y-wish:before",
   [
     `content: 'Copyright (c) chengchuu'`,
@@ -1274,15 +1366,19 @@ Output:
 <style id="z-style">.footer>.x-wish>a:first-child,div.wish-flex>a[href^='https://github.com/chengchuu'],.m-hide{display: none;}.footer>.y-wish:before{content: 'Copyright (c) chengchuu';color: inherit;padding-inline-start: var(--y-wish-1_5);padding-inline-end: var(--y-wish-1_5);padding-top: var(--y-wish-1);padding-bottom: var(--y-wish-1);}</style>
 ```
 
-#### genStyleString
+#### createCSSRule
 
-Generate the inline style string from the given parameters. The first parameter is the query selector, and the second parameter is the style array.
+Create CSS rule text from a selector and an array of declarations. The helper
+joins declarations with semicolons without validating or escaping CSS.
+`genStyleString` remains a deprecated alias.
 
 Usage:
 
 ```javascript
-const ret1 = genStyleString(".a", [ "color:red" ]);
-const ret2 = genStyleString("#b", [ "color:red", "font-size:12px" ]);
+import { createCSSRule } from "mazey";
+
+const ret1 = createCSSRule(".a", [ "color:red" ]);
+const ret2 = createCSSRule("#b", [ "color:red", "font-size:12px" ]);
 console.log(ret1);
 console.log(ret2);
 ```
@@ -1294,18 +1390,18 @@ Output:
 #b{color:red;font-size:12px;}
 ```
 
-Example: Combine `genStyleString` and `injectStyle` to add multiple styles at once.
+Example: Combine `createCSSRule` and `injectStyle` to add multiple styles at once.
 
 ```javascript
-import { genStyleString, injectStyle } from "mazey";
+import { createCSSRule, injectStyle } from "mazey";
 
-const xStyle = genStyleString(
+const xStyle = createCSSRule(
   ".footer>.x-wish>a:first-child" +
   ",div.wish-flex>a[href^='https://github.com/chengchuu']" +
   ",.m-hide",
   [ "display: none" ]
 );
-const yStyle = genStyleString(
+const yStyle = createCSSRule(
   ".footer>.y-wish:before",
   [
     `content: 'Copyright (c) chengchuu'`,
@@ -1435,14 +1531,14 @@ calculateCAGR(
 
 Date strings are validated using Mazey's strict date rules. Invalid dates, malformed or non-finite returns, and non-increasing date ranges throw errors. The parsed total return must be greater than `-1`, because `-1` represents a complete loss for which CAGR is undefined.
 
-#### inRate
+#### randomBoolean
 
-Hit probability (1% ~ 100%).
+Return whether a generated random value is less than the supplied probability.
 
 Usage:
 
 ```javascript
-const ret = inRate(0.5); // 0.01 ~ 1 true/false
+const ret = randomBoolean(0.5); // A 50% chance of returning true.
 console.log(ret);
 ```
 
@@ -1459,7 +1555,7 @@ Example: Test the precision.
 let trueCount = 0;
 let falseCount = 0;
 new Array(1000000).fill(0).forEach(() => {
-  if (inRate(0.5)) {
+  if (randomBoolean(0.5)) {
     trueCount++;
   } else {
     falseCount++;
@@ -1468,6 +1564,9 @@ new Array(1000000).fill(0).forEach(() => {
 console.log(trueCount, falseCount); // 499994 500006
 ```
 
+`randomBoolean` evaluates `Math.random() < rate` without clamping the supplied
+rate. `isHit` is a deprecated alias, and `inRate` remains a compatibility alias.
+
 #### longestComSubstring
 
 Computes the longest common substring of two strings.
@@ -1791,7 +1890,7 @@ reports iOS and Android as `"mobile"`; the new helpers provide a more specific
 phone, tablet, or desktop classification.
 
 `isPhone` checks device form factor. The separate `isMobile` API is a direct
-alias of `isValidPhoneNumber`; it validates an 11-digit Chinese mobile-shaped
+alias of `isCNMobileNumber`; it validates an 11-digit Chinese mobile-shaped
 number and does not inspect the browser or device.
 
 #### isIOS
@@ -1906,6 +2005,20 @@ const { system, shell } = getBrowserInfo();
 const isMobileQQ = ["android", "ios"].includes(system) && ["qq_browser", "qq_app"].includes(shell);
 ```
 
+#### getBrowserClassNames
+
+Return class-name tokens from the cached browser classification. An optional
+prefix and separator apply to each token; the helper does not modify the DOM.
+
+```javascript
+import { getBrowserClassNames } from "mazey";
+
+console.log(getBrowserClassNames("browser"));
+// Possible output: ["browser-windows", "browser-desktop", "browser-webkit", "browser-chrome"]
+```
+
+`genBrowserAttrs` remains a deprecated alias.
+
 #### isSafePWAEnv
 
 Detect whether the current browser document provides the minimum prerequisites

package/README.zh-CN.md

@@ -78,6 +78,7 @@ isNumber(z, { isInfinityAsNumber: true }); // 输出: true
   - [windowLoaded](#windowloaded)
 - [通用工具](#通用工具)
   - [isNumber](#isnumber)
+  - [isNullish](#isnullish)
   - [isJSONString](#isjsonstring)
   - [isValidData](#isvaliddata)
   - [genRndNumString](#genrndnumstring)
@@ -107,6 +108,7 @@ isNumber(z, { isInfinityAsNumber: true }); // 输出: true
   - [Storage 工具](#storage-工具)
 - [DOM](#dom)
   - [Class 工具](#class-工具)
+  - [hideElements 和 showElements](#hideelements-和-showelements)
   - [injectStyle](#injectstyle)
   - [genStyleString](#genstylestring)
   - [newLine](#newline)
@@ -115,7 +117,7 @@ isNumber(z, { isInfinityAsNumber: true }); // 输出: true
 - [计算与公式](#计算与公式)
   - [calculateAspectRatio](#calculateaspectratio)
   - [calculateCAGR](#calculatecagr)
-  - [inRate](#inrate)
+  - [randomBoolean](#randomboolean)
   - [longestComSubstring](#longestcomsubstring)
   - [longestComSubsequence](#longestcomsubsequence)
 - [浏览器信息](#浏览器信息)
@@ -266,6 +268,9 @@ windowLoaded()
 
 ### 通用工具
 
+使用原生 `Date.now()` 获取当前时间戳 (毫秒)。原有的 `mNow()` 工具仍作为弃用兼容 API
+保留。
+
 #### isNumber
 
 判断某个值是否为有效数字。
@@ -289,6 +294,20 @@ console.log(ret1, ret2, ret3, ret4, ret5, ret6);
 true false false true false true
 ```
 
+#### isNullish
+
+判断值是否严格为 `undefined` 或 `null`。其他假值不属于空值。
+
+```javascript
+isNullish(undefined); // true
+isNullish(null); // true
+isNullish(false); // false
+isNullish(0); // false
+isNullish(""); // false
+```
+
+`isUdfOrNul` 仍作为 `isNullish` 的弃用别名保留。
+
 #### isJSONString
 
 判断字符串是否为有效的 JSON 字符串。
@@ -861,6 +880,27 @@ addClass(dom, "test");
 removeClass(dom, "test");
 ```
 
+#### hideElements 和 showElements
+
+隐藏或显示 CSS 选择器、单个元素、可迭代元素集合或类数组元素集合。两个函数都会返回原始输入。
+重复元素只会被修改一次。函数会忽略无效选择器和不支持的值。
+
+`hideElements()` 会保存可见元素的内联 `display` 值。`showElements()` 会恢复该值。如果样式表仍隐藏该元素，函数会恢复元素的默认显示方式。
+
+```javascript
+import { hideElements, showElements } from "mazey";
+
+const notices = document.querySelectorAll(".notice");
+
+hideElements(notices);
+showElements(notices);
+
+hideElements("#temporary-message");
+showElements(document.querySelector("#temporary-message"));
+```
+
+`hide` 和 `show` 仍作为弃用别名保留。
+
 #### injectStyle
 
 在 `<head>` 中添加 `<style>` 元素。
@@ -1092,14 +1132,14 @@ calculateCAGR(
 
 日期字符串遵循 Mazey 的严格日期校验规则。无效日期、格式错误或非有限的回报率，以及没有递增的日期范围都会抛出错误。解析后的总回报率必须大于 `-1`，因为 `-1` 表示本金完全损失，此时 CAGR 没有定义。
 
-#### inRate
+#### randomBoolean
 
-按照指定概率返回命中结果。有效概率范围为 1%～100%。
+判断生成的随机值是否小于指定概率。
 
 用法:
 
 ```javascript
-const ret = inRate(0.5); // 0.01～1，返回 true 或 false
+const ret = randomBoolean(0.5); // 有 50% 的概率返回 true
 console.log(ret);
 ```
 
@@ -1116,7 +1156,7 @@ true
 let trueCount = 0;
 let falseCount = 0;
 new Array(1000000).fill(0).forEach(() => {
-  if (inRate(0.5)) {
+  if (randomBoolean(0.5)) {
     trueCount++;
   } else {
     falseCount++;
@@ -1125,6 +1165,9 @@ new Array(1000000).fill(0).forEach(() => {
 console.log(trueCount, falseCount); // 499994 500006
 ```
 
+`randomBoolean` 直接计算 `Math.random() < rate`，不会限制传入的概率值。`isHit` 是弃用别名。
+`inRate` 仍作为兼容别名保留。
+
 #### longestComSubstring
 
 计算两个字符串的最长公共子串长度。