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

package/README.md

@@ -29,7 +29,7 @@
 - **Arbitary Node Access** – Returns a `Map` that 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.
-- **Depth Values** – Optionally includes a depth value in each node.
+- **Depth Values** – Optionally include a depth value in each node.
 
 ## Installation
 
@@ -66,13 +66,13 @@ 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`.
+- `nodeValueMapper`: Function to map an item to a custom value stored in the node.
+- `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

@@ -23,7 +23,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 function buildTree(items, options) {
   if (!options) {
-    throw new Error('Missing required "options" parameter.');
+    throw new Error(`Missing required 'options' parameter.`);
   }
   const {
     id: idAccessor,
@@ -33,18 +33,18 @@ function buildTree(items, options) {
     nodeValueKey = "value",
     nodeParentKey = "parent",
     nodeChildrenKey = "children",
-    withDepth = false,
+    nodeDepthKey = false,
     validateTree = false,
     validateReferences = false
   } = options;
   if (!idAccessor) {
-    throw new Error('Option "id" is required.');
+    throw new Error(`Option 'id' is required.`);
   }
   if (!parentIdAccessor && !childIdsAccessor) {
-    throw new Error('Either "parentId" or "childIds" must be provided.');
+    throw new Error(`Either 'parentId' or 'childIds' must be provided.`);
   }
   if (parentIdAccessor && childIdsAccessor) {
-    throw new Error('"parentId" and "childIds" cannot be used together.');
+    throw new Error(`'parentId' and 'childIds' cannot be used together.`);
   }
   const roots = [];
   const nodes = /* @__PURE__ */ new Map();
@@ -53,9 +53,15 @@ function buildTree(items, options) {
     for (const item of items) {
       const id = typeof idAccessor === "function" ? idAccessor(item) : item[idAccessor];
       if (nodes.has(id)) {
-        throw new Error(`Duplicate identifier "${id}".`);
+        throw new Error(`Duplicate identifier '${id}'.`);
       }
       const node = nodeValueKey !== false ? { [nodeValueKey]: nodeValueMapper ? nodeValueMapper(item) : item } : { ...nodeValueMapper ? nodeValueMapper(item) : item };
+      if (nodeValueKey === false) {
+        if (nodeParentKey !== false) {
+          delete node[nodeParentKey];
+        }
+        delete node[nodeChildrenKey];
+      }
       nodes.set(id, node);
       const parentId = typeof parentIdAccessor === "function" ? parentIdAccessor(item) : item[parentIdAccessor];
       const parentNode = nodes.get(parentId);
@@ -86,7 +92,7 @@ function buildTree(items, options) {
     }
     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.`);
+        throw new Error(`Referential integrity violation: parentId '${parentId}' does not match any item in the input.`);
       }
       for (const node of nodes2) {
         roots.push(node);
@@ -98,14 +104,20 @@ function buildTree(items, options) {
     for (const item of items) {
       const id = typeof idAccessor === "function" ? idAccessor(item) : item[idAccessor];
       if (nodes.has(id)) {
-        throw new Error(`Duplicate identifier "${id}".`);
+        throw new Error(`Duplicate identifier '${id}'.`);
       }
       const node = nodeValueKey !== false ? { [nodeValueKey]: nodeValueMapper ? nodeValueMapper(item) : item } : { ...nodeValueMapper ? nodeValueMapper(item) : item };
+      if (nodeValueKey === false) {
+        if (nodeParentKey !== false) {
+          delete node[nodeParentKey];
+        }
+        delete node[nodeChildrenKey];
+      }
       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.`);
+          throw new Error(`Item '${id}' has invalid children: expected an iterable value.`);
         }
         node[nodeChildrenKey] = [];
         for (const childId of childIds) {
@@ -114,12 +126,15 @@ function buildTree(items, options) {
             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.`);
+                throw new Error(`Node '${childId}' already has a different parent, refusing to overwrite.`);
               }
               childNode[nodeParentKey] = node;
             }
             rootCandidates.delete(childId);
           } else {
+            if (waitingChildren.has(childId)) {
+              throw new Error(`Multiple parents reference the same unresolved child '${childId}'.`);
+            }
             waitingChildren.set(childId, {
               parentNode: node,
               childIndex: node[nodeChildrenKey].length
@@ -137,7 +152,7 @@ function buildTree(items, options) {
         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.`);
+            throw new Error(`Node '${id}' already has a different parent, refusing to overwrite.`);
           }
           node[nodeParentKey] = parentNode;
         }
@@ -149,7 +164,7 @@ function buildTree(items, options) {
     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.`);
+        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--) {
@@ -164,6 +179,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 +195,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> = {
-    [K in keyof T]: T[K] extends Iterable<unknown> & object ? K : never;
+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) | null | undefined ? 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> = {
-    [K in keyof T]: T[K] extends Iterable<unknown> & object ? K : never;
+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) | null | undefined ? 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

@@ -1,6 +1,6 @@
 function buildTree(items, options) {
   if (!options) {
-    throw new Error('Missing required "options" parameter.');
+    throw new Error(`Missing required 'options' parameter.`);
   }
   const {
     id: idAccessor,
@@ -10,18 +10,18 @@ function buildTree(items, options) {
     nodeValueKey = "value",
     nodeParentKey = "parent",
     nodeChildrenKey = "children",
-    withDepth = false,
+    nodeDepthKey = false,
     validateTree = false,
     validateReferences = false
   } = options;
   if (!idAccessor) {
-    throw new Error('Option "id" is required.');
+    throw new Error(`Option 'id' is required.`);
   }
   if (!parentIdAccessor && !childIdsAccessor) {
-    throw new Error('Either "parentId" or "childIds" must be provided.');
+    throw new Error(`Either 'parentId' or 'childIds' must be provided.`);
   }
   if (parentIdAccessor && childIdsAccessor) {
-    throw new Error('"parentId" and "childIds" cannot be used together.');
+    throw new Error(`'parentId' and 'childIds' cannot be used together.`);
   }
   const roots = [];
   const nodes = /* @__PURE__ */ new Map();
@@ -30,9 +30,15 @@ function buildTree(items, options) {
     for (const item of items) {
       const id = typeof idAccessor === "function" ? idAccessor(item) : item[idAccessor];
       if (nodes.has(id)) {
-        throw new Error(`Duplicate identifier "${id}".`);
+        throw new Error(`Duplicate identifier '${id}'.`);
       }
       const node = nodeValueKey !== false ? { [nodeValueKey]: nodeValueMapper ? nodeValueMapper(item) : item } : { ...nodeValueMapper ? nodeValueMapper(item) : item };
+      if (nodeValueKey === false) {
+        if (nodeParentKey !== false) {
+          delete node[nodeParentKey];
+        }
+        delete node[nodeChildrenKey];
+      }
       nodes.set(id, node);
       const parentId = typeof parentIdAccessor === "function" ? parentIdAccessor(item) : item[parentIdAccessor];
       const parentNode = nodes.get(parentId);
@@ -63,7 +69,7 @@ function buildTree(items, options) {
     }
     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.`);
+        throw new Error(`Referential integrity violation: parentId '${parentId}' does not match any item in the input.`);
       }
       for (const node of nodes2) {
         roots.push(node);
@@ -75,14 +81,20 @@ function buildTree(items, options) {
     for (const item of items) {
       const id = typeof idAccessor === "function" ? idAccessor(item) : item[idAccessor];
       if (nodes.has(id)) {
-        throw new Error(`Duplicate identifier "${id}".`);
+        throw new Error(`Duplicate identifier '${id}'.`);
       }
       const node = nodeValueKey !== false ? { [nodeValueKey]: nodeValueMapper ? nodeValueMapper(item) : item } : { ...nodeValueMapper ? nodeValueMapper(item) : item };
+      if (nodeValueKey === false) {
+        if (nodeParentKey !== false) {
+          delete node[nodeParentKey];
+        }
+        delete node[nodeChildrenKey];
+      }
       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.`);
+          throw new Error(`Item '${id}' has invalid children: expected an iterable value.`);
         }
         node[nodeChildrenKey] = [];
         for (const childId of childIds) {
@@ -91,12 +103,15 @@ function buildTree(items, options) {
             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.`);
+                throw new Error(`Node '${childId}' already has a different parent, refusing to overwrite.`);
               }
               childNode[nodeParentKey] = node;
             }
             rootCandidates.delete(childId);
           } else {
+            if (waitingChildren.has(childId)) {
+              throw new Error(`Multiple parents reference the same unresolved child '${childId}'.`);
+            }
             waitingChildren.set(childId, {
               parentNode: node,
               childIndex: node[nodeChildrenKey].length
@@ -114,7 +129,7 @@ function buildTree(items, options) {
         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.`);
+            throw new Error(`Node '${id}' already has a different parent, refusing to overwrite.`);
           }
           node[nodeParentKey] = parentNode;
         }
@@ -126,7 +141,7 @@ function buildTree(items, options) {
     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.`);
+        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--) {
@@ -141,6 +156,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 +172,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.1",
   "description": "Easily construct highly customizable bi-directional tree structures from iterable data.",
   "types": "./index.d.mts",
   "module": "./index.mjs",
@@ -22,7 +22,7 @@
     "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"
+    "coverage": "c8 -r text -r text-summary -r lcov --include \"*.mjs\" npm test"
   },
   "devDependencies": {
     "c8": "^10.1.3",