fast-tree-builder 1.0.2 → 2.0.0-alpha.0

package/README.md

@@ -6,7 +6,8 @@
 [![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)
 ![Maintenance](https://img.shields.io/maintenance/yes/2025)
 
-`fast-tree-builder` is an npm package that allows you to build trees quickly from iterable data structures. With its optimized algorithm, strong TypeScript typings, and customizable node structure it provides a convenient solution for working with hierarchical data.
+`fast-tree-builder` is a high-performance TypeScript-first utility for constructing trees from iterable collections. It supports flexible input formats and fully customizable output node structures, enabling safe and idiomatic manipulation of hierarchical data.
+
 
 ## Prerequisites
 
@@ -14,44 +15,81 @@
 - each item is identifiable by a unique id,
 - the items are connected via a *parent id* OR *children ids*.
 
+
 ## Features
 
-- **Efficient Tree Building**: Using an optimized algorithm to construct trees in `O(n)` time.
+- **Fully Typed and Customizable** – TypeScript support with correct types for the built tree.
+- **Supports Both `parentId` and `childIds` Models** – Choose your relation style via options.
+- **Iterable Input Support** – Works on arrays, sets, or any iterable.
+- **Flexible Key Types** – Anything can be an identifier. Relations checked with (`childKey === parentKey`) comparison.
+- **Fully Customizable Node Structure**: Design the node structure as you like.
+- **O(n) Tree Construction** – Efficient building from unordered data, no sorting needed.
+- **Bi-Directional Tree Links** – Nodes can store both `children` and `parent` references.
+- **Multi-Root Support** – Handles disjoint trees naturally if no virtual root is present.
+- **Map of Nodes** – Returned `Map` allows constant-time access to any node.
+- **Tree Validation** – Detects cycles or nodes reachable through multiple paths.
+- **Reference Validation** – Optionally enforce that all parent/child links are valid.
 
-- **Bi-Directional Tree Traversal**: Pointers for parent and children both created for the nodes.
 
-- **Robust TypeScript Type Definitions**: Type safety through extensive TypeScript type definitions which helps code reliability and developer workflow.
+## Installation
 
-- **Fully Customizable Node Structure**: The structure of the nodes in the built tree is customizable 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.
+```sh
+npm install fast-tree-builder
+```
 
-- **Works on Iterables**: Designed to handle arrays, sets, and other iterable data structures out of the box ensuring broad applicability.
+or
 
-- **No Sorting Required**: The algorithm does not require your input data to be sorted (eg. parent must come before children), saving you preprocessing time and effort.
+```sh
+yarn add fast-tree-builder
+```
 
-- **Flexible Key Types**: You can use any JavaScript value for identifying items. Relations checked with strict (`childKey === parentKey`) comparison.
 
-- **Multiple Root Nodes**: Can construct multiple distinct trees. Handy when the intent is to handle the set as one tree, but a 'virtual' root item is not present among the items to couple them together. The 'roots' becomes your virtual root in this case.
+## Documentation
 
-- **Map of Nodes**: Beside the root nodes you can retrieve a `Map` object containing the nodes of the built tree, enabling easy entry on any point of the tree.
+### `buildTree(items: Iterable<T>, options: Options): TreeResult`
 
-- **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.
+Builds a tree structure from an iterable list of items.
 
-- **Support for Tree Validation**: Ensures the recieved data structure is an acyclic graph.
+#### Parameters
 
-## Installation
+* `items`: Any iterable of input items.
+* `options`: Configuration object:
 
-To install `fast-tree-builder`, use npm:
+##### Required
 
-```sh
-npm install fast-tree-builder
-```
+- `id`: A key or function used to extract the unique identifier from each item.
 
-or
+##### One of:
 
-```sh
-yarn add fast-tree-builder
+- `parentId`: A key or function returning the parent ID of the item.
+- `childIds`: A key or function returning an iterable of child IDs for the item.
+
+##### Optional
+
+- `nodeValueMapper`: Function to map an item to a custom value stored in the node. Optional.
+- `nodeValueKey`: Key where the item's data is stored in the output node. Set to `false` to inline the item directly into the node. Default: `'value'`.
+- `nodeParentKey`: Key where the node's parent reference is stored. Set to `false` to omit parent links. Default: `'parent'`.
+- `nodeChildrenKey`: Key where the node's children are stored. Default: `'children'`.
+- `withDepth`: When `true`, adds a `depth` property to each node indicating its depth in the tree. Also implies `validateTree`. Default: `false`.
+- `validateReferences`: When `true`, verifies all `parentId` or `childIds` resolve to real items. Errors are thrown on invalid references. Default: `false`.
+- `validateTree`: When `true`, verifies that the final structure is a valid tree (no cycles or multi-path references). Errors are thrown if the check fails. Default: `false`.
+
+#### Returns
+
+```ts
+{
+  roots: TreeNode[],                // top-level nodes
+  nodes: Map<id, TreeNode>          // all nodes by id
+}
 ```
 
+#### Throws
+
+- Missing required `id`, `parentId`/`childIds`, or `options` parameter
+- Duplicate item identifiers
+- Invalid reference (if `validateReferences` is enabled)
+- Cycle or structural error (if `validateTree` or `withDepth` is enabled)
+
 
 ## Usage
 
@@ -74,46 +112,46 @@ const items = [
 
 const { roots, nodes } = buildTree(items, {
   // the input items:
-  key: 'id',
-  parentKey: 'parent',
+  id: 'id',
+  parentId: 'parent',
   // the built node:
-  nodeDataKey: 'data',
+  nodeValueKey: 'value',
   nodeParentKey: 'parent',
   nodeChildrenKey: 'children',
 });
 
-console.log(roots[0].data.name);
+console.log(roots[0].value.name);
 // Expected output: Root 1
 
-console.log(roots[0].children[1].data.name);
+console.log(roots[0].children[1].value.name);
 // Expected output: Child 1.2
 
-console.log(roots[0].children[1].parent.data.name);
+console.log(roots[0].children[1].parent.value.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: { ... } }
+//   { value: { id: 1, parent: null, name: 'Root 1' }, children: [
+//     { value: { id: 3, parent: 1, name: 'Child 1.1' }, parent: { ... } },
+//     { value: { 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: { ... } }
+//   { value: { id: 2, parent: null, name: 'Root 2' }, children: [
+//     { value: { 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: { ... } }
+//   1 => { value: { id: 1, parent: null, name: 'Root 1' }, children: [
+//     { value: { id: 3, parent: 1, name: 'Child 1.1' }, parent: { ... } },
+//     { value: { 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: { ... } }
+//   2 => { value: { id: 2, parent: null, name: 'Root 2' }, children: [
+//     { value: { 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: { ... } }
+//   3 => { value: { id: 3, parent: 1, name: 'Child 1.1' }, parent: { ... } },
+//   4 => { value: { id: 4, parent: 1, name: 'Child 1.2' }, parent: { ... } },
+//   5 => { value: { id: 5, parent: 2, name: 'Child 2.1' }, parent: { ... } }
 // }
 ```
 
@@ -132,7 +170,8 @@ const items = [
 ];
 
 const { roots, nodes } = buildTree(items, {
-  mode: 'children'
+  id: 'id',
+  childIds: 'children',
 });
 ```
 
@@ -152,12 +191,12 @@ const items = [
 ];
 
 const { roots, nodes } = buildTree(items, {
-  key(item) { return item.key?.n; },
-  parentKey(item) { return item.parentKey?.n; },
-  nodeDataKey: false, // merge item data into node
+  id: item => item.key?.n,
+  parentId: item => item.parentKey?.n,
+  nodeValueMapper: item => ({ title: item.name }),
+  nodeValueKey: false, // merge item data into node
   nodeParentKey: 'up',
   nodeChildrenKey: 'down',
-  mapNodeData(item) { return { title: item.name }; },
 });
 
 console.log(roots[0].title);
@@ -210,10 +249,10 @@ const items = [
 ];
 
 const { roots, nodes } = buildTree(items, {
-  key(item) { return item.substring(2, 4); },
-  parentKey(item) { return item.substring(0, 2); },
-  mapNodeData(item) { return { name: item.substring(4) }; },
-  nodeDataKey: false, // merge item data into node
+  id: item => item.substring(2, 4),
+  parentKey: item => item.substring(0, 2),
+  nodeValueMapper: item => ({ name: item.substring(4) }),
+  nodeValueKey: false, // merge item data into node
 });
 
 console.log(roots[0].name);
@@ -234,40 +273,6 @@ console.log(roots);
 // ]
 ```
 
-## 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 of the tree.
-- `options`: An object specifying the build options. It has the following properties:
-  - `mode`: (Optional) Defines the item connection method. `children` means items defines their children in an array, child nodes connects to these; `parent` means items defines their parent, parent nodes connects to these. Defaults to `parent`.
-  - `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`. 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
-
-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.
-
-Throws `Error` when:
-
-- A duplicate identifier 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.
 
 ## FAQ
 
@@ -291,7 +296,7 @@ for (const item of items) {
     node = {};
     nodes.set(item.id, node);
   }
-  node.data = item; // Or Object.assign(node, item);
+  node.value = item; // Or Object.assign(node, item);
   if (item.parentId) {
     let parent = nodes.get(item.parentId);
     if (!parent) {

package/index.cjs

@@ -1,188 +1,195 @@
 "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, validRootParentKeys, validateTree = false, } = options;
-    const roots = [];
-    const nodes = new Map();
-    const danglingNodes = new Map();
-    if (mode === 'parent') {
-        for (const item of items) {
-            const keyOfNode = typeof key === 'function' ? key(item) : item[key];
-            const keyOfParentNode = typeof parentKey === 'function' ? parentKey(item) : item[parentKey];
-            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
-            let parentNode = nodes.get(keyOfParentNode) ?? danglingNodes.get(keyOfParentNode);
-            if (!parentNode) {
-                // No parent node exists yet, create as dangling node
-                parentNode = {};
-                // Track as dangling node, we dont know yet if it really exists
-                danglingNodes.set(keyOfParentNode, parentNode);
-            }
-            // When no children added yet
-            if (!parentNode[nodeChildrenKey]) {
-                parentNode[nodeChildrenKey] = [];
-            }
-            // Add as child
-            parentNode[nodeChildrenKey].push(node);
-            // Set the parent on this node
-            if (nodeParentKey !== false) {
-                node[nodeParentKey] = parentNode;
-            }
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var index_exports = {};
+__export(index_exports, {
+  default: () => buildTree
+});
+module.exports = __toCommonJS(index_exports);
+function buildTree(items, options) {
+  if (!options) {
+    throw new Error('Missing required "options" parameter.');
+  }
+  const {
+    id: idAccessor,
+    parentId: parentIdAccessor,
+    childIds: childIdsAccessor,
+    nodeValueMapper,
+    nodeValueKey = "value",
+    nodeParentKey = "parent",
+    nodeChildrenKey = "children",
+    withDepth = false,
+    validateTree = false,
+    validateReferences = false
+  } = options;
+  if (!idAccessor) {
+    throw new Error('Option "id" is required.');
+  }
+  if (!parentIdAccessor && !childIdsAccessor) {
+    throw new Error('Either "parentId" or "childIds" must be provided.');
+  }
+  if (parentIdAccessor && childIdsAccessor) {
+    throw new Error('"parentId" and "childIds" cannot be used together.');
+  }
+  const roots = [];
+  const nodes = /* @__PURE__ */ new Map();
+  if (parentIdAccessor) {
+    const waitingForParent = /* @__PURE__ */ new Map();
+    for (const item of items) {
+      const id = typeof idAccessor === "function" ? idAccessor(item) : item[idAccessor];
+      if (nodes.has(id)) {
+        throw new Error(`Duplicate identifier "${id}".`);
+      }
+      const node = nodeValueKey !== false ? { [nodeValueKey]: nodeValueMapper ? nodeValueMapper(item) : item } : { ...nodeValueMapper ? nodeValueMapper(item) : item };
+      nodes.set(id, node);
+      const parentId = typeof parentIdAccessor === "function" ? parentIdAccessor(item) : item[parentIdAccessor];
+      const parentNode = nodes.get(parentId);
+      if (parentNode) {
+        parentNode[nodeChildrenKey] ||= [];
+        parentNode[nodeChildrenKey].push(node);
+        if (nodeParentKey !== false) {
+          node[nodeParentKey] = parentNode;
         }
-        // Children of dangling nodes will become the root nodes
-        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
-                    if (nodeParentKey !== false) {
-                        delete root[nodeParentKey];
-                    }
-                    roots.push(root);
-                }
-            }
+      } else {
+        const siblings = waitingForParent.get(parentId);
+        if (siblings) {
+          siblings.push(node);
+        } else {
+          waitingForParent.set(parentId, [node]);
         }
-        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);
-                }
-            }
-        }
-        // 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}"`);
-                }
-            }
+      }
+      const children = waitingForParent.get(id);
+      if (children) {
+        node[nodeChildrenKey] = children;
+        if (nodeParentKey !== false) {
+          for (const child of children) {
+            child[nodeParentKey] = node;
+          }
         }
+        waitingForParent.delete(id);
+      }
     }
-    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) {
-            const keyOfNode = typeof key === 'function' ? key(item) : item[key];
-            const keyOfChildNodes = typeof childrenKey === 'function' ? childrenKey(item) : item[childrenKey];
-            if (knownNodes.has(keyOfNode)) {
-                throw new Error(`Duplicate identifier detected for "${keyOfNode}"`);
-            }
-            knownNodes.add(keyOfNode);
-            incompleteNodes.delete(keyOfNode);
-            let node = nodes.get(keyOfNode);
-            if (!node) {
-                node = {};
-                danglingNodes.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 children to this node
-            if (keyOfChildNodes) {
-                node[nodeChildrenKey] = [];
-                for (const keyOfChildNode of keyOfChildNodes) {
-                    let childNode = danglingNodes.get(keyOfChildNode);
-                    if (childNode) {
-                        nodes.set(keyOfChildNode, childNode);
-                        danglingNodes.delete(keyOfChildNode);
-                        // Set the parent on child node
-                        if (nodeParentKey !== false) {
-                            childNode[nodeParentKey] = node;
-                        }
-                    }
-                    else if (nodes.has(keyOfChildNode)) {
-                        throw new Error(`Duplicate parent detected for "${keyOfChildNode}"`);
-                    }
-                    else {
-                        // We create a new temporary node
-                        childNode = {};
-                        // Set the parent on child node
-                        if (nodeParentKey !== false) {
-                            childNode[nodeParentKey] = node;
-                        }
-                        nodes.set(keyOfChildNode, childNode);
-                        incompleteNodes.add(keyOfChildNode);
-                    }
-                    node[nodeChildrenKey].push(childNode);
-                }
-            }
+    for (const [parentId, nodes2] of waitingForParent.entries()) {
+      if (validateReferences && parentId != null) {
+        throw new Error(`Referential integrity violation: parentId "${parentId}" does not match any item in the input.`);
+      }
+      for (const node of nodes2) {
+        roots.push(node);
+      }
+    }
+  } else if (childIdsAccessor) {
+    const waitingChildren = /* @__PURE__ */ new Map();
+    const rootCandidates = /* @__PURE__ */ new Map();
+    for (const item of items) {
+      const id = typeof idAccessor === "function" ? idAccessor(item) : item[idAccessor];
+      if (nodes.has(id)) {
+        throw new Error(`Duplicate identifier "${id}".`);
+      }
+      const node = nodeValueKey !== false ? { [nodeValueKey]: nodeValueMapper ? nodeValueMapper(item) : item } : { ...nodeValueMapper ? nodeValueMapper(item) : item };
+      nodes.set(id, node);
+      const childIds = typeof childIdsAccessor === "function" ? childIdsAccessor(item) : item[childIdsAccessor];
+      if (childIds != null) {
+        if (typeof childIds[Symbol.iterator] !== "function") {
+          throw new Error(`Item "${id}" has invalid children: expected an iterable value.`);
         }
-        if (incompleteNodes.size > 0) {
-            throw new Error(`Some nodes miss their referenced children (count: ${incompleteNodes.size}, references: ${JSON.stringify([...incompleteNodes])}).`);
+        node[nodeChildrenKey] = [];
+        for (const childId of childIds) {
+          const childNode = nodes.get(childId);
+          if (childNode) {
+            node[nodeChildrenKey].push(childNode);
+            if (nodeParentKey !== false) {
+              if (childNode[nodeParentKey] && childNode[nodeParentKey] !== node) {
+                throw new Error(`Node "${childId}" already has a different parent, refusing to overwrite. Set "nodeParentKey" to false to supress this error.`);
+              }
+              childNode[nodeParentKey] = node;
+            }
+            rootCandidates.delete(childId);
+          } else {
+            waitingChildren.set(childId, {
+              parentNode: node,
+              childIndex: node[nodeChildrenKey].length
+            });
+            node[nodeChildrenKey].push(null);
+          }
         }
-        if (validRootKeys) {
-            const validKeys = new Set(validRootKeys);
-            for (const [key, node] of danglingNodes.entries()) {
-                if (!validKeys.has(key)) {
-                    throw new Error(`A root node has an invalid key "${key}"`);
-                }
-                roots.push(node);
-                nodes.set(key, node);
-            }
+        if (node[nodeChildrenKey].length === 0) {
+          delete node[nodeChildrenKey];
         }
-        else {
-            for (const [key, node] of danglingNodes.entries()) {
-                roots.push(node);
-                nodes.set(key, node);
-            }
+      }
+      const parentDescriptor = waitingChildren.get(id);
+      if (parentDescriptor) {
+        const { parentNode, childIndex } = parentDescriptor;
+        parentNode[nodeChildrenKey][childIndex] = node;
+        if (nodeParentKey !== false) {
+          if (node[nodeParentKey] && node[nodeParentKey] !== parentNode) {
+            throw new Error(`Node "${id}" already has a different parent, refusing to overwrite. Set "nodeParentKey" to false to supress this error.`);
+          }
+          node[nodeParentKey] = parentNode;
         }
+        waitingChildren.delete(id);
+      } else {
+        rootCandidates.set(id, node);
+      }
     }
-    if (validateTree) {
-        if (nodes.size > 0 && danglingNodes.size === 0) {
-            throw new Error('Tree validation error: Stucture is a cyclic graph.');
-        }
-        // Count nodes, if count === nodes.size then no cycles.
-        const gray = [...roots];
-        let count = 0;
-        let node;
-        while ((node = gray.pop()) && count <= nodes.size) {
-            ++count;
-            if (node[nodeChildrenKey]) {
-                for (const child of node[nodeChildrenKey]) {
-                    gray.push(child);
-                }
-            }
+    if (waitingChildren.size > 0) {
+      if (validateReferences) {
+        const childId = waitingChildren.keys().next().value;
+        throw new Error(`Referential integrity violation: child reference "${childId}" does not match any item in the input.`);
+      }
+      const pending = Array.from(waitingChildren.values());
+      for (let i = pending.length - 1; i >= 0; i--) {
+        const { parentNode, childIndex } = pending[i];
+        parentNode[nodeChildrenKey].splice(childIndex, 1);
+        if (parentNode[nodeChildrenKey].length === 0) {
+          delete parentNode[nodeChildrenKey];
         }
-        if (count !== nodes.size) {
-            throw new Error('Tree validation error: Stucture is a cyclic graph.');
+      }
+    }
+    for (const node of rootCandidates.values()) {
+      roots.push(node);
+    }
+  }
+  if (validateTree || withDepth) {
+    if (roots.length === 0 && nodes.size > 0) {
+      throw new Error("Tree validation failed: detected a cycle.");
+    }
+    const stack = [...roots].map((node) => ({ node, depth: 0 }));
+    const visited = /* @__PURE__ */ new Set();
+    let processedCount = 0;
+    const MAX_NODES = nodes.size;
+    while (stack.length > 0 && processedCount++ <= MAX_NODES) {
+      const { node, depth } = stack.pop();
+      if (visited.has(node)) {
+        throw new Error("Tree validation failed: a node reachable via multiple paths.");
+      }
+      visited.add(node);
+      if (withDepth) {
+        node.depth = depth;
+      }
+      if (node[nodeChildrenKey]) {
+        for (const child of node[nodeChildrenKey]) {
+          stack.push({ node: child, depth: depth + 1 });
         }
+      }
+    }
+    if (nodes.size !== visited.size) {
+      throw new Error("Tree validation failed: detected a cycle.");
     }
-    return { roots, nodes };
+  }
+  return { roots, nodes };
 }
-exports.default = buildTree;

package/index.d.cts

@@ -0,0 +1,109 @@
+type TreeNode<TValue, TValueKey extends string | number | symbol | false, TParentKey extends string | number | symbol | false, TChildrenKey extends string | number | symbol, TWithDepth extends boolean> = (TValueKey extends false ? (TParentKey extends false ? Omit<TValue, TChildrenKey> & {
+    [k in TChildrenKey]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TWithDepth>[];
+} : Omit<TValue, Exclude<TParentKey, false> | TChildrenKey> & {
+    [k in Exclude<TParentKey, false>]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TWithDepth>;
+} & {
+    [k in TChildrenKey]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TWithDepth>[];
+}) : (TParentKey extends false ? {
+    [k in Exclude<TValueKey, false>]: TValue;
+} & {
+    [k in TChildrenKey]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TWithDepth>[];
+} : {
+    [k in Exclude<TValueKey, false>]: TValue;
+} & {
+    [k in Exclude<TParentKey, false>]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TWithDepth>;
+} & {
+    [k in TChildrenKey]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TWithDepth>[];
+})) & (TWithDepth extends true ? {
+    depth: number;
+} : {});
+type AccessorReturnType<T, P extends (keyof T) | ((item: T) => any)> = P extends ((item: T) => infer R) ? R : P extends (keyof T) ? T[P] : never;
+type IterableKeys<T> = {
+    [K in keyof T]: T[K] extends Iterable<unknown> ? K : never;
+}[keyof T];
+export default function buildTree<TInputValue extends (TIdAccessor extends (keyof TInputValue) ? object : (TNodeValueKey extends false ? object : unknown)), TIdAccessor extends (keyof TInputValue) | ((item: TInputValue) => unknown), TMappedValue extends (TNodeValueKey extends false ? object : unknown) = TInputValue, TNodeValueKey extends string | number | symbol | false = 'value', TNodeParentKey extends string | number | symbol | false = 'parent', TNodeChildrenKey extends string | number | symbol = 'children', TWithDepth extends boolean = false, TTreeNode = TreeNode<TMappedValue extends undefined ? TInputValue : TMappedValue, TNodeValueKey, TNodeParentKey, TNodeChildrenKey, TWithDepth>>(items: Iterable<TInputValue>, options: {
+    /**
+     * A string key or function used to get the item's unique identifier.
+     */
+    id: TIdAccessor;
+    /**
+     * A string key or function used to get the item's parent identifier.
+     *
+     * Either `parentId` or `childIds` must be provided.
+     */
+    parentId?: (keyof TInputValue) | ((item: TInputValue) => unknown);
+    /**
+     * A string key or function to retrieve a list of child identifiers from an item.
+     *
+     * Either `parentId` or `childIds` must be provided.
+     */
+    childIds?: IterableKeys<TInputValue> | ((item: TInputValue) => Iterable<unknown> | null | undefined);
+    /**
+     * Maps the input item to a different value stored in the resulting tree node.
+     */
+    nodeValueMapper?: {
+        (item: TInputValue): TMappedValue;
+    };
+    /**
+     * Object key used to store the mapped value in the output tree node.
+     *
+     * Defaults to `'value'`.
+     */
+    nodeValueKey?: TNodeValueKey;
+    /**
+     * Object key used to store the reference to the parent node in the output tree node.
+     *
+     * Defaults to `'parent'`.
+     */
+    nodeParentKey?: TNodeParentKey;
+    /**
+     * Object key used to store the list of child nodes in the output tree node.
+     *
+     * Defaults to `'children'`.
+     */
+    nodeChildrenKey?: TNodeChildrenKey;
+    /**
+     * When enabled, adds a `depth` property to each output node indicating its depth within the tree.
+     * Root nodes have a depth of 0.
+     *
+     * This also implicitly enables `validateTree`, as depth assignment requires a valid tree structure,
+     * and both operations share the same traversal logic.
+     *
+     * Defaults to `false`.
+     */
+    withDepth?: TWithDepth;
+    /**
+     * Validates that the final structure forms a tree.
+     *
+     * Ensures:
+     * - No cycles
+     * - No node reachable through multiple paths
+     *
+     * Throws if the structure is not a proper tree.
+     *
+     * Defaults to `false`
+     */
+    validateTree?: boolean;
+    /**
+     * Validates referential integrity of the input.
+     *
+     * In strict mode:
+     * - All parent and child references must point to existing items in the input.
+     * - Root items must have their `parentId` unset, `null`, or `undefined`.
+     *
+     * Any invalid or missing references will result in an error during tree construction.
+     *
+     * Defaults to `false`
+     */
+    validateReferences?: boolean;
+} & ({
+    parentId?: never;
+    childIds: IterableKeys<TInputValue> | ((item: TInputValue) => unknown[] | null | undefined);
+} | {
+    parentId: (keyof TInputValue) | ((item: TInputValue) => unknown);
+    childIds?: never;
+})): {
+    roots: TTreeNode[];
+    nodes: Map<AccessorReturnType<TInputValue, TIdAccessor>, TTreeNode>;
+};
+export {};

package/index.d.mts

@@ -0,0 +1,109 @@
+type TreeNode<TValue, TValueKey extends string | number | symbol | false, TParentKey extends string | number | symbol | false, TChildrenKey extends string | number | symbol, TWithDepth extends boolean> = (TValueKey extends false ? (TParentKey extends false ? Omit<TValue, TChildrenKey> & {
+    [k in TChildrenKey]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TWithDepth>[];
+} : Omit<TValue, Exclude<TParentKey, false> | TChildrenKey> & {
+    [k in Exclude<TParentKey, false>]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TWithDepth>;
+} & {
+    [k in TChildrenKey]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TWithDepth>[];
+}) : (TParentKey extends false ? {
+    [k in Exclude<TValueKey, false>]: TValue;
+} & {
+    [k in TChildrenKey]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TWithDepth>[];
+} : {
+    [k in Exclude<TValueKey, false>]: TValue;
+} & {
+    [k in Exclude<TParentKey, false>]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TWithDepth>;
+} & {
+    [k in TChildrenKey]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TWithDepth>[];
+})) & (TWithDepth extends true ? {
+    depth: number;
+} : {});
+type AccessorReturnType<T, P extends (keyof T) | ((item: T) => any)> = P extends ((item: T) => infer R) ? R : P extends (keyof T) ? T[P] : never;
+type IterableKeys<T> = {
+    [K in keyof T]: T[K] extends Iterable<unknown> ? K : never;
+}[keyof T];
+export default function buildTree<TInputValue extends (TIdAccessor extends (keyof TInputValue) ? object : (TNodeValueKey extends false ? object : unknown)), TIdAccessor extends (keyof TInputValue) | ((item: TInputValue) => unknown), TMappedValue extends (TNodeValueKey extends false ? object : unknown) = TInputValue, TNodeValueKey extends string | number | symbol | false = 'value', TNodeParentKey extends string | number | symbol | false = 'parent', TNodeChildrenKey extends string | number | symbol = 'children', TWithDepth extends boolean = false, TTreeNode = TreeNode<TMappedValue extends undefined ? TInputValue : TMappedValue, TNodeValueKey, TNodeParentKey, TNodeChildrenKey, TWithDepth>>(items: Iterable<TInputValue>, options: {
+    /**
+     * A string key or function used to get the item's unique identifier.
+     */
+    id: TIdAccessor;
+    /**
+     * A string key or function used to get the item's parent identifier.
+     *
+     * Either `parentId` or `childIds` must be provided.
+     */
+    parentId?: (keyof TInputValue) | ((item: TInputValue) => unknown);
+    /**
+     * A string key or function to retrieve a list of child identifiers from an item.
+     *
+     * Either `parentId` or `childIds` must be provided.
+     */
+    childIds?: IterableKeys<TInputValue> | ((item: TInputValue) => Iterable<unknown> | null | undefined);
+    /**
+     * Maps the input item to a different value stored in the resulting tree node.
+     */
+    nodeValueMapper?: {
+        (item: TInputValue): TMappedValue;
+    };
+    /**
+     * Object key used to store the mapped value in the output tree node.
+     *
+     * Defaults to `'value'`.
+     */
+    nodeValueKey?: TNodeValueKey;
+    /**
+     * Object key used to store the reference to the parent node in the output tree node.
+     *
+     * Defaults to `'parent'`.
+     */
+    nodeParentKey?: TNodeParentKey;
+    /**
+     * Object key used to store the list of child nodes in the output tree node.
+     *
+     * Defaults to `'children'`.
+     */
+    nodeChildrenKey?: TNodeChildrenKey;
+    /**
+     * When enabled, adds a `depth` property to each output node indicating its depth within the tree.
+     * Root nodes have a depth of 0.
+     *
+     * This also implicitly enables `validateTree`, as depth assignment requires a valid tree structure,
+     * and both operations share the same traversal logic.
+     *
+     * Defaults to `false`.
+     */
+    withDepth?: TWithDepth;
+    /**
+     * Validates that the final structure forms a tree.
+     *
+     * Ensures:
+     * - No cycles
+     * - No node reachable through multiple paths
+     *
+     * Throws if the structure is not a proper tree.
+     *
+     * Defaults to `false`
+     */
+    validateTree?: boolean;
+    /**
+     * Validates referential integrity of the input.
+     *
+     * In strict mode:
+     * - All parent and child references must point to existing items in the input.
+     * - Root items must have their `parentId` unset, `null`, or `undefined`.
+     *
+     * Any invalid or missing references will result in an error during tree construction.
+     *
+     * Defaults to `false`
+     */
+    validateReferences?: boolean;
+} & ({
+    parentId?: never;
+    childIds: IterableKeys<TInputValue> | ((item: TInputValue) => unknown[] | null | undefined);
+} | {
+    parentId: (keyof TInputValue) | ((item: TInputValue) => unknown);
+    childIds?: never;
+})): {
+    roots: TTreeNode[];
+    nodes: Map<AccessorReturnType<TInputValue, TIdAccessor>, TTreeNode>;
+};
+export {};

package/index.mjs

@@ -0,0 +1,175 @@
+function buildTree(items, options) {
+  if (!options) {
+    throw new Error('Missing required "options" parameter.');
+  }
+  const {
+    id: idAccessor,
+    parentId: parentIdAccessor,
+    childIds: childIdsAccessor,
+    nodeValueMapper,
+    nodeValueKey = "value",
+    nodeParentKey = "parent",
+    nodeChildrenKey = "children",
+    withDepth = false,
+    validateTree = false,
+    validateReferences = false
+  } = options;
+  if (!idAccessor) {
+    throw new Error('Option "id" is required.');
+  }
+  if (!parentIdAccessor && !childIdsAccessor) {
+    throw new Error('Either "parentId" or "childIds" must be provided.');
+  }
+  if (parentIdAccessor && childIdsAccessor) {
+    throw new Error('"parentId" and "childIds" cannot be used together.');
+  }
+  const roots = [];
+  const nodes = /* @__PURE__ */ new Map();
+  if (parentIdAccessor) {
+    const waitingForParent = /* @__PURE__ */ new Map();
+    for (const item of items) {
+      const id = typeof idAccessor === "function" ? idAccessor(item) : item[idAccessor];
+      if (nodes.has(id)) {
+        throw new Error(`Duplicate identifier "${id}".`);
+      }
+      const node = nodeValueKey !== false ? { [nodeValueKey]: nodeValueMapper ? nodeValueMapper(item) : item } : { ...nodeValueMapper ? nodeValueMapper(item) : item };
+      nodes.set(id, node);
+      const parentId = typeof parentIdAccessor === "function" ? parentIdAccessor(item) : item[parentIdAccessor];
+      const parentNode = nodes.get(parentId);
+      if (parentNode) {
+        parentNode[nodeChildrenKey] ||= [];
+        parentNode[nodeChildrenKey].push(node);
+        if (nodeParentKey !== false) {
+          node[nodeParentKey] = parentNode;
+        }
+      } else {
+        const siblings = waitingForParent.get(parentId);
+        if (siblings) {
+          siblings.push(node);
+        } else {
+          waitingForParent.set(parentId, [node]);
+        }
+      }
+      const children = waitingForParent.get(id);
+      if (children) {
+        node[nodeChildrenKey] = children;
+        if (nodeParentKey !== false) {
+          for (const child of children) {
+            child[nodeParentKey] = node;
+          }
+        }
+        waitingForParent.delete(id);
+      }
+    }
+    for (const [parentId, nodes2] of waitingForParent.entries()) {
+      if (validateReferences && parentId != null) {
+        throw new Error(`Referential integrity violation: parentId "${parentId}" does not match any item in the input.`);
+      }
+      for (const node of nodes2) {
+        roots.push(node);
+      }
+    }
+  } else if (childIdsAccessor) {
+    const waitingChildren = /* @__PURE__ */ new Map();
+    const rootCandidates = /* @__PURE__ */ new Map();
+    for (const item of items) {
+      const id = typeof idAccessor === "function" ? idAccessor(item) : item[idAccessor];
+      if (nodes.has(id)) {
+        throw new Error(`Duplicate identifier "${id}".`);
+      }
+      const node = nodeValueKey !== false ? { [nodeValueKey]: nodeValueMapper ? nodeValueMapper(item) : item } : { ...nodeValueMapper ? nodeValueMapper(item) : item };
+      nodes.set(id, node);
+      const childIds = typeof childIdsAccessor === "function" ? childIdsAccessor(item) : item[childIdsAccessor];
+      if (childIds != null) {
+        if (typeof childIds[Symbol.iterator] !== "function") {
+          throw new Error(`Item "${id}" has invalid children: expected an iterable value.`);
+        }
+        node[nodeChildrenKey] = [];
+        for (const childId of childIds) {
+          const childNode = nodes.get(childId);
+          if (childNode) {
+            node[nodeChildrenKey].push(childNode);
+            if (nodeParentKey !== false) {
+              if (childNode[nodeParentKey] && childNode[nodeParentKey] !== node) {
+                throw new Error(`Node "${childId}" already has a different parent, refusing to overwrite. Set "nodeParentKey" to false to supress this error.`);
+              }
+              childNode[nodeParentKey] = node;
+            }
+            rootCandidates.delete(childId);
+          } else {
+            waitingChildren.set(childId, {
+              parentNode: node,
+              childIndex: node[nodeChildrenKey].length
+            });
+            node[nodeChildrenKey].push(null);
+          }
+        }
+        if (node[nodeChildrenKey].length === 0) {
+          delete node[nodeChildrenKey];
+        }
+      }
+      const parentDescriptor = waitingChildren.get(id);
+      if (parentDescriptor) {
+        const { parentNode, childIndex } = parentDescriptor;
+        parentNode[nodeChildrenKey][childIndex] = node;
+        if (nodeParentKey !== false) {
+          if (node[nodeParentKey] && node[nodeParentKey] !== parentNode) {
+            throw new Error(`Node "${id}" already has a different parent, refusing to overwrite. Set "nodeParentKey" to false to supress this error.`);
+          }
+          node[nodeParentKey] = parentNode;
+        }
+        waitingChildren.delete(id);
+      } else {
+        rootCandidates.set(id, node);
+      }
+    }
+    if (waitingChildren.size > 0) {
+      if (validateReferences) {
+        const childId = waitingChildren.keys().next().value;
+        throw new Error(`Referential integrity violation: child reference "${childId}" does not match any item in the input.`);
+      }
+      const pending = Array.from(waitingChildren.values());
+      for (let i = pending.length - 1; i >= 0; i--) {
+        const { parentNode, childIndex } = pending[i];
+        parentNode[nodeChildrenKey].splice(childIndex, 1);
+        if (parentNode[nodeChildrenKey].length === 0) {
+          delete parentNode[nodeChildrenKey];
+        }
+      }
+    }
+    for (const node of rootCandidates.values()) {
+      roots.push(node);
+    }
+  }
+  if (validateTree || withDepth) {
+    if (roots.length === 0 && nodes.size > 0) {
+      throw new Error("Tree validation failed: detected a cycle.");
+    }
+    const stack = [...roots].map((node) => ({ node, depth: 0 }));
+    const visited = /* @__PURE__ */ new Set();
+    let processedCount = 0;
+    const MAX_NODES = nodes.size;
+    while (stack.length > 0 && processedCount++ <= MAX_NODES) {
+      const { node, depth } = stack.pop();
+      if (visited.has(node)) {
+        throw new Error("Tree validation failed: a node reachable via multiple paths.");
+      }
+      visited.add(node);
+      if (withDepth) {
+        node.depth = depth;
+      }
+      if (node[nodeChildrenKey]) {
+        for (const child of node[nodeChildrenKey]) {
+          stack.push({ node: child, depth: depth + 1 });
+        }
+      }
+    }
+    if (nodes.size !== visited.size) {
+      throw new Error("Tree validation failed: detected a cycle.");
+    }
+  }
+  return { roots, nodes };
+}
+export {
+  buildTree as default
+};

package/package.json

@@ -1,30 +1,30 @@
 {
   "name": "fast-tree-builder",
-  "version": "1.0.2",
+  "version": "2.0.0-alpha.0",
   "description": "Efficiently construct highly customizable bi-directional tree structures from iterable data.",
-  "type": "module",
-  "module": "./index.js",
+  "types": "./index.d.mts",
+  "module": "./index.mjs",
   "main": "./index.cjs",
-  "types": "./index.d.ts",
   "exports": {
     ".": {
-      "import": "./index.js",
-      "require": "./index.cjs",
-      "types": "./index.d.ts"
+      "types": "./index.d.mts",
+      "import": "./index.mjs",
+      "require": "./index.cjs"
     }
   },
   "scripts": {
     "prepack": "npm run build && npm run test",
     "postversion": "git push && git push --tags",
-    "clean": "node scripts/clean.js",
-    "build": "node scripts/build.js",
-    "watch": "node scripts/watch.js",
+    "clean": "node scripts/clean.mjs",
+    "build": "node scripts/build.mjs",
+    "watch": "node scripts/watch.mjs",
     "test": "mocha",
     "coverage": "c8 -r text -r text-summary -r lcov --include \"*.js\" npm test"
   },
   "devDependencies": {
     "c8": "^10.1.3",
     "chokidar": "^4.0.3",
+    "esbuild": "^0.25.4",
     "mocha": "^11.1.0",
     "typescript": "^5.3.3"
   },

package/index.d.ts

@@ -1,37 +0,0 @@
-type TreeNode<TInputData, TDataKey extends string | number | symbol | false, TParentKey extends string | number | symbol | false, TChildrenKey extends string | number | symbol> = (TDataKey extends false ? (TParentKey extends false ? Omit<TInputData, TChildrenKey> & {
-    [k in TChildrenKey]?: TreeNode<TInputData, TDataKey, TParentKey, TChildrenKey>[];
-} : Omit<TInputData, Exclude<TParentKey, false> | TChildrenKey> & {
-    [k in Exclude<TParentKey, false>]?: TreeNode<TInputData, TDataKey, TParentKey, TChildrenKey>;
-} & {
-    [k in TChildrenKey]?: TreeNode<TInputData, TDataKey, TParentKey, TChildrenKey>[];
-}) : (TParentKey extends false ? {
-    [k in Exclude<TDataKey, false>]: TInputData;
-} & {
-    [k in TChildrenKey]?: TreeNode<TInputData, TDataKey, TParentKey, TChildrenKey>[];
-} : {
-    [k in Exclude<TDataKey, false>]: TInputData;
-} & {
-    [k in Exclude<TParentKey, false>]?: TreeNode<TInputData, TDataKey, TParentKey, TChildrenKey>;
-} & {
-    [k in TChildrenKey]?: TreeNode<TInputData, TDataKey, TParentKey, TChildrenKey>[];
-}));
-type KeyReturnType<T, P extends keyof T | ((item: T) => any)> = P extends ((item: T) => infer R) ? R : P extends keyof T ? T[P] : never;
-declare function buildTree<TInputData extends (TNodeDataKey extends false ? object : unknown), TKey extends keyof TInputData | ((item: TInputData) => any), TMappedData extends (TNodeDataKey extends false ? object : unknown) = TInputData, TNodeDataKey extends string | number | symbol | false = 'data', TNodeParentKey extends string | number | symbol | false = 'parent', TNodeChildrenKey extends string | number | symbol = 'children'>(items: Iterable<TInputData>, options?: {
-    mode?: 'parent' | 'children';
-    key?: TKey;
-    parentKey?: keyof TInputData | ((item: TInputData) => any);
-    childrenKey?: keyof TInputData | ((item: TInputData) => any);
-    nodeDataKey?: TNodeDataKey;
-    nodeParentKey?: TNodeParentKey;
-    nodeChildrenKey?: TNodeChildrenKey;
-    mapNodeData?: {
-        (item: TInputData): TMappedData;
-    };
-    validRootKeys?: Iterable<unknown>;
-    validRootParentKeys?: Iterable<unknown>;
-    validateTree?: boolean;
-}): {
-    roots: TreeNode<TMappedData extends undefined ? TInputData : TMappedData, TNodeDataKey, TNodeParentKey, TNodeChildrenKey>[];
-    nodes: Map<KeyReturnType<TInputData, TKey>, TreeNode<TMappedData extends undefined ? TInputData : TMappedData, TNodeDataKey, TNodeParentKey, TNodeChildrenKey>>;
-};
-export default buildTree;

package/index.js

@@ -1,186 +0,0 @@
-function buildTree(items, 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();
-    if (mode === 'parent') {
-        for (const item of items) {
-            const keyOfNode = typeof key === 'function' ? key(item) : item[key];
-            const keyOfParentNode = typeof parentKey === 'function' ? parentKey(item) : item[parentKey];
-            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
-            let parentNode = nodes.get(keyOfParentNode) ?? danglingNodes.get(keyOfParentNode);
-            if (!parentNode) {
-                // No parent node exists yet, create as dangling node
-                parentNode = {};
-                // Track as dangling node, we dont know yet if it really exists
-                danglingNodes.set(keyOfParentNode, parentNode);
-            }
-            // When no children added yet
-            if (!parentNode[nodeChildrenKey]) {
-                parentNode[nodeChildrenKey] = [];
-            }
-            // Add as child
-            parentNode[nodeChildrenKey].push(node);
-            // Set the parent on this node
-            if (nodeParentKey !== false) {
-                node[nodeParentKey] = parentNode;
-            }
-        }
-        // Children of dangling nodes will become the root nodes
-        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
-                    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);
-                }
-            }
-        }
-        // 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) {
-            const keyOfNode = typeof key === 'function' ? key(item) : item[key];
-            const keyOfChildNodes = typeof childrenKey === 'function' ? childrenKey(item) : item[childrenKey];
-            if (knownNodes.has(keyOfNode)) {
-                throw new Error(`Duplicate identifier detected for "${keyOfNode}"`);
-            }
-            knownNodes.add(keyOfNode);
-            incompleteNodes.delete(keyOfNode);
-            let node = nodes.get(keyOfNode);
-            if (!node) {
-                node = {};
-                danglingNodes.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 children to this node
-            if (keyOfChildNodes) {
-                node[nodeChildrenKey] = [];
-                for (const keyOfChildNode of keyOfChildNodes) {
-                    let childNode = danglingNodes.get(keyOfChildNode);
-                    if (childNode) {
-                        nodes.set(keyOfChildNode, childNode);
-                        danglingNodes.delete(keyOfChildNode);
-                        // Set the parent on child node
-                        if (nodeParentKey !== false) {
-                            childNode[nodeParentKey] = node;
-                        }
-                    }
-                    else if (nodes.has(keyOfChildNode)) {
-                        throw new Error(`Duplicate parent detected for "${keyOfChildNode}"`);
-                    }
-                    else {
-                        // We create a new temporary node
-                        childNode = {};
-                        // Set the parent on child node
-                        if (nodeParentKey !== false) {
-                            childNode[nodeParentKey] = node;
-                        }
-                        nodes.set(keyOfChildNode, childNode);
-                        incompleteNodes.add(keyOfChildNode);
-                    }
-                    node[nodeChildrenKey].push(childNode);
-                }
-            }
-        }
-        if (incompleteNodes.size > 0) {
-            throw new Error(`Some nodes miss their referenced children (count: ${incompleteNodes.size}, references: ${JSON.stringify([...incompleteNodes])}).`);
-        }
-        if (validRootKeys) {
-            const validKeys = new Set(validRootKeys);
-            for (const [key, node] of danglingNodes.entries()) {
-                if (!validKeys.has(key)) {
-                    throw new Error(`A root node has an invalid key "${key}"`);
-                }
-                roots.push(node);
-                nodes.set(key, node);
-            }
-        }
-        else {
-            for (const [key, node] of danglingNodes.entries()) {
-                roots.push(node);
-                nodes.set(key, node);
-            }
-        }
-    }
-    if (validateTree) {
-        if (nodes.size > 0 && danglingNodes.size === 0) {
-            throw new Error('Tree validation error: Stucture is a cyclic graph.');
-        }
-        // Count nodes, if count === nodes.size then no cycles.
-        const gray = [...roots];
-        let count = 0;
-        let node;
-        while ((node = gray.pop()) && count <= nodes.size) {
-            ++count;
-            if (node[nodeChildrenKey]) {
-                for (const child of node[nodeChildrenKey]) {
-                    gray.push(child);
-                }
-            }
-        }
-        if (count !== nodes.size) {
-            throw new Error('Tree validation error: Stucture is a cyclic graph.');
-        }
-    }
-    return { roots, nodes };
-}
-export default buildTree;