simple-tree-utils

Simple Tree Utils

Simple Tree Utils is the library to convert and manipulate with tree-like structures. Library provides converter from an array of objects to trees like structure and vice versa, and also methods to manipulate that tree and/or search in that tree.

It is created because I needed to convert the array of objects into a tree to visualize in Angular tree component. Surely there are plenty of similar libraries, but I think all of them work with their own models/classes, I needed to use my own data without no extra instantiating, or adding extra methods/properties into the working model.

Content

• 🚀 Instalation
• 📚 Documentation
• 💻 Usage
  • 🌐 Usage in browser
• 📖 License

🚀 Instalation

Install library using npm npm install simple-tree-utils --save and import main class into your code base import {TreeUtils} from 'simple-tree-utils'; .

📚 Documentation

For more details and complete documentation check: https://simple-tree-utils.netlify.app/

💻 Usage

First instantiate class with config, or without config.

const treeUtils = new TreeUtils(); // without config, default values are used (id as idProp, parentId as parentIdProp, children as childrenProp)
const treeUtils2 = new TreeUtils({
  idProp: 'id', // the key of a unique identifier for an object (source object)
  parentIdProp: 'parentId', // the key of a unique parent identifier (source object)
  childrenProp: 'children', // the key, where child nodes are stored (destination object tree)
});

After instantiation, you can use tree utils. You can convert the array of the following objects into a tree using list2Tree method as following

const items = [
  {id: 1, parentId: null, name: 'Node 1'},
  {id: 2, parentId: null, name: 'Node 2'},
  {id: 3, parentId: 1, name: 'Node 3'},
  {id: 4, parentId: 1, name: 'Node 4'},
  {id: 5, parentId: 2, name: 'Node 5'},
  {id: 6, parentId: 3, name: 'Node 6'},
];
const output = treeUtils.list2Tree(items);

then the output of lift2Tree will be

const tree = [
  {
    id: 1, parentId: null, name: 'Node 1', children: [
      {
        id: 3, parentId: 1, name: 'Node 3', children: [
          {id: 6, parentId: 3, name: 'Node 6', children: []},
        ]
      },
      {id: 4, parentId: 1, name: 'Node 4', children: []},
    ]
  },
  {
    id: 2, parentId: null, name: 'Node 2', children: [
      {id: 5, parentId: 2, name: 'Node 5', children: []},
    ]
  },
];

When you got a structure like the above, you can use all the methods stated here: https://simple-tree-utils.netlify.app/classes/treeutils

For example, we can find node by giving callback

const node = treeUtils.find(tree, item => item.id === 2);

If you need a list again, you can convert the tree back to a list using treeUtils.tree2List method

treeUtils.tree2List(tree);

🌐 Usage in browser

You can also use this library in the browser without compiling using jsDelivr. Import script into HTML file, and you can access classes through the global treeUtils object.

<script src="https://cdn.jsdelivr.net/npm/simple-tree-utils@1/dist/browser-bundle.min.js"></script>
<script>
    const utils = new treeUtils.TreeUtils();
    const tree = utils.list2Tree(items);
</script>

📖 License

MIT

Changelog

2.0.0

3 January 2025

• feat(method): getPathNodes presented #15
• feat(methods): getDistance presented #8
• feat(methods): getNodesAtLevel, getWidth, getHeight, getTreeDegree methods presented #5 #6 #10 #14
• feat(methods): getSize, getBreath, getDepth, getLevel, getDegree methods presented #13 #12 #9 #7 #4
• feat(methods): getLeafs method presented #13
• build(node): update node to v22, typescript to v5 and all possible dependencies ce4acc0
• refactor(api): refactor publis api to be more JSish way 798e264
• feat(api): rename public API methods 3e7bbc8
• docs(comments): add missing documentation comments 3744f64
• feat(methods): getNeighbours and getSiblings methods presented 0ae9eed
• refactor(naming): refactor naming of main file with all logic d1f7e75
• docs(readme): fix readme method usage instruction 07aa1cf
• docs(readme): unify badges 20c2f4d