sculp-js 1.19.6 → 1.19.12

package/dist/esm/tree.mjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.6
+ * sculp-js v1.19.12
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
@@ -20,10 +20,11 @@ function getChildNodes(item, childField, isDomNode) {
   return isDomNode && isNodeList(child) ? Array.from(child) : Array.isArray(child) ? child : null;
 }
 /**
- * 深度遍历函数 (支持 continue 和 break 操作), 可用于遍历 Array 和 NodeList 类型的数据
- * @param {ArrayLike<V>} tree  树形数据
- * @param {Function} iterator  迭代函数，返回值为 true 时 continue, 返回值为 false 时 break
- * @param {options} options 支持定制子元素名称、反向遍历、广度优先遍历，默认{
+ * Tree traversal function (default DFS, supports continue and break operations).
+ * Can be used to traverse Array and NodeList type data.
+ * @param {V[]} tree - Tree data
+ * @param {Function} iterator - Iterator function. Returns true to continue, false to break.
+ * @param {object} options - Options to customize child element name, reverse traversal, breadth-first traversal. Default: {
     childField: 'children',
     reverse: false,
     breadthFirst: false,
@@ -98,10 +99,10 @@ function forEachDeep(
   tree = null;
 }
 /**
- * 树查找函数，可用于查找 Array 和 NodeList 类型的数据
- * @param {ArrayLike<V>} tree  树形数据
- * @param {Function} predicate  断言函数
- * @param {options} options 支持定制子元素名称、反向遍历、广度优先遍历，默认{
+ * Tree search function, can be used to search Array and NodeList type data.
+ * @param {V[]} tree - Tree data
+ * @param {Function} predicate - Predicate function
+ * @param {object} options - Options to customize child element name, reverse traversal, breadth-first traversal. Default: {
     childField: 'children',
     reverse: false,
     breadthFirst: false,
@@ -133,10 +134,10 @@ function findDeep(
   return result;
 }
 /**
- * 树过滤函数，可用于过滤 Array 和 NodeList 类型的数据
- * @param {ArrayLike<V>} tree  树形数据
- * @param {Function} predicate  断言函数
- * @param {options} options 支持定制子元素名称、反向遍历、广度优先遍历，默认{
+ * Tree filter function, can be used to filter Array and NodeList type data.
+ * @param {V[]} tree - Tree data
+ * @param {Function} predicate - Predicate function
+ * @param {object} options - Options to customize child element name, reverse traversal, breadth-first traversal. Default: {
     childField: 'children',
     reverse: false,
     breadthFirst: false,
@@ -167,16 +168,17 @@ function filterDeep(
   return result;
 }
 /**
- * 创建一个新数组，深度优先遍历的 Map 函数 (支持 continue 和 break 操作), 可用于 insert tree item 和 remove tree item
+ * Creates a new array using a depth-first traversal Map function (supports continue and break operations).
+ * Can be used for inserting or removing tree items.
  *
- * 可遍历任何带有 length 属性和数字键的类数组对象
- * @param {ArrayLike<V>} tree  树形数据
- * @param {Function} iterator  迭代函数，返回值为 true 时 continue, 返回值为 false 时 break
- * @param {options} options 支持定制子元素名称、反向遍历，默认{
+ * Can traverse any array-like object with a length property and numeric keys.
+ * @param {V[]} tree - Tree data
+ * @param {Function} iterator - Iterator function. Returns true to continue, false to break.
+ * @param {object} options - Options to customize child element name, reverse traversal. Default: {
     childField: 'children',
     reverse: false,
   }
- * @returns {any[]} 新的一棵树
+ * @returns {any[]} A new tree structure
  */
 function mapDeep(
   tree,
@@ -234,14 +236,14 @@ function mapDeep(
   return newTree;
 }
 /**
- * 在树中找到 id 为某个值的节点，并返回上游的所有父级节点
+ * Retrieves the path (ancestors + self) for a given node ID.
  *
- * @param {ArrayLike<T>} tree - 树形数据
- * @param {number | string} nodeId - 目标元素 ID
- * @param {ITreeConf} options - 迭代配置项，默认：{ children = 'children', id = 'id' }
- * @returns {[(number | string)[], V[]]} - 由 parentId...childId, parentObject-childObject 组成的二维数组
+ * @param {ArrayLike<T>} tree - Tree data
+ * @param {number | string} nodeId - Target node ID
+ * @param {ITreeConf} options - Configuration. Default: { childField = 'children', keyField = 'id' }
+ * @returns {[(number | string)[], V[]]} - Array of IDs and Array of Nodes from root to target
  */
-function searchTreeById(tree, nodeId, options = { childField: 'children', keyField: 'id' }) {
+function getPathById(tree, nodeId, options = { childField: 'children', keyField: 'id' }) {
   const { childField = 'children', keyField = 'id' } = isObject(options) ? options : {};
   const flatMap = {};
   // 扁平化 - 使用迭代而非递归，避免栈溢出
@@ -279,11 +281,11 @@ function searchTreeById(tree, nodeId, options = { childField: 'children', keyFie
   return [ids, nodes];
 }
 /**
- * 扁平化数组转换成树
- * @param {any[]} list
- * @param {IFieldOptions} options 定制 id 字段名，子元素字段名，父元素字段名，默认
+ * Converts a flat array into a tree structure.
+ * @param {any[]} list - Flat list of items
+ * @param {IFieldOptions} options - Customizes id field name, child element field name, parent element field name. Default:
  *        { keyField: 'key', childField: 'children', pidField: 'pid' }
- * @returns {any[]}
+ * @returns {any[]} Tree structure array
  */
 function formatTree(list, options = defaultFieldOptions) {
   const { keyField = 'key', childField = 'children', pidField = 'pid' } = isObject(options) ? options : {};
@@ -309,11 +311,11 @@ function formatTree(list, options = defaultFieldOptions) {
   return treeArr;
 }
 /**
- * 树形结构转扁平化
- * @param {any[]} treeList
- * @param {IFieldOptions} options 定制 id 字段名，子元素字段名，父元素字段名，默认
+ * Converts a tree structure into a flat array.
+ * @param {any[]} treeList - Tree structure array
+ * @param {IFieldOptions} options - Customizes id field name, child element field name, parent element field name. Default:
  *        { keyField: 'key', childField: 'children', pidField: 'pid' }
- * @returns {any[]}
+ * @returns {any[]} Flat array
  */
 function flatTree(treeList, options = defaultFieldOptions) {
   const { keyField = 'key', childField = 'children', pidField = 'pid' } = isObject(options) ? options : {};
@@ -340,23 +342,26 @@ function flatTree(treeList, options = defaultFieldOptions) {
   return res;
 }
 /**
- * 模糊搜索函数，返回包含搜索字符的节点及其祖先节点, 适用于树型组件的字符过滤功能
- * 以下搜索条件二选一，按先后优先级处理：
- * 1. 过滤函数filter, 返回true/false
- * 2. 匹配关键词，支持是否启用忽略大小写来判断
+ * Fuzzy search function that returns nodes containing the search character and their ancestor nodes.
+ * Suitable for character filtering in tree components.
  *
- * 有以下特性：
- * 1. 可配置removeEmptyChild字段，来决定是否移除搜索结果中的空children字段
- * 2. 若无任何过滤条件或keyword模式匹配且keyword为空串，返回原对象；其他情况返回新数组
- * @param {V[]} nodes
- * @param {IFilterCondition} filterCondition
- * @param {ISearchTreeOpts} options 默认配置项 {
+ * Two search conditions are available, processed in priority order:
+ * 1. Filter function `filter`, returning true/false.
+ * 2. Keyword matching, supporting case-insensitive check.
+ *
+ * Features:
+ * 1. Configurable `removeEmptyChild` field to decide whether to remove empty children fields in search results.
+ * 2. If no filter condition is provided, or keyword mode is used with an empty keyword, the original object is returned; otherwise, a new array is returned.
+ *
+ * @param {V[]} nodes - Tree nodes
+ * @param {IFilterCondition} filterCondition - Filter conditions
+ * @param {ISearchTreeOpts} options - Default configuration: {
       childField: 'children',
       nameField: 'name',
       removeEmptyChild: false,
       ignoreCase: true
     }
- * @returns {V[]}
+ * @returns {V[]} Filtered tree nodes
  */
 function fuzzySearchTree(nodes, filterCondition, options = defaultSearchTreeOptions) {
   if (!objectHas(filterCondition, 'filter') && !filterCondition.keyword) {
@@ -411,7 +416,8 @@ var tree = {
   findDeep,
   filterDeep,
   mapDeep,
-  searchTreeById,
+  getPathById,
+  searchTreeById: getPathById,
   formatTree,
   flatTree,
   fuzzySearchTree
@@ -425,6 +431,7 @@ export {
   forEachDeep,
   formatTree,
   fuzzySearchTree,
+  getPathById,
   mapDeep,
-  searchTreeById
+  getPathById as searchTreeById
 };

package/dist/esm/type.mjs

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

package/dist/esm/unicodeToolkit.mjs

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

package/dist/esm/unique.mjs

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

package/dist/esm/url.mjs

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

package/dist/esm/validator.mjs

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

package/dist/esm/variable.mjs

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

package/dist/esm/watermark.mjs

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

package/dist/types/tree.d.ts

@@ -14,10 +14,11 @@ export interface IFilterCondition<V> {
     filter?: (args: V) => boolean;
 }
 /**
- * 深度遍历函数 (支持 continue 和 break 操作), 可用于遍历 Array 和 NodeList 类型的数据
- * @param {ArrayLike<V>} tree  树形数据
- * @param {Function} iterator  迭代函数，返回值为 true 时 continue, 返回值为 false 时 break
- * @param {options} options 支持定制子元素名称、反向遍历、广度优先遍历，默认{
+ * Tree traversal function (default DFS, supports continue and break operations).
+ * Can be used to traverse Array and NodeList type data.
+ * @param {V[]} tree - Tree data
+ * @param {Function} iterator - Iterator function. Returns true to continue, false to break.
+ * @param {object} options - Options to customize child element name, reverse traversal, breadth-first traversal. Default: {
     childField: 'children',
     reverse: false,
     breadthFirst: false,
@@ -25,17 +26,17 @@ export interface IFilterCondition<V> {
   }
  * @returns {*}
  */
-export 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?: {
+export declare function forEachDeep<V>(tree: V[], iterator: (val: V, index: number, currentArr: V[], tree: V[], parent: V | null, level: number) => boolean | void, options?: {
     childField?: string;
     reverse?: boolean;
     breadthFirst?: boolean;
     isDomNode?: boolean;
 }): void;
 /**
- * 树查找函数，可用于查找 Array 和 NodeList 类型的数据
- * @param {ArrayLike<V>} tree  树形数据
- * @param {Function} predicate  断言函数
- * @param {options} options 支持定制子元素名称、反向遍历、广度优先遍历，默认{
+ * Tree search function, can be used to search Array and NodeList type data.
+ * @param {V[]} tree - Tree data
+ * @param {Function} predicate - Predicate function
+ * @param {object} options - Options to customize child element name, reverse traversal, breadth-first traversal. Default: {
     childField: 'children',
     reverse: false,
     breadthFirst: false,
@@ -43,17 +44,17 @@ export declare function forEachDeep<V>(tree: ArrayLike<V>, iterator: (val: V, in
   }
  * @returns {V|null}
  */
-export declare function findDeep<V>(tree: ArrayLike<V>, predicate: (val: V, index: number, currentArr: ArrayLike<V>, tree: ArrayLike<V>, parent: V | null, level: number) => boolean | void, options?: {
+export declare function findDeep<V>(tree: V[], predicate: (val: V, index: number, currentArr: V[], tree: V[], parent: V | null, level: number) => boolean | void, options?: {
     childField?: string;
     reverse?: boolean;
     breadthFirst?: boolean;
     isDomNode?: boolean;
 }): V | null;
 /**
- * 树过滤函数，可用于过滤 Array 和 NodeList 类型的数据
- * @param {ArrayLike<V>} tree  树形数据
- * @param {Function} predicate  断言函数
- * @param {options} options 支持定制子元素名称、反向遍历、广度优先遍历，默认{
+ * Tree filter function, can be used to filter Array and NodeList type data.
+ * @param {V[]} tree - Tree data
+ * @param {Function} predicate - Predicate function
+ * @param {object} options - Options to customize child element name, reverse traversal, breadth-first traversal. Default: {
     childField: 'children',
     reverse: false,
     breadthFirst: false,
@@ -61,76 +62,80 @@ export declare function findDeep<V>(tree: ArrayLike<V>, predicate: (val: V, inde
   }
  * @returns {V[]}
  */
-export declare function filterDeep<V>(tree: ArrayLike<V>, predicate: (val: V, index: number, currentArr: ArrayLike<V>, tree: ArrayLike<V>, parent: V | null, level: number) => boolean | void, options?: {
+export declare function filterDeep<V>(tree: V[], predicate: (val: V, index: number, currentArr: V[], tree: V[], parent: V | null, level: number) => boolean | void, options?: {
     childField?: string;
     reverse?: boolean;
     breadthFirst?: boolean;
     isDomNode?: boolean;
 }): V[];
 /**
- * 创建一个新数组，深度优先遍历的 Map 函数 (支持 continue 和 break 操作), 可用于 insert tree item 和 remove tree item
+ * Creates a new array using a depth-first traversal Map function (supports continue and break operations).
+ * Can be used for inserting or removing tree items.
  *
- * 可遍历任何带有 length 属性和数字键的类数组对象
- * @param {ArrayLike<V>} tree  树形数据
- * @param {Function} iterator  迭代函数，返回值为 true 时 continue, 返回值为 false 时 break
- * @param {options} options 支持定制子元素名称、反向遍历，默认{
+ * Can traverse any array-like object with a length property and numeric keys.
+ * @param {V[]} tree - Tree data
+ * @param {Function} iterator - Iterator function. Returns true to continue, false to break.
+ * @param {object} options - Options to customize child element name, reverse traversal. Default: {
     childField: 'children',
     reverse: false,
   }
- * @returns {any[]} 新的一棵树
+ * @returns {any[]} A new tree structure
  */
 export 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, options?: {
     childField?: string;
     reverse?: boolean;
-    breadthFirst?: boolean;
 }): any[];
 export type IdLike = number | string;
 export type ITreeConf = Omit<IFieldOptions, 'pidField'>;
 /**
- * 在树中找到 id 为某个值的节点，并返回上游的所有父级节点
+ * Retrieves the path (ancestors + self) for a given node ID.
  *
- * @param {ArrayLike<T>} tree - 树形数据
- * @param {number | string} nodeId - 目标元素 ID
- * @param {ITreeConf} options - 迭代配置项，默认：{ children = 'children', id = 'id' }
- * @returns {[(number | string)[], V[]]} - 由 parentId...childId, parentObject-childObject 组成的二维数组
+ * @param {ArrayLike<T>} tree - Tree data
+ * @param {number | string} nodeId - Target node ID
+ * @param {ITreeConf} options - Configuration. Default: { childField = 'children', keyField = 'id' }
+ * @returns {[(number | string)[], V[]]} - Array of IDs and Array of Nodes from root to target
  */
-export declare function searchTreeById<V>(tree: ArrayLike<V>, nodeId: IdLike, options?: ITreeConf): [(number | string)[], any[]];
+export declare function getPathById<V>(tree: V[], nodeId: IdLike, options?: ITreeConf): [(number | string)[], any[]];
+export { getPathById as searchTreeById };
 /**
- * 扁平化数组转换成树
- * @param {any[]} list
- * @param {IFieldOptions} options 定制 id 字段名，子元素字段名，父元素字段名，默认
+ * Converts a flat array into a tree structure.
+ * @param {any[]} list - Flat list of items
+ * @param {IFieldOptions} options - Customizes id field name, child element field name, parent element field name. Default:
  *        { keyField: 'key', childField: 'children', pidField: 'pid' }
- * @returns {any[]}
+ * @returns {any[]} Tree structure array
  */
 export declare function formatTree(list: any[], options?: IFieldOptions): any[];
 /**
- * 树形结构转扁平化
- * @param {any[]} treeList
- * @param {IFieldOptions} options 定制 id 字段名，子元素字段名，父元素字段名，默认
+ * Converts a tree structure into a flat array.
+ * @param {any[]} treeList - Tree structure array
+ * @param {IFieldOptions} options - Customizes id field name, child element field name, parent element field name. Default:
  *        { keyField: 'key', childField: 'children', pidField: 'pid' }
- * @returns {any[]}
+ * @returns {any[]} Flat array
  */
 export declare function flatTree(treeList: any[], options?: IFieldOptions): any[];
 /**
- * 模糊搜索函数，返回包含搜索字符的节点及其祖先节点, 适用于树型组件的字符过滤功能
- * 以下搜索条件二选一，按先后优先级处理：
- * 1. 过滤函数filter, 返回true/false
- * 2. 匹配关键词，支持是否启用忽略大小写来判断
+ * Fuzzy search function that returns nodes containing the search character and their ancestor nodes.
+ * Suitable for character filtering in tree components.
+ *
+ * Two search conditions are available, processed in priority order:
+ * 1. Filter function `filter`, returning true/false.
+ * 2. Keyword matching, supporting case-insensitive check.
  *
- * 有以下特性：
- * 1. 可配置removeEmptyChild字段，来决定是否移除搜索结果中的空children字段
- * 2. 若无任何过滤条件或keyword模式匹配且keyword为空串，返回原对象；其他情况返回新数组
- * @param {V[]} nodes
- * @param {IFilterCondition} filterCondition
- * @param {ISearchTreeOpts} options 默认配置项 {
+ * Features:
+ * 1. Configurable `removeEmptyChild` field to decide whether to remove empty children fields in search results.
+ * 2. If no filter condition is provided, or keyword mode is used with an empty keyword, the original object is returned; otherwise, a new array is returned.
+ *
+ * @param {V[]} nodes - Tree nodes
+ * @param {IFilterCondition} filterCondition - Filter conditions
+ * @param {ISearchTreeOpts} options - Default configuration: {
       childField: 'children',
       nameField: 'name',
       removeEmptyChild: false,
       ignoreCase: true
     }
- * @returns {V[]}
+ * @returns {V[]} Filtered tree nodes
  */
 export declare function fuzzySearchTree<V>(nodes: V[], filterCondition: IFilterCondition<V>, options?: ISearchTreeOpts): V[];
 declare const _default: {
@@ -138,7 +143,8 @@ declare const _default: {
     findDeep: typeof findDeep;
     filterDeep: typeof filterDeep;
     mapDeep: typeof mapDeep;
-    searchTreeById: typeof searchTreeById;
+    getPathById: typeof getPathById;
+    searchTreeById: typeof getPathById;
     formatTree: typeof formatTree;
     flatTree: typeof flatTree;
     fuzzySearchTree: typeof fuzzySearchTree;