fast-tree-builder 0.0.1

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright 2023 László BULIK
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the “Software”),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# fast-tree-builder
+
+[![Build Status](https://github.com/lionel87/fast-tree-builder/actions/workflows/coveralls.yaml/badge.svg)](https://github.com/lionel87/fast-tree-builder/actions/workflows/coveralls.yaml)
+[![Coverage Status](https://coveralls.io/repos/github/lionel87/fast-tree-builder/badge.svg?branch=master)](https://coveralls.io/github/lionel87/fast-tree-builder?branch=master)
+![npms.io (quality)](https://img.shields.io/npms-io/quality-score/fast-tree-builder?label=quality)
+![Maintenance](https://img.shields.io/maintenance/yes/2023)
+
+`fast-tree-builder` is an npm package that allows you to efficiently build trees from iterable data structures. With its optimized algorithm, strong TypeScript typings, and customizable node structure, it provides a reliable solution for organizing and manipulating hierarchical data.
+
+
+## Features
+
+Efficient Tree Building: The package utilizes an optimized algorithm to construct trees efficiently, ensuring quick performance even with large datasets.
+
+- **Bi-Directional Tree Traversal**: Traverse the built tree in both directions, enabling easy navigation between parent and child nodes.
+
+- **Strong TypeScript Typings**: Enjoy the benefits of type safety with comprehensive TypeScript typings. The package provides detailed type definitions to enhance your development experience.
+
+- **Fully Customizable Node Structure**: Tailor the structure of the nodes in the built tree to meet your specific requirements. You have the freedom to define data, parent, and children key names according to your application's needs. To avoid circular references parent links can be turned off which helps generating JSON data.
+
+- **Works on Any Iterable Data Structure**: Whether you have an array, set, or any other iterable data structure, `fast-tree-builder` can process it seamlessly, making it compatible with a wide range of use cases.
+
+- **No Sorting Required**: The package does not require your input data to be sorted, saving you preprocessing time and effort.
+
+- **Flexible Key and Parent Key Types**: You can use any JavaScript type as keys. Items are matched by comparing `key === parentKey`.
+
+- **Map of Nodes**: Retrieve a `Map` object containing the nodes of the built tree, enabling easy entry and access on any point of the tree.
+
+- **Support for Multiple Root Nodes**: The package supports building trees with multiple root nodes.
+
+- **Support for Parent Key Validation**: Enables you to validate parent keys while building the tree. When a node missing its parent, an error will be thrown.
+
+
+## Installation
+
+To install `fast-tree-builder`, use npm:
+
+```sh
+npm install fast-tree-builder
+```
+
+or
+
+```sh
+yarn add fast-tree-builder
+```
+
+
+## Usage
+
+Here are some examples showcasing the usage of `fast-tree-builder` and their expected outputs:
+
+### Example 1: Basic Tree Building
+
+```typescript
+import buildTree from 'fast-tree-builder';
+
+const items = [
+  { id: 1, parent: null, name: 'Root 1' },
+  { id: 2, parent: null, name: 'Root 2' },
+  { id: 3, parent: 1, name: 'Child 1.1' },
+  { id: 4, parent: 1, name: 'Child 1.2' },
+  { id: 5, parent: 2, name: 'Child 2.1' },
+];
+
+const { roots, nodes } = buildTree(items, {
+  key: 'id',
+  parentKey: 'parent',
+  nodeDataKey: 'data',
+  nodeParentKey: 'parent',
+  nodeChildrenKey: 'children',
+});
+
+console.log(roots[0].data.name);
+// Expected output: Root 1
+
+console.log(roots[0].children[1].data.name);
+// Expected output: Child 1.2
+
+console.log(roots[0].children[1].parent.data.name);
+// Expected output: Root 1
+
+console.log(roots);
+// Expected output: [
+//   { data: { id: 1, parent: null, name: 'Root 1' }, children: [
+//     { data: { id: 3, parent: 1, name: 'Child 1.1' }, parent: { ... } },
+//     { data: { id: 4, parent: 1, name: 'Child 1.2' }, parent: { ... } }
+//   ] },
+//   { data: { id: 2, parent: null, name: 'Root 2' }, children: [
+//     { data: { id: 5, parent: 2, name: 'Child 2.1' }, parent: { ... } }
+//   ] }
+// ]
+
+console.log(nodes);
+// Expected output: Map {
+//   1 => { data: { id: 1, parent: null, name: 'Root 1' }, children: [
+//     { data: { id: 3, parent: 1, name: 'Child 1.1' }, parent: { ... } },
+//     { data: { id: 4, parent: 1, name: 'Child 1.2' }, parent: { ... } }
+//   ] },
+//   2 => { data: { id: 2, parent: null, name: 'Root 2' }, children: [
+//     { data: { id: 5, parent: 2, name: 'Child 2.1' }, parent: { ... } }
+//   ] },
+//   3 => { data: { id: 3, parent: 1, name: 'Child 1.1' }, parent: { ... } },
+//   4 => { data: { id: 4, parent: 1, name: 'Child 1.2' }, parent: { ... } },
+//   5 => { data: { id: 5, parent: 2, name: 'Child 2.1' }, parent: { ... } }
+// }
+```
+
+
+### Example 2: Customized Node Structure
+
+```typescript
+import buildTree from 'fast-tree-builder';
+
+const items = [
+  { key: { n: 1 }, parentKey: null, name: 'Root 1' },
+  { key: { n: 2 }, parentKey: null, name: 'Root 2' },
+  { key: { n: 3 }, parentKey: { n: 1 }, name: 'Child 1.1' },
+  { key: { n: 4 }, parentKey: { n: 1 }, name: 'Child 1.2' },
+  { key: { n: 5 }, parentKey: { n: 2 }, name: 'Child 2.1' },
+];
+
+const { roots, nodes } = buildTree(items, {
+  key(item) { return item.key?.n; },
+  parentKey(item) { return item.parentKey?.n; },
+  nodeDataKey: false, // don't store data separately on the node
+  nodeParentKey: 'up',
+  nodeChildrenKey: 'down',
+  mapNodeData(item) { return { title: item.name }; },
+});
+
+console.log(roots[0].title);
+// Expected output: Root 1
+
+console.log(roots[0].down[1].title);
+// Expected output: Child 1.2
+
+console.log(roots[0].down[1].up.title);
+// Expected output: Root 1
+
+console.log(roots);
+// Expected output: [
+//   { title: 'Root 1', down: [
+//     { title: 'Child 1.1', up: { ... } },
+//     { title: 'Child 1.2', up: { ... } }
+//   ] },
+//   { title: 'Root 2', down: [
+//     { title: 'Child 2.1', up: { ... } }
+//   ] }
+// ]
+
+console.log(nodes);
+// Expected output: Map {
+//   1 => { title: 'Root 1', down: [
+//     { title: 'Child 1.1', up: { ... } },
+//     { title: 'Child 1.2', up: { ... } }
+//   ] },
+//   2 => { title: 'Root 2', down: [
+//     { title: 'Child 2.1', up: { ... } }
+//   ] },
+//   3 => { title: 'Child 1.1', up: { ... } },
+//   4 => { title: 'Child 1.2', up: { ... } },
+//   5 => { title: 'Child 2.1', up: { ... } }
+// }
+```
+
+
+## Documentation
+
+### `buildTree(items: Iterable<T>, options: BuildTreeOptions): TreeResult<T>`
+
+Builds a tree from the given iterable `items` using the specified `options`.
+
+Parameters
+
+- `items`: An iterable data structure containing the items to build the tree from.
+- `options`: An object specifying the build options. It has the following properties:
+	- `key`: (Optional) The key used to identify items. It can be a string, number, symbol, or a function that extracts the key from an item. Defaults to `'id'`.
+	- `parentKey`: (Optional) The key used to identify the parent of each item. It can be a string, number, symbol, or a function that extracts the parent key from an item. Defaults to `'parent'`.
+	- `nodeDataKey`: (Optional) The key used to store the item's data in each node. It can be a string, number, symbol, or false if the data should be merged directly into the node. Defaults to `'data'`.
+	- `nodeParentKey`: (Optional) The key used to store the parent node in each node. It can be a string, number, symbol, or false if the parent node should not be included. Defaults to `'parent'`.
+	- `nodeChildrenKey`: (Optional) The key used to store the children nodes in each node. It can be a string, number, symbol, or false if the children nodes should not be included. Defaults to `'children'`.
+	- `mapNodeData`: (Optional) A function that maps an item to its corresponding node data. It allows transforming the item before assigning it to the node. Defaults to `undefined`.
+	- `validateParentKeys`: (Optional) An iterable containing keys that should be validated as existing parent keys. If provided, any item with a parent key not present in this iterable will cause an error to be thrown. Defaults to `undefined`.
+
+Returns
+
+An object with the following properties:
+
+- `roots`: An array of the root nodes of the built tree.
+- `nodes`: A `Map` object containing all nodes of the built tree, with keys corresponding to their identifiers.
+
+
+## Contributions
+
+Contributions to `fast-tree-builder` are welcome! If you have any bug reports, feature requests, or improvements, please open an issue on the [GitHub repository](https://github.com/lionel87/fast-tree-builder).
+
+## License
+
+`fast-tree-builder` is licensed under the [MIT License](https://github.com/lionel87/fast-tree-builder/blob/main/LICENSE).

package/cjs/index.d.ts

@@ -0,0 +1,36 @@
+type TreeNode<T, D extends string | number | symbol | false, P extends string | number | symbol | false, C extends string | number | symbol> = (D extends false ? (P extends false ? T & {
+    [k in C]?: TreeNode<T, D, P, C>[];
+} : T & {
+    [k in Exclude<P, false>]?: TreeNode<T, D, P, C>;
+} & {
+    [k in C]?: TreeNode<T, D, P, C>[];
+}) : (P extends false ? {
+    [k in Exclude<D, false>]: T;
+} & {
+    [k in C]?: TreeNode<T, D, P, C>[];
+} : {
+    [k in Exclude<D, false>]: T;
+} & {
+    [k in Exclude<P, false>]?: TreeNode<T, D, P, C>;
+} & {
+    [k in C]?: TreeNode<T, D, P, C>[];
+}));
+declare function buildTree<T extends (D extends false ? object : unknown), M extends (D extends false ? object : unknown) = T, K extends unknown = unknown, D extends string | number | symbol | false = 'data', P extends string | number | symbol | false = 'parent', C extends string | number | symbol = 'children'>(items: Iterable<T>, options: {
+    key?: string | number | symbol | {
+        (item: T): K;
+    };
+    parentKey?: string | number | symbol | {
+        (item: T): K;
+    };
+    nodeDataKey?: D;
+    nodeParentKey?: P;
+    nodeChildrenKey?: C;
+    mapNodeData?: {
+        (item: T): M;
+    };
+    validateParentKeys?: Iterable<unknown>;
+}): {
+    roots: TreeNode<M extends undefined ? T : M, D, P, C>[];
+    nodes: Map<K, TreeNode<M extends undefined ? T : M, D, P, C>>;
+};
+export default buildTree;

package/cjs/index.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+function buildTree(items, options) {
+    var _a;
+    const { key = 'id', parentKey = 'parent', nodeDataKey = 'data', nodeParentKey = 'parent', nodeChildrenKey = 'children', mapNodeData, validateParentKeys, } = options;
+    const nodes = new Map();
+    const danglingNodes = new Map();
+    for (const item of items) {
+        // @ts-ignore
+        const keyOfNode = typeof key === 'function' ? key(item) : item[key];
+        if (nodes.has(keyOfNode)) {
+            throw new Error(`Duplicate identifier detected for "${keyOfNode}"`);
+        }
+        // Current node can be new or already created by a child item as its parent
+        let node = danglingNodes.get(keyOfNode);
+        if (node) {
+            danglingNodes.delete(keyOfNode);
+        }
+        else {
+            node = {};
+        }
+        nodes.set(keyOfNode, node);
+        // Set the data of the node
+        const nodeData = typeof mapNodeData === 'function' ? mapNodeData(item) : item;
+        if (nodeDataKey !== false) {
+            node[nodeDataKey] = nodeData;
+        }
+        else {
+            Object.assign(node, nodeData);
+        }
+        // Link this node to its parent
+        // @ts-ignore
+        const keyOfParentNode = typeof parentKey === 'function' ? parentKey(item) : item[parentKey];
+        let parent = (_a = nodes.get(keyOfParentNode)) !== null && _a !== void 0 ? _a : danglingNodes.get(keyOfParentNode);
+        if (!parent) {
+            // No parent node exists yet, create as dangling node
+            parent = {};
+            // Track as dangling node, we dont know yet if it really exists
+            danglingNodes.set(keyOfParentNode, parent);
+        }
+        // When no children added yet
+        if (!parent[nodeChildrenKey]) {
+            parent[nodeChildrenKey] = [];
+        }
+        // Add as child
+        parent[nodeChildrenKey].push(node);
+        // Set the parent on this node
+        if (nodeParentKey !== false) {
+            node[nodeParentKey] = parent;
+        }
+    }
+    if (danglingNodes.size === 0) {
+        throw new Error(`Could not find root nodes, circular references found.`);
+    }
+    // Children of dangling nodes will become the root nodes
+    const roots = [];
+    if (validateParentKeys) {
+        const validParentKeys = new Set(validateParentKeys);
+        for (const [key, node] of danglingNodes.entries()) {
+            if (!validParentKeys.has(key)) {
+                throw new Error(`Invalid parent key "${key}" from items "${node[nodeChildrenKey].join('", "')}".`);
+            }
+            for (const root of node[nodeChildrenKey]) {
+                // Root nodes does not have a parent, unlink the dangling node
+                if (nodeParentKey !== false) {
+                    delete root[nodeParentKey];
+                }
+                roots.push(root);
+            }
+        }
+    }
+    else {
+        for (const node of danglingNodes.values()) {
+            for (const root of node[nodeChildrenKey]) {
+                // Root nodes does not have a parent, unlink the dangling node
+                if (nodeParentKey !== false) {
+                    delete root[nodeParentKey];
+                }
+                roots.push(root);
+            }
+        }
+    }
+    return { roots, nodes };
+}
+exports.default = buildTree;

package/cjs/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/esm/index.d.ts

@@ -0,0 +1,36 @@
+type TreeNode<T, D extends string | number | symbol | false, P extends string | number | symbol | false, C extends string | number | symbol> = (D extends false ? (P extends false ? T & {
+    [k in C]?: TreeNode<T, D, P, C>[];
+} : T & {
+    [k in Exclude<P, false>]?: TreeNode<T, D, P, C>;
+} & {
+    [k in C]?: TreeNode<T, D, P, C>[];
+}) : (P extends false ? {
+    [k in Exclude<D, false>]: T;
+} & {
+    [k in C]?: TreeNode<T, D, P, C>[];
+} : {
+    [k in Exclude<D, false>]: T;
+} & {
+    [k in Exclude<P, false>]?: TreeNode<T, D, P, C>;
+} & {
+    [k in C]?: TreeNode<T, D, P, C>[];
+}));
+declare function buildTree<T extends (D extends false ? object : unknown), M extends (D extends false ? object : unknown) = T, K extends unknown = unknown, D extends string | number | symbol | false = 'data', P extends string | number | symbol | false = 'parent', C extends string | number | symbol = 'children'>(items: Iterable<T>, options: {
+    key?: string | number | symbol | {
+        (item: T): K;
+    };
+    parentKey?: string | number | symbol | {
+        (item: T): K;
+    };
+    nodeDataKey?: D;
+    nodeParentKey?: P;
+    nodeChildrenKey?: C;
+    mapNodeData?: {
+        (item: T): M;
+    };
+    validateParentKeys?: Iterable<unknown>;
+}): {
+    roots: TreeNode<M extends undefined ? T : M, D, P, C>[];
+    nodes: Map<K, TreeNode<M extends undefined ? T : M, D, P, C>>;
+};
+export default buildTree;

package/esm/index.js

@@ -0,0 +1,83 @@
+function buildTree(items, options) {
+    var _a;
+    const { key = 'id', parentKey = 'parent', nodeDataKey = 'data', nodeParentKey = 'parent', nodeChildrenKey = 'children', mapNodeData, validateParentKeys, } = options;
+    const nodes = new Map();
+    const danglingNodes = new Map();
+    for (const item of items) {
+        // @ts-ignore
+        const keyOfNode = typeof key === 'function' ? key(item) : item[key];
+        if (nodes.has(keyOfNode)) {
+            throw new Error(`Duplicate identifier detected for "${keyOfNode}"`);
+        }
+        // Current node can be new or already created by a child item as its parent
+        let node = danglingNodes.get(keyOfNode);
+        if (node) {
+            danglingNodes.delete(keyOfNode);
+        }
+        else {
+            node = {};
+        }
+        nodes.set(keyOfNode, node);
+        // Set the data of the node
+        const nodeData = typeof mapNodeData === 'function' ? mapNodeData(item) : item;
+        if (nodeDataKey !== false) {
+            node[nodeDataKey] = nodeData;
+        }
+        else {
+            Object.assign(node, nodeData);
+        }
+        // Link this node to its parent
+        // @ts-ignore
+        const keyOfParentNode = typeof parentKey === 'function' ? parentKey(item) : item[parentKey];
+        let parent = (_a = nodes.get(keyOfParentNode)) !== null && _a !== void 0 ? _a : danglingNodes.get(keyOfParentNode);
+        if (!parent) {
+            // No parent node exists yet, create as dangling node
+            parent = {};
+            // Track as dangling node, we dont know yet if it really exists
+            danglingNodes.set(keyOfParentNode, parent);
+        }
+        // When no children added yet
+        if (!parent[nodeChildrenKey]) {
+            parent[nodeChildrenKey] = [];
+        }
+        // Add as child
+        parent[nodeChildrenKey].push(node);
+        // Set the parent on this node
+        if (nodeParentKey !== false) {
+            node[nodeParentKey] = parent;
+        }
+    }
+    if (danglingNodes.size === 0) {
+        throw new Error(`Could not find root nodes, circular references found.`);
+    }
+    // Children of dangling nodes will become the root nodes
+    const roots = [];
+    if (validateParentKeys) {
+        const validParentKeys = new Set(validateParentKeys);
+        for (const [key, node] of danglingNodes.entries()) {
+            if (!validParentKeys.has(key)) {
+                throw new Error(`Invalid parent key "${key}" from items "${node[nodeChildrenKey].join('", "')}".`);
+            }
+            for (const root of node[nodeChildrenKey]) {
+                // Root nodes does not have a parent, unlink the dangling node
+                if (nodeParentKey !== false) {
+                    delete root[nodeParentKey];
+                }
+                roots.push(root);
+            }
+        }
+    }
+    else {
+        for (const node of danglingNodes.values()) {
+            for (const root of node[nodeChildrenKey]) {
+                // Root nodes does not have a parent, unlink the dangling node
+                if (nodeParentKey !== false) {
+                    delete root[nodeParentKey];
+                }
+                roots.push(root);
+            }
+        }
+    }
+    return { roots, nodes };
+}
+export default buildTree;

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "fast-tree-builder",
+  "version": "0.0.1",
+  "description": "Efficiently construct highly customizable bi-directional tree structures from iterable data.",
+  "type": "module",
+  "main": "cjs/index.js",
+  "module": "esm/index.js",
+  "types": "esm/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./cjs/index.js",
+      "default": "./esm/index.js"
+    }
+  },
+  "scripts": {
+    "prepack": "npm run build",
+    "clean": "rimraf esm cjs",
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc",
+    "watch:esm": "tsc --watch",
+    "build:cjs": "tsc --outDir cjs --module commonjs && echo { \"type\": \"commonjs\" }>cjs/package.json",
+    "watch:cjs": "npm run build:cjs && tsc --outDir cjs --module commonjs --watch",
+    "test": "node test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lionel87/fast-tree-builder.git"
+  },
+  "keywords": [
+    "tree builder",
+    "tree structure",
+    "iterable data",
+    "typescript",
+    "type safe",
+    "bi-directional traversal",
+    "list to tree",
+    "array to tree",
+    "unflatten tree",
+    "algorithm",
+    "navigation",
+    "breadcrumbs",
+    "descendants",
+    "ancestors",
+    "tree",
+    "builder",
+    "children",
+    "child",
+    "nested",
+    "list",
+    "validation"
+  ],
+  "author": "László BULIK",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/lionel87/fast-tree-builder/issues"
+  },
+  "homepage": "https://github.com/lionel87/fast-tree-builder#readme",
+  "devDependencies": {
+    "rimraf": "^5.0.1",
+    "typescript": "^5.1.3"
+  }
+}