treechop

This library provides a set of utility functions for manipulating tree-structured data in JavaScript/TypeScript. Below are the available methods, their signatures, and usage examples.

Options and Meta Information: Most methods accept an options parameter to customize keys (e.g., childrenKey, idKey, parentKey) and traversal strategy (pre, post, breadth). The callback meta argument provides information like depth, index, and parents.

treeCount

Description: Counts the number of nodes in a tree that match a given predicate.

Signature:

treeCount<T extends TreeNode>(
  tree: T[],
  predicate?: (node: T, meta: CallbackMeta) => boolean,
  options?: TreeOptions
): number

Example:

const count = treeCount(tree, node => node.id % 2 === 0)

treeDelete

Description: Deletes nodes from a tree that match a given predicate, returning a new tree.

Signature:

treeDelete<T extends TreeNode>(
  tree: T[],
  predicate: (node: T, meta: CallbackMeta) => boolean,
  options?: TreeOptions
): T[]

Example:

const newTree = treeDelete(tree, node => node.id === 4)

treeFlatFilter & treeFilter

Description:

• treeFlatFilter: Returns a flat array of nodes matching the predicate.
• treeFilter: Returns a tree structure containing only nodes matching the predicate.

Signature:

treeFlatFilter<T extends TreeNode>(
  tree: T[],
  predicate: (node: T, meta: CallbackMeta) => boolean,
  options?: TraversalOptions
): T[]

treeFilter<T extends TreeNode>(
  tree: T[],
  predicate: (node: T, meta: CallbackMeta) => boolean,
  options?: TreeOptions
): T[]

Example:

const flat = treeFlatFilter(tree, node => node.value % 2 === 0)
const filteredTree = treeFilter(tree, node => node.value >= 2)

treeFind

Description: Finds the first node in the tree that matches the predicate.

Signature:

treeFind<T extends TreeNode>(
  tree: T[],
  predicate: (node: T, meta: CallbackMeta) => boolean,
  options?: TraversalOptions
): T | undefined

Example:

const found = treeFind(tree, node => node.id === 4)

treeForeach

Description: Traverses every node in the tree and applies a callback.

Signature:

treeForeach<T extends TreeNode>(
  tree: T[],
  callback: (node: T, meta: CallbackMeta) => void,
  options?: TraversalOptions
): void

Example:

treeForeach(tree, node => console.log(node.id))

treeFromArray

Description: Converts a flat array of nodes (with parent references) into a tree structure.

Signature:

treeFromArray<T extends TreeNode>(
  nodes: T[],
  options?: FromArrayOptions<T>
): T[]

Example:

const tree = treeFromArray([
  { id: '1', name: 'Node 1' },
  { id: '1-1', name: 'Node 1-1', pid: '1' }
])

treeFlatMap & treeMap

Description:

• treeFlatMap: Maps each node to a value and returns a flat array.
• treeMap: Maps each node to a new node, preserving the tree structure.

Signature:

treeFlatMap<T extends TreeNode, R>(
  tree: T[],
  callback: (node: T, meta: CallbackMeta) => R,
  options?: TraversalOptions
): R[]

treeMap<T extends TreeNode, R extends TreeNode>(
  tree: T[],
  callback: (node: T, meta: CallbackMeta) => R,
  options?: TreeOptions
): R[]

Example:

const names = treeFlatMap(tree, node => node.name)
const upperTree = treeMap(tree, node => ({ ...node, name: node.name.toUpperCase() }))

treeSearch

Description: Returns a tree containing only the branches where at least one node matches the predicate.

Signature:

treeSearch<T extends TreeNode>(
  tree: T[],
  predicate: (node: T, meta: CallbackMeta) => boolean,
  options?: TreeOptions
): T[]

Example:

const result = treeSearch(tree, node => node.value === 2)

treeSome

Description: Returns true if at least one node in the tree matches the predicate.

Signature:

treeSome<T extends TreeNode>(
  tree: T[],
  predicate: (node: T, meta: CallbackMeta) => boolean,
  options?: TreeOptions
): boolean

Example:

const hasEven = treeSome(tree, node => node.id % 2 === 0)

treeSort

Description: Sorts the tree nodes at each level by a specified key.

Signature:

treeSort<T extends TreeNode>(
  tree: T[],
  options: { sortKey: string, order?: 'asc' | 'desc' }
): T[]

Example:

const sorted = treeSort(tree, { sortKey: 'value', order: 'asc' })

treeToArray

Description: Converts a tree structure into a flat array, adding parent references.

Signature:

treeToArray<T extends TreeNode>(
  tree: T[],
  options?: ToArrayOptions<T>
): T[]

Example:

const arr = treeToArray(tree)

Coverage

License

MIT License © jinghaihan