mazey 4.0.7 → 4.1.1

package/lib/util.d.ts

@@ -0,0 +1,841 @@
+import type { ThrottleFunc, DebounceFunc, IsNumberOptions, ZResResponse, ZResIsValidResOptions, SimpleType, MazeyObject, MazeyFnParams, MazeyFnReturn, MazeyFunction, RepeatUntilOptions } from "./typing";
+/**
+ * Copy/Clone Object deeply.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret1 = deepCopy(['a', 'b', 'c']);
+ * const ret2 = deepCopy('abc');
+ * console.log(ret1);
+ * console.log(ret2);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * ['a', 'b', 'c']
+ * abc
+ * ```
+ *
+ * @param {object} obj The value to clone.
+ * @returns {object} Returns the deep cloned value.
+ * @category Util
+ */
+export declare function deepCopy<T>(obj: T): T;
+/**
+ * Alias of `deepCopy`.
+ *
+ * @hidden
+ */
+export declare function deepCopyObject<T>(obj: T): T;
+/**
+ * Transfer CamelCase to KebabCase.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret1 = convertCamelToKebab('ABC');
+ * const ret2 = convertCamelToKebab('aBC');
+ * console.log(ret1);
+ * console.log(ret2);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * a-b-c
+ * a-b-c
+ * ```
+ *
+ * @param {string} camelCase 'aBC' or 'ABC'
+ * @returns {string} 'a-b-c'
+ * @category Util
+ */
+export declare function convertCamelToKebab(camelCase: string): string;
+/**
+ * Convert CamelCase to KebabCase.
+ *
+ * @param {string} kebabCase
+ * @returns {string}
+ * @category Util
+ */
+export declare function convertKebabToCamel(kebabCase: string): string;
+/**
+ * Alias of `convertCamelToKebab`.
+ *
+ * @hidden
+ */
+export declare function camelCaseToKebabCase(camelCase: string): string;
+/**
+ * Transfer CamelCase to Underscore.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret1 = convertCamelToUnder('ABC');
+ * const ret2 = convertCamelToUnder('aBC');
+ * console.log(ret1);
+ * console.log(ret2);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * a_b_c
+ * a_b_c
+ * ```
+ *
+ * @param {string} camelCase 'aBC' or 'ABC'
+ * @returns {string} 'a_b_c'
+ * @category Util
+ */
+export declare function convertCamelToUnder(camelCase: string): string;
+/**
+ * Alias of `convertCamelToUnder`.
+ *
+ * @hidden
+ */
+export declare function camelCase2Underscore(camelCase: string): string;
+/**
+ * Remove leading and trailing whitespace or specified characters from string.
+ *
+ * Note: This method is used to replace the native `String.prototype.trim()`. But it is not necessary to use it in modern browsers.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret1 = mTrim(' 1 2 3 ');
+ * const ret2 = mTrim('abc ');
+ * console.log(ret1);
+ * console.log(ret2);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * 1 2 3
+ * abc
+ * ```
+ *
+ * @param {string} str The string to trim.
+ * @returns {string} Trimmed string.
+ * @category Util
+ * @hidden
+ */
+export declare function mTrim(str: string): string;
+/**
+ * Check whether it is a valid JSON string.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret1 = isJSONString(`['a', 'b', 'c']`);
+ * const ret2 = isJSONString(`["a", "b", "c"]`);
+ * console.log(ret1);
+ * console.log(ret2);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * false
+ * true
+ * ```
+ *
+ * @param {string} str The string to check.
+ * @returns {boolean} Return the result of checking.
+ * @category Util
+ */
+export declare function isJSONString(str: string): boolean;
+/**
+ * Alias of `isJSONString`.
+ *
+ * @hidden
+ */
+export declare function isJsonString(str: string): boolean;
+/**
+ * Produce a random string of number, `genRndNumString(7)` => '7658495'.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret1 = genRndNumString(4);
+ * const ret2 = genRndNumString(7);
+ * console.log(ret1);
+ * console.log(ret2);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * 9730
+ * 2262490
+ * ```
+ *
+ * @param {number} n Length
+ * @returns {string} Return the random string.
+ * @category Util
+ */
+export declare function genRndNumString(n?: number): string;
+/**
+ * Alias of `genRndNumString`.
+ *
+ * @hidden
+ */
+export declare function generateRndNum(n?: number): string;
+/**
+ * EN: Generate a unique identifier number based on time: `genUniqueNumString()` => `1538324722364123`
+ *
+ * ZH: 根据时间生成唯一标志的数字：`genUniqueNumString()` => `1538324722364123`
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret1 = genUniqueNumString();
+ * const ret2 = genUniqueNumString(3);
+ * console.log(ret1);
+ * console.log(ret2);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * 1538324722364123
+ * 1538324722364123
+ * ```
+ *
+ * @param {number} n 随机数的长度
+ * @category Util
+ */
+export declare function genUniqueNumString(n?: number): string;
+/**
+ * Alias of `genUniqueNumString`.
+ *
+ * @hidden
+ */
+export declare function generateUniqueNum(n?: number): string;
+/**
+ * EN: Get timestamp.
+ *
+ * ZH: 获取时间戳
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret = mNow();
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * 1585325367122
+ * ```
+ *
+ * @category Util
+ */
+export declare function mNow(): number;
+/**
+ * EN: Floating point number to percentage 0.2 => 20%
+ *
+ * ZH: 浮点数转为百分比 0.2 => 20%
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret1 = floatToPercent(0.2);
+ * const ret2 = floatToPercent(0.2, 2);
+ * console.log(ret1);
+ * console.log(ret2);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * 20%
+ * 20.00%
+ * ```
+ *
+ * @param {number} num 浮点数
+ * @param {number} fixSize 保留几位浮点数
+ * @category Util
+ */
+export declare function floatToPercent(num: number, fixSize?: number): string;
+/**
+ * 浮点数保留指定位
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret1 = floatFixed(0.2);
+ * const ret2 = floatFixed(0.2, 2);
+ * console.log(ret1);
+ * console.log(ret2);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * 0
+ * 0.20
+ * ```
+ *
+ * @category Util
+ */
+export declare function floatFixed(num: string, size?: number): string;
+/**
+ * EN: Throttle
+ *
+ * ZH: 节流
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const foo = throttle(() => {
+ *   console.log('The function will be invoked at most once per every wait 1000 milliseconds.');
+ * }, 1000, { leading: true });
+ * ```
+ *
+ * Reference: [Lodash](https://lodash.com/docs/4.17.15#throttle)
+ *
+ * @category Util
+ */
+export declare function throttle<T extends (...args: MazeyFnParams) => MazeyFnReturn>(func: T, wait: number, options?: {
+    leading?: boolean;
+    trailing?: boolean;
+}): ThrottleFunc<T>;
+/**
+ * EN: Debounce
+ *
+ * ZH: 去抖
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const foo = debounce(() => {
+ *   console.log('The debounced function will only be invoked in 1000 milliseconds, the other invoking will disappear during the wait time.');
+ * }, 1000, true);
+ * ```
+ *
+ * @category Util
+ */
+export declare function debounce<T extends (...args: MazeyFnParams) => MazeyFnReturn>(func: T, wait: number, immediate?: boolean): DebounceFunc<T>;
+/**
+ * 获取间隔时间
+ *
+ * Usage:
+ *
+ * ```javascript
+ * 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);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * 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
+ * @category Util
+ */
+export declare function getFriendlyInterval(start?: number | string | Date, end?: number | string | Date, options?: {
+    type?: string;
+}): number | string;
+/**
+ * EN: Check whether it is a right number.
+ *
+ * ZH: 判断是否有效数字
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret1 = isNumber(123);
+ * const ret2 = isNumber('123');
+ * // Default: NaN, Infinity is not Number
+ * const ret3 = isNumber(Infinity);
+ * const ret4 = isNumber(Infinity, { isInfinityAsNumber: true });
+ * const ret5 = isNumber(NaN);
+ * const ret6 = isNumber(NaN, { isNaNAsNumber: true, isInfinityAsNumber: true });
+ * console.log(ret1, ret2, ret3, ret4, ret5, ret6);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true false false true false true
+ * ```
+ *
+ * @param {*} num 被判断的值
+ * @param {boolean} options.isNaNAsNumber 是否 NaN 算数字（默认不算）
+ * @param {boolean} options.isInfinityAsNumber 是否 无限 算数字（默认不算）
+ * @returns {boolean} true 是数字
+ * @category Util
+ */
+export declare function isNumber(num: unknown, options?: IsNumberOptions): boolean;
+/**
+ * 执行有效函数
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret = invokeFn(() => {
+ *  console.log('invokeFn');
+ * });
+ * ```
+ *
+ * @param {function} fn 等待被执行的未知是否有效的函数
+ * @category Util
+ */
+export declare function invokeFn(fn: MazeyFunction, ...params: Parameters<MazeyFunction>): ReturnType<MazeyFunction> | null;
+/**
+ * Alias of `invokeFn`.
+ *
+ * @hidden
+ */
+export declare function doFn(fn: MazeyFunction, ...params: Parameters<MazeyFunction>): ReturnType<MazeyFunction> | null;
+/**
+ * Verify the validity of a non-empty array.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret = isNonEmptyArray([1, 2, 3]);
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true
+ * ```
+ *
+ * @category Util
+ */
+export declare function isNonEmptyArray<T>(arr: Array<T>): boolean;
+/**
+ * Convert newline characters `\n` into HTML line breaks `<br />`.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret1 = convertToHtmlBreaks('a\nb\nc');
+ * const ret2 = convertToHtmlBreaks('a\n\nbc');
+ * console.log(ret1);
+ * console.log(ret2);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * a<br />b<br />c
+ * a<br /><br />bc
+ * ```
+ *
+ * @param {string} str The string to make a new line.
+ * @returns {string} A newline with `br`.
+ * @category Util
+ */
+export declare function convertToHtmlBreaks(str: string): string;
+/**
+ * Alias of `convertToHtmlBreaks`.
+ *
+ * @hidden
+ */
+export declare function newLine(str: string): string;
+/**
+ * Remove HTML tags from a string, and optionally newline characters.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret = removeHtml('<div>hello world</div>');
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * hello world
+ * ```
+ *
+ * @param {string} str 带 HTML 标签的字符串
+ * @returns {string} 字符串
+ * @category Util
+ */
+export declare function removeHtml(str: string, options?: {
+    removeNewLine?: boolean;
+}): string;
+/**
+ * Alias of `removeHtml`.
+ *
+ * @hidden
+ */
+export declare function clearHtml(str: string, options?: {
+    removeNewLine?: boolean;
+}): string;
+/**
+ * Sanitizes user input to prevent XSS attacks.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret = sanitizeInput('<div>hello world</div>');
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * &lt;div&gt;hello world&lt;/div&gt;
+ * ```
+ *
+ * @param input - The input string to sanitize
+ * @returns The sanitized input string
+ * @category Util
+ */
+export declare function sanitizeInput(input: string): string;
+/**
+ * Reverses the sanitization done by the `sanitizeInput` function.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret = unsanitizeInput('&lt;div&gt;hello world&lt;/div&gt;');
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * <div>hello world</div>
+ * ```
+ *
+ * @param input - The input string to unsanitize
+ * @returns The unsanitized input string
+ * @category Util
+ */
+export declare function unsanitizeInput(input: string): string;
+/**
+ * Alias of `unsanitizeInput`.
+ *
+ * @hidden
+ */
+export declare function unsanitize(str: string): string;
+/**
+ * 截取字符串，中文算 2 个字节
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret = cutZHString('hello world', 5);
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * hello
+ * ```
+ *
+ * @param {string} str 要截取的字符串
+ * @param {number} len
+ * @param {boolean} options.hasDot
+ * @param {string} options.dotText
+ * @returns {string} 返回截取后的字符串
+ * @category Util
+ */
+export declare function cutZHString(str: string, len: number, options?: {
+    hasDot?: boolean;
+    dotText?: string;
+}): string;
+/**
+ * Alias of `cutZHString`.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret = truncateZHString('hello world', 5);
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * hello
+ *
+ * @param {string} str 要截取的字符串
+ * @param {number} len
+ * @param {boolean} hasDot
+ * @returns {string} 返回截取后的字符串
+ * @hidden
+ */
+export declare function truncateZHString(str: string, len: number, hasDot?: boolean): string;
+/**
+ * Alias of `truncateZHString`.
+ *
+ * @hidden
+ */
+export declare function cutCHSString(str: string, len: number, hasDot?: boolean): string;
+/**
+ * Verify the validity of axios response.
+ *
+ * Reference: [Handling Errors](https://axios-http.com/docs/handling_errors)
+ *
+ * @category Util
+ * @hidden
+ */
+export declare function zAxiosIsValidRes(res: ZResResponse | undefined, options?: ZResIsValidResOptions): boolean;
+/**
+ * Determine the validity of the data.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const validData = {
+ *   a: {
+ *     b: {
+ *       c: 413
+ *     }
+ *   }
+ * };
+ * const isValidDataResA = isValidData(validData, ['a', 'b', 'c'], 2333);
+ * const isValidDataResB = isValidData(validData, ['a', 'b', 'c'], 413);
+ * const isValidDataResC = isValidData(validData, ['d', 'd'], 413);
+ * console.log('isValidDataResA:', isValidDataResA);
+ * console.log('isValidDataResB:', isValidDataResB);
+ * console.log('isValidDataResC:', isValidDataResC);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * isValidDataResA: false
+ * isValidDataResB: true
+ * isValidDataResC: false
+ * ```
+ *
+ * @param {any} data Original Data
+ * @param {string[]} attributes Data Attributes
+ * @param {any} validValue Given Value for verifying.
+ * @returns {boolean} Return TRUE if the data is valid.
+ * @category Util
+ */
+export declare function isValidData(data: MazeyObject, attributes: string[], validValue: SimpleType): boolean;
+/**
+ * 语义化文件大小，把字节转换成正常文件大小。
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret = getFileSize(1024);
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * 1 KB
+ * ```
+ *
+ * @category Util
+ */
+export declare function getFileSize(size: number): string;
+/**
+ * Generate a Hash Code from a string.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret = genHashCode('hello world');
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * 1794106052
+ * ```
+ *
+ * Reference: [Generate a Hash from string in Javascript](https://stackoverflow.com/questions/7616461/generate-a-hash-from-string-in-javascript-jquery)
+ *
+ * @category Util
+ */
+export declare function genHashCode(str: string): number;
+/**
+ * Return the formatted date string in the given format.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret1 = formatDate();
+ * const ret2 = formatDate('Tue Jan 11 2022 14:12:26 GMT+0800 (China Standard Time)', 'yyyy-MM-dd hh:mm:ss');
+ * const ret3 = formatDate(1641881235000, 'yyyy-MM-dd hh:mm:ss');
+ * const ret4 = formatDate(new Date(2014, 1, 11), 'MM/dd/yyyy');
+ * console.log('Default formatDate value:', ret1);
+ * console.log('String formatDate value:', ret2);
+ * console.log('Number formatDate value:', ret3);
+ * console.log('Date formatDate value:', ret4);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * Default formatDate value: 2023-01-11
+ * String formatDate value: 2022-01-11 14:12:26
+ * Number formatDate value: 2022-01-11 14:07:15
+ * Date formatDate value: 02/11/2014
+ * ```
+ *
+ * @param {Date|number|string} dateIns Original Date
+ * @param {string} format Format String
+ * @returns {string} Return the formatted date string.
+ * @category Util
+ */
+export declare function formatDate(dateIns?: Date | number | string, format?: string): string;
+/**
+ * Check if the given string is a mobile phone number.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret1 = isMobile('13800138000');
+ * const ret2 = isMobile('1380013800');
+ * const ret3 = isMobile('138001380000');
+ * const ret4 = isMobile('1380013800a');
+ * console.log(ret1, ret2, ret3, ret4);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true false false false
+ * ```
+ *
+ * @param mobile
+ * @returns {boolean} Return true if the given string is a mobile phone number.
+ * @category Util
+ */
+export declare function isValidPhoneNumber(mobile: string): boolean;
+/**
+ * Check if the given string is a valid email.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret = isValidEmail('mazeyqian@gmail.com');
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true
+ * ```
+ *
+ * @param email
+ * @returns {boolean} Return true if the given string is a valid email.
+ * @category Util
+ */
+export declare function isValidEmail(email: string): boolean;
+/**
+ * Convert a given 10-hex number to a lowercase 26-hex string.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * const ret1 = convert10To26(1);
+ * const ret2 = convert10To26(26);
+ * const ret3 = convert10To26(27);
+ * const ret4 = convert10To26(52);
+ * const ret5 = convert10To26(53);
+ * console.log(ret1, ret2, ret3, ret4, ret5);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * a z aa az ba
+ * ```
+ *
+ * @param {number} num
+ * @returns {string} Return a lowercase 26-hex string.
+ * @category Util
+ */
+export declare function convert10To26(num: number): string;
+/**
+ * Get the current version.
+ *
+ * @hidden
+ */
+export declare function getCurrentVersion(): string;
+/**
+ * Repeatedly fires a callback function with a certain interval until a specified condition is met.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * repeatUntilConditionMet(
+ *   () => {
+ *     console.log('repeatUntilConditionMet');
+ *     return true;
+ *   }, {
+ *     interval: 1000,
+ *     times: 10,
+ *     context: null,
+ *     args: [],
+ *   }, (result) => {
+ *     return result === true;
+ *   }
+ * );
+ * ```
+ *
+ * @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 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
+ */
+export declare function repeatUntilConditionMet<T extends (...args: MazeyFnParams) => MazeyFnReturn>(callback: T, options?: RepeatUntilOptions, condition?: (result: ReturnType<T>) => boolean): void;
+/**
+ * Wait for a specified amount of time.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * waitTime(1000).then((time) => {
+ *  console.log('waitTime:', time);
+ * });
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * waitTime: 1000
+ * ```
+ *
+ * @param time The amount of time to wait, in milliseconds.
+ * @returns A Promise that resolves after the specified time has elapsed.
+ * @category Util
+ */
+export declare function waitTime(time: number): Promise<number>;
+/**
+ * Alias of `waitTime`.
+ *
+ * @hidden
+ */
+export declare function sleep(time: number): Promise<number>;
+//# sourceMappingURL=util.d.ts.map