mazey 5.9.1 → 5.10.0

package/README.md

@@ -78,6 +78,7 @@ 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)
   - [escapeHtmlAttribute](#escapehtmlattribute)
@@ -121,17 +122,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)
-  - [addStyle](#addstyle)
+  - [injectStyle](#injectstyle)
   - [genStyleString](#genstylestring)
   - [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)
@@ -291,6 +294,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
@@ -321,6 +327,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.
@@ -1137,29 +1158,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.
@@ -1202,18 +1225,20 @@ const text = extractElementText(message, {
 });
 ```
 
-#### addStyle
+#### injectStyle
 
 Add `<style>` in `<head>`.
 
+`addStyle` is a deprecated compatibility alias of `injectStyle`.
+
 Usage:
 
 Example 1: Add the `<style>` with `id`, and repeated invoking will update the content instead of adding a new one.
 
 ```javascript
-import { addStyle } from "mazey";
+import { injectStyle } from "mazey";
 
-addStyle(
+injectStyle(
   "body { background-color: #333; }",
   { id: "test" }
 );
@@ -1228,9 +1253,9 @@ Output:
 Example 2: Add the `<style>` without `id`, and repeated invoking will add a new one.
 
 ```javascript
-import { addStyle } from "mazey";
+import { injectStyle } from "mazey";
 
-addStyle("body { background-color: #444; }");
+injectStyle("body { background-color: #444; }");
 ```
 
 Output:
@@ -1239,10 +1264,10 @@ Output:
 <style>body { background-color: #444; }</style>
 ```
 
-Example 3: Combine `genStyleString` and `addStyle` to add multiple styles at once.
+Example 3: Combine `genStyleString` and `injectStyle` to add multiple styles at once.
 
 ```javascript
-import { genStyleString, addStyle } from "mazey";
+import { genStyleString, injectStyle } from "mazey";
 
 const xStyle = genStyleString(
   ".footer>.x-wish>a:first-child" +
@@ -1261,7 +1286,7 @@ const yStyle = genStyleString(
     "padding-bottom: var(--y-wish-1)",
   ]
 );
-addStyle(xStyle + yStyle, { id: "z-style" });
+injectStyle(xStyle + yStyle, { id: "z-style" });
 ```
 
 Output:
@@ -1290,10 +1315,10 @@ Output:
 #b{color:red;font-size:12px;}
 ```
 
-Example: Combine `genStyleString` and `addStyle` to add multiple styles at once.
+Example: Combine `genStyleString` and `injectStyle` to add multiple styles at once.
 
 ```javascript
-import { genStyleString, addStyle } from "mazey";
+import { genStyleString, injectStyle } from "mazey";
 
 const xStyle = genStyleString(
   ".footer>.x-wish>a:first-child" +
@@ -1312,7 +1337,7 @@ const yStyle = genStyleString(
     "padding-bottom: var(--y-wish-1)",
   ]
 );
-addStyle(xStyle + yStyle, { id: "z-style" });
+injectStyle(xStyle + yStyle, { id: "z-style" });
 ```
 
 Output:
@@ -1341,6 +1366,23 @@ a<br />b<br />c
 a<br /><br />bc
 ```
 
+### Event
+
+#### onEvent
+
+Register a named Mazey event callback. Duplicate callbacks are allowed.
+`addEvent` is a deprecated compatibility alias of `onEvent`.
+
+```javascript
+import { fireEvent, onEvent } from "mazey";
+
+onEvent("test", event => {
+  console.log("test event:", event);
+});
+
+fireEvent("test", { type: "test" });
+```
+
 ### Calculate and Formula
 
 #### calculateAspectRatio
@@ -1414,14 +1456,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);
 ```
 
@@ -1438,7 +1480,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++;
@@ -1447,6 +1489,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.

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,13 +108,16 @@ isNumber(z, { isInfinityAsNumber: true }); // 输出: true
   - [Storage 工具](#storage-工具)
 - [DOM](#dom)
   - [Class 工具](#class-工具)
-  - [addStyle](#addstyle)
+  - [hideElements 和 showElements](#hideelements-和-showelements)
+  - [injectStyle](#injectstyle)
   - [genStyleString](#genstylestring)
   - [newLine](#newline)
+- [事件](#事件)
+  - [onEvent](#onevent)
 - [计算与公式](#计算与公式)
   - [calculateAspectRatio](#calculateaspectratio)
   - [calculateCAGR](#calculatecagr)
-  - [inRate](#inrate)
+  - [randomBoolean](#randomboolean)
   - [longestComSubstring](#longestcomsubstring)
   - [longestComSubsequence](#longestcomsubsequence)
 - [浏览器信息](#浏览器信息)
@@ -264,6 +268,9 @@ windowLoaded()
 
 ### 通用工具
 
+使用原生 `Date.now()` 获取当前时间戳 (毫秒)。原有的 `mNow()` 工具仍作为弃用兼容 API
+保留。
+
 #### isNumber
 
 判断某个值是否为有效数字。
@@ -287,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 字符串。
@@ -859,18 +880,41 @@ addClass(dom, "test");
 removeClass(dom, "test");
 ```
 
-#### addStyle
+#### 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>` 元素。
 
+`addStyle` 是 `injectStyle` 的弃用兼容别名。
+
 用法:
 
 示例 1: 添加带有 `id` 的 `<style>`。重复调用会更新内容，不会添加新元素。
 
 ```javascript
-import { addStyle } from "mazey";
+import { injectStyle } from "mazey";
 
-addStyle(
+injectStyle(
   "body { background-color: #333; }",
   { id: "test" }
 );
@@ -885,9 +929,9 @@ addStyle(
 示例 2: 添加不带 `id` 的 `<style>`。重复调用会添加新元素。
 
 ```javascript
-import { addStyle } from "mazey";
+import { injectStyle } from "mazey";
 
-addStyle("body { background-color: #444; }");
+injectStyle("body { background-color: #444; }");
 ```
 
 输出:
@@ -896,10 +940,10 @@ addStyle("body { background-color: #444; }");
 <style>body { background-color: #444; }</style>
 ```
 
-示例 3: 组合使用 `genStyleString` 和 `addStyle`，一次添加多条样式。
+示例 3: 组合使用 `genStyleString` 和 `injectStyle`，一次添加多条样式。
 
 ```javascript
-import { genStyleString, addStyle } from "mazey";
+import { genStyleString, injectStyle } from "mazey";
 
 const xStyle = genStyleString(
   ".footer>.x-wish>a:first-child" +
@@ -918,7 +962,7 @@ const yStyle = genStyleString(
     "padding-bottom: var(--y-wish-1)",
   ]
 );
-addStyle(xStyle + yStyle, { id: "z-style" });
+injectStyle(xStyle + yStyle, { id: "z-style" });
 ```
 
 输出:
@@ -947,10 +991,10 @@ console.log(ret2);
 #b{color:red;font-size:12px;}
 ```
 
-下面的示例组合使用 `genStyleString` 和 `addStyle`，一次添加多条样式。
+下面的示例组合使用 `genStyleString` 和 `injectStyle`，一次添加多条样式。
 
 ```javascript
-import { genStyleString, addStyle } from "mazey";
+import { genStyleString, injectStyle } from "mazey";
 
 const xStyle = genStyleString(
   ".footer>.x-wish>a:first-child" +
@@ -969,7 +1013,7 @@ const yStyle = genStyleString(
     "padding-bottom: var(--y-wish-1)",
   ]
 );
-addStyle(xStyle + yStyle, { id: "z-style" });
+injectStyle(xStyle + yStyle, { id: "z-style" });
 ```
 
 输出:
@@ -998,6 +1042,23 @@ a<br />b<br />c
 a<br /><br />bc
 ```
 
+### 事件
+
+#### onEvent
+
+注册具名的 Mazey 事件回调。函数允许重复注册同一个回调。
+`addEvent` 是 `onEvent` 的弃用兼容别名。
+
+```javascript
+import { fireEvent, onEvent } from "mazey";
+
+onEvent("test", event => {
+  console.log("test event:", event);
+});
+
+fireEvent("test", { type: "test" });
+```
+
 ### 计算与公式
 
 #### calculateAspectRatio
@@ -1071,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);
 ```
 
@@ -1095,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++;
@@ -1104,6 +1165,9 @@ new Array(1000000).fill(0).forEach(() => {
 console.log(trueCount, falseCount); // 499994 500006
 ```
 
+`randomBoolean` 直接计算 `Math.random() < rate`，不会限制传入的概率值。`isHit` 是弃用别名。
+`inRate` 仍作为兼容别名保留。
+
 #### longestComSubstring
 
 计算两个字符串的最长公共子串长度。