@utopia-utils/tree/dist/index.d.mts

Collection of common tree utils

//#region src/type.d.ts
interface FieldNames {
  id?: string;
  children?: string;
  parentId?: string;
}
//#endregion
//#region src/breadthFirstTraverse.d.ts
interface Options$6 {
  /** Customize node children field name */
  fieldNames?: Pick<FieldNames, "children">;
}
/**
* Breadth-First Traverse (BFS or 广度优先遍历)
* @param {TreeNode[] | TreeNode} tree - The tree to traverse.
* @param action - (node: TreeNode) => unknown ; function called for each node in the tree, return false to stop traverse
* @param {Options} [options]
* @linkcode https://github.com/GreatAuk/utopia-utils/blob/main/packages/tree/src/breadthFirstTraverse.ts
* @example
* ```
const tree = [
{
name: 'a',
Children_: [
{ name: 'b' }
],
},
{
name: 'c',
}
]
breadthFirstTraverse(tree, node => console.log(node.name), {
fieldNames: {
children: 'Children_', // default is children
}
})
// output 'a', 'c', 'b'
* ```
*/
declare function breadthFirstTraverse<TreeNode>(tree: TreeNode[] | TreeNode, action: (node: TreeNode) => unknown, options?: Options$6): void;
//#endregion
//#region src/buildTreeFromList.d.ts
interface Options$5 {
  /**
  * custom list field names
  *
  * @default { id: 'id', parentId: 'parentId', children: 'children' }
  */
  listFieldNames?: FieldNames;
  /**
  * custom tree field names
  *
  * @default { id: 'id', parentId: 'parentId', children: 'children' }
  */
  treeFieldNames?: FieldNames;
}
/**
* It takes a list of items and returns a tree of items
* @param {any[]} list - the list of items to be converted to a tree
* @param {Options} [options] - {
* @returns A tree structure
* @linkcode https://github.com/GreatAuk/utopia-utils/blob/main/packages/tree/src/buildTreeFromList.ts
* @example
* ```
const list = [
{ uid: '1', title: 'node 1', pid: '' },
{ uid: '1-1', title: 'node 1-1', pid: '1' },
{ uid: '1-2', title: 'node 1-2', pid: '1' },
{ uid: '1-1-1', title: 'node 1-1-1', pid: '1-1' },
]

interface TreeNode {
key: string
title: string
children: TreeNode[]
pid: string
}
const tree = buildTreeFromList<TreeNode>(list, {
listFieldNames: { id: 'uid', parentId: 'pid', children: '_Children' },
treeFieldNames: { id: 'key', parentId: 'pid', children: 'children' },
})
* ```
*/
declare function buildTreeFromList<TreeNode>(list: any[], options?: Options$5): TreeNode[];
//#endregion
//#region src/deepFirstTraverse.d.ts
interface Options$4 {
  /** Customize node children field name */
  fieldNames?: Pick<FieldNames, "children">;
  /** Traverse order, support 'pre' and 'post' */
  order?: "pre" | "post";
}
interface TraverseAction<TreeNode> {
  (node: TreeNode, parent: TreeNode | null, level: number): unknown;
}
/**
* The function performs a deep first traversal of a tree data structure and applies a given action to
* each node.
* @param {TreeNode | TreeNode[]} tree - The tree parameter is either a single TreeNode or an array of
* TreeNodes.
* @param action - The function to be executed on each node of the tree during traversal. It takes
* three arguments: the current node, its parent node (or null if it's the root node), and the current
* level of the node in the tree. If the action function returns false, the traversal will be stopped.
* @param {Options} [options]
* @linkcode https://github.com/GreatAuk/utopia-utils/blob/main/packages/tree/src/deepFirstTraverse.ts
* @example
* ```ts
* const tree = [
*  {
*    name: 'a',
*    children: [
*      { name: 'b' }
*    ],
*  },
*  {
*    name: 'c',
*  }
* ]
* deepFirstTraverse(tree, node => console.log(node.name))
* // output 'a', 'b', 'c'
* ```
*/
declare function deepFirstTraverse<TreeNode>(tree: TreeNode | TreeNode[], action: TraverseAction<TreeNode>, options?: Options$4): void;
//#endregion
//#region src/flattenTree.d.ts
interface Options$3<TreeNode> {
  /**
  * customize node field name
  *
  * @default { id: 'id', parentId: 'parentId', children: 'children' }
  */
  fieldNames?: FieldNames;
  /** Function called for each node in the tree */
  onEachTraverse?: (node: TreeNode) => void;
}
/**
* It takes a tree and returns a flat array of all the nodes in the tree
* @param {TreeNode | TreeNode[]} tree - The tree to flatten.
* @param [options]
* @returns An array of all the nodes in the tree.
* @linkcode https://github.com/GreatAuk/utopia-utils/blob/main/packages/tree/src/flattenTree.ts
* @example
* ```
const tree = {
id: 1,
children: [
{
id: 2,
},
],
}
const list = flattenTree(tree)
console.log(list)
// output
// [
//   {
//     "ID": 1,
//     "children": [
//       {
//         "ID": 2,
//       },
//     ],
//   },
//   {
//     "ID": 2,
//   },
// ]
* ```
*/
declare function flattenTree<TreeNode>(tree: TreeNode | TreeNode[], options?: Options$3<TreeNode>): TreeNode[];
//#endregion
//#region src/treeFilterNode.d.ts
interface Options$2<TreeNode> {
  /** Customize node field name */
  fieldNames?: Pick<FieldNames, "children">;
  /** Function called for each node in the tree */
  onEachTraverse?: (node: TreeNode) => void;
}
/**
* It takes a tree, a predicate function, and returns a filtered tree with
* only the nodes that pass the predicate
* @param {TreeNode[] | TreeNode} tree - The tree to filter.
* @param predicate - (node: TreeNode) => boolean
* @param {Options} [options] - {
* @returns A filtered tree
* @linkcode https://github.com/GreatAuk/utopia-utils/blob/main/packages/tree/src/treeFilterNode.ts
*/
declare function treeFilterNode<TreeNode>(tree: TreeNode[] | TreeNode, predicate: (node: TreeNode) => boolean, options?: Options$2<TreeNode>): TreeNode[];
//#endregion
//#region src/treeFindNode.d.ts
interface Options$1<TreeNode> {
  /** Customize node field name */
  fieldNames?: Pick<FieldNames, "children">;
  /** whether to find all nodes, default is find first node */
  isFindAll?: boolean;
  /** Function called for each node in the tree */
  onEachTraverse?: (node: TreeNode) => void;
}
/**
* Returns the first node or all nodes in the tree that matches the predicate (use breadth-first traverse).
* @param {TreeNode[] | TreeNode} tree - TreeNode[] | TreeNode
* @param predicate - (node: TreeNode) => boolean
* @param {Options} [options]
* @returns {TreeNode[]} - a array of TreeNode that matches the predicate
* @linkcode https://github.com/GreatAuk/utopia-utils/blob/main/packages/tree/src/treeFindNode.ts
* @example
* ```
const tree = [
{
name: 'a',
children: [
{ name: 'b' },
],
}
]
const res = treeFindNode(tree, node => node.name === 'b') // res is [{ name: 'b' }]
* ```
*/
declare function treeFindNode<TreeNode>(tree: TreeNode[] | TreeNode, predicate: (node: TreeNode) => boolean, options?: Options$1<TreeNode>): TreeNode[];
//#endregion
//#region src/treeFindPath.d.ts
interface Options {
  /** Customize node field name */
  fieldNames?: Pick<FieldNames, "children">;
}
/**
* It takes a tree and a predicate, and returns the path to the first node that satisfies the predicate
* @param {TreeNode[] | TreeNode} tree - The tree to search.
* @param predicate - (node: TreeNode) => boolean
* @param {Options}
* @returns A path to a node in a tree that matches the predicate.
* @linkcode https://github.com/GreatAuk/utopia-utils/blob/main/packages/tree/src/treeFindPath.ts
* @example
* ```ts
const tree = [
{
name: 'a',
children: [
{ name: 'b' },
],
},
{
name: 'c',
},
]

const path = treeFindPath(tree, node => node.name === 'b')
console.log(path?.map(v => v.name)) // ['a', 'b']
* ```
*/
declare function treeFindPath<TreeNode>(tree: TreeNode[] | TreeNode, predicate: (node: TreeNode) => boolean, options?: Options): TreeNode[] | null;
//#endregion
export { breadthFirstTraverse, buildTreeFromList, deepFirstTraverse, flattenTree, treeFilterNode, treeFindNode, treeFindPath };
//# sourceMappingURL=index.d.mts.map