fast-tree-builder 2.0.0 → 2.0.2

package/README.md

@@ -61,8 +61,8 @@ Builds a tree structure from an iterable list of items.
 
 ##### One of
 
-- `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.
+- `parentId`: A key or a function that returns the parent ID of the item.
+- `childIds`: A key or a function that returns an iterable of child IDs for the item.
 
 ##### Optional
 
@@ -71,20 +71,10 @@ Builds a tree structure from an iterable list of items.
 - `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. Setting this enables validateTree implicitly, as depth calculation requires full tree validation. Defaults to `false`.
+- `includeEmptyChildrenArray`: Leaf nodes will include an empty children array when this is set to `true`. Otherwise they are left as `undefined`. 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
 
 ```ts
@@ -101,6 +91,36 @@ Builds a tree structure from an iterable list of items.
 - Invalid reference (if `validateReferences` is enabled)
 - Cycle or structural error (if `validateTree` is enabled or `depthKey` is string)
 
+### Good to know
+
+> **Input Accessors vs. Output Keys in Options**
+>
+> * `id`, `parentId`, `childIds` works on the input item and can be property names or functions.
+> * `valueKey`, `parentKey`, `childrenKey`, `depthKey` are always strings or `false` and are used as keys in the output nodes.
+>
+> I considered prefixing these two groups with `input` and `output` to distinguish them, but in the end, this note in the README felt good enough.
+
+
+> **Identifiers**
+>
+> The library makes no assumptions about ID values — any unique JavaScript value is accepted, including `null` and `undefined`.
+
+
+> **Child Node Ordering**
+>
+> This library preserves the order of items when building tree structures, depending on how the tree is constructed:
+>
+> When using parent IDs to connect items, the order of child nodes will match the order in which the items appeared in the original input array.
+>
+> When using child IDs to connect items, the order of child nodes will match the order of the child IDs defined in the input item.
+
+
+> **'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.
+
 
 ## Usage
 
@@ -293,13 +313,40 @@ 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.
+    If the above doesn't work for your case, define your tree node type from scratch.
+
+    We intentionally don’t expose a generic `TreeNode` type in the package, as maintaining a complex set of generic parameters is often more cumbersome than writing a custom recursive type yourself.
+
+2. How can I present the `children` list in a specific order?
+
+    Pre-sort your input items:
+
+    ```typescript
+    const items = [
+      { id: 0, name: 'X', order: 0 },
+      { id: 1, name: 'A', order: 3, parent: 0 },
+      { id: 2, name: 'B', order: 2, parent: 0 },
+      { id: 3, name: 'C', order: 1, parent: 0 },
+    ];
+
+    // sort input by your `order` value
+    items.sort((a, b) => a.order - b.order);
+
+    const { roots } = buildTree(items, {
+      id: 'id',
+      parentId: 'parent',
+    });
+
+    roots[0].children
+    // this will be sorted as 'C', 'B', 'A'
+    // according to their order values.
+    ```
 
 ## 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.
+The package is designed to be feature-complete and highly customizable, which often comes at the cost of performance. Some libraries may be more *performant*, but they lack features I regularly need. In typical use cases, this package performs well, and others are usually only faster when offering much less customization.
 
-For scenarios where performance is critical and you start to benchmark tree building libraries, consider  implementing your custom algorithm instead. It could be as simple as:
+For scenarios where performance is critical and you start benchmarking libraries, consider implementing your custom algorithm instead. It could be as simple as:
 ```js
 const roots = [];
 const nodes = new Map();

package/index.cjs

@@ -35,7 +35,8 @@ function buildTree(items, options) {
     childrenKey = "children",
     depthKey = false,
     validateTree = false,
-    validateReferences = false
+    validateReferences = false,
+    includeEmptyChildrenArray = false
   } = options;
   if (!idAccessor) {
     throw new Error(`Option 'id' is required.`);
@@ -62,6 +63,9 @@ function buildTree(items, options) {
         }
         delete node[childrenKey];
       }
+      if (includeEmptyChildrenArray) {
+        node[childrenKey] = [];
+      }
       nodes.set(id, node);
       const parentId = typeof parentIdAccessor === "function" ? parentIdAccessor(item) : item[parentIdAccessor];
       const parentNode = nodes.get(parentId);
@@ -113,6 +117,9 @@ function buildTree(items, options) {
         }
         delete node[childrenKey];
       }
+      if (includeEmptyChildrenArray) {
+        node[childrenKey] = [];
+      }
       nodes.set(id, node);
       const childIds = typeof childIdsAccessor === "function" ? childIdsAccessor(item) : item[childIdsAccessor];
       if (childIds != null) {

package/index.d.cts

@@ -1,17 +1,19 @@
-type TreeNode<TValue, TValueKey extends PropertyKey | false, TParentKey extends PropertyKey | false, TChildrenKey extends PropertyKey, TDepthKey extends PropertyKey | false> = (TValueKey extends false ? Omit<TValue, Exclude<TParentKey, false> | TChildrenKey | Exclude<TDepthKey, false>> : {
+type TreeNode<TValue, TValueKey extends PropertyKey | false, TParentKey extends PropertyKey | false, TChildrenKey extends PropertyKey, TDepthKey extends PropertyKey | false, TIncludeEmptyChildrenArray extends boolean> = (TValueKey extends false ? Omit<TValue, Exclude<TParentKey, false> | TChildrenKey | Exclude<TDepthKey, false>> : {
     [k in Exclude<TValueKey, false>]: TValue;
 }) & (TParentKey extends false ? {} : {
-    [k in Exclude<TParentKey, false>]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TDepthKey>;
-}) & {
-    [k in TChildrenKey]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TDepthKey>[];
-} & (TDepthKey extends false ? {} : {
+    [k in Exclude<TParentKey, false>]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TDepthKey, TIncludeEmptyChildrenArray>;
+}) & (TIncludeEmptyChildrenArray extends true ? {
+    [k in TChildrenKey]: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TDepthKey, TIncludeEmptyChildrenArray>[];
+} : {
+    [k in TChildrenKey]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TDepthKey, TIncludeEmptyChildrenArray>[];
+}) & (TDepthKey extends false ? {} : {
     [k in Exclude<TDepthKey, false>]: number;
 });
 type AccessorReturnType<O, P extends (keyof O) | ((item: O) => any)> = P extends ((item: O) => infer R) ? R : P extends (keyof O) ? O[P] : never;
-type ObjectKeysOfIterableProperties<T> = {
+type ObjectKeysOfIterableProperties<T> = 0 extends (1 & T) ? PropertyKey : {
     [K in keyof T]: T[K] extends (Iterable<unknown> & object) | null | undefined ? K : never;
 }[keyof T];
-declare function buildTree<TIdAccessor extends (keyof NoInfer<TInputValue>) | ((item: NoInfer<TInputValue>) => unknown), TValueKey extends PropertyKey | false = 'value', TParentKey extends PropertyKey | false = 'parent', TChildrenKey extends PropertyKey = 'children', TDepthKey extends PropertyKey | false = false, TInputValue extends (TValueKey extends false ? object : TIdAccessor extends PropertyKey ? object : unknown) = any, TResolvedValue extends (TValueKey extends false ? object : unknown) = TInputValue>(items: Iterable<TInputValue>, options: {
+declare function buildTree<TIdAccessor extends NoInfer<keyof TInputValue> | ((item: NoInfer<TInputValue>) => unknown), TValueKey extends PropertyKey | false = 'value', TParentKey extends PropertyKey | false = 'parent', TChildrenKey extends PropertyKey = 'children', TDepthKey extends PropertyKey | false = false, TInputValue extends (TValueKey extends false ? object : TIdAccessor extends PropertyKey ? object : unknown) = any, TResolvedValue extends (TValueKey extends false ? object : unknown) = TInputValue, TIncludeEmptyChildrenArray extends boolean = false>(items: Iterable<TInputValue>, options: {
     /**
      * A string key or function used to get the item's unique identifier.
      */
@@ -56,6 +58,15 @@ declare function buildTree<TIdAccessor extends (keyof NoInfer<TInputValue>) | ((
      * Defaults to `false`.
      */
     depthKey?: TDepthKey;
+    /**
+     * Leaf nodes will include an empty children array when this is set to `true`.
+     * Otherwise they are left as `undefined`.
+     *
+     * This ensures you can loop over every node child list without checking its existence.
+     *
+     * Defaults to `false`.
+     */
+    includeEmptyChildrenArray?: TIncludeEmptyChildrenArray;
     /**
      * Validates that the final structure forms a tree.
      *
@@ -90,14 +101,14 @@ declare function buildTree<TIdAccessor extends (keyof NoInfer<TInputValue>) | ((
      *
      * Either `parentId` or `childIds` must be provided.
      */
-    childIds: ObjectKeysOfIterableProperties<NoInfer<TInputValue>> | ((item: NoInfer<TInputValue>) => (Iterable<unknown> & object) | null | undefined);
+    childIds: NoInfer<ObjectKeysOfIterableProperties<TInputValue>> | ((item: NoInfer<TInputValue>) => (Iterable<unknown> & object) | null | undefined);
 } | {
     /**
      * A string key or function used to get the item's parent identifier.
      *
      * Either `parentId` or `childIds` must be provided.
      */
-    parentId: (keyof NoInfer<TInputValue>) | ((item: NoInfer<TInputValue>) => unknown);
+    parentId: NoInfer<keyof TInputValue> | ((item: NoInfer<TInputValue>) => unknown);
     /**
      * A string key or function to retrieve a list of child identifiers from an item.
      *
@@ -105,8 +116,8 @@ declare function buildTree<TIdAccessor extends (keyof NoInfer<TInputValue>) | ((
      */
     childIds?: never;
 })): {
-    roots: TreeNode<TResolvedValue extends undefined ? TInputValue : TResolvedValue, TValueKey, TParentKey, TChildrenKey, TDepthKey>[];
-    nodes: Map<AccessorReturnType<TInputValue, TIdAccessor>, TreeNode<TResolvedValue extends undefined ? TInputValue : TResolvedValue, TValueKey, TParentKey, TChildrenKey, TDepthKey>>;
+    roots: TreeNode<TResolvedValue extends undefined ? TInputValue : TResolvedValue, TValueKey, TParentKey, TChildrenKey, TDepthKey, TIncludeEmptyChildrenArray>[];
+    nodes: Map<AccessorReturnType<TInputValue, TIdAccessor>, TreeNode<TResolvedValue extends undefined ? TInputValue : TResolvedValue, TValueKey, TParentKey, TChildrenKey, TDepthKey, TIncludeEmptyChildrenArray>>;
 };
 declare const _default: { default: typeof buildTree };
 export = _default;

package/index.d.mts

@@ -1,17 +1,19 @@
-type TreeNode<TValue, TValueKey extends PropertyKey | false, TParentKey extends PropertyKey | false, TChildrenKey extends PropertyKey, TDepthKey extends PropertyKey | false> = (TValueKey extends false ? Omit<TValue, Exclude<TParentKey, false> | TChildrenKey | Exclude<TDepthKey, false>> : {
+type TreeNode<TValue, TValueKey extends PropertyKey | false, TParentKey extends PropertyKey | false, TChildrenKey extends PropertyKey, TDepthKey extends PropertyKey | false, TIncludeEmptyChildrenArray extends boolean> = (TValueKey extends false ? Omit<TValue, Exclude<TParentKey, false> | TChildrenKey | Exclude<TDepthKey, false>> : {
     [k in Exclude<TValueKey, false>]: TValue;
 }) & (TParentKey extends false ? {} : {
-    [k in Exclude<TParentKey, false>]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TDepthKey>;
-}) & {
-    [k in TChildrenKey]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TDepthKey>[];
-} & (TDepthKey extends false ? {} : {
+    [k in Exclude<TParentKey, false>]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TDepthKey, TIncludeEmptyChildrenArray>;
+}) & (TIncludeEmptyChildrenArray extends true ? {
+    [k in TChildrenKey]: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TDepthKey, TIncludeEmptyChildrenArray>[];
+} : {
+    [k in TChildrenKey]?: TreeNode<TValue, TValueKey, TParentKey, TChildrenKey, TDepthKey, TIncludeEmptyChildrenArray>[];
+}) & (TDepthKey extends false ? {} : {
     [k in Exclude<TDepthKey, false>]: number;
 });
 type AccessorReturnType<O, P extends (keyof O) | ((item: O) => any)> = P extends ((item: O) => infer R) ? R : P extends (keyof O) ? O[P] : never;
-type ObjectKeysOfIterableProperties<T> = {
+type ObjectKeysOfIterableProperties<T> = 0 extends (1 & T) ? PropertyKey : {
     [K in keyof T]: T[K] extends (Iterable<unknown> & object) | null | undefined ? K : never;
 }[keyof T];
-export default function buildTree<TIdAccessor extends (keyof NoInfer<TInputValue>) | ((item: NoInfer<TInputValue>) => unknown), TValueKey extends PropertyKey | false = 'value', TParentKey extends PropertyKey | false = 'parent', TChildrenKey extends PropertyKey = 'children', TDepthKey extends PropertyKey | false = false, TInputValue extends (TValueKey extends false ? object : TIdAccessor extends PropertyKey ? object : unknown) = any, TResolvedValue extends (TValueKey extends false ? object : unknown) = TInputValue>(items: Iterable<TInputValue>, options: {
+export default function buildTree<TIdAccessor extends NoInfer<keyof TInputValue> | ((item: NoInfer<TInputValue>) => unknown), TValueKey extends PropertyKey | false = 'value', TParentKey extends PropertyKey | false = 'parent', TChildrenKey extends PropertyKey = 'children', TDepthKey extends PropertyKey | false = false, TInputValue extends (TValueKey extends false ? object : TIdAccessor extends PropertyKey ? object : unknown) = any, TResolvedValue extends (TValueKey extends false ? object : unknown) = TInputValue, TIncludeEmptyChildrenArray extends boolean = false>(items: Iterable<TInputValue>, options: {
     /**
      * A string key or function used to get the item's unique identifier.
      */
@@ -56,6 +58,15 @@ export default function buildTree<TIdAccessor extends (keyof NoInfer<TInputValue
      * Defaults to `false`.
      */
     depthKey?: TDepthKey;
+    /**
+     * Leaf nodes will include an empty children array when this is set to `true`.
+     * Otherwise they are left as `undefined`.
+     *
+     * This ensures you can loop over every node child list without checking its existence.
+     *
+     * Defaults to `false`.
+     */
+    includeEmptyChildrenArray?: TIncludeEmptyChildrenArray;
     /**
      * Validates that the final structure forms a tree.
      *
@@ -90,14 +101,14 @@ export default function buildTree<TIdAccessor extends (keyof NoInfer<TInputValue
      *
      * Either `parentId` or `childIds` must be provided.
      */
-    childIds: ObjectKeysOfIterableProperties<NoInfer<TInputValue>> | ((item: NoInfer<TInputValue>) => (Iterable<unknown> & object) | null | undefined);
+    childIds: NoInfer<ObjectKeysOfIterableProperties<TInputValue>> | ((item: NoInfer<TInputValue>) => (Iterable<unknown> & object) | null | undefined);
 } | {
     /**
      * A string key or function used to get the item's parent identifier.
      *
      * Either `parentId` or `childIds` must be provided.
      */
-    parentId: (keyof NoInfer<TInputValue>) | ((item: NoInfer<TInputValue>) => unknown);
+    parentId: NoInfer<keyof TInputValue> | ((item: NoInfer<TInputValue>) => unknown);
     /**
      * A string key or function to retrieve a list of child identifiers from an item.
      *
@@ -105,7 +116,7 @@ export default function buildTree<TIdAccessor extends (keyof NoInfer<TInputValue
      */
     childIds?: never;
 })): {
-    roots: TreeNode<TResolvedValue extends undefined ? TInputValue : TResolvedValue, TValueKey, TParentKey, TChildrenKey, TDepthKey>[];
-    nodes: Map<AccessorReturnType<TInputValue, TIdAccessor>, TreeNode<TResolvedValue extends undefined ? TInputValue : TResolvedValue, TValueKey, TParentKey, TChildrenKey, TDepthKey>>;
+    roots: TreeNode<TResolvedValue extends undefined ? TInputValue : TResolvedValue, TValueKey, TParentKey, TChildrenKey, TDepthKey, TIncludeEmptyChildrenArray>[];
+    nodes: Map<AccessorReturnType<TInputValue, TIdAccessor>, TreeNode<TResolvedValue extends undefined ? TInputValue : TResolvedValue, TValueKey, TParentKey, TChildrenKey, TDepthKey, TIncludeEmptyChildrenArray>>;
 };
 export {};

package/index.mjs

@@ -12,7 +12,8 @@ function buildTree(items, options) {
     childrenKey = "children",
     depthKey = false,
     validateTree = false,
-    validateReferences = false
+    validateReferences = false,
+    includeEmptyChildrenArray = false
   } = options;
   if (!idAccessor) {
     throw new Error(`Option 'id' is required.`);
@@ -39,6 +40,9 @@ function buildTree(items, options) {
         }
         delete node[childrenKey];
       }
+      if (includeEmptyChildrenArray) {
+        node[childrenKey] = [];
+      }
       nodes.set(id, node);
       const parentId = typeof parentIdAccessor === "function" ? parentIdAccessor(item) : item[parentIdAccessor];
       const parentNode = nodes.get(parentId);
@@ -90,6 +94,9 @@ function buildTree(items, options) {
         }
         delete node[childrenKey];
       }
+      if (includeEmptyChildrenArray) {
+        node[childrenKey] = [];
+      }
       nodes.set(id, node);
       const childIds = typeof childIdsAccessor === "function" ? childIdsAccessor(item) : item[childIdsAccessor];
       if (childIds != null) {

package/package.json

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