sculp-js 1.12.0 → 1.13.1

package/lib/es/date.js

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

package/lib/es/dom.js

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

package/lib/es/download.js

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

package/lib/es/easing.js

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

package/lib/es/file.js

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

package/lib/es/func.js

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

package/lib/es/index.js

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

package/lib/es/isEqual.js

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

package/lib/es/math.js

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

package/lib/es/number.js

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

package/lib/es/object.js

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

package/lib/es/path.js

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

package/lib/es/qs.js

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

package/lib/es/random.js

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

package/lib/es/string.js

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

package/lib/es/tooltip.js

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

package/lib/es/tree.js

@@ -1,11 +1,11 @@
 /*!
- * sculp-js v1.12.0
+ * sculp-js v1.13.1
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
 
 import { objectOmit } from './object.js';
-import { objectHas, isEmpty } from './type.js';
+import { isObject, objectHas, isEmpty } from './type.js';
 
 const defaultFieldOptions = { keyField: 'key', childField: 'children', pidField: 'pid' };
 const defaultSearchTreeOptions = {
@@ -15,58 +15,126 @@ const defaultSearchTreeOptions = {
     ignoreCase: true
 };
 /**
- * 深度优先遍历函数(支持continue和break操作), 可用于insert tree item 和 remove tree item
+ * 树遍历函数(支持continue和break操作), 可用于insert tree item 和 remove tree item
  * @param {ArrayLike<V>} tree  树形数据
  * @param {Function} iterator  迭代函数, 返回值为true时continue, 返回值为false时break
- * @param {string} children 定制子元素的key
- * @param {boolean} isReverse  是否反向遍历
+ * @param {options} options 支持定制子元素名称、反向遍历、广度优先遍历，默认{
+    childField: 'children',
+    reverse: false,
+    breadthFirst: false
+  }
  * @returns {*}
  */
-function forEachDeep(tree, iterator, children = 'children', isReverse = false) {
+function forEachDeep(tree, iterator, options = {
+    childField: 'children',
+    reverse: false,
+    breadthFirst: false
+}) {
+    const { childField = 'children', reverse = false, breadthFirst = false } = isObject(options) ? options : {};
     let isBreak = false;
+    const queue = [];
     const walk = (arr, parent, level = 0) => {
-        if (isReverse) {
-            for (let i = arr.length - 1; i >= 0; i--) {
+        if (reverse) {
+            for (let index = arr.length - 1; index >= 0; index--) {
                 if (isBreak) {
                     break;
                 }
-                const re = iterator(arr[i], i, arr, tree, parent, level);
-                if (re === false) {
-                    isBreak = true;
-                    break;
+                const item = arr[index];
+                // 广度优先
+                if (breadthFirst) {
+                    queue.push({ item, index, array: arr, tree, parent, level });
                 }
-                else if (re === true) {
-                    continue;
+                else {
+                    const re = iterator(item, index, arr, tree, parent, level);
+                    if (re === false) {
+                        isBreak = true;
+                        break;
+                    }
+                    else if (re === true) {
+                        continue;
+                    }
+                    // @ts-ignore
+                    if (item && Array.isArray(item[childField])) {
+                        // @ts-ignore
+                        walk(item[childField], item, level + 1);
+                    }
                 }
-                // @ts-ignore
-                if (arr[i] && Array.isArray(arr[i][children])) {
+            }
+            if (breadthFirst) {
+                // Process queue
+                while (queue.length > 0 && !isBreak) {
+                    const current = queue.shift();
+                    // iterate(info);
+                    // @ts-ignore
+                    const { item, index, array, tree, parent, level } = current;
+                    const re = iterator(item, index, array, tree, parent, level);
+                    if (re === false) {
+                        isBreak = true;
+                        break;
+                    }
+                    else if (re === true) {
+                        continue;
+                    }
                     // @ts-ignore
-                    walk(arr[i][children], arr[i], level + 1);
+                    if (item && Array.isArray(item[childField])) {
+                        // @ts-ignore
+                        walk(item[childField], item, level + 1);
+                    }
                 }
             }
         }
         else {
-            for (let i = 0, len = arr.length; i < len; i++) {
+            for (let index = 0, len = arr.length; index < len; index++) {
                 if (isBreak) {
                     break;
                 }
-                const re = iterator(arr[i], i, arr, tree, parent, level);
-                if (re === false) {
-                    isBreak = true;
-                    break;
+                const item = arr[index];
+                if (breadthFirst) {
+                    // 广度优先
+                    queue.push({ item, index: index, array: arr, tree, parent, level });
                 }
-                else if (re === true) {
-                    continue;
+                else {
+                    // 深度优先
+                    const re = iterator(item, index, arr, tree, parent, level);
+                    if (re === false) {
+                        isBreak = true;
+                        break;
+                    }
+                    else if (re === true) {
+                        continue;
+                    }
+                    // @ts-ignore
+                    if (item && Array.isArray(item[childField])) {
+                        // @ts-ignore
+                        walk(item[childField], item, level + 1);
+                    }
                 }
-                // @ts-ignore
-                if (arr[i] && Array.isArray(arr[i][children])) {
+            }
+            if (breadthFirst) {
+                while (queue.length > 0 && !isBreak) {
+                    const current = queue.shift();
+                    if (!current)
+                        break;
+                    // @ts-ignore
+                    const { item, index, array, tree, parent, level } = current;
+                    const re = iterator(item, index, array, tree, parent, level);
+                    if (re === false) {
+                        isBreak = true;
+                        break;
+                    }
+                    else if (re === true) {
+                        continue;
+                    }
                     // @ts-ignore
-                    walk(arr[i][children], arr[i], level + 1);
+                    if (item && Array.isArray(item[childField])) {
+                        // @ts-ignore
+                        walk(item[childField], item, level + 1);
+                    }
                 }
             }
         }
     };
-    walk(tree, null);
+    walk(tree, null, 0);
     // @ts-ignore
     tree = null;
 }
@@ -76,20 +144,27 @@ function forEachDeep(tree, iterator, children = 'children', isReverse = false) {
  * 可遍历任何带有 length 属性和数字键的类数组对象
  * @param {ArrayLike<V>} tree  树形数据
  * @param {Function} iterator  迭代函数, 返回值为true时continue, 返回值为false时break
- * @param {string} children 定制子元素的key
- * @param {boolean} isReverse  是否反向遍历
+ * @param {options} options 支持定制子元素名称、反向遍历，默认{
+    childField: 'children',
+    reverse: false,
+  }
  * @returns {any[]} 新的一棵树
  */
-function mapDeep(tree, iterator, children = 'children', isReverse = false) {
+function mapDeep(tree, iterator, options = {
+    childField: 'children',
+    reverse: false
+}) {
+    const { childField = 'children', reverse = false } = isObject(options) ? options : {};
     let isBreak = false;
     const newTree = [];
     const walk = (arr, parent, newTree, level = 0) => {
-        if (isReverse) {
+        if (reverse) {
             for (let i = arr.length - 1; i >= 0; i--) {
                 if (isBreak) {
                     break;
                 }
-                const re = iterator(arr[i], i, arr, tree, parent, level);
+                const item = arr[i];
+                const re = iterator(item, i, arr, tree, parent, level);
                 if (re === false) {
                     isBreak = true;
                     break;
@@ -97,16 +172,16 @@ function mapDeep(tree, iterator, children = 'children', isReverse = false) {
                 else if (re === true) {
                     continue;
                 }
-                newTree.push(objectOmit(re, [children]));
+                newTree.push(objectOmit(re, [childField]));
                 // @ts-ignore
-                if (arr[i] && Array.isArray(arr[i][children])) {
-                    newTree[newTree.length - 1][children] = [];
+                if (item && Array.isArray(item[childField])) {
+                    newTree[newTree.length - 1][childField] = [];
                     // @ts-ignore
-                    walk(arr[i][children], arr[i], newTree[newTree.length - 1][children], level + 1);
+                    walk(item[childField], item, newTree[newTree.length - 1][childField], level + 1);
                 }
                 else {
                     // children非有效数组时，移除该属性字段
-                    delete re[children];
+                    delete re[childField];
                 }
             }
         }
@@ -115,7 +190,8 @@ function mapDeep(tree, iterator, children = 'children', isReverse = false) {
                 if (isBreak) {
                     break;
                 }
-                const re = iterator(arr[i], i, arr, tree, parent, level);
+                const item = arr[i];
+                const re = iterator(item, i, arr, tree, parent, level);
                 if (re === false) {
                     isBreak = true;
                     break;
@@ -123,16 +199,16 @@ function mapDeep(tree, iterator, children = 'children', isReverse = false) {
                 else if (re === true) {
                     continue;
                 }
-                newTree.push(objectOmit(re, [children]));
+                newTree.push(objectOmit(re, [childField]));
                 // @ts-ignore
-                if (arr[i] && Array.isArray(arr[i][children])) {
-                    newTree[newTree.length - 1][children] = [];
+                if (item && Array.isArray(item[childField])) {
+                    newTree[newTree.length - 1][childField] = [];
                     // @ts-ignore
-                    walk(arr[i][children], arr[i], newTree[newTree.length - 1][children], level + 1);
+                    walk(item[childField], item, newTree[newTree.length - 1][childField], level + 1);
                 }
                 else {
                     // children非有效数组时，移除该属性字段
-                    delete re[children];
+                    delete re[childField];
                 }
             }
         }
@@ -146,30 +222,30 @@ function mapDeep(tree, iterator, children = 'children', isReverse = false) {
  * 在树中找到 id 为某个值的节点，并返回上游的所有父级节点
  *
  * @param {ArrayLike<T>} tree - 树形数据
- * @param {IdLike} nodeId - 元素ID
- * @param {ITreeConf} config - 迭代配置项
- * @returns {[IdLike[], ITreeItem<V>[]]} - 由parentId...childId, parentObject-childObject组成的二维数组
+ * @param {number | string} nodeId - 目标元素ID
+ * @param {ITreeConf} options - 迭代配置项, 默认：{ children = 'children', id = 'id' }
+ * @returns {[(number | string)[], V[]]} - 由parentId...childId, parentObject-childObject组成的二维数组
  */
-function searchTreeById(tree, nodeId, config) {
-    const { children = 'children', id = 'id' } = config || {};
+function searchTreeById(tree, nodeId, options = { childField: 'children', keyField: 'id' }) {
+    const { childField = 'children', keyField = 'id' } = isObject(options) ? options : {};
     const toFlatArray = (tree, parentId, parent) => {
         return tree.reduce((t, _) => {
-            const child = _[children];
+            const child = _[childField];
             return [
                 ...t,
                 parentId ? { ..._, parentId, parent } : _,
-                ...(child && child.length ? toFlatArray(child, _[id], _) : [])
+                ...(child && child.length ? toFlatArray(child, _[keyField], _) : [])
             ];
         }, []);
     };
     const getIds = (flatArray) => {
-        let child = flatArray.find(_ => _[id] === nodeId);
+        let child = flatArray.find(_ => _[keyField] === nodeId);
         const { parent, parentId, ...other } = child;
         let ids = [nodeId], nodes = [other];
         while (child && child.parentId) {
             ids = [child.parentId, ...ids];
             nodes = [child.parent, ...nodes];
-            child = flatArray.find(_ => _[id] === child.parentId); // eslint-disable-line
+            child = flatArray.find(_ => _[keyField] === child.parentId); // eslint-disable-line
         }
         return [ids, nodes];
     };
@@ -178,11 +254,12 @@ function searchTreeById(tree, nodeId, config) {
 /**
  * 扁平化数组转换成树
  * @param {any[]} list
- * @param {IFieldOptions} options
+ * @param {IFieldOptions} options 定制id字段名，子元素字段名，父元素字段名，默认
+ *        { keyField: 'key', childField: 'children', pidField: 'pid' }
  * @returns {any[]}
  */
 function formatTree(list, options = defaultFieldOptions) {
-    const { keyField, childField, pidField } = options;
+    const { keyField = 'key', childField = 'children', pidField = 'pid' } = isObject(options) ? options : {};
     const treeArr = [];
     const sourceMap = {};
     for (let i = 0, len = list.length; i < len; i++) {
@@ -205,12 +282,13 @@ function formatTree(list, options = defaultFieldOptions) {
 }
 /**
  * 树形结构转扁平化
- * @param {any} treeList
- * @param {IFieldOptions} options
- * @returns {*}
+ * @param {any[]} treeList
+ * @param {IFieldOptions} options 定制id字段名，子元素字段名，父元素字段名，默认
+ *        { keyField: 'key', childField: 'children', pidField: 'pid' }
+ * @returns {any[]}
  */
 function flatTree(treeList, options = defaultFieldOptions) {
-    const { childField, keyField, pidField } = options;
+    const { keyField = 'key', childField = 'children', pidField = 'pid' } = isObject(options) ? options : {};
     let res = [];
     for (let i = 0, len = treeList.length; i < len; i++) {
         const node = treeList[i];
@@ -241,7 +319,12 @@ function flatTree(treeList, options = defaultFieldOptions) {
  * 2. 若无任何过滤条件或keyword模式匹配且keyword为空串，返回原对象；其他情况返回新数组
  * @param {V[]} nodes
  * @param {IFilterCondition} filterCondition
- * @param {ISearchTreeOpts} options
+ * @param {ISearchTreeOpts} options 默认配置项 {
+      childField: 'children',
+      nameField: 'name',
+      removeEmptyChild: false,
+      ignoreCase: true
+    }
  * @returns {V[]}
  */
 function fuzzySearchTree(nodes, filterCondition, options = defaultSearchTreeOptions) {

package/lib/es/type.js

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

package/lib/es/unique.js

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

package/lib/es/url.js

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

package/lib/es/validator.js

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

package/lib/es/variable.js

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

package/lib/es/watermark.js

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

package/lib/es/we-decode.js

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

package/lib/index.d.ts

@@ -634,16 +634,16 @@ declare function asyncMap<T, R>(list: Array<T>, mapper: (val: T, idx: number, li
  * Execute a promise safely
  *
  * @param { Promise } promise
- * @param { Object= } errorExt - Additional Information you can pass to the err object
+ * @param { Object= } errorExt - Additional Information you can pass safeAwait the err object
  * @return { Promise }
  * @example
  * async function asyncTaskWithCb(cb) {
      let err, user, savedTask, notification;
 
-     [ err, user ] = await to(UserModel.findById(1));
+     [ err, user ] = await safeAwait(UserModel.findById(1));
      if(!user) return cb('No user found');
 
-     [ err, savedTask ] = await to(TaskModel({userId: user.id, name: 'Demo Task'}));
+     [ err, savedTask ] = await safeAwait(TaskModel({userId: user.id, name: 'Demo Task'}));
      if(err) return cb('Error occurred while saving task')
 
     cb(null, savedTask);
@@ -909,53 +909,65 @@ interface IFilterCondition<V> {
     filter?: (args: V) => boolean;
 }
 /**
- * 深度优先遍历函数(支持continue和break操作), 可用于insert tree item 和 remove tree item
+ * 树遍历函数(支持continue和break操作), 可用于insert tree item 和 remove tree item
  * @param {ArrayLike<V>} tree  树形数据
  * @param {Function} iterator  迭代函数, 返回值为true时continue, 返回值为false时break
- * @param {string} children 定制子元素的key
- * @param {boolean} isReverse  是否反向遍历
+ * @param {options} options 支持定制子元素名称、反向遍历、广度优先遍历，默认{
+    childField: 'children',
+    reverse: false,
+    breadthFirst: false
+  }
  * @returns {*}
  */
-declare function forEachDeep<V>(tree: ArrayLike<V>, iterator: (val: V, i: number, currentArr: ArrayLike<V>, tree: ArrayLike<V>, parent: V | null, level: number) => boolean | void, children?: string, isReverse?: boolean): void;
+declare function forEachDeep<V>(tree: ArrayLike<V>, iterator: (val: V, index: number, currentArr: ArrayLike<V>, tree: ArrayLike<V>, parent: V | null, level: number) => boolean | void, options?: {
+    childField?: string;
+    reverse?: boolean;
+    breadthFirst?: boolean;
+}): void;
 /**
  * 创建一个新数组, 深度优先遍历的Map函数(支持continue和break操作), 可用于insert tree item 和 remove tree item
  *
  * 可遍历任何带有 length 属性和数字键的类数组对象
  * @param {ArrayLike<V>} tree  树形数据
  * @param {Function} iterator  迭代函数, 返回值为true时continue, 返回值为false时break
- * @param {string} children 定制子元素的key
- * @param {boolean} isReverse  是否反向遍历
+ * @param {options} options 支持定制子元素名称、反向遍历，默认{
+    childField: 'children',
+    reverse: false,
+  }
  * @returns {any[]} 新的一棵树
  */
-declare function mapDeep<T>(tree: T[], iterator: (val: T, i: number, currentArr: T[], tree: T[], parent: T | null, level: number) => {
+declare function mapDeep<T>(tree: T[], iterator: (val: T, index: number, currentArr: T[], tree: T[], parent: T | null, level: number) => {
     [k: string | number]: any;
-} | boolean, children?: string, isReverse?: boolean): any[];
+} | boolean, options?: {
+    childField?: string;
+    reverse?: boolean;
+    breadthFirst?: boolean;
+}): any[];
 type IdLike = number | string;
-interface ITreeConf {
-    id: string | number;
-    children: string;
-}
+type ITreeConf = Omit<IFieldOptions, 'pidField'>;
 /**
  * 在树中找到 id 为某个值的节点，并返回上游的所有父级节点
  *
  * @param {ArrayLike<T>} tree - 树形数据
- * @param {IdLike} nodeId - 元素ID
- * @param {ITreeConf} config - 迭代配置项
- * @returns {[IdLike[], ITreeItem<V>[]]} - 由parentId...childId, parentObject-childObject组成的二维数组
+ * @param {number | string} nodeId - 目标元素ID
+ * @param {ITreeConf} options - 迭代配置项, 默认：{ children = 'children', id = 'id' }
+ * @returns {[(number | string)[], V[]]} - 由parentId...childId, parentObject-childObject组成的二维数组
  */
-declare function searchTreeById<V>(tree: ArrayLike<V>, nodeId: IdLike, config?: ITreeConf): [IdLike[], ArrayLike<V>[]];
+declare function searchTreeById<V>(tree: ArrayLike<V>, nodeId: IdLike, options?: ITreeConf): [(number | string)[], ArrayLike<V>[]];
 /**
  * 扁平化数组转换成树
  * @param {any[]} list
- * @param {IFieldOptions} options
+ * @param {IFieldOptions} options 定制id字段名，子元素字段名，父元素字段名，默认
+ *        { keyField: 'key', childField: 'children', pidField: 'pid' }
  * @returns {any[]}
  */
 declare function formatTree(list: any[], options?: IFieldOptions): any[];
 /**
  * 树形结构转扁平化
- * @param {any} treeList
- * @param {IFieldOptions} options
- * @returns {*}
+ * @param {any[]} treeList
+ * @param {IFieldOptions} options 定制id字段名，子元素字段名，父元素字段名，默认
+ *        { keyField: 'key', childField: 'children', pidField: 'pid' }
+ * @returns {any[]}
  */
 declare function flatTree(treeList: any[], options?: IFieldOptions): any[];
 /**
@@ -969,7 +981,12 @@ declare function flatTree(treeList: any[], options?: IFieldOptions): any[];
  * 2. 若无任何过滤条件或keyword模式匹配且keyword为空串，返回原对象；其他情况返回新数组
  * @param {V[]} nodes
  * @param {IFilterCondition} filterCondition
- * @param {ISearchTreeOpts} options
+ * @param {ISearchTreeOpts} options 默认配置项 {
+      childField: 'children',
+      nameField: 'name',
+      removeEmptyChild: false,
+      ignoreCase: true
+    }
  * @returns {V[]}
  */
 declare function fuzzySearchTree<V>(nodes: V[], filterCondition: IFilterCondition<V>, options?: ISearchTreeOpts): V[];