mazey 4.13.2 → 5.0.1

package/lib/index.d.ts

@@ -143,7 +143,7 @@ type SingleValueUrlParams = {
 
 type ThrottleFunc<T extends (...args: any[]) => any> = (...args: Parameters<T>) => ReturnType<T> | null;
 
-type DebounceFunc<T extends (...args: any[]) => any> = (...args: Parameters<T>) => ReturnType<T>;
+type DebounceFunc<T extends (...args: any[]) => any> = (...args: Parameters<T>) => ReturnType<T> | null;
 
 interface IsNumberOptions {
   isNaNAsNumber?: boolean;
@@ -170,7 +170,7 @@ interface RepeatUntilOptions {
   args?: Array<any>;
 }
 
-type LoadScriptReturns = Promise<boolean | string | Error | void>;
+type LoadScriptReturns = Promise<string>;
 
 type SimpleType = string | number | boolean | null | undefined;
 
@@ -203,6 +203,9 @@ interface OnURLChangeOptions {
 /**
  * Copy/Clone Object deeply.
  *
+ * Custom class instances are copied as plain objects containing their own
+ * properties. Unsupported native instances are preserved by reference.
+ *
  * Usage:
  *
  * ```javascript
@@ -578,7 +581,7 @@ declare function floatToPercent(num: number, fixSize?: number): string;
  *
  * @category Util
  */
-declare function floatFixed(num: string, size?: number): string;
+declare function floatFixed(num: number | string, size?: number): string;
 /**
  * EN: Throttle, used to limit the frequency of function execution over time.
  *
@@ -621,37 +624,56 @@ declare function throttle<T extends (...args: MazeyFnParams) => MazeyFnReturn>(f
  */
 declare function debounce<T extends (...args: MazeyFnParams) => MazeyFnReturn>(func: T, wait: number, immediate?: boolean): DebounceFunc<T>;
 /**
- * EN: Get interval time.
+ * Calculate the interval between two dates or timestamps.
  *
- * ZH: 获取间隔时间。
+ * The default `d` type returns the number of whole days. The `text` type
+ * returns an English duration using days, hours, minutes, and seconds while
+ * omitting zero-valued units. A zero interval returns `"0 seconds"`. Any other
+ * type returns the number of whole seconds. Negative intervals and invalid
+ * dates return an empty string.
  *
  * Usage:
  *
  * ```javascript
- * import { getFriendlyInterval } from "mazey";
+ * import { getDateDifference } from "mazey";
  *
- * const ret1 = getFriendlyInterval(new Date("2020-03-28 00:09:27"), new Date("2023-04-18 10:54:00"), { type: "d" });
- * const ret2 = getFriendlyInterval(1585325367000, 1681786440000, { type: "text" });
- * const ret3 = getFriendlyInterval("2020-03-28 00:09:27", "2023-04-18 10:54:00", { type: "text" });
- * console.log(ret1);
- * console.log(ret2);
- * console.log(ret3);
+ * const days = getDateDifference(0, 90061000);
+ * const text = getDateDifference(0, 90061000, { type: "text" });
+ * const compactText = getDateDifference(0, 90060000, { type: "text" });
+ * const dateStringDays = getDateDifference(
+ *   "2020-03-28 00:09:27",
+ *   "2023-04-18 10:54:00"
+ * );
+ * console.log(days);
+ * console.log(text);
+ * console.log(compactText);
+ * console.log(dateStringDays);
  * ```
  *
  * Output:
  *
  * ```text
+ * 1
+ * 1 day 1 hour 1 minute 1 second
+ * 1 day 1 hour 1 minute
  * 1116
- * 1116 天 10 时 44 分 33 秒
- * 1116 天 10 时 44 分 33 秒
  * ```
  *
- * @param {number/Date} start 开始时间戳 1585325367122
- * @param {number/Date} end 结束时间戳 1585325367122
- * @param {string} options.type 返回类型 d: 2(天) text: 2 天 4 时...
- * @returns {string/number} 取决于 type
+ * @param start Start date or timestamp.
+ * @param end End date or timestamp.
+ * @param options Formatting options. Use `d` for whole days or `text` for an English duration.
+ * @returns Whole days, whole seconds, an English duration, or an empty string for a negative or invalid interval.
+ * @remarks Strings in `YYYY-MM-DD HH:mm:ss` format are normalized and parsed as local time. Other date strings use the runtime's native `Date` parser; use timestamps or ISO strings with an explicit timezone when parsing must be portable.
  * @category Util
  */
+declare function getDateDifference(start?: number | string | Date, end?: number | string | Date, options?: {
+    type?: string;
+}): number | string;
+/**
+ * Alias of `getDateDifference`.
+ *
+ * @hidden
+ */
 declare function getFriendlyInterval(start?: number | string | Date, end?: number | string | Date, options?: {
     type?: string;
 }): number | string;
@@ -704,8 +726,7 @@ declare function formatDurationFromMs(durationMs: number): string;
  * ```
  *
  * @param {*} num 被判断的值
- * @param {boolean} options.isNaNAsNumber 是否 NaN 算数字（默认不算）
- * @param {boolean} options.isInfinityAsNumber 是否 无限 算数字（默认不算）
+ * @param options Controls whether `NaN`, `Infinity`, or other non-finite values count as numbers.
  * @returns {boolean} true 是数字
  * @category Util
  */
@@ -728,13 +749,13 @@ declare function isNumber(num: unknown, options?: IsNumberOptions): boolean;
  * @param {function} fn 等待被执行的未知是否有效的函数
  * @category Util
  */
-declare function invokeFn(fn: MazeyFunction, ...params: Parameters<MazeyFunction>): ReturnType<MazeyFunction> | null;
+declare function invokeFn(fn: MazeyFunction | null | undefined, ...params: Parameters<MazeyFunction>): ReturnType<MazeyFunction> | null;
 /**
  * Alias of `invokeFn`.
  *
  * @hidden
  */
-declare function doFn(fn: MazeyFunction, ...params: Parameters<MazeyFunction>): ReturnType<MazeyFunction> | null;
+declare function doFn(fn: MazeyFunction | null | undefined, ...params: Parameters<MazeyFunction>): ReturnType<MazeyFunction> | null;
 /**
  * Verify the validity of a non-empty array.
  *
@@ -1099,7 +1120,7 @@ declare function unsanitize(str: string): string;
  * @returns {string} 返回截取后的字符串
  * @category Util
  */
-declare function cutZHString(str: string, len: number, options?: {
+declare function cutZHString(str: string | null | undefined, len: number, options?: {
     hasDot?: boolean;
     dotText?: string;
 }): string;
@@ -1126,13 +1147,13 @@ declare function cutZHString(str: string, len: number, options?: {
  * @returns {string} 返回截取后的字符串
  * @hidden
  */
-declare function truncateZHString(str: string, len: number, hasDot?: boolean): string;
+declare function truncateZHString(str: string | null | undefined, len: number, hasDot?: boolean): string;
 /**
  * Alias of `truncateZHString`.
  *
  * @hidden
  */
-declare function cutCHSString(str: string, len: number, hasDot?: boolean): string;
+declare function cutCHSString(str: string | null | undefined, len: number, hasDot?: boolean): string;
 /**
  * Verify the validity of axios response.
  *
@@ -1141,7 +1162,7 @@ declare function cutCHSString(str: string, len: number, hasDot?: boolean): strin
  * @category Util
  * @hidden
  */
-declare function zAxiosIsValidRes(res: ZResResponse | undefined, options?: ZResIsValidResOptions): boolean;
+declare function zAxiosIsValidRes(res: ZResResponse | undefined, options?: ZResIsValidResOptions | null): boolean;
 /**
  * Determine the validity of the data.
  *
@@ -1226,9 +1247,61 @@ declare function getFileSize(size: number): string;
  * @category Util
  */
 declare function genHashCode(str: string): number;
+/**
+ * Check whether an unknown value represents a valid date.
+ *
+ * Valid inputs include `Date` instances, finite millisecond timestamps,
+ * structured local date strings, and ISO 8601 strings with `Z` or a numeric
+ * timezone offset. Structured strings are parsed into numeric components and
+ * validated strictly, so invalid calendar dates are not normalized.
+ *
+ * Supported string forms are `YYYY-MM-DD`, `YYYY-MM-DD HH:mm[:ss]`,
+ * `YYYY-MM-DDTHH:mm[:ss]`, and the same `T`-separated date-time with `Z` or
+ * a `+HH:mm`/`-HH:mm` offset. Zoned strings may include 1-3 millisecond digits.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { isValidDate } from "mazey";
+ *
+ * const ret1 = isValidDate(1577877720000);
+ * const ret2 = isValidDate("2020-01-01 11:22");
+ * const ret3 = isValidDate("2020-02-30");
+ * const ret4 = isValidDate(new Date("invalid"));
+ *
+ * console.log(ret1, ret2, ret3, ret4);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true true false false
+ * ```
+ *
+ * @param value A `Date`, millisecond timestamp, or supported structured date string.
+ * @returns Whether the value represents a valid date.
+ * @category Util
+ */
+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
@@ -1253,14 +1326,15 @@ declare function genHashCode(str: string): number;
  * 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
  */
 declare function formatDate(dateIns?: MazeyDate, format?: string): string;
 /**
- * Generate a Calendar Versioning string from a date.
+ * Generate a local-time Calendar Versioning string from a date.
  *
  * The conceptual format is `yyyy.MMdd.HHmmss`. Leading zeroes are removed
  * from each segment to keep numeric Semantic Versioning identifiers valid.
@@ -1282,6 +1356,7 @@ declare function formatDate(dateIns?: MazeyDate, format?: string): string;
  *
  * @param {MazeyDate} dateIns Original date. Defaults to the current date.
  * @returns {string} Return the generated calendar version.
+ * @throws {RangeError} If `dateIns` is not a valid date.
  * @category Util
  */
 declare function generateCalendarVersion(dateIns?: MazeyDate): string;
@@ -1391,11 +1466,7 @@ declare function getCurrentVersion(): string;
  * ```
  *
  * @param callback The callback function to fire.
- * @param options An object containing the options for the function.
- * @param options.interval The interval between each firing of the callback function, in milliseconds. Defaults to 1000.
- * @param options.times The maximum number of times to fire the callback function. Defaults to 10.
- * @param options.context The context to use when calling the callback function. Defaults to null.
- * @param options.args An array of arguments to pass to the callback function.
+ * @param options Controls the interval, maximum invocation count, callback context, and callback arguments.
  * @param condition A function that takes the result of the callback function as its argument and returns a boolean value indicating whether the condition has been met. Defaults to a function that always returns true.
  * @category Util
  */
@@ -2214,7 +2285,7 @@ declare function fireEvent(type: string, params?: MazeyObject): void;
  *
  * @hidden
  */
-declare function invokeEvent(type: string): void;
+declare function invokeEvent(type: string, params?: MazeyObject): void;
 /**
  * Remove event.
  *
@@ -2230,7 +2301,7 @@ declare function invokeEvent(type: string): void;
  * @param fn
  * @category Event
  */
-declare function removeEvent(type: string, fn: MazeyFn): void;
+declare function removeEvent(type: string, fn?: MazeyFn): void;
 
 /**
  * EN: Handle Storage (Keep fit for JSON, it can transfer format automatically).
@@ -2503,7 +2574,7 @@ declare function delCookie(name: string): void;
  */
 declare function loadCSS(url: string, options?: {
     id?: string;
-}): Promise<unknown>;
+}): Promise<string>;
 /**
  * EN: Load a JavaScript file from the server and execute it.
  *
@@ -2590,7 +2661,7 @@ declare function loadScript(url: string, options?: {
  * @returns {Promise<string>} document is loaded? "complete" "load" / "timeout"
  * @category Load
  */
-declare function windowLoaded(timeout?: number): Promise<string | Error>;
+declare function windowLoaded(timeout?: number): Promise<string>;
 /**
  * Load an image from the given URL.
  *
@@ -2815,7 +2886,6 @@ declare function getTTFB(): Promise<number>;
  * @remarks
  * This function uses the [`PerformanceNavigationTiming`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming) API to get page load time data.
  * The `PerformanceNavigationTiming` API provides more accurate and detailed information about page load time than the deprecated [`PerformanceTiming`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceTiming) API.
- * If you are using an older browser that does not support `PerformanceNavigationTiming`, you can still use the `PerformanceTiming` API by using the previous version of this library ([`v3.9.7`](https://github.com/chengchuu/mazey/releases/tag/v3.9.7)).
  *
  * Usage:
  *
@@ -2857,7 +2927,7 @@ declare function getTTFB(): Promise<number>;
  * @returns {Promise<object>} 加载数据
  * @category Perf
  */
-declare function getPerformance(camelCase?: boolean): Promise<WebPerformance | Error>;
+declare function getPerformance(camelCase?: boolean): Promise<WebPerformance>;
 
 /**
  * Detect whether the current browser document provides the minimum
@@ -2886,7 +2956,7 @@ declare function getPerformance(camelCase?: boolean): Promise<WebPerformance | E
  * true
  * ```
  *
- * @environment Browser
+ * @remarks Browser only.
  * @returns Whether the detectable minimum PWA prerequisites are satisfied.
  * @category Browser Information
  */
@@ -2933,7 +3003,7 @@ declare function isSafePWAEnv(): boolean;
  * const isMobileQQ = ["android", "ios"].includes(system) && ["qq_browser", "qq_app"].includes(shell);
  * ```
  *
- * @environment Browser
+ * @remarks Browser only.
  * @returns Browser information
  * @category Browser Information
  */
@@ -2958,7 +3028,7 @@ declare function getBrowserInfo(): BrowserInfo;
  * ["windows", "desktop", "webkit", "chrome"]
  * ```
  *
- * @environment Browser
+ * @remarks Browser only.
  * @param {string} prefix
  * @returns {array} Browser attributes
  * @category Browser Information
@@ -3063,4 +3133,4 @@ declare const mazeyCon: Console;
  */
 declare const timeCon: Console;
 
-export { addClass, addEvent, addStyle, calLongestCommonSubsequence, calLongestCommonSubstring, camelCase2Underscore, camelCaseToKebabCase, cancelBubble, clearHTML, clearHtml, convert10To26, convertCamelToKebab, convertCamelToUnder, convertHttpToHttps, convertKebabToCamel, convertObjectToQuery, convertToHtmlBreaks, convertUnderToCamel, cutCHSString, cutZHString, debounce, deepCopy, deepCopyObject, deepFreeze, delCookie, doFn, fireEvent, floatFixed, floatToPercent, formatDate, formatDurationFromMs, genBrowserAttrs, genCustomConsole, genHashCode, genRndNumString, genStyleString, genUniqueNumString, generateCalendarVersion, generateRndNum, generateUniqueNum, getAllQueryParams, getBrowserInfo, getCLS, getCookie, getCurrentVersion, getDefineListeners, getDomain, getFCP, getFID, getFP, getFileSize, getFriendlyInterval, getHashQueryParam, getLCP, getLocalStorage, getPageMeta, getPerformance, getQueryParam, getScriptQueryParam, getSessionStorage, getTTFB, getUrlFileType, getUrlHost, getUrlParam, getUrlPath, hasClass, inRate, invokeEvent, invokeFn, isArray, isBool, isBoolean, isBrowser, isFunction, isHit, isJSONString, isJsonString, isNonEmptyArray, isNonEmptyObject, isNumber, isPureObject, isSafePWAEnv, isString, isSupportWebp, isSupportedEntryType, isUdfOrNul, isValidData, isValidEmail, isValidHttpUrl, isValidPhoneNumber, isValidUrl, loadCSS, loadImage, loadScript, loadScriptIfUndefined, longestComSubsequence, longestComSubstring, mNow, mTrim, mazeyCon, newLine, onURLChange, removeClass, removeCookie, removeEvent, removeHTML, removeHtml, repeatUntilConditionMet, replaceHttp, sanitizeInput, setClass, setCookie, setImgSizeBySrc, setImgWidHeiBySrc, setLocalStorage, setSessionStorage, sleep, throttle, timeCon, truncateZHString, unsanitize, unsanitizeInput, updateQueryParam, waitTime, windowLoaded, zAxiosIsValidRes };
+export { addClass, addEvent, addStyle, calLongestCommonSubsequence, calLongestCommonSubstring, camelCase2Underscore, camelCaseToKebabCase, cancelBubble, clearHTML, clearHtml, convert10To26, convertCamelToKebab, convertCamelToUnder, convertHttpToHttps, convertKebabToCamel, convertObjectToQuery, convertToHtmlBreaks, convertUnderToCamel, cutCHSString, cutZHString, debounce, deepCopy, deepCopyObject, deepFreeze, delCookie, doFn, fireEvent, floatFixed, floatToPercent, formatDate, formatDurationFromMs, genBrowserAttrs, genCustomConsole, genHashCode, genRndNumString, genStyleString, genUniqueNumString, generateCalendarVersion, generateRndNum, generateUniqueNum, getAllQueryParams, getBrowserInfo, getCLS, getCookie, getCurrentVersion, getDateDifference, getDefineListeners, getDomain, getFCP, getFID, getFP, getFileSize, getFriendlyInterval, getHashQueryParam, getLCP, getLocalStorage, getPageMeta, getPerformance, getQueryParam, getScriptQueryParam, getSessionStorage, getTTFB, getUrlFileType, getUrlHost, getUrlParam, getUrlPath, hasClass, inRate, invokeEvent, invokeFn, isArray, isBool, isBoolean, isBrowser, isFunction, isHit, isJSONString, isJsonString, isNonEmptyArray, isNonEmptyObject, isNumber, isPureObject, isSafePWAEnv, isString, isSupportWebp, isSupportedEntryType, isUdfOrNul, isValidData, isValidDate, isValidEmail, isValidHttpUrl, isValidPhoneNumber, isValidUrl, loadCSS, loadImage, loadScript, loadScriptIfUndefined, longestComSubsequence, longestComSubstring, mNow, mTrim, mazeyCon, newLine, onURLChange, removeClass, removeCookie, removeEvent, removeHTML, removeHtml, repeatUntilConditionMet, replaceHttp, sanitizeInput, setClass, setCookie, setImgSizeBySrc, setImgWidHeiBySrc, setLocalStorage, setSessionStorage, sleep, throttle, timeCon, truncateZHString, unsanitize, unsanitizeInput, updateQueryParam, waitTime, windowLoaded, zAxiosIsValidRes };