@cloudcome/utils-core/dist/tree.d.ts

cloudcome core utils

import { AnyObject } from './types';
/**
 * 表示深度遍历中的节点对象，包含子节点列表。
 */
export type TreeItem = AnyObject & {
    /**
     * 子节点列表。
     */
    children?: TreeItem[];
};
/**
 * 表示深度遍历中的节点列表。
 *
 * @template I - 节点对象的类型，必须继承自 `TreeItem`。
 */
export type TreeList<I extends TreeItem> = I[];
/**
 * 表示深度遍历中的遍历器状态。
 *
 * @template I - 节点对象的类型，必须继承自 `TreeItem`。
 */
export type TreeWalker<I extends TreeItem> = {
    /**
     * 当前层级的节点列表。
     */
    list: TreeList<I>;
    /**
     * 当前节点的父节点，如果为根节点则为 `null`。
     */
    parent: I | null;
    /**
     * 当前节点的层级，从 1 开始计数。
     */
    level: number;
    /**
     * 从根节点到当前节点的路径。
     */
    path: TreeList<I>;
};
/**
 * 表示深度遍历中的节点信息。
 *
 * @template I - 节点对象的类型，必须继承自 `TreeItem`。
 */
export type TreeInfo<I extends TreeItem> = TreeWalker<I> & {
    /**
     * 当前节点。
     */
    item: I;
    /**
     * 当前节点在 `list` 中的索引。
     */
    index: number;
};
/**
 * 深度遍历的同步迭代器函数类型。
 *
 * @template I - 节点对象的类型，必须继承自 `TreeItem`。
 * @param info - 当前节点的信息。
 * @returns 如果返回 `false`，则提前终止遍历。
 */
export type TreeEachIterator<I extends TreeItem> = (info: TreeInfo<I>) => false | unknown;
/**
 * 深度遍历的异步迭代器函数类型。
 *
 * @template I - 节点对象的类型，必须继承自 `TreeItem`。
 * @param info - 当前节点的信息。
 * @returns 如果返回 `false`，则提前终止遍历。
 */
export type TreeEachIteratorAsync<I extends TreeItem> = (info: TreeInfo<I>) => Promise<boolean | unknown>;
/**
 * 深度遍历的同步遍历器函数类型。
 *
 * @template I - 节点对象的类型，必须继承自 `TreeItem`。
 * @param walker - 遍历器状态。
 * @returns 遍历结果。
 */
export type TreeWalk<I extends TreeItem> = (walker: TreeWalker<I>) => unknown;
/**
 * 深度遍历的异步遍历器函数类型。
 *
 * @template I - 节点对象的类型，必须继承自 `TreeItem`。
 * @param walker - 遍历器状态。
 * @returns 异步遍历结果。
 */
export type TreeWalkAsync<I extends TreeItem> = (walker: TreeWalker<I>) => Promise<unknown>;
/**
 * 深度遍历数组中的每个元素，并对每个元素执行提供的回调函数。
 *
 * @param treeList - 要遍历的深度数组。
 * @param iterator - 对每个元素执行的回调函数。如果回调函数返回 `false`，则提前终止遍历。
 * @param breadthFist - 是否使用广度优先遍历，默认为 `false`（深度优先）。
 * @returns 无返回值。
 *
 * @example
 * ```typescript
 * const treeList = [
 *   { value: 1, children: [{ value: 2 }, { value: 3 }] },
 *   { value: 4 }
 * ];
 *
 * treeEach(treeList, (item) => {
 *   console.log(item.value);
 *   if (item.value === 2) return false; // 提前终止遍历
 * });
 * ```
 */
export declare function treeEach<I extends TreeItem = TreeItem>(treeList: TreeList<I>, iterator: TreeEachIterator<I>, breadthFist?: boolean): void;
/**
 * 在深度数组中查找满足条件的第一个节点信息。
 *
 * @param treeList - 要查找的深度数组。
 * @param predicate - 判断节点是否满足条件的回调函数。
 * @param breadthFist - 是否使用广度优先查找，默认为 `false`（深度优先）。
 * @returns 如果找到满足条件的节点，则返回该节点的信息；否则返回 `undefined`。
 *
 * @example
 * ```typescript
 * const treeList = [
 *   { value: 1, children: [{ value: 2 }, { value: 3 }] },
 *   { value: 4 }
 * ];
 *
 * const found = treeFind(treeList, (info) => info.item.value === 3);
 * console.log(found);
 * // {
 * //    item: { value: 3 },
 * //    index: 1,
 * //    list: [{ value: 2 }, { value: 3 }],
 * //    parent: { value: 1, children: [{ value: 2 }, { value: 3 }] },
 * //    level: 2,
 * //    path: [{ value: 1, children: [{ value: 2 }, { value: 3 }] }, { value: 3 }]
 * // }
 * ```
 */
export declare function treeFind<I extends TreeItem>(treeList: TreeList<I>, predicate: (info: TreeInfo<I>) => boolean, breadthFist?: boolean): TreeInfo<I> | undefined;
/**
 * 将深度嵌套的树形结构扁平化为一维数组，并对每个节点执行指定的转换函数。
 *
 * @template I - 树节点的类型，必须继承自 `TreeItem`。
 * @template T - 转换后的数据类型。
 * @param {TreeList<I>} deepList - 要扁平化的深度嵌套树形结构。
 * @param {(info: TreeInfo<I>) => T} flatten - 对每个节点执行的转换函数，返回转换后的数据。
 * @param {boolean} [breadthFist=false] - 是否使用广度优先遍历，默认为 `false`（深度优先）。
 * @returns {T[]} - 转换后的一维数组。
 * @example
 * ```typescript
 * const treeList = [
 *   { value: 1, children: [{ value: 2 }, { value: 3 }] },
 *   { value: 4 }
 * ];
 *
 * const flattened = deepFlat(treeList, (info) => info.item.value);
 * console.log(flattened); // [1, 2, 3, 4]
 * ```
 */
export declare function deepFlat<I extends TreeItem, T>(deepList: TreeList<I>, flatten: (info: TreeInfo<I>) => T, breadthFist?: boolean): T[];
type FromItemInfo<I> = {
    selfKey: unknown;
    parentKey: unknown;
    item: I;
    index: number;
};
export type TreeFromOptions<I extends TreeItem> = {
    getSelfKey: (item: I, index: number) => unknown;
    getParentKey: (item: I, index: number) => unknown;
    appendChild: (parentInfo: FromItemInfo<I>, info: FromItemInfo<I>) => unknown;
};
/**
 * 从扁平列表构建树形结构。
 *
 * @template I - 节点对象的类型，必须继承自 `AnyObject`。
 * @param {I[]} list - 扁平化的节点列表。
 * @param {TreeFromOptions<I>} options - 构建树形结构的配置选项。
 * @param {function} options.getSelfKey - 获取节点自身唯一标识的函数。
 * @param {function} options.getParentKey - 获取节点父节点唯一标识的函数。
 * @param {function} options.appendChild - 将子节点添加到父节点的函数。
 * @returns {I | undefined} - 构建的树形结构的根节点，如果未找到根节点则返回 `undefined`。
 *
 * @example
 * ```typescript
 * const list = [
 *   { id: 1, parentId: null, name: 'Root' },
 *   { id: 2, parentId: 1, name: 'Child 1' },
 *   { id: 3, parentId: 1, name: 'Child 2' }
 * ];
 *
 * const tree = treeFrom(list, {
 *   getSelfKey: (item) => item.id,
 *   getParentKey: (item) => item.parentId,
 *   appendChild: (parent, info) => {
 *     if (!parent.children) parent.children = [];
 *     parent.children.push(info.item);
 *   }
 * });
 *
 * console.log(tree);
 * // {
 * //   id: 1,
 * //   parentId: null,
 * //   name: 'Root',
 * //   children: [
 * //     { id: 2, parentId: 1, name: 'Child 1' },
 * //     { id: 3, parentId: 1, name: 'Child 2' }
 * //   ]
 * // }
 * ```
 */
export declare function treeFrom<I extends TreeItem>(list: I[], options: TreeFromOptions<I>): TreeList<I> | undefined;
export {};