@jckj/tree-util 1.1.11 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +193 -1
  2. package/package.json +4 -2
  3. package/types.d.ts +91 -1
package/README.md CHANGED
@@ -1 +1,193 @@
1
- ### 第一次提交
1
+ # @jckj/tree-util
2
+
3
+ 🚀 高性能、轻量级的树形数据结构操作工具库。
4
+
5
+ 针对前端大数据量树形操作(如万级节点组织架构树)进行了极致优化,提供了扁平化与树形结构的相互转换、节点查找、路径追溯、过滤、映射及 Immutable 更新等全套 API。
6
+
7
+ ## ✨ 核心亮点
8
+
9
+ - **极致性能**:抛弃低效的深拷贝与递归,采用浅拷贝 + 惰性挂载 + 双循环字典寻址,`arrayToTree` 速度提升 10 倍以上。
10
+ - **栈迭代防溢出**:核心遍历方法(`treeToArray`, `forEachNode`, `getNodeById`)全部使用栈模拟递归,彻底告别万层深度数据的 `Maximum call stack size exceeded` 报错。
11
+ - **V8 引擎友好**:避免使用 `delete` 操作符防止对象退化为慢属性模式,采用解构赋值保持对象 Hidden Class 稳定。
12
+ - **Immutable 更新**:提供 `updateNodeById`,浅拷贝变化路径上的节点,完美契合 React 等框架的状态更新需求。
13
+ - **全量 TypeScript**:使用泛型提供完善的类型推导,保留原始数据类型约束。
14
+ - **零依赖**:纯逻辑实现,无任何第三方依赖,体积微小。
15
+
16
+ ## 📦 安装
17
+
18
+ ```bash
19
+ # npm
20
+ npm install @jckj/tree-util
21
+
22
+ # yarn
23
+ yarn add @jckj/tree-util
24
+
25
+ # pnpm
26
+ pnpm add @jckj/tree-util
27
+ ```
28
+
29
+ ## 📖 使用文档
30
+
31
+ ### 🛠基础配置(TreeOptions)
32
+
33
+ > 所有方法均支持传入可选的配置项 options,以适配不同后端的数据字段命名:
34
+
35
+ | 参数 | 类型 | 默认值 | 说明 |
36
+ | ----------- | ------------------ | ----------- | -------------------- |
37
+ | idKey | keyof T | `id` | 节点唯一标识字段名 |
38
+ | parentKey | keyof T | `parent_id` | 父节点唯一标识字段名 |
39
+ | childrenKey | `string` | `children` | 子节点字段名 |
40
+ | rootId | `string`\|`number` | '0' | 根节点标识 |
41
+ | isTree | `boolean` | `false` | 是否为树形结构 |
42
+
43
+ ### 使用实例
44
+
45
+ > 假设我们有如下扁平数据和树形数据:
46
+
47
+ ```ts
48
+ const flatArr = [
49
+ { id: 1, parent_id: 0, name: "总部" },
50
+ { id: 2, parent_id: 1, name: "研发部" },
51
+ { id: 3, parent_id: 1, name: "产品部" },
52
+ { id: 4, parent_id: 2, name: "前端组" },
53
+ ];
54
+
55
+ const treeArr = [
56
+ {
57
+ id: 1,
58
+ parent_id: 0,
59
+ name: "总部",
60
+ children: [
61
+ {
62
+ id: 2,
63
+ parent_id: 1,
64
+ name: "研发部",
65
+ children: [{ id: 4, parent_id: 2, name: "前端组" }],
66
+ },
67
+ { id: 3, parent_id: 1, name: "产品部" },
68
+ ],
69
+ },
70
+ ];
71
+ ```
72
+
73
+ 1. `arrayToTree`:将扁平化数据转换为树形结构。
74
+ > 将扁平化的节点数组转换为嵌套的树形数据结构。
75
+ > 优化点:O(2N) 双循环 + 字典 O(1) 寻址 + 浅拷贝避免副作用 + 惰性创建 children 数组节省内存。
76
+
77
+ ```ts
78
+ import { arrayToTree } from "@jckj/tree-util";
79
+
80
+ const tree = arrayToTree(flatArr);
81
+ // 结果: treeArr
82
+ ```
83
+
84
+ 2. `treeToArray`:将树形结构转换为扁平化数据。
85
+ > 将树形结构扁平化为一维数组。
86
+
87
+ ```ts
88
+ import { treeToArray } from "@jckj/tree-util";
89
+
90
+ const flat = treeToArray(treeArr);
91
+ // 结果: flatArr
92
+ ```
93
+
94
+ 3. forEachNode<T>(treeData, callback, options?)
95
+ 遍历树中的每一个节点(类似数组的 forEach)。
96
+
97
+ ```ts
98
+ import { forEachNode } from "@jckj/tree-util";
99
+
100
+ forEachNode(treeArr, (item, list) => {
101
+ if (item.id === 4) console.log("找到前端组:", item);
102
+ });
103
+ ```
104
+
105
+ 4. getNodeById<T>(treeData, nodeId, options?)
106
+ 根据 ID 在树中查找节点引用,找到即提前返回,避免无效遍历。
107
+
108
+ ```ts
109
+ import { getNodeById } from "@jckj/tree-util";
110
+
111
+ const node = getNodeById(treeArr, 4);
112
+ // 结果: { id: 4, parent_id: 2, name: '前端组' }
113
+ ```
114
+
115
+ 5. getChildrenToList<T>(treeData, nodeId, options?)
116
+ 获取某个节点及其所有子节点组成的一维数组(不包含自身则只返回子节点树转数组)。内部复用 getNodeById 和 treeToArray。
117
+
118
+ ```ts
119
+ import { getChildrenToList } from "@jckj/tree-util";
120
+
121
+ const children = getChildrenToList(treeArr, 2);
122
+ // 结果: [{ id: 4, parent_id: 2, name: '前端组' }]
123
+ ```
124
+
125
+ 6. getParentNodes<T>(treeData, nodeId, options?)
126
+ 获取某个节点的所有祖先节点路径(从自己往上一直到根)。
127
+ 优化点:先 O(N) 扁平化建字典,再 O(1) 向上追溯,总复杂度 O(N)。支持直接传入扁平数组(配置 isTree: false)。
128
+
129
+ ```ts
130
+ import { getParentNodes } from "@jckj/tree-util";
131
+
132
+ const parents = getParentNodes(treeArr, 4, { isTree: true });
133
+ // 结果: [{ id: 4, name: '前端组' }, { id: 2, name: '研发部' }, { id: 1, name: '总部' }]
134
+ ```
135
+
136
+ 7. filterTree<T>(treeData, predicate, options?)
137
+ 过滤树节点,保留命中节点及其祖先路径。典型场景:树形组件的模糊搜索功能。如果子节点命中,其父节点必须保留,否则树结构断裂。
138
+ 算法:后序遍历(自底向上),子节点被保留则强制保留父节点。
139
+
140
+ ```ts
141
+ import { filterTree } from "@jckj/tree-util";
142
+
143
+ // 搜索包含 "前端" 的节点
144
+ const filtered = filterTree(treeArr, (node) => node.name.includes("前端"));
145
+ // 结果: 保留了 前端组、研发部、总部 (保证树结构完整)
146
+ ```
147
+
148
+ 8. mapTree<T, U>(treeData, mapper, options?)
149
+ 映射树节点(类似 Array.map),但保持树形结构。典型场景:批量修改节点属性或提取特定字段。
150
+
151
+ ```ts
152
+ import { mapTree } from "@jckj/tree-util";
153
+
154
+ // 给所有节点增加一个 disabled 属性
155
+ const newTree = mapTree(treeArr, (node) => ({
156
+ ...node,
157
+ disabled: node.id === 3, // 将产品部禁用
158
+ }));
159
+ ```
160
+
161
+ 9. updateNodeById<T>(treeData, nodeId, updater, options?)
162
+ Immutable 更新树节点。根据 ID 查找并更新,返回一棵新树。
163
+ 场景:React setState 修改树中某个节点,不能直接 mutate 原树。
164
+ 算法:浅拷贝路径上的节点,最大化引用不变(时间复杂度 O(N))。
165
+
166
+ ```ts
167
+ import { updateNodeById } from "@jckj/tree-util";
168
+ import { useState } from "react";
169
+
170
+ const [tree, setTree] = useState(treeArr);
171
+
172
+ const handleClick = (id) => {
173
+ setTree((prevTree) =>
174
+ updateNodeById(prevTree, id, (node) => ({
175
+ ...node,
176
+ // 修改你需要的属性
177
+ selected: true,
178
+ })),
179
+ );
180
+ };
181
+ import { treeToArray } from "@jckj/tree-util";
182
+
183
+ const flat = treeToArray(treeArr);
184
+ // 结果: flatArr (顺序为深度优先遍历顺序)
185
+ ```
186
+
187
+ ## 🤝 贡献
188
+
189
+ 欢迎提交 PR 或 Issue,共同完善这个项目。
190
+
191
+ ## 📝 许可证
192
+
193
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jckj/tree-util",
3
- "version": "1.1.11",
3
+ "version": "1.2.0",
4
4
  "publishConfig": {
5
5
  "access": "public",
6
6
  "registry": "https://registry.npmjs.org/"
@@ -27,7 +27,9 @@
27
27
  },
28
28
  "keywords": [
29
29
  "tree",
30
- "util"
30
+ "util",
31
+ "tree-util",
32
+ "tree-util-ts"
31
33
  ],
32
34
  "author": "chuz1 <jckjsjz@163.com>",
33
35
  "license": "MIT",
package/types.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- declare module "tree-util-jc" {
1
+ declare module "tree-util" {
2
2
  /**
3
3
  * #### 树形结构操作配置选项
4
4
  * @template T 原始数据项的类型
@@ -15,8 +15,98 @@ declare module "tree-util-jc" {
15
15
  /** 传入的 data 是否已经是树形结构 (用于 getParentNodes 判断) */
16
16
  isTree?: boolean;
17
17
  }
18
+ /**
19
+ * #### 将扁平化的节点数组转换为嵌套的树形数据结构 (大数据量优化版)
20
+ * 核心优化:
21
+ * 1. 废弃 deepClone,采用浅拷贝 + 惰性挂载,速度提升 10 倍以上
22
+ * 2. 双循环 O(2N) 算法,利用字典 O(1) 寻址
23
+ */
18
24
  export function arrayToTree<T extends object>(
19
25
  arr: T[],
20
26
  options?: TreeOptions<T>,
21
27
  ): T[];
28
+
29
+ /**
30
+ * #### 将树形结构扁平化为一维数组 (大数据量优化版)
31
+ * 核心优化:
32
+ * 1. 迭代法(栈)替代递归,防止 1万层以上数据栈溢出
33
+ * 2. 使用解构提取 rest,避免 delete 操作导致 V8 对象退化为慢属性模式
34
+ */
35
+ export function treeToArray<T extends object>(
36
+ tree: T[],
37
+ options?: TreeOptions<T>,
38
+ ): T[];
39
+
40
+ /**
41
+ * #### 遍历树中的每一个节点 (迭代法优化)
42
+ * 使用栈模拟递归,避免栈溢出,提升性能
43
+ */
44
+ export function forEachNode<T extends object>(
45
+ treeData: T[],
46
+ callback: (item: T, list: T[]) => void,
47
+ options?: TreeOptions<T>,
48
+ ): void;
49
+
50
+ /**
51
+ * #### 根据 ID 在树中查找节点 (迭代法优化)
52
+ * 找到即提前返回,避免继续遍历整棵树
53
+ */
54
+ export function getNodeById<T extends object>(
55
+ treeData: T[],
56
+ nodeId: number | string,
57
+ options?: TreeOptions<T>,
58
+ ): T | undefined;
59
+
60
+ /**
61
+ * #### 获取某个节点及其所有子节点组成的一维数组
62
+ * 复用 getNodeById 和 treeToArray
63
+ */
64
+ export function getChildrenToList<T extends object>(
65
+ treeData: T[],
66
+ nodeId: string | number,
67
+ options?: TreeOptions<T>,
68
+ ): T[];
69
+
70
+ /**
71
+ * #### 获取某个节点的所有祖先节点路径 (从自己往上一直到根)
72
+ * 核心优化:先 O(N) 扁平化并建字典,再 O(1) 向上追溯,总复杂度 O(N)
73
+ */
74
+ export function getParentNodes<T extends object>(
75
+ treeData: T[],
76
+ nodeId: string | number,
77
+ options?: TreeOptions<T>,
78
+ ): T[];
79
+
80
+ /**
81
+ * #### 过滤树节点 (保留命中节点及其祖先路径)
82
+ * 场景:树形组件搜索功能。如果子节点命中,其父节点必须保留,否则树结构断裂。
83
+ * 算法:后序遍历(自底向上),如果子节点被保留,则父节点强制保留
84
+ */
85
+ export function filterTree<T extends object>(
86
+ treeData: T[],
87
+ predicate: (node: T) => boolean,
88
+ options?: TreeOptions<T>,
89
+ ): T[];
90
+
91
+ /**
92
+ * #### 映射树节点 (类似 Array.map,但保持树形结构)
93
+ * 场景:批量修改树节点的某些属性,或提取特定字段组成新树
94
+ */
95
+ export function mapTree<T extends object, U extends object>(
96
+ treeData: T[],
97
+ mapper: (node: T) => U,
98
+ options?: TreeOptions<T>,
99
+ ): U[];
100
+
101
+ /**
102
+ * #### Immutable 更新树节点 (根据 ID 查找并更新,返回新树)
103
+ * 场景:React setState 修改树中某个节点的属性,不能直接 mutate 原树
104
+ * 算法:浅拷贝路径上的节点,保证引用不变的最大化(时间复杂度 O(N))
105
+ */
106
+ export function updateNodeById<T extends object>(
107
+ treeData: T[],
108
+ nodeId: string | number,
109
+ updater: (node: T) => T, // 接收旧节点,返回新节点的函数
110
+ options?: TreeOptions<T>,
111
+ ): T[];
22
112
  }