sculp-js 1.8.3 → 1.9.0

package/lib/es/index.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
@@ -21,7 +21,7 @@ export { chooseLocalFile, compressImg, supportCanvas } from './file.js';
 export { genCanvasWM } from './watermark.js';
 export { debounce, getGlobal, once, setGlobal, throttle } from './func.js';
 export { STRING_POOL, randomNumber, randomString, randomUuid } from './random.js';
-export { HEX_POOL, formatNumber, numberAbbr, numberToHex } from './number.js';
+export { HEX_POOL, formatNumber as formatMoney, formatNumber, humanFileSize, numberAbbr, numberToHex } from './number.js';
 export { UNIQUE_NUMBER_SAFE_LENGTH, uniqueNumber, uniqueString } from './unique.js';
 export { tooltipEvent } from './tooltip.js';
 export { flatTree, forEachDeep, formatTree, fuzzySearchTree, mapDeep, searchTreeById } from './tree.js';

package/lib/es/isEqual.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/lib/es/math.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/lib/es/number.js

@@ -1,11 +1,12 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
 
 import { getGlobal } from './func.js';
 import { STRING_ARABIC_NUMERALS, STRING_UPPERCASE_ALPHA, STRING_LOWERCASE_ALPHA } from './string.js';
+import { isNullOrUnDef, isNumber } from './type.js';
 
 const HEX_POOL = `${STRING_ARABIC_NUMERALS}${STRING_UPPERCASE_ALPHA}${STRING_LOWERCASE_ALPHA}`;
 const supportBigInt = typeof BigInt !== 'undefined';
@@ -43,35 +44,69 @@ function numberToHex(decimal, hexPool = HEX_POOL) {
     return ret.join('');
 }
 /**
- * 缩写
+ * 将数字转换为携带单位的字符串
  * @param {number | string} num
  * @param {Array<string>} units
- * @param {number} ratio
- * @param {number} exponent
+ * @param {INumberAbbr} options default: { ratio: 1000, decimals: 0, separator: ' ' }
  * @returns {string}
  */
-const numberAbbr = (num, units, ratio = 1000, exponent) => {
+const numberAbbr = (num, units, options = { ratio: 1000, decimals: 0, separator: ' ' }) => {
+    const { ratio = 1000, decimals = 0, separator = ' ' } = options;
     const { length } = units;
     if (length === 0)
-        throw new Error('至少需要一个单位');
+        throw new Error('At least one unit is required');
     let num2 = Number(num);
     let times = 0;
     while (num2 >= ratio && times < length - 1) {
         num2 = num2 / ratio;
         times++;
     }
-    const value = num2.toFixed(exponent);
+    const value = num2.toFixed(decimals);
     const unit = units[times];
-    return value.toString() + '' + unit;
+    return String(value) + separator + unit;
 };
+/**
+ * Converting file size in bytes to human-readable string
+ *  reference: https://zh.wikipedia.org/wiki/%E5%8D%83%E5%AD%97%E8%8A%82
+ * @param {number | string} num bytes Number in Bytes
+ * @param {IHumanFileSizeOptions} options default: { decimals = 0, si = false, separator = ' ' }
+ *        si: True to use metric (SI) units, aka powers of 1000, the units is
+ *            ['B', 'kB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'].
+ *            False to use binary (IEC), aka powers of 1024, the units is
+ *            ['Byte', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB']
+ * @returns
+ */
+function humanFileSize(num, options) {
+    const { decimals = 0, si = false, separator = ' ', maxUnit } = options;
+    const units = si
+        ? ['B', 'kB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB']
+        : ['Byte', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB'];
+    if (!isNullOrUnDef(maxUnit)) {
+        const targetIndex = units.findIndex(el => el === maxUnit);
+        if (targetIndex !== -1) {
+            units.splice(targetIndex + 1);
+        }
+    }
+    return numberAbbr(num, units, { ratio: si ? 1000 : 1024, decimals, separator });
+}
 /**
  * 将数字格式化成千位分隔符显示的字符串
- * @param {number} val 数字
- * @param {'int' | 'float'} type 展示分段显示的类型 int:整型 | float:浮点型
+ * @param {number|string} num 数字
+ * @param {number} decimals 格式化成指定小数位精度的参数
  * @returns {string}
  */
-function formatNumber(val, type = 'int') {
-    return type === 'int' ? parseInt(String(val)).toLocaleString() : Number(val).toLocaleString('en-US');
+function formatNumber(num, decimals) {
+    if (isNullOrUnDef(decimals)) {
+        return parseInt(String(num)).toLocaleString();
+    }
+    let prec = 0;
+    if (!isNumber(decimals)) {
+        throw new Error('Decimals must be a positive number not less than zero');
+    }
+    else if (decimals > 0) {
+        prec = decimals;
+    }
+    return Number(Number(num).toFixed(prec)).toLocaleString('en-US');
 }
 
-export { HEX_POOL, formatNumber, numberAbbr, numberToHex };
+export { HEX_POOL, formatNumber as formatMoney, formatNumber, humanFileSize, numberAbbr, numberToHex };

package/lib/es/object.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/lib/es/path.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/lib/es/qs.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/lib/es/random.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/lib/es/string.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/lib/es/tooltip.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/lib/es/tree.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
@@ -210,7 +210,7 @@ function flatTree(treeList, options = defaultFieldOptions) {
             ...node,
             [childField]: [] // 清空子级
         };
-        item.hasOwnProperty([childField]) && delete item[childField];
+        objectHas(item, childField) && delete item[childField];
         res.push(item);
         if (node[childField]) {
             const children = node[childField].map(item => ({

package/lib/es/type.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/lib/es/unique.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/lib/es/url.js

@@ -1,27 +1,37 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
 
+import { isFunction } from './type.js';
 import { pathJoin } from './path.js';
 import { qsParse, qsStringify } from './qs.js';
 
-const anchorEl = document.createElement('a');
 /**
  * url 解析
  * @param {string} url
+ * @param {boolean} isModernApi 使用现代API:URL, 默认true (对无效url解析会抛错), 否则使用a标签来解析（兼容性更强）
  * @returns {Url}
  */
-const urlParse = (url) => {
-    anchorEl.href = url;
-    const { protocol, username, password, host, port, hostname, hash, search, pathname: _pathname } = anchorEl;
+const urlParse = (url, isModernApi = true) => {
+    // @ts-ignore
+    let urlObj = null;
+    if (isFunction(URL) && isModernApi) {
+        urlObj = new URL(url);
+    }
+    else {
+        urlObj = document.createElement('a');
+        urlObj.href = url;
+    }
+    const { protocol, username, password, host, port, hostname, hash, search, pathname: _pathname } = urlObj;
     // fix: ie 浏览器下，解析出来的 pathname 是没有 / 根的
     const pathname = pathJoin('/', _pathname);
     const auth = username && password ? `${username}:${password}` : '';
     const query = search.replace(/^\?/, '');
     const searchParams = qsParse(query);
     const path = `${pathname}${search}`;
+    urlObj = null;
     return {
         protocol,
         auth,

package/lib/es/validator.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/lib/es/variable.js

@@ -1,10 +1,10 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
 
-import { objectHas } from './type.js';
+import { isNullOrUnDef, objectHas } from './type.js';
 
 /**
  * 去除字符串中重复字符
@@ -47,7 +47,8 @@ function parseVariableRegExp(leftMatchSymbol, rightMatchSymbol) {
  * default match symbol {} same as /{\s*([^{}\s]*)\s*}/g
  */
 function parseVarFromString(str, leftMatchSymbol = '{', rightMatchSymbol = '}') {
-    return Array.from(str.matchAll(parseVariableRegExp(leftMatchSymbol, rightMatchSymbol))).map(el => el?.[1]);
+    // @ts-ignore
+    return Array.from(str.matchAll(parseVariableRegExp(leftMatchSymbol, rightMatchSymbol))).map(el => isNullOrUnDef(el) ? void 0 : el[1]);
 }
 /**
  * 替换字符串中的插值变量

package/lib/es/watermark.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/lib/es/we-decode.js

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.8.3
+ * sculp-js v1.9.0
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/lib/index.d.ts

@@ -332,13 +332,22 @@ declare function downloadHref(href: string, filename: string, callback?: Functio
  * @param {Function} callback
  */
 declare function downloadBlob(blob: Blob, filename: string, callback?: Function): void;
+type CrossOriginDownloadParams = {
+    successCode?: number;
+    successCallback?: Function;
+    failCallback?: Function;
+};
 /**
  * 根据URL下载文件（解决跨域a.download不生效问题)
+ *
+ * 可定制下载成功的状态码status(浏览器原生状态码)
+ *
+ * 支持下载操作成功、失败后的回调
  * @param {string} url
  * @param {string} filename
- * @param {Function} callback
+ * @param {CrossOriginDownloadParams} options
  */
-declare function crossOriginDownload(url: string, filename: string, callback?: Function): void;
+declare function crossOriginDownload(url: string, filename: string, options?: CrossOriginDownloadParams): void;
 type FileType = 'json' | 'csv' | 'xls' | 'xlsx';
 /**
  * 将指定数据格式通过 A 链接的方式下载
@@ -517,9 +526,10 @@ interface Url {
 /**
  * url 解析
  * @param {string} url
+ * @param {boolean} isModernApi 使用现代API:URL, 默认true (对无效url解析会抛错), 否则使用a标签来解析（兼容性更强）
  * @returns {Url}
  */
-declare const urlParse: (url: string) => Url;
+declare const urlParse: (url: string, isModernApi?: boolean) => Url;
 /**
  * url 字符化，url 对象里的 searchParams 会覆盖 url 原有的查询参数
  * @param {Url} url
@@ -688,22 +698,44 @@ declare const HEX_POOL: string;
  * @returns {string}
  */
 declare function numberToHex(decimal: number | string, hexPool?: string): string;
+interface INumberAbbr {
+    ratio?: number;
+    decimals?: number;
+    separator?: string;
+}
 /**
- * 缩写
+ * 将数字转换为携带单位的字符串
  * @param {number | string} num
  * @param {Array<string>} units
- * @param {number} ratio
- * @param {number} exponent
+ * @param {INumberAbbr} options default: { ratio: 1000, decimals: 0, separator: ' ' }
  * @returns {string}
  */
-declare const numberAbbr: (num: number | string, units: Array<string>, ratio?: number, exponent?: number) => string;
+declare const numberAbbr: (num: number | string, units: Array<string>, options?: INumberAbbr) => string;
+interface IHumanFileSizeOptions {
+    decimals?: number;
+    si?: boolean;
+    separator?: string;
+    maxUnit?: string;
+}
+/**
+ * Converting file size in bytes to human-readable string
+ *  reference: https://zh.wikipedia.org/wiki/%E5%8D%83%E5%AD%97%E8%8A%82
+ * @param {number | string} num bytes Number in Bytes
+ * @param {IHumanFileSizeOptions} options default: { decimals = 0, si = false, separator = ' ' }
+ *        si: True to use metric (SI) units, aka powers of 1000, the units is
+ *            ['B', 'kB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'].
+ *            False to use binary (IEC), aka powers of 1024, the units is
+ *            ['Byte', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB']
+ * @returns
+ */
+declare function humanFileSize(num: number | string, options: IHumanFileSizeOptions): string;
 /**
  * 将数字格式化成千位分隔符显示的字符串
- * @param {number} val 数字
- * @param {'int' | 'float'} type 展示分段显示的类型 int:整型 | float:浮点型
+ * @param {number|string} num 数字
+ * @param {number} decimals 格式化成指定小数位精度的参数
  * @returns {string}
  */
-declare function formatNumber(val: number, type?: string): string;
+declare function formatNumber(num: number | string, decimals?: number): string;
 
 declare const UNIQUE_NUMBER_SAFE_LENGTH = 18;
 /**
@@ -1057,4 +1089,4 @@ type Comparable = null | undefined | boolean | number | string | Date | RegExp |
  */
 declare function isEqual(a: Comparable, b: Comparable): boolean;
 
-export { type AnyArray, type AnyFunc, type AnyObject, type ArrayElements, type Comparable, type DateObj, type DateValue, type DebounceFunc, EMAIL_REGEX, type FileType, HEX_POOL, HTTP_URL_REGEX, type ICanvasWM, type ICompressOptions, type IFieldOptions, type IFilterCondition, IPV4_REGEX, IPV6_REGEX, type ISearchTreeOpts, type ITreeConf, type IdLike, type LooseParamValue, type LooseParams, type ObjectAssignItem, type OnceFunc, PHONE_REGEX, type Params, type PartialDeep, type RandomString, type Replacer, STRING_ARABIC_NUMERALS, STRING_LOWERCASE_ALPHA, STRING_POOL, STRING_UPPERCASE_ALPHA, type SetStyle, type SmoothScrollOptions, type Style, type ThrottleFunc, UNIQUE_NUMBER_SAFE_LENGTH, URL_REGEX, type UniqueString, type Url, add, addClass, arrayEach, arrayEachAsync, arrayInsertBefore, arrayLike, arrayRemove, asyncMap, calculateDate, calculateDateTime, chooseLocalFile, cloneDeep, compressImg, cookieDel, cookieGet, cookieSet, copyText, crossOriginDownload, dateParse, dateToEnd, dateToStart, debounce, decodeFromBase64, divide, downloadBlob, downloadData, downloadHref, downloadURL, encodeToBase64, escapeRegExp, executeInScope, flatTree, forEachDeep, formatDate, formatNumber, formatTree, fuzzySearchTree, genCanvasWM, getComputedCssVal, getGlobal, getStrWidthPx, getStyle, hasClass, isArray, isBigInt, isBoolean, isDate, isDigit, isEmail, isEmpty, isEqual, isError, isFloat, isFunction, isIdNo, isInteger, isIpV4, isIpV6, isJsonString, isNaN, isNull, isNullOrUnDef, isNullOrUnDef as isNullish, isNumber, isNumerical, isObject, isPhone, isPlainObject, isPrimitive, isRegExp, isString, isSymbol, isUndefined, isUrl, isValidDate, mapDeep, multiply, numberAbbr, numberToHex, objectAssign, objectEach, objectEachAsync, objectFill, objectGet, objectHas, objectMap, objectAssign as objectMerge, objectOmit, objectPick, once, parseQueryParams, parseVarFromString, pathJoin, pathNormalize, qsParse, qsStringify, randomNumber, randomString, randomUuid, removeClass, replaceVarFromString, searchTreeById, setGlobal, setStyle, smoothScroll, stringAssign, stringCamelCase, stringEscapeHtml, stringFill, stringFormat, stringKebabCase, strip, subtract, supportCanvas, throttle, tooltipEvent, typeIs, uniqueNumber, uniqueString, uniqueSymbol, urlDelParams, urlParse, urlSetParams, urlStringify, wait, weAtob, weBtoa };
+export { type AnyArray, type AnyFunc, type AnyObject, type ArrayElements, type Comparable, type DateObj, type DateValue, type DebounceFunc, EMAIL_REGEX, type FileType, HEX_POOL, HTTP_URL_REGEX, type ICanvasWM, type ICompressOptions, type IFieldOptions, type IFilterCondition, IPV4_REGEX, IPV6_REGEX, type ISearchTreeOpts, type ITreeConf, type IdLike, type LooseParamValue, type LooseParams, type ObjectAssignItem, type OnceFunc, PHONE_REGEX, type Params, type PartialDeep, type RandomString, type Replacer, STRING_ARABIC_NUMERALS, STRING_LOWERCASE_ALPHA, STRING_POOL, STRING_UPPERCASE_ALPHA, type SetStyle, type SmoothScrollOptions, type Style, type ThrottleFunc, UNIQUE_NUMBER_SAFE_LENGTH, URL_REGEX, type UniqueString, type Url, add, addClass, arrayEach, arrayEachAsync, arrayInsertBefore, arrayLike, arrayRemove, asyncMap, calculateDate, calculateDateTime, chooseLocalFile, cloneDeep, compressImg, cookieDel, cookieGet, cookieSet, copyText, crossOriginDownload, dateParse, dateToEnd, dateToStart, debounce, decodeFromBase64, divide, downloadBlob, downloadData, downloadHref, downloadURL, encodeToBase64, escapeRegExp, executeInScope, flatTree, forEachDeep, formatDate, formatNumber as formatMoney, formatNumber, formatTree, fuzzySearchTree, genCanvasWM, getComputedCssVal, getGlobal, getStrWidthPx, getStyle, hasClass, humanFileSize, isArray, isBigInt, isBoolean, isDate, isDigit, isEmail, isEmpty, isEqual, isError, isFloat, isFunction, isIdNo, isInteger, isIpV4, isIpV6, isJsonString, isNaN, isNull, isNullOrUnDef, isNullOrUnDef as isNullish, isNumber, isNumerical, isObject, isPhone, isPlainObject, isPrimitive, isRegExp, isString, isSymbol, isUndefined, isUrl, isValidDate, mapDeep, multiply, numberAbbr, numberToHex, objectAssign, objectEach, objectEachAsync, objectFill, objectGet, objectHas, objectMap, objectAssign as objectMerge, objectOmit, objectPick, once, parseQueryParams, parseVarFromString, pathJoin, pathNormalize, qsParse, qsStringify, randomNumber, randomString, randomUuid, removeClass, replaceVarFromString, searchTreeById, setGlobal, setStyle, smoothScroll, stringAssign, stringCamelCase, stringEscapeHtml, stringFill, stringFormat, stringKebabCase, strip, subtract, supportCanvas, throttle, tooltipEvent, typeIs, uniqueNumber, uniqueString, uniqueSymbol, urlDelParams, urlParse, urlSetParams, urlStringify, wait, weAtob, weBtoa };