fast-tree-builder 2.0.0-beta.4 → 2.0.0-beta.6

package/README.md

@@ -61,18 +61,29 @@ Builds a tree structure from an iterable list of items.
 
 ##### One of
 
-- `parentId`: A key or function that access the parent ID of the item.
-- `childIds`: A key or function that access an iterable of child IDs for the item.
+- `parentId`: A key or function that accesses the parent ID of the item.
+- `childIds`: A key or function that accesses an iterable of child IDs for the item.
 
 ##### Optional
 
 - `valueResolver`: Function to transform an item to a custom value stored in the node. Defaults to use the input item as is.
-- `valueKey`: Key where the item is stored in the output node. Set to `false` to inline the item directly into the node. Defaults to `'value'`.
+- `valueKey`: Key where the item is stored in the output node. Set to `false` to merge the item's properties directly into the node (shallow copy). Defaults to `'value'`.
 - `parentKey`: Key where the node's parent reference is stored in the output node. Set to `false` to omit parent links. Defaults to `'parent'`.
 - `childrenKey`: Key where the node's children are stored in the output node. Defaults to `'children'`.
-- `depthKey`: Key where the node's depth (with root = 0) is stored in the output node. Set to `false` to omit depth values. Automatically enables `validateTree` when a string value is set here. Defaults to `false`.
-- `validateReferences`: When `true`, verifies all `parentId` or `childIds` resolve to real items. Errors are thrown on invalid references. Defaults to `false`.
-- `validateTree`: When `true`, verifies that the final structure is a valid tree (no cycles or nodes reachable via multipla paths). Errors are thrown if the check fails. Defaults to `false`.
+- `depthKey`: Key where the node's depth (with root = 0) is stored in the output node. Set to `false` to omit depth values. Setting this enables validateTree implicitly, as depth calculation requires full tree validation. Defaults to `false`.
+- `validateReferences`: When `true`, verifies all `parentId` or `childIds` resolve to real items. Only `null` and `undefined` are acceptable parent ids for root nodes when enabled. Errors are thrown on invalid references. Defaults to `false`.
+- `validateTree`: When `true`, verifies that the final structure is a valid tree (no cycles or nodes reachable via multiple paths). Errors are thrown if the check fails. Defaults to `false`.
+
+> **Input Accessors vs. Output Keys**
+>
+> * `id`, `parentId`, `childIds` works on the input item and can be property names or functions. The library does not make any assumption what an id should be so we purposely allow `null` and `undefined` as a valid id too!
+> * `valueKey`, `parentKey`, `childrenKey`, `depthKey` are always strings or `false` and are used as keys in the output nodes.
+
+> **'validateReferences' option**
+>
+> Validation operates differently when in `parentId` mode and in `childIds` mode!
+> * in `parentId` mode: validates that the parent ids of root nodes was `null` or `undefined` and nothing else. If you expect these parent ids to be other than `null` or `undefined`, you can safely turn off this validation and loop trough on the roots manually to check the original parentId values are the ones you expect.
+> * in `childIds` mode: validates that every referenced child is resolved. Even if the child list contains `undefined`, a node with an `undefined` as ID must exist in the input.
 
 #### Returns
 
@@ -250,7 +261,7 @@ const items = [
 
 const { roots, nodes } = buildTree(items, {
   id: item => item.substring(2, 4),
-  parentKey: item => item.substring(0, 2),
+  parentId: item => item.substring(0, 2),
   valueResolver: item => ({ name: item.substring(4) }),
   valueKey: false, // merge item data into node
 });
@@ -282,6 +293,8 @@ console.log(roots);
     type TreeNode = typeof roots[number];
     ```
 
+    We intentionally do not expose a generic `TreeNode` type from the package. It is harder to parameterize correctly by hand than to write a recursive type from scratch.
+
 ## Comparison with other tree building libraries
 
 The package aims to be feature complete and highly customizable, which usually opposes with performance. There are other packages that may be more *performant* but lacks features that I really needed in my daily coding. In standard scenarios this package should perform more than enough and nearly as good as any other package.

package/index.d.cts

@@ -25,7 +25,7 @@ declare function buildTree<TIdAccessor extends (keyof NoInfer<TInputValue>) | ((
     /**
      * Key where the item is stored in the output node.
      *
-     * Set to `false` to inline the item directly into the node.
+     * Set to `false` to merge the item's properties directly into the node (shallow copy).
      *
      * Defaults to `'value'`.
      */
@@ -50,8 +50,8 @@ declare function buildTree<TIdAccessor extends (keyof NoInfer<TInputValue>) | ((
      *
      * Set to `false` to omit depth values.
      *
-     * Automatically enables `validateTree` when a string value is set here:
-     * Depth assignment requires a valid tree structure, and both operations also share the same traversal logic.
+     * Setting this enables validateTree implicitly, as depth calculation requires full tree validation.
+     * Both operations share the same traversal logic so the additional tree validation is not an overhead.
      *
      * Defaults to `false`.
      */

package/index.d.mts

@@ -25,7 +25,7 @@ export default function buildTree<TIdAccessor extends (keyof NoInfer<TInputValue
     /**
      * Key where the item is stored in the output node.
      *
-     * Set to `false` to inline the item directly into the node.
+     * Set to `false` to merge the item's properties directly into the node (shallow copy).
      *
      * Defaults to `'value'`.
      */
@@ -50,8 +50,8 @@ export default function buildTree<TIdAccessor extends (keyof NoInfer<TInputValue
      *
      * Set to `false` to omit depth values.
      *
-     * Automatically enables `validateTree` when a string value is set here:
-     * Depth assignment requires a valid tree structure, and both operations also share the same traversal logic.
+     * Setting this enables validateTree implicitly, as depth calculation requires full tree validation.
+     * Both operations share the same traversal logic so the additional tree validation is not an overhead.
      *
      * Defaults to `false`.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fast-tree-builder",
-  "version": "2.0.0-beta.4",
+  "version": "2.0.0-beta.6",
   "description": "Easily construct highly customizable bi-directional tree structures from iterable data.",
   "types": "./index.d.mts",
   "module": "./index.mjs",