fast-tree-builder 1.0.0-alpha.2 → 1.0.0-beta.0

package/README.md

@@ -1,35 +1,36 @@
 # fast-tree-builder
 
+[![NPM version](https://img.shields.io/npm/v/fast-tree-builder.svg)](https://npmjs.org/package/fast-tree-builder)
+[![NPM downloads](https://img.shields.io/npm/dm/fast-tree-builder.svg)](https://npmjs.org/package/fast-tree-builder)
 [![Build Status](https://github.com/lionel87/fast-tree-builder/actions/workflows/build.yaml/badge.svg)](https://github.com/lionel87/fast-tree-builder/actions/workflows/build.yaml)
 [![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)
-![npms.io (quality)](https://img.shields.io/npms-io/quality-score/fast-tree-builder?label=quality)
-![Maintenance](https://img.shields.io/maintenance/yes/2024)
+![Maintenance](https://img.shields.io/maintenance/yes/2025)
 
-`fast-tree-builder` is an npm package that allows you to efficiently build trees from iterable data structures. With its optimized algorithm, strong TypeScript typings, and customizable node structure, it provides a reliable solution for organizing and manipulating hierarchical data.
+`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.
 
 ## Prerequisites
 
 - You have a list of items,
-- where each item is identifiable by a unique value,
-- and the items are connected via a *parent* OR a *childred* relation.
+- each item is identifiable by a unique id,
+- the items are connected via a *parent id* OR *children ids*.
 
 ## Features
 
-- **Efficient Tree Building**: The package utilizes an optimized algorithm to construct trees efficiently in `O(n)` time, while maintaining good performance.
+- **Efficient Tree Building**: Using an optimized algorithm to construct trees in `O(n)` time.
 
-- **Bi-Directional Tree Traversal**: Traverse the built tree in both directions, enabling easy navigation between parent and child nodes.
+- **Bi-Directional Tree Traversal**: Pointers for parent and children both created for the nodes.
 
-- **Robust TypeScript Type Definitions**: Leverage type safety through extensive TypeScript type definitions. The package includes precise type annotations to improve code reliability and developer workflow.
+- **Robust TypeScript Type Definitions**: Type safety through extensive TypeScript type definitions which helps code reliability and developer workflow.
 
-- **Fully Customizable Node Structure**: Tailor the structure of the nodes in the built tree 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.
+- **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.
 
-- **Works on Any Iterable Data**: Designed to handle arrays, sets, and other iterable data structures efficiently, ensuring broad applicability.
+- **Works on Iterables**: Designed to handle arrays, sets, and other iterable data structures out of the box ensuring broad applicability.
 
-- **No Sorting Required**: The algorithm does not require your input data to be sorted, saving you preprocessing time and effort.
+- **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.
 
-- **Flexible Key and Parent Key Types**: You can use any JavaScript value for identifying items. Relations checked with strict (`childKey === parentKey`) comparison.
+- **Flexible Key Types**: You can use any JavaScript value for identifying items. Relations checked with strict (`childKey === parentKey`) comparison.
 
-- **Multiple Root Nodes**: Can efficiently construct trees with multiple root nodes, accommodating scenarios that necessitate distinct, separate tree structures within the same dataset.
+- **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.
 
 - **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.
 
@@ -241,16 +242,16 @@ Builds a tree from the given iterable `items` using the specified `options`.
 
 Parameters
 
-- `items`: An iterable data structure containing the items to build the tree from.
+- `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 an item defines its children in a list, and connects that way; `parent` means an item defines its parent, and connects to it that way. 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`.
+  - `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`.
 
@@ -270,9 +271,9 @@ Throws `Error` when:
 
 ## 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 other packages.
+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.
 
-For scenarios where performance is critical, consider implementing a tailored, optimized algorithm. It could be as simple as:
+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:
 ```js
 const roots = [];
 const nodes = new Map();

package/index.d.ts

@@ -1,37 +1,37 @@
-type TreeNode<T, D extends string | number | symbol | false, P extends string | number | symbol | false, C extends string | number | symbol> = (D extends false ? (P extends false ? T & {
-    [k in C]?: TreeNode<T, D, P, C>[];
-} : T & {
-    [k in Exclude<P, false>]?: TreeNode<T, D, P, C>;
+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 C]?: TreeNode<T, D, P, C>[];
-}) : (P extends false ? {
-    [k in Exclude<D, false>]: T;
+    [k in TChildrenKey]?: TreeNode<TInputData, TDataKey, TParentKey, TChildrenKey>[];
+}) : (TParentKey extends false ? {
+    [k in Exclude<TDataKey, false>]: TInputData;
 } & {
-    [k in C]?: TreeNode<T, D, P, C>[];
+    [k in TChildrenKey]?: TreeNode<TInputData, TDataKey, TParentKey, TChildrenKey>[];
 } : {
-    [k in Exclude<D, false>]: T;
+    [k in Exclude<TDataKey, false>]: TInputData;
 } & {
-    [k in Exclude<P, false>]?: TreeNode<T, D, P, C>;
+    [k in Exclude<TParentKey, false>]?: TreeNode<TInputData, TDataKey, TParentKey, TChildrenKey>;
 } & {
-    [k in C]?: TreeNode<T, D, P, C>[];
+    [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<T extends (D extends false ? object : unknown), K extends keyof T | ((item: T) => any), M extends (D extends false ? object : unknown) = T, D extends string | number | symbol | false = 'data', P extends string | number | symbol | false = 'parent', C extends string | number | symbol = 'children'>(items: Iterable<T>, options?: {
+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?: K;
-    parentKey?: keyof T | ((item: T) => KeyReturnType<T, K>);
-    childrenKey?: keyof T | ((item: T) => KeyReturnType<T, K>);
-    nodeDataKey?: D;
-    nodeParentKey?: P;
-    nodeChildrenKey?: C;
+    key?: TKey;
+    parentKey?: keyof TInputData | ((item: TInputData) => any);
+    childrenKey?: keyof TInputData | ((item: TInputData) => any);
+    nodeDataKey?: TNodeDataKey;
+    nodeParentKey?: TNodeParentKey;
+    nodeChildrenKey?: TNodeChildrenKey;
     mapNodeData?: {
-        (item: T): M;
+        (item: TInputData): TMappedData;
     };
     validRootKeys?: Iterable<unknown>;
     validRootParentKeys?: Iterable<unknown>;
     validateTree?: boolean;
 }): {
-    roots: TreeNode<M extends undefined ? T : M, D, P, C>[];
-    nodes: Map<KeyReturnType<T, K>, TreeNode<M extends undefined ? T : M, D, P, C>>;
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fast-tree-builder",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-beta.0",
   "description": "Efficiently construct highly customizable bi-directional tree structures from iterable data.",
   "type": "module",
   "module": "./index.js",
@@ -23,9 +23,9 @@
     "coverage": "c8 -r text -r text-summary -r lcov --include \"*.js\" npm test"
   },
   "devDependencies": {
-    "c8": "^9.1.0",
-    "chokidar": "^3.5.3",
-    "mocha": "^10.2.0",
+    "c8": "^10.1.3",
+    "chokidar": "^4.0.3",
+    "mocha": "^11.1.0",
     "typescript": "^5.3.3"
   },
   "homepage": "https://github.com/lionel87/fast-tree-builder#readme",