fast-tree-builder 2.0.0-alpha.4 → 2.0.0-beta.0

package/README.md

@@ -67,12 +67,12 @@ Builds a tree structure from an iterable list of items.
 ##### 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 nodes reachable via multipla paths). Errors are thrown if the check fails. Default: `false`.
+- `nodeValueKey`: Key where the item is stored in the output node. Set to `false` to inline the item directly into the node. Defaults to `'value'`.
+- `nodeParentKey`: Key where the node's parent reference is stored. Set to `false` to omit parent links. Defaults to `'parent'`.
+- `nodeChildrenKey`: Key where the node's children are stored. Defaults to `'children'`.
+- `nodeDepthKey`: Object key used to store the node's depth in the tree (root = 0). Set to `false` to omit depth values. Turns on `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`.
 
 #### Returns
 
@@ -88,7 +88,7 @@ Builds a tree structure from an iterable list of items.
 - Missing required `id`, `parentId`/`childIds`, or `options` parameter
 - Duplicate item identifiers in input
 - Invalid reference (if `validateReferences` is enabled)
-- Cycle or structural error (if `validateTree` or `withDepth` is enabled)
+- Cycle or structural error (if `validateTree` is enabled or `nodeDepthKey` is string)
 
 
 ## Usage

package/index.cjs

@@ -33,7 +33,7 @@ function buildTree(items, options) {
     nodeValueKey = "value",
     nodeParentKey = "parent",
     nodeChildrenKey = "children",
-    withDepth = false,
+    nodeDepthKey = false,
     validateTree = false,
     validateReferences = false
   } = options;
@@ -164,6 +164,7 @@ function buildTree(items, options) {
       roots.push(node);
     }
   }
+  const withDepth = typeof nodeDepthKey === "string" || typeof nodeDepthKey === "symbol" || typeof nodeDepthKey === "number";
   if (validateTree || withDepth) {
     if (roots.length === 0 && nodes.size > 0) {
       throw new Error("Tree validation failed: detected a cycle.");
@@ -179,7 +180,7 @@ function buildTree(items, options) {
       }
       visited.add(node);
       if (withDepth) {
-        node.depth = depth;
+        node[nodeDepthKey] = depth;
       }
       if (node[nodeChildrenKey]) {
         for (const child of node[nodeChildrenKey]) {

package/index.d.cts

@@ -1,51 +1,31 @@
-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 ? {
+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>> : {
     [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;
+}) & (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<TDepthKey, false>]: 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> = {
+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> = {
     [K in keyof T]: T[K] extends Iterable<unknown> & object ? K : never;
 }[keyof T];
-declare 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: {
+declare function buildTree<TIdAccessor extends (keyof NoInfer<TInputValue>) | ((item: NoInfer<TInputValue>) => unknown), TNodeValueKey extends PropertyKey | false = 'value', TNodeParentKey extends PropertyKey | false = 'parent', TNodeChildrenKey extends PropertyKey = 'children', TNodeDepthKey extends PropertyKey | false = false, TInputValue extends (TNodeValueKey extends false ? object : TIdAccessor extends PropertyKey ? object : unknown) = any, TMappedValue extends (TNodeValueKey extends false ? object : unknown) = TInputValue>(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> & object) | null | undefined);
     /**
      * Maps the input item to a different value stored in the resulting tree node.
      */
     nodeValueMapper?: {
-        (item: TInputValue): TMappedValue;
+        (item: NoInfer<TInputValue>): TMappedValue;
     };
     /**
-     * Object key used to store the mapped value in the output tree node.
+     * Object key used to store the input item in the output tree node.
+     *
+     * Set to `false` to merge the item into the node itself.
      *
      * Defaults to `'value'`.
      */
@@ -53,6 +33,8 @@ declare function buildTree<TInputValue extends (TIdAccessor extends (keyof TInpu
     /**
      * Object key used to store the reference to the parent node in the output tree node.
      *
+     * Set to `false` to omit parent links.
+     *
      * Defaults to `'parent'`.
      */
     nodeParentKey?: TNodeParentKey;
@@ -63,15 +45,17 @@ declare function buildTree<TInputValue extends (TIdAccessor extends (keyof TInpu
      */
     nodeChildrenKey?: TNodeChildrenKey;
     /**
-     * When enabled, adds a `depth` property to each output node indicating its depth within the tree.
+     * Object key used to store a value indicating the node depth in the tree on each output node.
      * 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.
+     * Set to `false` to omit depth values.
+     *
+     * Enables `validateTree`, as depth assignment requires a valid tree structure,
+     * and both operations also share the same traversal logic.
      *
      * Defaults to `false`.
      */
-    withDepth?: TWithDepth;
+    nodeDepthKey?: TNodeDepthKey;
     /**
      * Validates that the final structure forms a tree.
      *
@@ -97,14 +81,34 @@ declare function buildTree<TInputValue extends (TIdAccessor extends (keyof TInpu
      */
     validateReferences?: boolean;
 } & ({
+    /**
+     * A string key or function used to get the item's parent identifier.
+     *
+     * Either `parentId` or `childIds` must be provided.
+     */
     parentId?: never;
-    childIds: IterableKeys<TInputValue> | ((item: TInputValue) => (Iterable<unknown> & object) | null | undefined);
+    /**
+     * A string key or function to retrieve a list of child identifiers from an item.
+     *
+     * Either `parentId` or `childIds` must be provided.
+     */
+    childIds: ObjectKeysOfIterableProperties<NoInfer<TInputValue>> | ((item: NoInfer<TInputValue>) => (Iterable<unknown> & object) | null | undefined);
 } | {
-    parentId: (keyof TInputValue) | ((item: TInputValue) => unknown);
+    /**
+     * 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);
+    /**
+     * A string key or function to retrieve a list of child identifiers from an item.
+     *
+     * Either `parentId` or `childIds` must be provided.
+     */
     childIds?: never;
 })): {
-    roots: TTreeNode[];
-    nodes: Map<AccessorReturnType<TInputValue, TIdAccessor>, TTreeNode>;
+    roots: TreeNode<TMappedValue extends undefined ? TInputValue : TMappedValue, TNodeValueKey, TNodeParentKey, TNodeChildrenKey, TNodeDepthKey>[];
+    nodes: Map<AccessorReturnType<TInputValue, TIdAccessor>, TreeNode<TMappedValue extends undefined ? TInputValue : TMappedValue, TNodeValueKey, TNodeParentKey, TNodeChildrenKey, TNodeDepthKey>>;
 };
 declare const _default: { default: typeof buildTree };
 export = _default;

package/index.d.mts

@@ -1,51 +1,31 @@
-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 ? {
+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>> : {
     [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;
+}) & (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<TDepthKey, false>]: 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> = {
+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> = {
     [K in keyof T]: T[K] extends Iterable<unknown> & object ? 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: {
+export default function buildTree<TIdAccessor extends (keyof NoInfer<TInputValue>) | ((item: NoInfer<TInputValue>) => unknown), TNodeValueKey extends PropertyKey | false = 'value', TNodeParentKey extends PropertyKey | false = 'parent', TNodeChildrenKey extends PropertyKey = 'children', TNodeDepthKey extends PropertyKey | false = false, TInputValue extends (TNodeValueKey extends false ? object : TIdAccessor extends PropertyKey ? object : unknown) = any, TMappedValue extends (TNodeValueKey extends false ? object : unknown) = TInputValue>(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> & object) | null | undefined);
     /**
      * Maps the input item to a different value stored in the resulting tree node.
      */
     nodeValueMapper?: {
-        (item: TInputValue): TMappedValue;
+        (item: NoInfer<TInputValue>): TMappedValue;
     };
     /**
-     * Object key used to store the mapped value in the output tree node.
+     * Object key used to store the input item in the output tree node.
+     *
+     * Set to `false` to merge the item into the node itself.
      *
      * Defaults to `'value'`.
      */
@@ -53,6 +33,8 @@ export default function buildTree<TInputValue extends (TIdAccessor extends (keyo
     /**
      * Object key used to store the reference to the parent node in the output tree node.
      *
+     * Set to `false` to omit parent links.
+     *
      * Defaults to `'parent'`.
      */
     nodeParentKey?: TNodeParentKey;
@@ -63,15 +45,17 @@ export default function buildTree<TInputValue extends (TIdAccessor extends (keyo
      */
     nodeChildrenKey?: TNodeChildrenKey;
     /**
-     * When enabled, adds a `depth` property to each output node indicating its depth within the tree.
+     * Object key used to store a value indicating the node depth in the tree on each output node.
      * 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.
+     * Set to `false` to omit depth values.
+     *
+     * Enables `validateTree`, as depth assignment requires a valid tree structure,
+     * and both operations also share the same traversal logic.
      *
      * Defaults to `false`.
      */
-    withDepth?: TWithDepth;
+    nodeDepthKey?: TNodeDepthKey;
     /**
      * Validates that the final structure forms a tree.
      *
@@ -97,13 +81,33 @@ export default function buildTree<TInputValue extends (TIdAccessor extends (keyo
      */
     validateReferences?: boolean;
 } & ({
+    /**
+     * A string key or function used to get the item's parent identifier.
+     *
+     * Either `parentId` or `childIds` must be provided.
+     */
     parentId?: never;
-    childIds: IterableKeys<TInputValue> | ((item: TInputValue) => (Iterable<unknown> & object) | null | undefined);
+    /**
+     * A string key or function to retrieve a list of child identifiers from an item.
+     *
+     * Either `parentId` or `childIds` must be provided.
+     */
+    childIds: ObjectKeysOfIterableProperties<NoInfer<TInputValue>> | ((item: NoInfer<TInputValue>) => (Iterable<unknown> & object) | null | undefined);
 } | {
-    parentId: (keyof TInputValue) | ((item: TInputValue) => unknown);
+    /**
+     * 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);
+    /**
+     * A string key or function to retrieve a list of child identifiers from an item.
+     *
+     * Either `parentId` or `childIds` must be provided.
+     */
     childIds?: never;
 })): {
-    roots: TTreeNode[];
-    nodes: Map<AccessorReturnType<TInputValue, TIdAccessor>, TTreeNode>;
+    roots: TreeNode<TMappedValue extends undefined ? TInputValue : TMappedValue, TNodeValueKey, TNodeParentKey, TNodeChildrenKey, TNodeDepthKey>[];
+    nodes: Map<AccessorReturnType<TInputValue, TIdAccessor>, TreeNode<TMappedValue extends undefined ? TInputValue : TMappedValue, TNodeValueKey, TNodeParentKey, TNodeChildrenKey, TNodeDepthKey>>;
 };
 export {};

package/index.mjs

@@ -10,7 +10,7 @@ function buildTree(items, options) {
     nodeValueKey = "value",
     nodeParentKey = "parent",
     nodeChildrenKey = "children",
-    withDepth = false,
+    nodeDepthKey = false,
     validateTree = false,
     validateReferences = false
   } = options;
@@ -141,6 +141,7 @@ function buildTree(items, options) {
       roots.push(node);
     }
   }
+  const withDepth = typeof nodeDepthKey === "string" || typeof nodeDepthKey === "symbol" || typeof nodeDepthKey === "number";
   if (validateTree || withDepth) {
     if (roots.length === 0 && nodes.size > 0) {
       throw new Error("Tree validation failed: detected a cycle.");
@@ -156,7 +157,7 @@ function buildTree(items, options) {
       }
       visited.add(node);
       if (withDepth) {
-        node.depth = depth;
+        node[nodeDepthKey] = depth;
       }
       if (node[nodeChildrenKey]) {
         for (const child of node[nodeChildrenKey]) {

package/package.json

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