fast-tree-builder 1.0.0-alpha.0 → 1.0.0-alpha.2

package/README.md

@@ -251,6 +251,7 @@ Parameters
 	- `nodeChildrenKey`: (Optional) The key used to store the children nodes in each node. It can be a `string`, `number`, `symbol`. 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`.
 	- `validRootKeys`: (Optional) An iterable containing key values that can be accepted as root nodes. If provided, any item with a key not present in this iterable will cause an error to be thrown. Defaults to `undefined`.
+  - `validRootParentKeys`: (Optional) Only available when `mode` is set to `parent`. An iterable containing key values that can be accepted the parent field values of root nodes. If provided, any root node with a parent key not present in this iterable will cause an error to be thrown. Defaults to `undefined`.
   - `validateTree`: (Optional) A boolean flag that determines whether to validate the resulting data structure. If the structure is a cyclic graph, an `Error` will be thrown. Requires additional `O(n)` time to compute. Defaults to `false`.
 
 Returns
@@ -263,7 +264,8 @@ An object with the following properties:
 Throws `Error` when:
 
 - A duplicate identifier is recieved,
-- or `validRootKeys` is set and an invalid parent key is recieved,
+- or `validRootKeys` is set and an invalid key is recieved,
+- or `validRootParentKeys` is set and an invalid parent key is recieved,
 - or `validateTree` is set to `true` and a cyclic graph is the result.
 
 ## Comparison with other tree building libraries

package/index.cjs

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 function buildTree(items, options = {}) {
-    const { mode = 'parent', key = 'id', parentKey = 'parent', childrenKey = 'children', nodeDataKey = 'data', nodeParentKey = 'parent', nodeChildrenKey = 'children', mapNodeData, validRootKeys, validateTree = false, } = options;
+    const { mode = 'parent', key = 'id', parentKey = 'parent', childrenKey = 'children', nodeDataKey = 'data', nodeParentKey = 'parent', nodeChildrenKey = 'children', mapNodeData, validRootKeys, validRootParentKeys, validateTree = false, } = options;
     const roots = [];
     const nodes = new Map();
     const danglingNodes = new Map();
@@ -49,11 +49,11 @@ function buildTree(items, options = {}) {
             }
         }
         // Children of dangling nodes will become the root nodes
-        if (validRootKeys) {
-            const validParentKeys = new Set(validRootKeys);
-            for (const [key, node] of danglingNodes.entries()) {
-                if (!validParentKeys.has(key)) {
-                    throw new Error(`Invalid parent key "${key}"`);
+        if (validRootParentKeys) {
+            const validParentKeys = new Set(validRootParentKeys);
+            for (const [parentKey, node] of danglingNodes.entries()) {
+                if (!validParentKeys.has(parentKey)) {
+                    throw new Error(`Invalid parent key "${parentKey}" found for a root node.`);
                 }
                 for (const root of node[nodeChildrenKey]) {
                     // Root nodes does not have a parent, unlink the dangling node
@@ -75,8 +75,21 @@ function buildTree(items, options = {}) {
                 }
             }
         }
+        // TODO: this could be optimized
+        if (validRootKeys) {
+            const rootsSet = new Set(roots);
+            const validKeys = new Set(validRootKeys);
+            for (const [key, node] of nodes) {
+                if (rootsSet.has(node) && !validKeys.has(key)) {
+                    throw new Error(`A root node has an invalid key "${key}"`);
+                }
+            }
+        }
     }
     else {
+        if (validRootParentKeys) {
+            throw new Error(`Option "validRootParentKeys" cannot be used when mode is set to "children".`);
+        }
         const knownNodes = new Set();
         const incompleteNodes = new Set();
         for (const item of items) {
@@ -134,10 +147,10 @@ function buildTree(items, options = {}) {
             throw new Error(`Some nodes miss their referenced children (${incompleteNodes.size}).`);
         }
         if (validRootKeys) {
-            const validParentKeys = new Set(validRootKeys);
+            const validKeys = new Set(validRootKeys);
             for (const [key, node] of danglingNodes.entries()) {
-                if (!validParentKeys.has(key)) {
-                    throw new Error(`Invalid parent key "${key}"`);
+                if (!validKeys.has(key)) {
+                    throw new Error(`A root node has an invalid key "${key}"`);
                 }
                 roots.push(node);
                 nodes.set(key, node);

package/index.d.ts

@@ -28,6 +28,7 @@ declare function buildTree<T extends (D extends false ? object : unknown), K ext
         (item: T): M;
     };
     validRootKeys?: Iterable<unknown>;
+    validRootParentKeys?: Iterable<unknown>;
     validateTree?: boolean;
 }): {
     roots: TreeNode<M extends undefined ? T : M, D, P, C>[];

package/index.js

@@ -1,5 +1,5 @@
 function buildTree(items, options = {}) {
-    const { mode = 'parent', key = 'id', parentKey = 'parent', childrenKey = 'children', nodeDataKey = 'data', nodeParentKey = 'parent', nodeChildrenKey = 'children', mapNodeData, validRootKeys, validateTree = false, } = options;
+    const { mode = 'parent', key = 'id', parentKey = 'parent', childrenKey = 'children', nodeDataKey = 'data', nodeParentKey = 'parent', nodeChildrenKey = 'children', mapNodeData, validRootKeys, validRootParentKeys, validateTree = false, } = options;
     const roots = [];
     const nodes = new Map();
     const danglingNodes = new Map();
@@ -47,11 +47,11 @@ function buildTree(items, options = {}) {
             }
         }
         // Children of dangling nodes will become the root nodes
-        if (validRootKeys) {
-            const validParentKeys = new Set(validRootKeys);
-            for (const [key, node] of danglingNodes.entries()) {
-                if (!validParentKeys.has(key)) {
-                    throw new Error(`Invalid parent key "${key}"`);
+        if (validRootParentKeys) {
+            const validParentKeys = new Set(validRootParentKeys);
+            for (const [parentKey, node] of danglingNodes.entries()) {
+                if (!validParentKeys.has(parentKey)) {
+                    throw new Error(`Invalid parent key "${parentKey}" found for a root node.`);
                 }
                 for (const root of node[nodeChildrenKey]) {
                     // Root nodes does not have a parent, unlink the dangling node
@@ -73,8 +73,21 @@ function buildTree(items, options = {}) {
                 }
             }
         }
+        // TODO: this could be optimized
+        if (validRootKeys) {
+            const rootsSet = new Set(roots);
+            const validKeys = new Set(validRootKeys);
+            for (const [key, node] of nodes) {
+                if (rootsSet.has(node) && !validKeys.has(key)) {
+                    throw new Error(`A root node has an invalid key "${key}"`);
+                }
+            }
+        }
     }
     else {
+        if (validRootParentKeys) {
+            throw new Error(`Option "validRootParentKeys" cannot be used when mode is set to "children".`);
+        }
         const knownNodes = new Set();
         const incompleteNodes = new Set();
         for (const item of items) {
@@ -132,10 +145,10 @@ function buildTree(items, options = {}) {
             throw new Error(`Some nodes miss their referenced children (${incompleteNodes.size}).`);
         }
         if (validRootKeys) {
-            const validParentKeys = new Set(validRootKeys);
+            const validKeys = new Set(validRootKeys);
             for (const [key, node] of danglingNodes.entries()) {
-                if (!validParentKeys.has(key)) {
-                    throw new Error(`Invalid parent key "${key}"`);
+                if (!validKeys.has(key)) {
+                    throw new Error(`A root node has an invalid key "${key}"`);
                 }
                 roots.push(node);
                 nodes.set(key, node);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fast-tree-builder",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.2",
   "description": "Efficiently construct highly customizable bi-directional tree structures from iterable data.",
   "type": "module",
   "module": "./index.js",