zhiaiwan-utils 1.0.3

package/dist/cjs/string/startsWith.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = startsWith;
+const coerceToString_1 = __importDefault(require("../_internal/coerceToString"));
+const toInteger_1 = __importDefault(require("../_internal/toInteger"));
+/**
+ * 检查字符串是否以 target 开头。
+ *
+ * @param value - 待检查的字符串
+ * @param target - 要匹配的前缀
+ * @param position - 开始匹配的位置，默认为 0
+ * @returns 若匹配返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.startsWith('abc', 'a');
+ * // => true
+ *
+ * zhiaiwanUtils.startsWith('abc', 'b');
+ * // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category String
+ */
+function startsWith(value, target, position = 0) {
+    const string = (0, coerceToString_1.default)(value);
+    const search = (0, coerceToString_1.default)(target);
+    const normalizedPosition = Math.max(0, Math.min((0, toInteger_1.default)(position), string.length));
+    return string.startsWith(search, normalizedPosition);
+}

package/dist/cjs/string/trim.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = trim;
+const coerceToString_1 = __importDefault(require("../_internal/coerceToString"));
+const baseTrim_1 = require("../_internal/baseTrim");
+/**
+ * 移除字符串两端的空白字符，或移除两端在 chars 中出现的字符。
+ *
+ * @param value - 待处理的值
+ * @param chars - 要移除的字符集合；省略时移除空白字符
+ * @returns 裁剪后的字符串
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.trim('  abc  ');
+ * // => 'abc'
+ *
+ * zhiaiwanUtils.trim('-_-abc-_-', '_-');
+ * // => 'abc'
+ * ```
+ *
+ * @since 1.0.0
+ * @category String
+ */
+function trim(value, chars) {
+    return (0, baseTrim_1.trimByChars)((0, coerceToString_1.default)(value), chars, 'both');
+}

package/dist/cjs/string/trimEnd.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = trimEnd;
+const coerceToString_1 = __importDefault(require("../_internal/coerceToString"));
+const baseTrim_1 = require("../_internal/baseTrim");
+/**
+ * 移除字符串末尾的空白字符，或移除末尾在 chars 中出现的字符。
+ *
+ * @param value - 待处理的值
+ * @param chars - 要移除的字符集合；省略时移除空白字符
+ * @returns 裁剪后的字符串
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.trimEnd('  abc  ');
+ * // => '  abc'
+ *
+ * zhiaiwanUtils.trimEnd('-_-abc-_-', '_-');
+ * // => '-_-abc'
+ * ```
+ *
+ * @since 1.0.0
+ * @category String
+ */
+function trimEnd(value, chars) {
+    return (0, baseTrim_1.trimByChars)((0, coerceToString_1.default)(value), chars, 'end');
+}

package/dist/cjs/string/trimStart.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = trimStart;
+const coerceToString_1 = __importDefault(require("../_internal/coerceToString"));
+const baseTrim_1 = require("../_internal/baseTrim");
+/**
+ * 移除字符串开头的空白字符，或移除开头在 chars 中出现的字符。
+ *
+ * @param value - 待处理的值
+ * @param chars - 要移除的字符集合；省略时移除空白字符
+ * @returns 裁剪后的字符串
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.trimStart('  abc  ');
+ * // => 'abc  '
+ *
+ * zhiaiwanUtils.trimStart('-_-abc-_-', '_-');
+ * // => 'abc-_-'
+ * ```
+ *
+ * @since 1.0.0
+ * @category String
+ */
+function trimStart(value, chars) {
+    return (0, baseTrim_1.trimByChars)((0, coerceToString_1.default)(value), chars, 'start');
+}

package/dist/cjs/string/unescape.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = unescape;
+const coerceToString_1 = __importDefault(require("../_internal/coerceToString"));
+const htmlEscape_1 = require("../_internal/htmlEscape");
+/**
+ * 将 HTML 实体还原为对应字符。
+ *
+ * @param value - 待反转义的值
+ * @returns 反转义后的字符串
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.unescape('fred, barney, & pebbles');
+ * // => 'fred, barney, & pebbles'
+ * ```
+ *
+ * @since 1.0.0
+ * @category String
+ */
+function unescape(value) {
+    return (0, htmlEscape_1.unescapeHtml)((0, coerceToString_1.default)(value));
+}

package/dist/cjs/string/upperFirst.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = upperFirst;
+const upperFirst_1 = __importDefault(require("../_internal/upperFirst"));
+/**
+ * 将字符串首字符转换为大写。
+ *
+ * @param string - 待转换字符串
+ * @returns 首字符大写后的字符串
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.upperFirst('fred');
+ * // => 'Fred'
+ * ```
+ *
+ * @since 1.0.0
+ * @category String
+ */
+function upperFirst(string) {
+    return (0, upperFirst_1.default)(String(string !== null && string !== void 0 ? string : ''));
+}

package/dist/cjs/tree/filterTreeNodes.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = filterTreeNodes;
+const baseTreeTraverse_1 = require("../_internal/baseTreeTraverse");
+const forEachTree_1 = __importDefault(require("./forEachTree"));
+/**
+ * 收集树中所有满足 `options.predicate` 的节点；DFS 遍历全部节点。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 遍历与匹配配置，含 `predicate`、`maxDepth` 及字段映射项
+ * @returns 命中节点数组；`predicate` 未传或非函数时返回 `[]`
+ *
+ * @example
+ * ```ts
+ * filterTreeNodes(
+ *   {
+ *     id: 1,
+ *     title: '根',
+ *     children: [
+ *       { id: 2, title: '启用', status: 1 },
+ *       { id: 3, title: '禁用', status: 0 },
+ *     ],
+ *   },
+ *   { predicate: (node) => node.status === 1 },
+ * );
+ * // => [{ id: 2, title: '启用', status: 1 }]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+function filterTreeNodes(tree, options) {
+    if (typeof (options === null || options === void 0 ? void 0 : options.predicate) !== 'function') {
+        return [];
+    }
+    if (tree == null) {
+        return [];
+    }
+    const { predicate, maxDepth: maxDepthInput, ...traverseOptions } = options;
+    const maxDepth = (0, baseTreeTraverse_1.normalizeTreeMaxDepth)(maxDepthInput);
+    const matched = [];
+    (0, forEachTree_1.default)(tree, (node, parent, depth, index, meta) => {
+        if (predicate(node, parent, depth, index, meta)) {
+            matched.push(node);
+        }
+    }, { ...traverseOptions, maxDepth });
+    return matched;
+}

package/dist/cjs/tree/findTreeNode.js

@@ -0,0 +1,45 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = findTreeNode;
+const baseTreeTraverse_1 = require("../_internal/baseTreeTraverse");
+const forEachTree_1 = __importDefault(require("./forEachTree"));
+/**
+ * 在树中查找第一个满足 `options.predicate` 的节点；找到后立即停止 DFS 遍历。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 遍历与匹配配置，含 `predicate`、`maxDepth` 及字段映射项
+ * @returns 命中的节点；`predicate` 未传或非函数时返回 `null`，未找到时返回 `undefined`
+ *
+ * @example
+ * ```ts
+ * findTreeNode(
+ *   { id: 1, title: '根', children: [{ id: 2, title: '子' }] },
+ *   { predicate: (node) => node.id === 2 },
+ * );
+ * // => { id: 2, title: '子' }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+function findTreeNode(tree, options) {
+    if (typeof (options === null || options === void 0 ? void 0 : options.predicate) !== 'function') {
+        return null;
+    }
+    if (tree == null) {
+        return undefined;
+    }
+    const { predicate, maxDepth: maxDepthInput, ...traverseOptions } = options;
+    const maxDepth = (0, baseTreeTraverse_1.normalizeTreeMaxDepth)(maxDepthInput);
+    let matched;
+    (0, forEachTree_1.default)(tree, (node, parent, depth, index, meta) => {
+        if (predicate(node, parent, depth, index, meta)) {
+            matched = node;
+            return false;
+        }
+    }, { ...traverseOptions, maxDepth });
+    return matched;
+}

package/dist/cjs/tree/forEachTree.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = forEachTree;
+const baseTreeTraverse_1 = __importDefault(require("../_internal/baseTreeTraverse"));
+/**
+ * 深度优先遍历树；iteratee 返回 `false` 时立即停止，并返回原树。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param iteratee - 每次访问节点时调用，接收 `(node, parent, depth, index, meta)`，`meta` 含 `parentNodes`
+ * @param options - 遍历选项，含 `maxDepth`、`childrenKey`、`keyField`、`parentIdField`、`labelField`、`getKey`、`getParentKey`、`getLabel`
+ * @returns 原树
+ *
+ * @example
+ * ```ts
+ * forEachTree(
+ *   { id: 1, children: [{ id: 2 }, { id: 3 }] },
+ *   (node) => {
+ *     if (node.id === 2) return false;
+ *   },
+ * );
+ * // 访问 1、2 后停止
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+function forEachTree(tree, iteratee, options) {
+    (0, baseTreeTraverse_1.default)(tree, iteratee, options, 'dfs', true);
+    return tree;
+}

package/dist/cjs/tree/getParentNodes.js

@@ -0,0 +1,49 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = getParentNodes;
+const baseTreeTraverse_1 = require("../_internal/baseTreeTraverse");
+const forEachTree_1 = __importDefault(require("./forEachTree"));
+/**
+ * 查找第一个满足 `options.predicate` 的目标节点，并返回其全部父级节点（从根到直接父节点，不含目标节点本身）。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 遍历与匹配配置，含 `predicate`、`maxDepth` 及字段映射项
+ * @returns 父级节点数组；根节点命中时返回 `[]`；`predicate` 未传或非函数时返回 `null`；未找到或空树时返回 `undefined`
+ *
+ * @example
+ * ```ts
+ * getParentNodes(
+ *   {
+ *     id: 1,
+ *     title: '根',
+ *     children: [{ id: 2, title: '子', children: [{ id: 3, title: '孙' }] }],
+ *   },
+ *   { predicate: (node) => node.id === 3 },
+ * );
+ * // => [{ id: 1, title: '根' }, { id: 2, title: '子' }]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+function getParentNodes(tree, options) {
+    if (typeof (options === null || options === void 0 ? void 0 : options.predicate) !== 'function') {
+        return null;
+    }
+    if (tree == null) {
+        return undefined;
+    }
+    const { predicate, maxDepth: maxDepthInput, ...traverseOptions } = options;
+    const maxDepth = (0, baseTreeTraverse_1.normalizeTreeMaxDepth)(maxDepthInput);
+    let parentNodes;
+    (0, forEachTree_1.default)(tree, (node, parent, depth, index, meta) => {
+        if (predicate(node, parent, depth, index, meta)) {
+            parentNodes = meta.parentNodes;
+            return false;
+        }
+    }, { ...traverseOptions, maxDepth });
+    return parentNodes;
+}

package/dist/cjs/tree/getTreeDepth.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = getTreeDepth;
+const baseTreeTraverse_1 = __importDefault(require("../_internal/baseTreeTraverse"));
+/**
+ * 获取树（或森林）的最大深度；根节点 `depth` 为 `0`。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 与 `forEachTree` 相同的 `TreeTraverseOptions`（`maxDepth` 限制下探范围）
+ * @returns 最大深度；`null`/`undefined` 时返回 `0`
+ *
+ * @example
+ * ```ts
+ * getTreeDepth({
+ *   id: 1,
+ *   children: [{ id: 2, children: [{ id: 3 }] }],
+ * });
+ * // => 2
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+function getTreeDepth(tree, options) {
+    if (tree == null) {
+        return 0;
+    }
+    let maxDepth = 0;
+    (0, baseTreeTraverse_1.default)(tree, (_node, _parent, depth) => {
+        if (depth > maxDepth) {
+            maxDepth = depth;
+        }
+    }, options, 'dfs', false, true);
+    return maxDepth;
+}

package/dist/cjs/tree/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TREE_TRAVERSE_FIELDS = exports.pruneTree = exports.mapTree = exports.getTreeDepth = exports.toFlatList = exports.toTree = exports.getParentNodes = exports.filterTreeNodes = exports.findTreeNode = exports.forEachTree = exports.traverseTreeBfs = exports.traverseTree = void 0;
+var traverseTree_1 = require("./traverseTree");
+Object.defineProperty(exports, "traverseTree", { enumerable: true, get: function () { return __importDefault(traverseTree_1).default; } });
+var traverseTreeBfs_1 = require("./traverseTreeBfs");
+Object.defineProperty(exports, "traverseTreeBfs", { enumerable: true, get: function () { return __importDefault(traverseTreeBfs_1).default; } });
+var forEachTree_1 = require("./forEachTree");
+Object.defineProperty(exports, "forEachTree", { enumerable: true, get: function () { return __importDefault(forEachTree_1).default; } });
+var findTreeNode_1 = require("./findTreeNode");
+Object.defineProperty(exports, "findTreeNode", { enumerable: true, get: function () { return __importDefault(findTreeNode_1).default; } });
+var filterTreeNodes_1 = require("./filterTreeNodes");
+Object.defineProperty(exports, "filterTreeNodes", { enumerable: true, get: function () { return __importDefault(filterTreeNodes_1).default; } });
+var getParentNodes_1 = require("./getParentNodes");
+Object.defineProperty(exports, "getParentNodes", { enumerable: true, get: function () { return __importDefault(getParentNodes_1).default; } });
+var toTree_1 = require("./toTree");
+Object.defineProperty(exports, "toTree", { enumerable: true, get: function () { return __importDefault(toTree_1).default; } });
+var toFlatList_1 = require("./toFlatList");
+Object.defineProperty(exports, "toFlatList", { enumerable: true, get: function () { return __importDefault(toFlatList_1).default; } });
+var getTreeDepth_1 = require("./getTreeDepth");
+Object.defineProperty(exports, "getTreeDepth", { enumerable: true, get: function () { return __importDefault(getTreeDepth_1).default; } });
+var mapTree_1 = require("./mapTree");
+Object.defineProperty(exports, "mapTree", { enumerable: true, get: function () { return __importDefault(mapTree_1).default; } });
+var pruneTree_1 = require("./pruneTree");
+Object.defineProperty(exports, "pruneTree", { enumerable: true, get: function () { return __importDefault(pruneTree_1).default; } });
+var baseTreeTraverse_1 = require("../_internal/baseTreeTraverse");
+Object.defineProperty(exports, "DEFAULT_TREE_TRAVERSE_FIELDS", { enumerable: true, get: function () { return baseTreeTraverse_1.DEFAULT_TREE_TRAVERSE_FIELDS; } });

package/dist/cjs/tree/mapTree.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = mapTree;
+const baseTreeTraverse_1 = require("../_internal/baseTreeTraverse");
+function getChildNodes(node, childrenKey) {
+    if (node == null || typeof node !== 'object') {
+        return [];
+    }
+    const children = node[childrenKey];
+    return Array.isArray(children) ? children : [];
+}
+function shouldDescendTree(resolved, depth) {
+    return resolved.maxDepth === 0 || depth < resolved.maxDepth;
+}
+function isTreeCycle(node, nodeKey, pathKeys, pathObjects) {
+    if (pathKeys.has(nodeKey)) {
+        return true;
+    }
+    if (node != null && typeof node === 'object' && pathObjects.has(node)) {
+        return true;
+    }
+    return false;
+}
+function enterTreePath(node, nodeKey, pathKeys, pathObjects) {
+    pathKeys.add(nodeKey);
+    if (node != null && typeof node === 'object') {
+        pathObjects.add(node);
+    }
+}
+function exitTreePath(node, nodeKey, pathKeys, pathObjects) {
+    pathKeys.delete(nodeKey);
+    if (node != null && typeof node === 'object') {
+        pathObjects.delete(node);
+    }
+}
+function mapTreeNode(node, parent, parentNodes, depth, index, mapper, resolved, pathKeys, pathObjects) {
+    const { childrenKey, getKey } = resolved;
+    const nodeKey = getKey(node);
+    if (isTreeCycle(node, nodeKey, pathKeys, pathObjects)) {
+        return undefined;
+    }
+    enterTreePath(node, nodeKey, pathKeys, pathObjects);
+    const mapped = mapper(node, parent, depth, index, { parentNodes });
+    const record = mapped;
+    if (shouldDescendTree(resolved, depth)) {
+        const children = getChildNodes(node, childrenKey);
+        const mappedChildren = [];
+        for (let childIndex = 0; childIndex < children.length; childIndex++) {
+            const mappedChild = mapTreeNode(children[childIndex], node, parentNodes.concat(node), depth + 1, childIndex, mapper, resolved, pathKeys, pathObjects);
+            if (mappedChild !== undefined) {
+                mappedChildren.push(mappedChild);
+            }
+        }
+        if (mappedChildren.length > 0) {
+            record[childrenKey] = mappedChildren;
+        }
+        else {
+            delete record[childrenKey];
+        }
+    }
+    else {
+        delete record[childrenKey];
+    }
+    exitTreePath(node, nodeKey, pathKeys, pathObjects);
+    return mapped;
+}
+/**
+ * 映射树节点并保留树形结构；不修改原树，返回新树。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param mapper - 节点映射函数，签名为 `(node, parent, depth, index, meta)`，`meta` 含 `parentNodes`
+ * @param options - 与 `forEachTree` 相同的 `TreeTraverseOptions`（`maxDepth` 限制递归深度）
+ * @returns 映射后的新树；`null`/`undefined` 原样返回
+ *
+ * @example
+ * ```ts
+ * mapTree(
+ *   { id: 1, title: '根', children: [{ id: 2, title: '子' }] },
+ *   (node) => ({ ...node, title: `[${node.title}]` }),
+ * );
+ * // => { id: 1, title: '[根]', children: [{ id: 2, title: '[子]' }] }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+function mapTree(tree, mapper, options) {
+    if (tree == null) {
+        return tree;
+    }
+    const resolved = (0, baseTreeTraverse_1.resolveTreeTraverseOptions)(options);
+    if (Array.isArray(tree)) {
+        return tree
+            .map((node, index) => mapTreeNode(node, null, [], 0, index, mapper, resolved, new Set(), new Set()))
+            .filter((node) => node !== undefined);
+    }
+    return mapTreeNode(tree, null, [], 0, 0, mapper, resolved, new Set(), new Set());
+}

package/dist/cjs/tree/pruneTree.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = pruneTree;
+const baseTreeTraverse_1 = require("../_internal/baseTreeTraverse");
+function getChildNodes(node, childrenKey) {
+    if (node == null || typeof node !== 'object') {
+        return [];
+    }
+    const children = node[childrenKey];
+    return Array.isArray(children) ? children : [];
+}
+function shouldDescendTree(resolved, depth) {
+    return resolved.maxDepth === 0 || depth < resolved.maxDepth;
+}
+function isTreeCycle(node, nodeKey, pathKeys, pathObjects) {
+    if (pathKeys.has(nodeKey)) {
+        return true;
+    }
+    if (node != null && typeof node === 'object' && pathObjects.has(node)) {
+        return true;
+    }
+    return false;
+}
+function enterTreePath(node, nodeKey, pathKeys, pathObjects) {
+    pathKeys.add(nodeKey);
+    if (node != null && typeof node === 'object') {
+        pathObjects.add(node);
+    }
+}
+function exitTreePath(node, nodeKey, pathKeys, pathObjects) {
+    pathKeys.delete(nodeKey);
+    if (node != null && typeof node === 'object') {
+        pathObjects.delete(node);
+    }
+}
+function pruneTreeNode(node, parent, parentNodes, depth, index, predicate, resolved, pathKeys, pathObjects) {
+    const { childrenKey, getKey } = resolved;
+    const nodeKey = getKey(node);
+    if (isTreeCycle(node, nodeKey, pathKeys, pathObjects)) {
+        return undefined;
+    }
+    enterTreePath(node, nodeKey, pathKeys, pathObjects);
+    const meta = { parentNodes };
+    if (predicate(node, parent, depth, index, meta)) {
+        exitTreePath(node, nodeKey, pathKeys, pathObjects);
+        return undefined;
+    }
+    const sourceChildren = getChildNodes(node, childrenKey);
+    let outputChildren;
+    if (shouldDescendTree(resolved, depth)) {
+        const prunedChildren = [];
+        for (let childIndex = 0; childIndex < sourceChildren.length; childIndex++) {
+            const prunedChild = pruneTreeNode(sourceChildren[childIndex], node, parentNodes.concat(node), depth + 1, childIndex, predicate, resolved, pathKeys, pathObjects);
+            if (prunedChild !== undefined) {
+                prunedChildren.push(prunedChild);
+            }
+        }
+        if (prunedChildren.length === 0 && sourceChildren.length > 0) {
+            exitTreePath(node, nodeKey, pathKeys, pathObjects);
+            return undefined;
+        }
+        if (prunedChildren.length > 0) {
+            outputChildren = prunedChildren;
+        }
+    }
+    else if (sourceChildren.length > 0) {
+        outputChildren = sourceChildren;
+    }
+    exitTreePath(node, nodeKey, pathKeys, pathObjects);
+    const record = { ...node };
+    if (outputChildren && outputChildren.length > 0) {
+        record[childrenKey] = outputChildren;
+    }
+    else {
+        delete record[childrenKey];
+    }
+    return record;
+}
+/**
+ * 按条件剔除树节点并返回新树；不修改原树。
+ *
+ * - `predicate` 返回真值的节点会被剔除；命中中间节点时，其子树一并移除，子节点不会上提。
+ * - 若某节点原有子节点，剔除后 `children` 为空，则该节点也会被剔除，并向上递归剔除空壳父节点。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 遍历与剔除配置，含 `predicate`、`maxDepth` 及字段映射项
+ * @returns 剔除后的新树；`predicate` 未传或非函数时返回 `null`；根被全部剔除时单根返回 `undefined`、森林返回 `[]`
+ *
+ * @example
+ * ```ts
+ * pruneTree(
+ *   {
+ *     id: 1,
+ *     title: '根',
+ *     children: [
+ *       { id: 2, title: '' },
+ *       { id: 3, title: '保留' },
+ *     ],
+ *   },
+ *   { predicate: (node) => !node.title?.trim() },
+ * );
+ * // => { id: 1, title: '根', children: [{ id: 3, title: '保留' }] }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+function pruneTree(tree, options) {
+    if (typeof (options === null || options === void 0 ? void 0 : options.predicate) !== 'function') {
+        return null;
+    }
+    if (tree == null) {
+        return tree;
+    }
+    const { predicate, maxDepth: maxDepthInput, ...traverseOptions } = options;
+    const resolved = (0, baseTreeTraverse_1.resolveTreeTraverseOptions)({
+        ...traverseOptions,
+        maxDepth: maxDepthInput,
+    });
+    if (Array.isArray(tree)) {
+        return tree
+            .map((node, index) => pruneTreeNode(node, null, [], 0, index, predicate, resolved, new Set(), new Set()))
+            .filter((node) => node !== undefined);
+    }
+    return pruneTreeNode(tree, null, [], 0, 0, predicate, resolved, new Set(), new Set());
+}